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).
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>.