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