Publishing a subdirectory to github pages

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.

Comments 6

  1. dom wrote:

    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.

    Posted 04 Jul 2009 at 02:19
  2. trans wrote:

    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.

    Posted 30 May 2011 at 02:29
  3. trans wrote:

    Never mind… it provides the changelog.

    But doesn’t the gh-pages branch still need to be pushed?

    Posted 30 May 2011 at 02:38
  4. Dominic Mitchell wrote:

    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.

    Posted 30 May 2011 at 15:50
  5. Meettya wrote:

    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

    Posted 06 Nov 2011 at 10:32
  6. Dominic Mitchell wrote:

    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.

    Posted 06 Nov 2011 at 21:52