using RCS

Hi, visitor from !

Here is some useful information for using RCS, the revision control system. RCS is a nice system for (at least) two reasons: (1) it is simple; (2) it locks files to prevent multiple users (who are all using RCS) from modifying those files simultaneously; (3) it provides a history of revisions to source files and a mechanism for diff-ing versions. Oops I guess that was already more than two reasons.

Here are the basic ideas behind using RCS. You can get more information about the commands described here and the other commands that exist by doing:

$ man -k rcs

Creating an RCS directory
Checking files into RCS
Checking files out of RCS
Looking at a file's revision history
Finding out who has a file locked
Freezing files

Creating an RCS directory

First, create a directory called RCS below your working directory. For example, if my working directory is called tools/src, then I'll create tools/src/RCS:

$ mkdir RCS

Checking files into RCS

Check in your source files using the ci command. For example, if I am writing in C, then I'll issue this command:

$ ci *.c *.h

This will move all the *.c and *.h files to the RCS directory, renaming them by adding a ,v suffix to each file name and making each file readable but non-writeable. All these files are now considered unlocked.

RCS will prompt you to enter a log message for the file (except the first time you check a file in; then the log message is just "Initial revision"). Ideally, the log messages are short, succinct descriptions of the changes to the file since the last time it was checked into RCS.

RCS Logging

RCS keeps track of who locks a file, based on username. You can look at who has a file locked by using the rlog command. This command also gives you a history of the modifications to that file - assuming users have entered log messages when checking files in (unlike the example below!). For example, if I wanted to see who had makefile locked, I could enter the command:

$ rlog makefile

(from my working directory) and I'd get output something like this:

RCS file: RCS/makefile,v
Working file: makefile
head: 1.2
branch:
locks: strict
        sklar: 1.2
access list:
symbolic names:
        C_1: 1.2
keyword substitution: kv
total revisions: 2;     selected revisions: 2
description:
----------------------------
revision 1.2    locked by: sklar;
date: 1998/06/07 18:47:13;  author: sklar;  state: Exp;  lines: +5 -1
*** empty log message ***
----------------------------
revision 1.1
date: 1998/06/07 18:41:34;  author: sklar;  state: Exp;
Initial revision
=============================================================================

Checking files out of RCS

The locking mechanism in RCS is controlled by the co command. Typically you check out a file just to look at it or compile it - in read-only or unlocked mode, or you check out a file to modify it - in read-write or locked mode. If you and everyone you share code with gets in the habit of only modifying files that have been checked out of RCS, then your files will be safely locked and you will not be making new versions of a file at the same time as someone else.

For example, to check out a file in read-only mode:

$ co login.c

This copies login.c from RCS/login.c,v to your working directory and renames the copy login.c.

For example, to check out a file in read-write mode:

$ co -l login.c

This copies login.c from RCS/login.c,v to your working directory and renames the copy login.c. It sets the protections of the file so that (only) you can write to that file. It also places a lock on the file so that no-one else can do co -l on that file until you have checked the file back into RCS.

Freezing files in RCS

One nice feature of RCS is the ability to group a configuration of files (that have all been checked in). For example, if you get your program working a certain way and you want to make more changes, but would like to save the files that make it work the way it works currently, you can save that configuration before you make any more changes.

Issue the command:

$ rcsfreeze

You will be prompted to enter some comments about this version. Then RCS will record the version numbers of every file in the RCS directory and will associate a symbolic name to that frozen set of files.

Now you can go on and modify your files, but you now have the ability to recover the exact working version using co -r<symbolic name>.