CVS revision numbers

The most important thing to know about CVS revisions is that in general you should never pay attention to them at all except as opaque identifiers for versions of files. The revision numbering convention is inherited from RCS and used internally for branching, and CVS works best and most reliably if revisions are never changed by hand. However, sometimes it's convenient to use the CVS revision as the version of a script when that script is a single file, so that one doesn't have to remember to manually maintain the version number.

CVS revisions are the version numbers that CVS assigns to files. All files in CVS have a corresponding revision, and whenever you commit a change, the revision number of the changed files is incremented. By default, revision numbers start at 1.1, and the second digit is incremented with each commit (becoming 1.2, 1.3, and so on). CVS will never by default increment the first digit; it will happily go on to revisions like 1.134.

However, things aren't quite as straightforward as just that. CVS, when assigning an initial version to a new file, doesn't always assign 1.1. Instead, it finds the highest numbered revision of any file in the same directory, takes the first digit, and assigns a revision of <digit>.1 to new files. In other words, if you have a file in the same directory that has a revision of 2.30, a new file in that directory will get a revision number of 2.1, not 1.1.

The other exception is that CVS will never assign a first revision lower than 1.1, even if all the files in the directory have revisions of 0.4 or so.

It's easy to tell CVS to increment the first digit of the revision number, provided that you're setting it to something equal to or greater than the highest first digit of all revisions of all files in the same directory. Just use the -r flag on commit. For example:

    cvs commit -r 2 <file>

where <file> currently has a revision of 1.<something>, will check in that file with a new revision of 2.1. Note that you only need to give the first digit of the new revision; the .1 part is assigned automatically. After you do this, 2 will be set as a sticky tag that you then want to clear by doing:

    cvs update -A <file>

(Note that you should never attempt to do this with files that have branches, since on branches CVS uses the revision number internally for important things and can get confused by manual changes.)

Be careful about doing this. As mentioned above, incrementing the major revision of a file will cause any new files added in the same directory to start with 2.1 (or whatever major version number you incremented to) by default instead of 1.1 and you'll need to use cvs commit -r1.1 to override that. Only do this if you really want to use the CVS revision for the version number for simplicity; there's no reason to ever do this for projects that involve multiple files.

If you do want to use the CVS revision number as the version number of a Perl script, I use the following code or something similar using Getopt::Long to handle the -v or --version command-line option:

    $ID = q$Id$;

    # [...]

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

See the documentation on file headers for more information about how you can use CVS's special keywords in the headers of files and scripts.