Git Version in Doxygen

When generating Doxygen documentation, you might want to tell the reader which version of the source code was used to generate the documentation. Here’s how to do that when you’re using git.

The ingredients are:

• A Makefile that calls doxygen, because that’s what you’re most likely using when dealing with Doxygen.
• The ability of make to export variables to the environment.
• The ability of make to deal with expressions that are stdout of shell commands, by using the $(shell ...) built-in function.
• The ability of doxygen to refer to environment variables in its configuration file Doxyfile, and a Doxyfile that makes use of this.
• The git plumbing command rev-parse to get the version number.
• The git plumbing command diff-index to find out whether something was modified.

Here’s the Makefile:

1 doc: export PROJECT_NUMBER:=$(shell git rev-parse HEAD ; git diff-index --quiet HEAD || echo "(with uncommitted changes)")
2 
3 .PHONY: doc
4 doc:
5 	doxygen

Here’s the relevant section of the Doxyfile:

1 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
2 # could be handy for archiving the generated documentation or if some version
3 # control system is used.
4 
5 PROJECT_NUMBER         = $(PROJECT_NUMBER)

In case you need a bash script instead of a Makefile, here you go:

1 #!/bin/bash
2 export PROJECT_NUMBER="$(git rev-parse HEAD ; git diff-index --quiet HEAD || echo '(with uncommitted changes)')"
3 exec doxygen

There you go!