GNU Info

(cvsbook.info)The commitinfo And loginfo And rcsinfo Files

---

Next: The verifymsg And rcsinfo Files Prev: The modules File Up: The CVSROOT/ Administrative Directory

---

Enter node , (file) or (file)node

The commitinfo And loginfo And rcsinfo Files
--------------------------------------------

Most of the other administrative files provide programmatic "hooks"
into various parts of the commit process (for example, the ability to
validate log messages or file states before permitting the commit, or
the ability to notify a group of developers whenever a commit happens in
a certain directory of the repository).

The files generally share a common syntax.  Each line is of the form:

     REGULAR_EXPRESSION    PROGRAM_TO_RUN

The regular expression will be tested against the directory into which
the commit is taking place (with the directory name relative to the top
of the repository).  If it matches, the designated program will be run.
The program will be passed the names of each of the files in the commit;
it can do whatever it likes with those names, including opening up the
files and examining their contents.  If the program returns with a
nonzero exit status, the commit is prevented from taking place.

("Regular expressions" are a system for concisely describing classes of
strings.  If you aren't familiar with regular expressions, you can get
by with the following short summary: `foo' would match any file whose
name contains the string `foo'; and `foo.*bar' would match any file
whose name contains `foo', followed by any number of characters,
followed by the string `bar'.  That's because normal substrings match
themselves, but `.' and `*' are special.  `.' matches any character,
and `*' means match any number of the preceding character, including
zero.  The `^' and `$' signs mean match at the beginning and end of the
string, respectively; thus, `^foo.*bar.*baz$' would match any string
beginning with `foo', containing `bar' somewhere in the middle, and
ending with `baz'.  That's all we'll go into here; this summary is a
very abbreviated subset of full regular expression syntax.)

The "commitinfo" file is for generic hooks you want run on every
commit.  Here are some example commitinfo lines:

     ^a-subdir*     /usr/local/bin/check-asubdir.sh
     ou             /usr/local/bin/validate-project.pl

So any commit into myproj/a-subdir/ would match the first line, which
would then run the check-asubdir.sh script.  A commit in any project
whose name (actual repository directory name, not necessarily module
name) contained the string `ou' would run the validate-project.pl
script, unless the commit had already matched the previous a-subdir
line.

In place of a regular expression, the word `DEFAULT' or `ALL' may be
used.  The DEFAULT line (or the first DEFAULT line, if there are more
than one) will be run if no regular expression matches, and each of the
ALL lines will be run in addition to any other lines that may match.

The file names passed to the program do not refer to RCS files - they
point to normal files, whose contents are exactly the same as the
working-copy files being committed.  The only unusual aspect is that CVS
has them temporarily placed inside the repository, so they'll be
available to programs running on the machine where the repository is
located.

The "loginfo" file is similar to commitinfo, except that instead of
acting on the files' contents, it acts on the log message.  The left
side of the loginfo file contains regular expressions, including
possibly DEFAULT and ALL lines.  The program invoked on the right side
receives the log message on its standard input; it can do whatever it
wants with that input.

The program on the right side can also take an arbitrary number of
command-line arguments.  One of those arguments can be a special `%'
code, to be expanded by CVS at runtime, as follows:

     %s    ------>      name(s) of the file(s) being committed
     %V    ------>      revision number(s) before the commit
     %v    ------>      revision number(s) after the commit

The expansion always begins with the repository subdirectory (relative
to the top of the repository), followed by the per-file information.
For example, if the files committed were foo, bar, and baz, all in
`myproj/a-subdir', then `%s' would expand into

     myproj/a-subdir  foo  bar  baz

whereas `%V' would expand to show their old revision numbers

     myproj/a-subdir  1.7  1.134  1.12

and `%v' their new revision numbers:

     myproj/a-subdir  1.8  1.135  1.13

You can combine `%' expressions by enclosing them in curly braces
following `%' sign - this will expand them into a series of
comma-separated sublists, each containing the corresponding information
for one file in the commit.  For instance, `%{sv}' would expand to

     myproj/a-subdir  foo,1.8  bar,1.135  baz,1.13

and `%{sVv}' would expand to

     myproj/a-subdir  foo,1.7,1.8  bar,1.134,1.135  baz,1.12,1.13

(You may have to look carefully to distinguish the commas from the
periods in those examples.)

Here is a sample loginfo file:

     ^myproj$   /usr/local/newrepos/CVSROOT/log.pl -m myproj-devel@foobar.com %s
     ou         /usr/local/bin/ou-notify.pl  %{sv}
     DEFAULT    /usr/local/bin/default-notify.pl  %{sVv}

In the first line, any commit in the myproj subdirectory of the
repository invokes `log.pl', passing it an email address (to which
`log.pl' will send a mail containing the log message), followed by the
repository, followed by all the files in the commit.

In the second line, any commit in a repository subdirectory containing
the string `ou' will invoke the (imaginary) `ou-notify.pl' script,
passing it the repository followed by the file names and new revision
numbers of the files in the commit.

The third line invokes the (equally imaginary) `default-notify.pl'
script for any commit that didn't match either of the two previous
lines, passing it all possible information (path to repository, file
names, old revisions, and new revisions).