Software Interest Group

• Schedule
• Documentation
• Resources
• Thanks

---

RCS

by Andre Lehovich

---

[Note (added Jan. 2005): there is a newer but very similar utility called Concurrent Versions System (CVS). Documentation for CVS can be found at the Linux info pages ($ info cvs) or at the following CVS tutorial website.]

Introduction

The Revision Control System (RCS) is a UNIX package to assist with version control -- it will keep track of how a file changes over time, and will let you retrieve an earlier version of the file. For example, you can have it show you what your program looked like 3 months ago, when you produced the results your advisor is unhappy with. RCS can also act as a mediator between multiple people working with the same set of files, e.g. co-authors or developers, although many of those features won't be discussed here.

The library is a good metaphor for RCS. When you want to get a file, either to look at it or to change it, you have to first check it out. When you are done making changes you check them back in.

Activating RCS

After creating the original version of your file (in these examples we'll use program.c) you tell RCS it exists with the command

ci program.c

You'll be asked to enter a description of the file. Terminate the description with a single ".":

A program to do many wonderful things.
.

This creates a new file program.c,v and deletes the old file program.c. Future access to the file will be mediated by RCS. (The ",v" files will be all stored in the same directory as the original. If you create a subdirectory called RCS they'll go there instead.)

Checking Out (co)

To look at the file, or compile it, you have to check it out:

co program.c

Notice that the file is now read-only. To make changes to the file you have to check it out with a lock:

co -l program.c

Locking is intended for projects with more than one person. Since only one person can have a lock at a time, you can be sure you're the only person making changes to the file.

Checking In (rcsdiff and ci)

Once you've made a bunch of changes to your file you have to tell RCS about them. Forgotten what the changes were? The command

rcsdiff program.c

will tell you, indicating which lines were added, deleted, or changed. (The output, which is in the format used by the diff command, will seem less cryptic with practice. You might also want to try

rcsdiff -c program.c

to see changes in context).

To tell RCS about the changes use the command

ci program.c

You'll be asked to enter a note indicating what you've changed:

Many important changes and bug fixes.
.

(Hint: Try to stick with comments which will make sense 6 months from now.) Again, the working file will be deleted, and you have to use co to check it out. (Note that the "-l" or "-u" options to ci can automate checking out). At this point RCS has recorded the changes you made to your file, and assigned a new version number to them.

Important Warning: Unless you regularly check files back in RCS is useless, as it only knows about changes present at check in. Exactly how often to check in is a judgment call, but RCS only knows about changes that are registered with "ci". Some folks make changes every day before going home, others after each set of changes which can be lumped together as a unit. Try to err on the side of too many check ins.

Looking at Old Versions (rlog, co)

Say you want to get at an older version of your file. First you can get a list of all the versions RCS knows about:

rlog program.c | more

The listing will include each revision number, it's date and time (RCS uses Greenwich Mean Time, not Tucson time), check-in comment, and author. Usually one checks out older files by revision number:

co -r1.1 program.c

One can also retrieve the last version checked in prior to a given date and time:

co -d'April 23 4:00pm LT' program.c

(The LT means use local time, not Greenwich time).

Magic Keywords

RCS can automatically update certain things within a file, such as the version number and date. For example, you can put the following at the top of a C or C++ file:

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

As you check the file in and out RCS will automatically update the ID string as needed. You can use something like

printf("Generated by version %s\n", rcsid);

to include version information in your program output. Since the version is stored in a string, the compiler will also place it into the executable. The following command will tell you which version of the source was used to produce the executable a.out:

ident a.out

For a full list of available keywords see the co man-page. If you put the following comment at the top of your C file it will build up a running history of changes:

/*
 * $Log: $
 */

Lock Disabling and Retroactive Locking (rcs)

On single user projects the lock feature can be a pain. To turn it off use the command

rcs -U program.c

To turn it back on use

rcs -L program.c

If you have made a bunch of changes without locking, and want to retroactively lock use

rcs -l program.c

Disk space

Instead of storing the complete text of version, behind the scenes RCS only keeps track of the changes between versions, and uses these to reconstruct older versions. This is fairly efficient, so keeping old versions of a file isn't a major disk space hit. The main cost is having the RCS master and your working copy both present. To get rid of the working copies (i.e. keep only the master ",v" files) use the command

rcsclean

You can check out the latest version of each file in the current directory with:

co *,v

In any case, disk space is cheaper than your time. (Even graduate student time!)

Suggested Uses for RCS

• Tracking how your numerical codes change with time.
• Storing your thesis as it gets written.
• Your .cshrc file. (Great if you have to switch from LaTeX2.9 to LaTeX2e, and 3 months later want to go backwards).
• Web pages.
• Any document you periodically distribute to others.

Emacs19 & Make

Emacs19 has it's own user interface to RCS. For a full description read the info page (from within emacs type "C-h i") on Version Control. Most commands start with the prefix "C-x v". File check-in and out is toggled using "C-x C-q". The snapshot feature is especially useful if you plan to distribute your software.

Some versions of make (including the gnu version) know how to check the latest version of a file out from RCS. For further details see the make documentation.

RCS vs. SCCS

RCS is partially based on an earlier program called SCCS. Even though RCS was written to correct many of its predecessor's defects, SCCS still ships with many versions of UNIX. Don't use it! RCS is faster, has more features, and is more robust. Specifically:

• RCS's user interface is simpler and easier to use.
• RCS allows lock stealing on multiple user projects. SCCS doesn't.
• RCS supports named versions, SCCS doesn't. (These can be used to generate "snapshots" of your directory).
• RCS's magic strings ("$Keyword:$") are more robust, and it supports more of them.
• SCCS uses forward differences from the original version (slow). RCS uses backward differences from the latest version (fast).
• RCS stores the latest version in clear-text, which is handy if some moron corrupts the master file. SCCS stores the earliest version.
• Linux ships with RCS, but not SCCS.

Other Information Sources

• The rcsintro man page is a good introduction, as is Tichy's paper on RCS.
• O'Reilly publishes the Racoon Book about RCS. I haven't read it, but they're one of the better UNIX publishers.
• RCS ships with many UNIX systems, including Linux. The RCS source code can be downloaded from the FSF Gnu Project.
• A DOS port is available from the Gnuish MS-DOG project. Windoze ports probably also exist.