Go to the first, previous, next, last section, table of contents.


CVS Reference

This chapter is a complete reference to CVS commands, repository administrative files, keyword substitution, run control files, working copy files, and environment variables -- everything in CVS as of CVS version 1.10.7 (more accurately, as of August 20, 1999).

Commands And Options

This section is a reference to all CVS commands. If you are not already familiar with the syntactic conventions shared by most CVS commands, you should probably read the relevant subsections before you look up any particular command.

Organization And Conventions

This section is organized alphabetically to make it easy for you to look up a particular command or option. The following conventions are used:

General Patterns In CVS Commands

CVS commands follow this form:

cvs [GLOBAL_OPTIONS] COMMAND [OPTIONS] [FILES]

The second set of options is sometimes called command options. Because there are so many of them, though, I'll just call them "options" in most places to save space.

Many commands are meant to be run within a working copy and, therefore, may be invoked without file arguments. These commands default to all of the files in the current directory and below. So when I refer to the "file" or "files" in the text, I'm talking about the files on which CVS is acting. Depending on how you invoked CVS, these files may or may not have been explicitly mentioned on the command line.

Date Formats

Many options take a date argument. CVS accepts a wide variety of date formats -- too many to list here. When in doubt, stick with the standard ISO 8601 format:

1999-08-23

This means "23 August 1999" (in fact, "23 August 1999" is a perfectly valid date specifier too, as long as you remember to enclose it in double quotes). If you need a time of day as well, you can do this:

"1999-08-23 21:20:30 CDT"

You can even use certain common English constructs, such as "now", "yesterday", and "12 days ago". In general, you can safely experiment with date formats; if CVS understands your format at all, it most likely will understand it in the way you intended. If it doesn't understand, it will exit with an error immediately.

Global Options

Here are all the global options to CVS.

--allow-root=REPOSITORY

The alphabetically first global option is one that is virtually never used on the command line. The --allow-root option is used with the pserver command to allow authenticated access to the named repository (which is a repository top level, such as `/usr/local/newrepos', not a project subdirectory such as `/usr/local/newrepos/myproj').

This global option is virtually never used on the command line. Normally, the only place you'd ever use it is in /etc/inetd.conf files (see section Repository Administration), which is also about the only place the pserver command is used.

Every repository to be accessed via cvs pserver on a given host needs a corresponding --allow-root option in `/etc/inetd.conf'. This is a security device, meant to ensure that people can't use a CVS pserver to gain access to private repositories.

(See section The Password-Authenticating Server also the node Password Authentication Server in the Cederqvist manual.)

-a

This authenticates all communications with the server. This option has no effect unless you're connecting via the GSSAPI server (gserver). GSSAPI connections are not covered in this book, because they're still somewhat rarely used (although that may change). (See the nodes Global Options and GSSAPI Authenticated in the Cederqvist manual for more information.)

-b (Obsolete)

This option formerly specified the directory where the RCS binaries could be found. CVS now implements the RCS functions internally, so this option has no effect (it is kept only for backward compatibility).

-d REPOSITORY

This specifies the repository, which might be an absolute pathname or a more complex expression involving a connection method, username and host, and path. If it is an expression specifying a connection method, the general syntax is:

:METHOD:USER@HOSTNAME:PATH_TO_REPOSITORY

Here are examples using each of the connection methods:

-e EDITOR

Invokes EDITOR for your commit message, if the commit message was not specified on the command line with the -m option. Normally, if you don't give a message with -m, CVS invokes the editor based on the $CVSEDITOR, $VISUAL, or $EDITOR environment variables, which it checks in that order. Failing that, it invokes the popular Unix editor vi.

If you pass both the -e global option and the -m option to commit, the -e is ignored in favor of the commit message given on the command line (that way it's safe to use -e in a `.cvsrc' file).

-f

This global option suppresses reading of the `.cvsrc' file.

--help [COMMAND] or -H [COMMAND]

These two options are synonymous. If no COMMAND is specified, a basic usage message is printed to the standard output. If COMMAND is specified, a usage message for that command is printed.

--help-options

Prints out a list of all global options to CVS, with brief explanations.

--help-synonyms

Prints out a list of CVS commands and their short forms ("up" for "update", and so on).

-l

Suppresses logging of this command in the `CVSROOT/history' file in the repository. The command is still executed normally, but no record of it is made in the history file.

-n

Doesn't change any files in the working copy or in the repository. In other words, the command is executed as a "dry run" -- CVS goes through most of the steps of the command but stops short of actually running it.

This is useful when you want to see what the command would have done had you actually run it. One common scenario is when you want to see what files in your working directory have been modified, but not do a full update (which would bring down changes from the repository). By running cvs -n update, you can see a summary of what's been done locally, without changing your working copy.

-q

This tells CVS to be moderately quiet by suppressing the printing of unimportant informational messages. What is considered "important" depends on the command. For example, in updates, the messages that CVS normally prints on entering each subdirectory of the working copy are suppressed, but the one-line status messages for modified or updated files are still printed.

-Q

This tells CVS to be very quiet, by suppressing all output except what is absolutely necessary to complete the command. Commands whose sole purpose is to produce some output (such as diff or annotate), of course, still give that output. However, commands that could have an effect independent of any messages that they may print (such as update or commit) print nothing.

-r

Causes new working files to be created read-only (the same effect as setting the $CVSREAD environment variable).

If you pass this option, checkouts and updates make the files in your working copy read-only (assuming your operating system permits it). Frankly, I'm not sure why one would ever want to use this option.

-s VARIABLE=VALUE

This sets an internal CVS variable named VARIABLE to VALUE.

On the repository side, the `CVSROOT/*info' trigger files can expand such variables to values that were assigned in the -s option. For example, if `CVSROOT/loginfo' contains a line like this

myproj  /usr/local/bin/foo.pl ${=FISH}

and someone runs a commit from a myproj working copy like this

floss$ cvs -s FISH=carp commit -m "fixed the bait bug"

the `foo.pl' script is invoked with carp as an argument. Note the funky syntax, though: The dollar sign, equal sign, and curly braces are all necessary -- if any of them are missing, the expansion will not take place (at least not as intended). Variable names may contain alphanumerics and underscores only. Although it is not required that they consist entirely of capital letters, most people do seem to follow that convention.

You can use the -s flag as many times as you like in a single command. However, if the trigger script refers to variables that aren't set in a particular invocation of CVS, the command still succeeds, but none of the variables are expanded, and the user sees a warning. For example, if loginfo has this

myproj  /usr/local/bin/foo.pl  ${=FISH}  ${=BIRD}

but the same command as before is run

floss$ cvs -s FISH=carp commit -m "fixed the bait bug"

the person running the command sees a warning something like this (placed last in the output)

loginfo:31: no such user variable ${=BIRD}

and the `foo.pl' script is invoked with no arguments. But if this command were run

floss$ cvs -s FISH=carp -s BIRD=vulture commit -m "fixed the bait bug"

there would be no warning, and both ${=FISH} and ${=BIRD} in loginfo would be correctly expanded. In either case, the commit itself would still succeed.

Although these examples all use commit, variable expansion can be done with any CVS command that can be noticed in a `CVSROOT/' trigger file -- which is why the -s option is global.

(See the section section Repository Administrative Files later in this chapter for more details about variable expansion in trigger files.)

-T DIR

Stores any temporary files in DIR instead of wherever CVS normally puts them (specifically, this overrides the value of the $TMPDIR environment variable, if any exists). DIR should be an absolute path.

This option is useful when you don't have write permission (and, therefore, CVS doesn't either) to the usual temporary locations.

-t

Traces the execution of a CVS command. This causes CVS to print messages showing the steps that it's going through to complete a command. You may find it particularly useful in conjunction with the -n global option, to preview the effects of an unfamiliar command before running it for real. It can also be handy when you're trying to discover why a command failed.

-v or --version

Causes CVS to print out its version and copyright information and then exit with no error.

-w

Causes new working files to be created read-write (overrides any setting of the $CVSREAD environment variable). Because files are created read-write by default anyway, this option is rarely used.

If both -r and -w are passed, -w dominates.

-x

Encrypts all communications with the server. This option has no effect unless you're connecting via the GSSAPI server (gserver). GSSAPI connections are not covered in this book, because they're still somewhat rarely used (although that may change). (See the nodes Global Options and GSSAPI Authenticated in the Cederqvist manual for more information.)

-z GZIPLEVEL

Sets the compression level on communications with the server. The argument GZIPLEVEL must be a number from 1 to 9. Level 1 is minimal compression (very fast, but doesn't compress much); Level 9 is highest compression (uses a lot of CPU time, but sure does squeeze the data). Level 9 is only useful on very slow network connections. Most people find levels between 3 and 5 to be most beneficial.

A space between -z and its argument is optional.

add

Synopsis: add [OPTIONS] FILES

Adds a new file or files to an existing project. Although the repository is contacted for confirmation, the file does not actually appear in it until a subsequent commit is performed. (See also section remove and section import.)

Options:

admin

Synopsis: admin [OPTIONS] [FILES]

This command is an interface to various administrative tasks -- specifically, tasks applicable to individual RCS files in the repository, such as changing a file's keyword substitution mode or changing a log message after it's been committed.

Although admin behaves recursively if no files are given as arguments, you normally will want to name files explicitly. It's very rare for a single admin command to be meaningful when applied to all files in a project, or even in a directory. Accordingly, when the following explanations refer to the "file", they mean the file or (rarely) files passed as arguments to the admin command.

If there is a system group named cvsadmin on the repository machine, only members of that group can run admin (with the exception of the cvs admin -k command, which is always permitted). Thus you can disallow admin for all users by setting the group to have no users.

Options:

annotate

Synopsis: annotate [OPTIONS] [FILES]

Shows information on who last modified each line of each file and when. Each line of output corresponds to one line of the file. From left to right, the line displays the revision number of the last modification of that line, a parenthetical expression containing the user and date of the modification, a colon, and the contents of the line in the file.

For example, if a file looks like this

this is a test file
it only has too lines
I mean "two"

the annotations for that file could look like this

1.1          (jrandom  22-Aug-99): this is a test file
1.1          (jrandom  22-Aug-99): it only has too lines
1.2          (jrandom  22-Aug-99): I mean "two"

from which you would know that the first two lines were in the initial revision, and the last line was added or modified (also by jrandom) in Revision 1.2.

Options:

checkout

Synopsis: checkout [OPTIONS] PROJECT(S)

Checks out a module from the repository into a working copy. The working copy is created if it doesn't exist already and updated if it does. (See also section update.)

Options:

commit

Synopsis: commit [OPTIONS] [FILES]

Commits changes from a working copy to the repository.

Options:

diff

Synopsis: diff [OPTIONS] [FILES]

Shows the difference between two revisions (in Unix diff format). When invoked with no options, CVS diffs the repository base revisions against the (possibly uncommitted) contents of the working copy. The base revisions are the latest revisions of this working copy retrieved from the repository; note that there could be even later revisions in the repository, if someone else committed changes but this working copy hasn't been updated yet. (See also section rdiff.)

Options:

Diff Compatibility Options

In addition to the preceding options, cvs diff also shares a number of options with the GNU version of the standard command-line diff program. Following is a complete list of these options, along with an explanation of a few of the most commonly used ones. (See the GNU diff documentation for the others.)

-0 -1 -2 -3 -4 -5 -6 -7 -8 -9 
    --binary
    --brief
    --changed-group-format=ARG
    -c
      -C NLINES
      --context[=LINES]
    -e --ed
    -t --expand-tabs
    -f --forward-ed
    --horizon-lines=ARG
    --ifdef=ARG
    -w --ignore-all-space
    -B --ignore-blank-lines
    -i --ignore-case
    -I REGEXP
       --ignore-matching-lines=REGEXP
    -h
    -b --ignore-space-change
    -T --initial-tab
    -L LABEL
      --label=LABEL
    --left-column
    -d --minimal
    -N --new-file
    --new-line-format=ARG
    --old-line-format=ARG
    --paginate
    -n --rcs
    -s --report-identical-files
    -p
    --show-c-function
    -y --side-by-side
    -F REGEXP
    --show-function-line=REGEXP
    -H --speed-large-files
    --suppress-common-lines
    -a --text
    --unchanged-group-format=ARG
    -u
      -U NLINES
      --unified[=LINES]
    -V ARG
    -W COLUMNS
      --width=COLUMNS

Following are the GNU diff options most frequently used with cvs diff.

edit

Synopsis: edit [OPTIONS] [FILES]

Signals that you are about to begin editing a watched file or files. Also adds you as a temporary watcher to the file's watch list (you'll be removed when you do cvs unedit). (See also section watch, section watchers, section unedit, and section editors.)

Options:

editors

Synopsis: editors [OPTIONS] [FILES]

Shows who is currently editing a watched file. (See also section watch, section watchers, section edit, and section unedit.)

Options:

export

Synopsis: export [OPTIONS] PROJECT(S)

Exports files from the repository to create a project tree that is not a working copy (has no CVS/ administrative subdirectories). Useful mainly for packaging distributions.

Options:

gserver

Synopsis: gserver

This is the GSSAPI (Generic Security Services API) server. This command is not normally run directly by users. Instead, it is started up on the server side when a user connects from a client with the :gserver: access method:

cvs -d :gserver:floss.red-bean.com:/usr/local/newrepos checkout myproj

GSSAPI provides, among other things, Kerberos Version 5; for Kerberos Version 4, use :kserver:.

Setting up and using a GSSAPI library on your machines is beyond the scope of this book. (See the node GSSAPI Authenticated in the Cederqvist manual for some useful hints, however.)

Options: None.

history [OPTIONS] [FILENAME_SUBSTRING(S)]

Shows a history of activity in the repository. Specifically, this option shows records of checkouts, commits, rtags, updates, and releases. By default, the option shows checkouts (but see the -x option). This command won't work if there's no CVSROOT/history file in the repository.

The history command differs from other CVS commands in several ways. First, it must usually be given options to do anything useful (and some of those options mean different things for history than they do elsewhere in CVS). Second, instead of taking full file names as arguments, it takes one or more substrings to match against file names (all records matching at least one of those substrings are retrieved). Third, history's output looks a lot like line noise until you learn to read it, so I'll explain the output format in a special section, after the options. (See also section log.)

Options:

History Output

The output of the history command is a series of lines; each line represents one "history event" and starts with a single code letter indicating what type of event it is. For example:

floss$ cvs history -D yesterday -x TMO
M 08/21 20:19 +0000 jrandom 2.2              baar       myproj == <remote>
M 08/22 04:18 +0000 jrandom 1.2              README     myproj == <remote>
O 08/22 05:15 +0000 jrandom myproj =myproj= ~/src/*
M 08/22 05:33 +0000 jrandom 2.18             README.txt myproj == ~/src/myproj
O 08/22 14:25 CDT jrandom myproj =myproj= ~/src/*
O 08/22 14:26 CDT jrandom [99.08.23.19.26.03] myproj =myproj= ~/src/*
O 08/22 14:28 CDT jrandom [Exotic_Greetings-branch] myproj =myproj= ~/src/*

The code letters are the same as for the -x option just described. Following the code letter is the date of the event (expressed in UTC/GMT time, unless the -z option is used), followed by the user responsible for the event.

After the user might be a revision number, tag, or date, but only if such is appropriate for the event (date or tag will be in square brackets and formatted as shown in the preceding example). If you commit a file, it shows the new revision number; if you check out with -D or -r, the sticky date or tag is shown in square brackets. For a plain checkout, nothing extra is shown.

Next comes the name of the file in question, or module name if the event is about a module. If the former, the next two things are the module/project name and the location of the working copy in the user's home directory. If the latter, the next two things are the name of the module's checked-out working copy (between two equal signs), followed by its location in the user's home directory. (The name of the checked-out working copy may differ from the module name if the -d flag is used with checkout.)

import

Synopsis: import [OPTIONS] REPOSITORY VENDOR_TAG RELEASE_TAG(S)

Imports new sources into the repository, either creating a new project or creating a new vendor revision on a vendor branch of an existing project. (See section Advanced CVS for a basic explanation of vendor branches in import, which will help you to understand the following.)

It's normal to use import to add many files or directories at once or to create a new project. To add single files, you should use add.

Options:

init

Synopsis: init NEW_REPOSITORY

Creates a new repository (that is, a root repository in which many different projects are stored). You will almost always want to use the global -d option with this, as in

floss$ cvs -d /usr/local/yet_another_repository init

because even if you have a CVSROOT environment variable set, it's probably pointing to an existing repository, which would be useless and possibly dangerous in the context of this command. (See section Repository Administration for additional steps that you should take after initializing a new repository.)

Options: None.

kserver

Synopsis: kserver

This is the Kerberos server. (If you have Kerberos libraries Version 4 or below -- Version 5 just uses GSSAPI, see section gserver.) This command is not normally run directly by users but is instead started up on the server side when a user connects from a client with the :kserver: access method:

cvs -d :kserver:floss.red-bean.com:/usr/local/newrepos checkout myproj

Setting up and using Kerberos on your machine is beyond the scope of this book. (However, see the node Kerberos Authenticated in the Cederqvist manual for some useful hints.)

Options: None.

log

Synopsis: log [OPTIONS] [FILES]

Shows log messages for a project, or for files within a project. The output of log is not quite in the same style as the output of other CVS commands, because log is based on an older RCS program (rlog). Its output format gives a header, containing various pieces of non-revision-specific information about the file, followed by the log messages (arranged by revision). Each revision shows not merely the revision number and log message, but also the author and date of the change and the number of lines added or deleted. All times are printed in UTC (GMT), not local time.

Because log output is per file, a single commit involving multiple files may not immediately appear as a conceptually atomic change. However, if you read all of the log messages and dates carefully, you may be able to reconstruct what happened. (For information about a tool that can reformat multifile log output into a more readable form, see section cvs2cl.pl -- Generate GNU-Style ChangeLogs in section Third-Party Tools for details.) (See also section history.)

Options:

As you read over the following filtering options, it may not be completely clear how they behave when combined. A precise description of log's behavior is that it takes the intersection of the revisions selected by -d, -s, and -w, intersected with the union of those selected by -b and -r.

login

Synopsis: login

Contacts a CVS server and confirms authentication information for a particular repository. This command does not affect either the working copy or the repository; it just confirms a password (for use with the :pserver: access method) with a repository and stores the password for later use in the .cvspass file in your home directory. Future commands accessing the same repository with the same username will not require you to rerun login, because the client-side CVS will just consult the .cvspass file for the password.

If you use this command, you should specify a repository using the pserver access method, like this

floss$ cvs -d :pserver:jrandom@floss.red-bean.com:/usr/local/newrepos

or by setting the CVSROOT environment variable.

If the password changes on the server side, you have to rerun login.

Options: None.

logout

Synopsis: logout

The opposite of login -- removes the password for this repository from .cvspass.

Options: None.

pserver

Synopsis: pserver

This is the password-authenticating server. This command is not normally run directly by users but is started up from `/etc/inetd.conf' on the server side when a user connects from a client with the :pserver: access method. (See also section login, section logout, and section .cvspass in the section Run Control Files section in this chapter. See section Repository Administration for details on setting up a password-authenticating CVS server.)

Options: None.

rdiff

Synopsis: rdiff [OPTIONS] PROJECTS

Like the diff command, except it operates directly in the repository and, therefore, requires no working copy. This command is meant for obtaining the differences between one release and another of your project, in a format suitable as input to the patch program (perhaps so you can distribute patch files to users who want to upgrade).

The operation of the patch program is beyond the scope of this book. However, note that if the patch file contains diffs for files in subdirectories, you may need to use the -p option to patch to get it to apply the differences correctly. (See the patch documentation for more about this.) (See also section diff.)

Options:

release

Synopsis: release [OPTIONS] DIRECTORY

Cancels a checkout (indicates that a working copy is no longer in use). Unlike most CVS commands that operate on a working copy, this one is not invoked from within the working copy but from directly above it (in its parent directory). You either have to set your CVSROOT environment variable or use the -d global option, as CVS will not be able to find out the repository from the working copy.

Using release is never necessary. Because CVS doesn't normally do locking, you can just remove your working copy.

However, if you have uncommitted changes in your working copy or you want your cessation of work to be noted in the CVSROOT/history file (see the history command), you should use release. CVS first checks for any uncommitted changes; if there are any, it warns you and prompts for continuation. Once the working copy is actually released, that fact is recorded in the repository's CVSROOT/history file.

Options:

If you created any new directories inside your working copy but did not add them to the repository, they are deleted along with the rest of the working copy, if you specified the -d flag.

remove

Synopsis: remove [OPTIONS] [FILES]

Removes a file from a project. Normally, the file itself is removed from disk when you invoke this command (but see -f). Although this command operates recursively by default, it is common to explicitly name the files being removed. Note the odd implication of the previous sentence: Usually, you run cvs remove on files that don't exist anymore in your working copy.

Although the repository is contacted for confirmation, the file is not actually removed until a subsequent commit is performed. Even then, the RCS file is not really removed from the repository; if it is removed from the trunk, it is just moved into an Attic/ subdirectory, where it is still available to exist on branches. If it is removed from a branch, its location is not changed, but a new revision with state dead is added on the branch. (See also section add.)

Options:

rtag

Synopsis: rtag [OPTIONS] TAG PROJECT(S)

Tags a module directly in the repository (requires no working copy). You probably need to have your CVSROOT environment variable set or use the -d global option for this to work. (See also section tag.)

Options:

server

Synopsis: server

Starts up a CVS server. This command is never invoked by users (unless they're trying to debug the client/server protocol), so forget I even mentioned it.

Options: None.

status

Synopsis: status [OPTIONS] [FILES]

Shows the status of files in the working copy.

Options:

tag

Synopsis: tag [OPTIONS] TAG [FILES]

Attaches a name to a particular revision or collection of revisions for a project. Often called "taking a snapshot" of the project. This command is also used to create branches in CVS. (See the -b option -- see also section rtag.)

Options:

unedit

Synopsis: unedit [OPTIONS] [FILES]

Signals to watchers that you are done editing a file. (See also section watch, section watchers, section edit, and section editors.)

Options:

update

Synopsis: update [OPTIONS] [FILES]

Merges changes from the repository into your working copy. As a side effect, it indicates which files in your working copy are modified (but if the -Q global option is passed, these indications won't be printed). (See also section checkout.)

Options:

watch

Synopsis: watch on|off|add|remove [OPTIONS] [FILES]

Sets a watch on one or more files. Unlike most CVS commands, watch requires a further subcommand to do something useful. (See also section watchers, section edit, section editors, and section unedit, and section users.)

Subcommands:

Options (for use with any watch subcommand). All three options have the same meanings as for edit:

watchers

Synopsis: watchers [OPTIONS] [FILES]

Shows who's watching what files.

Options -- these options mean the same thing here as for section edit:

Keyword Substitution (RCS Keywords)

CVS can perform certain textual substitutions in files, allowing you to keep some kinds of information automatically up to date in your files. All of the substitutions are triggered by a certain keyword pattern, surrounded by dollar signs. For example,

$Revision$

in a file expands to something like

$Revision: 1.5 $

and CVS continues to keep the revision string up to date as new revisions are committed.

Controlling Keyword Expansion

By default, CVS performs keyword expansion unless you tell it to stop. You can permanently suppress keyword expansion for a file with the -k option when you add the file to the project, or you can turn it off later by invoking admin with -k. The -k option offers several different modes of keyword control; usually you want mode o or b, for example:

floss$ cvs add -ko chapter-9.sgml

This command added `chapter-9.sgml' to the project with keyword expansion turned off. It sets the file's default keyword expansion mode to o, which means no substitution. (Actually, the "o" stands for "old", meaning to substitute the string with its old value, which is the same as substituting it for itself, resulting in no change. I'm sure this logic made sense to somebody at the time.)

Each file's default keyword mode is stored in the repository. However, each working copy can also have its own local keyword substitution mode -- accomplished with the -k options to checkout or update. You can also have a mode in effect for the duration of just one command, with the -k option to diff.

Here are all the possible modes, presented with the -k option prepended (as one would type at a command line). Any of these options can be used as either the default or local keyword substitution mode for a file:

List Of Keywords

These are all the dollar-sign-delimited keywords that CVS recognizes. Following is a list of the keyword, a brief description, and an example of its expanded form:

Repository Administrative Files

The repository's administrative files are stored in the CVSROOT subdirectory of the repository. These files control various aspects of CVS's behavior (in that repository only, of course).

You may also want to refer to the discussion of administrative files in section Repository Administration, which includes examples.

Storage And Editing

Generally, the administrative files are kept under revision control just like any other file in the repository (the exceptions are noted). However, unlike other files, checked-out copies of the administrative files are stored in the repository, right next to their corresponding RCS files in the `CVSROOT' subdirectory. It is these checked-out copies which actually govern CVS's behavior.

The normal way to modify the administrative files is to check out a working copy of the CVSROOT module, make your changes, and commit. CVS updates the checked-out copies in the repository automatically. (See section checkoutlist.) In an emergency, however, it is also possible to edit the checked-out copies in the repository directly.

Shared Syntax

In all of the administrative files, a # at the beginning of a line signifies a comment; that line is ignored by CVS. A backslash preceding a newline quotes the newline out of existence.

Some of the files (commitinfo, loginfo, taginfo, and rcsinfo) share more syntactic conventions as well. In these files, on the left of each line is a regular expression (which is matched against a file or directory name), and the rest of the line is a program, possibly with arguments, which is invoked if something is done to a file matching the regular expression. The program is run with its working directory set to the top of the repository.

In these files, there are two special regular expressions that may be used: ALL and DEFAULT. ALL matches any file or directory, whether or not there is some other match for it, and DEFAULT matches only if nothing else matched.

Shared Variables

The info files also allow certain variables to be expanded at runtime. To expand a variable, precede it with a dollar sign (and put it in curly braces just to be safe). Here are the variables CVS knows about:

User Variables

Users can set also set their own variables when they run any CVS command. (See the -s global option.) These variables can be accessed in the `*info' files by preceding them with an equal sign, as in ${=VAR}.

checkoutlist

This contains a list of files for which checked-out copies should be kept in the repository. Each line gives the file name and an error message for CVS to print if, for some reason, the file cannot be checked out in the repository:

FILENAME  ERROR_MESSAGE

Because CVS already knows to keep checked-out copies of the existing administrative files, they do not need to be listed in checkoutlist. Specifically, the following files never need entries in checkoutlist: loginfo, rcsinfo, editinfo, verifymsg, commitinfo, taginfo, ignore, checkoutlist, cvswrappers, notify, modules, readers, writers, and config.

commitinfo

Specifies programs to run at commit time, based on what's being committed. Each line consists of a regular expression followed by a command template:

REGULAR_EXPRESSION PROGRAM [ARGUMENTS]

The PROGRAM is passed additional arguments following any arguments you may have written into the template. These additional arguments are the full path to the repository, followed by the name of each file about to be committed. These files can be examined by PROGRAM; their contents are the same as those of the working copy files about to be committed. If PROGRAM exits with nonzero status, the commit fails; otherwise, it succeeds. (See also section Shared Syntax earlier in this chapter.)

config

Controls various global (non-project-specific) repository parameters. The syntax of each line is

ParameterName=yes|no

except for the LockDir parameter, which takes an absolute pathname as argument.

The following parameters are supported:

cvsignore

Ignores certain files when doing updates, imports, or releases. By default, CVS already ignores some kinds of files. (For a full list, see the -I option to import, earlier in this chapter.) You can add to this list by putting additional file names or wildcard patterns in the cvsignore file. Each line gives a file name or pattern, for example:

README.msdos
*.html
blah?.out

This causes CVS to ignore any file named `README.msdos', any file ending in `.html', and any file beginning with `blah' and ending with `.out'. (Technically, you can name multiple files or patterns on each line, separated by whitespace, but it is more readable to keep them to one per line. The whitespace separation rule does, unfortunately, mean that there's no way to specify a space in a file name, except to use wildcards.)

A ! anywhere in the list cancels all previous entries. (See section $CVSIGNORE in the section section Environment Variables in this chapter for a fuller discussion of ignore processing.)

cvswrappers

Specifies certain filtering behaviors based on file name. Each line has a file-globbing pattern (that is, a file name or file wildcards), followed by an option indicating the filter type and an argument for the option.

Options:

Here is an example cvswrappers file:

*.blob    -m COPY
*.blink   -k o

This cvswrappers file says to not attempt merges on files ending in `.blob' and suppress keyword substitution for files ending in `.blink'. (See also section .cvswrappers in the section Working Copy Files section in this chapter.)

editinfo

This file is obsolete. Very.

history

Stores an ever-accumulating history of activity in the repository, for use by the cvs history command. To disable this feature, simply remove the history file. If you don't remove the file, you should probably make it world-writeable to avoid permission problems later.

The contents of this file do not modify CVS's behavior in any way (except for the output of cvs history, of course).

loginfo

Specifies programs to run on the log message for each commit, based on what's being committed. Each line consists of a regular expression followed by a command template:

REGULAR_EXPRESSION PROGRAM [ARGUMENTS]

The PROGRAM is passed the log message on its standard input.

Several special codes are available for use in the arguments: %s expands to the names of the files being committed, %V expands to the old revisions from before the commit, and %v expands to the new revisions after the commit. When there are multiple files involved, each element of the expansion is separated from the others by whitespace. For example, in a commit involving two files, %s might expand into hello.c README.txt, and %v into 1.17 1.12.

You may combine codes inside curly braces, in which case, each unit of expansion is internally separated by commas and externally separated from the other units by whitespace. Continuing the previous example, %{sv} expands into hello.c,1.17 README.txt,1.12.

If any % expansion is done at all, the expansion is prefixed by the full path of the repository. So that last expansion would actually be:

/usr/local/newrepos  hello.c,1.17  README.txt,1.12

If PROGRAM exits with nonzero status, the commit fails; otherwise, it succeeds. (See also the section Shared Syntax section in this chapter.)

modules

This maps names to repository directories. The general syntax of each line is:

MODULE [OPTIONS] [&OTHERMODULE...] [DIR] [FILES]

DIR need not be a top-level project directory -- it could be a subdirectory. If any FILES are specified, the module consists of only those files from the directory.

An ampersand followed by a module name means to include the expansion of that module's line in place.

Options:

notify

Controls how the notifications for watched files are performed. (You may want to read up on the watch and edit commands, or see the section section Watches (CVS As Telephone) in section Advanced CVS.) Each line is of the usual form:

REGULAR_EXPRESSION PROGRAM [ARGUMENTS]

A %s in ARGUMENTS is expanded to the name of the user to be notified, and the rest of the information regarding the notification is passed to PROGRAM on standard input (usually this information is a brief message suitable for emailing to the user). (See the section section Shared Syntax earlier in this chapter.)

As shipped with CVS, the notify file has one line

ALL mail %s -s "CVS notification"

which is often all you need.

passwd

Provides authentication information for the pserver access method. Each line is of the form:

USER:ENCRYPTED_PASSWORD[:SYSTEM_USER]

If no SYSTEM_USER is given, USER is taken as the system username.

rcsinfo

Specifies a form that should be filled out for log messages that are written with an interactive editor. Each line of rcsinfo looks like:

REGULAR_EXPRESSION FILE_CONTAINING_TEMPLATE

This template is brought to remote working copies at checkout time, so if the template file or rcsinfo file changes after checkout, the remote copies won't know about it and will continue to use the old template. (See also the section section Shared Syntax in this chapter.)

taginfo

Runs a program at tag time (usually done to check that the tag name matches some pattern). Each line is of the form:

REGULAR_EXPRESSION PROGRAM

The program is handed a set group of arguments. In order, they are the tag name, the operation (see below), the repository, and then as many file name/revision-number pairs as there are files involved in the tag. The file/revision pairs are separated by whitespace, like the rest of the arguments.

The operation is one of add, mov, or del (mov means the -F option to tag was used).

If PROGRAM exits with nonzero status, the tag operation will not succeed. (See also the section section Shared Syntax in this chapter.)

users

Maps usernames to email addresses. Each line looks like:

USERNAME:EMAIL_ADDRESS

This sends watch notifications to EMAIL_ADDRESS instead of to USERNAME at the repository machine. (All this really does is control the expansion of %s in the notify file.) If EMAIL_ADDRESS includes whitespace, make sure to surround it with quotes.

If user aliasing is being used in the passwd file, the username that will be matched is the CVS username (the one on the left), not the system username (the one on the right, if any).

val-tags

Caches valid tag names for speedier lookups. You should never need to edit this file, but you may need to change its permissions, or even ownership, if people are having trouble retrieving or creating tags.

verifymsg

Used in conjunction with rcsinfo to verify the format of log messages. Each line is of the form:

REGULAR_EXPRESSION PROGRAM [ARGUMENTS]

The full path to the current log message template (see section rcsinfo earlier in this chapter) is appended after the last argument written in the verifymsg file. If PROGRAM exits with nonzero status, the commit fails.

Run Control Files

There are a few files on the client (working copy) side that affect CVS's behavior. In some cases, they are analogs of repository administrative files; in other cases, they control behaviors that are only appropriate for the client side.

.cvsrc

Specifies options that you want to be used automatically with every CVS command. The format of each line is

COMMAND OPTIONS

where each COMMAND is an unabbreviated CVS command, such as checkout or update (but not co or up). The OPTIONS are those that you want to always be in effect when you run that command. Here is a common `.cvsrc' line:

update -d -P

To specify global options, simple use cvs as the COMMAND.

.cvsignore

Specifies additional ignore patterns. (See section cvsignore in the section Repository Administrative Files section in this chapter for the syntax.)

You can have a .cvsignore file in your home directory, which will apply every time you use CVS. You can also have directory-specific ones in each project directory of a working copy (these last only apply to the directory where the .cvsignore is located, and not to its subdirectories).

(See section $CVSIGNORE in the section section Environment Variables in this chapter, for a fuller discussion of ignore processing.)

.cvspass

Stores passwords for each repository accessed via the pserver method. Each line is of the form:

REPOSITORY LIGHTLY_SCRAMBLED_PASSWORD

The password is essentially stored in cleartext -- a very mild scrambling is done to prevent accidental compromises (such as the root user unintentionally looking inside the file). However, this scrambling will not deter any serious-minded person from gaining the password if they get access to the file.

The .cvspass file is portable. You can copy it from one machine to another and have all of your passwords at the new machine, without ever having run cvs login there. (See also the section login and section logout commands.)

.cvswrappers

This is a client side version of the cvswrappers file. (See the section Repository Administrative Files section in this chapter.) There can be a `.cvswrappers' file in your home directory and in each directory of a working copy directory, just as with `.cvsignore'.

Working Copy Files

The CVS/ administrative subdirectories in each working copy contain some subset of the following files.

CVS/Base/ (directory)

`CVS/Base/' (directory)

If watches are on, cvs edit stores the original copy of the file in this directory. That way, cvs unedit can work even if it can't reach the server.

CVS/Baserev

`CVS/Baserev'

Lists the revision for each file in `Base/'. Each line looks like this:

FILE/REVISION/EXPANSION

EXPANSION is currently ignored to allow for, well, future expansion.

CVS/Baserev.tmp

`CVS/Baserev.tmp'

This is the temp file for the preceding. (See section CVS/Notify.tmp or section CVS/Entries.Backup later in this section for further explanation.)

CVS/Checkin.prog

`CVS/Checkin.prog'

Records the name of the program specified by the -i option in the modules file. (See the section Repository Administrative Files section in this chapter.)

CVS/Entries

`CVS/Entries'

Stores the revisions for the files in this directory. Each line is of the form:

[CODE_LETTER]/FILE/REVISION/DATE/[KEYWORD_MODE]/[STICKY_OPTION]

If CODE_LETTER is present, it must be D for directory (anything else is silently ignored by CVS, to allow for future expansion), and the rest of the items on the line are absent.

This file is always present.

CVS/Entries.Backup

`CVS/Entries.Backup'

This is just a temp file. If you're writing some program to modify the `Entries' file, have it write the new contents to `Entries.backup' and then atomically rename it to `Entries'.

CVS/Entries.Log

`CVS/Entries.Log'

This is basically a patch file to be applied to `Entries' after `Entries' has been read (this is an efficiency hack, to avoid having to rewrite all of `Entries' for every little change). The format is the same as `Entries', except that there is an additional mandatory code letter at the front of every line: An A means this line is to be added to what's in `Entries'; R means it's to be removed from what's in `Entries'. Any other letters should be silently ignored, to allow for future expansion.

CVS/Entries.Static

`CVS/Entries.Static'

If this file exists, it means only part of the directory was fetched from the repository, and CVS will not create additional files in that directory. This condition can usually be cleared by using update -d.

CVS/Notify

`CVS/Notify'

Stores notifications that have not yet been sent to the server.

CVS/Notify.tmp

`CVS/Notify.tmp'

Temp file for `Notify'. The usual procedure for modifying `Notify' is to write out `Notify.tmp' and then rename it to `Notify'.

CVS/Repository

`CVS/Repository'

The path to the project-specific subdirectory in the repository. This may be an absolute path, or it may be relative to the path given in Root.

This file is always present.

CVS/Root

`CVS/Root'

This is the repository; that is, the value of the $CVSROOT environment variable or the argument to the -d global option.

This file is always present.

CVS/Tag

`CVS/Tag'

If there is a sticky tag or date on this directory, it is recorded in the first line of the file. The first character is a single letter indicating the type of tag: T, N, or D, for branch tag, nonbranch tag, or date respectively. The rest of the line is the tag or date itself.

CVS/Template

`CVS/Template'

Contains a log message template as specified by the rcsinfo file. (See section Repository Administrative Files earlier in this chapter.) It is relevant only for remote working copies; working copies on the same machine as the repository just read rcsinfo directly.

CVS/Update.prog

`CVS/Update.prog'

Records the name of the program specified by the -u option in the modules file. (See the section Repository Administrative Files section in this chapter.)

Environment Variables

Following is a description of all of environment variables that affect CVS.

$COMSPEC

This is used in OS/2 only; it specifies the name of the command interpreter. It defaults to CMD.EXE.

$CVS_CLIENT_LOG

Used for debugging the client/server protocol. Set this variable to a file name before you start using CVS; all traffic to the server will be logged in filename.in, and everything from the server will be logged in filename.out.

$CVS_CLIENT_PORT

Used in Kerberos-authenticated client/server access.

$CVSEDITOR

Specifies the program to use to edit log messages for commits. This overrides $EDITOR and $VISUAL.

$CVSIGNORE

A whitespace-separated list of file names and wildcard patterns that CVS should ignore. (See also the -I option to the section import command.)

This variable is appended last to the ignore list during a command. The list is built up in this order: `CVSROOT/cvsignore', the `.cvsignore' file in your home directory, the $CVSIGNORE variable, any -I command option, and finally the contents of `.cvsignore' files in the working copy used as CVS works in each directory. A ! as the ignore specification at any point nullifies the entire ignore list built up to that point.

$CVS_IGNORE_REMOTE_ROOT

Recently obsolete.

$CVS_PASSFILE

Tells CVS to use some file other than .cvspass in your home directory. (See section .cvspass in the section Run Control Files section in this chapter.)

$CVS_RCMD_PORT

Specifies the port number to contact the rcmd daemon on the server side. (This variable is currently ignored in Unix CVS clients.)

$CVSREAD

Makes working copy files read-only on checkout and update, if possible (the default is for them to be read-write). (See also the -r global option.)

$CVSROOT

This specifies the path to the repository. This is overridden with the -d global option and by the ambient repository for a given working copy. The path to the repository may be preceded by an access method, username, and host, according to the following syntax:

[[:METHOD:][[USER@]HOST]:]/REPOSITORY_PATH

See the -d global option, in the section section Global Options near the beginning of this chapter, for a list of valid methods.

$CVS_RSH

Specifies an external program for connecting to the server when using the :ext: access method. Defaults to rsh, but ssh is a common replacement value.

$CVS_SERVER

Program to invoke for CVS on the server side. Defaults to cvs, of course.

$CVS_SERVER_SLEEP

Delays the start of the server child process by the specified number of seconds. This is used only for debugging, to allow time for a debugger to connect.

$CVSUMASK

Permissions for files and directories in the repository. (You probably don't want to set this; it doesn't work for client/server anyway.)

$CVSWRAPPERS

A whitespace-separated list of file names, wildcards, and arguments that CVS should use as wrappers. (See section cvswrappers in the section Repository Administrative Files section in this chapter for more information.)

$EDITOR

(See section $CVSEDITOR.)

$HOME %HOMEDRIVE% %HOMEPATH%

Where the `.cvsrc', `.cvspass', and other such files are found (under Unix, only $HOME is used). In Windows NT, %HOMEDRIVE% and %HOMEPATH% might be set for you; in Windows 95, you may need to set them for yourself.

In Windows 95, you may also need to set %HOME%. Make sure not to give it a trailing backslash; use set HOME=C: or something similar.

$PATH

Obsolete.

$TEMP $TMP $TMPDIR

Where temporary files go (the server uses TMPDIR; Windows NT uses TMP). Setting this on the client side will not affect the server. Setting this on either side will not affect where CVS stores temporary lock files. (See section config in the section Repository Administrative Files section in this chapter for more information.)

$VISUAL

(See section $CVSEDITOR.)


Go to the first, previous, next, last section, table of contents.