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. These files can be checked out 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.
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).
The file format is to simply list the names of the files, one file per line. All files must be in the CVSROOT directory.
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.
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. The action is a command-line template or the address of a script, plus any parameters required for that script or template. The full path of the repository and the filenames of all files to be committed are appended as parameters by CVS during processing.
Example 11-1 shows a commitinfo file that calls a formatcheck script with the --style=gnu parameter, for any files committed from the src directory of the wizzard project. The formatcheck script is stored in the repository's CVSROOT directory.
^wizzard/src\(/\|$\) /home/cvs/CVSROOT/formatcheck --style=gnu
Lines starting with the hash symbol (#) are comments and are ignored. The special ALL pattern matches all directories. The special DEFAULT pattern matches directories that do not match any pattern except ALL. CVS uses the script on the first line with a directory-name pattern that matches the directory tree the file is in. If no pattern match is found, the script specified by the DEFAULT line is executed. Scripts specified by ALL lines are always executed.
The commitinfo file is usually used to enforce project standards.
The config file contains CVS configuration options. 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.
These are the available configuration options:
If this setting is present, CVS puts lock files in the specified directory rather than in the repository. You need to create the directory, but CVS creates all the necessary subdirectories.
|
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:
Log when a file is added to the repository.
Log when a file would have been updated in a sandbox, but needed to be merged and there were conflicts in the merge.
Log when a file is exported.
Log when a file is released.
Log when a file is updated in a sandbox with a successful merge.
Log when a file is modified (a sandbox revision is added to the repository).
Log when a file is checked out.
Log when a file is removed from the repository.
Log when a file is tagged or rtagged.
Log when a file is updated in a sandbox with no merge required.
Log when a file is deleted from a sandbox during an update because it is no longer active in the repository.
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.
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:
Reread the log message after the verifymsg file has been processed. This option is the default case.
Do not reread the log message after the verifymsg file has been processed.
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.
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.
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.
CVS 1.11.5 does not support this option. In the versions that support it, the option causes CVS to store sandbox permissions in the repository with other data for each revision and pass that data to the sandbox when a file revision is checked out. The valid values are yes and no.
This option is available in CVS 1.12.1 and later. If value exists, then 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.
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.
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.
These are the options and values:
Indicates the merge methodology to use for files that match the pattern. Valid modes are COPY or MERGE.
Indicates the keyword-expansion mode to use for files that match the pattern. The keyword-expansion modes are provided in Section 11.6 later in this chapter.
Process the file through the filter program every time the file leaves the repository. This option is not available in CVS 1.10 and later.
Process the file through the filter program every time the file enters the repository. This option is not available in CVS 1.10 and later.
The editinfo file is obsolete; it has been replaced by verifymsg and rcsinfo. 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.
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 log file, 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.)
The loginfo file defines programs to run when the file has been committed successfully. These programs run on the repository computer.
Lines starting with the hash symbol (#) are comments and are ignored. The special ALL pattern matches all directories. The special DEFAULT pattern matches directories that do not match any pattern except ALL. CVS uses the script on the first line with a directory-name pattern that matches the directory tree the file is in. If no pattern match is found, the script specified by the DEFAULT line is executed. Scripts specified by ALL lines are always executed.
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. The action is a command-line template or the address of a script, plus any parameters required for that script or template, plus a format string. The action is passed the log message on the standard input, followed by the repository path and the results of the format string.
The format string is processed by CVS before being passed to the action's script or command. Before processing, the format string consists of a %, followed by a space, a single variable, or a set of variables enclosed in braces ({ }). These are the variables for the format string:
Expands to the name of the current file being processed.
Expands to the file's revision number prior to the commit.
Expands to the file's revision number after the commit.
When CVS processes the format string, the output passed to the script is a space-separated list of variable expansions, with a variable expansion for each file that was committed. The series of variable expansions is a comma-separated set of strings, such that %{sV} could be expanded to a string like main.c,1.3.
Dollar signs ($), backticks (`), backslashes (\), and quotation marks (") in the repository path or in any filenames expanded from the format string are escaped with a backslash, but the backslash is not visible in the called scripts.
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:
Use directory_name rather than the module name as the name of the sandbox root directory.
Run the script when the module is exported. The script is given the module name as an argument.
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.
Run the script when the module is checked out. The script is given the module name as an argument.
Provide a status for the module. This 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.
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.
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.
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).
|
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 can allow several people to work on a project, while recording the changes across multiple users.
The rcsinfo file defines forms to display as the templates for commit log messages. The rcsinfo file is processed before a file is committed.
The file syntax is:
name_pattern action
The name_pattern is a regular expression that must match a relative path within the repository. The action is the path to a template file for log messages.
Lines starting with the hash symbol (#) are comments and are ignored. The special ALL pattern matches all directories. The special DEFAULT pattern matches directories that do not match any other pattern. CVS uses the file on the first line with a directory name pattern that matches the directory tree the file is in. Files in each directory are processed according to the rules given in the first matching line or in the DEFAULT line. In addition, rules given in ALL lines are always applied.
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. 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.
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.
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.
The file syntax is:
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 path and filename of a script, plus any parameters required for that script or template. The full path of the repository and the filenames of all files to be committed are appended as parameters.
Lines starting with the hash symbol (#) are comments and are ignored. The special ALL pattern matches all directories. 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 the file is in. Files in each directory are processed according to the rules given in the first matching line or in the DEFAULT line. In addition, rules given in ALL lines are always applied.
A string with the following format is appended to the script parameters:
tagname operation repository_path file_revision_pair [file_revision_pair...]
The file_revision_pair is a space-separated filename and revision number, and there is one pair for each file to be tagged. The operation is add, mov, or del. The mov operation is used when tag or rtag is called with -F, and del is used when they are called with -d.
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
|
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.
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.
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.
|
|
|
|
| Top |
