Next: , Previous: Annotations And Branches, Up: Advanced CVS


Using Keyword Expansion

You may recall a brief mention of keyword expansion in An Overview of CVS. RCS keywords are special words, surrounded by dollar signs, that CVS looks for in text files and expands into revision-control information. For example, if a file contains

     $Author$

then when updating the file to a given revision, CVS will expand it to the username of the person who committed that revision:

     $Author: jrandom $

CVS is also sensitive to keywords in their expanded form, so that once expanded, they continue to be updated as appropriate.

Although keywords don't actually offer any information that's not available by other means, they give people a convenient way to see revision control facts embedded in the text of the file itself, rather than by invoking some arcane CVS operation.

Here are a few other commonly used keywords:

     $Date$       ==>  date of last commit, expands to ==>
     $Date: 1999/07/26 06:39:46 $
     
     $Id$         ==>  filename, revision, date, and author; expands to ==>
     $Id: hello.c,v 1.11 1999/07/26 06:39:46 jrandom Exp $
     
     $Revision$   ==>  exactly what you think it is, expands to ==>
     $Revision: 1.11 $
     
     $Source$     ==> path to corresponding repository file, expands to ==>
     $Source: /usr/local/newrepos/tossproj/hello.c,v $
     
     $Log$        ==>  accumulating log messages for the file, expands to ==>
     $Log: hello.c,v $
     Revision 1.2  1999/07/26 06:47:52  jrandom
     ...and this is the second log message.
     
     Revision 1.1  1999/07/26 06:39:46  jrandom
     This is the first log message...

The $Log$ keyword is the only one of these that expands to cover multiple lines, so its behavior is unique. Unlike the others, it does not replace the old expansion with the new one, but instead inserts the latest expansion, plus an additional blank line, right after the keyword (thereby pushing any previous expansions downward). Furthermore, any text between the beginning of the line and $Log is used as a prefix for the expansions (this is done to ensure that the log messages stay commented in program code). For example, if you put this into the file

     // $Log$

it will expand to something like this on the first commit:

     // $Log: hello.c,v $
     // Revision 1.14  1999/07/26 07:03:20  jrandom
     // this is the first log message...
     //

this on the second:

     // $Log: hello.c,v $
     // Revision 1.15  1999/07/26 07:04:40  jrandom
     // ...and this is the second log message...
     //
     // Revision 1.14  1999/07/26 07:03:20  jrandom
     // this is the first log message...
     //

and so on:

     // $Log: hello.c,v $
     // Revision 1.16  1999/07/26 07:05:34  jrandom
     // ...and this is the third!
     //
     // Revision 1.15  1999/07/26 07:04:40  jrandom
     // ...and this is the second log message...
     //
     // Revision 1.14  1999/07/26 07:03:20  jrandom
     // this is the first log message...
     //

You may not want to keep your entire log history in the file all the time; if you do, you can always remove the older sections when it starts to get too lengthy. It's certainly more convenient than running cvs log, and it may be worthwhile in projects where people must constantly read over the logs.

A more common technique may be to include $Revision$ in a file and use it as the version number for the program. This can work if the project consists of essentially one file or undergoes frequent releases and has at least one file that is guaranteed to be modified between every release. You can even use an RCS keyword as a value in program code:

     VERSION = "$Revision: 1.114 $";

CVS expands that keyword just like any other; it has no concept of the programming language's semantics and does not assume that the double quotes protect the string in any way.

A complete list of keywords (there are a few more, rather obscure ones) is given in CVS Reference.

Karl Fogel wrote this book. Buy a printed copy via his homepage at red-bean.com

copyright  ©  January 18 2019 sean dreilinger url: https://durak.org/sean/pubs/software/cvsbook/Using-Keyword-Expansion.html