xenial (1) syncmail.1.gz

Provided by: cvs-syncmail_2.3-1ubuntu1_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)