Skip to content

Instantly share code, notes, and snippets.

@chrisjacob
Created February 18, 2011 03:44
Star You must be signed in to star a gist
Save chrisjacob/833223 to your computer and use it in GitHub Desktop.
Setup GitHub Pages "gh-pages" branch and "master" branch as subfolders of a parent project folder ("grandmaster").

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 ^_^

@theskillwithin
Copy link

git push --force origin $(git commit-tree -m "auto" master:dist):gh-pages
tree="$(cp .git/index{,-bk} && git add -f dist && git write-tree --prefix=dist && mv .git/index{-bk,})"

git push -f origin "$(git commit-tree -m auto "$tree")":gh-pages
tree="$(export GIT_INDEX_FILE="$(mktemp)"; cat .git/index >"$GIT_INDEX_FILE"; git add -f dist && git write-tree --prefix=dist)"
    after that, imo you should do something like 
    git update-ref refs/heads/gh-pages "$(git commit-tree -p gh-pages -m auto "$tree")"

still trying to figure it out with a build folder that is in gitignore but would be root level on gh-pages deploy

@ooade
Copy link

ooade commented Mar 11, 2017

I think you can cut some few steps off. If you don't clone the repo, you won't have the master branch hanging around the gh-pages. Nice tho 👍

@dreyks
Copy link

dreyks commented Apr 27, 2017

also you can use git worktree
for an existing project inside your workdir

$ git worktree add ../gh-pages gh-pages

@AndrejGajdos
Copy link

@hendrawd I got the same error message. How did you solve it?

@glfmn
Copy link

glfmn commented Jan 26, 2018

You could easily use a hook to synchronize pushing, if anyone is still wondering how to approach that

@equero
Copy link

equero commented Feb 2, 2018

This example is dead

@interglobalmedia
Copy link

interglobalmedia commented May 8, 2018

It sure is dead. It should be removed.

@Convincible
Copy link

Why is it dead?

@ranolfi
Copy link

ranolfi commented Dec 2, 2019

A post-commit hook is a much clearer approach. Refer to https://githooks.com/.

@Vadorequest
Copy link

Example is dead because Github made things much easier I believe. Example if from 2013...

@AlexByte
Copy link

Once the branch is pushed to GitHub, you have to go to the Settings page of the repository. In the section “GitHub Pages”, select gh-pages as the source. The step is described in more details here. If successful, you will see a message saying “Your site is published at https://your-username.github.io/your-repository/”.

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