Publishing README files automatically with gitweb

Tags: programming

Published on
« Previous post: QApplication and the locale — Next post: Why E-Mail made in Germany is a farce »

If you are using gitweb to serve your git repositories, you can add a file named README.html to the (bare) repository. gitweb will then display the contents of this file along with the tree of commits.

It is more satisfying, however, to generate the HTML file automatically. This is 2013, after all. We have the technology! I personally like Markdown as a lightweight and readable format. With the corresponding converter, you won’t ever have to think about HTML again.

My current setup looks like this:

  • A git repository on a local machine somewhere
  • A file named README.md in the root directory of this repository
  • A remote bare repository on a server that is accessed by gitweb

To create the README.html file within the bare repository, I created a simple post-receive hook:

#!/bin/sh
git cat-file blob HEAD:README.md | markdown > $GIT_DIR/README.html

Place this hook in the hooks subdirectory under the name post-receive and make it executable. After the chunks for each commit have been received, the hook will look for the file README.md on the master branch of the repository and generate the corresponding HTML file from it. The best part of this is that the file is getting updated along with the program and you never have to worry about re-generating the documentation.