svnrreport - Generate revision reports against a remote subversion repository
svnrreport is a Perl program for generating revision reports (e.g. log messages and diffs) against a remote subversion repository. If one has local administrator access to the repository, such a facility can be done via post-commit hooks. However, if you do not have such access and are unable to get those who do to set up such a facility, you can use svnrreport.
To best illustrate how to use the program, we will start off with an example:
svnrrreport -outdir out \ -repo https://svn.example.com/repo \ -to email@example.com \ -from firstname.lastname@example.org
In the example provided, reports for all revisions will be written to the directory called
-r option can be used to limit the revision range if desired (see OPTIONS).
For each revision, a file is created in the output location, where the name of each file is the revision number the report is associated with. The format of each file is in mail message format. For example:
From: email@example.com Reply-To: firstname.lastname@example.org Subject: [SVN] (me) r6215 - https://svn.example.com/repo Date: Fri, 27 Dec 2013 16:43:17 -0600 [...log message for revision here...] [...context diffs of any modified files here...]
From: is specified by the
Reply-To: is based on the commit user. See
-usermap for more information on how the mail address is determined.
Subject: field is based on the subversion user who committed the revision (denoted in the parentheses), the revision number, and the repository URL.
Date: field is set to the commit date of the revision.
You may be asking the following, "What's with the mail header?" The reasons are as follows:
-notifyoption is specified, the file is fed directly to the mail program to send notification to those specified by
Include, or skip, context diff output for each revision. The default is to include the context diff.
NOTE: Context diffs are only done for files that are marked as modified for a revision.
The mail domain to use for mail addresses that do not include a domain component. If not specified, then no domain component is added to addresses that are missing it.
Example: When the
Reply-To: field is printed, the address used is based on the commit user of the revision. So if the commit user is
example.com is the specified domain by the
-domain option, then the reply-to address will be
NOTE: If subversion user identities are not equivalent to local names of user addresses, you can use the
-usermap option to map subversion user names to mail addresses.
If unable to lock archive, still perform operation.
To protect against concurrent svnrreport processes from operating on the same report archive, svnrreport will perform a lock before modifying the archive.
From address to use in mail notifications if
-notify is specified. If no from address provided, then the login name of the user running this program is used.
Reply-To: field in the report. The default is to include the
svnrreport makes an attempt to set the reply-to address to the committer of the revision. Therefore, recipients of the notification can directly reply to the committer.
Include, or not, the
To: field in the report. The default is to exclude the
-notify is enabled, svnrreport provides the recipient list to the mail program via the command-line, so the inclusion of the recipient addresses in the message is not required for delivery.
NOTE: The reason
To: is suppressed by default is that some MUAs (I'm talking to you GMail) may not honor the
Reply-To: field when
To: is present.
Pathname to program for sending mail notifications. Default value is
If sendmail is not on your system, a good alternative is ssmtp.
The program is invoked as follows:
The following is shell-equivalent example of how the mail program is invoked if the recipients are
mailexe email@example.com firstname.lastname@example.org < file
Archive location to write revision reports to. Default valus is
. (the current working directory).
Send, or not, email notification for each revision. The default is to NOT send notification.
URL to repository to generate reports against. This option should be specified the first time this program is invoked.
Revision range to generate reports for. If not specified, reports starting from revision 1 to the latest is done.
If just a number if provided, reports are generated starting with the given number to the latest. For example, the following will generate reports from revision 5000 to latest:
If a range specification is provided, then reports are generated for revisions in the range, inclusively. For example, the following will generate reports from revision 5000 to 6000, inclusively:
NOTE: If you want to create a report for a single revision, then provide a range where the start and end are the same. For example, the following will only generate a report for revision 5000:
If in update mode, see
-update, and you do not want to generate reports to the latest revision, but to a specific revision number, you can do something like the following:
This says to generate reports from the last known revision to revision 6000.
NOTE: Svn revision keywords are NOT supported. Only numbers are supported. This program does NOT recognize the keywords
Filename of the file to store last execution state. The state file is stored relative to the output location specified by
-outdir. The default filename used is
The state file is used when
-update is specified to recall what was the last revision processed. The state file also includes other option settings so such settings do not have to be respecified each time you run svnrreport.
NOTE: The state file contains a single Perl data structure. If you are careful, you can manually edit the file directly to make changes to options that will apply to future updates. svnrreport uses Perl's require operator to load the file.
Subject: field of mail. Default value is
Name, or pathname, to subversion command-line client. The default value is
NOTE: The executable provided must support the standard
svn command-line client options.
Recipient address to receive mail notifications, if
-notify is specified. Multiple addresses can be specified as follows:
-to "email@example.com, firstname.lastname@example.org"
-to email@example.com -to firstname.lastname@example.org
Run, or not, in update mode. Default is no update.
In update mode, the state file is first read to obtain the last revision reported against and start generating reports for subsequent revisions .
NOTE: If the state file is not present when
-update is specified, svnrreport will generate a warning but will try to continue processing. Therefore, you may want to prime the report archive like the following:
svnrrreport -outdir out \ -repo https://svn.example.com/repo \ -to email@example.com \ -from firstname.lastname@example.org \ -r 1000
The above invocation initializes the report archive, starting with revision 1000.
When you want to update the archive, you can then invoke svnrreport in update mode:
svnrreport -outdir out -update
If any other option is specified when
-update is used, it will override any previous value for the option. For example, if mail notifications were not enabled initially, you can enable them as follows:
svnrreport -outdir out -update -notify
Pathname of file mapping names to mail addresses.
The syntax of the file is pretty basic, as illustrated by the following example:
# Comment lines are specified with the hash character # # The following maps "joe" to his mail address, # where a colon is used to delimit the name from # the address joe: email@example.com
If you create a mapping that does not include the domain portion of an address, then
-domain value will be used, if specified, to generate a full mail address.
Prints out status messages during processing.
Prints out debugging messages during execution.
Prints out the help message.
Prints out the complete manual page.
The best way to automate the generation of reports, and the sending of notifications if
-notify is specified, is to use a tool like cron. To simplify the crontab entry for generating reports, a wrapper script can be used.
Example: We create a wrapper script called
gen-svn-reports and place it at
$HOME/cron/gen-svn-reports. The body of the script is as follows:
svnrreport \ -repo https://svn.example.com/repo -from firstname.lastname@example.org \ -to email@example.com \ -mailexe "ssmtp" \ -notify \ -update \ -outdir "$HOME/svn/reports"
For your own script edit/add/remove options to reflect your needs.
In our crontab, we add the following entry:
0,30 * * * 1-5 $HOME/cron/gen-svn-reports
This entry says to run our script every half-hour, Monday through Friday (things are quiet on the weekends :). In your own crontab, set whatever frequency works best for you.
svnthat specifies the credentials. The
-svnexeoption can be used to point to your wrapper.
svn_login the source code for the cases where multiple diff requests are required.
Perl and the subversion,
svn, command-line client.
Copyright (C) 2013, Earl Hood <firstname.lastname@example.org>
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.