NAME

svnrreport - Generate revision reports against a remote subversion repository

SYNOPSIS

svnrreport [options]

DESCRIPTION

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:

OPTIONS

-diff, -nodiff

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.

-domain

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.

-force

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

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.

-increplyto, -noincreplyto

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.

-incto, -noincto

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.

-mailexe pathname

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
-outdir pathname

Archive location to write revision reports to. Default valus is . (the current working directory).

-notify, -nonotify

Send, or not, email notification for each revision. The default is to NOT send notification.

-repo URL

URL to repository to generate reports against. This option should be specified the first time this program is invoked.

-r rev-start
-r rev-start:rev-end

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.

-statefile filename

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.

-subjectprefix string

Prefix for Subject: field of mail. Default value is [SVN] .

-svnexe executable

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.

-to address

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
-update, -noupdate

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
-usermap pathname

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.

-verbose

Prints out status messages during processing.

-debug

Prints out debugging messages during execution.

-help

Prints out the help message.

-man

Prints out the complete manual page.

AUTOMATING REPORT GENERATION

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.

NOTES

PREREQUISITES

Perl and the subversion, svn, command-line client.

AUTHOR

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.