Section: (1)
Updated: 09 August 2005



syncmail - Send email notifications of CVS activity 


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



syncmail sends out notifications of CVScommits via email, including the patch that was applied forchanged files, the content of new files, or notes about filesthat were removed.

In any large project, keeping track of changes is difficult.CVS does a reasonable job of allowing source changes to becontrolled and managed, but does not provide tools to make iteasier to work with a changing code base. The hardest part ofworking on a dynamic project with many changing modules isknowing when changes occur, and what those changes are.

Software developers often are heavy email users, spending hugeamounts of time working with their email software. Open sourcedevelopers are among the most serious email addicts out there,sorting through hundreds of emails a day, since this is oftenthe only way to stay in touch with users and fellow developers.

Clearly, we need more email.

syncmail works by integrating with CVS in the repositoryusing the configuration files in the repository's CVSROOTmodule. When CVS executes commands from theloginfo file, syncmail is invoked if itsbeen configured, and it sends email to one or more emailaddresses specified on the command line. 


Setting up syncmail is not difficult, but there are usuallyseveral steps:

Set up a mailing list. Strictly speaking, this is optional,but with most good mailing list managers, it's easier tomaintain a mailing list than it is to continually update alist of individual email addresses on the syncmailcommand line. How this is done depends on many things, butnot syncmail, so will not be further covered here.
Install syncmail. This is usually done by adding it toyour CVS repository, but it may be located in a directory onthe default PATH, or just about anywhere else.
Configure CVS to invoke syncmail. This is a matter ofadding and/or changing some of the configuration files inthe CVSROOT module in the repository.


syncmail consists of a single Python script; it does notneed any supplemental data files. There are two approaches toinstalling the script:check it into the repository, or place it in a shared location on the CVSserver.

To install syncmail by checking it into the repositoryitself, check out a working copy of the CVSROOT module. Addthe name syncmail to the filecheckoutlist in that directory as well,and commit that change. This will cause a copy of syncmailto be checked out into the repository itself. Copy tesyncmail script into the directory, make sure that it isexecutable by everyone (you should use chmod a+xsyncmail for this), and use the cvsadd and cvs commit commands toadd it to the repository. Once the commit is complete, achecked-out copy of the syncmail script should be locatedin the repository in the CVSROOT directory in therepository. This is the usual way of integrating syncmailinto a CVS repository.

To install syncmail outside of the repository, find alocation for the script. This can be in a "bin" directorysuch as /usr/local/bin/, or can be insome other location. The only requirement is that all usersof the repository be able to execute the script (you shoulduse chmod a+x syncmail for this). Thisapproach requires direct access to the CVS server machine, andis most useful if several repositories are going to share asingle copy of syncmail (maybe to ensure the same versionis used for each; it's not large enough for disk space to bean issue). 


Getting the CVS server to invoke syncmail requires editingone more file in the CVSROOT module of the repository. Evenif you're using a single installation of syncmail, thisconfiguration needs to be performed for each repository.

The loginfo file in the CVSROOT moduleneeds to be modified to invoke syncmail when appropriate.Just when is appropriate depends entirely on your project. Ifyour loginfo file still contains thecomments that cvs init copies in, this is agood time to read them if you haven't. If the file does notalready contain any configuration lines, you can simply add tothe end of the file.

Here are two example lines to get you started:

CVSROOT $CVSROOT/CVSROOT/syncmail %{sVv} youAATTexample.comDEFAULT $CVSROOT/CVSROOT/syncmail %{sVv}

This will cause email to be sent to two different places, withwhich depending on what files in the repository are affected.For administrative files in the CVSROOT module, email will besent to <>; you should probablylist all your project administrators here. For all otherfiles, email will be sent to the addresses you specify.

If you have several sub-products for which you want differentcheckin lists, you can change the "DEFAULT" label to match thesubtree that you want to go to each list, with a separate linefor each distinct prefix. For example, if your repositoryincludes the modules "one" and "two", you could use thefollowing:

CVSROOT $CVSROOT/CVSROOT/syncmail %{sVv} youAATTexample.comone/ $CVSROOT/CVSROOT/syncmail %{sVv} myproject-one-cvsAATTexample.comtwo/ $CVSROOT/CVSROOT/syncmail %{sVv}

Note that %{sSv} is magic that CVSunderstands and replaces with information about the files thatare affected; be sure to enter that exactly as shown, justbefore the email addresses. Command line options forsyncmail should be placed between the name of thesyncmail command and the %{sSv}.

You can still have a "DEFAULT" line that gets used for anyadditional subprojects.

If you do not have a stockloginfo file, then you can probablyfigure out what you need to do to combine the informationabove with your existing changes. If the command lines in thefile become too long for comfort, some helper scripts can beadded to the CVSROOT module (remember to add their names tothe checkoutlist as well!).

To finish the repository configuration, commit the changesyou've made. Once the CVS server has reported that it is"Rebuilding administrative file database", your repository isconfigured to use syncmail. 


When an option includes an argument, you may specify theargument either separate ("-d output") or mashed ("-doutput").syncmail supports both. For long options which include anargument, the argument may be separated from the option("--fromhost") or mashed, but with an equals signbetween the option and the argument ("").

--cvsroot path
Use path as the value for theCVSROOT environment variable. This isusually not needed.
--context lines
-C lines
Generate context diffs withlines lines of contextdisplayed on either side of the changed portion.
Generate context diffs with two lines of context shown oneither side of the changed portion. This is the default.
Generate unified diffs instead of context diffs. Unifieddiffs are typically shorter than context diffs, but manyusers find it easier to read context diffs.
Do not display progress information to the user. Bydefault, syncmail will display the email addresses itis sending mail to and note when it starts generating thenotification email and when it is done sending the email.
--fromhost hostname
-f hostname
Specify the host name that email should appear to comefrom. By default, syncmail uses the fully qualifiedname for the host it's running on, and lets the local MTAtake care of host name translation.
--mailhost hostname
-m hostname
Specify the host name that should be used to submit mailvia SMTP. By default, syncmail useslocalhost.
--reply-to email-address
-R email-address
Specify an email address that should be used for theReply-To header in email. This header is not normallyused.
--subject-prefix string
-S string
Provide a string that is pre-pended to the subject ofgenerated email. This prefix is often of the formmail from syncmail for a specific CVS repository orproject.

This is often not needed if mail is being sent to amailing list manager that adds a prefix of it's own.

Print a summary of the command line options to standardoutput.


There are probably some bugs. If you find them, pleasereport them to the maintainers using the bugtracker <URL:>. 


Other people have written tools that serve similar purposes, butnot all of these are meant to support CVS repositories accessedfrom remote locations (anything other than direct filesystemaccess).

A mostly-equivalent package, written in Perl, is available ascvs-syncmail (Perl version) <URL:>.

log_accum is another Perl implementation, butthere appears to be no authoritative source of information forthis package.

Please inform the syncmail maintainers if you can providecurrent references to these efforts. 


The syncmail page <URL:> on SourceForge <URL:>.

The CVS home page <URL:>. 


syncmail was originally written by Barry Warsaw to send mailbased on checkins to the Python project. Barry continues tomaintain syncmail with help from Fred L. Drake, Jr. and others.

This manual page was written by Fred L. Drake, Jr. <>.




This document was created byman2html,using the manual pages.