RCS

Contents

Overview

RCS stands for Revision Control System. The purpose of RCS is to help you keep track of different version of your code. The basic facilities provided by RCS are:

To use RCS, you should make a directory named RCS (in the directory where you will be working on your code). RCS will store the versions of your code in that directory, but you should never access the files in that directory yourself (only via RCS).

Basic Commands

There are two basic RCS commands: ci (check-in), and co (check-out). They need to be typed in the directory that contains the RCS directory.

Check In
The format of the check-in command is: ci -l <list of file names>. For example:
ci -l Test.java SymTab.java
The command "checks in" the named files (saves them in the RCS directory). The -l flag is optional; if it is omitted, the files will be saved by RCS, and will be removed from the current directory. When you use the check-in command, RCS will ask you for:
  • A description of each file (if this is the first time you're checking them in), or
  • A log message for each file (if this is a new version of a file that has been checked in before). The log message should be a description of the changes made since the last check-in.
After typing the description or log message (you can use multiple lines), type a dot at the beginning of the line to end your input.

If the file has been checked in before, and it has not been changed, RCS will print a message saying that the file is unchanged, and will essentially abort the checkin (except that if you don't use the -l flag, the file will still be removed from your directory). If you want to force RCS to check in the file (e.g., so that you can provide a log message, or an attribute value -- see Atrributes below) you must use the -f flag (to "force" a check in).

Check Out
The format of the check-out command is: co -l <list of file names>. The command "checks out" the named files (copies them from the RCS directory to the current directory).

The -l flag means lock the files being checked out. This flag is optional; if it is omitted, the files will be checked out, but they will be write-protected (i.e., you will be able to read them, but you will not be able to change them). See Group Project below for more about locking files.

Without additional flags, you will get the most recently checked-in version of each file.

Attributes

Every file checked in to RCS has the following attributes, which can be used, when you do a check-out, to get versions other than the most recently checked in version:

revision
Each time you check in a file, it is given a revision number: 1.1, 1.2, 1.3, etc. You can use the -r flag to get back a specific version when you check out a file. For example: co -r1.2 checks out revision 1.2 (instead of the most recently checked in version).

You can also use the -r flag when you check in a file to tell RCS to start numbering the revision with a new number. For example: ci -r2 Test.java causes the checked-in file to be given revision number 2.1, and subsequently checked-in versions to be given numbers 2.2, 2.3, etc. This might be useful in the context of your class project; you might use revision 1 for all versions having to do with the second assignment (the scanner), revision 2 for versions having to do with the third assignment (the parser) etc.

date
The format is: yyyy/mm/dd, for example: 2000/02/09 means the ninth of February, 2000. You can used the -d flag when you check out a file to specify that you want the latest version that was checked in before midnight on the given date (but note that midnight on February 9 is the beginning, not the end of that day). For example: co -d2000/02/01 Test.java means "check out the most recent version of Test.java that was checked in before midnight on February 1" (i.e., was checked in no later than 11:59 on January 31).

state
The value of the state attribute can be any sequence of non-whitespace characters. The value of the state attribute is set when a file is checked in. For example: ci -sworkingVersion Test.java sets the state attribute of the checked-in version to be "workingVersion". You can use the -s flag when you check out a file to specify that you only want a version with the given value for the state attribute. For example: co -sworkingVersion Test.java will check out the most recent version of Test.java whose state attribute is "workingVersion".

It is a good idea to set the state attribute when you are checking in multiple files that "go together". For example, suppose you are writing a program that involves two files: Test.java and SymTab.java, and you've gotten to a point where the program works, but is incomplete. You might want to check in the two files with the same state (e.g., "Working1") so that you can easily retrieve this working version. If you don't use the state variable, and you make some changes to each of the source files (checking in each file individually after each change), it will be difficult to figure out which previous versions of the two files "went together" to give you a working program.

Viewing the Log History

To see all of the log messages that have been entered for a file when it has been checked in, use the rlog command; e.g., to see the log messages for Test.java, type: rlog Test.java

You can also have RCS put the log messages in the file itself by putting the text: $Log$ in the file. This is normally done inside a comment (otherwise, for programs, it will cause compiler errors). For example, you could start your program as follows:

and when the file is checked out, the $Log$ will be replaced with the actual log history (and, since the line containing $Log started with a space and a star, all of the lines of the log history will also start with a space and a star).

Group Projects

RCS can be useful if multiple people want to work on a project. The idea is to use one directory just for RCS, and for each person to do their actual work in their own directory. RCS prevents simultaneous changes being made to a file as follows:

Suppose one person checks out a file using the -l flag (i.e., with the intention of editing the file, not just looking at it), and then moves the checked-out file to their own directory to work on it. Now suppose another person decides to edit the same file, and so tries to check it out using the -l flag. RCS will complain that the file is already locked (by the first person), and will not permit the second person to check out the file. That's a good idea, because it prevents both people from working on the same file at the same time.

If the second person really wants to check out the file (for writing, not just for reading), they can break the lock by typing:

RCS will ask for a reason for breaking the lock, and will send that reason in an e-mail message to the person who held the lock.

How RCS Works

RCS works by saving the most recent version of each file, plus, for each previous version, information about how to edit the file to "go back" one version. So for example, if the most recent version is revision 1.4, and you ask for revision 1.2, RCS will apply one set of edits to get revision 1.3 from revision 1.4, and then will apply a second set of edits to get revision 1.2 from revision 1.3.

This means that retrieving recent versions (which is the most common operation) is very fast, while retrieving old versions (a less common operation) is slower.

More Information on RCS

You can find out more about RCS by typing one of the following: 

    man rcs
    man ci
    man co

You can also find out about a more sophisticated revision-control system called CVS by reading the document prepared by Jonathan Ledlie in: 

    ~ledlie/public/html/CVS_Example.doc
(You will need to logon to an NT machine and use Microsoft Word to look at the document.)