Ubuntu Manpage: syncmail - Send email notifications of CVS activity

Provided by: cvs-syncmail_2.3-1ubuntu1_all

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.

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)