Skip to content

Instantly share code, notes, and snippets.

@chrisjacob
Created February 14, 2011 14:31
Show Gist options
  • Save chrisjacob/825950 to your computer and use it in GitHub Desktop.
Save chrisjacob/825950 to your computer and use it in GitHub Desktop.
Setup GitHub Pages "gh-pages" branch as a subfolder within the "master" project on your local checkout - a step-by-step guide.

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 git@github.com: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 git@github.com: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".

@rubik
Copy link

rubik commented Jun 15, 2011

Thanks for the guide! Really clear and useful.

@jay
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
/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

@chrisjacob
Copy link
Author

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

@Kline-
Copy link

Kline- commented Apr 15, 2012

Found this on Google, thanks for the writeup!

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

@rudylattae
Copy link

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

@rattrayalex
Copy link

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

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

@sztupy
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

@rahuldave
Copy link

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

@dandv
Copy link

dandv commented Jun 4, 2015

@dandv
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 :)

@GraniteConsultingReviews

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

@volodalexey
Copy link

Awesome! Thanks!

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