Publishing README files automatically with
Tags: programming« 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
to the (bare) repository.
gitweb will then display the contents of this file along with the tree
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.mdin the root directory of this repository
- A remote bare repository on a server that is accessed by
To create the
README.html file within the bare repository, I created a simple
#!/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
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.