C. Reference manual for Administrative files

Inside the repository, in the directory `$CVSROOT/CVSROOT', there are a number of supportive files for CVS. You can use CVS in a limited fashion without any of them, but if they are set up properly they can help make life easier. For a discussion of how to edit them, see The administrative files.

The most important of these files is the `modules' file, which defines the modules inside the repository.

C.1 The modules file

The `modules' file records your definitions of names for collections of source code. CVS will use these definitions if you use CVS to update the modules file (use normal commands like add, commit, etc).

The `modules' file may contain blank lines and comments (lines beginning with `#') as well as module definitions. Long lines can be continued on the next line by specifying a backslash (`\') as the last character on the line.

There are three basic types of modules: alias modules, regular modules, and ampersand modules. The difference between them is the way that they map files in the repository to files in the working directory. In all of the following examples, the top-level repository contains a directory called `first-dir', which contains two files, `file1' and `file2', and a directory `sdir'. `first-dir/sdir' contains a file `sfile'.

C.1.1 Alias modules

Alias modules are the simplest kind of module:

mname -a aliases…

This represents the simplest way of defining a module mname. The `-a' flags the definition as a simple alias: CVS will treat any use of mname (as a command argument) as if the list of names aliases had been specified instead. aliases may contain either other module names or paths. When you use paths in aliases, checkout creates all intermediate directories in the working directory, just as if the path had been specified explicitly in the CVS arguments.

For example, if the modules file contains:

amodule -a first-dir

then the following two commands are equivalent:

$ cvs co amodule
$ cvs co first-dir

and they each would provide output such as:

cvs checkout: Updating first-dir
U first-dir/file1
U first-dir/file2
cvs checkout: Updating first-dir/sdir
U first-dir/sdir/sfile

C.1.2 Regular modules

mname [ options ] dir [ files… ]

In the simplest case, this form of module definition reduces to `mname dir'. This defines all the files in directory dir as module mname. dir is a relative path (from $CVSROOT) to a directory of source in the source repository. In this case, on checkout, a single directory called mname is created as a working directory; no intermediate directory levels are used by default, even if dir was a path involving several directory levels.

For example, if a module is defined by:

regmodule first-dir

then regmodule will contain the files from first-dir:

$ cvs co regmodule
cvs checkout: Updating regmodule
U regmodule/file1
U regmodule/file2
cvs checkout: Updating regmodule/sdir
U regmodule/sdir/sfile
$

By explicitly specifying files in the module definition after dir, you can select particular files from directory dir. Here is an example:

regfiles first-dir/sdir sfile

With this definition, getting the regfiles module will create a single working directory `regfiles' containing the file listed, which comes from a directory deeper in the CVS source repository:

$ cvs co regfiles
U regfiles/sfile
$

C.1.3 Ampersand modules

A module definition can refer to other modules by including `&module' in its definition.

mname [ options ] &module…

Then getting the module creates a subdirectory for each such module, in the directory containing the module. For example, if modules contains

ampermod &first-dir

then a checkout will create an ampermod directory which contains a directory called first-dir, which in turns contains all the directories and files which live there. For example, the command

$ cvs co ampermod

will create the following files:

ampermod/first-dir/file1
ampermod/first-dir/file2
ampermod/first-dir/sdir/sfile

There is one quirk/bug: the messages that CVS prints omit the `ampermod', and thus do not correctly display the location to which it is checking out the files:

$ cvs co ampermod
cvs checkout: Updating first-dir
U first-dir/file1
U first-dir/file2
cvs checkout: Updating first-dir/sdir
U first-dir/sdir/sfile
$

Do not rely on this buggy behavior; it may get fixed in a future release of CVS.

C.1.4 Excluding directories

An alias module may exclude particular directories from other modules by using an exclamation mark (`!') before the name of each directory to be excluded.

For example, if the modules file contains:

exmodule -a !first-dir/sdir first-dir

then checking out the module `exmodule' will check out everything in `first-dir' except any files in the subdirectory `first-dir/sdir'.

C.1.5 Module options

Either regular modules or ampersand modules can contain options, which supply additional information concerning the module.

-d name

Name the working directory something other than the module name.

-e prog

Specify a program prog to run whenever files in a module are exported. prog runs with a single argument, the module name.

-o prog

Specify a program prog to run whenever files in a module are checked out. prog runs with a single argument, the module name. See How the modules file “program options” programs are run for information on how prog is called.

-s status

Assign a status to the module. When the module file is printed with `cvs checkout -s' the modules are sorted according to primarily module status, and secondarily according to the module name. This option has no other meaning. You can use this option for several things besides status: for instance, list the person that is responsible for this module.

-t prog

Specify a program prog to run whenever files in a module are tagged with rtag. prog runs with two arguments: the module name and the symbolic tag specified to rtag. It is not run when tag is executed. Generally you will find that the `taginfo' file is a better solution (see section Taginfo).

You should also see see section How the modules file “program options” programs are run about how the “program options” programs are run.

C.1.6 How the modules file “program options” programs are run

For checkout, rtag, and export, the program is server-based, and as such the following applies:-

If using remote access methods (pserver, ext, etc.), CVS will execute this program on the server from a temporary directory. The path is searched for this program.

If using “local access” (on a local or remote NFS file system, i.e. repository set just to a path), the program will be executed from the newly checked-out tree, if found there, or alternatively searched for in the path if not.

The programs are all run after the operation has effectively completed.

C.2 The cvswrappers file

Wrappers refers to a CVS feature which lets you control certain settings based on the name of the file which is being operated on. The settings are `-k' for binary files, and `-m' for nonmergeable text files.

The `-m' option specifies the merge methodology that should be used when a non-binary file is updated. MERGE means the usual CVS behavior: try to merge the files. COPY means that cvs update will refuse to merge files, as it also does for files specified as binary with `-kb' (but if the file is specified as binary, there is no need to specify `-m 'COPY''). CVS will provide the user with the two versions of the files, and require the user using mechanisms outside CVS, to insert any necessary changes.

WARNING: do not use COPY with CVS 1.9 or earlier - such versions of CVS will copy one version of your file over the other, wiping out the previous contents. The `-m' wrapper option only affects behavior when merging is done on update; it does not affect how files are stored. See Handling binary files, for more on binary files.

The basic format of the file `cvswrappers' is:

wildcard     [option value][option value]...

where option is one of
-m           update methodology      value: MERGE or COPY
-k           keyword expansion       value: expansion mode

and value is a single-quote delimited value.

For example, the following command imports a directory, treating files whose name ends in `.exe' as binary:

cvs import -I ! -W "*.exe -k 'b'" first-dir vendortag reltag

C.3 The Trigger Scripts

Several of the administrative files support triggers, or the launching external scripts or programs at specific times before or after particular events, during the execution of CVS commands. These hooks can be used to prevent certain actions, log them, and/or maintain anything else you deem practical.

All the trigger scripts are launched in a copy of the user sandbox being committed, on the server, in client-server mode. In local mode, the scripts are actually launched directly from the user sandbox directory being committed. For most intents and purposes, the same scripts can be run in both locations without alteration.

C.3.1 The common syntax

The administrative files such as `commitinfo', `loginfo', `rcsinfo', `verifymsg', etc., all have a common format. The purpose of the files are described later on. The common syntax is described here.

Each line contains the following:

• A regular expression or the literal string `DEFAULT'. Some script hooks also support the literal string `ALL'. Other than the `ALL' and `DEFAULT' keywords, this is a basic regular expression in the syntax used by GNU emacs. See the descriptions of the individual script hooks for information on whether the `ALL' keyword is supported (see section The Trigger Scripts).
• A whitespace separator—one or more spaces and/or tabs.
• A file name or command-line template.

Blank lines are ignored. Lines that start with the character `#' are treated as comments. Long lines unfortunately can not be broken in two parts in any way.

The first regular expression that matches the current directory name in the repository or the first line containing `DEFAULT' in lieu of a regular expression is used and all lines containing `ALL' is used for the hooks which support the `ALL' keyword. The rest of the line is used as a file name or command-line template as appropriate. See the descriptions of the individual script hooks for information on whether the `ALL' keyword is supported (see section The Trigger Scripts).

Note: The following information on format strings is valid as long as the line UseNewInfoFmtStrings=yes appears in your repository's config file (see section The CVSROOT/config configuration file). Otherwise, default format strings may be appended to the command line and the `loginfo' file, especially, can exhibit slightly different behavior. For more information, See section Updating legacy repositories to stop using deprecated command line template formats.

In the cases where the second segment of the matched line is a command line template (e.g. `commitinfo', `loginfo', & `verifymsg'), the command line template may contain format strings which will be replaced with specific values before the script is run.

Format strings can represent a single variable or one or more attributes of a list variable. An example of a list variable would be the list available to scripts hung on the loginfo hooks - the list of files which were just committed. In the case of loginfo, three attributes are available for each list item: file name, precommit version, and postcommit version.

Format strings consist of a `%' character followed by an optional `{' (required in the multiple list attribute case), a single format character representing a variable or a single attribute of list elements or multiple format characters representing attributes of list elements, and a closing `}' when the open bracket was present.

Flat format strings, or single format characters which get replaced with a single value, will generate a single argument to the called script, regardless of whether the replacement variable contains white space or other special characters.

List attributes will generate an argument for each attribute requested for each list item. For example, `%{sVv}' in a `loginfo' command template will generate three arguments (file name, precommit version, postcommit version, ...) for each file committed. As in the flat format string case, each attribute will be passed in as a single argument regardless of whether it contains white space or other special characters.

`%%' will be replaced with a literal `%'.

The format strings available to all script hooks are:

c

The canonical name of the command being executed. For instance, in the case of a hook run from cvs up, CVS would replace `%c' with the string `update' and, in the case of a hook run from cvs ci, CVS would replace `%c' with the string `commit'.

n

The null, or empty, string.

p

The name of the directory being operated on within the repository.

r

The name of the repository (the path portion of $CVSROOT).

R

On a server, the name of the referrer, if any. The referrer is the CVSROOT the client reports it used to contact a server which then referred it to this server. Should usually be set on a primary server with a write proxy setup.

Other format strings are file specific. See the docs on the particular script hooks for more information (see section The Trigger Scripts).

As an example, the following line in a `loginfo' file would match only the directory `module' and any subdirectories of `module':

^module\(/\|$\) (echo; echo %p; echo %{sVv}; cat) >>$CVSROOT/CVSROOT/commitlog

Using this same line and assuming a commit of new revisions 1.5.4.4 and 1.27.4.1 based on old revisions 1.5.4.3 and 1.27, respectively, of file1 and file2 in module, something like the following log message should be appended to commitlog:

module
file1 1.5.4.3 1.5.4.4 file2 1.27 1.27.4.1
Update of /cvsroot/module
In directory localhost.localdomain:/home/jrandom/work/module

Modified Files:
	file1 file2
Log Message:
A log message.

C.3.2 Security and the Trigger Scripts

Security is a huge subject, and implementing a secure system is a non-trivial task. This section will barely touch on all the issues involved, but it is well to note that, as with any script you will be allowing an untrusted user to run on your server, there are measures you can take to help prevent your trigger scripts from being abused.

For instance, since the CVS trigger scripts all run in a copy of the user's sandbox on the server, a naively coded Perl trigger script which attempts to use a Perl module that is not installed on the system can be hijacked by any user with commit access who is checking in a file with the correct name. Other scripting languages may be vulnerable to similar hacks.

One way to make a script more secure, at least with Perl, is to use scripts which invoke the -T, or "taint-check" switch on their #! line. In the most basic terms, this causes Perl to avoid running code that may have come from an external source. Please run the perldoc perlsec command for more on Perl security. Again, other languages may implement other security verification hooks which look more or less like Perl's "taint-check" mechanism.

C.3.3 The commit support files

The `-i' flag in the `modules' file can be used to run a certain program whenever files are committed (see section The modules file). The files described in this section provide other, more flexible, ways to run programs whenever something is committed.

There are three kinds of programs that can be run on commit. They are specified in files in the repository, as described below. The following table summarizes the file names and the purpose of the corresponding programs.

`commitinfo'

The program is responsible for checking that the commit is allowed. If it exits with a non-zero exit status the commit will be aborted. See section Commitinfo.

`verifymsg'

The specified program is used to evaluate the log message, and possibly verify that it contains all required fields. This is most useful in combination with the `rcsinfo' file, which can hold a log message template (see section Rcsinfo). See section Verifying log messages.

`loginfo'

The specified program is called when the commit is complete. It receives the log message and some additional information and can store the log message in a file, or mail it to appropriate persons, or maybe post it to a local newsgroup, or… Your imagination is the limit! See section Loginfo.

C.3.3.1 Updating legacy repositories to stop using deprecated command line template formats

New repositories are created set to use the new format strings by default, so if you are creating a new repository, you shouldn't have to worry about this section.

If you are attempting to maintain a legacy repository which was making use of the `commitinfo', `editinfo', `verifymsg', `loginfo', and/or `taginfo' script hooks, you should have no immediate problems with using the current CVS executable, but your users will probably start to see deprecation warnings.

The reason for this is that all of the script hooks have been updated to use a new command line parser that extensibly supports multiple `loginfo' & `notify' style format strings (see section The common syntax) and this support is not completely compatible with the old style format strings.

The quick upgrade method is to stick a `1' after each format string in your old `loginfo' file. For example:

DEFAULT (echo ""; id; echo %{sVv}; date; cat) >> $CVSROOT/CVSROOT/commitlog

would become:

DEFAULT (echo ""; id; echo %1{sVv}; date; cat) >> $CVSROOT/CVSROOT/commitlog

If you were counting on the fact that only the first `%' in the line was replaced as a format string, you may also have to double up any further percent signs on the line.

If you did this all at once and checked it in, everything should still be running properly.

Now add the following line to your config file (see section The CVSROOT/config configuration file):

UseNewInfoFmtStrings=yes

Everything should still be running properly, but your users will probably start seeing new deprecation warnings.

Dealing with the deprecation warnings now generated by `commitinfo', `editinfo', `verifymsg', and `taginfo' should be easy. Simply specify what are currently implicit arguments explicitly. This means appending the following strings to each active command line template in each file:

commitinfo

` %r/%p %s'

editinfo

` %l'

taginfo

` %t %o %p %{sv}'

verifymsg

` %l'

If you don't desire that any of the newly available information be passed to the scripts hanging off of these hooks, no further modifications to these files should be necessary to insure current and future compatibility with CVS's format strings.

Fixing `loginfo' could be a little tougher. The old style `loginfo' format strings caused a single space and comma separated argument to be passed in in place of the format string. This is what will continue to be generated due to the deprecated `1' you inserted into the format strings.

Since the new format separates each individual item and passes it into the script as a separate argument (for a good reason - arguments containing commas and/or white space are now parsable), to remove the deprecated `1' from your `loginfo' command line templates, you will most likely have to rewrite any scripts called by the hook to handle the new argument format.

Also note that the way `%' followed by unrecognized characters and by `{}' was treated in past versions of CVS is not strictly adhered to as there were bugs in the old versions. Specifically, `%{}' would eat the next character and unrecognized strings resolved only to the empty string, which was counter to what was stated in the documentation. This version will do what the documentation said it should have (if you were using only some combination of `%{sVv}', e.g. `%{sVv}', `%{sV}', or `%v', you should have no troubles).

On the bright side, you should have plenty of time to do this before all support for the old format strings is removed from CVS, so you can just put up with the deprecation warnings for awhile if you like.

C.3.4 Commitinfo

The `commitinfo' file defines programs to execute whenever `cvs commit' is about to execute. These programs are used for pre-commit checking to verify that the modified, added and removed files are really ready to be committed. This could be used, for instance, to verify that the changed files conform to to your site's standards for coding practice.

The `commitinfo' file has the standard form for script hooks (see section The Trigger Scripts), where each line is a regular expression followed by a command to execute. It supports only the DEFAULT keywords.

In addition to the common format strings (see section The common syntax), `commitinfo' supports:

{s}

a list of the names of files to be committed

Currently, if no format strings are specified, a default string of ` %r/%p %{s}' will be appended to the command line template before replacement is performed, but this feature is deprecated. It is simply in place so that legacy repositories will remain compatible with the new CVS application. For information on updating, see section Updating legacy repositories to stop using deprecated command line template formats.

The first line with a regular expression matching the directory within the repository will be used. If the command returns a non-zero exit status the commit will be aborted.

The command will be run in the root of the workspace containing the new versions of any files the user would like to modify (commit), or in a copy of the workspace on the server (see section Remote repositories). If a file is being removed, there will be no copy of the file under the current directory. If a file is being added, there will be no corresponding archive file in the repository unless the file is being resurrected.

Note that both the repository directory and the corresponding Attic (see section The attic) directory may need to be checked to locate the archive file corresponding to any given file being committed. Much of the information about the specific commit request being made, including the destination branch, commit message, and command line options specified, is not available to the command.

C.3.5 Verifying log messages

Once you have entered a log message, you can evaluate that message to check for specific content, such as a bug ID. Use the `verifymsg' file to specify a program that is used to verify the log message. This program could be a simple script that checks that the entered message contains the required fields.

The `verifymsg' file is often most useful together with the `rcsinfo' file, which can be used to specify a log message template (see section Rcsinfo).

The `verifymsg' file has the standard form for script hooks (see section The Trigger Scripts), where each line is a regular expression followed by a command to execute. It supports only the DEFAULT keywords.

In addition to the common format strings (see section The common syntax), `verifymsg' supports:

l

the full path to the file containing the log message to be verified

{sV}

File attributes, where:

s

file name

V

old version number (pre-checkin)

Currently, if no format strings are specified, a default string of ` %l' will be appended to the command line template before replacement is performed, but this feature is deprecated. It is simply in place so that legacy repositories will remain compatible with the new CVS application. For information on updating, see section Updating legacy repositories to stop using deprecated command line template formats.

One thing that should be noted is that the `ALL' keyword is not supported. If more than one matching line is found, the first one is used. This can be useful for specifying a default verification script in a directory, and then overriding it in a subdirectory.

If the verification script exits with a non-zero exit status, the commit is aborted.

In the default configuration, CVS allows the verification script to change the log message. This is controlled via the RereadLogAfterVerify CVSROOT/config option.

When `RereadLogAfterVerify=always' or `RereadLogAfterVerify=stat', the log message will either always be reread after the verification script is run or reread only if the log message file status has changed.

See section The CVSROOT/config configuration file, for more on CVSROOT/config options.

It is NOT a good idea for a `verifymsg' script to interact directly with the user in the various client/server methods. For the pserver method, there is no protocol support for communicating between `verifymsg' and the client on the remote end. For the ext and server methods, it is possible for CVS to become confused by the characters going along the same channel as the CVS protocol messages. See Remote repositories, for more information on client/server setups. In addition, at the time the `verifymsg' script runs, the CVS server has locks in place in the repository. If control is returned to the user here then other users may be stuck waiting for access to the repository.

This option can be useful if you find yourself using an rcstemplate that needs to be modified to remove empty elements or to fill in default values. It can also be useful if the rcstemplate has changed in the repository and the CVS/Template was not updated, but is able to be adapted to the new format by the verification script that is run by `verifymsg'.

An example of an update might be to change all occurrences of 'BugId:' to be 'DefectId:' (which can be useful if the rcstemplate has recently been changed and there are still checked-out user trees with cached copies in the CVS/Template file of the older version).

Another example of an update might be to delete a line that contains 'BugID: none' from the log message after validation of that value as being allowed is made.

C.3.5.1 Verifying log messages

The following is a little silly example of a `verifymsg' file, together with the corresponding `rcsinfo' file, the log message template and a verification script. We begin with the log message template. We want to always record a bug-id number on the first line of the log message. The rest of log message is free text. The following template is found in the file `/usr/cvssupport/tc.template'.

BugId:

The script `/usr/cvssupport/bugid.verify' is used to evaluate the log message.

#!/bin/sh
#
#       bugid.verify filename
#
#  Verify that the log message contains a valid bugid
#  on the first line.
#
if sed 1q < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then
    exit 0
elif sed 1q < $1 | grep '^BugId:[ ]*none$' > /dev/null; then
    # It is okay to allow commits with 'BugId: none',
    # but do not put that text into the real log message.
    grep -v '^BugId:[ ]*none$' > $1.rewrite
    mv $1.rewrite $1
    exit 0
else
    echo "No BugId found."
    exit 1
fi

The `verifymsg' file contains this line:

^tc     /usr/cvssupport/bugid.verify %l

The `rcsinfo' file contains this line:

^tc     /usr/cvssupport/tc.template

The `config' file contains this line:

RereadLogAfterVerify=always

C.3.6 Loginfo

The `loginfo' file is used to control where log information is sent after versioned changes are made to repository archive files and after directories are added ot the repository. Logging tags for how to log tagging information and Logging admin commands for how to log changes due to the admin command.

The `loginfo' file has the standard form for script hooks (see section The Trigger Scripts), where each line is a regular expression followed by a command to execute. It supports the ALL and DEFAULT keywords.

Any specified scripts are called:

commit

Once per directory, immediately after a successfully completing the commit of all files within that directory.

import

Once per import, immediately after completion of all write operations.

add

Immediately after the successful add of a directory.

Any script called via `loginfo' will be fed the log information on its standard input. Note that the filter program must read all of the log information from its standard input or CVS may fail with a broken pipe signal.

In addition to the common format strings (see section The common syntax), `loginfo' supports:

{stVv}

File attributes, where:

s

file name

T

tag name of destination, or the empty string when there is no associated tag name (this usually means the trunk)

V

old version number (pre-checkin)

v

new version number (post-checkin)

For example, some valid format strings are `%%', `%s', `%{s}', and `%{stVv}'.

Currently, if `UseNewInfoFmtStrings' is not set in the `config' administration file (see section The CVSROOT/config configuration file), the format strings will be substituted as they were in past versions of CVS, but this feature is deprecated. It is simply in place so that legacy repositories will remain compatible with the new CVS application. For information on updating, please see Updating legacy repositories to stop using deprecated command line template formats.

As an example, if `/u/src/master/yoyodyne/tc' is the repository, `%p' and `%{sVv}' are the format strings, and three files (ChangeLog, Makefile, foo.c) were modified, the output might be:

yoyodyne/tc ChangeLog 1.1 1.2 Makefile 1.3 1.4 foo.c 1.12 1.13

Note: when CVS is accessing a remote repository, `loginfo' will be run on the remote (i.e., server) side, not the client side (see section Remote repositories).

C.3.6.1 Loginfo example

The following `loginfo' file, together with the tiny shell-script below, appends all log messages to the file `$CVSROOT/CVSROOT/commitlog', and any commits to the administrative files (inside the `CVSROOT' directory) are also logged in `/usr/adm/cvsroot-log'. Commits to the `prog1' directory are mailed to ceder.

ALL                     /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog $USER
^CVSROOT\(/\|$\)        /usr/local/bin/cvs-log /usr/adm/cvsroot-log $USER
^prog1\(/\|$\)          Mail -s "%p %s" ceder

The shell-script `/usr/local/bin/cvs-log' looks like this:

#!/bin/sh
(echo "------------------------------------------------------";
 echo -n "$2  ";
 date;
 echo;
 cat) >> $1

C.3.6.2 Keeping a checked out copy

It is often useful to maintain a directory tree which contains files which correspond to the latest version in the repository. For example, other developers might want to refer to the latest sources without having to check them out, or you might be maintaining a web site with CVS and want every checkin to cause the files used by the web server to be updated.

The way to do this is by having loginfo invoke cvs update. Doing so in the naive way will cause a problem with locks, so the cvs update must be run in the background. Here is an example for unix (this should all be on one line):

^cyclic-pages\(/\|$\)	(date; cat; (sleep 2; cd /u/www/local-docs;
 cvs -q update -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1

This will cause checkins to repository directory cyclic-pages and its subdirectories to update the checked out tree in `/u/www/local-docs'.

C.3.7 Logging admin commands

The `postadmin' file defines programs to execute after an admin command modifies files. The `postadmin' file has the standard form for script hooks (see section The Trigger Scripts), where each line is a regular expression followed by a command to execute. It supports the ALL and DEFAULT keywords.

The `postadmin' file supports no format strings other than the common ones (see section The common syntax),

C.3.8 Taginfo

The `taginfo' file defines programs to execute when someone executes a tag or rtag command. The `taginfo' file has the standard form for script hooks (see section The Trigger Scripts), where each line is a regular expression followed by a command to execute. It supports the ALL and DEFAULT keywords.

In addition to the common format strings (see section The common syntax), `taginfo' supports:

b

tag type (T for branch, N for not-branch, or ? for unknown, as during delete operations)

o

operation (add for tag, mov for tag -F, or del for tag -d)

t

new tag name

{sTVv}

file attributes, where:

s

file name

T

tag name of destination, or the empty string when there is no associated tag name (this usually means the trunk)

V

old version number (for a move or delete operation)

v

new version number (for an add or move operation)

For example, some valid format strings are `%%', `%p', `%t', `%s', `%{s}', and `%{sVv}'.

Currently, if no format strings are specified, a default string of ` %t %o %p %{sv}' will be appended to the command line template before replacement is performed, but this feature is deprecated. It is simply in place so that legacy repositories will remain compatible with the new CVS application. For information on updating, see section Updating legacy repositories to stop using deprecated command line template formats.

A non-zero exit of the filter program will cause the tag to be aborted.

Here is an example of using `taginfo' to log tag and rtag commands. In the `taginfo' file put:

ALL /usr/local/cvsroot/CVSROOT/loggit %t %b %o %p %{sVv}

Where `/usr/local/cvsroot/CVSROOT/loggit' contains the following script:

#!/bin/sh
echo "$@" >>/home/kingdon/cvsroot/CVSROOT/taglog

C.3.9 Logging tags

The `posttag' file defines programs to execute after a tag or rtag command modifies files. The `posttag' file has the standard form for script hooks (see section The Trigger Scripts), where each line is a regular expression followed by a command to execute. It supports the ALL and DEFAULT keywords.

The `posttag' admin file supports the same format strings as the `taginfo' file (see section Taginfo),

C.3.10 Logging watch commands

The `postwatch' file defines programs to execute after any command (for instance, watch, edit, unedit, or commit) modifies any `CVS/fileattr' file in the repository (see section Mechanisms to track who is editing files). The `postwatch' file has the standard form for script hooks (see section The Trigger Scripts), where each line is a regular expression followed by a command to execute. It supports the ALL and DEFAULT keywords.

The `postwatch' file supports no format strings other than the common ones (see section The common syntax), but it is worth noting that the %c format string may not be replaced as you might expect. Client runs of edit and unedit can sometimes skip contacting the CVS server and cache the notification of the file attribute change to be sent the next time the client contacts the server for whatever other reason,

C.3.11 Launch a Script before Proxying

The `preproxy' file defines programs to execute after a secondary server receives a write request from a client, just before it starts up the primary server and becomes a write proxy. This hook could be used to dial a modem, launch an SSH tunnel, establish a VPN, or anything else that might be necessary to do before contacting the primary server.

`preproxy' scripts are called once, at the time of the write request, with the repository argument (if requested) set from the topmost directory sent by the client.

The `preproxy' file has the standard form for script hooks (see section The Trigger Scripts), where each line is a regular expression followed by a command to execute. It supports the ALL and DEFAULT keywords.

In addition to the common format strings, the `preproxy' file supports the following format string:

P

the CVSROOT string which specifies the primary server

C.3.12 Launch a Script after Proxying

The `postproxy' file defines programs to execute after a secondary server notes that the connection to the primary server has shut down and before it releases the client by shutting down the connection to the client. This could hook could be used to disconnect a modem, an SSH tunnel, a VPN, or anything else that might be necessary to do after contacting the primary server. This hook should also be used to pull updates from the primary server before allowing the client which did the write to disconnect since otherwise the client's next read request may generate error messages and fail upon encountering an out of date repository on the secondary server.

`postproxy' scripts are called once per directory.

The `postproxy' file has the standard form for script hooks (see section The Trigger Scripts), where each line is a regular expression followed by a command to execute. It supports the ALL and DEFAULT keywords.

In addition to the common format strings, the `postproxy' file supports the following format string:

P

the CVSROOT string which specifies the primary server

C.4 Rcsinfo

The `rcsinfo' file can be used to specify a form to edit when filling out the commit log. The `rcsinfo' file has a syntax similar to the `verifymsg', `commitinfo' and `loginfo' files. See section The common syntax. Unlike the other files the second part is not a command-line template. Instead, the part after the regular expression should be a full pathname to a file containing the log message template.

If the repository name does not match any of the regular expressions in this file, the `DEFAULT' line is used, if it is specified.

All occurrences of the name `ALL' appearing as a regular expression are used in addition to the first matching regular expression or `DEFAULT'.

The log message template will be used as a default log message. If you specify a log message with `cvs commit -m message' or `cvs commit -f file' that log message will override the template.

See section Verifying log messages, for an example `rcsinfo' file.

When CVS is accessing a remote repository, the contents of `rcsinfo' at the time a directory is first checked out will specify a template. This template will be updated on all `cvs update' commands. It will also be added to new directories added with a `cvs add new-directory' command. In versions of CVS prior to version 1.12, the `CVS/Template' file was not updated. If the CVS server is at version 1.12 or higher an older client may be used and the `CVS/Template' will be updated from the server.

C.5 Ignoring files via cvsignore

There are certain file names that frequently occur inside your working copy, but that you don't want to put under CVS control. Examples are all the object files that you get while you compile your sources. Normally, when you run `cvs update', it prints a line for each file it encounters that it doesn't know about (see section update output).

CVS has a list of files (or sh(1) file name patterns) that it should ignore while running update, import and release. This list is constructed in the following way.

• The list is initialized to include certain file name patterns: names associated with CVS administration, or with other common source control systems; common names for patch files, object files, archive files, and editor backup files; and other names that are usually artifacts of assorted utilities. Currently, the default list of ignored file name patterns is:

  RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state .nse_depinfo *~ #* .#* ,* _$* *$ *.old *.bak *.BAK *.orig *.rej .del-* *.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core

• The per-repository list in `$CVSROOT/CVSROOT/cvsignore' is appended to the list, if that file exists.
• The per-user list in `.cvsignore' in your home directory is appended to the list, if it exists.
• Any entries in the environment variable $CVSIGNORE is appended to the list.
• Any `-I' options given to CVS is appended.
• As CVS traverses through your directories, the contents of any `.cvsignore' will be appended to the list. The patterns found in `.cvsignore' are only valid for the directory that contains them, not for any sub-directories.

In any of the 5 places listed above, a single exclamation mark (`!') clears the ignore list. This can be used if you want to store any file which normally is ignored by CVS.

Specifying `-I !' to cvs import will import everything, which is generally what you want to do if you are importing files from a pristine distribution or any other source which is known to not contain any extraneous files. However, looking at the rules above you will see there is a fly in the ointment; if the distribution contains any `.cvsignore' files, then the patterns from those files will be processed even if `-I !' is specified. The only workaround is to remove the `.cvsignore' files in order to do the import. Because this is awkward, in the future `-I !' might be modified to override `.cvsignore' files in each directory.

Note that the syntax of the ignore files consists of a series of lines, each of which contains a space separated list of filenames. This offers no clean way to specify filenames which contain spaces, but you can use a workaround like `foo?bar' to match a file named `foo bar' (it also matches `fooxbar' and the like). Also note that there is currently no way to specify comments.

C.6 The checkoutlist file

It may be helpful to use CVS to maintain your own files in the `CVSROOT' directory. For example, suppose that you have a script `logcommit.pl' which you run by including the following line in the `commitinfo' administrative file:

ALL   $CVSROOT/CVSROOT/logcommit.pl %r/%p %s

To maintain `logcommit.pl' with CVS you would add the following line to the `checkoutlist' administrative file:

logcommit.pl

The format of `checkoutlist' is one line for each file that you want to maintain using CVS, giving the name of the file, followed optionally by more whitespace and any error message that should print if the file cannot be checked out into CVSROOT after a commit:

logcommit.pl	Could not update CVSROOT/logcommit.pl.

After setting up `checkoutlist' in this fashion, the files listed there will function just like CVS's built-in administrative files. For example, when checking in one of the files you should get a message such as:

cvs commit: Rebuilding administrative file database

and the checked out copy in the `CVSROOT' directory should be updated.

Note that listing `passwd' (see section Setting up the server for password authentication) in `checkoutlist' is not recommended for security reasons.

For information about keeping a checkout out copy in a more general context than the one provided by `checkoutlist', see Keeping a checked out copy.

C.7 The history file

By default, the file `$CVSROOT/CVSROOT/history' is used to log information for the history command (see section history—Show status of files and users). This file name may be changed with the `HistoryLogPath' and `HistorySearchPath' config options (see section The CVSROOT/config configuration file).

The file format of the `history' file is documented only in comments in the CVS source code, but generally programs should use the cvs history command to access it anyway, in case the format changes with future releases of CVS.

C.8 Expansions in administrative files

Sometimes in writing an administrative file, you might want the file to be able to know various things based on environment CVS is running in. There are several mechanisms to do that.

To find the home directory of the user running CVS (from the HOME environment variable), use `~' followed by `/' or the end of the line. Likewise for the home directory of user, use `~user'. These variables are expanded on the server machine, and don't get any reasonable expansion if pserver (see section Direct connection with password authentication) is in use; therefore user variables (see below) may be a better choice to customize behavior based on the user running CVS.

One may want to know about various pieces of information internal to CVS. A CVS internal variable has the syntax ${variable}, where variable starts with a letter and consists of alphanumeric characters and `_'. If the character following variable is a non-alphanumeric character other than `_', the `{' and `}' can be omitted. The CVS internal variables are:

CVSROOT

This is the absolute path to the current CVS root directory. See section The Repository, for a description of the various ways to specify this, but note that the internal variable contains just the directory and not any of the access method information.

RCSBIN

In CVS 1.9.18 and older, this specified the directory where CVS was looking for RCS programs. Because CVS no longer runs RCS programs, specifying this internal variable is now an error.

CVSEDITOR

EDITOR

VISUAL

These all expand to the same value, which is the editor that CVS is using. See section Global options, for how to specify this.

USER

Username of the user running CVS (on the CVS server machine). When using pserver, this is the user specified in the repository specification which need not be the same as the username the server is running as (see section Setting up the server for password authentication). Do not confuse this with the environment variable of the same name.

SESSIONID

Unique Session ID of the CVS process. This is a random string of printable characters of at least 16 characters length. Users should assume that it may someday grow to at most 256 characters in length.

COMMITID

Unique Session ID of the CVS process. This is a random string of printable characters of at least 16 characters length. Users should assume that it may someday grow to at most 256 characters in length.

If you want to pass a value to the administrative files which the user who is running CVS can specify, use a user variable. To expand a user variable, the administrative file contains ${=variable}. To set a user variable, specify the global option `-s' to CVS, with argument variable=value. It may be particularly useful to specify this option via `.cvsrc' (see section Default options and the ~/.cvsrc file).

For example, if you want the administrative file to refer to a test directory you might create a user variable TESTDIR. Then if CVS is invoked as

cvs -s TESTDIR=/work/local/tests

and the administrative file contains sh ${=TESTDIR}/runtests, then that string is expanded to sh /work/local/tests/runtests.

All other strings containing `$' are reserved; there is no way to quote a `$' character so that `$' represents itself.

Environment variables passed to administrative files are:

CVS_USER

The CVS-specific username provided by the user, if it can be provided (currently just for the pserver access method), and to the empty string otherwise. (CVS_USER and USER may differ when `$CVSROOT/CVSROOT/passwd' is used to map CVS usernames to system usernames.)

LOGNAME

The username of the system user.

USER

Same as LOGNAME. Do not confuse this with the internal variable of the same name.

C.9 The CVSROOT/config configuration file

Usually, the `config' file is found at `$CVSROOT/CVSROOT/config', but this may be overridden on the pserver and server command lines (see section server & pserver—Act as a server for a client on stdin/stdout).

The administrative file `config' contains various miscellaneous settings which affect the behavior of CVS. The syntax is slightly different from the other administrative files.

Leading white space on any line is ignored, though the syntax is very strict and will reject spaces and tabs almost anywhere else.

Empty lines, lines containing nothing but white space, and lines which start with `#' (discounting any leading white space) are ignored.

Other lines consist of the optional leading white space, a keyword, `=', and a value. Please note again that this syntax is very strict. Extraneous spaces or tabs, other than the leading white space, are not permitted on these lines.

As of CVS 1.12.13, lines of the form `[CVSROOT]' mark the subsequent section of the config file as applying only to certain repositories. Multiple `[CVSROOT]' lines without intervening `KEYWORD=VALUE' pairs cause processing to fall through, processing subsequent keywords for any root in the list. Finally, keywords and values which appear before any `[CVSROOT]' lines are defaults, and may to apply to any repository. For example, consider the following file:

# Defaults
LogHistory=TMAR

[/cvsroots/team1]
  LockDir=/locks/team1

[/cvsroots/team2]
  LockDir=/locks/team2

[/cvsroots/team3]
  LockDir=/locks/team3

[/cvsroots/team4]
  LockDir=/locks/team4

[/cvsroots/team3]
[/cvsroots/team4]
  # Override logged commands for teams 3 & 4.
  LogHistory=all

This example file sets up separate lock directories for each project, as well as a default set of logged commands overridden for the example's team 3 & team 4. This syntax could be useful, for instance, if you wished to share a single config file, for instance `/etc/cvs.conf', among several repositories.

Currently defined keywords are:

HistorySearchPath=pattern

Request that CVS look for its history information in files matching pattern, which is a standard UNIX file glob. If pattern matches multiple files, all will be searched in lexicographically sorted order. See section history—Show status of files and users, and The history file, for more.

If no value is supplied for this option, it defaults to `$CVSROOT/CVSROOT/history'.

HistoryLogPath=path

Control where CVS logs its history. If the file does not exist, CVS will attempt to create it. Format strings, as available to the GNU C strftime function and often the UNIX date command, and the string $CVSROOT will be substituted in this path. For example, consider the line:

HistoryLogPath=$CVSROOT/CVSROOT/history/%Y-%m-%d

This line would cause CVS to attempt to create its history file in a subdirectory (`history') of the configuration directory (`CVSROOT') with a name equal to the current date representation in the ISO8601 format (for example, on May 11, 2005, CVS would attempt to log its history under the repository root directory in a file named `CVSROOT/history/2005-05-11'). See section history—Show status of files and users, and The history file, for more.

If no value is supplied for this option, it defaults to `$CVSROOT/CVSROOT/history'.

ImportNewFilesToVendorBranchOnly=value

Specify whether cvs import should always behave as if the `-X' flag was specified on the command line. value may be either `yes' or `no'. If set to `yes', all uses of cvs import on the repository will behave as if the `-X' flag was set. The default value is `no'.

KeywordExpand=value

Specify `i' followed by a list of keywords to be expanded (for example, `KeywordExpand=iMYCVS,Name,Date'), or `e' followed by a list of keywords not to be expanded (for example, `KeywordExpand=eCVSHeader'). For more on keyword expansion, see Configuring Keyword Expansion.

LocalKeyword=value

Specify a local alias for a standard keyword. For example, `LocalKeyword=MYCVS=CVSHeader'. For more on local keywords, see Keyword substitution.

LockDir=directory

Put CVS lock files in directory rather than directly in the repository. This is useful if you want to let users read from the repository while giving them write access only to directory, not to the repository. It can also be used to put the locks on a very fast in-memory file system to speed up locking and unlocking the repository. You need to create directory, but CVS will create subdirectories of directory as it needs them. For information on CVS locks, see Several developers simultaneously attempting to run CVS.

Before enabling the LockDir option, make sure that you have tracked down and removed any copies of CVS 1.9 or older. Such versions neither support LockDir, nor will give an error indicating that they don't support it. The result, if this is allowed to happen, is that some CVS users will put the locks one place, and others will put them another place, and therefore the repository could become corrupted. CVS 1.10 does not support LockDir but it will print a warning if run on a repository with LockDir enabled.

LogHistory=value

Control what is logged to the `CVSROOT/history' file (see section history—Show status of files and users). Default of `TOEFWUPCGMAR' (or simply `all') will log all transactions. Any subset of the default is legal. (For example, to only log transactions that modify the `*,v' files, use `LogHistory=TMAR'.) To disable history logging completely, use `LogHistory='.

MaxCommentLeaderLength=length

Set to some length, in bytes, where a trailing `k', `M', `G', or `T' causes the preceding nubmer to be interpreted as kilobytes, megabytes, gigabytes, or terrabytes, respectively, will cause $Log$ keywords (see section Keyword substitution), with more than length bytes preceding it on a line to be ignored (or to fall back on the comment leader set in the RCS archive file - see UseArchiveCommentLeader below). Defaults to 20 bytes to allow checkouts to proceed normally when they include binary files containing $Log$ keywords and which users have neglected to mark as binary.

MinCompressionLevel=value

MaxCompressionLevel=value

Restricts the level of compression used by the CVS server to a value between 0 and 9. values 1 through 9 are the same ZLIB compression levels accepted by the `-z' option (see section Global options), and 0 means no compression. When one or both of these keys are set and a client requests a level outside the specified range, the server will simply use the closest permissable level. Clients will continue compressing at the level requested by the user.

The exception is when level 0 (no compression) is not available and the client fails to request any compression. The CVS server will then exit with an error message when it becomes apparent that the client is not going to request compression. This will not happen with clients version 1.12.13 and later since these client versions allow the server to notify them that they must request some level of compression.

PrimaryServer=CVSROOT

When specified, and the repository specified by CVSROOT is not the one currently being accessed, then the server will turn itself into a transparent proxy to CVSROOT for write requests. The hostname configured as part of CVSROOT must resolve to the same string returned by the uname command on the primary server for this to work. Host name resolution is performed via some combination of named, a broken out line from `/etc/hosts', and the Network Information Service (NIS or YP), depending on the configuration of the particular system.

Only the `:ext:' method is currently supported for primaries (actually, `:fork:' is supported as well, but only for testing - if you find another use for accessing a primary via the `:fork:' method, please send a note to bug-cvs@nongnu.org about it). See Distributing load across several CVS servers for more on configuring and using write proxies.

RCSBIN=bindir

For CVS 1.9.12 through 1.9.18, this setting told CVS to look for RCS programs in the bindir directory. Current versions of CVS do not run RCS programs; for compatibility this setting is accepted, but it does nothing.

RereadLogAfterVerify=value

Modify the `commit' command such that CVS will reread the log message after running the program specified by `verifymsg'. value may be one of `yes' or `always', indicating that the log message should always be reread; `no' or `never', indicating that it should never be reread; or value may be `stat', indicating that the file should be checked with the file system `stat()' function to see if it has changed (see warning below) before rereading. The default value is `always'.

Note: the `stat' mode can cause CVS to pause for up to one extra second per directory committed. This can be less IO and CPU intensive but is not recommended for use with large repositories

See section Verifying log messages, for more information on how verifymsg may be used.

SystemAuth=value

If value is `yes', then pserver should check for users in the system's user database if not found in `CVSROOT/passwd'. If it is `no', then all pserver users must exist in `CVSROOT/passwd'. The default is `yes'. For more on pserver, see Direct connection with password authentication.

TmpDir=path

Specify path as the directory to create temporary files in. See section Global options, for more on setting the path to the temporary directory. This option first appeared with CVS release 1.12.13.

TopLevelAdmin=value

Modify the `checkout' command to create a `CVS' directory at the top level of the new working directory, in addition to `CVS' directories created within checked-out directories. The default value is `no'.

This option is useful if you find yourself performing many commands at the top level of your working directory, rather than in one of the checked out subdirectories. The `CVS' directory created there will mean you don't have to specify CVSROOT for each command. It also provides a place for the `CVS/Template' file (see section How data is stored in the working directory).

UseArchiveCommentLeader=value

Set to true, if the text preceding a $Log$ keyword is found to exceed MaxCommentLeaderLength (above) bytes, then the comment leader set in the RCS archive file (see section admin—Administration), if any, will be used instead. If there is no comment leader set in the archive file or value is set to `false', then the keyword will not be expanded (see section Keyword List). To force the comment leader in the RCS archive file to be used exclusively (and $Log$ expansion skipped in files where the comment leader has not been set in the archive file), set value and set MaxCommentLeaderLength to 0.

UseNewInfoFmtStrings=value

Specify whether CVS should support the new or old command line template model for the commit support files (see section The commit support files). This configuration variable began life in deprecation and is only here in order to give people time to update legacy repositories to use the new format string syntax before support for the old syntax is removed. For information on updating your repository to support the new model, please see Updating legacy repositories to stop using deprecated command line template formats.

Note that new repositories (created with the cvs init command) will have this value set to `yes', but the default value is `no'.

UserAdminOptions=value

Control what options will be allowed with the cvs admin command (see section admin—Administration) for users not in the cvsadmin group. The value string is a list of single character options which should be allowed. If a user who is not a member of the cvsadmin group tries to execute any cvs admin option which is not listed they will will receive an error message reporting that the option is restricted.

If no cvsadmin group exists on the server, CVS will ignore the UserAdminOptions keyword (see section admin—Administration).

When not specified, UserAdminOptions defaults to `k'. In other words, it defaults to allowing users outside of the cvsadmin group to use the cvs admin command only to change the default keyword expansion mode for files.

As an example, to restrict users not in the cvsadmin group to using cvs admin to change the default keyword substitution mode, lock revisions, unlock revisions, and replace the log message, use `UserAdminOptions=klum'.

This document was generated by Derek R. Price on October, 3 2005 using texi2html 1.77.