DUE: NEVER

TURNIN:  NOTHING

ASSIGNMENT:

PURPOSE:  The purpose of this laboratory is to introduce and demonstrate a simplified use of RCS in a unix/Linux environment.

When working with computers, it becomes a harsh reality that somewhere, somehow, someday you're going to work with code and source files. During code development, source files are modified very heavily, increasing the odds that someone will introduce bugs into the code that could potentially cause the application being written to crash or quit working. Using traditional coding techniques, the only version of the code that exists is the one that was last modified, even if the error which caused the failure was introduced months before. Obviously if incremental copies of every revision of code were saved, the problem could be isolated and repaired or development could be resumed from the last known working copy. Instead, debugging and finding the error can cost many precious hours under deadline conditions. Revision Control System (RCS) incorporates a "smart" system of saving versions of code while under development so that an error can be recovered from any modified version of the software currently under version control. In any discussion about version control techniques, it is necessary to understand the modification cycle of source files and projects.

The modification cycle of source files naturally divides itself up into three distinct steps:

• File Creation - A new file is created, either from scratch or through the modification of some pre-existing source file.
• Testing - Confirming that the newly created file does what it was meant to do.
• Capturing a result - Requires saving some output from the creation or use of the file for future reference. This may include source files and compiled binaries built for various platforms.

Obviously if this cycle had only one iteration, meaning you could write code only once and then never touch it again for the rest of time, you would not need to waste your time worrying about the cycle and countless University types would have to babble about other things around the water cooler. Unfortunately, as your code evolves and becomes more popular and efficient, it is necessary to repeat the cycle for one file or an entire project, changing files, testing them, and saving them for future reference.

Suppose that after the third or fourth modification to a file, an error is found in a particular portion of the code. You have 2 questions you must ask; Has something outside the code, for example the OS, gone crazy, or is has the new file itself caused the error? Most likely it is the modifications you have made to the file, and all you have is the latest revision of the code. You could go in and track down modifications, if you can remember what they all were and how to fix it back to the way it was. More troublesome is if your new changes to put the code back to the way it was made even more errors. Source file control gives you the tools and info to analyze problems and recover code in the case something goes hanously awry.

The essential idea behind source control lies in versioning, or recording changes made to the file in each iteration of the modification cycle. Each version, or revision, can then be recovered at any time from the archive it is stored in. If you have a revision of a source that you are happy with, you can archive that revision. Then, when necessary, make further changes to the file. When all goes well, the previous revision of a source file serves as the starting point for each new set of changes you make. If, however, something goes wrong after a new set of changes are implemented, then the archived revisions of the file permit you to take two important steps:

• You can compare the latest revision of the file against the archived (and presumably the correct) one.
• If you want, you can roll back the source file to any previous revision that you have archived.

Some of the functional goals Source Control programs, like RCS, that we will be exploring in this lab are:

• Ability to record file revisions
• Ability to retrieve previous file revisions
• Control over new revision creation - Most of the time, when you modify a file, you modify the last revision archived. However, there are times when you want to modify an older revision of the same file. Source control can allow you to specify what file revision you want to start with, and also how the revision of the file you're creating will relate to the ones that already exist.
• Ability to record why a revision was made - As source files evolve, it is easy to lose track of not just what changed but why it changed. So, in addition to saving a revision of a source file, you also save an explanation, or "log commentary," whenever creating a new revision.
• Control of file modification - In most cases, it is important to ensure that two developers can't modify the same revision of any file simultaneously. For this reason, RCS allows "locking" revisions that are being updated.
• Control of file access - Source control can control access to archived files. Read and write access is handled seperately from what is specified in the files themselves, while still honoring the usual Unix file protection bits. RCS also allows you to specify a list of users who are allowed to add revisions to an archive file.

For most projects, the solution is plain to see: "source" files. However, sometimes it is not that easy. When we talk about files which you use during a project, we generally want to try to categorize them into 3 groups:

• Dynamic Files - Dynamic files are generally those which change over time, like a Makefile or .c files. Sometimes, input files must be placed under this category because as your project changes, the format of your input file(s) can change rapidly, especially for proprietary software.
• Static Files - Static files are generally those which do NOT change over time, like library files. Most of the time, input files are placed under this category because normally the format of your input file(s) does not change. As a matter of fact, most of the programs written are done so with a particular input file already in mind (Graphics and CAD programs). Microstation did not change its input file type for 12 years!
• Derived Files - Derived files are generally those which are created by some process from dynamic files. Good examples of these are .o files, which are used to link modules of a program together but are created from a call to, say, gcc. Files under this class should never be put into source control, since the addition of these files are unnecessary (since they are rebuilt every time the source is built in most cases).

Source file revision numbers

Each revision of a file you put into an RCS archive file is assigned a revision number. By default, RCS revision numbers use a two-part revision numbering scheme in the form of n.m. You can think of n as a major revision, and m as a minor revision number. So, the original file is generally numbered 1.0, and each subsequent revision is labeled 1.1, 1.2, etc., respectively. In this case, the latest revision will have the highest revision number. Of course, you can choose to identify a revision by a "release number", which would correspond to setting the minor revision number to zero and incrementing the major revision number by one. It isn't very difficult to see how this can be useful when releasing software!

Source file revision storage

An archive can contain many revisions of a source file. However, only one revision of the source is stored in literal form with the archive file. All others are stored as a set of differences, or deltas, from that single revision. When you request a given revision, the source control system constructs that revision by applying as many deltas as necessary to the literal revision of the source file. This method requires much less disk space than saving literal copies of every revision of the source file.

Other archive file contents

In addition to a set of source file revisions, an archive file contains a history, or log, that records why each revision of the file was submitted to the archive. These descriptions are stored in the archive for you to access later.

An archive file also contains administrative information, such as the list of people allowed to check in new source file revisions. The archive also contains many other things, most of which will not be covered in this discussion.

RCS Command Lines

Like most Unix programs, all RCS commands expect a command line that consists of a command name followed by one or more file names. The file names may be preceded by zero or more options. As expected, any options you provide will change how the command works. As a template, a command will generally look like so:

command-name [options] {files...}

NOTE: options are always preceded by a hyphen, which is what distinguishes it from a filename. After the hyphen follows the option letter that identifies the option, and sometimes a string that serves as a value for the option. One common mistake is to put whitespace between the hyphen and the option, or the option and the value (if applicable). No whitespace should appear between these; let them appear as one argument on the command line.

STRINGS: One final piece of info more related to your particular shell is entering in quoted strings. Sometimes you have the ability to enter a description as a string on the command line. When entering multiple words (a word is any sequence of characters followed by and/or preceded by whitespace) you'll need to do so as a quoted string. If you continue your description over more than one line, you'll have to use whatever convention your shell supports for continuing a command line.

For example, the -m option to the ci program specifies comments for a check-in operation. IF you want to specify a multi-line comment and you're using csh(1), you need to preced each carriage return in the command by a backslash (like in C) as such:

% ci -m"Fixed several errors, none of which were evident in\
? RH6.2 version released last week." mysource.c

However, if you're using the Bourne shell( or ksh(1) or bash(1)), as long as the value for -m is quoted, you don't need to do anything special to continue the comments to the second line:

$ ci -m"Fixed several errors, none of which were evident in
> RH6.2 version released last week." mysource.c

RCS file naming

When running an RCS command, you can name either a working file or the corresponding RCS file on the command line. RCS files are, by default, stored in the current directory or into an RCS directory if one is present. RCS archive files take the form of FILENAME,v where FILENAME is the file name of the original file before put under RCS revision control. When putting source files under RCS control, RCS creates the ,v file and removes your original file. This ,v file then is present in your working directory. It is recommended, however, to place all of your ,v files for a particular directory into a repository, or a directory specifically created for archive files. Each directory that you have files under source control by RCS needs to have a directory called RCS manually created. When checking in a file into source control, RCS checks to see if the current directory has an RCS subdirectory; if so, RCS archive files are placed in this directory instead of cluttering up your working directory. When checking files out of RCS, RCS will look for an RCS subdirectory for the specified file if not specifically pathed. Thus, the repository can be very helpful if taken advantage of.

RCS Commands in a Nutshell

ci - Checks in RCS revisions

ci, short for "Check In", submits file in for RCS revision control. This command, in its basic form, needs no options. Hence, the only parameter the command needs is a file name of the file you wish to check in. Remember that you can also specify the archive file instead, or you can specify a file/archive pair. In this case, if you have the file Tew.c in RCS source control in an RCS directory, the following commands all do the same thing:

%ci Tew.c
%ci Tew.c,v
%ci RCS/Tew.c,v
%ci RCS/Tew.c,v Tew.c
%ci Tew.c RCS/Tew.c,v

When checking files in, you are asked to enter a file description string. This log shows up whenever you ask RCS to display a revision history; the first revision is given the description "Initial Revision" by default. A sample session is below:

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

Once the RCS file is created in the repository (if an RCS subdirectory is detected) your source file is immediately deleted. It is, of course, now safely stored in the RCS file and can be extracted as a working file whenever you want.

co - Checks out RCS revisions

co, short for "Check Out", comes in two flavors. If used with no parameters, it acts as a "Check out for Reading" command which allows you to check out files for the sole purpose of reading the source files. This point is further italicized by the fact that the files produced by this type of call are marked as read only. In order to check out files for modification, you use the other flavor of co which includes the parameter -l in the command. This locks the file so that no other person can check out this file for modification to prevent simultaneous changes. Just watch out; you can still check out files even if they are locked! Examples:

% ls
RCS
% co Tew.c
RCS/Tew.c,v --> Tew.c
revision 1.1
done
% co -l Tew.c
RCS/Tew.c,v --> Tew.c
revision 1.1 (locked)
done
% co Tew.c
RCS/Tew.c,v --> Tew.c
revision 1.1
writable Tew.c exists; remove it? [ny](n): n
co: checkout aborted

rcsdiff - Compares a working file to its RCS file.

rcsdiff compares the working file currently being modified with the last version stored in the RCS archive. This is useful if something happened to the code between revision check-ins that caused the program to suddenly quit working. With this, you can usually find simple mistakes like stray keystrokes or simple modification problems. To specify a version other than the last version, use the -r option, followed by the revision you want to compare the working file with. For example, if I checked out version 1.2 and decided to compare it with version 1.3, rcsdiff would show the differences between the two revisions like so:

% co -r1.2 Tew.c
RCS/Tew.c,v --> Tew.c
revision 1.2
done
% rcsdiff -r1.3 Tew.c
==========================
RCS file: RCS/Tew.c,v
retrieving revision 1.3
diff -r1.3 Tew.c
1,4c1,3
< /*
< * Allison Tew is a teacher.
< * She teaches CS2335.
< */
---
> Allison Tew is a teacher.
> She teaches CS2335.
>

rcs - Administrative RCS command.

rcs is the command for all of the administrative actions that may need to be done to RCS files/archives. For example, the rcs function can lock and unlock files, set permission lists, and a wide variety of actions. For this lab, we will only be using the -u option.
rcs -u will unlock any file that is currently locked. For example, if the file Tew.c was checked out using co -l, nobody else with permissions to check the file out may do so until the file has been checked back in. If the user who checked the file out decided not to modify the file, and erased it, the administrator can unlock the file for others to access. If unlocking a revision other than the last one, the revision must be specified after the -u option. Example:

% co -l -r1.2 Tew.c
RCS/Tew.c,v --> Tew.c
revision 1.2 (locked)
done
% rcs -u1.2 Tew.c
RCS file: RCS/Tew.c,v
1.2 unlocked
done
% rm Tew.c

rlog - Displays revision log

rlog displays the revision log for a particular file under RCS revision control, plus all of the properties set for the file. Example:

% rlog Tew.c
RCS file: RCS/Tew.c,v
Working file: Tew.c
head: 1.3
branch:
locks: strict
access list:
symbolic names:
keyword substitution: kv
total revisions: 3; selected revisions: 3
description:
Sample file for RCS instruction.
----------------------------
revision 1.3
date: 2001/01/16 07:34:35; author: ddiaz; state: Exp; lines: +4 -3
Added C-Style Comments.
----------------------------
revision 1.2
date: 2001/01/16 07:31:27; author: ddiaz; state: Exp; lines: +2 -0
Added Second Line
----------------------------
revision 1.1
date: 2001/01/16 04:31:34; author: ddiaz; state: Exp;
Initial revision
=====================================================

rcsclean - Cleans up a source directory

rsclean is used to help tidy-up the source directory when you're done working with it. This program basically compares working files in the current directory with those in the archive file and removes working files which were checked out but never modified. Three rules apply when working with rsclean:

• A working file that was checked out for reading is removed only if it still matches the head revision in the archive file (last revision) .
• If the -u option is given, a working file that was checked out for modification is removed if it still matches the original revision (that is, the one checked out and locked by the user).
• If a working file does not match the revision noted in the last two rules, the rsclean will never remove it and you have to rm it yourself.

Any commands rsclean executes are echoed to its standard output so you can see what's going on. If you want to see what commands the rsclean program would excute without actually executing them, use the -n option. Note that the output from rsclean -n looks exactly like the normal output, so be careful not to confuse a -n run with the real McCoy!

SUMMARY

The following table sums up the commands necessary for RCS operation along with a brief description of their purpose.

Command	Basic Operation
ci	Creating/Updating an archive file
co	Getting a working file for reading
co -l	Getting a working file for modification
rcsdiff	Comparing a working file to its RCS file
rcs -u (plus rm)	Unlocking and discarding a working file
rlog	Viewing the history of an RCS file
rcsclean	Cleaning up a source directory

YOUR ASSIGNMENT

You are to gain some experience with RCS by placing past programs under RCS control. You are responsible for being able to use RCS as described on this page, so a familiarity with RCS and related commands is a must. If you have any questions about RCS, please feel free to post them to the newsgroup.

DISCLAIMER:  Some (or most) of this lab was created with the help of "Applying RCS and SCCS," published by O'Reilly & Associates Inc., and written by Don Bolinger & Tan Bronson; First edition, 1995.
The lab may not be perfect.  If there are any questions or problems about clarity, please post to the newsgroup: git.cc.class.cs2335 or send e-mail to:  ddiaz@cc.gatech.edu

---

Back to Lab Information Page | Back to CS 2335 Home Page