Russ Allbery > Software > svnlog | svnlog Changes > |
(Mail Subversion commit notifications)
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
Print out this documentation (which is done simply by feeding the script to
perldoc -t
).
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.
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.
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.
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.
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.
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.
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).
Print out the version of svnlog and exit.
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.
Follow these steps to add svnlog to your project:
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).
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.
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.
(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.
(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.
(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.
(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.
(Warning) The given line in the configuration file was syntactically invalid. See CONFIG FILE for the correct syntax.
(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.
(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.
(Warning) The given configuration parameter isn't one of the ones that svnlog knows about.
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.
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.
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.
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.
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/>.
Russ Allbery <rra@stanford.edu>.
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.
Russ Allbery > Software > svnlog | svnlog Changes > |