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?

Lorenelorens

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.

Oliy

God - yes! that is what scm is for.. knowing the last time a file was modified. Metadata must not be mixed with data. The NSA can explain this problem :-) – Furnivall

@Furnivall I see what you did here ;) If I parse your last comment through the prism of the actuality, its meaning is quite clear. – Oliy

The purpose of including the revision in code is to track the source of the code after it is published. This is more important then having to manually merge one file. This "don't do it" answer is a typical case where someone thinks a tool is more important than its purpose.. – Ackerman

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.

Golfer

Answer 3

After working with Post-commit-hooks and scripts, which change files. And other methods, if was glad, when I found this:

create a file .git/info/attribute

# use keyword replacements
*.py ident
*.c ident
*.cpp ident
*.h ident
*.txt ident
*.md ident

# eof

Now use it in your source code like with SVN:

__revision__ = "$Id: 3bdd3ee4bff8ff63bf6525f55b1d435258b6327b $"[5:5+7]
__version__ ="3.0.3." + __revision__

Commit and checkout again, what a surprise! Unfortunately it doesn't work with Rev, Date, HeadUrl. But the Hash-Revision is the most important, and that's very useful.

Nitrification