2.  Getting started with RCS

      Suppose a text file f.c is to be placed under control of RCS. Invoking the check-in command 


ci  f.c
creates a new revision group with the contents of f.c as the initial revision (numbered 1.1) and stores the group into the file f.c,v. Unless told otherwise, the command deletes f.c. It also asks for a description of the group. The description should state the common purpose of all revisions in the group, and becomes part of the group's documentation. All later check-in commands will ask for a log entry, which should summarize the changes made. (The first revision is assigned a default log message, which just records the fact that it is the initial revision.)

      Files ending in ,v are called RCS files (v stands for versions); the others are called working files. To get back the working file f.c in the previous example, execute the check-out command: 


co  f.c
This command extracts the latest revision from the revision group f.c,v and writes it into f.c. The file f.c can now be edited and, when finished, checked back in with ci: 

ci  f.c
Ci assigns number 1.2 to the new revision. If ci complains with the message 

ci error: no lock set by <login>
then the system administrator has decided to configure RCS for a production environment by enabling the `strict locking feature'. If this feature is enabled, all RCS files are initialized such that check-in operations require a lock on the previous revision (the one from which the current one evolved). Locking prevents overlapping modifications if several people work on the same file. If locking is required, the revision should have been locked during the check-out by using the option -l: 

co  -l  f.c
Of course it is too late now for the check-out with locking, because f.c has already been changed; checking out the file again would overwrite the modifications. (To prevent accidental overwrites, co senses the presence of a working file and asks whether the user really intended to overwrite it. The overwriting check-out is sometimes useful for backing up to the previous revision.) To be able to proceed with the check-in in the present case, first execute 

rcs  -l  f.c
This command retroactively locks the latest revision, unless someone else locked it in the meantime. In this case, the two programmers involved have to negotiate whose modifications should take precedence.

      If an RCS file is private, i.e., if only the owner of the file is expected to deposit revisions into it, the strict locking feature is unnecessary and may be disabled. If strict locking is disabled, the owner of the RCS file need not have a lock for check-in. For safety reasons, all others still do. Turning strict locking off and on is done with the commands: 


rcs  -U  f.c       and         rcs  -L  f.c
These commands enable or disable the strict locking feature for each RCS file individually. The system administrator only decides whether strict locking is enabled initially.

      To reduce the clutter in a working directory, all RCS files can be moved to a subdirectory with the name RCS. RCS commands look first into that directory for RCS files. All the commands presented above work with the RCS subdirectory without change.**

      It may be undesirable that ci deletes the working file. For instance, sometimes one would like to save the current revision, but continue editing. Invoking 


ci  -l  f.c
checks in f.c as usual, but performs an additional check-out with locking afterwards. Thus, the working file does not disappear after the check-in. Similarly, the option -u does a check-in followed by a check-out without locking. This option is useful if the file is needed for compilation after the check-in. Both options update the identification markers in the working file (see below).

      Besides the operations ci and co, RCS provides the following commands: 

ident       extract identification markers
rcs         change RCS file attributes
rcsclean    remove unchanged working files (optional)
rcsdiff     compare revisions
rcsfreeze   record a configuration (optional)
rcsmerge    merge revisions
rlog        read log messages and other information in RCS files
A synopsis of these commands appears in the Appendix.

2.1.  Automatic Identification

      RCS can stamp source and object code with special identification strings, similar to product and serial numbers. To obtain such identification, place the marker 


$Id$
into the text of a revision, for instance inside a comment. The check-out operation will replace this marker with a string of the form 

$Id:  filename  revisionnumber  date  time  author  state  locker $
This string need never be touched, because co keeps it up to date automatically. To propagate the marker into object code, simply put it into a literal character string. In C, this is done as follows: 

static char rcsid[] = "$Id$";
The command ident extracts such markers from any file, in particular from object code. Ident helps to find out which revisions of which modules were used in a given program. It returns a complete and unambiguous component list, from which a copy of the program can be reconstructed. This facility is invaluable for program maintenance.

      There are several additional identification markers, one for each component of $Id$. The marker 


$Log$
has a similar function. It accumulates the log messages that are requested during check-in. Thus, one can maintain the complete history of a revision directly inside it, by enclosing it in a comment. Figure 1 is an edited version of a log contained in revision 4.1 of the file ci.c. The log appears at the beginning of the file, and makes it easy to determine what the recent modifications were. 

/*
* $Log: ci.c,v $
* Revision 4.1  1983/05/10 17:03:06  wft
* Added option -d and -w, and updated assignment of date, etc. to new delta.
* Added handling of default branches.
*
* Revision 3.9  1983/02/15 15:25:44  wft
* Added call to fastcopy() to copy remainder of RCS file.
*
* Revision 3.8  1983/01/14 15:34:05  wft
* Added ignoring of interrupts while new RCS file is renamed;
* avoids deletion of RCS files by interrupts.
*
* Revision 3.7  1982/12/10 16:09:20  wft
* Corrected checking of return code from diff.
* An RCS file now inherits its mode during the first ci from the working file,
* except that write permission is removed.
*/
Figure 1.  Log entries produced by the marker $Log$.

Since revisions are stored in the form of differences, each log message is physically stored once, independent of the number of revisions present. Thus, the $Log$ marker incurs negligible space overhead.