ACTIVITYMAIL(1) User Contributed Perl Documentation ACTIVITYMAIL(1)NAMEactivitymail - CVS activity notification
SYNOPSIS
# In commitinfo:
DEFAULT $CVSROOT/CVSROOT/activitymail -l
# In loginfo:
DEFAULT $CVSROOT/CVSROOT/activitymail -dacf '%{sVv}' -t admins@example.com
DESCRIPTION
This program may be used for sending email messages for CVS repository
activity. There are a number of different modes supported. It can send
messages for every change to the repository (like "syncmail"), or it
can be used to send a single message for each commit. In the latter
case, a list of all the files affected by the commit will be assembled
and listed in the single message. This is similar to how "commit_prep"
and "log_accum" work, but is more efficient.
An additional option allows for diffs to be calculated for the recent
changes, and either appended to the message (like "syncmail" does) or
added as an attachment (neater). See the "-d" and "-a" options below.
PREREQUISITES
This script requires Getopt::Std and File::Basename. It also requires a
CVS server and the diff package. See "Known Issues" for more
information.
COREQUISITES
This script works best with File::Spec installed. See "Known Issues"
for more information.
USAGE
To use this program, you need to check out your CVSROOT repository from
CVS and edit some files. Here are the steps to follow:
1. Copy activitymail into your CVSROOT checkout.
2. Add activitymail to the CVSROOT repository.
3. Add activitymail to the checkoutlist file.
4. If you plan to use commit mode (see "Commit Mode" below), add a
call (or calls) to "activitymail" with the "-l" options to the
commitinfo file. Read the CVS docs to determine the format for
this file, and to decide which repositories for which you want it
run. Here's an example:
DEFAULT $CVSROOT/CVSROOT/activitymail -l
5. Add a call (or calls) to activitymail to the loginfo file. Note
that the "-f" and "-t" options are required here, and the "-P"
option is a good idea for CVS 1.12 and later. Use the "-c" option
if you're running commit mode (i.e., you've added a call with "-l"
to the commitinfo file -- see "Commit Mode" below). Here's an
example:
DEFAULT $CVSROOT/CVSROOT/activitymail -cP %p -f '%{sVv}' -t admins@example.com
6. Commit your changes to CVSROOT.
OPTIONS-l Directory logging mode. Use this mode in the commitinfo file to log
the current directory. Best if used with "-c" in the loginfo file
-- otherwise it's just a waste.
-c Commit mode. This mode will aggregate all the actions on a single
commit and send a single message. Must have specified "-l" in the
commitinfo file.
-f '%{sVv}'
The file spec argument from CVS. It must be called as "-f
'%{sVv}'". Single quotes are recommended, as some shells otherwise
seem to have a hard time. Required unless "-l". CVS 1.12 and later
users should also use "-P %p", as "-f %1{SVv}" will generate
deprecation warnings.
-P The directory argument from CVS. This option is only useful for CVS
1.12 or later, where the command line format should be "-P %p -f
'%{sVv}'".
-t <email>
The email address or addresses to send notifications to. Required
unless "-l".
-e <cvs>
Location of the CVS executable, e.g., /usr/bin/cvs. Defaults to
cvs, thus assuming that the cvs executable is in the path.
-d Include the diffs for all the files processed. These will be
appended to the notification message unless the -a option has been
specified.
-j <diff>
Location of the diff executable, e.g., /usr/bin/diff. Defaults to
diff, thus assuming that the cvs executable is in the path. Used
only for comparing added and deleted files to /dev/null.
-N <file>
Location of the null file. Defaults to /dev/null. This file will be
used to diff against deleted and added files. In most cases this
option can be left to the default, but Win32 systems, for example,
will need to change it to NUL or some such.
-o <diff options>
Options to pass to the "cvs diff" command. Useful for changing the
behavior of the diff command. Be sure to include these options
inside quotation marks so that they will be distinguished from the
options parsed by activitymail itself. See diff for a list of
available options. Defaults to "-u --minimal" if not specified.
-a Attach diffs to the notification message. The diffs for all the
files processed will be calculated, and then they will be added to
the message as an attachment.
-r <email>
An optional reply-to address. This address will be added to a
Reply-To header in the notification email.
-n Ignore "New directory" commits. By default, activitymail sends mail
when a directory has been added. Use this option to ignore those
actions.
-i Ignore imports. By default, activitymail sends mail when a files
have been imported. Use this option to ignore those actions.
-m <message>
An optional message to put at the beginning of the email subject.
-p Option to add the name of the CVS module to the message subject.
-S Optional attempt give the file name or lowest common directory
name. Used only in commit mode.
-s <sendmail>
Location of sendmail. If not specified, activitymail will search
for sendmail in the following locations: "/usr/lib/sendmail".
"/usr/sbin/sendmail", "/usr/ucblib/sendmail". If activitymail
cannot find sendmail, it'll throw an exception.
-u <user email>
Email address to use in the From header of the commit email
message. Typical usage is to use the CVS $USER variable to specify
an address, e.g., "-u ${USER}@example.com". The default behavior is
to provide no From header and to let Sendmail do it.
-g Groups the collection of CVS transactions in a single commit by the
$USER environment variable. This is most useful when connecting to
CVS via ":pserver:", since the usual method of collecting
transactions -- by relying on the value returned by "pgrp", won't
work. Use in both the commitinfo and loginfo files, or else it
won't work at all!
-M <size>
Max length for email messages, in kilobytes. If an email greater
than this size would be sent then an error message is printed to
the user's terminal, instead. This option is useful if your
repository contains large binary files not prevented from be diffed
by "-B", or when adding many files at once. In those cases,
failing to use this option may result in broken mail clients.
-V Include the old and new revision numbers after each file listed in
the email.
-H Generate HTML emails. The Content-Type header will be set to
"text/html" and some basic HTML formatting tags used for the
display of the commit message.
-C <charset>
Character set to be used in the Content-Type header. Defaults to
"UTF-8". If much of the content in your repository is encoded in a
character set incompatible with UTF-8, then set this option for a
more appropriate character set.
-w <url>
Include links to specified ViewVC or CVSWeb URL for the diffs for
each file. Most useful with the "-H" option.
-B <list>
Binary file extension list. "activitymail" does its best to prevent
binary files from being diffed by using the Perl "-B" operator to
check for binary files. However, this approach doesn't catch all
binary files. If you find that "activitymail" is diffing binary
files, use this option to specify a quoted, space-delimited list of
file name extensions on the binary files that you want
"activitymail" to skip.
-I <regexen>
A quoted, space-delimited list of regular expressions identifying
the files to include in the processing of the commit message. Use
"\s" in place of literal spaces. The file name checked by the
regular expression will be relative to the CVS module root. Cannot
be used in combination with "-E".
-E <regexen>
A quoted, space-delimited list of regular expressions identifying
the files to exclude from the processing of the commit message. Use
"\s" in place of literal spaces. The file name checked by the
regular expression will be relative to the CVS module root. Cannot
be used in combination with "-I".
-U Older versions of CVS had a bug that prevented them from properly
diffing when they were passed arguments to be passed to "diff" with
spaces in them. Since we use the "-L" option to diff to pass in
the complete file name to be put into the diff headers, this can
lead to problems. So if you're using an older version of CVS that
exhibits this problem (prior to 1.12, if I recall correctly), use
this option to replace any spaces in file names with underscores
before passing them off to "diff".
-q Quiet mode. Status messages will be suppressed. Debug messages will
still be output if "-D" is enabled.
-Q Very quiet mode. In addition to the status messages suppressed by
"-q", "-Q" will also suppress the message output when an email
won't be sent because of a size limitation set by "-m". Debug
messages will still be output if "-D" is enabled.
-h Print usage statement. It's a simplified version of this section of
the docs, intended to remind the user of all the options. Be sure
to read the detailed descriptions here, first.
-D Enables debug mode. This will trigger lots of output. All
activitymail debug messages will start with the string "@@@@@@@@
activitymail debug:" so that they can be spotted easily.
MODES
Standard Mode
In this mode, a notification message will be sent for every directory
affected by a single commit to the repository. This could be a lot of
messages if you've made a lot of changes, and is thus highly redundant.
To use it, all you need to cimply add a call to "activitymail" to your
loginfo file with (at minimum) the "-f", "-P" (for CVS 1.12 and later),
and "-t" options:
DEFAULT $CVSROOT/CVSROOT/activitymail -P %p -f '%{sVv}' -t admins@example.com
To mimic the behavior of syncmail, add the -d option to append diffs:
DEFAULT $CVSROOT/CVSROOT/activitymail -dP %p -f '%{sVv}' -t admins@example.com
Commit Mode
This mode takes a just a little more work to put in place, but manages
your email resources much more efficiently. In this mode,
"activitymail" tracks all the files changed throughout a single commit
and sends a single email when all the changes have been made. This is
especially useful in circumstances where many files have been changed
at once. In standard mode, many messages will be sent, but in commit
mode, only one will be sent.
An additional advantge of commit mode is that "activitymail" will
construct a custom subject for the notification messages. In standard
mode, the subject is simply the contents of the "-P" and "-f" options.
In commit mode, however, "activitymail" will use either the first
sentence of the log message, or the maximum number of words that take
up less than 72 characters (including the "-m" and/or "-p" options, if
specified). This offers an easy way to see what was done during the
commit based on the context of the beginning of the actual log message.
CVS users thus might want to consider making the first sentence of
their messages (up to the first period) be a brief summary, and the
rest of the message can be a more detailed description of the changes.
To use commit mode, you must place a call to "activitymail" with the
"-l" option in your commitinfo file for every repository package you
want to manage in commit mode. Usually, that's everything, so you can
just use the line (as long as you have no other lines -- see cvs for
more information):
DEFAULT $CVSROOT/CVSROOT/activitymail -l
Then, you'll need to add a second call to "activitymail" to your
loginfo file for the same repository packages as in the commitinfo
file's call to "activitymail". A convenient line for this purpose (even
if you have other log filters in place) is the ALL line:
ALL $CVSROOT/CVSROOT/activitymail -cf '%{sVv}' -t admins@example.com
The DEFAULT line will work equally well. Perhaps you want to have mail
sent to different addresses for different repository packages. see cvs
for more information on the loginfo file syntax.
If you'd like to see diffs for the changes for any particular commit,
add the "-d" option. All of the changes to the repository will be
recorded in diff format and appended to the end of the message:
ALL $CVSROOT/CVSROOT/activitymail -cdf '%{sVv}' -t admins@example.com
Better still, have the diffs added to the message as attachments by
adding the -a option.
ALL $CVSROOT/CVSROOT/activitymail -cdaf '%{sVv}' -t admins@example.com
Finally, If you commit to CVS via ":pserver:", you should use the -g
option to get "activitymail" to properly group all of the CVS activity
for a commit. By default, "activitymail" uses the value returned by
"pgrp" to determine what's part of a single commit action and what's
another action. However, in ":pserver:" mode, "pgrp" always returns the
same value. The solution is to use the $USER environment variable to
group the CVS activity. The assumption is that a single user will not
be doing two separate commits at the same time, so this should work
fine. Note that if you use the -g option, you must use it in both the
commitinfo file:
DEFAULT $CVSROOT/CVSROOT/activitymail -lg
And the loginfo file:
ALL $CVSROOT/CVSROOT/activitymail -cdagf '%{sVv}' -t admins@example.com
KNOWN ISSUES
· This program depends on the presence of several modules that are
distributed standard with Perl. They are Getopt::Std,
File::Basename, and File::Spec. If either Getopt::Std or
File::Basename isn't present, "activitymail" won't run. If
File::Spec isn't installed (not uncommon, since it's a fairly
recent addition to Perl -- SourceForge, for example, doesn't have
it as of this writing), "activitymail" will assume very simple Unix
semantics for creating file names, and will assume that "/tmp" is
the temp directory.
· The default "diff" on SunOS 5.9 does not like the "-L" option that
"activitymail" uses. The workaround is to install GNU "diff".
TO DO
· Change the way diffs are aggregated for messages so that we're not
loading them all up into memory, but passing them directly to
sendmail instead. This should dramatically lower the amount of
memory "activitymail" takes up during a large commit.
BUGS
Please send bug reports to <bug-activitymail@rt.cpan.org> or report
them via the CPAN Request Tracker at
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=activitymail>.
AUTHOR
David Wheeler <david@justatheory.com>
SEE ALSO
SVN::Notify
This is a port of "activitymail" to subversion. Only it's a lot
better. Check it out!
CVSspam
Ruby-powered CVS notification. Includes colored HTML
representations of diffs right in the email.
<http://www.badgers-in-foil.co.uk/projects/cvsspam/>.
syncmail
Python-powered CVS notification. Sends emails with diffs for every
directory in a single commit. Popular on SourceForge.
<http://sourceforge.net/projects/cvs-syncmail>.
commit_prep & log_accum
The original Perl 4-powered CVS notification applications.
<http://ccvs.cvshome.org/source/browse/ccvs/contrib/log_accum.in>,
<http://ccvs.cvshome.org/source/browse/ccvs/contrib/commit_prep.in>.
SUPPORT
This module is stored in an open repository at the following address:
<http://github.com/theory/activitymail/tree/>
Patches against Widget::Meta are welcome. Please send bug reports to
<bug-activitymail@rt.cpan.org>.
COPYRIGHT AND LICENSE
Copyright (c) 2002-2009, David Wheeler. Some Rights Reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl.
perl v5.20.2 2015-08-30 ACTIVITYMAIL(1)