Aerospace Software Ltd.

RCS Howto

Mandrake 10.0

Scope

Albert Einstein said: "A thing should be as simple as possible, but no simpler".
RCS fits that description.

This guide explains how to use RCS to easily manage the configuration files on a server. Anyone who ever had to configure a mail system ended up with configuration files like this:

main.cf
main.cf.good
main.cf.bad
main.cf.orig
main.cf.almostworks
main.cf.fschkup
...

RCS is a very simple, no-nonsense, yet powerful revision control system and is ideal for ad-hoc use to keep control of pesky configuration files, web sites, small programming projects, documents and the like. It is great when there is only one person working on something and can help you keep your sanity when you have to configure Postfix or Apache.

The really nice thing about RCS is that you don't have to install anything, or configure anything - it just works - every Linux/Unix system I ever used has it installed by default.

RCS has been around since before the dinosaurs and it has good manual pages, but they don't really tell you how to use the system - this guide should fill that gap.

Getting Started

The easiest way to use RCS is on a per directory basis. Say you are in /etc/postfix, then all you have to do is create a sub directory called RCS:

cd /etc/postfix
mkdir RCS

Now you can check all your files in:

ci -u -t-Baseline *

The -u parameter will check the files out again, which is normally what you want to happen. The -t- parameter is only used the very first time to supply a baseline comment for each file checked in. This is the only parameter with two dashes.

That's it, all your files are now safe and you can edit them and go crazy, knowing that you can always check the previous version out again if you screw up.

Important Trick

I frequently found myself forgetting to check a change in, then when I come back to that directory, I lock the head version and overwrite my last working copy... or I modify a file and then can't check it in since it wasn't locked... Bah! Humbug!

If you are in a situation where there is always only one person at a time working on a subsystem, then you can make a nice simplification:

rcs -U *

That is a VERY important trick. It suppresses RCS file locking.

Now you don't have to worry about file locking anymore - you just go to the directory concerned, modify a file and check the change in. If you forget to check a change in - well, some other day when you get back there and change the file again, you may remember to check it in.

Using RCS

So, how do you use RCS?

Checkin

You modified a file and want to check the change in:

ci -u filename

You will be prompted for a description of the change - be verbose - it is for your own benefit.

To check in a bunch of files:

ci -u -mShortMessage *html
ci -u -m"Very verbose message" *html

That way you can type the message on the command line once only.

If you forget the -u option, then the file will disappear - it will be in the repository, but when you reload Postfix or Apache, they may become very unhappy - to recover, just check it out explicitly: co filename...

No More Checkouts

If you used my abovementioned lock suppression trick, then you don't have to check things out. The only command that you ever need to use is ci -u filename, unless you made a mistake and want to restore a previous version.

Handling Screw-ups

Well, that is what using RCS for configuration files is all about isn't it?

If you screwed up and want to restore a previous version, how do you know which one to get? First of all check in the current version - even if it is bad. Then examine the log with rlog, finally check out the version you want and if you are happy with your new changes, check them in again:

rlog filename (to see which version to get)
co -r1.8 filename (to get version 1.8)
Edit the file and test till you are happy with it
ci -u -f filename (force the file into the head of the repository)

This is where all those very verbose messages that you meticulously typed in become very useful - otherwise, check out various versions and read them, until you find the correct one. That is the nice thing about a revision system - it works like a library.

Since you checked out an old version and you usually don't want to create a branch, you may have to force the file into the top of the repository using the -f option when you check it in. Keep things simple - avoid branches.

Referenced Documents

You only need to read four man pages to know all you need to know about RCS:

man ci
man co
man rcs
man rlog

Have fun!

Herman