It's For The Orphans!

Too often, I come across GitHub Pages branches (gh-pages) branches that are simply forks from the master branch of the repository. This is not ideal.

Commit History showing Merge master into gh-pages on GitHub

There are several problems with this strategy:

  • Unless you manually update the gh-pages branch every time you add a commit to master, you will be out of date.
  • It makes for a much more difficult to understand source folder for the Jekyll or HTML site, since people have to mentally categorize every file and folder into either part of the site or an artifact from the master branch.
  • It introduces the need to have lines like this in _config.yml to prevent unrelated files from being included in the gh-pages site:

exclude: ./app, ./lib, ./project.gemspec, ./Gemfile, ./LICENSE, ./Rakefile, ./readme.md, ./features, ./spec

Little Orphan Annie

git checkout --orphan gh-pages

When it comes time to create a GitHub Page for your project, use the above command. This creates a branch that is completely separate from the history of the rest of the repository. You will need to delete the files by running git rm -rf .:

If you want to start a disconnected history that records a set of paths that
is totally different from the one of <start_point>, then you should clear
the index and the working tree right after creating the orphan branch by
running "git rm -rf ." from the top level of the working tree. Afterwards
you will be ready to prepare your new files, repopulating the working tree,
by copying them from elsewhere, extracting a tarball, etc.

git checkout --help

After you have an empty branch, you’re ready to get started on your Jekyll or HTML site with a clean history and a clear conscience.

Goal-Oriented Git book cover

Goal-Oriented Git is our practical, no-nonsense guide to using Git to achieve your goals in everyday situations. If you've ever wanted to improve your Git skills without getting distracted by complex internals, then this book is for you.