Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/shiftyp/submodule-gh-pages-example
An example of using a self referencing submodule for gh-pages: http://shiftyp.github.io/submodule-gh-pages-example
https://github.com/shiftyp/submodule-gh-pages-example
Last synced: 11 days ago
JSON representation
An example of using a self referencing submodule for gh-pages: http://shiftyp.github.io/submodule-gh-pages-example
- Host: GitHub
- URL: https://github.com/shiftyp/submodule-gh-pages-example
- Owner: shiftyp
- Created: 2016-01-06T00:38:12.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2016-04-21T04:07:41.000Z (almost 9 years ago)
- Last Synced: 2025-01-10T20:56:45.747Z (15 days ago)
- Language: HTML
- Homepage:
- Size: 15.6 KB
- Stars: 38
- Watchers: 3
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-luooooob - shiftyp/submodule-gh-pages-example - An example of using a self referencing submodule for gh-pages: http://shiftyp.github.io/submodule-gh-pages-example (HTML)
README
# Setting up your gh-pages as a submodule
When setting up a GitHub page only repo where you have some source files and a build step, it isn't exactly clear how you should go about creating the repository without mixing your source and built files, and without having to navigate to a build directory on your github page.
There is a way to do it, and it involves using submodules. If you look at this repo on GitHub you'll see that the `build` directory looks a little funny and has a commit hash next to it. That's because it's a submodule; a git repo within a git repo. If you look at what's in there, and look at the gh-pages branch, you'll see that they are exactly the same.
What we have here is a repository, inside the repository, that is also the repository...inception type stuff I know but it doesn't require superpowers to set this up for yourself. The advantage is your gh-pages branch will be just your built files, your master branch will have your source, and you'll still have your same build directory to build and test in. So let's see how to set this up:
## The Setup
If you are just starting your project and have a fresh repository, the steps are surprisingly simple:
```
git checkout --orphan gh-pages
git commit -m "initial gh-pages commit"
git push origin gh-pages
git checkout master
git submodule add build
cd build
git checkout gh-pages
cd ../
git commit -am "Set up gh-pages as a submodule"
```
Annd you're done, and you can skip to the workflow section. If you already have a some work done then follow these steps:
Reclone your repository into a new directory, so for this one I'd do this from the directory above my current project:
```shell
git clone [email protected]:shiftyp/submodules-gh-pages-example.git some-other-directory
cd some-other-directory
```
Checkout an orphan gh-pages branch. If you already have a gh-pages branch, delete that first (be sure that your master branch is up to date before you do this). To do all of this, you'd do:
```shell
git checkout master
git merge gh-pages
# This deletes it locally
git branch -D gh-pages
# This deletes it on github
git push origin :gh-pages
# Then checkout a new orphan branch (meaning master isn't a parent)
git checkout --orphan gh-pages
```
Clear out the files in this new directory (except the .git dir), then copy what's currently in your build directory into this new repository.
```shell
mv .git ../git-backup-tmp
rm -r ./*
mv ../git-backup-tmp ./.git
cp -r ../submodules-gh-pages-example/build/* ./
```
Now commit and push
```shell
git commit -am "Redoing gh-pages as a submodule, initial commit"
git push origin gh-pages
```
You can now remove the current directory. Then cd into your old repo and remove the build directory.
```shell
cd ../
rm -rf some-other-directory
cd submodule-gh-pages-example
rm -rf build
```
Add your repository...to your repository...as a submodule. Whoa!
```shell
git submodule add [email protected]:shiftyp/submodule-gh-pages-example.git build
```
cd into your build directory and checkout gh-pages
```
cd build
git checkout gh-pages
```
## The Workflow
Annnd you're done! Now build as usual, and when you want to push to gh-pages, cd into build and do a commit and push to `origin gh-pages`. If you end up wanting to check out your repository somewhere else do:
```
git clone [email protected]:shiftyp/submodule-gh-pages-example.git
cd submodule-gh-pages-example
git submodule init && git submodule update
cd build
git checkout gh-pages
```
## Still with me?
Pretty cool! Now your master and gh-pages are easily linked, yet completely separate. I haven't seen many people do this, but I wouldn't do it any other way.