15.6 CVS User Reference

This section provides details on connecting to a repository, the structure of sandboxes, and using the CVS commands.

15.6.1 Repository Locators

CVS currently supports six methods for the client to access the repository: local, forked, external, a password server, a GSS-API (Generic Security Services API) server, and a Kerberos 4 server (most Kerberos users will want to use GSS-API). Table 15-10 describes the various repository locator types and their respective access methods.

Table 15-10. Repository access types and methods

Method	Locator format	Description
Local	path :local:path	If the repository directory is local to the computer from which you will access it (or appears local, such as an NFS or Samba mounted filesystem), the repository string is just the pathname of the repository directory, such as /usr/local/cvsrep, or it can use the :local: prefix.
Forked local	:fork:path	This type of locator is used primarily for debugging the CVS protocol code, as it causes CVS to start (fork) a separate process to work with the repository and communicates with it using the CVS remote protocol.
External	:ext:user@host:path	External repositories are accessed via a remote shell utility, usually rsh (the default) or ssh. The environment variable $CVS_RSH is used to specify the remote shell program.
Password server	:pserver:user@host:path	Password server repositories require authentication to a user account before allowing use of the repository. Public CVS servers are commonly configured this way so they can provide anonymous CVS access. See Section 15.5.3.11 earlier in this chapter for more information on anonymous CVS.
GSS-API server	:gserver:	This locator type is used for servers accessible via Kerberos 5 or other authentication mechanisms supported by GSS-API.
Kerberos server	:kserver:	This locator type is used for servers accessible via Kerberos 4.

15.6.2 Configuring CVS

CVS's behavior can be influenced by two classes of settings other than the command-line arguments: environment variables (see Table 15-11) and special files (see Table 15-12).

Table 15-11. Environment variables

Variable	Description
$CVS_CLIENT_LOG	Client-side debugging file specification for client/server connections. $CVS_CLIENT_LOG is the basename for the $CVS_CLIENT_LOG.in and $CVS_CLIENT_LOG.out files, which will be written in the current working directory at the time a command is executed.
$CVS_CLIENT_PORT	The port number for :kserver: locators. $CVS_CLIENT_PORT doesn't need to be set if the kserver is listening on port 1999 (the default).
$CVS_IGNORE_REMOTE_ROOT	According to the change log, this variable was removed from CVS with Version 1.10.3.
$CVS_PASSFILE	Password file for :pserver: locators. This variable must be set before issuing the cvs login to have the desired effect. Defaults to $HOME/.cvspass.
$CVS_RCMD_PORT	For non-Unix clients, the port for connecting to the server's rcmd daemon.
$CVS_RSH	Remote shell for :ext: locators, if not rsh.
$CVS_SERVER	Remote server program for :ext: locators, if not cvs.
$CVS_SERVER_SLEEP	Server-side execution delay (in seconds) to allow time to attach a debugger.
$CVSEDITOR	Editor used for log messages; overrides $EDITOR.
$CVSIGNORE	A list of filename patterns to ignore, separated by whitespace. (See also cvsignore in Table 15-4 and .cvsignore in Table 15-12.)
$CVSREAD	Determines read-only (if the variable is set) or read/write (if the variable is not set) for checkout and update.
$CVSROOT	Default repository locator.
$CVSUMASK	Used to determine permissions for (local) repository files.
$CVSWRAPPERS	A list of filename patterns for the cvswrappers function. See also Section 15.5.3.
$EDITOR	Specifies the editor to use for log messages; see notes for $CVSEDITOR earlier in this table.
$HOME	On Unix, used to find the .cvsrc file.
$HOMEDRIVE	On Windows NT, used to find the .cvsrc file.
$HOMEPATH	On Windows NT, used to find the .cvsrc file.
$PATH	Used to locate programs to run.
$TEMP$TMP$TMPDIR	Location for temporary files. $TMPDIR is used by the server. On Unix, /tmp (and TMP on Windows NT) may not be overridden for some functions of CVS due to reliance on the system's tmpnam( ) function.
$VISUAL	Specifies the editor to use for log messages; see notes for $CVSEDITOR earlier in this table.

Despite the similarity in names, the $CVSROOT environment variable and the CVSROOT directory in a repository are not related to each other.

The "RSH" in the name of the $CVS_RSH environment variable doesn't refer to the particular program (rsh), but rather to the program CVS is supposed to use for creating remote shell connections (which could be some program other than rsh, such as ssh).

Because there is only one way to specify the remote shell program to use ($CVS_RSH) and because this is a global setting, users that commonly access multiple repositories may need to pay close attention to which repository they are using. If one repository requires one setting of this variable and another requires a different setting, you will have to change this variable between accesses to repositories requiring different settings. This aspect of the repository access method is not stored in the CVS/Root file in the sandbox (see Section 15.6.4.3, later in this chapter). For example, if you access some repositories via rsh and some via ssh, you can create the following two utility aliases (bash syntax):

$ alias cvs="export CVS_RSH=ssh; cvs"
$ alias cvr="export CVS_RSH=rsh; cvs"

Table 15-12 shows the files used by the CVS command-line client for server connection and client configuration information. These files reside in the user's home directory.

Table 15-12. Client configuration files

Option	Description
~/.cvsignore	Filename patterns of files to ignore.
~/.cvspass	Passwords cached by cvs login.
~/.cvsrc	Default command options.
~/.cvswrappers	User-specific checkout and commit filters.

The ~/.cvspass file is really an operational file, not a configuration file. It is used by the cvs client program to store the repository user account password between cvs login and cvs logoff.

Some common .cvsrc settings are:

update -dP

Bring in new directories and prune empty directories on cvs update.

diff -c

Give output in context diff format.

15.6.3 Creating a Sandbox

In order to use CVS, you must create a sandbox or have one created for you. This section describes sandbox creation, assuming there is already a module in the repository you want to work with. See the import command for information on importing a new module into the repository.

For example:

$ export CVSROOT=/usr/local/cvsroot
$ cd ~/work
$ cvs checkout hello

15.6.4 Sandbox Structure

This section describes the files and directories that may be encountered in sandboxes.

15.6.4.1 .cvsignore files

Sandboxes may contain .cvsignore files. These files specify filename patterns for files that may exist in the sandbox but that normally won't be checked into CVS. This is commonly used to cause CVS to bypass derived files.

15.6.4.2 .cvswrappers files

Sandboxes may contain .cvswrappers files, which provide directory-specific file handling information like that in the repository configuration file cvswrappers (see Section 15.5.3.6 earlier in this chapter).

15.6.4.3 CVS directories

Each directory in a sandbox contains a CVS directory. The files in this directory (see Table 15-13) contain metadata used by CVS to locate the repository and track which file versions have been copied into the sandbox.

Table 15-13. Files in the CVS directories

File	Description
BaseBaserevBaserev.tmp	The Base directory stores copies of files when the edit command is in use. The Baserev file contains the revision numbers of the files in Base. The Baserev.tmp file is used in updating the Baserev file.
Checkin.progUpdate.prog	The programs specified in the modules file for options -i and -u, respectively (if any).
Entries	Version numbers and timestamps for the files as they were copied from the repository when checked out or updated.
Entries.BackupEntries.LogEntries.Static	Temporary and intermediate files used by CVS.
Notify Notify.tmp	Temporary files used by CVS for dealing with notifications for commands such as edit and unedit.
Repository	The name by which the directory is known in the repository.
Root	The repository locator in effect when the sandbox was created (via cvs checkout).
Tag	Information about sticky tags and dates for files in the directory.
Template	Used to store the contents of the rcsinfo administrative file from the repository for remote repositories.

Since each sandbox directory has one CVS/Root file, a sandbox directory corresponds to exactly one repository. You cannot check out some files from one repository and some from another into a single sandbox directory.

15.6.5 Client Global Options

Table 15-14 lists the global options that control the operation of the CVS client program.

Table 15-14. Client global options

Option	Description
-a	Authenticate (gserver only).
-d root	Locate the repository. Overrides the setting of $CVSROOT.
-e editor	Specify message editor. Overrides the settings of $CVSEDITOR and $EDITOR.
-f	Don't read ~/.cvsrc. Useful when you have .cvsrc settings that you want to forgo for a particular command.
-H [command]--help [command]	Display help. If no command is specified, displays general CVS help, including a list of other help options.
-l	Don't log command in history.
-n	Don't change any files. Useful when you want to know ahead of time which files will be affected by a particular command.
-q	Be quiet.
-Q	Be very quiet. Print messages for serious problems only.
-r	Make new working files read-only.
-s variable=value	Set the value of a user variable to a given value. User variables can be used in the contents of administrative files.
-t	Trace execution. Helpful in debugging remote repository connection problems and, in conjunction with -n, in determining the effect of an unfamiliar command.
-w	Make new working files read/write. Overrides $CVSREAD. Files are read/write unless $CVSREAD is set or -r is specified.
-x	Encrypt. (Introduced in Version 1.10.)
-z gzip_level	Set the compression level. Useful when using CVS in client/server mode across slow connections.

15.6.6 Common Client Options

Table 15-15 and Table 15-16 describe the options that are common to many CVS commands. Table 15-15 lists the common options with a description of their function, while Table 15-16 lists which options can be used with the user commands. In the sections that follow, details are provided only for options that are not listed here or that do not function as described here.

Table 15-15. Common options

Option	Description
-D date	Use the most recent revision no later than date (see Section 15.6.6.1 for supported date formats).
-f	For commands that involve tags (via -r) or dates (via -D), include files not tagged with the specified tag or not present on the specified date. The most recent revision will be included.
-k kflag	Determine how keyword substitution will be performed. The space between -k and kflag is optional. See Table 15-17 for the list of keyword substitution modes.
-l	Do not recurse into subdirectories.
-n	Don't run module programs.
-R	Do recurse into subdirectories (the default). As of Version 1.11, CVS can work in sandboxes with directories checked out from different repositories.
-r rev	Use a particular revision number or symbolic tag.

Table 15-16 shows which common options are applicable to each user command.

Table 15-16. Common client option applicability

Command	-D	-f	-k	-l	-n	-R	-r
add
annotate
checkout
commit
diff
edit
editors
export
help
history
import
log
login
logout
rannotate
rdiff
release
remove
rlog
rtag
status
tag
unedit
update
version
watch
watchers

15.6.6.1 Date formats

CVS can understand dates in a wide variety of formats, including:

ISO standard

The preferred format is YYYY-MM-DD HH:MM, which would read as 2000-05-17, or 2000-05-17 22:00. The technical details of the format are defined in the ISO 8601 standard.

Email standard

17 May 2000. The technical details of the format are defined in the RFC 822 and RFC 1123 standards.

Relative

10 days ago, 4 years ago.

Common

month/day/year. This form can cause confusion because not all cultures use the first two fields in this order (1/2/2000 would be ambiguous).

Other

Other formats are accepted, including YYYY/MM/DD and those omitting the year (which is assumed to be the current year).

15.6.6.2 Keyword substitutions

Table 15-17 describes the keyword substitution modes that can be selected with the -k option. CVS uses keyword substitutions to insert revision information into files when they are checked out or updated.

Table 15-17. Keyword substitution modes

Mode	Description
b	Binary mode. Treat the file the same as with mode o, but also avoid newline conversion.
k	Keyword-only mode. Flatten all keywords to just the keyword name. Use this mode if you want to compare two revisions of a file without seeing the keyword substitution differences.
kv	Keyword-value mode. The keyword and the corresponding value are substituted. This is the default mode.
kvl	Keyword-value-locker mode. This mode is the same as kv mode, except it always adds the lock holder's user ID if the revision is locked. The lock is obtained via the cvs admin -l command.
o	Old-contents mode. Use the keyword values as they appear in the repository rather than generate new values.
v	Value-only mode. Substitute the value of each keyword for the entire keyword field, omitting even the $ delimiters. This mode destroys the field in the process, so use it cautiously.

Keyword substitution fields are strings of the form $Keyword ...$. The valid keywords are:

Author

The user ID of the person who committed the revision.

Date

The date and time (in standard UTC format) the revision was committed.

Header

The full path of the repository RCS file, the revision number, the commit date, time, and user ID, the file's state, and the lock holder's user ID if the file is locked.

Id

A shorter form of Header, omitting the leading directory name(s) from the RCS file's path, leaving only the filename.

Name

The tag name used to retrieve the file, or empty if no explicit tag was given when the file was retrieved.

Locker

The user ID of the user holding a lock on the file, or empty if the file is not locked.

Log

The RCS filename. In addition to keyword expansion in the keyword field, each commit adds additional lines in the file immediately following the line containing this keyword. The first such line contains the revision number and the commit date, time, and user ID. Subsequent lines are the contents of the commit log message. The result over time is a reverse-chronological list of log entries for the file. Each of the additional lines is preceded by the same characters that precede the keyword field on its line. This allows the log information to be formatted in a comment for most languages. For example:

#
# foo.pl
#
# $Log: ch15.xml,v $
#
#
# Revision 1.2  2000/06/09 22:10:23  me
# Fixed the new bug introduced when the last one was fixed.
# 
# Revision 1.1  2000/06/09 18:07:51  me
# Fixed the last remaining bug in the system.
#

Be sure that you don't place any keyword fields in your log messages if you use this keyword, since they will get expanded if you do.

RCSfile

The name of the RCS file (without any leading directories).

Revision

The revision number of the file.

Source

The full path of the RCS file.

State

The file's state, as assigned by cvs admin -s (if you don't set the state explicitly, it will be Exp by default).

15.6.7 User Commands

The CVS client program provides the user commands defined in Table 15-18.

Table 15-18. User commands

Command	Description
adaddnew	Indicate that files/directories should be added to the repository.
annannotate	Display contents of the head revision of a file, annotated with the revision number, user, and date of the last change for each line.
checkoutcoget	Create a sandbox for a module.
cicomcommit	Commit changes from the sandbox back to the repository.
didifdiff	View differences between file versions.
edit	Prepare to edit files. This is used for enhanced developer coordination.
editors	Display a list of users working on the files. This is used for enhanced developer coordination.
exexpexport	Retrieve a module, but don't make the result a sandbox.
help	Get help.
hihishistory	Display the log information for files.
imimpimport	Import new modules into the repository.
lgnloginlogon	Log into (cache the password for) a remote CVS server.
lolog	Show the activity log for the file(s).
logout	Log off from (flush the password for) a remote CVS server.
papatchrdiff	Release diff. The output is the format of input to Larry Wall's patch command. Does not have to be run from within a sandbox.
rannotate	Display contents of the head revision of a module, annotated with the revision number, user, and date of the last change for each line.
rerelrelease	Perform a logged delete on a sandbox.
rlog	Show the activity log for the module(s).
removermdelete	Remove a file or directory from the repository.
rtrtagrfreeze	Tag a particular revision.
ststatstatus	Show detailed status for files.
tatagfreeze	Attach a tag to files in the repository.
unedit	Abandon file modifications and make read-only again.
upupdupdate	Synchronize sandbox to repository.
version	Display the version of the CVS client (and server, if appropriate) being used.
watch	Manage the watch settings. This is used for enhanced developer coordination.
watchers	Display the list of users watching for changes to the files. This is used for enhanced developer coordination.

add  
 [ -k kflag ]  
 [ -m message ]  
 file ...

Indicate that files/directories should be added to the repository. They are not actually added until they are committed via cvs commit. This command is also used to resurrect files that have been deleted with cvs remove.

The standard meaning of the common client option -k applies. The only additional option that can be used with the add command is -m message. This option is used to provide a description of the file (which appears in the output of the log command).

annotate  
 [ [ -D date | -r rev ] -f ]  
 [ -F ]  
 [ -l | -R ]  
 file ...

CVS prints a report showing each line of the specified file. Each line is prefixed by information about the most recent change to the line, including the revision number, user, and date. If no revision is specified, the head of the trunk is used.

The standard meanings of the common client options -D, -f, -l, -r, and -R apply. There is one additional option:

-F

Annotate binary files. CVS normally skips binary files.

checkout  
 [ -A ]  
 [ -c | -s ]  
 [ -d dir [ -N ] ]  
 [ [ -D date | -r rev ] -f ]  
 [ -j rev1 [ -j rev2 ] ] 
 [ -k kflag ]  
 [ -l | -R ]  
 [ -n ]  
 [ -p ]  
 [ -P ]  
 module ...

Copy files from the repository to the sandbox.

The standard meanings of the common client options -D, -f, -k, -l, -n, -r, and -R apply. Additional options are:

-A

Reset any sticky tags or dates.

-c

Copy the module file to standard output.

-d dir

Override the default directory name.

-j rev

Join branches together.

-N

Don't shorten module paths.

-p

Pipe the files to standard output, with header lines between them showing the filename, RCS filename, and version.

-P

Prune empty directories.

-s

Show status for each module from the modules file.

commit  
 [ -f | [ -l | -R ] ]  
 [ -F file | -m message ]
 [ -n ]  
 [ -r revision ]  
 [ file ... ]

Commit the changes (if any) made to the specified files in the sandbox to the repository. If no files are specified, commit all modified files.

The standard meanings of the common client options -l, -n, -r, and -R apply. Use of the -r option causes the revision to be sticky, requiring the use of admin -A to continue to use the sandbox. Additional options are:

-f

Force commit, even if no changes were made.

-F file

Use the contents of the file as the message.

-m message

Use the message specified.

diff  
 [ -k kflag ]  
 [ -l | -R ]  [ format ]  
 [ [ -r rev1 | -D date1 ] [ -r rev2 | -D date2 ] ]
 [ file ... ]

Compare two versions of a file and display the differences in a format determined by the options. By default, the sandbox version of the file is compared to the repository version it was originally copied from.

The standard meanings of the common client options -D, -k, -l, -r, and -R apply. All options for the diff command can also be used.

edit  
 [ -a action ]  
 [ -l | -R ]  
 [ file ... ]

The edit command is used in conjunction with watch to permit a more coordinated (serialized) development process. It makes the file writable and sends out an advisory to any users that have requested them. A temporary watch is established and will be removed automatically when either the unedit or the commit command is issued.

The standard meanings of the common client options -l and -R apply. The only additional option that can be used with the edit command is -a actions. This option is used to specify the actions to watch. The legal values for actions are described in the entry for the watch command.

editors  
 [ -l | -R ]  
 [ file ... ]

Display a list of users working on the files specified. This is determined by checking which users have run the edit command on those files. If the edit command has not been used, no results are displayed.

The standard meanings of the common client options -l and -R apply.

See also watch.

export  
 [ -d dir [ -N ] ]  
 [ -D date | -r rev ]  
 [ -f ]  [ -k kflag ]  
 [ -l | -R ]  
 [ -n ]  
 [ -P ]  
 module ...

Export files from the repository, much like the checkout command, except that the result is not a sandbox (i.e., CVS subdirectories are not created). This can be used to prepare a directory for distribution. For example:

$ cvs export -r foo-1_0 -d foo-1.0 foo
$ tar czf foo-1.0.tar.gz foo-1.0

The standard meanings of the common client options -D, -f, -k, -l, -n, -r, and -R apply. Additional options are:

-d dir

Use dir as the directory name instead of using the module name.

-n

Don't run any checkout programs.

-N

Don't shorten paths.

When checking out a single file located one or more directories down in a module's directory structure, the -N option can be used with -d to prevent the creation of intermediate directories.

help

Display helpful information about using the cvs program.

history  
 [ -a | -u user ]  
 [ -b string ]  
 [ -c ]  
 [ -D date ]  
 [ -e | -x type ]  
 [ -f file | -m module | -n module | -p repository ]...   
 [ -l ]  
 [ -o ]  
 [ -r rev ]  
 [ -t tag ]  
 [ -T ]  
 [ -w ]  
 [ -x types ]  
 [ -z zone ]  
 [ file ... ]

Display historical information. To use the history command, you must first set up the history file in the repository. See Section 15.5.3 for more information on this file.

When used with the history command, the functions of -f, -l, -n, and -p are not the same as elsewhere in CVS.

The standard meanings of the common client options -D and -r apply. History is reported for activity subsequent to the date or revision indicated. Additional options are:

-a

Show history for all users (default is current user).

-b str

Show history back to the first record containing str in the module name, filename, or repository path.

-c

Report each commit.

-e

Report everything.

-f file

Show the most recent event for file.

-l

Show last event only.

-m module

Produce a full report on module.

-n module

Report the last event for module.

-o

Report on modules that have been checked out.

-p repository

Show history for a particular repository directory.

-t tag

Show history since tag was last added to the history file.

-T

Report on all tags.

-u name

Show history for a particular user.

-w

Show history only for the current working directory.

-x types

Report on specific types of activity. See Table 15-19.

-z zone

Display times according to the specified time zone.

The -p option should limit the history report to entries for the directory or directories (if multiple -p options are specified) given, but as of Version 1.10.8, it doesn't seem to affect the output. For example, to report history for the CVSROOT and hello modules, run the command:

cvs history -p CVSROOT -p hello

Using -t is faster than using -r because it only needs to search through the history file, not all of the RCS files.

The record types shown in Table 15-19 are generated by update commands.

Table 15-19. Update-related history record types

Type	Description
C	Merge was necessary, but conflicts requiring manual intervention occurred.
G	Successful automatic merge.
U	Working file copied from repository.
W	Working copy deleted.

The record types shown in Table 15-20 are generated by commit commands.

Table 15-20. Commit-related history record types

Type	Description
A	Added for the first time
M	Modified
R	Removed

Each of the record types shown in Table 15-21 is generated by a different command.

Table 15-21. Other history record types

Type	Command
E	export
F	release
O	checkout
T	rtag

import  
 [ -b branch ]  
 [ -d ]  
 [ -I pattern ]  
 [ -k kflag ]  
 [ -m message ]  
 [ -W spec ]  
 module  
 vendor_tag  
 release_tag ...

Import an entire directory into the repository as a new module. Used to incorporate code from outside sources or other code that was initially created outside the control of the CVS repository. More than one release_tag may be specified, in which case multiple symbolic tags will be created for the initial revision.

The vendor_tag argument is used to track third-party code that may be used in your project. By using different values for this argument, you can track the third-party code separately, and upgrade that portion of your code to a new release with a subsequent cvs import command. Since the argument is not optional, use some conventional value such as "vendor" whenever the code being imported should not be tracked separately.

The release_tag argument is used to associate a symbolic tag with the initial version of every file being imported. Since this argument is not optional, use some conventional value such as "start" whenever you don't have a more meaningful value to provide.

The standard meaning of the common client option -k applies. Additional options are:

-b branch

Import to a vendor branch.

-d

Use the modification date and time of the file instead of the current date and time as the import date and time. For local repository locators only.

-I pattern

Filename patterns for files to ignore.

-m message

Use message as the log message instead of invoking the editor.

-W spec

Wrapper specification.

The -k setting applies only to files imported during this execution of the command. The keyword substitution modes of files already in the repository are not modified.

When used with -W, the spec variable is in the same format as entries in the cvswrappers administrative file (see Section 15.5.3.6).

Table 15-22 describes the status codes displayed by the import command.

Table 15-22. import status codes

Status	Description
C	Changed. The file is in the repository, and the sandbox version is different; a merge is required.
I	Ignored. The .cvsignore file is causing CVS to ignore the file.
L	Link. Symbolic links are ignored by CVS.
N	New. The file is new; it has been added to the repository.
U	Update. The file is in the repository, and the sandbox version is not different.

log  
 [ -b ]  
 [ -d dates ]  
 [ -h ]  
 [ -N ]  
 [ -rrevisions ]  
 [ -R ]  
 [ -s states ]  
 [ -t ]  
 [ -wlogins ]  
 [ file ... ]

Print an activity log for the files.

The standard meaning of the common client option -l applies. Additional options are:

-b

List revisions on default branch.

-d dates

Report on these dates.

-h

Print header only.

-N

Don't print tags.

-r[revisions]

Report on the listed revisions. There is no space between -r and its argument. Without an argument, the latest revision of the default branch is used.

-R

Print RCS filename only. The usage of -R here is different from elsewhere in CVS (-R usually causes CVS to operate recursively).

-s states

Print only those revisions having one of the specified states.

-S

Don't print the header if the output would otherwise be empty.

-t

Print only header and descriptive text.

-wlogins

Report on checkins by the listed logins. There is no space between -w and its argument.

For -d, use the date specifications in Table 15-23. Multiple specifications separated by semicolons may be provided. For -s, separate multiple states with commas.

Table 15-23. log date range specifications

Specification	Description
d1<d2 or d2>d1	The revisions dated between d1 and d2, exclusive
d1<=d2 or d2>=d1	The revisions dated between d1 and d2, inclusive
<d or d>	The revisions dated before d
<=d or d>=	The revisions dated on or before d
d< or >d	The revisions dated after d
d<= or >=d	The revisions dated on or after d
d	The most recent revision dated d or earlier

For -r, use the revision specifications in Table 15-24.

Table 15-24. log revision specifications

Specification	Description
rev1: rev2	The revisions between rev1 and rev2, inclusive.
:rev	The revisions from the beginning of the branch to rev, inclusive.
rev:	The revisions from rev to the end of the branch, inclusive.
branch	All revisions on the branch.
branch1: branch2	All revisions on all branches between branch1 and branch2, inclusive.
branch.	The latest revision on the branch.

For rev1:rev2, it is an error if the revisions are not on the same branch.

login

Log into a remote repository. The password entered will be cached in the ~/.cvspass file, since a connection to the server is not maintained across invocations.

logout

Log out of a remote repository. The password cached in the ~/.cvspass file will be deleted.

rannotate  
 [ [ -D date | -r rev ] -f ]  
 [ -F ]  
 [ -l | -R ]  
 module ...

CVS prints a report showing each line of the specified module or module file. Each line is prefixed by information about the most recent change to the line, including the revision number, user, and date. If no revision is specified, the head of the trunk is used.

The rannotate command differs from the annotate command in that it refers directly to modules (and their files) in the repository rather than inferring the module based on the sandbox from which it is run. The first path component of each module argument must be a valid module for the repository.

The standard meanings of the common client options -D, -f, -l, -r, and -R apply. There is one additonal option:

-F

Annotate binary files. CVS normally skips binary files.

rdiff  
 [ -c | -s | -u ]  
 [ { { -D date1 | -r rev1 } [ -D date2 | -r rev2 ] } | -t ]  
 [ -f ]  
 [ -l | -R ]  
 [-V vn]  
 file ...

Create a patch file that can be used to convert a directory containing one release into a different release.

The standard meanings of the common client options -D, -f, -l, -r, and -R apply. Additional options are:

-c

Use context diff format (the default).

-s

Output a summary of changed files instead of a patch file.

-t

Show the differences between the two most recent revisions.

-u

Use unidiff format.

-V rcsver

Obsolete. Used to specify version of RCS to emulate for keyword expansion. (Keyword expansion emulates RCS Version 5.)

release
  [ -d ]
  directory ...

Sandboxes can be abandoned or deleted without using cvs release, but using the release command will log an entry to the history file (if this mechanism is configured) about the sandbox being destroyed. In addition, it will check the disposition (recursively) of each sandbox file before deleting anything. This can prevent destroying work that has not yet been committed.

There is only one option that can be used with the release command, -d. The -d option will delete the sandbox copy if no uncommitted changes are present.

New directories (including any files in them) in the sandbox will be deleted if the -d option is used with release.

The status codes listed in Table 15-25 are used to describe the disposition of each file encountered in the repository and the sandbox.

Table 15-25. release status Codes

Status	Description
A	The sandbox file has been added (the file was created and cvs add was run), but the addition has not been committed.
M	The sandbox copy of the file has been modified.
P U	Update available. There is a newer version of the file in the repository, and the copy in the sandbox has not been modified.
R	The sandbox copy was removed (the file was deleted and cvs remove was run), but the removal was not committed.
?	The file is present in the sandbox but not in the repository.

remove
  [ -f ]
  [ -l | -R ]
  [ file ... ]

Indicate that files should be removed from the repository. The files will not actually be removed until they are committed. Use cvs add to resurrect files that have been removed if you change your mind later.

The standard meanings of the common client options -l and -R apply. Only one other option may be used with the remove command, -f. When used, -f will delete the file from the sandbox first.

rlog
  [ -b ]
  [ -d dates ]
  [ -h ]  [ -N ]  [ -rrevisions ]
  [ -R ]
  [ -s state ]
  [ -t ]
  [ -wlogins ]
  [ module ... ]

Print an activity log for the modules.

The standard meaning of the common client option -l applies. Additional options are:

-b

List revisions on default branch.

-d dates

Report on these dates.

-h

Print header only.

-N

Don't print tags.

-r[revisions]

Report on the listed revisions. There is no space between -r and its argument. Without an argument, the latest revision of the default branch is used.

-R

Print RCS filename only. The usage of -R here is different from elsewhere in CVS (-R usually causes CVS to operate recursively).

-s state

Print only those revisions having the specified state.

-t

Print only header and descriptive text.

-wlogins

Report on checkins by the listed logins. There is no space between -w and its argument.

For -d, use the date specifications in Table 15-23. Multiple specifications separated by semicolons may be provided.

For -r, use the revision specifications in Table 15-24.

rtag
  [ -a ]
  [ -b ]
  [ -B ]
  [ -d ]
  [ -D date | -r rev ]
  [ -f ]
  [ -F ]
  [ -l | - R ]
  [ -n ]
  tag
  file ...

Assign a tag to a particular revision of a set of files. If the file already uses the tag for a different revision, cvs rtag will complain unless the -F option is used. This command does not refer to the sandbox file revisions (use cvs tag for that), so it can be run outside of a sandbox if desired.

The standard meanings of the common client options -D, -f, -l, -r, and -R apply. Additional options are:

-a

Search the attic for removed files containing the tag.

-b

Make it a branch tag.

-B

Allow movement or deletion of branch tags (used with -d or -F.)

-d

Delete the tag.

-F

Force. Move the tag from its current revision to the one specified.

-n

Don't run any tag program from the modules file.

status
  [ -l | -R ]
  [ -v ]
  [ file ... ]

Display the status of the files.

The standard meanings of the common client options -l and -R apply. You can use status -v to include tag information.

tag
  [ -b ]
  [ -c ]
  [ -d ]
  [ -D date | -r rev ]
  [ -f ]
  [ -F ]
  [ -l | R ]
  tag
  [ file ... ]

Assign a tag to the sandbox revisions of a set of files. You can use the status -v command to list the existing tags for a file.

The tag must start with a letter and consist entirely of letters, numbers, dashes, and underscores. Therefore, while you might want to tag your hello project with 1.0 when you release Version 1.0, you'll need to tag it with something like hello-1_0 instead.

The standard meanings of the common client options -D, -f, -l, -r, and -R apply. Additional options are:

-b

Make a branch.

-c

Check for changes. Make sure the files are not locally modified before tagging.

-d

Delete the tag.

-F

Force. Move the tag from its current revision to the one specified.

Since the -d option throws away information that might be important, it is recommended that you use it only when absolutely necessary. It is usually better to create a different tag with a similar name.

unedit
  [ -l | -R ]
  [ file ... ]

Abandon file modifications and make the file read-only again. Watchers will be notified.

The standard meanings of the common client options -l and -R apply.

update
  [ -A ]
  [ -C ]
  [ -d ]
  [ -D date | -r rev ]
  [ -f ]
  [ -I pattern ]
  [ -j rev1 [ -j rev2 ] ]
  [ -k kflag ]
  [ -l | -R ]
  [ -p ]
  [ -P ]
  [ -W spec ]
  [ file ... ]

Update the sandbox, merging in any changes from the repository. For example:

cvs -n -q update -AdP

can be used to do a quick status check of the current sandbox versus the head of the trunk of development.

The standard meanings of the common client options -D, -f, -k, -l, -r, and -R apply. Additional options are:

-A

Reset sticky tags.

-C

Replace modified files with clean copies.

-d

Create and update new directories.

-I pattern

Provide filename patterns for files to ignore.

-j revision

Merge in (join) changes between two revisions.

-p

Check out files to standard output.

-P

Prune empty directories.

-W spec

Provide wrapper specification.

When using -C, CVS makes backups of modified files before copying the clean version. The backup files are named .#file.revision.

Using -D or -r results in sticky dates or tags, respectively, on the affected files (using -p along with these prevents stickiness). Use -A to reset any sticky tags or dates.

If two -j specifications are made, the differences between them are computed and applied to the current file. If only one is given, then the common ancestor of the sandbox revision and the specified revision is used as a basis for computing differences to be merged. For example, suppose a project has an experimental branch, and important changes to the file foo.c were introduced between revisions 1.2.2.1 and 1.2.2.2. Once those changes have proven stable, you want them reflected in the main line of development. From a sandbox with the head revisions checked out, run:

$ cvs update -j 1.2.2.1 -j 1.2.2.2 foo.c

CVS finds the differences between the two revisions and applies those differences to the file in your sandbox.

The spec used with -W is in the same format as entries in the cvswrappers administrative file (see Section 15.5.3.6).

The status codes listed in Table 15-26 are used to describe the action taken on each file encountered in the repository and the sandbox.

Table 15-26. update status codes

Status	Description
A	Added. Server took no action because there was no repository file. Indicates that cvs add, but not cvs commit, has been run.
C	Conflict. Sandbox copy is modified (it has been edited since it was checked out or last committed). There was a new revision in the repository, and there were conflicts when CVS merged its changes into the sandbox version.
M	Modified. Sandbox copy is modified (it has been edited since it was checked out or last committed). If there was a new revision in the repository, its changes were successfully merged into the file (no conflicts).
P	Patched. Same as U, but indicates the server used a patch.
R	Removed. Server took no action. Indicates that cvs remove, but not cvs commit, has been run.
U	Updated. The file was brought up to date.
?	File is present in sandbox but not in repository.

version

Display the version of the CVS client (and server, if appropriate) being used.

watch
  { { on | off } | { add | remove } [ -a action ] }
  [ -l | -R ]
  file ...

The watch command controls CVS's edit tracking mechanism. By default, CVS operates in its concurrent development mode, allowing any user to edit any file at any time. CVS includes this watch mechanism to support developers who would rather be notified of edits made by others proactively than discover them when doing an update. The CVSROOT/notify file determines how notifications are performed.

Table 15-27 shows the watch subcommands and their uses.

Table 15-27. watch subcommands

Subcommand	Description
add	Start watching files.
off	Turn off watching.
on	Turn on watching.
remove	Stop watching files.

The standard meanings of the common client options -l and -R apply. The only other option that can be used with the watch command is -a action. The -a option is used in conjunction with one of the actions listed in Table 15-28.

Table 15-28. watch Actions

Action	Description
all	All of the following.
commit	A user has committed changes.
edit	A user ran cvs edit.
none	Don't watch. Used by the edit command.
unedit	A user ran cvs unedit, cvs release, or deleted the file and ran cvs update, re-creating it.

See also edit, editors, unedit, and watchers.

watchers
  [ -l | -R ]
  [ file ... ]

Display a list of users watching the specified files. This is determined by checking which users have run the watch command on a particular file (or set of files). If the watch command has not been used, no results will be displayed.

The standard meanings of the common client options -l and -R apply.

See also watch.