Setup GitHub Pages "gh-pages" branch as a subfolder within the "master" project on your local checkout.
If you plan on switching between different branches (e.g. git checkout master-experiment
then revert back with git checkout master) you will loose your child folder from this tutorial (because it's in your
.gitignore and is not part of your master branch).
For this reason I prefer to: Setup GitHub Pages "gh-pages" branch and "master" branch as subfolders of a parent project folder ("grandmaster")
See "master" branch: https://github.com/chrisjacob/parent
See "gh-pages" branch: https://github.com/chrisjacob/parent/tree/gh-pages
The final folder structure on my local system is:
/parent
/parent/.git # checkout of "master" branch
/parent/.gitignore # ignores child/ folder
/parent/README.markdown
/parent/child
/parent/child/.git # checkout of "gh-pages" branch (+ removed "master" branch)
/parent/child/index.html
/parent/child/README.textile
A note for GitHub novices - replace "chrisjacob" with your own GitHub username.
A note for Terminal novices - you don't need to enter the "ichris:Sites $ " parts of the code listed below. ^_^
Visit GitHub and create a new repository with the project name "parent" https://github.com/repositories/new
Open Terminal.app, initialise a new git repository for the project and push the "master" branch to GitHub.
ichris:~ $ cd Sites/
ichris:Sites $ mkdir parent
ichris:Sites $ cd parent/
ichris:parent $ git init
ichris:parent $ echo "# Parent README file" > README.markdown
ichris:parent $ git add .
ichris:parent $ git commit -m "Parent README added"
ichris:parent $ git remote add origin [email protected]:chrisjacob/parent.git
ichris:parent $ git push origin master
Refresh your projects "master" branch page on GitHub to see the committed files https://github.com/chrisjacob/parent
Auto generate a GitHub Pages branch, with some default content https://github.com/chrisjacob/parent/pages/create
Or follow these steps to get to the generator page:
Go to the projects Admin page on GitHub https://github.com/chrisjacob/parent/admin
Check the "GitHub Pages" checkbox
A popup will ask you to "Activate GitHub Pages" - click the big "Automatic GitHub Page Generator" button
Check that your GitHub Pages page has been built and is available http://chrisjacob.github.com/parent/
Back in Terminal.app, setup a "child" folder for your "gh-pages" branch and make sure the "master" branch ignore's this folder. Commit this to "master".
ichris:parent $ mkdir child
ichris:parent $ echo "child/" > .gitignore
ichris:parent $ git add .
ichris:parent $ git commit -m ".gitignore child/ folder (contains gh-pages branch)"
ichris:parent $ git push origin master
Change into the "child" folder, clone your repo, checkout the "gh-pages" branch, list the files (should have "index.html" and ".git") and then remove the "master" branch to avoid any confusion. Last step is to check that "master" branch was removed and only "gh-pages" is listed.
ichris:child $ cd child/
ichris:child $ git clone [email protected]:chrisjacob/parent.git .
ichris:child $ git checkout origin/gh-pages -b gh-pages
ichris:child $ ls -la
ichris:child $ git branch -d master
ichris:child $ git branch
You will probably get a warning when deleting the "master" branch... don't worry about it ^_^
Lets add a "README.textile" file to the gh-pages branch - notice parents/ README has the extension .markdown; I've chosen .textile here to demonstrate that these two repositories don't "see" each others files.
ichris:child $ echo "h1. Child README file" > README.textile
ichris:child $ git add .
ichris:child $ git commit -m "Child README added"
Now push to the "gh-pages" branch
ichris:child $ git push origin gh-pages
Visit your projects "gh-pages" branch page on GitHub to see the committed files https://github.com/chrisjacob/parent/tree/gh-pages
Change directory back to the parent/ folder, make sure it doesn't have the "gh-pages" branch, make sure it has ignored the child/ folder and all it's content.
ichris:child $ cd ../
ichris:parent $ git branch
ichris:parent $ git status
If everything has gone well you can now work in parent/ and commit to "master". You can also cd into child/, make changes and commit to "gh-pages".