UserPreferences

RcsIntro

1. 5-Minute Guide to RCS

1.1. Or: Basic RCS For Systems Administration

RCS isn't used much any more, with better SCM systems like CVS or Subversion being widely available. As a source control system, RCS is lousy--no network access, only a single shared working directory and repository, requires locking, has annoying command-line quirks. But like the proverbial ham sandwich, it's better than nothing. For example, there are times when one has a server that is not part of a source-controlled configuration management system but one still wants to maintain a history of changes to files. RCS is quick, ubiquitous and just adequate. Here are the basics of using it; I am not going to cover anything advanced, like locking or branching, since chances are slim you'll need those (and if you do, you should probably use a better SCM) and since I'm approaching it from the perspective of systems administration, I am going to assuming you're working as root.

1.2. The Check-out, Change, Check-in Cycle

This section is first because it's the most frequently used. See below for getting started using RCS.

Assuming you have a file being managed with RCS that you want to change, the first thing you have to do is check-out and lock the file: 
# co -l foo.txt
RCS/foo.txt,v  -->  foo.txt
revision 1.1 (locked)
done
Now you do your work on the file, whatever that is. Somewhere partly through, you want to review what you've changed, so you use the rcsdiff command: 
# echo bar >> foo.txt
# rcsdiff -u foo.txt
===================================================================
RCS file: RCS/foo.txt,v
retrieving revision 1.1
diff -u -r1.1 foo.txt
--- foo.txt     2006/06/08 22:13:48     1.1
+++ foo.txt     2006/06/08 22:16:15
@@ -1 +1,2 @@
 foo
+bar

Note that I used the -u option for the diff format; this uses what is called the unified diff format. I find it to be the most readable of the formats, but you could use other diff options (including, probably using something like colordiff). Also, depending on who ships the RCS and diff implementation, you might not have all the options you have with a more full-featured diff, like GNU diff.

It's a good idea to do a diff just before you check the file in, so you can see exactly what you've changed and won't forget to log it. So now check it back in: 
# ci -wwcooley -u -m'Added "bar"' foo.txt
RCS/foo.txt,v  <--  foo.txt
new revision: 1.2; previous revision: 1.1
done

This is where the options become non-obvious. Since we're working as root, any check-ins would normally be logged as having been done as root, which makes it less than useful for playing the blame-game. Instead, the -wwcooley option ensures the log message indicates that user wcooley made the change. Note that due to oddness in the way it parses command-line options, space between -w and username is not permitted.

The -u option releases the lock on the file (the file write-permissions are removed) but does not remove the working file, which is the default. (A really dumb default too.) Let me emphasize, since it's very confusing if you do not remember this: DO NOT FORGET -u.

Finally, -m provides the log message for the check-in. Describe here briefly what you've done. If you don't provide a message, it will open your $EDITOR (which might be /bin/ed) and allow you to type in a message. It's much easier to remember to provide one. Also note that the opening single-quote character follows the -m immediately. Same as the -w above--a space is not permitted and will resulting ci helpfully opening your editor for you.

1.3. Getting Started

The first thing to do is to create a subdirectory of the directory containing the files you want to manage called RCS. You don't have to, but if you don't, the revision-storing files (called, curiously enough, "RCS files") will be kept in the same directory as the file you're working on, which just makes for clutter and confusion. 
# mkdir RCS
The next thing you want to do is manage some files, so you do an initial check-in: 
# ci -u -m'Initial check-in' foo.txt
RCS/foo.txt,v  <--  foo.txt
enter description, terminated with single '.' or end of file:
NOTE: This is NOT the log message!
>> Test file
>> .
initial revision: 1.1
done

You're prompted for a description for the file, which may or may not be useful. You can add "-t-'description'" to not be prompted.

That's it. Now you've got to check the file back out and lock it and get to work.

Checking-in for the first time is sufficiently tedious that I have written a script to automate it. I have never found a use for the file description or an initial log message more interesting than "Initial check-in". I have written a litte script called [WWW]rcsinit that will create the RCS directory and perform the initial check-in in one fell swoop.

1.4. Who Changed What

Two other things you'll want to know are who changed the file and what did he change. We've seen a partial answer to the second question--the rcsdiff command shows us differences between versions of files. To compare two versions that have already been committed, however, we'll need to use the -r to specify the revision, twice probably! How do you know which revision you want? That's where we use rlog, to review log entries to see who made the change. Let say that in our sample foo.txt file, we want to know when we added the bar entry and what else we changed then. The rlog command lists log entries and lots of other details about the file: 
# rlog foo.txt

RCS file: RCS/foo.txt,v
Working file: foo.txt
head: 1.3
branch:
locks: strict
access list:
symbolic names:
keyword substitution: kv
total revisions: 3;     selected revisions: 3
description:
Test file
----------------------------
revision 1.3
date: 2006/06/08 23:24:06;  author: cooleyw;  state: Exp;  lines: +1 -0
Added baz
----------------------------
revision 1.2
date: 2006/06/08 22:17:56;  author: cooleyw;  state: Exp;  lines: +1 -0
Added "bar"
----------------------------
revision 1.1
date: 2006/06/08 22:13:48;  author: cooleyw;  state: Exp;
Initial check-in
=============================================================================
Well, clearly we added bar are revision 1.2. Now lets see what else we changed between revision 1.1 and 1.2: 
# rcsdiff -u -r1.1 -r1.2 foo.txt
===================================================================
RCS file: RCS/foo.txt,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- foo.txt     2006/06/08 22:13:48     1.1
+++ foo.txt     2006/06/08 22:17:56     1.2
@@ -1 +1,2 @@
 foo
+bar

Well, not much it seems--no other changes than adding bar.

1.5. Rolling Back

Reverting a change the easy way is not obvious and it does not seem to be expressly mentioned in the documentation. The process is basically:

  1. Check out the current version.

  2. Merge from the desired version to the working copy.

  3. Commit the changes. 

$ co -l <file>
$ rcsmerge -rPREVIOUS_VERSION <file>
$ ci -u -m"Rolled back to PREVIOUS_VESION" <file>

2. Trouble

2.1. Writable File Exists

Sometimes when attempting to check-out or lock a file, you receive a message such as: 
$ co -l foo
RCS/foo,v  -->  foo
revision 1.16 (locked)
writable foo exists; remove it? [ny](n):

This is caused either by it being left checked-out in a locked state or because it wasn't finally committed. You can more or less determine which by using rcsdiff foo to see if there are uncommitted changes: 

$ rcsdiff foo
===================================================================
RCS file: RCS/foo,v
retrieving revision 1.16
diff -r1.16 foo

Since there are no differences, the last checked-in version and the working file are the same and the file has simply been left checked out. In that case, you were just going to lock the working version, but it's already locked, so you can just get to work.

If there are differences, then it's a matter of judgement whether to guess what the other person (assuming it wasn't you who worked on it last) did (sometimes it's obvious) and commit for him (perhaps making a note in the log that the changes are not your own) or bug him to commit his changes.

NB: The RCS documentation has mentions here and there breaking locks. That applies to using it in a multi-user mode, which isn't generally how a group of sys admins, working with role accounts, would use it.