Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ACTIVITYMAIL(1)	      User Contributed Perl Documentation      ACTIVITYMAIL(1)

NAME
       activitymail - 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
       o   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.

       o   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
       o   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.32.1			  2022-03-28		       ACTIVITYMAIL(1)

NAME | SYNOPSIS | DESCRIPTION | PREREQUISITES | COREQUISITES | USAGE | OPTIONS | MODES | KNOWN ISSUES | TO DO | BUGS | AUTHOR | SEE ALSO | SUPPORT | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=activitymail&sektion=1&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help