GNU RCS Tutorial

The following examples will use the file our_file.txt. By default, version files (see section on version files) when initially checked-in (see section on checking-in) are placed in the same directory as the file being checked-in. To avoid clutter in your directory, an RCS subdirectory can be created to collect RCS files. If such a subdirectory exists, RCS will store all RCS files to the subdirectory rather than the same directory of the working file (see section on working file).

Create an RCS subdirectory with the following command:

$ mkdir RCS

To check-in our file to RCS, you would issue the command:

$ ci our_file.txt

RCS will respond with:

RCS/our_file.txt,v  <--  our_file.txt
enter description, terminated with single '.' or end of file:
NOTE: This is NOT the log message!
>> 

RCS displays where the working file is and where the RCS file is. In this example, the location of the RCS file is in the RCS subdirectory with the name of the working file with a comma and the letter v (,v) appended to the filename. A ,v is the default extension to RCS files. This behavior can be modified so that RCS looks for a different extension for RCS files (see section on extension option).

If there hadn't been an RCS subdirectory, then the RCS file would be placed in the same directory as the working file. The RCS file would still have a ,v appended to the name.

RCS then gives directions on how to submit a file description (see section on file description). After these directions an interactive prompt awaits the input for the description.

Upon initially checking-in (see section on check-in) a file, RCS requests a file description. The request is not for a revision log message, so do not describe the changes made or the current state of the initial revision. Instead, this is a request for a description (see section on file descriptions) of the file. The description has no functional purpose in RCS. The description serves only to describe the file to you and others. This can be helpful when files are given obscure, non-descriptive file names, or impracticcal and vague names like in this example.

Descriptions, as RCS requests, are ended with a single period (.), or an “end of file”. An “end of file” on most systems is issued by typing Ctrl D (^D). By “single”, the period or end of file should be the only character on the line. After entering a period a carriage return (on most systems enter or return) must be entered. A carriage return is not necessary after terminating the description with an end of file.

Here is a description entry for the initial revision of the example:

RCS/our_file.txt,v  <--  our_file.txt
enter description, terminated with single '.' or end of file:
NOTE: This is NOT the log message!
>> Our Example RCS Text File
>> .
initial revision: 1.1
done

Descriptions can also be entered as a command-line argument (see section on file description option).

Upon checking-in a file, RCS by default deletes the working copy (see section on working file) of the file. To view, compile or distribute the file enter the following to make a working copy of the file available:

$ co our_file.txt
RCS/our_file.txt,v  -->  our_file.txt
revision 1.1 (unlocked)
done

The file is now available but is unlocked (see section on unlocked) and therefore read-only. This is because the revision of the file would need to be locked (see section on locking). The file is actually unlocked, as RCS outputs above, and could have been checked-out with the more explicit check-out command:

$ co -u our_file.txt
RCS/our_file.txt,v  -->  our_file.txt
revision 1.1 (unlocked)
done

To check-out the file for editing, a request for a lock and a request for retrieval of a version must be made:

$ co -l our_file.txt
RCS/our_file.txt,v  -->  our_file.txt
revision 1.1 (locked)
done

The checking-in, checking-out and locking of a file can be done with a single check-in. This is combined into a single checking-in command:

$ ci -l our_file.txt
RCS/our_file.txt,v  <--  our_file.txt
new revision: 1.2; previous revision: 1.1
enter log message, terminated with single '.' or end of file:
>> Added another question.
>> ^D
done

In the examples so far, we have been checking-out, editing, checking-in and locking only the most recent version of the file in RCS. These are adequate skills for gaining the familiariarty and good habit of using version control. However, the benefits of using version control come from being able to have access to previous revisions of a file.

The most direct and simple method for retrieving revisions is to specify the revision number with the revision command-line option (-r). In the examples above, the revision was not specified in the RCS command but instead implied silently as a request for the most recent revision. However, after checking in the file the first time, the most recent revision of the file could have also been retrieved by specifying the revision with the revision option:

$ co -r1.1 our_file.txt

The revision command-line option can be combined with the check-out's locking option. So, the check-out and locking of the first revision done above could have been accomplished instead by combining the revision option with the lock option:

$ co -r1.1 -l our_file.txt

The lock option is actually able to take an argument in the same format as the revision option, allowing the above command to be shortened:

$ co -l1.1 our_file.txt

In the same vein, all these options are recognized by the check-in command. To check-in, check-out and lock the second revision:

$ ci -l1.2 our_file.txt

After making edits to the file, RCS can display the differences made to the working file. This is helpful to tell when a file has been edited since you last checked it out or to see the specific changes made to a file.

The name of the command is rcsdiff. rcsdiff takes the same options as the diff command. The general form of such a command is:

$ rcsdiff our_file.txt
===================================================================
RCS file: RCS/our_file.txt,v
retrieving revision 1.1
diff -r1.1 our_file.txt
1a2
> Which of it is ours?

The output of rcsdiff is the default output for the system's diff command. For this example, the output is the ed format.

Another feature desired by users of RCS besides general version control is the use of keywords. To utilize RCS keywords (see section on keywords) simply insert the keywords. For example, place the commonly Id keyword at the end of the file, accomplished by this shell command:

$ echo '$Id: tutorial.html,v 1.2 2005-04-06 02:15:14-04 ashawley Exp $' >> our_file.txt

When the file is checked-in and out, RCS will replace the keywords with their respective values:

$ ci -l our_file.txt
RCS/our_file.txt,v  <--  our_file.txt
new revision: 1.3; previous revision: 1.2
enter log message, terminated with single '.' or end of file:
>> Added Id keyword.
>> ^D
done

$ cat our_file.txt
This is our file.
Which of it is ours?
Do we agree to it?
$Id: tutorial.html,v 1.2 2005-04-06 02:15:14-04 ashawley Exp $

In the case of our example, checking the values of keywords is a simple task given the short length of the file. In the case of large files, finding keywords can become a painful task. Fortunately, an RCS command is able to retrieve the keywords from a file and display them:

$ ident our_file.txt
our_file.txt:
     $Id: tutorial.html,v 1.2 2005-04-06 02:15:14-04 ashawley Exp $

The log command can retrieve and display a bulk great amount of meta-information about versions for a file under RCS. Here is information of what we have done to our example text file with RCS:

$ rlog our_file.txt

RCS file: RCS/our_file.txt,v
Working file: our_file.txt
head: 1.3
branch:
locks: strict
access list:
symbolic names:
keyword substitution: kv
total revisions: 3;     selected revisions: 3
description:
Our Example RCS Text File
----------------------------
revision 1.3
date: 2003-05-27 03:11:54-04;  author: ashawley;  state: Exp;  lines: +1 -0
Added Id keyword.
----------------------------
revision 1.2
date: 2003-05-27 03:08:56-04;  author: ashawley;  state: Exp;  lines: +1 -0
Added another question.
----------------------------
revision 1.1
date: 2003-05-27 03:07:51-04;  author: ashawley;  state: Exp;
Initial revision
=============================================================================

The response of the log command highlights the file's information including the path of the RCS file (see section on RCS file), the description (see section on file description), the number of revisions (see section on revisions) and information about revisions including check-in date, author and the log submitted for the revision.

This tutorial covered the fundamental operations of version control with RCS. The total functionality offered by RCS far surpasses the coverage of the tutorial in this section. However, familiarity with just these routine version control tasks leverages many of the benefits of version control. From here, other concepts and features of RCS can be easily learned and understood.

Other features and concepts skipped include branches, merges, keyword subsitution options, version names, file initilization options, localizations and the realm of multiple author usage and administration. However, these operations are so rarely used or needed for so few tasks that they need not complicate an introductory tutorial.