Provided by: cvs-syncmail_2.3-1_all bug

NAME

       syncmail - Send email notifications of CVS activity

SYNOPSIS

       syncmail [ --cvsroot path ] [  [ --context | -C ] lines ] [ -c ] [ -u ] [ --quiet | -q ] [
       --fromhost hostname ] [ -f hostname ] [ --mailhost 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  executes  commands  from  the  loginfo  file,
       syncmail  is  invoked  if  its  been  configured,  and it sends email to one or more email
       addresses specified 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 syncmail 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 integrating  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 administrative 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 administrative 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://sourceforge.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)