How to use RCS, and why

RCS is a freely available file revision control system that was developed by Walter Tichy at Purdue University in 1982. It is now distributed by the Free Software Foundation and maintained by Paul Eggert.

RCS can be used to coordinate groups of people working on common files as well as by yourself alone in your own private projects. You should know and use RCS, because it allows you to

• get easy access to the latest version of a file that is being worked on by many people;
• get easy access to all previous version of files to
  • undo unfortunate modifications,
  • reconstruct the source code of old released file versions;
• get easy access to a list of changes (diff) that have been made by various people to your files
• avoid that two people independently make non-causal changes at the same time on the latest version of a file and thereby create two different latest versions.

Using a revision control system is one of the most elementary good practices of software engineering, and this alone should be reason enough for getting familiar with RCS.

Is RCS right for your project? RCS offers version control only for individual files and provides no support for remote access. Its facilities for collaborative work are quite restricted. It has no notion of directory trees and changes to them (e.g., copying or renaming files and directories). For any project that consists of more than a very small number of files or that has subdirectories or multiple people working on it, RCS is no longer considered an appropriate choice. Have a look at Subversion (manual) instead!

RCS consists of the four frequently used shell commands ci, co, rlog, and rcsdiff, as well as of the rarely needed commands rcs, ident, rcsclean, and rcsmerge.

Read man rcsintro now to get a quick overview of the system. Basically all you have to remember is

ci -u filename

Upload (check in) your latest changes back into the database, release your lock, and keep an unlocked read-only working file. (Without option -u, ci would remove your working file and you'd have to use co to get it back.)

ci -l filename

Upload your latest changes back into the database, but do not release the lock and keep a locked writable working file.

co filename

Retrieve (check out) an unlocked latest-version read-only working file from the database.

co -l filename

Retrieve a locked latest-version writable working file from the database. Only one user can have such a writable locked version at a time.

rlog filename

Show the revision history of a file.

rcsdiff -u filename

Show the differences between your working file and the latest revision in the database. (Option -u selects the nicer unified diff output format.)

The primary owner of a file creates a subdirectory RCS/ in the directory where her files to be managed are located. In this directory, the RCS commands will keep a filename,v database file associated with your working file. This database file will contain the entire revision history of one of your files. If you want to share with others in the Unix group sec-grp some files, then create the subdirectory with say

  user1$ cd ~/papers/IEEE98/
  user1$ mkdir RCS
  user1$ chgrp sec-grp RCS
  user1$ chmod g+w RCS
  user1$ ci -u ieee98.tex fig1.fig fig2.fig

All other users put in their working directory instead of the RCS/ subdirectory a symbolic link named RCS that references to the common RCS subdirectory created above:

  user2$ ln -s ~user1/papers/IEEE98/RCS
  user2$ co RCS/*

The Unix group sec-grp includes all Cambridge Security Group PhD students and was created to allow easy sharing of RCS managed files.

And some more tips:

• Add to your .bashrc file the line RCSINIT=-zLT such that local time is used by rlog.
• Have a look at the Emacs support for RCS, which allows you to check-in and check-out the currently edited file simply by pressing C-x v v. See the emacs manual chapter on Version Control for more info.

See the man pages for more information.

Markus Kuhn

created 1997-11-21 – last modified 2005-07-05 – http://www.cl.cam.ac.uk/~mgk25/rcsintro.html