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 2.4 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		Defining modules
C.2 The cvswrappers file		Specify binary-ness based on file name
C.3 The commit support files
C.4 Commitinfo		Pre-commit checking
C.5 Verifying log messages		How are log messages evaluated?
C.6 Editinfo		Specifying how log messages are created

                                (obsolete)

C.7 Loginfo		Where should log messages be sent?
C.8 Rcsinfo		Templates for the log messages
C.9 Ignoring files via cvsignore
C.10 The checkoutlist file		Adding your own administrative files
C.11 The history file		History information
C.12 Expansions in administrative files		Various variables are expanded
C.13 The CVSROOT/config configuration file		Miscellaneous CVS configuration

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		The simplest kind of module
C.1.2 Regular modules
C.1.3 Ampersand modules
C.1.4 Excluding directories		Excluding directories from a module
C.1.5 Module options		Regular and ampersand modules can take options
C.1.6 How the modules file "program options" programs are run		How the modules "program options" programs are run.

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.

-i prog

Specify a program prog to run whenever files in a module are committed. prog runs with a single argument, the full pathname of the affected directory in a source repository. The `commitinfo', `loginfo', and `verifymsg' files provide other ways to call a program on commit.

-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.

-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 taginfo is a better solution (see section 8.3 User-defined logging).

-u prog

Specify a program prog to run whenever `cvs update' is executed from the top-level directory of the checked-out module. prog runs with a single argument, the full path to the source repository for this module.

You should also see see section C.1.6 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 filesystem, 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 commit and update programs are locally-based, and are run as follows:-

The program is always run locally. One must re-checkout the tree one is using if these options are updated in the modules administrative file. The file CVS/Checkin.prog contains the value of the option `-i' set in the modules file, and similarly for the file CVS/Update.prog and `-u'. The program is always executed from the top level of the checked-out copy on the client. Again, the program is first searched for in the checked-out copy and then using the path.

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 9. 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 commit support files

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

There are three kind 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.

`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 C.8 Rcsinfo).

`editinfo'

The specified program is used to edit 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 C.8 Rcsinfo). (obsolete)

`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!

C.3.1 The common syntax

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. This is a basic regular expression in the syntax used by GNU emacs.

• 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 is used. The rest of the line is used as a file name or command-line as appropriate.

C.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.

As mentioned earlier, each line in the `commitinfo' file consists of a regular expression and a command-line template. The template can include a program name and any number of arguments you wish to supply to it. The full path to the current source repository is appended to the template, followed by the file names of any files involved in the commit (added, removed, and modified files).

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.

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 the name `DEFAULT'.

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

C.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.

Each line in the `verifymsg' file consists of a regular expression and a command-line template. The template must include a program name, and can include any number of arguments. The full path to the current log message template file is appended to the template.

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 repository name does not match any of the regular expressions in this file, the `DEFAULT' line is used, if it is specified.

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

Note that the verification script cannot change the log message; it can merely accept it or reject it.

The following is a little silly example of a `verifymsg' file, together with the corresponding `rcsinfo' file, the log message template and an 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 head -1 < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then exit 0 else echo "No BugId found." exit 1 fi

The `verifymsg' file contains this line:

^tc /usr/cvssupport/bugid.verify

The `rcsinfo' file contains this line:

^tc /usr/cvssupport/tc.template

C.6 Editinfo

NOTE: The `editinfo' feature has been rendered obsolete. To set a default editor for log messages use the EDITOR environment variable (see section D. All environment variables which affect CVS) or the `-e' global option (see section A.4 Global options). See C.5 Verifying log messages, for information on the use of the `verifymsg' feature for evaluating log messages.

If you want to make sure that all log messages look the same way, you can use the `editinfo' file to specify a program that is used to edit the log message. This program could be a custom-made editor that always enforces a certain style of the log message, or maybe a simple shell script that calls an editor, and checks that the entered message contains the required fields.

If no matching line is found in the `editinfo' file, the editor specified in the environment variable $CVSEDITOR is used instead. If that variable is not set, then the environment variable $EDITOR is used instead. If that variable is not set a default will be used. See 1.3.2 Committing your changes.

The `editinfo' file is often most useful together with the `rcsinfo' file, which can be used to specify a log message template.

Each line in the `editinfo' file consists of a regular expression and a command-line template. The template must include a program name, and can include any number of arguments. The full path to the current log message template file is appended to the template.

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 edit script in a module, and then overriding it in a subdirectory.

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

If the edit script he current source repository is appended to the template, followed by the file names of any files involved in the commit (added, removed, and modified files).

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.

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 the name `DEFAULT'.

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

C.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.

Each line in the `verifymsg' file consists of a regular expression and a command-line template. The template must include a program name, and can include any number of arguments. The full path to the current log message template file is appended to the template.

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 repository name does not match any of the regular expressions in this file, the `DEFAULT' line is used, if it is specified.

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

Note that the verification script cannot change the log message; it can merely accept it or reject it.

The following is a little silly example of a `verifymsg' file, together with the corresponding `rcsinfo' file, the log message template and an 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 head -1 < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then exit 0 else echo "No BugId found." exit 1 fi

The `verifymsg' file contains this line:

^tc /usr/cvssupport/bugid.verify

The `rcsinfo' file contains this line:

^tc /usr/cvssupport/tc.template

C.6 Editinfo

NOTE: The `editinfo' feature has been rendered obsolete. To set a default editor for log messages use the EDITOR environment variable (see section D. All environment variables which affect CVS) or the `-e' global option (see section A.4 Global options). See C.5 Verifying log messages, for information on the use of the `verifymsg' feature for evaluating log messages.

If you want to make sure that all log messages look the same way, you can use the `editinfo' file to specify a program that is used to edit the log message. This program could be a custom-made editor that always enforces a certain style of the log message, or maybe a simple shell script that calls an editor, and checks that the entered message contains the required fields.

If no matching line is found in the `editinfo' file, the editor specified in the environment variable $CVSEDITOR is used instead. If that variable is not set, then the environment variable $EDITOR is used instead. If that variable is not set a default will be used. See 1.3.2 Committing your changes.

The `editinfo' file is often most useful together with the `rcsinfo' file, which can be used to specify a log message template.

Each line in the `editinfo' file consists of a regular expression and a command-line template. The template must include a program name, and can include any number of arguments. The full path to the current log message template file is appended to the template.

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 edit script in a module, and then overriding it in a subdirectory.

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

If the edit script he current source repository is appended to the template, followed by the file names of any files involved in the commit (added, removed, and modified files).

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.

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 the name `DEFAULT'.

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

C.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.

Each line in the `verifymsg' file consists of a regular expression and a command-line template. The template must include a program name, and can include any number of arguments. The full path to the current log message template file is appended to the template.

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 repository name does not match any of the regular expressions in this file, the `DEFAULT' line is used, if it is specified.

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

Note that the verification script cannot change the log message; it can merely accept it or reject it.

The following is a little silly example of a `verifymsg' file, together with the corresponding `rcsinfo' file, the log message template and an 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 head -1 < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then exit 0 else echo "No BugId found." exit 1 fi

The `verifymsg' file contains this line:

^tc /usr/cvssupport/bugid.verify

The `rcsinfo' file contains this line:

^tc /usr/cvssupport/tc.template

C.6 Editinfo

NOTE: The `editinfo' feature has been rendered obsolete. To set a default editor for log messages use the EDITOR environment variable (see section D. All environment variables which affect CVS) or the `-e' global option (see section A.4 Global options). See C.5 Verifying log messages, for information on the use of the `verifymsg' feature for evaluating log messages.

If you want to make sure that all log messages look the same way, you can use the `editinfo' file to specify a program that is used to edit the log message. This program could be a custom-made editor that always enforces a certain style of the log message, or maybe a simple shell script that calls an editor, and checks that the entered message contains the required fields.

If no matching line is found in the `editinfo' file, the editor specified in the environment variable $CVSEDITOR is used instead. If that variable is not set, then the environment variable $EDITOR is used instead. If that variable is not set a default will be used. See 1.3.2 Committing your changes.

The `editinfo' file is often most useful together with the `rcsinfo' file, which can be used to specify a log message template.

Each line in the `editinfo' file consists of a regular expression and a command-line template. The template must include a program name, and can include any number of arguments. The full path to the current log message template file is appended to the template.

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 edit script in a module, and then overriding it in a subdirectory.

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

If the edit script he current source repository is appended to the template, followed by the file names of any files involved in the commit (added, removed, and modified files).

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.

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 the name `DEFAULT'.

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

C.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.

Each line in the `verifymsg' file consists of a regular expression and a command-line template. The template must include a program name, and can include any number of arguments. The full path to the current log message template file is appended to the template.

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 repository name does not match any of the regular expressions in this file, the `DEFAULT' line is used, if it is specified.

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

Note that the verification script cannot change the log message; it can merely accept it or reject it.

The following is a little silly example of a `verifymsg' file, together with the corresponding `rcsinfo' file, the log message template and an 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 head -1 < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then exit 0 else echo "No BugId found." exit 1 fi

The `verifymsg' file contains this line:

^tc /usr/cvssupport/bugid.verify

The `rcsinfo' file contains this line:

^tc /usr/cvssupport/tc.template

C.6 Editinfo

NOTE: The `editinfo' feature has been rendered obsolete. To set a default editor for log messages use the EDITOR environment variable (see section D. All environment variables which affect CVS) or the `-e' global option (see section A.4 Global options). See C.5 Verifying log messages, for information on the use of the `verifymsg' feature for evaluating log messages.

If you want to make sure that all log messages look the same way, you can use the `editinfo' file to specify a program that is used to edit the log message. This program could be a custom-made editor that always enforces a certain style of the log message, or maybe a simple shell script that calls an editor, and checks that the entered message contains the required fields.

If no matching line is found in the `editinfo' file, the editor specified in the environment variable $CVSEDITOR is used instead. If that variable is not set, then the environment variable $EDITOR is used instead. If that variable is not set a default will be used. See 1.3.2 Committing your changes.

The `editinfo' file is often most useful together with the `rcsinfo' file, which can be used to specify a log message template.

Each line in the `editinfo' file consists of a regular expression and a command-line template. The template must include a program name, and can include any number of arguments. The full path to the current log message template file is appended to the template.

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 edit script in a module, and then overriding it in a subdirectory.

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

If the edit script he current source repository is appended to the template, followed by the file names of any files involved in the commit (added, removed, and modified files).

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.

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 the name `DEFAULT'.

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

C.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.

Each line in the `verifymsg' file consists of a regular expression and a command-line template. The template must include a program name, and can include any number of arguments. The full path to the current log message template file is appended to the template.

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 repository name does not match any of the regular expressions in this file, the `DEFAULT' line is used, if it is specified.

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

Note that the verification script cannot change the log message; it can merely accept it or reject it.

The following is a little silly example of a `verifymsg' file, together with the corresponding `rcsinfo' file, the log message template and an 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 head -1 < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then exit 0 else echo "No BugId found." exit 1 fi

The `verifymsg' file contains this line:

^tc /usr/cvssupport/bugid.verify

The `rcsinfo' file contains this line:

^tc /usr/cvssupport/tc.template

C.6 Editinfo

NOTE: The `editinfo' feature has been rendered obsolete. To set a default editor for log messages use the EDITOR environment variable (see section D. All environment variables which affect CVS) or the `-e' global option (see section A.4 Global options). See C.5 Verifying log messages, for information on the use of the `verifymsg' feature for evaluating log messages.

If you want to make sure that all log messages look the same way, you can use the `editinfo' file to specify a program that is used to edit the log message. This program could be a custom-made editor that always enforces a certain style of the log message, or maybe a simple shell script that calls an editor, and checks that the entered message contains the required fields.

If no matching line is found in the `editinfo' file, the editor specified in the environment variable $CVSEDITOR is used instead. If that variable is not set, then the environment variable $EDITOR is used instead. If that variable is not set a default will be used. See 1.3.2 Committing your changes.

The `editinfo' file is often most useful together with the `rcsinfo' file, which can be used to specify a log message template.

Each line in the `editinfo' file consists of a regular expression and a command-line template. The template must include a program name, and can include any number of arguments. The full path to the current log message template file is appended to the template.

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 edit script in a module, and then overriding it in a subdirectory.

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

If the edit script he current source repository is appended to the template, followed by the file names of any files involved in the commit (added, removed, and modified files).

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.

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 the name `DEFAULT'.

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