O'Reilly Network: The Five-Minute RCS Tutorial - Automating System Administration with Perl

This quick tutorial will teach you everything you need to know to use the Revision Control System (RCS) for system administration. RCS is useful for applying version control to all of your system files. It has considerably more functionality than we’ll discuss here, so be sure to take a look at the manual pages and the references at the end of this appendix if you plan to use it heavily. You may also be wondering why we’re bothering with RCS when more modern systems, such as Git and Subversion, exist. That’s a good question, and I’ll address it at the end of the tutorial. In the meantime, though, let’s get the RCS basics down; they’ll help with the explanation later.

RCS functions like a car rental agency. Only one person at a time can actually rent a particular car and drive it off the lot. The agency can only rent out a new car after adding it to its pool. Customers can browse the list of cars (and their features) at any time, but if two people want to rent the same car, the second person must wait for the car to be returned to the lot. Finally, car rental agencies inspect cars very carefully after they have been returned and record any changes that took place during the rental. All of these properties hold true for RCS as well.

In RCS, a file is like a car. If you wish to keep track of a file using RCS (i.e., add it to the rental lot), you must “check it in” for the first time:

$ ci -u inetd.conf

ci stands for “check in,” and the -u tells RCS to leave inetd.conf in place during the check-in. When a file is checked in (i.e., made available for rental), RCS does one of two things to remind the user that the file is under RCS’s control:

Deletes the original file, leaving only the RCS archive file behind. It sometimes distresses new users of RCS when the file seems to disappear after being checked in, but in fact the data has just been squirreled away in its archive file. This archive file is usually called filename,v and is kept either in the same directory as the original file or in a subdirectory called RCS (if the user creates it). You must protect the RCS directory and archive file (using filesystem permissions) at least as strongly as the original file.
If -u is used (as in our earlier command), it checks the file out again, leaving the permissions on the file set to “read-only.”

To modify a file under RCS’s control (i.e., rent a car), you first need to “check out” (co) that file:

$ co -l services

The -l switch tells RCS to “strictly lock” services (i.e., do not allow any other user to check out services at the same time). This lock is respected only by RCS; the file is not actually locked using filesystem capabilities (ACLs, attributes, etc.). Other switches that are commonly used with co include:

-r <revision number> to check out an older revision of a file
-p to print a past revision to the screen without actually checking it out

Once you are done modifying a file, you need to check it back in using the same command you used to put the file under RCS’s control (ci -u filename). The check-in process stores any changes made to this file in a space-efficient manner.

Each time a file that has been modified is checked in, it is given a new revision number. At check-in time, RCS will prompt you for a comment to be placed in the change log it automatically keeps for each file. This log and the listing of the current person who has checked out a file can be viewed using rlog filename.

If someone neglects to check her changes to a particular file back into RCS (perhaps having gone home for the day) and you have a real need to change the file yourself, you can break that person’s lock using rcs -u filename. This command will prompt for a break-lock message that is mailed to the person who owns the lock.

After breaking the lock, you should check to see how the current copy differs from the RCS archive revision. rcsdiff filename will show you this information. If you wish to preserve these changes, check the file in (with an appropriate change-log comment), and then check it back out again before working on it. rcsdiff, like co example, can also take a -r <revision number> flag to allow you to compare two past revisions.

Table E.1, “Common RCS operations” lists some common RCS operations and their command lines.

Table E.1. Common RCS operations

RCS operation	Command line
Initial check-in of file (leaving file active in filesystem)	`ci -u` `filename`
Check out with lock	`co -l` `filename`
Check in and unlock (leaving file active in filesystem)	`ci -u` `filename`
Display version x.y of a file	`co -p``x`.`y` `filename`
Undo to version x.y (overwrites file active in filesystem with the specified revision)	`co -r``x`.`y` `filename`
Diff file active in filesystem and last revision	`rcsdiff` `filename`
Diff versions x.y and x.z	`rcsdiff -r``x`.`y -rx`.`z` `filename`
View log of check-ins	`rlog` `filename`
Break an RCS lock held by another person on a file	`rcs -u` `filename`

Believe it or not, this is really all you need to get started using RCS. Once you start using it for system administration, you’ll find it pays off handsomely.

Choosing RCS over CVS, Git, SVN, etc.

Given that there are modern version control systems available that are much cooler than RCS, why do I still suggest people learn and use RCS? The fact is that the newer systems (which I use for my own version control in other contexts) have a model that is not nearly as conducive for this specific sysadmin need as RCS.

With systems like CVS and SVN, the user checks out the file or files in question into a “working directory” from the central repository. Changes are made and then re-synced to the repository. Multiple people can check out the same files, and (if possible) all of their changes are automatically merged/reconciled when the file is returned to the repository. The Subversion documentation refers to this process as “copy-modify-merge.”

There are a few reasons why this model doesn’t mesh well with our usual sysadmin workflow around things like configuration files:

The presence of config files in a specific place in the filesystem is dreadfully important. /etc/passwd doesn’t do you any good if it isn’t in /etc or is stored in a special repository format. It is possible to force people to use /etc as the working directory, but that can be fraught with peril. RCS lets you simply keep your files in the live filesystem after they’ve been checked back in.
The copy-modify-merge approach often doesn’t jive with how sysadmins work. The notion that multiple people might be making concurrent edits to a configuration file that later will automatically be reconciled (without regard for how parts of that file might interact with other parts) is a very scary thought. Both CVS and SVN have at least some support for locking a file so others won’t edit it at the same time, but this runs contrary to the spirit of those systems. RCS only thinks in terms of locking, likely making it a better fit. If you need data to be concurrently edited, I’d suggest that using a database from which config files are generated is probably a better approach.
CVS and SVN are “directory-based”: they deal with directory trees that contain files. Git is content-based (it manages the data under source control). RCS is file-based.
Though the newer distributed version control systems allow for a certain amount of disconnected operation, using a centralized networked file repository for crucial files can sometimes get you into trouble. If your machine is off the net for some reason and you are trying to fix it, as long as you have your RCS repository and the RCS binaries you are in okay shape. But if you use a version control system that requires network access to get to the file you need to fix the lack of network access, you’ve got a problem. Git’s fully distributed model is better in this sense, but it has its own issues in this context.
In short, while CVS, SVN, Git and the rest of the pack of version control systems are probably much better at version control for most software development environments, RCS is better suited to managing system files.

References for More Information

ftp://ftp.gnu.org/pub/gnu/rcs has the latest source code for the RCS package (though it is available through most standard packaging mechanisms if it doesn’t ship with your OS).

http://cygwin.com is a source for an RCS package (and many, many other Unix-born programs). If you’d like to install RCS without requiring the entire Cygwin environment, there is a version available at http://www.cs.purdue.edu/homes/trinkle/RCS.

Applying RCS and SCCS: From Source Control to Project Control, by Don Bolinger and Tan Bronson (O’Reilly), is an excellent RCS reference.

http://www.nongnu.org/cvs and http://subversion.tigris.org are the places to go if you find you need features not provided in RCS. The next step up is either the Concurrent Versions System (CVS) or Subversion (SVN).

The next step up from CVS and SVN is the crop of relatively new distributed version control systems, such as git, mercurial, bazaar, and darcs. For more info, check out the article at http://en.wikipedia.org/wiki/Distributed_Version_Control_System.