GitHub: serve files to the web, with a single branch

GitHub has a nifty feature called GitHub Pages that allows you to serve files in your repository to the web. Those files have to reside in the branch gh-pages, which is different from the usual master branch. To avoid the slightly cumbersome maintenance of two branches, this post shows you how to only work with gh-pages.

Steps:

• Create a new repository called my_repo on GitHub.
• Create the repository locally:

      $ mkdir my_repo
      $ cd my_repo/
      $ git init
  

• Create the gh-pages branch. Given that a branch is mainly a reference to a commit, you first must create a commit. The option --allow-empty allows you to do so without adding any files.

      $ git commit --allow-empty -m "Initial commit"
      $ git branch gh-pages
  

• Switch to the gh-pages branch.

      $ git checkout gh-pages
  

• Add files, commit changes as usual.
• Push everything to GitHub.

      $ git remote add origin git@github.com:joe/my_repo.git
      $ git push -u origin gh-pages
  

  If you now go to GitHub, you see that the repository only has a single branch (popup menu “Current branch”).
• The files in your repository are now online at

      http://joe.github.io/my_repo/
  

• Whenever you clone your repository, you are automatically in the gh-pages branch:

      $ git clone git@github.com:joe/my_repo.git
      Cloning into my_repo...
      $ cd my_repo/
      $ git branch
      * gh-pages
  

Caveat: I’m not a git expert, but all the solutions for managing the gh-pages branch that I found on the web were too complicated for my taste. The above approach has worked well for me, so far.

---