What's GNU?

What is RCS? RCS is the Revision Control System. Its job is to manage the process of revising and updating files. It can and should be used for program text and documentation, as well as for any other files that are revised on a frequent basis. RCS allows you to retrieve earlier versions of files, while keeping a log of what changes were made, who made them, and why. RCS makes it easy to compare any two versions of a file, and provides a mechanism for merging changes from two different development “branches” of a source file.

RCS was originally written by Dr. Walter F. Tichy, at Purdue University. Beginning in 1983, it received wide-spread use in the Unix community with its release as part of the User Contributed Software in 4.2BSD. It was described in an article in “Software—Practice And Experience” in July 1985.

RCS provides a safety net for the software developer. When developing, fixing, and improving a program, changes are inevitable. By saving a stable version of your file in RCS, you can later return to a known state if a set of changes does not work out.

If more than one person is working on the same file, RCS allows you to “lock” a file, so that only one person will be allowed to make changes. Other people can still use the file, e.g., for compiling.

Besides keeping track of what changes were made to a file, RCS tracks who made the change and when. RCS also files a log message describing the change. This makes it easy to figure out who broke the program when the fatal bug is finally isolated.

The user interface is intentionally quite simple, consisting primarily of two commands, ci and co. To start with, make a directory to hold the program and cd into it. Then make a directory named RCS. Although not required, this is the cleanest way to do it; all RCS files will be kept in the RCS subdirectory. We'll also create the first version of the program.

$ mkdir hello
$ cd hello
$ mkdir RCS
$ cat > hello.c # editors are for wimps! :-)
#include <stdio.h>
int main(void)
{
   printf("hello, world\n");
}
^D
$ ls -l hello.c
-rw-r--r--  1 arnold       66 Nov  5 22:33 hello.c

We now have a C source file that is ready to go. When compiled and run, it prints the well-known, friendly greeting beloved by C programmers the world over.

After making sure it compiles, the first thing to do is “check in” the program with RCS. This is accomplished with ci.

$ ci hello.c
RCS/hello.c,v <-- hello.c
enter description, terminated with single `.' or end of file:
NOTE: This is NOT the log message!
> world famous C program that prints a friendly
message.
> .
initial revision: 1.1
done
$ ls
RCS

The first time a file is checked in, RCS wants a description of just what the file is. It reminds us that this is not the log message, thus, something like “initial revision” would be inappropriate here. The > is the prompt for information. Also note that the original file is removed. RCS has the file safely stored in the RCS file hello.c,v in the RCS directory.

Well, a file that we can't compile isn't of much use, so the next thing to do is get a copy so that we can actually compile the program and use it. This is done with co, which stands for “check out”.

$ co hello.c
RCS/hello.c,v -> hello.c
revision 1.1
done
$ ls -l hello.c
-r--r--r-- 1 arnold 66 Nov 5 22:43 hello.c
$ gcc hello.c -O -o hello; ./hello
hello, world

Note that the file is returned to us, but with read-only permissions. We are thus allowed to use the file, but not change it. In normal use, for instance, to build a whole source tree to install software, you would check out the files read-only, compile the programs, and then remove the source files.

What about when you want to change a file? Programs do evolve, so how do you get to the next revision? The first thing to do is to check out the file, but with a lock on the file. The lock says that you, and only you, are allowed to check in a new revision of the file. This is necessary if more than one person will be working with the source file, so that two people don't trash each other's work.

$ co -l hello.c
RCS/hello.c,v -> hello.c
 revision 1.1 (locked)
done
$ ls -l hello.c
-rw-r--r-- 1 arnold         66 Nov  5 22:51 hello.c

This checks out the file, and locks it. Note that the permissions now allow writing to the file. We can edit the file, and make our changes to it.

$ sam hello.c   # a nifty editor,
# watch for a future column on it.
$ cat hello.c
#include <stdio.h>
#include <string.h>
int main(int argc, char **argv)
{
   if (argc > 1 && strcmp(argv[1], "-advice") == 0) {
      printf("Don't Panic!\n");
      exit(42);
   }
   printf("hello, world\n");
   exit(0);
}
$ gcc -O hello.c -o hello
$ ./hello -advice
Don't Panic!
$ ./hello
hello, world

Our program now has a new option, -advice, that prints a friendly piece of advice and exits with a well known, special value. The default behavior remains unchanged, except that exit is now used for the normal case, as well.

We can now check in the new version to RCS. Assuming that we will want to do further work on the file, ci also allows us to use the -l option. With this option, ci will perform the check-in and automatically do a co -l for us, so that we can continue to work on the file.

$ ci -l hello.c
RCS/hello.c,v <- hello.c
new revision: 1.2; previous revision: 1.1
enter log message, terminated with single `.' or end of file:
> Added -advice option, and made regular case use exit.
> .
done
$ ls -l hello.c
-rw-r--r-- 1 arnold        208 Nov 5 22:54 hello.c

Here we see where the log message is entered. Log messages should be relatively brief, describing what was changed and why. In a commercial environment, you might enter the bug number associated with a particular fix into the log, as well. We also see that the file is still available for further editing (permissions -rw-r--r--).