.\" This manpage has been automatically generated by docbook2man
.\" from a DocBook document. This tool can be found at:
.\"
.\" Please send any bug reports, improvements, patches,
.\" etc. to Steve Cheng .
.TH "SYNCMAIL" "1" "09 August 2005" "" ""
.SH NAME
syncmail \- Send email notifications of CVS activity
.SH SYNOPSIS
\fBsyncmail\fR [ \fB\-\-cvsroot \fIpath\fB\fR ] [ \fB [ \-\-context | \-C ]
\fIlines\fB\fR ] [ \fB\-c\fR ] [ \fB\-u\fR ] [ \fB\-\-quiet | \-q\fR ] [ \fB\-\-fromhost \fIhostname\fB\fR ] [ \fB\-f \fIhostname\fB\fR ] [ \fB\-\-mailhost \fIhostname\fB\fR ] [ \fB\-m \fIhostname\fB\fR ] [ \fB\-\-reply\(hyto \fIemail\(hyaddress\fB\fR ] [ \fB\-R \fIemail\(hyaddress\fB\fR ] [ \fB\-\-subject\(hyprefix \fIstring\fB\fR ] [ \fB\-S \fIstring\fB\fR ] [ \fB\-\-help | \-h\fR ] \fB%{sSv}\fR \fBemail\fR\fI ...\fR
.SH "DESCRIPTION"
.PP
\fBsyncmail\fR 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.
.PP
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.
.PP
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.
.PP
\fBClearly, we need more email.\fR
.PP
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
\fIloginfo\fR file, syncmail is invoked if its
been configured, and it sends email to one or more email
addresses specified on the command line.
.SH "SETTING UP SYNCMAIL"
.PP
Setting up syncmail is not difficult, but there are usually
several steps:
.TP 3
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.
.TP 3
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 \fBPATH\fR, or just about anywhere else.
.TP 3
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.
.SS "INSTALL SYNCMAIL"
.PP
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\&.
.PP
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
\fIcheckoutlist\fR 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 \fBchmod a+x
syncmail\fR for this), and use the \fBcvs
add\fR and \fBcvs commit\fR commands to
add it to the repository. Once the commit is complete, a
checked\(hyout copy of the syncmail script should be located
in the repository in the \fICVSROOT\fR directory in the
repository. This is the usual way of integrating syncmail
into a CVS repository.
.PP
To install syncmail outside of the repository, find a
location for the script. This can be in a "bin" directory
such as \fI/usr/local/bin/\fR, 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 \fBchmod a+x syncmail\fR 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).
.SS "CONFIGURE CVS TO USE SYNCMAIL"
.PP
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.
.PP
The \fIloginfo\fR 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 \fIloginfo\fR file still contains the
comments that \fBcvs init\fR 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.
.PP
Here are two example lines to get you started:
.nf
CVSROOT $CVSROOT/CVSROOT/syncmail %{sVv} you@example.com
DEFAULT $CVSROOT/CVSROOT/syncmail %{sVv} myproject\(hycheckins@example.com
.fi
.PP
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 should probably
list all your project administrators here. For all other
files, email will be sent to the addresses you specify.
.PP
If you have several sub\(hyproducts 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:
.nf
CVSROOT $CVSROOT/CVSROOT/syncmail %{sVv} you@example.com
one/ $CVSROOT/CVSROOT/syncmail %{sVv} myproject\(hyone\(hycvs@example.com
two/ $CVSROOT/CVSROOT/syncmail %{sVv} myproject\(hytwo\(hycvs@exmaple.com
.fi
.PP
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}\&.
.PP
You can still have a "DEFAULT" line that gets used for any
additional subprojects.
.PP
If you do \fBnot\fR have a stock
\fIloginfo\fR 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 \fIcheckoutlist\fR as well!).
.PP
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.
.SH "OPTIONS"
.PP
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").
.TP
\fB\-\-cvsroot \fIpath\fB\fR
Use \fIpath\fR as the value for the
\fBCVSROOT\fR environment variable. This is
usually not needed.
.TP
\fB\-\-context \fIlines\fB\fR
.TP
\fB\-C \fIlines\fB\fR
Generate context diffs with
\fIlines\fR lines of context
displayed on either side of the changed portion.
.TP
\fB\-c\fR
Generate context diffs with two lines of context shown on
either side of the changed portion. This is the default.
.TP
\fB\-u\fR
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.
.TP
\fB\-\-quiet\fR
.TP
\fB\-q\fR
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.
.TP
\fB\-\-fromhost \fIhostname\fB\fR
.TP
\fB\-f \fIhostname\fB\fR
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.
.TP
\fB\-\-mailhost \fIhostname\fB\fR
.TP
\fB\-m \fIhostname\fB\fR
Specify the host name that should be used to submit mail
via SMTP. By default, syncmail uses
\fBlocalhost\fR\&.
.TP
\fB\-\-reply\(hyto \fIemail\(hyaddress\fB\fR
.TP
\fB\-R \fIemail\(hyaddress\fB\fR
Specify an email address that should be used for the
Reply-To header in email. This header is not normally
used.
.TP
\fB\-\-subject\(hyprefix \fIstring\fB\fR
.TP
\fB\-S \fIstring\fB\fR
Provide a string that is pre\(hypended to the subject of
generated email. This prefix is often of the form
'[Checkins]', allowing mail filters to easily identify
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.
.TP
\fB\-\-help\fR
.TP
\fB\-h\fR
Print a summary of the command line options to standard
output.
.SH "BUGS"
.PP
There are probably some bugs. If you find them, please
report them to the maintainers using the bug
tracker \&.
.SH "ALTERNATIVES"
.PP
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).
.PP
A mostly\(hyequivalent package, written in Perl, is available as
cvs-syncmail (Perl version) \&.
.PP
\fBlog_accum\fR is another Perl implementation, but
there appears to be no authoritative source of information for
this package.
.PP
Please inform the syncmail maintainers if you can provide
current references to these efforts.
.SH "SEE ALSO"
.PP
The syncmail page on SourceForge \&.
.PP
The CVS home page \&.
.SH "AUTHOR"
.PP
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.
.PP
This manual page was written by Fred L. Drake, Jr. \&.