Next: , Previous: The modules File, Up: The CVSROOT/ Administrative Directory


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

Karl Fogel wrote this book. Buy a printed copy via his homepage at red-bean.com

copyright  ©  August 22 2019 sean dreilinger url: https://durak.org/sean/pubs/software/cvsbook/The-commitinfo-And-loginfo-And-rcsinfo-Files.html