1.2.1 Interaction model

The interaction model is straightforward. For each working file, you initialize its RCS file once, then enter a cycle of checkout, modification, and checkin operations. Along the way, you can tweak some of the RCS file’s metadata, as well. All of this is done through RCS commands; you need not modify the RCS file directly (and in fact you should probably avoid doing so lest RCS become confused). This model is somewhat analogous to using a library (of books). With a library, you sign up for a library card (initialize), then enter a cycle of taking a book home (checkout), enjoying it (NB: without modification, one hopes), and returning it to the library (checkin).

Furthermore, you can compare revisions in the RCS file against each other, examine the user- (hopefully high) quality descriptions of the changes each revision embodies, merge selected revisions, and so forth.

1.2.2 Working file

RCS commands operate on one pair of files at a time. The working file is what you normally view and edit (e.g., a file of C programming language source code named a.c). Because the working file’s contents can be extracted from the RCS file (called instantiating a working file), it can be safely deleted to regain some disk space.

1.2.3 RCS file

The RCS file is a separate file, conventionally placed in the subdirectory RCS, wherein RCS commands organize the initial and subsequent revisions of the working file, associating with each revision a unique revision number along with the remembered particulars of the checkin that produced it. It also contains a description of the working file and various other metadata, described below.

The RCS file is also known (colloquially) as the “comma-v file”, due to its name often ending in ,v (e.g., a.c,v).

A revision number is a branch number followed by a dot followed by an integer, and a branch number is an odd number of integers separated by dot. A revision number with one dot (implying a branch number without any dots) is said to be on the trunk. All integers are positive. For example:

1.1         -- revision number for initial checkin (typically);
               branch number: 1

9.4.1.42    -- more complicated (perhaps after much gnarly hacking);
               branch number: 9.4.1

333.333.333 -- not a valid revision number;
               however, a perfectly valid branch number

The branch point of a non-trunk branch is the revision number formed by removing the branch’s trailing integer. To compute the next higher branch or revision number, add one to the trailing integer. The highest-numbered revision on a branch is called the tip of the branch (or branch tip). Continuing the example:

1.1         -- on trunk; no branch point;
               next higher branch number:   2
               next higher revision number: 1.2

9.4.1.42    -- not on trunk; branch point:  9.4
               next higher branch number:   9.4.2
               next higher revision number: 9.4.1.43

333.333.333 -- not on trunk; branch point:  333.333
               next higher branch number:   333.333.334
               next higher revision number: 333.333.333.1

In addition to this “tree” of thus-linked revisions, the RCS file keeps track of the default branch, i.e., the branch whose tip corresponds to the most recent checkin; as well as the symbolic names, a list of associations between a user-supplied (and presumably meaningful) symbol and an underlying branch or revision number.

The RCS file contains two pieces of information used to implement its access control policy. The first is a list of usernames. If non-empty, only those users listed can modify the RCS file (via RCS commands). The second is a list of locks, i.e., association between a username and a revision number. If a lock username:revno exists, that means only username may modify revno (that is, do a checkin operation to deposit the next higher revision, or a higher revision number on the same branch as revno).

1.2.4 Fundamental operations

The checkin operation records the contents of the working file in the RCS file, assigning it a new (normally the next higher) revision number and recording the username, timestamp, state (a short symbol), and user-supplied log message (a textual description of the changes leading to that revision). It uses diff to find the differences between the tip of the default branch and the working file, thereby writing the minimal amount of information needed to be able to recreate the contents of the previous tip.

The checkout operation identifies a specific revision from the RCS file and either displays the content to standard output or instantiates a working file, overwriting any current instantiation with the selected revision. In either case, the content may undergo keyword expansion, which replaces text of the form ‘$Keyword$’ with (possibly) different text comprising the keyword and its value, depending on the current keyword expansion mode (see Substitution mode option).

1.2.5 Keywords

The keywords and their values are:

Author

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

Date

The date and time the revision was checked in. May include an appended timezone offset.

Header

A standard header containing the absolute RCS filename, the revision number, the date and time, the author, the state, and the locker (if locked). May include an appended timezone offset.

Id

Same as ‘Header’, except that only the basename appears (no directory components).

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 filename, the revision number, the author, and the date and time. May include an appended timezone offset.

Existing log messages are not replaced. Instead, the new log message is inserted after ‘$Log:...$’. This is useful for accumulating a complete change log in a source file.

Each inserted line is prefixed by the string that prefixes the ‘$Log$’ line. For example, if the ‘$Log$’ line is

// $Log: tan.cc $

then RCS prefixes each line of the log with ‘// ’ (slash, slash, space). This is useful for languages with comments that go to the end of the line.

The convention for other languages is to use a ‘ * ’ (space, asterisk, space) prefix inside a multiline comment. For example, the initial log comment of a C program conventionally is of the following form:

 /*
  * $Log$
  */

For backwards compatibility with older versions of RCS, if the log prefix is ‘/*’ or ‘(*’ surrounded by optional white space, inserted log lines contain a space instead of ‘/’ or ‘(’; however, this usage is obsolescent and should not be relied on.

Name

The symbolic name used to check out the revision, if any. For example, ‘co -rJoe’ generates ‘$Name: Joe $’. Plain co generates just ‘$Name: $’.

RCSfile

The basename of the RCS file.

Revision

The revision number assigned to the revision.

Source

The absolute RCS filename.

State

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

2.1.1 Revision options

As to be expected in a revision control system, many options are of the form ‘-flag[rev]’, where flag is a single letter (e.g., ‘r’). If ommitted, rev defaults to the latest revision on the default branch. A revision can be specified in many ways:

br.n

Straightforward dot-notation, where br specifies the branch.

.n

Like br.n, using the default branch.

br

Like br.n, using the a command-specific computation of n, given the current tip i. For ci (see Invoking ci), n would be i + 1, while for other commands n would be simply i.

name

This is the symbolic name of a revision, as assigned previously by a ci -n or ci -N command.

$ ¶

The command computes the effective revision by examining the values of keyword expansions in the working file.

For commands that accept a range of revisions, the syntax is generally rev1:rev2, i.e., two revisions (specified as described above) separated by a colon.

2.1.2 Date option

Some commands accept an option of the form ‘-ddate’ to specify a date, an absolute point in time (to second resolution), expressed in a date format. These also accept ‘-zzone’ to specify the timezone. The special value ‘LT’ stands for the local time zone. RCS recognizes many date formats and time zones. For example, the following dates are equivalent if local time is January 11, 1990, 8pm Pacific Standard Time, eight hours west of Coordinated Universal Time (UTC):

8:00 pm lt
4:00 AM, Jan. 12, 1990           default is UTC
1990-01-12 04:00:00+00           ISO 8601 (UTC)
1990-01-11 20:00:00-08           ISO 8601 (local time)
1990/01/12 04:00:00              traditional RCS format
Thu Jan 11 20:00:00 1990 LT      output of ctime(3) + LT
Thu Jan 11 20:00:00 PST 1990     output of date(1)
Fri Jan 12 04:00:00 GMT 1990
Thu, 11 Jan 1990 20:00:00 -0800  Internet RFC 822
12-January-1990, 04:00 WET

Most fields in the date and time can be defaulted. The default time zone is normally UTC, but this can be overridden by the -z option. The other defaults are determined in the order year, month, day, hour, minute, and second (most to least significant). At least one of these fields must be provided. For omitted fields that are of higher significance than the highest provided field, the time zone’s current values are assumed. For all other omitted fields, the lowest possible values are assumed. For example, without -z, the date ‘20, 10:30’ defaults to ‘10:30:00 UTC’ of the 20th of the UTC time zone’s current month and year. Note that for the shell, the date/time must be quoted if it contains spaces.

RCS also accepts some other formats which specify only the date portion (omitting the time portion). In the following table, year is the four-digit year YYYY, and all examples specify 20 April 2018.

2.1.3 Description option

Some commands accept an option of the form ‘-t-text’ or ‘-tfile-name’. This option is to set or update the RCS file description text. In the first form, text is used directly, excluding the leading hyphen (‘-’) that distinguishes the two forms. In the second form, the description text is taken from the contents of file-name.

2.1.4 Substitution mode option

Some commands accept an option of the form -ksubst, used to control how keywords (see Concepts) are expanded in the working file. In the following table of subst values, the example keyword is ‘Revision’ and its value is ‘5.13’.

kv

Generate ‘$Revision: 5.13 $’ (dollar-sign, keyword, colon, space, value, space, dollar-sign). A locker’s name is inserted in the value of the Header, Id and Locker keyword strings only as a file is being locked, i.e., by ci -l and co -l. This is the default substitution mode.

kvl

Like -kkv, except that a locker’s name is always inserted if the given revision is currently locked.

k

Generate ‘$Revision$’ (dollar-sign, keyword, dollar-sign). This is useful when comparing different revisions of a file. Log messages are inserted after Log keywords even if -kk is specified, since this tends to be more useful when merging changes.

o

Like -kkv, but use the old value present in the working file just before it was checked in. This can be useful for file formats that cannot tolerate any changes to substrings that happen to take the form of keyword strings.

b

Like -ko, but do all file i/o in binary mode. This makes little difference on POSIX and Unix hosts, but on DOS-like hosts one should use rcs -i -kb to initialize an RCS file intended to be used for binary files. Also, on all hosts, rcsmerge normally refuses to merge files when -kb is in effect.

v

Generate ‘5.13’ (value only). Further keyword substitution cannot be performed once the keyword names are removed, so this should be used with care. Because of this danger of losing keywords, -kv cannot be combined with -l, and the owner write permission of the working file is turned off; to edit the file later, check it out again without -kv.

2.1.5 Log message option

Both ci and rcs allow a log message to be specified with the -m option. If the msg argument to this option is empty, RCS uses the default ‘*** empty log message ***’. This particular message is handled specially (i.e., filtered out) by rlog.

2.1.6 State option

Some commands accept an option of the form -sstate to specify a state (see Invoking ci, see Invoking co). For frob (see Invoking rcs), you can also specify a revision. For log (see Invoking rlog), you can specify more than one state (see Delim-separated list).

RCS uses Exp (for “experimental”) as the default state, but does not attach any meaning to it or any state you choose. Other common states are Rel (for “release”), Prod (for “production”), Stable, and so on. A state should be an id (“identifier”, see File format grammar).

2.1.7 Working file mtime option

Two commands that mutate the working file (see Invoking ci, see Invoking co) accept an option of the form -M or -Mrev.

This option works with -u or -l to specify that the working file’s modification time should be set to the date associated with revision rev (defaults to the branch tip if unspecified).

Like -T, this can be useful when the working file is named in a Makefile target’s list of prerequisites.

2.1.8 Misc common options

Other common options are -I, -q, -T, -V, -w, -x.

-I

This option enables interactive mode. More precisely, it forces interactive mode, whereby RCS commands believe that their standard input is a terminal, normally a precondition for displaying a prompt to receive input (such as a log message on checkin). The intention of -I is for scripting situations where standard input is actually not a terminal but you know beforehand (without prompting) that input is needed and you are ready to provide it on standard input anyway.

-q

This option enables quiet mode. Commands work silently (unless there is an error condition), and suppress warnings and prompts.

-T

This option controls how some commands (see Invoking ci, see Invoking co, see Invoking rcs, see Invoking rcsclean) timestamp the RCS file. Normally, RCS commands set the RCS file’s timestamp when modifying it in the “natural” way (without taking any particular care). With -T, on the other hand, the commands either preserve the timestamp (for standalone lock/unlock operations), or use the timestamp of the working file (for ci).

This can be useful if the RCS file is found in a makefile target’s list of prerequisites (see Rule Syntax in The GNU Make Manual), that is, if some target should be rebuilt if the RCS file is newer than it. In that case, you can do ‘rcs -u -T’, for example, to unlock a revision in the RCS file without triggering a recompilation.

See Stamp resolution, for details on support for subsecond resolution.

-V

Behave like --version, i.e., display command version information and exit successfully. NB: This option is obsolete and its support will be removed in some future release.

-Vn

n specifies the RCS (major) version to emulate. Valid values for n are: 3, 4, 5. Version 5 is the current version, so -V5 does nothing special.

In versions prior to 5, RCS outputs ‘\t’ (tab, U+09) between the ‘:’ (colon) and the value (for keyword substitution) instead of space, uses the RCS file comment string to prefix each line in the Log expansion instead of computing it on the fly from the input text, writes/reads localtime instead of UTC, and displays slightly different output for rlog.

For version 4, the Header expansion unconditionally includes Locker: locker, as if the kvl substitution mode were specified (see Substitution mode option).

For version 3, the Header expansion omits the directories from the filename and says only Locked instead of the state.

-wlogin

Some commands accept an option of the form ‘-wlogin’ to specify the login name of the author of a revision, i.e., “who” is responsible.

-xsuff

Specify suff as the slash-separated list of file name suffixes used to recognize an RCS file. The default value is ‘,v/’, that is, first try with ‘,v’ then try with an empty suffix.

This basename search occurs within (i.e., starting from the beginning) the larger directory search loop, which comprises two candidates: d/RCS and d, where d is the directory component of the working file name. For example, given the working file a.c in the current directory, RCS tries, in order, these candidates:

./RCS/a.c,v
./RCS/a.c
./a.c,v
./a.c

Note that the last candidate is impossible (and is in fact discarded), because the working and RCS files cannot have the same name.

2.1.9 Delim-separated list

Some options that require (or allow) additional information can take multiple items of that information in the form of a delim-separated list, a concatenation of items with one or more delimiter characters between adjacent items. Multiple adjacent delim characters count as a single delimiter.

Most often you will use comma (, or U+2C), but RCS also permits others, depending on context. In the following table, “SPC” is the space character (U+20), “LF” is the linefeed character (U+0A), “TAB” is the tab character (U+09), and “semi” is ; (U+3B).

REV
REV1:          REV1-
REV1:REV2      REV1-REV2

Maintainer’s Note: This embarrassment of choice for delim characters will probably be reduced to simply one character in RCS 6: comma.

2.1.10 Environment

Various environment variables influence how RCS works.

Environment Variable: RCSINIT ¶

Another way to set common options is with the ‘RCSINIT’ environment variable. This is a space-separated list of options. Use ‘\’ (backslash) to escape significant space. For example:

# Set the value; make it available to subsequent commands.
RCSINIT="-q -x/,v -zLT"
export RCSINIT

# Use it (implicitly).
rlog -L foo

This example, in Bourne shell syntax, arranges for RCS commands to operate as if each command-line had prepended ‘-q -x/,v -zLT’ to the rest of the command-line. The effective command-line that rlog sees is thus ‘-q -x/,v -zLT -L foo’.

Environment Variable: RCS_MEM_LIMIT ¶

Normally, for speed, commands either memory map or copy into memory the RCS file if its size is less than the memory limit, currently defaulting to “unlimited”. Otherwise (or if the initially-tried speedy ways fail), the commands fall back to using standard i/o routines.

You can adjust the memory limit by setting the ‘RCS_MEM_LIMIT’ environment variable to a numeric value (measured in kilobytes). An empty value is silently ignored.

As a side effect, specifying the memory limit inhibits fall-back to slower routines. (This env var is mostly intended for testing RCS; normally, you can leave it unset. Probably it will be removed in a future release.)

Environment Variable: TMPDIR ¶

Environment Variable: TMP ¶

Environment Variable: TEMP ¶

Commands sometimes create temporary files, normally in a system-dependent directory, such as /tmp. You can override this directory by specifying another one as the value of one of the environment variables TMPDIR, TMP, or TEMP (checked in that order).

Environment Variable: LOGNAME ¶

Environment Variable: USER ¶

Absent -wlogin, or when login is omitted (see Misc common options), commands check environment variables LOGNAME and USER in that order². If neither of these are set, RCS queries the host for, and uses, your login.

2.6.1 modern

rcs [options] command [command-arg …]

This rcs usage dispatches to command, passing along command-arg… without interpretation.

--commands

Display a list of available commands, including a one-line description, and exit successfully.

--aliases

Display a list of command aliases and exit successfully.

--help command

Display help for a particular command and exit successfully. For example, to display help for the legacy interface, use:

--help frob

2.6.2 legacy

rcs frob [options] file …
(or “rcs” instead of “rcs frob”)

This rcs usage performs various administrative operations on the RCS file, depending on the options given.

-i

Create and initialize a new RCS file.

-L

Set strict locking.

-U

Set non-strict locking.

-M

Don’t send mail when breaking someone else’s lock.

Do not confuse this with -Mrev (see Working file mtime option).

-T

Preserve the modification time on the RCS file unless a revision is removed.

-I

-q

See Misc common options.

-alogins

Append logins (see Delim-separated list) to access-list.

-e[logins]

Erase logins (see Delim-separated list) from access-list. If logins is omitted, clear the access-list.

-Afile-name

Append access-list of file-name to current access-list.

-b[rev]

Set default branch to that of rev or highest branch on trunk if rev is omitted.

-l[rev]

Lock a revision.

-u[rev]

Unlock a revision.

-cstring

Set comment leader to string. NB: Don’t use; obsolete.

-ksubst

See Substitution mode option.

-mrev:[msg]

Replace log message with msg. See Log message option.

-nname[:[rev]]

If :rev is omitted, delete symbolic name. Otherwise, associate name with rev; name must be new.

-Nname[:[rev]]

Like -n, but overwrite any previous assignment.

-orange

Delete (also known as “outdate”) revisions in range:

rev

single revision

br

latest revision on branch br

rev1:rev2

rev1 to rev2 on same branch, inclusive

:rev

beginning of branch to rev

rev:

rev to end of branch

-sstate[:rev]

Set state (see State option).

-t-text

-tfile-name

See Description option. Replace description.

-V

-Vn

-xsuff

See Misc common options.

These options have no effect, and are included solely for consistency with other commands (see Environment): -zzone.

3.1.1 File format grammar

The meta syntax in this section uses the following conventions: ‘|’ (U+7C) separates alternatives; ‘{’ (U+7B) and ‘}’ (U+7D) enclose optional phrases; ‘{’ and ‘}*’ (trailing U+2A) enclose phrases that can be repeated zero or more times; ‘{’ and ‘}+’ (trailing U+2B) enclose phrases that must appear at least once and can be repeated; terminal symbols are in ‘""’ (two U+22).

rcstext   ::=  admin {delta}* desc {deltatext}*

admin     ::=  "head"         {num} ";"
               { "branch"     {num} ";" }
               "access"       {id}* ";"
               "symbols"      { sym ":" num }* ";"
               "locks"        { id ":" num }* ";"
               { "strict" ";" }
               { "integrity " {intstring} ";" }
               { "comment"    {string} ";" }
               { "expand"     {string} ";" }

delta     ::=  num
               "date"       num ";"
               "author"     id ";"
               "state"      {id} ";"
               "branches"   {num}* ";"
               "next"       {num} ";"
               { "commitid" sym ";" }

desc      ::=  "desc"  string

deltatext ::=  num
               "log"   string
               "text"  string

num       ::=  { digit | "." }+

digit     ::=  "0" through "9"

id        ::=  { idchar | "." }+

sym       ::=  {idchar}+

idchar    ::=  any visible graphic character except special

special   ::=  "$" | "," | "." | ":" | ";" | "@"

string    ::=  "@" { any character, with @ doubled }* "@"

word      ::=  id | num | string | ":"

intchar   ::=  any character, except @

thirdp    ::=  "^L" {intchar}*

intstring ::= "@" {intchar}* {thirdp}* "@"

3.1.2 Additional particulars of the file format

• In releases prior to 5.8 (2011-08-30), the grammar included the production:

  newphrase ::= id word* ";"
  

  and used it in the admin, delta and deltatext productions. This allowed third-party programs to interoperate with RCS by storing opaque (to RCS) data in the file.

  As of 5.8, in the name of progress (towards more systematic file integrity support), the only area reserved for third-party interop is in the string value of the integrity field, specifically after the first formfeed (U+0C). A further restriction (for all programs) is that the integrity value must not contain ‘@’.

  Warning: This change means you cannot use rlog (or rcs log) as a workalike for cvs log for versions of CVS that write other kinds of metadata into the file. If you use CVS and have access to the *,v files it writes, you can determine if they require cvs log by the following command:

  if grep -E -q '^(deltatype|permissions|kopt)' *,v
    then echo 'must use "cvs log"'
    else echo 'probably safe to use "rcs log" (for now)'
  fi
  

  The “(for now)” bit is a nod to the most probable trajectory for both RCS and CVS: away from interop.

• Whitespace has no significance except in string values. However, whitespace cannot appear within an id, num, or sym, and an RCS file must end with newline (U+0A). A string value is enclosed by ‘@’ (U+40) with internal ‘@’ characters doubled. All other bytes (arbitrary binary data) represent themselves. For example:

  conceptual string	persistent representation
  a string of five words	@a string of five words@
  another, with one ’@’ char	@another, with one '@@' char@
  with newline and unquoted @	@with newline and unquoted @@@

• Identifiers are case sensitive. Keywords are in lower case only. The sets of keywords and identifiers can overlap.
• Dates, which appear after the date keyword, are of the form Y.m.d.H.M.S, where Y is the year, m the month (01–12), d the day (01–31), H the hour (00–23), M the minute (00–59), and S the second (00–60). (These correspond to strftime format strings, with the exception of Y, which depends on the particular year.)

  Y contains just the last two digits of the year for years from 1900 through 1999, and all the digits of years thereafter. Dates use the Gregorian calendar; times use UTC.

• The delta nodes form a tree. All nodes whose numbers consist of a single pair, e.g.:

  2.3
  2.1
  1.3
  

  are on the trunk, and are linked through the next field in order of decreasing numbers. The head field in the admin node points to the head of that sequence (i.e., contains the highest pair). The branch node in the admin node indicates the default branch (or revision) for most RCS operations. If empty, the default branch is the highest branch on the trunk.

  All delta nodes whose numbers consist of 2n fields (n ≥ 2), e.g.:

  3.1.1.1
  2.1.2.2
  

  are linked as follows. All nodes whose first 2n-1 number fields are identical are linked through the next field in order of increasing numbers. For each such sequence, the delta node whose number is identical to the first 2n-2 number fields of the delta nodes on that sequence is called the branchpoint.

  The branches field of a node contains a list of the numbers of the first nodes of all sequences for which it is a branchpoint. This list is ordered in increasing numbers. See Figure 3.1.

                             Head
                               |
                               v                        / \
                           ---------                   /   \
     / \          / \      |       |      / \         /     \
    /   \        /   \     |  2.1  |     /   \       /       \
   /     \      /     \    |       |    /     \     /         \
  /1.2.1.3\    /1.3.1.1\   |       |   /1.2.2.2\   /1.2.2.1.1.1\
  ---------    ---------   ---------   ---------   -------------
      ^            ^           |           ^             ^
      |            |           v           |             |
     / \           |       ---------      / \            |
    /   \          |       \  1.3  /     /   \           |
   /     \         ---------\     /     /     \-----------
  /1.2.1.1\      1.3.1       \   /     /1.2.2.1\     1.2.2.1.1
  ---------                   \ /      ---------
      ^                        |           ^
      |                        v           |
      |                    ---------       |
      |                    \  1.2  /       |
      ----------------------\     /---------
    1.2.1                    \   /       1.2.2
                              \ /
                               |
                               v
                           ---------
                           \  1.1  /
                            \     /
                             \   /
                              \ /
  

  Figure 3.1: The organization of an example RCS file.