A workflow for using GitHub project pages to host a static site.

workflow.md

First Time

The gh-pages branch does not exist on the remote.

# Set up the build directory on an orphan branch
$ mkdir build && cd build
$ git init
$ git checkout --orphan gh-pages

# Seed the repository
$ echo 'Hello, world!' > index.html
$ git add .
$ git commit -m "Initial commit"

# Publish the branch
$ REMOTE_URL=`cd .. && git config --get remote.origin.url`
$ git remote add origin $REMOTE_URL
$ git push origin gh-pages

Other Times

The gh-pages branch is already on the remote.

# Checkout the branch
$ mkdir build && cd build
$ git init
$ REMOTE_URL=`cd .. && git config --get remote.origin.url`
$ git remote add origin $REMOTE_URL
$ git fetch origin
$ git checkout gh-pages

# Do some work
$ git add --all
$ git commit -m "..."

# Push the changes
$ git push origin gh-pages

References

• https://github.com/neo/middleman-gh-pages/blob/master/lib/middleman-gh-pages/tasks/gh-pages.rake
• https://help.github.com/articles/creating-project-pages-manually/

The command git rev-parse --show-toplevel always returns the absolute path to the .git directory even if you are several directories deep in a git repository.

Remote references are stored in .git/refs/remotes.

You can get the URL of a given remote using git config --get remote.<remote_name>.url, where <remote_name> could be origin for example.

List the remote branches using git branch -r.

Show the abbreviated commit hash of the most recent commit using git log --pretty="%h" -n1.