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

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:

See the man pages for more information.

Markus Kuhn

created 1997-11-21 – last modified 2005-07-05 –