How to use rcs – a tutorial

In an earlier post, I introduced “rcs” and indicated that I intended to provide a tutorial on how to use the package of commands.  This post will be that tutorial.  I shall explain how to use it for the kind of simple use an individual linux user might have.  I shall illustrate that with a shell script.

Hello world

Our simple shell script will be to display the string “Hello world” with a few later modifications.  And we shall be using the “rcs” package of commands to keep track of the modifications.

I’ll call the shell script “hw”, because unix folk like short cryptic names.  So we can start by creating our first version of “hw” which we will save in the directory “bin” under our home directory.  Of course “bin” is an abbreviation of “binary”, and a shell script contains only text.  However, there is a tradition in unix to put commands in “/bin” and “/usr/bin” for system wide commands, and in “$HOME/bin” for an individual user’s commands.

I’ll start by creating the command file (there’s no need to include the comments that I added to a few lines).

% cd ~/bin   ### move to my bin directory
% touch hw ### create an empty file
% chmod a+x hw ### give the file execute permissions
% ls -l hw
-rw-r-xr-x 1 rickert users 0 Oct 27 13:45 hw

Note that lines starting with “% ” are the lines that I directly type; “% ” is set as my shell prompt.

We now have the file, but it is empty. Next we must add some shell commands to the file. Use your text editor of choice. I will be using “vi” (which is really “vim” in “vi” mode).

We start by adding the line:

echo "Hello world"

and we can now test that by typing the command

% hw
Hello world

Depending on your default shell, you might need to enter the command “rehash” before your shell sees the command.  You will also need your “bin” directory to be in your path, though that is a fairly common default in linux systems.

Checking into RCS

Our main aim was to show how to use rcs.  So let’s start by checking in our new script.  Although not strictly necessary, it is best to create a subdirectory named “RCS”.  You can do that with

% mkdir RCS

I already have that directory, so I had no need to create it.  Now that the directory is created, we can check in our new command with:

% ci hw
RCS/hw,v  <--  hw
enter description, terminated with single '.' or end of file:
NOTE: This is NOT the log message!
>> .
initial revision: 1.1

You will be prompted for a description of the file.  Just enter “.” on a line by itself when done.  I entered “.” because I did not want to bother with a description.

Next, we can list the file and its RCS archive.

% ls hw RCS/hw*
ls: cannot access hw: No such file or directory
-r-xr-xr-x 1 rickert users 199 Oct 27 14:06 RCS/hw,v

Well, oops. The script “hw” no longer exists. However, its archive “RCS/hw,v” does exist. That is one of the effects of checking in a file. The original file disappears. I can fix that with

# co hw
RCS/hw,v  -->  hw
revision 1.1
% ls -l hw RCS/hw*
-r-xr-xr-x 1 rickert users  19 Oct 27 14:17 hw
-r-xr-xr-x 1 rickert users 199 Oct 27 14:06 RCS/hw,v

and now both the shell script and the RCS archive exist.  Notice, however, that the shell script is now a read-only file.

I could have checked in the file using

% ci -u hw


% ci -l hw

The first version checks it in, then checks it out unlocked.  That way “hw” will be read-only.  The second version checks it in, then checks it out locked.  That will leave “hw” a writable file, with the assumption that we want to make further changes.

Since we do want to make further changes, we can now go ahead and check it out locked:

% co -l hw
RCS/hw,v  -->  hw
revision 1.1 (locked)
% ls -l hw RCS/hw*
-rwxr-xr-x 1 rickert users  19 Oct 27 14:24 hw
-r-xr-xr-x 1 rickert users 212 Oct 27 14:24 RCS/hw,v

Let’s now proceed to make some changes.

It is usually a good idea to begin a shell script with an interpreter line.  So I will add that and a comment.  I will insert the following two lines at the beginning of the file:

#! /bin/sh –
### script to print “Hello world”.

And now we can compare our current version with the previous version:

% rcsdiff hw
RCS file: RCS/hw,v
retrieving revision 1.1
diff -r1.1 hw
> #! /bin/sh -
> ### script to print "Hello world".

or, you might prefer

% rcsdiff -u hw
RCS file: RCS/hw,v
retrieving revision 1.1
diff -u -r1.1 hw
--- hw  2012/10/27 19:06:46     1.1
+++ hw  2012/10/27 19:29:34
@@ -1 +1,3 @@
+#! /bin/sh -
+### script to print "Hello world".
echo "Hello world"

Either way, the difference between the current version and the previous version is displayed.

And now, let’s check in that updated version:

% ci -l hw
RCS/hw,v  <--  hw
new revision: 1.2; previous revision: 1.1
enter log message, terminated with single '.' or end of file:
>> .

That has updated the RCS archive, which now has both versions.  I could check out either version if I wished.

Adding RCS version information

Let’s make one more change.  I will add the line

### $Id$

near the beginning of the file.  The shell sees that as a comment, because it starts with “#” (the shell comment character).  But the “rcs” commands see the “$Id” part as a special keyword.  So let’s check that in.  This time we will leave it unlocked since I am not planning any more changes.

% ci -u hw
RCS/hw,v  <--  hw
new revision: 1.3; previous revision: 1.2
enter log message, terminated with single '.' or end of file:
>> .

We can type out the content of the file, to see what that did:

% cat hw
#! /bin/sh -
### $Id: hw,v 1.3 2012/10/27 19:39:31 rickert Exp $
### script to print "Hello world".
echo "Hello world"

As you can see, that “$Id” keyword has now been expanded to contain the version number.

A few more commands

Here are some other commands that you can experiment with, to see what they do:

% ident hw
% rlog hw
% rcsdiff -r1.1 -r1.2 hw

This was intended as an introductory tutorial.  I hope it is enough for you to see how the “rcs” package could be useful.  The “man” pages for “rcs” provides information on some of the other things you can do.


Tags: ,

About Neil Rickert

Retired mathematician and computer scientist who dabbles in cognitive science.

2 responses to “How to use rcs – a tutorial”

  1. ytd2525 says :

    Reblogged this on ytd2525.


%d bloggers like this: