Subversion Keywords

Initial thought: what a pain.

Howeve, after thinking about that, I take it back. This is a lot more flexible than CVS, and a lot less error-prone, so I guess I should be happy. It's still a pain, though, and I always forget to do it and forget how to do it.

In CVS, certain keywords (inherited from RCS) are automatically expanded when they're discovered in the source code. For instance, $Id$ might expand to $Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp $ when the file is checked in. There are a number of keyword expansion modes (-kkv, -kkvl, -kk, -kv, -ko, -kb) which you set to determine how (or if) the expansion is going to take place. However, the default is for the expansion to happen. This is sometimes a problem when importing existing code (with its own Ids) into a vendor branch (CVS will replace the labels unless told otherwise) and it can also be a problem in binary files (images) which CVS does not really recognize.

Instead of the hard-to-remember expansion modes and a fixed set of tags, the Subversion designers opted for something more flexible and more powerful: each versioned resource has a set of properties associated with it. There are still certain built-in properties, but you can also specify your own properties, which is actually a pretty cool concept. See the svnbook for more details.

Anyway, in order to Subversion to recognize things like $Id$ and $Revision$ in source files, you have to tell it to do this explicitly by updating the svn:keywords property:

   svn propset svn:keywords "Id" <file>

Changes such as this are versioned just like any other changes to files, so you'll have to commit after running this command for it to take effect.

I would like to be able to say "set the Id keywords property on all files in this directory". I haven't found a way to do that, but I have figured out how to set the property automatically on files matching certain patterns. Add lines such as this to your ~/.subversion/config file:

[miscellany]
enable-auto-props = yes

[auto-props]
   *.py = svn:keywords = Id
   *.c = svn:keywords = Id
   *.pl = svn:keywords = Id

Whenever you add a file matching *.py, *.c or *.pl to your repository, it will automatically have the Id keyword set.

Note: According to Andy Miller (whose update to this page I have edited), TortiseSVN does allow for recursively setting a property.

Note: I think I have found a bug (which I haven't yet managed to reproduce) where if you set a property on an unchanged file that is already set on the checked-in version, any additional property changes you make after that don't take effect. So, if you see something surprising, blow away the working copy of the file, and use svn update to start over. That should fix it.

For some files, like Vim files, I use $LastChangedDate$ rather than $Id$ because Bram wants "Last Change" as a header item. (I could also just use $Date$ , rather than $LastChangedDate$ - they're equivalent.)

In my own source trees (Python or whatever), I set the "Id" keyword on all files. In source trees like banner that contain external files from things like autoconf and automake, I only set the keyword on the files I actually maintain. The same goes for Vim directories where I'm storing a version of someone else's script just for simplicity's sake (I wouldn't want to blow away their version number from the script). Also, I don't set the keyword values on unit test data unless I actually want a keyword in the data.

Unfortunately, there's no equivalent of the CVS $Revision$ keyword that has the latest file revision, because Subversion has no concept of per-file revisions. Instead, what's shown is the global repository revision (which is more like a commit reference).