public
Last active

Setup GitHub Pages "gh-pages" branch and "master" branch as subfolders of a parent project folder ("grandmaster").

  • Download Gist
README.md
Markdown

Intro

Description: Setup GitHub Pages "gh-pages" branch and "master" branch as subfolders of a parent project folder ("grandmaster").

Author: Chris Jacob @_chrisjacob

Tutorial (Gist): https://gist.github.com/833223

The Result

The final folder structure on my local system is:

/grandmaster
/grandmaster/master
/grandmaster/master/.git # checkout of "master" branch
/grandmaster/master/README.markdown
/grandmaster/gh-pages
/grandmaster/gh-pages/.git # checkout of "gh-pages" branch (removed "master" branch)
/grandmaster/gh-pages/index.html
/grandmaster/gh-pages/README.textile

See "master" branch: https://github.com/chrisjacob/grandmaster

See "gh-pages" branch: https://github.com/chrisjacob/grandmaster/tree/gh-pages

See GitHub Page (auto generated): http://chrisjacob.github.com/grandmaster/

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 "grandmaster".
https://github.com/repositories/new

Don't follow GitHub's Next steps instructions! Follow the steps below to setup your projects folders on your local system.

Open Terminal.app, create project parent folder "grandmaster", and a subfolder for the "master" branch. Initialise a new git repository for the project and push the "master" branch to GitHub.

ichris:Sites $ mkdir grandmaster
ichris:Sites $ cd grandmaster/
ichris:grandmaster $ mkdir master
ichris:grandmaster $ cd master/
ichris:master $ git init
ichris:master $ echo "# Master README file" > README.markdown
ichris:master $ git add .
ichris:master $ git commit -m "Master README added"
ichris:master $ git remote add origin git@github.com:chrisjacob/grandmaster.git
ichris:master $ git push origin master

Refresh your projects "master" branch page on GitHub to see the committed files.
https://github.com/chrisjacob/grandmaster

Auto generate a GitHub Pages branch, with some default content.
https://github.com/chrisjacob/grandmaster/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/grandmaster/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/grandmaster/

Back in Terminal.app, change directory back to the parent folder, setup a "gh-pages" subfolder for your "gh-pages" branch and change directory into it.

ichris:master $ cd ../
ichris:grandmaster $ mkdir gh-pages
ichris:grandmaster $ cd gh-pages/

Clone your "grandmaster" repository into the "gh-pages" folder (this will clone in the "master" branch), 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" branch is listed.

ichris:gh-pages $ git clone git@github.com:chrisjacob/grandmaster.git .
ichris:gh-pages $ git checkout origin/gh-pages -b gh-pages
ichris:gh-pages $ ls -la
ichris:gh-pages $ git branch -d master
ichris:gh-pages $ 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

ichris:gh-pages $ echo "h1. GitHub Pages README file" > README.textile
ichris:gh-pages $ git add .
ichris:gh-pages $ git commit -m "Child README added"

Now push to the "gh-pages" branch

ichris:gh-pages $ git push origin gh-pages

Visit your projects "gh-pages" branch page on GitHub to see the committed files.
https://github.com/chrisjacob/grandmaster/tree/gh-pages

If everything has gone well you now have a parent project folder named "grandmaster", with subfolders for its two branches "master" and "gh-pages"; each containing a checkout of their respective branch.

For me this system keeps things nice and tidy without needing to do git checkout gh-pages each time I want to view my "gh-pages" branch.

Might also be a useful structure for output from static site generators like Jekyll, Webby, or nanoc.

Enjoy ^_^

Thank you. Thank you! THANK YOU! I've been cursing gh-pages for over a year and had to fuss with things like grancher, it's failure on 1.9, then writing my own task to copy the files, which had it's own edge cases. Now I am free!!!

FYI. I did one thing different, I just made the gh-pages directory a subdirectory of my main project and added it to .gitignore.

You're most welcome. Thank you for the feedback. I also played the 1.9 dance with Grancher ;-)

RE: gh-pages as a subfolder for master, I tried that too, but found the setup fails when switching between branches, see the note I made here: https://gist.github.com/825950

Hmm... how do you loose it? I just tired it and it is still there. Anything in .gitignore just hangs about no mater what branch you are in.

Ahhh k. I never tried with the gh-pages folder in .gitignore - I will have to give it a go, but as you say, sounds like it works fine. Thx for the tip ^_^

Nothing doing. I can't even describe how tickled pink I am that you set me down the "right path" on this.

Also, it just occurred to me that one could also do:

$ cd myapp
$ git clone --local . gh-pages

But I'm not yet sure how that plays out when pushing gh-pages to the remote.

Ok. I tried out local clone and I think it's not a good way b/c it means pushing twice. Once from gh-pages to local and again from master to remote gh-pages.

Hello, thanks for sharing this.
Someone know how to keep some files in gh-pages sync with the master branch (like in this article http://nicolasgallagher.com/git-checkout-specific-files-from-another-branch/) with this directory architecture?
Seems not possible because master branch is cloned then deleted in gh-pages folder, and checkout can't point to a specific external folder (at least I dunno how to do)...

I just use a rake task, or such device, to keep files in sync between the two when need be.

@adriengibrat

If you've already followed this gist then:

  1. cd /grandmaster/gh-pages/
  2. git checkout origin/master -b master
  3. git checkout gh-pages
  4. git checkout master -- README.markdown

You should now have "README.markdown" and "README.textile" in the gh-pages folder.

... Also you don't need to delete the master branch inside the gh-pages folder. So if you need to pull in files from "master" like Nicolas's post outline then certainly keep "master" around - p.s. Thanks for the link to this by the way - great tip! ;-)

hello everyone, when we deploy pages on github branch, we can access those pages using
http://xxx.github.com/pages/username/repository_name
But I dont want the username to appear in the link, instead I want it to be any other name, is that possible?

Hi
I followed theses instructions and it worked fine. Thank you, I managed to put my Doxygen files in my gh-pages.

Hi, I know this is old, but I'm trying to do something similar, with this twist: I want my gh-pages branch to be the same as a sub-directory of my master branch. So in my master, I have:

node-server.js // a very simple node server for local development
source/
      // psd files, wireframes, etc.
site/
    index.html, etc. // the real project -- a static site that I also want to serve from gh-pages

I've successfully created a gh-branch, and manually copied the stuff from site/ to it, but do you have any advice on how to easily keep them in sync? Can I do something like:

grandmaster$ ln-s master/site gh-pages

@sprugman I'd like to have a similar setup :+1:

@chrisjacob, you're awesome!

Hey, very nice tutorial.

Since i'm new to GitHub, I was using their tutorial https://help.github.com/articles/fork-a-repo to create a fork. However, I prefer your approach since I like to keep things organised. But I'm not sure if I got it right. At Github article they show us how to keep your fork updated with the original one, doing this:

cd Spoon-Knife
# Changes the active directory in the prompt to the newly cloned "Spoon-Knife" directory
git remote add upstream https://github.com/octocat/Spoon-Knife.git
# Assigns the original repository to a remote called "upstream"
git fetch upstream
# Pulls in changes not present in your local repository, without modifying your files

But that is only for the 'master' branch, right? Using your approach, how can I have both master and gh-pages in sync with the original repo?

Thanks.

So basically all you're doing is creating two separate working copies on different branches? In no way are the working copies linked, aside from having the same remote?

I stumbled on this and at first had no idea why you would want to do this, then you mentioned it being useful for output from static site generators. With this I can probably use a single repo instead of two repos (one for the documentation's source which uses Sphinx, the other for gh-pages). Thanks!

BTW, the webpage 404s: http://chrisjacob.github.com/grandmaster/

Has anyone tried to replicate this with git submodules?

I have written a small script that assists in synchronizing a subdirectory with the gh-pages branch. It's in my scriptlets repo. Use ghpsd init for creating an empty gh-pages subdirectory that will hold the contents of your gh-pages branch. After adding to this subdirectory, use ghpsd merge for updating the gh-pages branch. Note that you still have to push to GitHub.

It works by cloning a copy of the repo into a shadow subdirectory named .gh-pages (which is added to .gitignore, too); this makes updating the gh-pages branch work seamless. Call ghpsd checkout to recreate the hidden .gh-pages folder, this clones locally and does not require network access.

Please sign in to comment on this gist.

Something went wrong with that request. Please try again.