I’ve written some HTML documentation for jslint4java. It lives in jslint4java-docs/src/main/resources in typical maven fashion. I’d like to get it published on github pages.
The starting point is similar to their documentation.
git symbolic-ref HEAD refs/heads/gh-pages rm .git/index git clean -fdx echo "My GitHub Page" > index.html git add . git commit -a -m "First pages commit" git push origin gh-pages
That lands us with a brand spanking new branch to play with. What I’d like to do is make a new commit on that branch, but from a tree which is already in my repository. The magic word is git commit-tree. It needs two things: the id of the tree and the id of the parent commit to attach to.
The parent to attach to is easy. It’s the tip of the gh-pages branch we just made. git show-ref will let us know the id.
$ git show-ref -s refs/heads/gh-pages 0a0c2a4ef1f9421b6f9537472c0f04fd6485d2cc
The next bit is the tree we want to commit. git ls-tree is the tool for the job.
$ git ls-tree -d HEAD jslint4java-docs/src/main/resources 040000 tree 5feb5926c39b5e6af3a51feb04750c819bf08b94 jslint4java-docs/src/main/resources
git commit-tree will return the id of the new commit it just created. All that remains is to update the gh-pages branch to point at it.
Pulling it all together, we have:
#!/bin/bash
parent_sha=$(git show-ref -s refs/heads/gh-pages)
doc_sha=$(git ls-tree -d HEAD jslint4java-docs/src/main/resources | awk '{print $3}')
new_commit=$(echo "Auto-update docs." | git commit-tree $doc_sha -p $parent_sha)
git update-ref refs/heads/gh-pages $new_commit
This isn’t ideal — it won’t automatically track updates to that directory. But it’s easy enough to run this once in a while to publish an update.
The end result is that my documentation is published.
Jabbering Giraffe 
6 replies on “Publishing a subdirectory to github pages”
And of course I’ve just realised that I don’t need $parent_sha at all. Specify refs/heads/gh-pages as the parent works just fine.
Oh yea, that’s so obvious! 😉
Really, I wonder about programmers some time.
In any case, `echo “Auto-update docs.”` doesn’t seem to do anything.
Never mind… it provides the changelog.
But doesn’t the gh-pages branch still need to be pushed?
Yes, you will need to push the gh-pages branch. I’m not keen on auto-pushing (I often work on the train), so I didn’t do so above.
As for me its not working out of box, instead of:
new_commit=$(git commit-tree $doc_sha -p $parent_sha)
I must write
git log –pretty=format:’%s’ -n 1 $doc_dir > tmp_message
new_commit=$(git commit-tree $doc_sha -p $parent_sha < tmp_message )
where $doc_dir – our doc directory
Thanks for pointing this out. I’ve not needed to do this since I wrote the post. These days’s I’d be taking a closer look at the github-maven-plugin.