git revision number in source code documentation

Question

I've seen in several projects that developers include something like $Revision$ in source code documentation. I think they are macros or environment variables for some tool but I do not know how to work with them.

I am interested on adding this feature to my next project. I normally use TextMate, git and doxygen. Any suggestions?

Answer 1

Yes: suggestion: don't do it.
Keyword expansion could be done with gitattribute filter, as presented in "Git equivalent of subversion's $URL$ keyword expansion", but this introduce metadata within the data, which usually makes merge much more complex that they actually are.

You can see in this (lengthy) answer on "What are the basic clearcase concepts every developer should know?" the all debate on "Embedded Version Numbers - Good or Evil?".
Unless you have a good merge manager in order to ignore those special values, you get a "Merge Hell".
And with Git, as detailed in "How does Git solve the merging problem?", the merge is quite basic. No fancy merge manager.

Answer 2

$Revision:$ (the ':' is required) is used by RCS and CVS. Some other systems have similar features, but it seems that the more modern ones do not.