Basic RCS commands

There are two commands that are used on a regular basis, ci ("check-in") and co ("check-out"). The following sections provide some tutorials on using the different options. The manual pages are the typically concise Unix manual pages -- but they are accurate. It is useful to have the manual pages in front of you as you go through this to correlate the language in the manual with the examples that follow.

Definitions

It is time to explicitly define the terminology. It is straight-forward, although somehow confusion arises when actually doing things.

Delta

Revision

A `delta' or revision is created everytime you check a file back into RCS. The differences between the revision you are checking in and the previous revision are calculated. The revision you check in is given a unique revision number so you can retrieve it later. These differences are the `delta'.

Check in

When you are finished with a set of changes, you check the file back into RCS using the ci command. To be able to check something in, you must have locked the file first or you must be creating the RCS file for the first time.

Check out

You check a file out from RCS when you want to use it. You can either check a file out as locked or unlocked. You can get particular revisions of the file but by default you get the most recent revision. When a file is checked out, certain keywords are filled in.

Locked

Unlocked

Locked and unlocked are the two ways you can check out a file. A file checked out unlocked will not have write permission on it. If you intend to change a file (i.e. edit the file) then you should check it out locked. Only one person at a time may have a lock on a file, this prevents simultaneous updates. If you want to compile the file, search for something, print it or anything else that does not involve changing the file, you should check it out unlocked.

Revision Numbering

Each time you check a file into RCS, it is assigned a unique revision number (among other things). RCS attempts to maintain a tree of revisions. Usually (99% of the time) it is just a straight tree without any branches. Knowing or understanding the number scheme is not that important, so skip the next paragraph if you are not interested in such arcane knowledge. The main trunk of the tree has numbers with two fields (like `1.1' or `2.3'). Each branch from the main trunk has an additional two fields suffixed to the version it branched off from. For example if you created a branch from revision `2.3' it would initially be called revision `2.3.1.1'. Branches can sprout further branches in which case an additional pair of fields is added to the name (ad infinitum, although ad nauseum is more appropriate because you would be very sick and confused if you had branches with branches with branches). RCS automatically increments the second field of the last pair of numbers. If you want to change the first field (from 1.x to 2.0) you must do so explicitly.

Symbolic Names.

This is a very important feature for software configuration management and is the big win that RCS has over SCCS. It allows you to assign a word to stand for a particular revision of a file. Since some files require more changes than others, revision numbers never match up. Instead you assign a symbolic name, such as Version2, to the appropriate revision of each file. Then you can use the symbolic name Version2 to refer to the sources that make up the second version of this program.

Soft (symbolic) Links

Soft links are a method that Unix uses to reference another file or directory. They are created with the command `ln -s orig-file symbolic-name'.

Check out

Once a file is under RCS control, you can get access to it for either reading or writing. If you only intend to print the file, compile it, search for something, etc, you should check it out unlocked. If you want to change the file, check it out locked. Usually, just check a file out unlocked.

To check out a file without a lock, just say

co test.c

this retrieves the most recent revision of the file (obtained from `RCS/test.c,v') and deposits it in your current directory. The access permission on the file is read only. This is a reminder that the file is not locked, and prevent users from changing the file (Note: you could do `chmod u+w file.c', but in that case why not just check it out locked?).

To check out a file with a lock:

co -l test.c

the `-l' stands for "locked". When a file has been checked out locked, you are given write permission. RCS may say `File locked by somebody', in which case one must negotiate with that person because they have the file locked.

There are many ways to specify which revision of a file to check out (either locked or unlocked). You can specify a specific revision number, symbolic name, date, state or author.

`revision'

One explicitly indicates the exact revision desired. Read about rlog to help you select which revision you want.

co -r1.3 test.c

retrieves revision 1.3 of the file `test.c'. If multiple files are specified,

co -r1.3 test1.c test2.c test3.c

then RCS would retrieve revision 1.3 of each of the files, probably not what is wanted.

`symbolic name'

Use the symbolic name instead of the explicit revision number.

co -rVersion_1 test.c

Use of symbolic names is especially useful for a group of files.

co -rVersion_1 test1.c test2.c test3.c

gets the appropriate revision of the three files needed to create Version_1.

`date'

You can use the `-d' flag to specify a date. The retrieved revision is the most recent revision of the file older then the given date. co is very smart about determining what time you actually meant. The following forms are all understood:

co -d"22-April-1982, 17:20-PDT" test.c
co -d"2:25 AM, Dec. 29, 1983" test.c
co -d"Tue-PDT, 1981, 4pm Jul 21" test.c

Note the use of quotes to keep the date as one argument. If a time is not completely specified, then default values are assigned.

`state'

It is possible to assign a word that indicates the state of each revision. By default, this is Exp for experimental. The other common state is Rel for released. If you specify a state, such as:

co -sRel test.c

then RCS finds the most recent revision with state Rel and checks it out. If you had the following revisions, each with the given state then RCS would check out revision 1.11, skipping revisions 1.12 and 2.0.

Revision

State

1.10

Rel

1.11

Rel

1.12

Exp

2.0

Exp

`author'

Retrieves the latest revision which was checked in by the user with the given login name.

co -wpete test.c

gets the latest revision by pete. Whereas

co -w test.c

gets the latest revision checked in by you.

All of these options can be combined. The first revision that matches all the requirements is checked out. If there are no revisions that match, then nothing is checked out and an error message is printed. The -l option can also be used with the above to check out the selected revision with a lock. Usually, only the -r option is used, the others involving author, date, state are marginally useful.

To take a quick look at a revision, the -p for `print' option specifies the file be sent to the screen. This is useful if you want a quick look at an old revision of the file, but don't want to overwrite the existing version. All the above flags except -l are available.

Keyword Substition

Frequently it is useful to maintain some information in a source file such as who recently made a change and when that change occurred. A further refinement is to arrange for this information to be compiled into the code. This is used to determine exactly which versions of a file went into making an executable if there are bugs in the executable.

RCS will automatically add text into your source when certain keywords present. Keywords are of the form $Keyword:$ where everything between the : and $ is replaced with the RCS values.

Keywords and their values are:

$Author:$

The login name of the user who checked in the revision.

$Date:$

Date and time the revision was checked in.

$Header:$

A standard header containing the RCS file name, the revision number, date, author and state. This is frequently embedded in a text string so that object files can be correctly identified. For example:

#ifndef lint
static char RCSid[] = "$Header:$";
#endif

It is surrounded with the #ifdef lint ... #endif because lint would complain about an unused variable RCSid and about RCSid being multiply defined. The variable is static so it will be unique to this object file and not available to any others. Upon being expanded it looks like:

static char RCSid[] =
"$Header: test.c,v 1.2 87/2/4 09:39:07 pete Exp $";

This incorporates all the other information that keywords give except for the log message.

$Locker:$

The login name of the user who locked the revision (empty if not locked).

$Log:$

The log message supplied during checkin, preceded by a header containing the RCS file name, the revision number, the author and the date. Existing log messages are not replaced (unlike the other text substituted for keywords). Instead, the new log message is inserted after $Log:$. This accumulates a history of all the changes in the source file.

$Revision:$

The revision number assigned to the revision.

$Source:$

The full pathname of the RCS file.

$State:$

The state assigned to the revision with rcs -s or ci -s

The following example includes all the above:

/*
 * $Author: pete $
 * $Date: 87/04/02 14:14:52 $
 * $Header: test.c,v 1.2 87/04/02 14:14:52 pete Locked $
 * $Locker: pete $
 * $Log:	test.c,v $
 * Revision 1.2  87/04/02  14:14:52  pete
 * Misspelt Revision keyword.
 * 
 * Revision 1.1  87/04/02  14:13:27  pete
 * Initial revision
 * 
 * $Revision: 1.2 $
 * $Source: /u0/pete/src/doc/RCS/test.c,v $
 * $State: Exp $
 */

The above are placed in a comment block, because that is the typical usage. The keywords substitutions occur wherever a keyword is located in the file. This keyword substition occurs at check out time, not at check in time.

Check in

To be able to check in a file, you must first have checked it out locked or it must be the initial (first time) check in. When you check a file in, you are prompted for a log message which should be one or two lines long (although it depends on how many changes you've made). The intention of the log messages is to remind yourself and inform others what the significant differences are between this revision and the previous revision. You terminate the log message with a . as the only character on a line or by entering ^D (EOF).

If the file has never been checked into RCS, you are prompted for an initial message which should be some descriptive text describing what the file is for. This has limited usefullness since the text cannot be included in the source file, and the source file should already be documented. In other words, it is acceptable to leave this empty. You terminate the initial message the same way as the log message: with a . on a line by itself or by entering ^D (EOF).

If you intend to edit the file immediatly after checking it in, use the -l flag (lock), which checks the file out with a lock immediatly after checking it in. If you want the file to stick around in the current directory, use the -u flag (unlock) to have it checked out without a lock immediatly after the check in.

If you are checking in a group of files and want the same log message for each file, try:

ci -m"Renamed variable v to velocity." test1.c test2. test3.c

and RCS will use the `Renamed ... velocity.' for the log message for all the files.

If you want to give a symbolic name to this revision, now is the best time to do so.

ci -NVersion_1 test1.c test2.c test3.c

You are limited to alphanumeric characters, -, and _. Each of the above files then has Version_1 as the name for the revision. This is used in configuration management to allow multiple versions of software to exist. You can also use this in a similar manner to maintain multiple versions of your programs. RCS enforces the restriction that a single name can refer to only one revision. A single revision can be known by more than one name. You can use the rcs command, described later, to assing symbolic names after the fact.

The state of the revision is assigned at this point. By default it is set to Exp for experimental. To change the default value, you must use the -s flag.

ci -sReleased test1.c

You can also give the revision number when you check in a file. Usually you just use RCS's default rules. Occasionally you want to increment the main branch number, say from 1.23 to 2.0, then you would type in:

ci -r2.0 test1.c

and the new revison would be 2.0. The specified revision number must be greater than any other revision number. In the above case, you could not check it in as -r1.13 even if there was no revision 1.13.

Sooner or later, you are going to attempt to check in a file that you have not locked. Theoretically, this should never happen, since you should always do a co -l before editing a file.

You need to find out if the file is already locked by somebody else or is not locked at all. If it is locked by someone, there are two choices: if you have added changes on top of the other persons and your changes are much smaller then the other persons, then let the other person check the file in; if the other person's changes are less than your changes, then have the other person do a rcs -u filename to unlock the RCS file and then you do a rcs -l filename to lock the file. You can then check the file in with ci.

If the file is not locked, then simply do a rcs -l filename to lock the file and then check it in using ci. However, be careful somebody else has not added a revision between the time you got your version of the file and the time you check it in. You can use the rlog command to see anything anybody else has done or you can use rcsdiff to compare the your revision of the file with the current RCS revision.

Go to the first, previous, next, last section, table of contents.