14.4 Alphabetical Summary of RCS Commands

For details on the syntax of keywords, revision numbers, dates, states, and standard options, refer to the previous discussions.

ci [options] files

Check in revisions. ci stores the contents of the specified working files into their corresponding RCS files. Normally, ci deletes the working file after storing it. If no RCS file exists, then the working file is an initial revision. In this case, the RCS file is created and you are prompted to enter a description of the file. If the RCS file exists, ci increments the revision number and prompts you to enter a message that logs the changes made. If a working file is checked in without changes, the file reverts to the previous revision.

The mutually exclusive options -u, -l, and -r are the most common. Use -u to keep a read-only copy of the working file (for example, so that the file can be compiled or searched). Use -l to update a revision and then immediately check it out again with a lock. This allows you to save intermediate changes but continue editing (for example, during a long editing session). Use -r to check in a file with a different release number. ci accepts the standard options -q, -V, -x, and -z.

Options

-d[date]

Check the file in with a timestamp of date or, if no date is specified, with the time of last modification.

-f[R]

Force a checkin even if there are no differences.

-I[R]

Interactive mode; prompt user even when standard input is not a terminal (e.g., when ci is part of a command pipeline).

-i[R]

Create (initialize) an RCS file and check it in. A warning is reported if the RCS file already exists.

-j[R]

Check in a file without initializing. Will report an error if file does not already exist.

-k[R]

Assign a revision number, creation date, state, and author from keyword values that were placed in the working file, instead of computing the revision information from the local environment. -k is useful for software distribution: the preset keywords serve as a timestamp shared by all distribution sites.

-l[R]

Do a co -l after checking in. This leaves a locked copy of the next revision in the working directory.

-mmsg

Use the msg string as the log message for all files checked in. When checking in multiple files, ci normally prompts whether to reuse the log message of the previous file. -m bypasses this prompting.

-M[R]

Set the working file's modification time to that of the retrieved version. Use of -M can confuse make and should be used with care.

-nname

Associate a text name with the new revision number.

-Nname

Same as -n, but override a previous name.

-r[R]

Check the file in as revision R.

-r

By itself, reverts to the default behavior of releasing a lock and removing the working file. This option overrides any -l or -u options that have been initialized by shell aliases or scripts. This behavior for -r is specific to ci.

-sstate

Set the state of the checked-in revision.

-tfile

Write the contents of file into the RCS file as the description, instead of prompting for it. This works only for the initial checkin.

-t-string

Write the specified string into the RCS file as the description, instead of prompting for it. This works only for initial checkin.

-T

Set the RCS file's modification time to the time of the latest revision if the RCS file's time precedes the new revision.

-u[R]

Do a co -u after checking in. This leaves a read-only copy in the working directory.

-wuser

Set the author field to user in the checked-in revision.

Examples

Check in chapter files using the same log message:

ci -m'First round edits' chap*

Check in edits to prog.c, leaving a read-only copy:

ci -u prog.c

Start revision level 2; refer to revision 2.1 as "Prototype":

ci -r2 -nPrototype prog.c

co [options] files

Retrieve a previously checked-in revision, and place it in the corresponding working file (or print to standard output if -p is specified). If you intend to edit the working file and check it in again, specify -l to lock the file. co accepts the standard options -q, -V, -x, and -z.

Options

-ddate

Retrieve latest revision whose checkin timestamp is on or before date.

-f[R]

Force the working file to be overwritten.

-I[R]

Interactive mode; prompt user even when standard input is not a terminal.

-jR2:R3

This works like rcsmerge. R2 and R3 specify two revisions whose changes are merged (joined) into a third file: either the corresponding working file or a third revision (any R specified by other co options).

-kc

Expand keyword symbols according to flag c, which can be:

b

Like o, but perform its operations in binary mode, generating the previous revision's keywords and values in binary.

k

Expand symbols to keywords only (no values). Useful for ignoring trivial differences during file comparison.

kv

Expand symbols to keyword and value (the default). Insert the locker's name only during a ci -l or co -l.

kvl

Like kv, but always insert the locker's name.

o

Expand symbols to keyword and value present in previous revision. This is useful for binary files that don't allow substring changes.

v

Expand symbols to values only (no keywords). This prevents further keyword substitution and is not recommended. Cannot be used with -l.

-l[R]

Same as -r, but also lock the retrieved revision.

-M[R]

Set the working file's modification time to that of the retrieved version. Use of -M can confuse make and should be used with care.

-p[R]

Send retrieved revision to standard output instead of to a working file. Useful for output redirection or filtering.

-r[R]

Retrieve the latest revision or, if R is given, retrieve the latest revision that is equal to or lower than R.

-sstate

Retrieve the latest revision having the given state.

-T

Preserve the modification time of the RCS file even if a lock is added or removed.

-u[R]

Same as -r, but also unlock the retrieved revision if you locked it previously.

-w[user]

Retrieve the latest revision that was checked in either by the invoking user or by the specified user.

Examples

Sort the latest stored version of file:

co -p  file  | sort

Check out (and lock) all uppercase filenames for editing:

co -l [A-Z]*

Note that filename expansion fails unless a working copy resides in the current directory. Therefore, this example works only if the files were previously checked in via ci -u. Finally, here are some different ways to extract the working files for a set of RCS files (in the current directory):

co -r3 *,v                    Latest revisions of release 3
co -r3 -wjim *,v              Same, but only if checked in by jim
co -d'May 5, 2 pm LT' *,v     Latest revisions that were modified 
                              on or before the date
co -rPrototype *,v            Latest revisions named Prototype

ident [option] [files]

Extract keyword/value symbols from files. files can be text files, object files, or dumps.

Options

-q

Suppress warning message when no keyword patterns are found.

-V

Print version information and exit.

Examples

If file prog.c is compiled, and it contains this line of code:

char rcsID[ ] = "$Author: daniel $";

then the following output is produced:

% ident prog.c prog.o
prog.c:
     $Author: daniel $
prog.o:
     $Author: daniel $

Show keywords for all RCS files (suppress warnings):

co -p RCS/*,v | ident -q

rcs [options] files

An administrative command for setting up or changing the default attributes of RCS files. Among other things, rcs lets you set strict locking (-L), delete revisions (-o), and override locks set by co (-l and -u). RCS files have an access list (created via -a); anyone whose username is on the list can run rcs. The access list is often empty, meaning that rcs is available to everyone. In addition, you can always invoke rcs if you own the file, if you're a privileged user, or if you run rcs with -i. rcs accepts the standard options -q, -V, -x, and -z.

Options

-ausers

Append the comma-separated list of users to the access list.

-Aotherfile

Append otherfile's access list to the access list of files.

-b[R]

Set the default branch to R or, if R is omitted, to the highest branch on the trunk.

-c'str'

Set the comment character to string str. This option is obsolete, because RCS normally uses the preceding $Log$ line's prefix when inserting log lines during checkout.

-e[users]

Erase everyone (or only the specified users) from the access list.

-i

Create (initialize) an RCS file, but don't deposit a revision.

-I

Interactive mode; prompt user even when standard input is not a terminal. (New in RCS Version 5.)

-kc

Use c as the default style for keyword substitution. (See co for values of c.) -kkv restores the default substitution style.

-l[R]

Lock revision R or the latest revision. -l "retroactively locks" a file and is useful if you checked out a file incorrectly by typing co instead of co -l. If another user already has a lock on the file, that lock is broken, as with -u.

-L

Turn on strict locking (the default). This means that everyone, including the owner of the RCS file, must use co -l to edit files. Strict locking is recommended when files are to be shared. (See -U.)

-mR:msg

Use the msg string to replace the log message of revision R.

-M

Disable email notification when breaking a lock on a file with rcs -u. This should be used only when there is another means to warn users that their files have been unlocked.

-nflags

Add or delete an association between a revision and a name. flags can be:

name:R

Associate name with revision R.

name:

Associate name with latest revision.

name

Remove association of name.

-Nflags

Same as -n, but overwrite existing names.

-oR_list

Delete (outdate) revisions listed in R_list. R_list can be specified as R1, R1:R2, R1:, or :R2. When a branch is given, -o deletes only the latest revision on it.

-sstate[:R]

Set the state of the latest revision, or revision R, to state.

-t[file]

Replace the RCS file description with the contents of file or, if no file is given, with standard input.

-t-string

Replace the RCS file description with string.

-T

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

-u[R]

The complement of -l: unlock a revision that was previously checked out via co -l. If someone else did the checkout, you are prompted to state the reason for breaking the lock. This message is mailed to the original locker.

-U

Turn on nonstrict locking. Everyone except the file owner must use co -l to edit files. (See -L.)

Examples

Associate the label To_customer with the latest revision of all RCS files:

rcs -nTo_customer: RCS/*

Add three users to the access list of file beatle_deals:

rcs -ageorge,paul,ringo beatle_deals

Delete revisions 1.2 through 1.5:

rcs -o1.2-1.5 doc

Replace an RCS file description with the contents of a variable:

echo "$description" | rcs -t  file 

rcsclean [options] [files]

Compare checked-out files against the corresponding latest revision or revision R (as given by the options). If no differences are found, the working file is removed. (Use rcsdiff to find differences.) rcsclean is useful in makefiles. For example, you could specify a "clean-up" target to update your directories. rcsclean is also useful prior to running rcsfreeze. rcsclean accepts the standard options -q, -V, -x, and -z.

Options

-kc

When comparing revisions, expand keywords using style c. (See co for values of c.)

-n[R]

Show what would happen, but don't actually execute.

-r[R]

Compare against revision R. R can be supplied as arguments to other options, so -r is redundant.

-T

Preserve the modification time of the RCS file even if a lock is added or removed.

-u[R]

Unlock the revision if it's the same as the working file.

Examples

Remove unchanged copies of program and header files:

rcsclean *.c *.h

rcsdiff [options] [diff_options] files

Compare revisions via diff. Specify revisions using -r as follows:

Number of revisions specified	Comparison made
0	Working file against latest revision
1	Working file against specified revision
2	One revision against the other

rcsdiff accepts the standard options -q, -V, -x, and -z, as well as diff_options, which can include any valid diff option. rcsdiff exits with a status of 0 (no differences), 1 (some differences), or 2 (unknown problem).

Options

-kc

When comparing revisions, expand keywords using style c. (See co for values of c.)

-rR1

Use revision R1 in the comparison.

-rR2

Use revision R2 in the comparison. (-rR1 must also be specified.)

-T

Preserve the modification time on the RCS file.

rcsmerge [options] file

Perform a three-way merge of file revisions, taking two differing versions and incorporating the changes into the working file. You must provide either one or two revisions to merge (typically with -r). Overlaps are handled the same as with merge, by placing warnings in the resulting file. rcsmerge accepts the standard options -q, -V, -x, and -z. rcsmerge exits with a status of 0 (no overlaps), 1 (some overlaps), or 2 (unknown problem).

Options

-kc

When comparing revisions, expand keywords using style c. (See co for values of c.)

-p[R]

Send merged version to standard output instead of overwriting file.

-r[R]

Merge revision R or, if no R is given, merge the latest revision.

Examples

Say you need to add updates to an old revision (1.3) of prog.c, but the current file is already at revision 1.6. To incorporate the changes:

co -l prog.c
(edit latest revision by adding revision 1.3 updates, then:)
rcsmerge -p -r1.3 -r1.6 prog.c > prog.updated.c

Undo changes between revisions 3.5 and 3.2, and overwrite the working file:

rcsmerge -r3.5 -r3.2 chap08

rlog [options] files

Display identification information for RCS files, including the log message associated with each revision, the number of lines added or removed, date of last checkin, and so on. With no options, rlog displays all information. Use options to display specific items. rlog accepts the standard options -V, -x, and -z.

Options

-b

Prune the display; print information about the default branch only.

-ddates

Display information for revisions whose checkin timestamps fall in the range of dates (a list separated by semicolons). Be sure to use quotes. Each date can be specified as:

date1<date2

Select revisions between date1 and date2, inclusive.

date1 <

Select revisions made on or after date1.

date1

Select revisions made on or before date1.

-h

Display only the beginning of the normal rlog listing, showing the RCS pathname, working pathname, header, default branch, etc.

-l[users]

Display information only about locked revisions or, if lockers is specified, only revisions locked by the comma-separated list of users.

-L

Skip files that aren't locked.

-N

Don't display symbolic names.

-r[list]

Display information for revisions in the comma-separated list of revision numbers. If no list is given, the latest revision is used. Items can be specified as:

R1

Select revision R1. If R1 is a branch, select all revisions on it.

R1.

If R1 is a branch, select its latest revision.

R1:R2

Select revisions R1 through R2.

:R1

Select revisions from beginning of branch through R1.

R1:

Select revisions from R1 through end of branch.

-R

Display only the name of the RCS file.

-sstates

Display information for revisions whose state matches one from the comma-separated list of states.

-t

Same as -h, but also display the file's description.

-w[users]

Display information for revisions checked in by anyone in the comma-separated list of users. If no users are supplied, assume the name of the invoking user.

Examples

Display a file's revision history:

rlog RCS/*,v | more

Display names of RCS files that are locked by user daniel:

rlog -R -L -ldaniel RCS/*

Display the "title" portion (no revision history) of a working file:

rlog -t calc.c