Essential CVS (Essentials)

11.2. CVSROOT Files

The CVSROOT directory in the CVS repository contains several administrative files. Most of these files are editable by the user and are stored in both RCS format (with a ,v suffix) and plain text to be used by CVS. With three exceptions, these files can be checked out, edited, and committed like any other CVS file.

The history and val-tags files should not be edited. The passwd file should never be checked out; it should be edited in place.

11.2.1. Scripting File Syntax

As of CVS 1.12.6, the syntax for scripting files changed. If you're using an older version of CVS, please see Chapter 7 for information on the file syntax. If you have different versions of CVS in the repository and the clients, see Chapter 9 for advice on cross-version issues.

In versions later than 1.12.6, whether you use the new or old format for the scripting files is controlled by the configuration option UseNewInfoFmtStrings. The valid options are yes (to use the new format) and no (to use the format prior to 1.12.6). These options are set in the config file, normally stored in the CVSROOT directory.

The file syntax is as follows:

name-pattern action

The name-pattern is a regular expression that must match a relative path within the repository, or one of the special words DEFAULT and ALL. It is separated from the action by one or more spaces or tabs. Regular expressions are explained later in this chapter.

The action is a command-line template, or the filename (and path) of a script plus any parameters required for that script. It is good practice to use the full pathname of the script, with the $CVSROOT variable standing in for the repository path. You may embed one or more format strings in the template or among the script's parameters; you may also use the variables listed later in this chapter, in the section "CVSROOT Variables."

The character # at the start of a line signals a comment. Blank lines are ignored. There is no way to break a long line in current versions of CVS.

CVS processes the file by matching the current repository directory to the regular expression. It looks for the first matching line, runs the action provided on that line, and also runs the actions on any line with a name-pattern of ALL. Note that DEFAULT as a name-pattern is deemed to match everything, so ensure that it is the last name-pattern other than ALL.

The format strings are processed by CVS before being passed to the action's script or command. Before processing, the format string consists of a %, followed by a single variable, optionally enclosed in braces ({ }), or by a set of variables enclosed in braces. Some of the variables represent individual values, and others represent list values. Each variable in a set of variables enclosed in braces must represent a list value.

Each value represented by a format string variable is passed to its script as a single argument, irrespective of white space within the value. A list on its own is passed as a single argument for each element of the list.

A set of list values is also passed as a single argument for each element of each list, but the values are collated. For instance, %{sVv} in the taginfo file will produce a list of arguments in the format file1 oldversion1 newversion1 file2 oldversion2 newversion2 file3 oldversion3 newversion3.

The format string variables which are valid in all files represent single values, and are:

%

A literal percent sign (that is, %% will become %).

c

The name of the command that triggered the execution of the script. In a script run because of a cvs commit, for instance, the format string will be replaced with commit.

n

The null string.

p

The name of the directory in the repository that's currently being processed.

r

The path of the repository root directory.

R

Relevant in repositories which are involved in proxy setups. This is the referrer, or the repository which the client contacted and which referred the operation to this server.

11.2.2. The checkoutlist File

The checkoutlist file is used to designate files to be stored in the CVSROOT directory in both RCS and clear-text formats. Most of the CVS administrative files are stored this way automatically, and the checkoutlist file allows you to store user-created files in the same way. The most common files to be stored like this are scripts executed by the scripting files (commitinfo, loginfo, rcsinfo, taginfo, and verifymsg; and after CVS 1.12.10, postadmin, postproxy, posttag, postwatch, and preproxy).

The file format is to list the names of the files, one file per line. All files must be in the CVSROOT directory.

To display an error message if the file cannot be checked out into CVSROOT, add whitespace, followed by the message, to the line the file is listed on. See Example 11-1.

Example 11-1. Adding whitespace to the message

11.2.3. The commitinfo File

The commitinfo file defines programs to run before a file is committed. If any of the programs exit with a nonzero exit status, the commit does not proceed. These programs run on the repository computer.

This file uses the standard scripting file syntax, and supports DEFAULT but not ALL. In addition to the usual format string variables, it allows s, a list variable containing the names of the files to be committed.

For backwards compatibility, the format string %r/%p %{s} is appended to the action if there is no format string in the action. This behavior should not be relied on, as it will probably be removed in a later version of CVS.

The commitinfo file is usually used to enforce project standards.

11.2.4. The config File

The config file contains CVS configuration options. It is normally found in the CVSROOT, but from CVS 1.12.13, you can use the -c option to pserver or server to specify a different config path.

Lines that start with a # are comments. All other lines are in the form:

keyword=value

There is one keyword/value pair per line. Each keyword/value pair represents a configuration option. Whitespace is significant, including carriage returns, tabs, and extra spaces.

From CVS 1.12.13, as well as specifying which config path the repository should use, you can also define which repository (or repositories) specific configurations apply to. The first section of the file contains default configurations. Later sections are defined by a string of the form [repository-path] on a line of its own. Each section applies to the repository path that precedes it. Multiple repository paths with no intervening configurations cause the configurations that follow them to apply to all the relevant paths.

Example 11-2 shows a configuration file. The comments explain which repositories are affected by which configurations.

Example 11-2. Multirepository configuration file

These are the available configuration options:

HistorySearchPattern=pattern HistoryLogPath=path

These two options control the files used to store the data for the cvs history command. The HistoryLogPath controls where the information is stored; the default is the file history in the repository's CVSROOT directory. The HistorySearchPattern controls where CVS looks for the data, and has the same default.

Any path to a filename is a valid value for HistoryLogPath, and can contain the variable $CVSROOT, which evaluates to the repository root. You can also use the substitutions listed in man date, the most useful of which (for this purpose) are %Y, %m, and %d (four-digit year, numeric month, and numeric day).

Any path to a filename is also a valid value for HistorySearchPattern, and it can also use $CVSROOT. Instead of the % substitutions, you can use pattern matches as described later in this chapter. Any files which match the pattern will be searched, in lexicographic order.

These options are valid from CVS 1.12.12 and later.

ImportNewFilesToVendorBranchOnly=value

This option is a repository-wide version of the -X command option to cvs import: during an import, new files are added only to the vendor branch, and not to the trunk. Valid values are yes or no. The default is no.

This option is valid from CVS 1.12.10.

KeywordExpand=value

This option controls which keywords may be expanded. It affects all files in all projects in the repository it's configured in. The value is in the format i|e[keyword list], where keyword list is a comma-separated list of keywords. The keywords may be any of the standard CVS keywords, or any local keyword as defined in the LocalKeyword configuration option (see following entry).

If the first character is i, the keywords in the list will be the only keywords that CVS expands. If the first character is e, the keywords in the list will not be expanded. A typical entry might be KeywordExpand=iAuthor, Id, Locker, which would limit expansion to the Author, ID, and Locker keywords.

This option is valid starting with CVS 1.12.2.

LocalKeyword=value=keyword

This option creates a keyword local to the current repository, which is an alias for one of the existing keywords. You could use LocalKeyword=Filename=RCSfile, for example, which would mean you could use $Filename$ instead of $RCSfile$ as the keyword that generates the name of the current file (or Path=Source to get the full path from the repository root).

This option is valid from CVS 1.12.2.

LockDir=directory

If this setting is present, CVS puts lock files in the specified directory rather than in the repository. You must create the directory, but CVS creates all the necessary subdirectories. LockDir is valid from CVS 1.11.

LogHistory=value

The text in value controls which actions are logged to the history file in the repository's CVSROOT directory. The valid values can be any combination of the following:

A

Log when a file is added to the repository.

C

Log when a file would have been updated in a sandbox, but needed to be merged and there were conflicts in the merge.

E

Log when a file is exported.

F

Log when a file is released.

G

Log when a file is updated in a sandbox with a successful merge.

M

Log when a file is modified (a sandbox revision is added to the repository).

O

Log when a file is checked out.

P

Log when a file is patched.

R

Log when a file is removed from the repository.

T

Log when a file is tagged or rtagged.

U

Log when a file is updated in a sandbox with no merge required.

W

Log when a file is deleted from a sandbox during an update because it is no longer active in the repository.

MaxCommentLeaderLength=value

This option affects the processing of the $ Log$ keyword. The text preceding the string $ Log$ on its line is the comment leader. If the comment leader exceeds the value, the keyword is ignored; unless the configuration option UseArchiveCommentLeader is set to yes, in which case the keyword is expanded with the comment leader specified by the repository copy of the file.

The value defaults to 20 bytes. As a bare number, it represents a value in bytes. If suffixed with k, M, G, or T, it represents kilobytes, megabytes, gigabytes, or terabytes, respectively.

This option is valid from CVS 1.12.10.

MinCompressionLevel=value MaxCompressionLevel=value

These control the compression level used by the CVS server, and correspond to the same levels available to clients with the -z global option. The values range from 0 (no compression) to 9 (maximum compression). If the client requests a compression level that is outside the ranges set with these options, the server uses the closest available compression level.

If the minimum compression level is higher than 0 and the client is older than 1.12.13, the server may exit with an error message if the client doesn't request compression. Clients later than 1.12.13 handle this more gracefully.

These options are valid starting with CVS 1.12.12.

PrimaryServer=repository-path

If the repository path is not the current repository, the server acts as a write proxy to the repository specified in repository-path. See Chapter 6 for more information.

This option is valid starting with CVS 1.12.10.

RCSBIN=directory

This option provides the directory in which CVS should look for the rcs program. This option applies only to CVS Versions 1.9.12 to 1.9.18; it is obsolete and ignored in later versions.

RereadLogAfterVerify=value

The log message saved during cvs commit might be changed if the verifymsg file is in use. This option controls whether the message is reread after the program listed in the verifymsg file runs.

This option is useful only if the verifymsg file is in use. These are the available options:

always or yes

Reread the log message after the verifymsg file has been processed. This option is the default case.

never or no

Do not reread the log message after the verifymsg file has been processed.

stat

Check whether the log message has been changed, using the filesystem's stat( ) command. If it has changed, reread the log message. This option can take up to an extra second per directory to process than the never case, but it may be faster than always if the log messages aren't always changed by verifymsg.

SystemAuth=value

If value is yes, the server authenticates the connecting user with the passwd file. If the user fails to authenticate there, the server authenticates the user against the main user database for the operating system. If value is no, the server authenticates the user only against the passwd file. The default value is yes.

This option is useful only if you have clients connecting to CVS in pserver mode.

TmpDir=path

This allows CVS to use a directory other than /tmp for its temporary files. The path should be a full path and the directory specified in the path should exist.

This option is valid from CVS 1.12.12.

TopLevelAdmin=value

If value is yes, a CVS subdirectory is created in the current working directory when you check out a sandbox. If value is no, the CVS subdirectories are created only in the actual sandbox directory tree. The default is no.

UseArchiveCommentLeader=value

The value may be true or false. Setting it to true only has an effect if the comment leader is set in the repository copy of a particular file. The comment leader can be set with the cvs admin command.

If the value is set to true, there is a comment leader in the repository file, and the text preceding the $Log$ keyword in a file is longer than the value of MaxCommentLeaderLength, the comment leader in the repository copy of the file will be used in place of the text preceding the $Log$ keyword.

Also see MaxCommentLeaderLength. This option is valid from CVS 1.12.10.

UseNewInfoFmtStrings=value

The value can be set to yes or no. It controls whether the scripting files use the old or new syntax. This option will be removed in later versions of CVS, and all scripting files will use the new syntax.

UserAdminOptions=value

This option is available in CVS 1.12.1 and later. If value exists, any user can run cvs admin options listed in value. The contents of value must be a string of letters with no separators or spaces, and the letters must be the command options (without parameters) for cvs admin.

If the cvsadmin group exists on the server machine, then only members of the cvsadmin group are allowed to run commands not listed in value.

11.2.5. The cvsignore File

The cvsignore file contains a list of filenames or filename patterns that CVS should not process. The syntax for this file is a space-separated or line-ending-separated list of filenames or name patterns. cvsignore uses wildcard pattern matching.

The special ! filename causes CVS to clear its ignore list. The special * filename causes CVS to ignore everything. See Chapter 6 for additional information.

11.2.6. The cvswrappers File

The cvswrappers file contains a line-ending-separated list of wrappers that control the merge method or keyword-substitution mode of files, based on a filename pattern. The syntax of a wrapper is as follows:

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

The wildcards are matched to filenames when files are added to the repository. See Chapter 3 for more information.

These are the options and values:

-m 'mode'

Indicates the merge methodology to use for files that match the pattern. Valid modes are COPY or MERGE.

-k 'mode'

Indicates the keyword-expansion mode to use for files that match the pattern. The keyword-expansion modes are provided in "Keywords and Keyword Modes" later in this chapter.

-f 'path_to_filter'

Processes the file through the filter program every time the file leaves the repository. This option is not available in CVS 1.10 and later.

-t 'path_to_filter'

Processes the file through the filter program every time the file enters the repository. This option is not available in CVS 1.10 and later.

11.2.7. The editinfo File

The editinfo file is obsolete; it has been replaced by verifymsg and rcsinfo, and removed as of CVS 1.12.2. In CVS versions that use editinfo, this file enforces the use of a specific editor when entering log messages. If CVS is called from a remote client, or if the -m or -F command options are used with cvs commit, the editinfo file is not used. If the editor exits with a nonzero exit status, the commit does not proceed.

11.2.8. The history File

The history file contains the information displayed by the cvs history command. It must be writable by all CVS users and is created by cvs init to be owner-, group-, and world-writable. This file should not be edited manually; all changes should occur through CVS.

If you wish to turn history logging off, a simple way to do so is to rename the history file. The file can also be removed or rotated like any logfile, with no effect on any CVS command other than cvs history. (If you do rotate the file, consider whether to lock the repository during the process of moving the file.)

11.2.9. The loginfo File

The loginfo file defines programs to run when information is recorded in the repository. It runs once per directory in a commit, after the files in the directory have been successfully recorded. It also runs after a successful import, and after a directory has been successfully added to the repository. These programs run on the repository computer.

This file uses the standard scripting file syntax, and supports both DEFAULT and ALL. In addition to the usual format string variables, it allows:

s

A list variable that expands to the names of the current files being processed.

T

A list variable that expands to the tag name of the destination, or the empty string if there is no relevant tag name.

V

A list variable that expands to the files' revision number prior to the commit.

v

A list variable that expands to the files' revision number after the commit.

For backwards compatibility, if there is no UseNewFormatStrings setting in the configuration file, loginfo is processed the old way. This behavior should not be relied on, as it will probably be removed in a later version of CVS. See Chapter 7 for information on the old format.

11.2.10. The modules File

The modules file is used to group arbitrary files or directories into a single module. Once a module is defined, the project files and directories it defines can be checked out into a sandbox by either the module name or the name of the repository directory it represents. The modules file can also specify programs to run when files in the module are committed, exported, updated, checked out, or tagged with rtag.

Each module definition needs to be on a line of its own. When adding directories to module definitions, use paths relative to the repository root directory.

An alias module can be used to group files and directories into a single module, regardless of where they are stored in the repository tree. The syntax for an alias module definition is as follows:

module_name -a path [path...]

A path may be a pathname to a file or directory or it may be another module name, and there may be any number of paths. If a path leads to a directory, all subdirectories and files are included in the module. If you wish to exclude subdirectories from an alias module, use an exclamation mark (!) in front of the directory name.

A regular module is used to define options for a project. It can also be used to define subsets of a project or group modules together. The syntax of a regular module is as follows:

module_name [options] [directory [files|subdirectories...]] [&modules...]

The directory should be a path relative to the repository root directory. If filenames or subdirectory names are included, they should be in the directory, and the module definition then applies only to those files or subdirectories. You can include a predefined module in a regular module by prefixing the module name with an ampersand (&) and specifying the resulting name in place of directory in the syntax. The module can be a regular module or an alias module.

Most of the options for a regular module define scripts to run immediately after a CVS command on the files in the module. Here is the full list of options for regular modules:

-d directory_name

Use directory_name rather than the module name as the name of the sandbox root directory.

-e script

Run the script when the module is exported. The script is given the module name as an argument.

-i script

Run the script when the module is committed. The script is given the full pathname of the relevant repository directory as an argument. This option is obsolete in CVS 1.11.6 and later.

-o script

Run the script when the module is checked out. The script is given the module name as an argument.

-s status

Provide a status for the module. This option has no meaning internal to CVS, but when the cvs checkout -s command runs, the status affects the display order.

CVS allocates an 11-character space for the status string when it is displayed, but the string is not truncated if it is longer than 11 characters.

-t script

Run the script when rtag is used on the module. This option does not run when tag is used. The script is given two arguments: the module name and the name of the tag.

-u script

Run the script when the module is updated. The script is given the full pathname of the affected repository directory as an argument. This option is obsolete in CVS 1.11.6 and later.

Each script designated in the modules file runs immediately after its associated CVS command completes. For example, the -o script runs after a checkout command for the module completes.

If the repository is not on the same computer as the client, the scripts for the -i and -u options are copied from their original location in the repository to the client computer and stored in the Checkin.prog and Update.prog files in the CVS subdirectories in the sandbox. These scripts are later copied back to the server computer, where they run. For security reasons, this behavior is changed in CVS 1.11.6 and later.

All other scripts called from the modules file run on the repository server computer.

The sandbox copies of the Checkin.prog and Update.prog files are not changed when the modules file or the repository computer's copies of the scripts are changed. To change Checkin.prog and Update.prog, commit and release the sandbox and check out a new sandbox. (This step is not relevant if you're using 1.11.6 or later.)

11.2.11. The notify File

The notify file contains the commands to run when conditions exist for cvs watch to notify a user of a change to a watched file.

The syntax of the notify file is a series of lines, each line in the following format:

filename_pattern command

The filename_pattern can be ALL or any wildcard pattern. The command can be any sh shell command, but it must contain %s, which is replaced by the name of the user to notify. The rest of the notification information is provided to the command through standard input (stdin).

11.2.12. The passwd File

The passwd file contains the usernames and passwords for the pserver repository method. This file is usually edited in place, not checked out like the other administrative files. If you wish to check it out, add it to the commitinfo file, but be aware of the security risks explained in Chapter 8.

The format for entries in the passwd file is:

CVS_username:password:system_username

The CVS_username is the name the user sends to CVS. The system_username is the name the CVS programs run under. If these names are the same, you don't need to include the system_username. The system_username must be a valid username on the server; if the system_username does not exist on the server, CVS commands will fail even if the user authenticates with CVS.

The passwords need to be encrypted with the standard Unix crypt( ) function. CVS does not provide a tool to encrypt passwords, so they need to be encrypted elsewhere and then pasted into the file. If the password field is empty, the user automatically authenticates. You can use the Unix and Linux program mkpasswd to encrypt a string for use as a password.

A single system username can be shared by multiple users with different CVS usernames. This feature allows several people to work on a project, while recording the changes across multiple users.

11.2.13. The postadmin File

The postadmin file defines programs to run after any cvs admin command that modifies a file is run. These programs run on the repository computer.

This file uses the standard scripting file syntax, and supports both DEFAULT and ALL.

11.2.14. The postproxy File

The postproxy file defines programs to run after a secondary server has completed a connection to a primary server, and before the secondary server releases the connection to the client. These programs run on the secondary server, and are called once per directory. It is recommended that the postproxy include a command to update the secondary server's copy of the repository.

This file uses the standard scripting file syntax, and supports both DEFAULT and ALL. It has the additional format variable P, the repository path of the primary server.

11.2.15. The posttag File

The posttag file defines programs to run after any cvs tag or rtag command that modifies a file is run. These programs run on the repository computer.

This file uses the standard scripting file syntax, and supports both DEFAULT and ALL. It permits the same format string attributes as the taginfo file: see the section on the taginfo file for more information.

11.2.16. The postwatch File

The postwatch file defines programs to run after any cvs watch, edit, or unedit command that modifies the repository's watch administrative file, fileattr. See Chapter 6 (specifically, information on fileattr) for more information on which commands are affected. These programs run on the repository computer.

This file uses the standard scripting file syntax, and supports both DEFAULT and ALL.

Note that edit and unedit do not always contact the server, and sometimes cache their notification to be run later.

11.2.17. The preproxy File

The preproxy file defines programs to run before a secondary server connects to a primary server, and after the client has contacted the secondary server. These programs run on the secondary server, and are called once, from the top directory specified by the client's request.

This file uses the standard scripting file syntax, and supports both DEFAULT and ALL. It has the additional format variable P, the repository path of the primary server.

11.2.18. The rcsinfo File

The rcsinfo file defines forms to display as the templates for commit log messages. The rcsinfo file is processed before a file is committed.

This file uses the standard scripting file syntax, and supports both DEFAULT and ALL. The action in the case of the rcsinfo file must be a pathname to a template file.

If the repository is not on the same computer as the client, CVS stores a copy of the template (or templates) that matches each sandbox directory in the appropriate CVS subdirectory of each sandbox. In versions prior to 1.12.1, this file is not updated with other sandbox files, so if the rcsinfo file or the main template changes, your users should release and recreate their sandboxes. (In 1.12.1 and later, the file is updated with the other sandbox files.)

11.2.19. The readers File

The readers file contains the usernames of people who have read-only access to the repository via the pserver remote-access method. The readers and writers files use the CVS_username, not the system_username, to determine whether a user has access. The file should contain one name per line. The newline character after the last username is significant.

If a user is listed in the readers file, he has read-only access to the repository, even if he is also listed in the writers file.

11.2.20. The taginfo File

The taginfo file defines programs to run before a file is tagged. If any of the programs exit with a nonzero exit status, the tag does not proceed.

This file uses the standard scripting file syntax, and supports both DEFAULT and ALL. In addition to the usual format string variables, it allows these:

b

Tag type. This is a single-element variable, and evaluates to T for a branch, N for a nonbranch, or ? for unknown.

o

Operation. This is a single-element variable, and evaluates to add, del, or mov, for additions, deletions, or moving of a tag.

s

This is a list variable, and evaluates to the current filename(s).

T

This is a list variable, and evaluates to the tag name of the destination, or the empty string if there is no such tag name.

t

This is a single-element variable, and evaluates to the new tag name.

V

This is a list variable, and evaluates to the old version number (as for a move or delete operation).

v

This is a list variable, and evaluates to the new version number (as for an add or move operation).

For backwards compatibility, the format string %t %o %p %{sv} is appended to the action if there is no format string in the action. This behavior should not be relied on, as it will probably be removed in a later version of CVS.

11.2.21. The users File

The users file provides a list of email addresses for users whose mailboxes are not on the same machine as the CVS repository. This file is used by the command given in the notify file, and it becomes the input represented by the %s string.

The format of this file is a separate line for each user, consisting of the username and the email address to send notifications to, in the following format:

username:email

11.2.22. The val-tags File

The val-tags file contains a list of valid tag names, acting as an internal cache for CVS. It must be writable by all CVS users, and is created by cvs init to be owner- and group-writable. This file should not be edited manually; all changes should occur through CVS.

11.2.23. The verifymsg File

The verifymsg file defines programs to run after a log message has been entered, but before the commit takes place. The programs are passed the log message, which they can modify or parse to ensure that all essential fields have been filled in. The verifymsg file is usually used with the rcsinfo file to manage log messages. If a program called from verifymsg exits with a nonzero error status, the commit is aborted.

The file syntax for verifymsg is as follows:

name_pattern action

The name_pattern is a regular expression that must match a relative path within the repository. The action is a command-line template or the address of a script, plus any parameters required for that script or template. The log message is passed to the script or template on the standard input (stdin), as is the path to a temporary file containing the log message.

Lines starting with the hash symbol (#) are comments and are ignored. The special DEFAULT pattern matches directories that do not match any other pattern. CVS uses the script on the first line with a directory-name pattern that matches the directory tree a file is in.

A script invoked through verifymsg can modify the log message, and the config file in the CVSROOT directory then determines whether CVS reads and uses the modified log message or the original one for the rest of the commit process.

11.2.24. The writers File

The writers file contains the usernames of people who have read-write access to the repository via the pserver remote-access method. The readers and writers files use the CVS username, not the system username, to determine whether a user has access. The file should contain one username per line. The newline character after the last user is significant.

If a user is listed in the writers file but not the readers file, she has read-write access to the repository.