svnrreport - Generate revision reports against a remote subversion repository
svnrreport [options]
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 me@example.com \
-from me@example.com
In the example provided, reports for all revisions will be written to the directory called out. The -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: me@example.com Reply-To: me@example.com 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...]
The From: is specified by the -from option.
The Reply-To: is based on the commit user. See -domain and -usermap for more information on how the mail address is determined.
The Subject: field is based on the subversion user who committed the revision (denoted in the parentheses), the revision number, and the repository URL.
The 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:
-notify option is specified, the file is fed directly to the mail program to send notification to those specified by -to.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 joe and example.com is the specified domain by the -domain option, then the reply-to address will be joe@example.com.
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.
Include the Reply-To: field in the report. The default is to include the Reply-To: field.
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 To: field.
NOTE: When -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 sendmail -i.
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 joe@example.com and mary@example.com:
mailexe joe@example.com mary@example.com < 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:
-r 5000
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:
-r 5000:6000
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:
-r 5000: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:
-r :6000
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 HEAD, BASE, COMMITTED, PREV.
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 .svnrreport.
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.
Prefix for Subject: field of mail. Default value is [SVN] .
Name, or pathname, to subversion command-line client. The default value is svn.
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 "joe@example.com, mary@example.com"
or,
-to joe@example.com -to mary@example.com
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 me@example.com \
-from me@example.com \
-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: joe.bloe@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 me@example.com \
-to me@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.
svn that specifies the credentials. The -svnexe option can be used to point to your wrapper.svn_log in 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 <earl@earlhood.com>
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.