Use subtree to merge commits from a project subdir (i.e., 'docs/') to gh-pages branch.
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.
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
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