GNU Info

(cvsbook.info)Using Keyword Expansion

---

Next: Going Out On A Limb (How To Work With Branches And Survive) Prev: Annotations And Branches Up: Advanced CVS

---

Enter node , (file) or (file)node

Using Keyword Expansion
=======================

You may recall a brief mention of `keyword expansion' in Note: 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 Note: CVS Reference.