SYNCMAIL(1)															       SYNCMAIL(1)

NAME

       syncmail - Send email notifications of CVS activity

SYNOPSIS

       syncmail  [ --cvsroot path ] [  [ --context | -C ] lines ] [ -c ] [ -u ] [ --quiet | -q ] [ --fromhost hostname ] [ -f hostname ] [ --mail-
       host hostname ] [ -m hostname ] [ --reply-to email-address ] [ -R email-address ] [ --subject-prefix string ] [ -S string ] [ --help | -h ]
       %{sSv} email ...

DESCRIPTION

       syncmail  sends	out  notifications  of	CVS  commits via email, including the patch that was applied for changed files, the content of new
       files, or notes about files that were removed.

       In any large project, keeping track of changes is difficult.  CVS does a reasonable job of allowing source changes  to  be  controlled  and
       managed,  but does not provide tools to make it easier to work with a changing code base.  The hardest part of working on a dynamic project
       with many changing modules is knowing when changes occur, and what those changes are.

       Software developers often are heavy email users, spending huge amounts of time working with their email software.  Open	source	developers
       are  among  the most serious email addicts out there, sorting through hundreds of emails a day, since this is often the only way to stay in
       touch with users and fellow developers.

       Clearly, we need more email.

       syncmail works by integrating with CVS in the repository using the configuration files in the repository's CVSROOT module.  When  CVS  exe-
       cutes  commands from the loginfo file, syncmail is invoked if its been configured, and it sends email to one or more email addresses speci-
       fied on the command line.

SETTING UP SYNCMAIL

       Setting up syncmail is not difficult, but there are usually several steps:

       1. Set up a mailing list.  Strictly speaking, this is optional, but with most good mailing list managers, it's easier to maintain a mailing
	  list	than  it  is to continually update a list of individual email addresses on the syncmail command line.  How this is done depends on
	  many things, but not syncmail, so will not be further covered here.

       2. Install syncmail.  This is usually done by adding it to your CVS repository, but it may be located in a directory on the  default  PATH,
	  or just about anywhere else.

       3. Configure  CVS  to invoke syncmail.  This is a matter of adding and/or changing some of the configuration files in the CVSROOT module in
	  the repository.

   INSTALL SYNCMAIL
       syncmail consists of a single Python script; it does not need any supplemental data files.  There are  two  approaches  to  installing  the
       script: check it into the repository, or place it in a shared location on the CVS server.

       To  install  syncmail  by checking it into the repository itself, check out a working copy of the CVSROOT module.  Add the name syncmail to
       the file checkoutlist in that directory as well, and commit that change.  This will cause a copy of syncmail to be  checked  out  into  the
       repository itself.  Copy te syncmail script into the directory, make sure that it is executable by everyone (you should use chmod a+x sync-
       mail for this), and use the cvs add and cvs commit commands to add it to the repository.  Once the commit is complete, a  checked-out  copy
       of  the syncmail script should be located in the repository in the CVSROOT directory in the repository.	This is the usual way of integrat-
       ing syncmail into a CVS repository.

       To install syncmail outside of the repository, find a location for the script.  This can be in a "bin" directory such  as  /usr/local/bin/,
       or  can	be in some other location.  The only requirement is that all users of the repository be able to execute the script (you should use
       chmod a+x syncmail for this).  This approach requires direct access to the CVS server machine, and is most useful if  several  repositories
       are going to share a single copy of syncmail (maybe to ensure the same version is used for each; it's not large enough for disk space to be
       an issue).

   CONFIGURE CVS TO USE SYNCMAIL
       Getting the CVS server to invoke syncmail requires editing one more file in the CVSROOT module of the repository.  Even if you're  using  a
       single installation of syncmail, this configuration needs to be performed for each repository.

       The loginfo file in the CVSROOT module needs to be modified to invoke syncmail when appropriate.  Just when is appropriate depends entirely
       on your project.  If your loginfo file still contains the comments that cvs init copies in, this is  a  good  time  to  read  them  if  you
       haven't.  If the file does not already contain any configuration lines, you can simply add to the end of the file.

       Here are two example lines to get you started:

       CVSROOT $CVSROOT/CVSROOT/syncmail %{sVv} you@example.com

       DEFAULT $CVSROOT/CVSROOT/syncmail %{sVv} myproject-checkins@example.com

       This  will cause email to be sent to two different places, with which depending on what files in the repository are affected.  For adminis-
       trative files in the CVSROOT module, email will be sent to <you@example.com>; you should probably  list	all  your  project  administrators
       here.  For all other files, email will be sent to the addresses you specify.

       If  you	have several sub-products for which you want different checkin lists, you can change the "DEFAULT" label to match the subtree that
       you want to go to each list, with a separate line for each distinct prefix.  For example, if your repository includes the modules "one" and
       "two", you could use the following:

       CVSROOT $CVSROOT/CVSROOT/syncmail %{sVv} you@example.com

       one/ $CVSROOT/CVSROOT/syncmail %{sVv} myproject-one-cvs@example.com
       two/ $CVSROOT/CVSROOT/syncmail %{sVv} myproject-two-cvs@exmaple.com

       Note  that  %{sSv}  is  magic  that  CVS understands and replaces with information about the files that are affected; be sure to enter that
       exactly as shown, just before the email addresses.  Command line options for syncmail should be placed between the  name  of  the  syncmail
       command and the %{sSv}.

       You can still have a "DEFAULT" line that gets used for any additional subprojects.

       If  you	do  not have a stock loginfo file, then you can probably figure out what you need to do to combine the information above with your
       existing changes.  If the command lines in the file become too long for comfort, some helper scripts can be added  to  the  CVSROOT  module
       (remember to add their names to the checkoutlist as well!).

       To  finish  the repository configuration, commit the changes you've made.  Once the CVS server has reported that it is "Rebuilding adminis-
       trative file database", your repository is configured to use syncmail.

OPTIONS

       When an option includes an argument, you may specify the argument either separate ("-d output") or mashed ("-doutput").	syncmail  supports
       both.   For long options which include an argument, the argument may be separated from the option ("--fromhost example.com") or mashed, but
       with an equals sign between the option and the argument ("--fromhost=example.com").

       --cvsroot path
	      Use path as the value for the CVSROOT environment variable.  This is usually not needed.

       --context lines

       -C lines
	      Generate context diffs with lines lines of context displayed on either side of the changed portion.

       -c     Generate context diffs with two lines of context shown on either side of the changed portion.  This is the default.

       -u     Generate unified diffs instead of context diffs.	Unified diffs are typically shorter than context diffs, but  many  users  find	it
	      easier to read context diffs.

       --quiet

       -q     Do  not  display	progress information to the user.  By default, syncmail will display the email addresses it is sending mail to and
	      note when it starts generating the notification email and when it is done sending the email.

       --fromhost hostname

       -f hostname
	      Specify the host name that email should appear to come from.  By default, syncmail uses the fully qualified name for the	host  it's
	      running on, and lets the local MTA take care of host name translation.

       --mailhost hostname

       -m hostname
	      Specify the host name that should be used to submit mail via SMTP.  By default, syncmail uses localhost.

       --reply-to email-address

       -R email-address
	      Specify an email address that should be used for the Reply-To header in email.  This header is not normally used.

       --subject-prefix string

       -S string
	      Provide  a  string  that is pre-pended to the subject of generated email.  This prefix is often of the form mail from syncmail for a
	      specific CVS repository or project.

	      This is often not needed if mail is being sent to a mailing list manager that adds a prefix of it's own.

       --help

       -h     Print a summary of the command line options to standard output.

BUGS

       There are probably some bugs.  If you find them,  please  report  them  to  the	maintainers  using  the  bug  tracker  <URL:http://source-
       forge.net/projects/cvs-syncmail/>.

ALTERNATIVES

       Other  people  have  written  tools  that  serve similar purposes, but not all of these are meant to support CVS repositories accessed from
       remote locations (anything other than direct filesystem access).

       A mostly-equivalent package, written in Perl, is available as cvs-syncmail (Perl version) <URL:http://cvs-syncmail-pl.sourceforge.net/>.

       log_accum is another Perl implementation, but there appears to be no authoritative source of information for this package.

       Please inform the syncmail maintainers if you can provide current references to these efforts.

SEE ALSO

       The syncmail page <URL:http://sourceforge.net/projects/cvs-syncmail/> on SourceForge <URL:http://sourceforge.net/>.

       The CVS home page <URL:http://www.cvshome.org/>.

AUTHOR

       syncmail was originally written by Barry Warsaw to send mail based on checkins to the Python project.  Barry continues to maintain syncmail
       with help from Fred L. Drake, Jr. and others.

       This manual page was written by Fred L. Drake, Jr. <fdrake@acm.org>.

								  09 August 2005						       SYNCMAIL(1)