It’s for the Orphans!

This post originally published on thoughtbot's Giant Robots blog.

I often 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, ./, ./features, ./spec

Please sir may I have some more

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.