Setup GitHub Pages "gh-pages" branch as a subfolder within the "master" project on your local checkout - a step-by-step guide.

README.md

Intro

Setup GitHub Pages "gh-pages" branch as a subfolder within the "master" project on your local checkout.

IMPORTANT

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")

The Result

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

The Process

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:

1. Go to the projects Admin page on GitHub https://github.com/chrisjacob/parent/admin

2. Check the "GitHub Pages" checkbox

3. 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".

Thanks for the guide! Really clear and useful.

Very helpful, thanks. I used this guide to move my gh-pages branch to its own subfolder, gh-pages. Your warning at the top there though, I don't get it. gh-pages subdir is ignored and untracked by the parent git dir so what's the problem? The directory should not disappear. Are there circumstances when it would?

$ pwd
/x/j/hooks/gethooks

$ dir -d gh-pages
gh-pages

$ git checkout master
Switched to branch 'master'

$ dir -d gh-pages
gh-pages

$ git checkout develop
Switched to branch 'develop'

$ dir -d gh-pages
gh-pages

$ grep gh-pages .gitignore
/gh-pages/
/gh-pages/*

$ git branch
* develop
  master

$ cd gh-pages && pwd
/x/j/hooks/gethooks/gh-pages

$ git branch
* gh-pages

master and develop and any other branches use the same .gitignore (it's untracked) and so gh-pages is always ignored when I checkout master, develop, etc

@jay thank you for raising this. When I tried changing branches I found that the "child" folder disappeared - and I would need to go through the process of creating the "child" folder again and doing a fresh 'gh-pages' checkout into that folder. Sounds like I will need to re-test this (I'm still a bit of a GIT noob).

Found this on Google, thanks for the writeup!

Excellent guide, thank you! Like jay, I've had no problems with this setup so the warning at the top seems unwarranted.

Thx, shows I'm not (too?)crazy since I'm not the only one using this setup.

Here's a quick/simple python script I wrote to automate my deploys with this technique:

https://gist.github.com/rattrayalex/fbd1c287c2c13c028b44

I think this could be improved using git submodules, so git will properly know that the directory also contains a git repo

This does not remove the gh-pages branch from the parent, right? it git branch in the parent folder ought to return both master and gh-pages, but you should be sitting in the master branch. I'd think you would be comitting harakiri otherwise, but the text you have above:

Change directory back to the parent/ folder, make sure it doesn't have the "gh-pages" branch,

indicates an additional branch delete in the main folder, which is not what i think you meant...

Is this a far easier way to push a subtree gh-pages ?

Yep, just one command to push your gh-pages directory to the gh-pages branch.

so nice, I wish I knew this before I tinkled my site with submodule :)

I have problems in folders but now your guide solve my problem

Awesome! Thanks!