svnlog

(Mail Subversion commit notifications)

SYNOPSIS

svnlog [-Ddhlosv] [-a address ...] [--confirm] [-c file] [--debbugs=address] [--diffstat=path] [-f from] [-H header ...] [-i regex ...] [--sendmail=path] [-p prefix] [--svnlook=path] repository revision

REQUIREMENTS

Subversion, including the svnlook command-line tool; Perl 5.8.0 or later; diffstat for the -s option; and a sendmail command that can accept formatted mail messages for delivery.

DESCRIPTION

svnlog is intended to be run out of Subversion's post-commit hook, generates a commit notification, and sends it via e-mail. The format is almost identical to the format of mail generated by cvslog. By default, the commit message will contain the author, date, and revision number; the files added, deleted, or modified; and the commit message. Optionally, the full diff of the commit or a diffstat(1) summary of the changes, or both, can be added to the notification.

For information on how to add svnlog to your Subversion repository, see INSTALLATION below. All necessary configuration options can be given on the command line, but if you would prefer you can also use the -c option to point svnlog at a configuration file. See "CONFIG FILE" below for the syntax.

The full path to the repository and the revision number of the change must be given on the command line. These are the same parameters that Subversion passes to its post-commit hook. svnlog must be able to find svnlook to work; if svnlook isn't on the default path, specify it via either the --svlook command-line option or the svnlook configuration parameter.

At least one -a option must be given or at least one address parameter must be set in the configuration file; otherwise, svnlog has nowhere to send mail and nothing to do.

OPTIONS

All of these options except -c, -h, and -v can also be set in a configuration file specified with -c. See "CONFIG FILE" below for the syntax.

-a address, --address=address

Send the commit notification to address. This option may occur more than once, and all specified addresses will receive a copy of the notification (including any addresses set in the configuration file, if any). There is no way to override the addresses set in the configuration file, just add more addresses.

-c file, --config=file

Load configuration options from file. See "CONFIG FILE" below for the syntax. Normally, command-line options override values set in the configuration file, but settings for -a (address) and -H (header) are cumulative between the command line and the configuration file.

--confirm

Prompt for user confirmation before sending the commit notification. The user must answer y or n, and if they answer n, svnlog will exit without doing anything further.

This option is something of a hack. It will only work if it can open the user's tty to print the prompt, which means that it may only work with local repositories or remote repositories accessed via ssh. If it cannot open the tty, it will exit quietly (as if the user said n), but if this function is called by a daemon that may have a tty of /dev/console, its operation is unpredictable. Recommended only for use with local repositories.

-D, --debug

Prints out the information svnlog got from Subversion as it works. This option is mostly useful for developing svnlog and checking exactly what data Subversion provides.

--debbugs=address

This is a special feature probably only of use to Debian developers. If this flag is given, scan the commit message for any bug closers (using the same syntax as is used in Debian changelog files). If any bug closers are found, send a separate mail message to address with the debbugs commands to tag those bugs as pending. The easiest way to get the appropriate bug closers into the commit message when working on Debian packages is to use debcommit to commit changes.

In versions of svnlog prior to 1.11, this option instead checked the diff for modifications to debian/changelog. This proved too likely to tag bugs spuriously when importing old source and was changed to only look in the commit message.

-d, --diff

Append the full diff output for each change to the notification message provided that it is less than 200KB. If longer than that, just append a note saying that the diff is too large and giving the svn command that would display it.

--diffstat=path

Sets the path to diffstat. If this option isn't given, svnlog defaults to attempting to find diffstat in its path (and what its path is will depend a great deal on your Subversion configuration).

-f from, --from=from

Sets the From header of the mail generated by svnlog to from. This must be syntactically valid as the contents of an RFC 2822 From header (a simple address of course qualifies). If this option is not given, the From header will be set to the user who made the commit, with their full name added if they're found in the local password file or equivalent. (Normally, the local mail system will then append a local domain to form an e-mail address.)

from should be specified in UTF-8. If it is, it will be encoded using RFC 2047 encoding if needed. If it is encoded in some other character set, svnlog will try to use it in the mail message without modification or encoding, which may produce surprising results.

-H header, --header=header

Include header in the headers of the mail message. header must be a valid mail header (including the keyword, colon, and space). This option may be given multiple times, and all of the headers (including any specified in the configuration file) will be included in the message. There is no way to override the headers set in the configuration file, just add to them.

-h, --help

Print out this documentation (which is done simply by feeding the script to perldoc -t).

-i regex, --include=regex

Only send a notification message if one of the files modified matches the regular expression regex. If none do, the commit will be silently ignored. This option may be given multiple times, and a notification message will be sent if any of the files in the commit match any of the provided regular expressions. There is no way to override include patterns set in the configuration file, just add to them.

If the notification is sent, all details about that commit will be sent, including listing files that don't match the regexes, including other changes in summary and diff output, and so forth.

-l, --long-subject

Normally, svnlog will just list the number of changed files rather than the complete list of them if the subject would otherwise be too long (more than 78 characters). This flag disables that behavior and includes the full list of modified files in the subject header of the mail, no matter how long it is. Currently, svnlog does not wrap the header, so using this option can result in a message that is not syntactically valid.

-o, --omit-author

Omit the author information from the commit notification. This is useful where all commits are done by the same person (so the author information is just noise) or where the author information isn't actually available. The author will still appear in the From header of the commit message unless the -f option is also given.

--sendmail=path

Sets the path to sendmail. If this option is not given, svnlog will search for sendmail in /usr/sbin and then /usr/lib, falling back on using /usr/lib/sendmail (and probably failing) if neither appears to exist.

-p prefix, --subject=prefix

Sets the Subject prefix for all commit messages. Appended to this prefix will be the relative path in the repository to the lowermost parent directory of all changed files and then a list of files (or a count of files) in parentheses. If this option is not given, the default prefix is Commit in . Note that you will normally want prefix to end in a trailing space.

-s, --summary

Append to each commit notification a summary of the changes, produced by generating diffs and feeding those diffs to diffstat(1). diffstat(1) must be installed to use this option; see also the --diffstat option to specify the path to the program.

--svnlook=path

Sets the path to svnlook. If this option is not given, svnlog attempt to find diffstat in its path (and what its path is will depend a great deal on your Subversion configuration).

-v, --version

Print out the version of svnlog and exit.

CONFIGURATION

svnlog can be told to read a configuration file with the -c option. The syntax of this file is one configuration parameter per line in the format:

    parameter: value

The value may be enclosed in double-quotes and must be enclosed in double-quotes if there is leading or trailing whitespace that should be part of the value. Whitespace after the colon and before the value (or an opening double quote) is ignored. There is no way to continue a line; each parameter must be a single line. Lines beginning with # are comments and ignored, as are blank lines.

The configuration parameters are exactly the same as the long names of the command-line options, with the exception that --config, --help, and --version have no corresponding parameters (for obvious reasons). As with the command-line options, the address and header parameters may be given multiple times; for all other parameters, the last value is taken if the paramter occurs multiple times.

When setting a boolean parameter like summary or diff, the value should be 1 if you want to turn it on and 0 if you want to turn it off.

Command-line options always override the configuration file except for the --address and --header options, as noted.

INSTALLATION

Follow these steps to add svnlog to your project:

  1. Install svnlog on your system in some convenient location. You may need to change the path to Perl on the first line of the script if your Perl isn't in /usr/bin/perl. svnlog does not have to be inside the hooks directory of the Subversion repository; it can be anywhere (/usr/local/bin, for instance).

  2. In the hooks directory of your Subversion repository, create a file named post-commit with the contents:

        #!/bin/sh
        /path/to/svnlog <options> "$1" "$2"

    where /path/to/svnlog is the full path to wherever you installed svnlog and <options> are whatever options you wish to use. Be sure to include at least one -a option (or a -c option pointing to a configuration file that includes at least one address parameter setting) so that svnlog knows where to send the mail.

    It's best to always specify the path to svnlook with the --svnlook option (and the path to diffstat with --diffstat if you're using it) even if you think that program will be in the default path, since Subversion can be run under unusual situations (such as by a web server) and the path may not be what you expect.

That's all there is to it. Try committing to your repository and see if mail is sent as you expect. Note that if you're configuring svnlog to send commit notifications to a mailing list, you may need to use the -f option to set the From header to an address that's allowed to mail that list. It's a good idea to test your configuration with -a pointing to your own e-mail address so that you see what the From header looks like and can find any problems.

EXAMPLES

The following examples show the svnlog command line that would go into the Subversion post-commit hook, so they assume that $1 is the path to the repository and $2 is the revision number.

A minimalist configuration, sending mail to commits@example.com:

    /usr/local/bin/svnlog -a commits@example.com "$1" "$2"

A more typical configuration, specifying the paths to svnlog and diffstat, sending commit notifications from commit-mailer@example.com (perhaps a special address that can send to mailing lists and discards any replies), sending them to proj-commits@example.com and to user@example.com, and including diffstat output.

    /usr/local/bin/svnlog --svnlook=/usr/bin/svnlook \
        --diffstat=/usr/bin/diffstat --summary \
        --from="Subversion Commits <commit-mailer@example.com>" \
        -a proj-commits@example.com -a user@example.com \
        "$1" "$2"

Here is the same example, but taking all of its parameters from a configuration file:

    /usr/local/bin/svnlog -c /usr/local/etc/svnlog.conf "$1" "$2"

where /usr/local/etc/svnlog.conf contains:

    # svnlog configuration
    svnlook:    /usr/bin/svnlook
    diffstat:   /usr/bin/diffstat
    summary:    1
    from:       Subversion Commits <commit-mailer@example.com>
    address:    proj-commits@example.com
    address:    user@example.com

Finally, here is an example for a Debian package maintainer. Send all commits, including diffs, to pkg-debian@lists.example.com, and cc control@bugs.debian.org with tag commands when appropriate. Also add the headers:

    X-Debian-Commit: yes
    X-Comment: Generated by svlog

to each commit message.

    /usr/local/bin/svnlog --svnlook=/usr/bin/svnlook \
        --diff --debbugs=control@bugs.debian.org \
        --header="X-Debian-Commit: yes" \
        --header="X-Comment: Generated by svnlog" \
        --address=pkg-debian@lists.debian.org \
        "$1" "$2"

The From header on the mail will be the default, derived from the user making the commit and the name from the local password file.

DIAGNOSTICS

cannot dup standard output: %s

(Fatal) svnlog is running in debug mode (-D) and was unable to send the output that would normally go into a mail message to standard output instead.

cannot fork %s: %s

(Fatal) svnlog was unable to run a program that it wanted to run. This may result in no notification being sent or in information missing. Generally this means that the program in question was missing or svnlog couldn't find it for some reason.

cannot open %s: %s

(Fatal) svnlog was unable to open the configuration file specified with -c or --config. The file may be missing or not readable by the user running svnlog.

pipe from '%s' failed: %s

(Fatal) Some program invoked by svnlog to get some information (usually svnlook) failed or died unexpectedly. There may be other error messages before this one that explain what happened. The exit status and any fatal signal received by the program are appended.

invalid config syntax: %s

(Warning) The given line in the configuration file was syntactically invalid. See "CONFIG FILE" for the correct syntax.

no addresses specified

(Fatal) There was no -a or --address command-line option and no address parameter in a config file. At least one recipient address must be specified for the Subversion commit notification.

unable to get list of changed files from svnlook

(Fatal) svnlog was unable to understand any of the output of svnlook changed and therefore was unable to tell what files were changed by this commit. There may be other error messages before this one that explain what happened.

unrecognized config line: %s

(Warning) The given configuration parameter isn't one of the ones that svnlog knows about.

FILES

/usr/sbin/sendmail
/usr/lib/sendmail

The default paths to sendmail if the --sendmail option and sendmail configuration parameter are not given. svnlog first tries the former and then the latter.

ENVIRONMENT

PATH

Used to find svnlook (and diffstat when the -s option is in effect) if the --svnlook and --diffstat command-line options or configuration parameters are not given.

CAVEATS

svnlog assumes that the full name in the local password file or equivalent is encoded in UTF-8. If it appears to be valid UTF-8, it will be used as UTF-8, which may mangle the name if it were actually in a different encoding. If it's not valid UTF-8, svnlog will use the full name without modification in the mail message, which may result in a syntactically invalid mail message and unexpected results.

BUGS

svnlog, when given the -l option, can generate syntactically invalid e-mail messages. The Subject header needs to be properly wrapped and some solution found to filenames longer than 998 characters (probably using RFC 2047 encoding).

No MIME type is declared in the mail message, which means that if your log messages (or file names or diffs) aren't US-ASCII, the results are unlikely to be what you want. You can work around this, if all of your commit messages are in the same character set, with command-line options like:

    --header="MIME-Version: 1.0"
    --header="Content-Type: text/plain; charset=utf-8"

but svnlog should really be able to figure this out for itself and should do the right thing with log messages in multiple character sets.

URLs for the diffs are not yet supported. If you want this added, please e-mail me the details of how to construct an appropriate URL and I'll see what I can do.

svnlog always reads the entire diff into memory. This may not be desirable on low-memory machines when processing huge changes such as merges. The functions that need the diff output to gather information should be able to scan the diff a line at a time when needed.

The diff size limit should be configurable, and what to include in the diff output should also be configurable. mailer.py supports specifying whether one wants diffs for adds, deletes, and modifications separately.

svnlog runs the command-line svnlook program and parses its output rather than using the Perl bindings. It was easier, but the Perl bindings would be more efficient.

SEE ALSO

debcommit(1), diffstat(1), svnlook(1).

The Subversion manual at <http://svnbook.red-bean.com/>.

diffstat is at <http://invisible-island.net/diffstat/>.

Current versions of this program are available from its web site at <http://www.eyrie.org/~eagle/software/svnlog/>.

AUTHOR

Russ Allbery <rra@stanford.edu>.

COPYRIGHT AND LICENSE

Copyright 2005, 2006, 2007, 2009 Board of Trustees, Leland Stanford Jr. University.

Based on cvslog, copyright 1998, 1999, 2000, 2001, 2002, 2003, 2004 Board of Trustees, Leland Stanford Jr. University.

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

Last spun 2013-07-01 from POD modified 2009-02-28