The commit support files

The -i flag in the modules file can be used to run a certain program whenever files are committed (the section called “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.

triggers

This is the main control file that cvs uses. Most of the other commit support files are implemented through a trigger (known as the default trigger).

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 (the section called “rcsinfo”).

The verifymsg script may or may be able to change the log message depending on the value of the RereadLogAfterVerify setting in the config file.

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!

precommand

The specified program is called prior to command execution, and is passed the list of arguments supplied to the command. Returning an error from this script will terminate command execution.

postcommand

The specified program is called when the command is complete, and all locks have been released from the repository prior to returning to the user. This is useful to maintain checked-out copies of repositories and to perform cvs actions after a commit.

premodule

The specified program is called prior to entering a module. It is passed the repository, command and module name. Returning an error from this script will terminate command execution.

Not all commands use the premodule/postmodule scripts, only those which take modules as arguments, eg. checkout, repository commands such as rlog, rtag, etc.

postmodule

The specified program is called when module processing is complete. It is passed the repository, command and module name.

Not all commands use the premodule/postmodule scripts, only those which take modules as arguments, eg. checkout, repository commands such as rlog, rtag, etc.

postcommit

The specified program is called when a commit is complete, and all locks have been released from the repository prior to returning to the user. This is useful to maintain checked-out copies of repositories and to perform cvs actions after a commit.

This script has been largely superceded by the postcommand script.

historyinfo

This is called when any action which causes an entry in the history file is initiated. Its standard input receives the line to be written to the history log, in a semi-compressed format.

notify

When required this file is called durin a commit, and also during edit/unedit.

keywords

Define non-standard or user defined keyword mappings

script.vbs, script.js, script.pl, script.py, script.rb

(Win32 only) ActiveScript trigger file. Implemented through the script trigger library (script_trigger.dll).

shadow

Define shadow or checked-out workspaces on the server. Implemented by the checkout trigger library.

commit_email

Define templates for automatic sending of emails during commit.

tag_email

Define templates for automatic sending of emails during tag

notify_email

Define templates for automatic sending of emails during notify

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 uses Perl-Compatible regular expression syntax (PCRE). On case insensitive servers this expression is also case insensitive.

  • A whitespace separator--one or more spaces and/or tabs.

  • shell command the commonest form, invokes a shell script using the parameters described below.

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.

Each regular expression that matches the current directory name in the repository is considered for use. The first match will be used, followed by any matching lines that are prefixed by '+'. The rest of the line after the regular expression is used as a file name or command-line as appropriate.

Directory and filename separators must use Unix conventions (forward slashes) on all platforms.

All files have a set of default parameters (see the description of each file for details). In addition a number of common parameters are available to be passed to each file.

%c

Command currently being executed.

%d

Date and time of executing command.

%h

Remote host name, on client/server connections.

%u

Current cvs username.

%r

virtual repository name (repository alias, to be displayed to the user).

%R

Physical repository name (for file access).

%S

Session ID or commit ID.

%e

Current value of $CVSEDITOR.

%H

Local host name.

%P

Local directory (temporary directory in client/server connections).

%i

Client version string if supplied by the client.

%n

An empty string.

%%

% sign

$...

CVSNT environment variable (see Appendix C, All environment variables which affect CVS), System environment variable, or User variable (see the section called “Expansions in administrative files”).

You can group parameters into a single script argument using the %{} syntax.

Parameters can be sent either to the script command line, or its standard input. Options for standard input begin with %<, as below.

%<option

Send value of option to standard input.

%<{options}

Send value of options to standard input on a single line.

%<< text for standard input\nhello %u!\n

Send the following string to standard input. This must be the last item on the line.

%<<TAG

Send everything in the file until the next occurence of TAG on its own to standard input. This must be the last item on the line.