John Goodall

Research Scientist / Team Lead

Situation Awareness and Visual Analytics team

Oak Ridge National Laboratory



Keep gh-pages in sync with master

I wanted to add the source for a web site to the master branch of a project, build static html from that, and keep those changes in sync with the gh-pages branch to automatically deploy to github pages on each commit.

Here are the steps to set this up. This assumes you dont have a gh-pages branch already (if you do, delete it). I was using the deploy directory in master branch as the source for the gh-pages branch, so modify that directory as needed. Here are the steps (you should be in the root of your project when you start this sequence):

    git checkout -b gh-pages
    ls | grep -v deploy | xargs rm -rf
    git mv deploy/* .
    rmdir deploy
    git add .
    git ls-files --deleted | while read FILE; do git rm "$FILE"; done
    git commit -a -m "Initial commit in pages branch"
    git push origin master gh-pages
    git checkout master

Update: you may have to do git mv -k deploy/* . if you have empty directories in your deploy directory

First, this creates and checks out the new gh-pages branch. Then remove all of the directories and files except the directory containing the web site (i.e. deploy). Move those files into the root directory and commit. Push the changes and go back to master.

Now, when you edit the files in master, you can merge them into the gh-pages branch by doing this (you should be in the root of your project when you start this sequence):

    git checkout gh-pages
    git merge -s subtree master
    git push origin master gh-pages

This will checkout the gh-pages branch, merge using the subtree strategy, then push both back to the origin remote repository.

Git hooks

Since we dont want to do all that every time, we can automate the process using git hooks in the master branch, so that the workflow is:

  1. edit a file in master
  2. add and commit the changes
  3. git push --all

A simple git pre-commit hook that uses grunt builds the static web site:

    git add deploy

The git post-commit hook will merge the changes with the gh-pages branch for deployment on github pages:

    git checkout gh-pages
    git merge -s subtree master
    git checkout master

To use the hooks, create them in your project root and then create the symlinks:

    ln -s ../../ .git/hooks/pre-commit
    ln -s ../../ .git/hooks/post-commit

Now, every time you do a git push --all in the master branch, the hooks will first build the static site and add the deploy directory to the commit, then will merge the changes to the gh-pages branch.