Using CVS keywords in file headers

CVS has a variety of keywords t hat are automatically expanded by CVS. $Id$ is one of the most useful ones; it expands out to the name of the RCS file (which is the name of the file plus a ,v), the revision number, the last modified date, and the username of the person to last modify the file. These are all interesting things to know about a file, so I generally will always put $Id$ somewhere in the header of any file I write that's under CVS revision control.

There are quite a few other keywords supported by CVS (mostly all inherited from RCS, so if you've used RCS before these should all be very familiar). $Revision$ contains just the revision number, $Date$ has just the last modified date, $Log$ will append CVS log entries to the file, and so on. For the most part, I only use $Id$, and I recommend against using $Log$ because it's easy enough to just get that information out of cvs log, but you may want to try playing around with the options and see what you think.

As examples, here are the headers that I use for various common types of files. For documentation files:

      Author: Name <email@address>
     Subject: Title of Documentation
    Revision: $Id$

For Perl scripts:

    #!/usr/bin/perl
    $ID = q$Id$;
    #
    # script -- One line description of script.
    #
    # Written by Name <email@address>
    # Copyright 1999 Board of Trustees, Leland Stanford Jr. University

For shell scripts, either the same, or if the shell script is particularly short sometimes the more abbreviated form of:

    #!/bin/sh
    # script -- One line description of script.
    # $Id$

For C code files and similarly for header files:

    /* $Id$

       One line description of file.

       Written by Name <email@address>
       Copyright 1999 Board of Trustees, Leland Stanford Jr. University

       Long description of what the file is for.  */

or sometimes the more abbreviated form of:

    /* file.h -- One line description of file. */
    /* $Id$ */

For configuration files, I usually use something like:

    # file -- One line description of file.
    # $Id$

(with the obvious variation for files that use different comment characters than #).

There are other obvious variations, but this should give a pretty good idea of how I use $Id$ in practice. Note that with the above syntax, a Perl script using that header actually gets the Id string in the variable $ID and can do things with it. In particular, I often use the code:

    if ($ARGV[0] =~ /^-.*v) {
        my $version = join (' ', (split (' ', $ID))[1..3]);
        $version =~ s/,v\b//;
        $version =~ s/(\S+)$/($1)/;
        die $version, "\n";
    }

to print out the name of a script and its current version number.