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

[2012-01-10] dev, git

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.