Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Setup GitHub Pages "gh-pages" branch as a subfolder within the "master" project on your local checkout - a step-by-step guide.


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

The Result

See "master" branch:

See "gh-pages" branch:

The final folder structure on my local system is:

/parent/.git # checkout of "master" branch
/parent/.gitignore # ignores child/ folder
/parent/child/.git # checkout of "gh-pages" branch (+ removed "master" branch)

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"

Open, 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
ichris:parent $ git push origin master

Refresh your projects "master" branch page on GitHub to see the committed files

Auto generate a GitHub Pages branch, with some default content

Or follow these steps to get to the generator page:

  1. Go to the projects Admin page on GitHub

  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

Back in, 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 .
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

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

Copy link

rubik commented Jun 15, 2011

Thanks for the guide! Really clear and useful.

Copy link

jay commented Dec 9, 2011

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

$ dir -d gh-pages

$ git checkout master
Switched to branch 'master'

$ dir -d gh-pages

$ git checkout develop
Switched to branch 'develop'

$ dir -d gh-pages

$ grep gh-pages .gitignore

$ git branch
* develop

$ cd gh-pages && pwd

$ 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

Copy link

chrisjacob commented Dec 12, 2011

@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).

Copy link

Kline- commented Apr 15, 2012

Found this on Google, thanks for the writeup!

Copy link

gfahl commented May 25, 2012

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

Copy link

rudylattae commented Dec 23, 2013

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

Copy link

rattrayalex commented Apr 30, 2014

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

Copy link

sztupy commented Jun 6, 2014

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

Copy link

rahuldave commented Oct 16, 2014

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

Copy link

dandv commented Jun 4, 2015

Copy link

dandv commented Jun 4, 2015

Copy link

ghost commented Aug 26, 2017

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment