Use subtree to merge commits from a project subdir (i.e., 'docs/') to gh-pages branch.

creating-project-pages-using-git-subtree.md

Creatings Project Pages using git-subtree

Many projects maintain their documentation within a subfolder of their repository (for example docs/). That way, as new features are added or existing features are modified, the documentation can be updated in the same commit. The git-subtree command can be an effective tool to merge those changes from the documentation subdirectory of your project to the root of the gh-pages branch.

Setup

According to the author of git-subtree, the command is included with git 1.7.11 and higher. However, it's in the "contrib" subtree for now, so it's not installed by default. Search for "git-subtree" in your system's package manager and install the package if it exists. If not, or if you are using an older version of git, the easiest way is to install git-subtree from the author's repo.

$ git clone https://github.com/apenwarr/git-subtree.git

$ cd git-subtree/

$ make install

Using git-subtree

Now that git-subtree is installed, lets look at the layout of our repo:

$ cd repo

$ git branch
* master

$ ls
README.md  docs  src

$ ls docs/
index.html

In the master branch of this repo we have a subdirectory docs/ which contains the file index.html. As we want the root of our gh-pages branch to match the docs subdirectory, use the following command:

$ git subtree split --branch gh-pages --prefix docs/
Created branch 'gh-pages'
ab8eb66a6770438b45505390a30232f9d50919a0

A quick inspection reveals that this worked:

$ git branch
  gh-pages
* master

$ git checkout gh-pages
Switched to branch 'gh-pages'

$ ls
index.html

Try viewing the logs and you will see that only the commits which effected the docs/ subdirectory are included. Additionaly, any commits which included changes in both the docs/ subdirectory and other parts of your source only include the changes to the docs/ subdirectory in the gh-pages branch.

Of course, you'll want to push your new gh-pages branch to Github:

$ git push origin gh-pages

Any time you want to update your gh-pages branch, simply commit all your changes to the master branch and then rerun the commands:

$ git subtree split --branch gh-pages --prefix docs/
Updated branch 'gh-pages'
d482d07108f23728cea4fe17699d0437648c433a
$ git push origin gh-pages