Version Control

Creating Initial RCS Files

The first step in managing source-file revisions by using RCS is to enable RCS to archive the current revision of your files. Follow these steps to put the source file under the control of RCS:

1. In the directory where you keep your application's source files, create a subdirectory named RCS by typing mkdir RCS. If the RCS subdirectory exists, RCS archives file revisions in this directory.

2. In each file you plan to place under revision control, add a comment by adding the following RCS identification keyword:

   $Id$

   In a C source file, for example, add the following:

   /*
    * $Id$
    */

   In a makefile, on the other hand, use the following:

   # $Id$

   Later, RCS expands these identifier keywords to include information about the file revision and date.

3. Check in each file with RCS; use the ci command, and provide a brief description of each file as prompted by ci. Following is how you might check in Makefile:

   ci Makefile
   RCS/Makefile,v  <--  Makefile
   enter description, terminated with single '.' or end of file:
   NOTE: This is NOT the log message!
   >> Makefile for sample programs.
   >> .
   initial revision: 1.1
   done

   When a file is checked in, the ci command creates a corresponding RCS file in the RCS subdirectory. The RCS file's name is the same as the original file, except a ,v is appended to the name. Thus, the RCS file for Makefile is Makefile,v. Also, ci deletes the original source file after it creates the RCS file. To use or edit the file again, you have to extract it by using the co command.

After you follow these steps, all your files are safely stored in RCS files in the RCS sub-directory.

Using the Archived Files

Now suppose you want to edit one of the files (for example, to add a new feature) and rebuild the application. For starters, you need all the source files and the makefile for the compile and link step.

You should extract all these files by using the co command for read-only access (except for the file you want to change). Using the co command is straightforward. To get a working copy of Makefile for read-only use, for example, use the following command:

co Makefile
RCS/Makefile,v --> Makefile
revision 1.1
done

By default, this command looks for an RCS file named RCS/Makefile,v and creates a read-only working copy of it named Makefile.

A copy of Makefile is in the directory. Examine that copy of Makefile to see what happens to the $Id$ keyword that you add as a comment. Here's what my example Makefile shows:

# $Id: Makefile,v 1.1 2003/02/08 03:06:56 naba Exp $

As this example shows, RCS expands each identifier keyword into a string with information. The exact information depends on the identifier.

If you want to modify a file, you have to check it out by using the -l option. If you want to check out a copy of the file xmutil.c for editing, use this command:

co -l xmutil.c
RCS/xmutil.c,v --> xmutil.c
revision 1.1 (locked)
done

Compare this output with that from the previous example of co; the current output confirms that the RCS file is locked. No one else can modify the archived file until you check in the copy you have checked out for editing.

When you check out a file and put a lock on it, no one else can check out the same file for editing. However, anyone can get a copy of the file for read-only use.

After you make changes in a file, you can check it in again by using the ci command, just as you do when you create the RCS file.

Using RCS Identification Keywords

You can use RCS identification keywords-each of which is a string delimited by dollar signs ($...$)-to record information in source files. RCS expands the $Id$ keyword, for example, into summary information about the file, including the filename, revision number, date, and author. All you have to do is put the keyword in the file; RCS takes care of expanding that keyword into the appropriate information. Table 23-6 lists the identification keywords RCS supports.

RCS expands the identifier keywords anywhere in a file. Thus, you might mark an object file (and the executable that uses that object file) by placing the identifier keyword in a string variable. A common practice is to define a string named rcsid as follows:

static const char rcsid[] = "$Id";

Defining the rcsid string causes the object and executable file to contain a string such as the following:

$Id: xmutil.c,v 1.1 2003/02/08 03:09:56 naba Exp naba $

Viewing the Changes Made So Far

Most of the time, the ci and co commands are used to maintain file revisions with RCS. RCS, however, includes several other tools for managing various aspects of version control, such as comparing two revisions, viewing the history of changes, and examining identifiers in files.

If you have checked out a file for modification, you might want to know what changes you have made thus far. You can use the rcsdiff program to see a list of changes. If you've been editing a file named xmutil.c, for example, you can compare the working file against its RCS file, by using this command:

rcsdiff xmutil.c

The rcsdiff program runs the UNIX diff utility to find the differences between the working file and the RCS file.

If necessary, you can even find the differences between two specific revisions of a file by using a command such as the following:

rcsdiff -r1.1 -r1.2 xmutil.c

This command lists the differences between revision 1.1 and 1.2 of the file xmutil.c.

Discarding Changes Made So Far

Sometimes after making changes in a file, you realize the changes are either wrong or unnecessary. In such a case, you want to discard the changes you have made so far.

To discard changes, all you have to do is unlock the RCS file and delete the working copy of the file. To unlock an RCS file, use the rcs command with the -u (unlock) option. The following command discards the current changes in the file named xmutil.c:

rcs -u xmutil.c

Another, more convenient, way to discard changes is to overwrite the current working file with a copy of the former RCS file. To do this, use the co command with -u and -f flags:

co -f -u xmutil.c

The -u option unlocks the checked-out revision, and -f forces co to overwrite the working file with the former revision of that file.

Viewing the Change Log

As you make changes in a file and keep checking in revisions, RCS maintains a log of changes. You can view this log by using the rlog command. The following example shows how to view the log of changes for the file xmutil.c:

rlog xmutil.c

RCS file: RCS/xmutil.c,v
Working file: xmutil.c
head: 1.2
branch:
locks: strict
access list:
symbolic names:
keyword substitution: kv
total revisions: 2;     selected revisions: 2
description:
Motif utilities
----------------------------
revision 1.2
date: 2003/02/08 01:16:47;  author: naba;  state: Exp;  lines: +10 -6
Added new header file
----------------------------
revision 1.1
date: 2002/10/26 01:10:27;  author: naba;  state: Exp;
Initial revision
======================================================================

The first part of the rlog output displays some summary information about the RCS file. The lines following the description: line show the description I enter when I create the RCS file. Following this description is an entry for each revision, with the most recent revision appearing first. Each revision's entry shows the date, the author, and a brief description the author has entered.

Examining Identifier Keywords

If any identifier keywords are embedded in a file, you can view them by using the ident command. If Makefile contains the $Id$ keyword, you can examine the keyword by using this command:

ident Makefile
Makefile:
     $Id: Makefile,v 1.1 2003/02/08 01:06:26 naba Exp $

If you define a string variable with a keyword that eventually gets embedded in a binary file (an object file or an executable file), ident displays those identifiers as well. You can try ident in any binary file to see whether it contains any embedded keywords. This is what I find when I try ident on the file /usr/bin/ident (the executable program for the ident command itself):

ident /usr/bin/ident
/usr/bin/ident:
     $Id: rcsbase.h,v 5.20 1995/06/16 06:19:24 eggert Exp $
     $Id: ident.c,v 5.9 1995/06/16 06:19:24 eggert Exp $
     $Id: rcsmap.c,v 5.3 1995/06/16 06:19:24 eggert Exp $

From this output, you can tell the exact versions of source files that are used to build this version of the ident program.