Question

Developing on github, I often maintain a html/ or _site/ subdirectory in my master branch where I generate web-based documentation for the project. I’d like to switch to my gh-pages branch and pull just the contents of this html directory into the root of the gh-pages branch, so it will render as a nice website through github (which automatically renders html in gh-pages at username.github.com/repositoryname). What is the best workflow to do this?

If I don’t yet have the gh-pages branch set up, I can branch, clear the branch, and copy in the contents of the html directory and presto, I have the a site ready to go. But I’m not sure how best to later update the gh-pages branch.

git branch gh-pages
git checkout gh-pages
# Remove files I don't need from the gh-pages branch
rm -rf data/ man/ R/ README.md NEWS NAMESPACE DESCRIPTION demo/
# move documentation to the root
mv inst/doc/html/* .
# remove the rest
rm -rf inst/
git add *
git commit -a -m "gh-pages documentation"
git push origin gh-pages
git checkout master

Now what should I do to update the gh-pages branch later? It sounds like this might involve subtree merging but I’m not quite sure.

Answer 1

To start your gh-pages branch:

true | git mktree | xargs git commit-tree | xargs git branch gh-pages

To fetch anything you want into it, say the html directory from the master branch, read-tree and commit:

git checkout gh-pages
git read-tree master:html
git commit -m'gh-pages documentation'
git push origin gh-pages
git checkout master

and you’re done.

Late addition: there’s a shorter sequence for adding to the gh-pages branch:

git commit-tree -p gh-pages -m "" master:html \
| xargs git update-ref refs/heads/gh-pages

which doesn’t require flushing the current working tree