RCS with Threads

The description of the RCS enhancements below is a bit technical, but then again, so is the use of the command line RCS tools. The quoted -D flags referenced represent new features that can be turned on or off at the time that RCS with Threads is compiled. More end-user oriented documentation can be found in the man pages for each of the affected RCS commands. This package can be downloaded from TransWeb Tools or from Sunsite (the latter is "uuencoded" - a 7-bit encoded format that's not used much anymore). This package can be used free of charge. This enhanced version of RCS has been in use for over five years, but it's still possible that some bugs have escaped detection, so the standard disclaimer applies: use it at your own risk.

"-DRCSTHREAD":
Compiling with this flag set incorporates a fairly compact thread mechanism. Simply put, this function allows the user to create a template for determining which version of a file should be checked out. It works like this: if the user has a file in the current directory called ".rcsthread" or an environment variable called "RCSTHREAD" set to the name of an existing file, the "co" command will attempt to determine which version of a requested file to check out by the contents of the thread file. The structure of the thread file is:

     <DEFAULT<,v>:<1st Sym/Rev> <2nd Sym/Rev> ... <Nth Sym/Rev>>
     File name 1<,v>:<1st Sym/Rev> <2nd Sym/Rev> ... <Nth Sym/Rev>
     File name 2<,v>:<1st Sym/Rev> <2nd Sym/Rev> ... <Nth Sym/Rev>
     File name 3<,v>:<1st Sym/Rev> <2nd Sym/Rev> ... <Nth Sym/Rev>
     File name K<,v>:<1st Sym/Rev> <2nd Sym/Rev> ... <Nth Sym/Rev>

The thread mechanism causes the "co" command to search for the requested file in the first column of the thread file. If a match is found, the items located after the ":" character are treated as first, second, third (and so on) choices for a version of the file. These entries can be symbolic names, revisions, branches (such as "1.2."), or the "*" character. The "*" character matches the most recent version on the default branch. The optional entry "DEFAULT" can be used as a wildcard for file names. In other words, if an exact match for the requested file is not found in the thread file, "co" will use the list of symbols/revisions designated by the entry "DEFAULT", if it exists. An example thread might look like this:

     DEFAULT:  CHICAGO_2_2 CHICAGO_2_1 *
     Makefile: CHICAGO_2_2 4.
     main.c:   CHICAGO_DEV CHICAGO_2_2 *

If a user with this thread file attempted to check out main.c, "co" would first see if a version with the symbolic name CHICAGO_DEV existed. If not, it would look for a version named CHICAGO_2_2. If that didn't exist, it would get the most recent version on the default branch. A request for any file other than main.c or Makefile would use the thread entry following the DEFAULT keyword.

"-DNODUPE_THR":
This define, when combined with the "-DRCSTHREAD" define, would make the thread mechanism check for duplicate entries while processing the user's thread file.

"-DFROZENREVS":
This adds a "release mechanism" to the RCS configuration management process. It defines a special RCS state that allows certain restrictions to be placed on a version or versions of a file. For instance, if a version of a file was used in the release of a product, you would want to make sure that that version could not be obsoleted (deleted), for at least as long as the lifetime of the release. A "released" version of a file cannot be deleted, have its description changed, and unless "-DREL_TAGS" was used to build the RCS commands, cannot have any symbolic names removed or moved from the released version. For this option to be fully effective, the RCS commands should be "setuid" and the ",v" files owned by an administrative user id. (Otherwise, the ",v" files could be hand edited or deleted.)

"-DOUTPUTOPT":
This adds a the option "-oFILENAME" to the "co" command. The "-oFILENAME" option allows a file to be checked out to a name or path other than the default. For example, "co -o/usr/tmp/Makefile.test Makefile" says to "check out the file 'Makefile' into the directory /usr/tmp and call the checked out copy 'Makefile.test'".

"-DREL_TAGS":
The approach of the release mechanism as described under the section "-DFROZENREVS" can be a little ambiguous under certain circumstances. For instance, if you have made several releases to a software package that happens to incorporate, say version 3.4 of a specific file into the build, you may want to be able to move a symbolic name off of the previously released version of the file - provided that the symbolic name you wish to move was not intended to represent the release. Let's say that the symbols TESTVERSION, CHICAGO_2_2 and CHICAGO_2_1 have been added to version 3.4 of a file. The symbols CHICAGO_2_2 and CHICAGO_2_1 were added as part of the release process, but the symbol TESTVERSION was added by a developer for some other purpose. Without the "-DREL_TAGS" option during the building of the RCS commands, the name "TESTVERSION" could not be moved from version 3.4 of the file - even though that particular symbol doesn't represent a special release of the file. The "REL_TAGS" feature allows the symbolic names themselves to be released, and not just the version of the file they represent. In the above example, with this feature enabled, the user (or the configuration manager) would set the state of the symbols CHICAGO_2_2 and CHICAGO_2_1 to "Released". This would, by default, set the version of the file 3.4 to be released (so that it couldn't be accidentally deleted later), but yet allow the non-"Released" symbol "TESTVERSION" to be deleted or moved to another version of the file.

"-DKEYWORD_SHOWTAGS":
The "Header" and "Id" RCS keywords now list a file revision's symbol list and symbol states in addition to its revision number. Also, a new RCS keyword has been created - "SymbolList" - which shows just the symbol names and states of the checked out file. (See "-DREL_TAGS" section for a description of "symbol states".) This is helpful if the constituent files of a released package were all given the same symbol names. For example, if a user needed to identify which source files went into building a particular program, the ident command could be used to show a list of symbols (in addition to the other identifying information). It is often easier to track versions of files by symbol names than by a series of revision numbers.

"-DAUTO_BIN_DETECT":
A "binary file detection" feature, which makes the "co" command check the contents of an RCS file to determine if it is binary or ascii. If the file is binary, and a "-k" option was not issued on the command line, "co" will warn that the file is a binary file and turn off keyword substitution. Applying keyword substitution on a binary file can cause problems with the file. This feature is provided in case the file has not had keyword substitution turned off previously with the "rcs -ko" command.