The ECN No Name Newsletter is no longer being published. This is an archived issue.
[previous article] [next article]
At one point or another everyone is faced with the prospect of throwing away an old version of something in favor of a newer version or deciding when to replace the last archived version of a project with a newer archived version. These decisions of when and what to keep can often pose severe problems especially if the wrong set of files is not archived. One package to help manage these revisions is the Revision Control System (RCS).
RCS is suitable for storing and retrieving any sort of text documents -- source code, papers, lists, etc. Each file and all its subsequent revisions are stored by RCS and can be later recalled. Additionally, RCS can be used by a team of people to serialize access to working files, making sure that no person over writes the work of another.
Be aware that RCS is a robust library system. This article can in no measure do justice to, or cover all, its myriad features. The intent is to give an introduction to RCS and describe its basic workings, not to be comprehensive in treatment. In some cases the facts have been bent or glossed over in order to present a simplified and explicable view of the package.
RCS is composed of more than six programs including: ci, co, rcs, rcsdiff, rcsmerge, and rlog. Of these ci and co store and retrieve revisions and are most crucial to the use of RCS. They form the basis of the user's interaction with RCS.
Each file that is archived is stored in a file with the same name as the original except with a ",v" at the end. So, for example, if one were to store the file main.c under RCS, the subsequent file generated to store main.c and its revisions would be named main.c,v. RCS first attempts to place these files in the ./RCS directory, i.e. the subdirectory named RCS under the directory the file is in. If it cannot find a subdirectory named RCS, it places the ,v file in the same directory as the source.
There are two main concepts to understand when dealing with RCS. The first, and most crucial for the single user of RCS, is that of "version". RCS associates with each revision a version number. The initial version is numbered 1.1 and subsequent versions continue 1.2, 1.3... In addition to storing a single set of revisions, RCS can also deal with multiple sets of revisions. Say, for example, that after working on the 1.x set of revisions, one decides to begin a completely different line. This line can be named the 2.x line and kept separate from the 1.x line. In this way, changes to both the 1.x and 2.x lines of versions can be kept and recorded.
The other concept, important for group projects, is that of a "locked version." When a version is removed from RCS, it is either removed "unlocked" or "locked". While any number of authorized users may check out a version in the unlocked state, only one user may check out a version in the locked state. Furthermore, only locked versions can be returned to the RCS store. If the file is locked, only the person who set the lock can save the file because RCS will not allow an unlocked version to be checked in. This feature prevents people working on a group project from overwriting each other's work because only one person has a modifiable copy of a given version (i.e. a locked version) at a given time.
Consider the following session:
[orchestra:]ls
article
[orchestra:]ci article
article,v <-- article
initial revision: 1.1
enter description, terminated with ^D or '.':
NOTE: This is NOT the log message!
>> First Draft of ECN Newsletter Article
>> .
done
[orchestra:]ls
article,v
In this case, ci has saved the initial version of the file. The file was removed from the directory and the RCS storing file, article,v, was placed in the directory. Now consider the following session:
[orchestra:]ls
article
[orchestra:]mkdir RCS
[orchestra:]ci article
RCS/article,v <-- article
initial revision: 1.1
enter description, terminated with ^D or '.':
NOTE: This is NOT the log message!
>> First Draft of ECN Newsletter Article
>> .
done
[orchestra:]ls
RCS
[orchestra:]ls RCS
article,v
In this case the same procedure was followed, only a subdirectory RCS was created in the directory containing the file article. This time when the ,v file was created it was placed in the RCS subdirectory, keeping the main directory clear. While this is not so important for a one file project, it is quite convenient for multi-file projects.
The following example shows how one would go back and make changes to the now archived file. This involves checking the file out of RCS in a locked condition and then checking it back in. [orchestra:]ls RCS [orchestra:]co -l article RCS/article,v --> article revision 1.1 (locked) done [orchestra:]ls RCS article [orchestra:]vi article ... Changes are made to article ... [orchestra:]ls -Flas RCS total 4 1 drwxr-xr-x 2 song 512 Feb 27 17:47 ./ 1 drwxr-xr-x 3 song 512 Feb 27 17:47 ../ 2 -r--r--r-- 1 song 1775 Feb 27 17:47 article,v [orchestra:]ls -Flas total 4 1 drwxr-xr-x 2 song 512 Feb 27 17:47 ./ 1 drwxr-xr-x 3 song 512 Feb 27 17:47 ../ 2 -rw-r--r-- 1 song 1514 Feb 27 17:47 article [orchestra:]ci article RCS/article,v <-- article new revision: 1.2; previous revision: 1.1 enter log message: (terminate with ^D or single '.') >> Addition of several basic examples..... >> . done [orchestra:]ls -Flas RCS total 4 1 drwxr-xr-x 2 song 512 Feb 27 17:48 ./ 1 drwxr-xr-x 3 song 512 Feb 27 17:48 ../ 2 -r--r--r-- 1 song 1917 Feb 27 17:48 article,v [orchestra:]ls RCS
There are several important things to note about this example. First is that RCS has again removed the working file from the directory as it was checked in. Also notice that the command co -l was used. The -l flag tells RCS to lock the version on checkout. By default (i.e. by just using co) RCS will checkout an unlocked version. It has also automatically logged this as version 1.2, up from version 1.1. The other thing to notice is the space used. The file article is 1514 bytes and the RCS file storing it, before the check in of the the new version is 1775 bytes. After the check in (and implicit storing) of a whole new version, the RCS file is only 1917 bytes. So while the archive of the initial version takes slightly more space than the file itself, subsequent revisions take much less space to store.
The whole point, of course, is to be able to retrieve past versions of a file. The following example removes version 1.1 from the RCS store, even though version 1.2 was the most recent.
[orchestra:]ls
RCS
[orchestra:]co -r1.1 article
RCS/article,v --> article
revision 1.1
done
[orchestra:]ls
RCS article
The -r option tells RCS to remove the version number given. So with this commands, any version of the file previously saved can be restored.
While the above examples show the basics of the checking in and out of files, there are several other convenient features to RCS which, while not essential to RCS's use, make it much nicer to use. Illustrated below is how to check in a file and immediately (in the same command) check out a locked copy of the new version. This is especially convenient when one is simply interested in storing something and then continuing to work on a given file.
[orchestra:]ls
RCS
[orchestra:]co -l article
RCS/article,v --> article
revision 1.2 (locked)
done
[orchestra:]vi article
[orchestra:]ci -l article
RCS/article,v <-- article
new revision: 1.3; previous revision: 1.2
enter log message:
(terminate with ^D or single '.')
>> Addition of locking explanation.
>> .
done
[orchestra:]ls
RCS article
[orchestra:]vi article
[orchestra:]ci article
RCS/article,v <-- article
new revision: 1.4; previous revision: 1.3
enter log message:
(terminate with ^D or single '.')
>> Final first version
>> .
done
[orchestra:]ls
RCS
Here, the file was checked out, modified and checked back in with the -l option. This forced RCS to check in the new version and check it out again locked. This one command takes the place of a ci followed by a co -l.
[orchestra:]ls
RCS
[orchestra:]co -l article
RCS/article,v --> article
revision 1.5 (locked)
done
[orchestra:]ci -r2 article
RCS/article,v <-- article
new revision: 2.1; previous revision: 1.5
File article is unchanged
with respect to revision 1.5
checkin anyway? [ny](n): y
enter log message:
(terminate with ^D or single '.')
>> First Version of 2.x
>> .
done
[orchestra:]ls
RCS
In this example, version 2.x was created by using the -r option to the ci command. The argument to -r specifies the number to use for the checked in version. A specific number consisting of both a major and minor version number can be used (ex: 2.3) or simply a major version number. In the previous case, only a major version number was used. Since this was the first 2.x version, version 2.1 was created. RCS will automatically checkout the latest version of a file if given no other instructions, so the 2.1 version is now the default RCS version.
RCS is a powerful utility. One can keep and control old versions of a project and organize group access to files with ease. However, due to the flexibility of RCS, it is impossible to describe all of its features in one short article. More can be learned about RCS by reading the online manual pages or attending an ECN short course devoted to RCS.
HTML