Back to contents
Author: Bo Berglund
History
When I started using CVS in order to bring some structure to the software development department
I run I first tested a number of alternative version managers like PVCS etc and two platforms: NT and Linux.
But in the end I selected CVS for NT as it was a stable
platform with good peer-to-peer support via the Internet.
Being an Open Source project also helped my decision, since we would never be stranded with a proprietary
solution from a commercial company that could disappear.
The downside to CVS is that you must spend some time fixing some useful features yourself. I found
that a lot of good stuff was available on Unix CVS but not easily ported to the Windows world. One
of these things was the email messaging system when things happen on the server. CVS has the needed
hooks in the administrative files, but they are all geared towards usage in an *ix environment.
So after a while I decided to program my email messaging system myself, that is the reason I did
the CVSMailer program. (In actual fact some time after I posted it on the web I found out that
someone else had a mailing program also called CVSMailer... Well, I'll keep the name until I get hit
by some litigation.)
There have recently been some changes in the way CVSNT handles the scripting and access and this affects
the operation of CVSMailer as well...
Notably these items have surfaced:
Starting from version 1.5.2.41 I have changed stuff as follows:
CVSMailer Download
CVSMailer Description
Known issues and bugs
CVSMailer Features
Requirements for CVSMailer operation
Installing and Configuring CVSMailer
Special considerations for CVSNT 2.5.01
Direct email sending using postcommand
Configuring CVSMailer for HTML messages and ViewCvs/CvsWeb links
Fixing problems with ViewCvs and recent CVSNT releases
Issue Tracking links
What can go wrong?
Managing the users who get email
Users from the CVS usergroups
Making mailings go to selected users
CVSMailer FAQ
Troubleshooting CVSMailer
Getting help in troubleshooting CVSMailer
Get news on CVSMailer updates
Send me info
There is often a need to let developers have some form of notification when changes
are done to their repository. This can be done in CVS in several ways, one of which
is automatic email transmissions on commits and other events.
The mechanism that controls this in CVS is the script files in the CVSROOT admin folder.
These script files are called whenever CVS performs certain actions and what happens
is depending on what is written in the script files. By default the script files are
commented out and so contain no actions.
There are many different methods of activation out there most of them descending from
UNIX and using Perl scripting. I never got that to work probably because I cannot read
or write Perl...
So I decided to take a different approach and wrote a mailer program myself that handles
the email stuff for me. This is the CVSMailer program that can be downloaded here:
CVSMailer Downloads
Back to contents
This is a list of some of the features of the program as per version 1.3.1:
Functional features:
CVSMailer cannot run everywhere, there are some requirements that need to be fulfilled first. Please check your system for these:
Installation of CVSMailer is done in two steps, first you install the program itself and then
you configure your system. Installation of the CVSMailer program is very simple if you use the
downloaded setup file. Just unzip and start it and follow the instructions.
Configuration
This is the part where you have to do the work yourself guided by these hints. What you need to do
is to tell CVSNT to use CVSMailer in the proper way. This is done by editing a number of administrative
files and adding a few new ones. I have tried to make this a bit easier for you by supplying these
files in a preformatted version and also a batch file that will set everything up as soon as you
have edited the files according to the instructions.
NOTE: These instructions assume that you have a fresh CVSNT installation where you have as
yet not edited any of these admin files: loginfo, notify, taginfo, users, checkoutlist. If this is
not the case then you should not overwrite these files with the ones supplied with CVSMailer!
Instead edit in the changes as needed.
Installation steps:
cvs checkout CVSROOT.
users Unable to check out 'users' file in CVSROOT.
loginfousers Unable to check out 'loginfousers' file in CVSROOT.
johnd:"John Doe <johnd@domain.net>"
[setup]
ShowFeedbackMessages = 0 (set to 1 if you want the user to see feedback messages from CVSMailer)
DelayedSend = 1 (this activates the consolidation of submodule emails into one)
TestMode = 0 (the setting as installed is 1 which means no email is being sent)
[Mailsettings]
MailHost = (your mailhost goes here like mymail.myorg.com)
SMTPPort = 25
AuthenticateSender = 1
AuthenticateAccount =
AuthenticateAccountPasswd = (the password of that account)
ForceIniSender = 1 (if you want the committing user to NOT be the sender, 0 otherwise)
Sender = (email address of forced sender)
TemporaryCommitWatchOnly = 0 (set to 1 if you want to limit notify messages to commits only)
cvs add loginfousers users
cvs commit -m "Adding the CVSMailer user management files" loginfousers users
cvs commit -m "Setting the CVSMailer files as admin files" checkoutlist
cvs commit -m "Activating CVSMailer" loginfo taginfo notify
This is simplified by using the batch file (cvsmailersetup.bat) I have prepared.
Simply execute it once and the changes will be applied in the correct sequence.
[Mailsettings]
;Control the subject of the messages
CommitMailSubject = CVS Commit
ImportMailSubject = CVS Import
TagMailSubject = CVS tag
NotifyMailSubject = CVS notify
<root> will be expanded to the CVSROOT value<module> will be expanded to the module name<server> will be expanded to the server computer name
[setup]
CVSServerNameReplacement = computername
It is now possible to use the postcommand scriptfile to send the emails if you use a CVSNT version that
supports postcommand. This is supported at least in 2.5.03, but might be there also in some earlier versions.
The configuration needed is the following:
DEFAULT C:/Programs/CVSMailer/CVSMailer.exe -p$CVSPID $USER $CVSROOT %c
[setup]
PostCommandSend=1
From the CVSNT release 2.5.01 there have been a lot of changes to the way scripts are executed.
Notably the data supplied to the loginfo script does no longer contain data that enables the detection
of which branch a committed file belongs to. There are other issues as well that prohibit the use of
standard syntax for loginfo in connection with CVSMailer. These seem to have been solved as of build 1927!
Version 2.5.01 of CVSNT introduces a common syntax for the commit scripts including loginfo, taginfo and notify.
This syntax can be used to supply the same type of information as before but in a different way.
CVSMailer has been modified to detect these new data from version 1.5.2.40 onwards.
What is needed to use this is to change the loginfo lines at the end as shown below.
Also note that CVSNT now requires the path to the program is entered using / instead of \ and any backslash
needed in the user specification must be doubled!
Old loginfo line:
DEFAULT C:\Programs\CVSMailer\CVSMailer.exe -l$CVSPID $USER $CVSROOT -rDOMAIN\user %{sVv}
New loginfo line (note that from build 1927 the old spec works again so only the slash change is needed):
DEFAULT C:/Programs/CVSMailer/CVSMailer.exe -l$CVSPID $USER $CVSROOT -rDOMAIN\\user %<< \nFiles:\n%<{sVvt} %<< \nLog Message:\n%<m
Back to contents
The configuration of the new features is done in the CVSMailer.ini file as everything else.
In order to get HTML formatted email you need to set up CVSMailer for delayed mailsend and HTML.
This is done as follows:
[setup]
DelayedSend=1
[FileLinks]
UseHTMLformat= 1
NOTE! The ViewCvs parts of the system will not work unless you have previously
installed and configured ViewCvs on your CVSNT server!
The Diff and File links will be possible only if you use delayed mailsend and HTML format and
have installed ViewCvs on your CVSNT server. CVSMailer will add links to ViewCvs according to the ini file setup,
but they will of course only function if you have a working installation.
What you need to do is to set up the CVSMailer.ini file as follows. Note that the computer name
must of course be changed, in this case altair is my development PC.:
Configuration for ViewCvs:
[FileLinks]
UseHTMLformat= 1
UseDiffLinks = 1
UseFileLinks = 1
BinaryFileExtensions= exe,res,jpg,gif,bin
(add all binary extensions you normally use here)
;The ViewCvs file views:
BaseFileUrl = http://altair/ViewCvs/viewcvs.cgi/
FileCmd = <module>/<file>?rev=<rev>&view=auto&cvsroot=<root>
FileSummaryCmd = <module>/<file>?view=log?cvsroot=<root>
;The ViewCvs module view:
ModuleCmd = <module>/?cvsroot=<root>
;The ViewCvs Diff:
BaseDiffUrl = http://altair/ViewCvs/viewcvs.cgi/
DiffCmd=<module>/<file>.diff?r1=<rev1>&r2=<rev2>&cvsroot=<root>
Binary files
Since binary files are not possible to view or diff CVSMailer has to have a way to know which files
not to create links for. So I have added the setting 'BinaryFileExtensions' as a list of file extensions
for binary files, to which you might add whatever extra files you like. All files with these extensions
will be excluded from having links to diff or markup added in the message.
File and Diff links
Normally you need only to care about the BaseDiffUrl and BaseFileUrl settings because they depend on
how ViewCvs has been installed. The commands themselves are standard commands for ViewCvs,
so you only have to select if you are going to use ViewCvs (or CvsWeb) by uncomment/comment
the ini file entries.
Notes on ViewCvs
When I first set up ViewCvs I ran into a number of problems that you might also face, so in order to help others
I have created an
installer for ViewCvs for Windows.
It automates the whole install and configuration process for ViewCvs both on IIS and Apache.
It works on all platforms I have tested on: Windows NT4, Windows 2000, Windows XP Pro, Windows 2003
Outlook 97 note:
The HTML emails that CVSMailer sends contain links to the web browsing service as described above. Unfortunately
for some unknown reason, Outlook 97 will not display these correctly. So instead of showing a link text the complete
URL code is visible and this effectively renders the messages unreadable.
I cannot do much about this, my only advice is to upgrade to Outlook 98 or later, which displays the messages correctly.
Back to contents
The configuration of the Issue Tracker links is done in the CVSMailer.ini file as everything else.
but it is probably easier using the configuration utility.
[IssueTracking]
UseIssueLinks=1
IssueUrl =http://myserver:8080/Tracker/issue<number>
IssueReference =[Issue<number>]
The IssueUrl value is the actual URL for the issue where the issue number is replaced by the placeholder <number>.
In the email the placeholder will get replaced by the real issue number.
The issue number is extracted from the commit log message entered. Anywhere CVSMailer finds an item that matches the
IssueReference from the ini file it will set it up as a weblink using the number in the message.
Example log message:
[Issue 45]
This is a commit against ticket 45. Some changes were made.
Also solves the problems in [Issue 63]
As you can see you can have multiple issue references, all will be converted to links.
The CVSMailer system depends on the two files 'users' and 'loginfousers' in the CVSROOT of the repository.
The system works like this:
Whenever a user makes a cvs commit or tag operation the connected script gets executed and at the end
CVSMailer is called. It needs to find out who to send the emails to so it looks first for the login of the
user who sent the email. This is compared to the logins in the 'users' file in order to find the email
address of that login.
Next CVSMailer looks up the 'loginfousers' file to find out who have subscribed to get an email. This file
is manually maintained by the CVS administrator and lists all user logins who are subscribed to the emails.
The login names are single entries on separate lines in this file.
It is the task of the CVS administrator to maintain these two files, otherwise the mailings will be incorrect.
The way to do this is to have a checked out copy of the CVSROOT module and add new users to these files as
they are added to the system as a whole.
Back to contents
In the previous section it was stated that email was sent to all users in the 'loginfousers' file. This is
normally correct, but there is one exception:
There is a command line switch for CVSMailer to change this into sending only to users specifically listed
on the CVSMailer command line. The switch is identified with -r and must be placed in the correct position
in the script file. This switch must be followed by a comma separated list of the user logins selected for mail
(no spaces allowed here!) as follows:
loginfo example:
DEFAULT C:/Programs/CVSMailer/CVSMailer.exe -l$CVSPID $USER $CVSROOT -rjohn,jane,charlie %{sVv}
taginfo example:
DEFAULT C:/Programs/CVSMailer/CVSMailer.exe -t$CVSPID $USER $CVSROOT -rjohn,jane,charlie
Now only users john, jane and charlie will get the emails even if more are located on the list in 'loginfousers'.
Adding loginfousers to command line
If you want to send email to specified users with the -r parameter as described above, you can in fact also
add the complete list in the loginfousers file to this list like this (taginfo example):
DEFAULT C:/Programs/CVSMailer/CVSMailer.exe -t$CVSPID $USER $CVSROOT -rjohn,jane,charlie,loginfousers
Now the users in the file will also get the email.
Notice:
The first item (here DEFAULT) can be a regular expression that identifies a certain module of special interest
for one or a few developers. In this case you can add a line specifying this and give their names on the command
line. They do not need to be listed in loginfousers as long as they are on the users list. Now they will get
email whenever something happens on a module they are interested in.
Example loginfo entry:
webshop C:/Programs/CVSMailer/CVSMailer.exe -l$CVSPID $USER $CVSROOT -rjohn,jane,charlie %{sVv}
They will now only get email whenever the module name contains the word 'webshop'. Note that this expression is
case sensitive on some builds of CVSNT, to make the expression trigger for all cases you must enclose all
characters in brackets and add both cases inside like this:
[Ww]Ee[Bb][Ss][Hh][Oo][Pp].
If you use specifiers like these then the DEFAULT line will only trigger if none of the others match.
But if your goal is to have the separate lines send to some people but you also have a subscription that
must always get served then you should use the ALL keyword first on the line. This line will
then always be called.
Usernames with embedded spaces:
When the usernames have embedded spaces in them then problems can arise already in CVSNT, but for sure with
CVSMailer. The reason is that the parsing of the command line arguments get interfered with by the extra
spaces that act as field separators.
The solution is to make sure that there are double quotes on some of the script command arguments:
loginfo:
webshop C:/Programs/CVSMailer/CVSMailer.exe -l$CVSPID "$USER" $CVSROOT "-rjohn doe,jane austin,charlie" %{sVv}
taginfo:
DEFAULT C:/Programs/CVSMailer/CVSMailer.exe -t$CVSPID "$USER" $CVSROOT "-rjohn doe,jane austin,charlie"
notify:
ALL C:/Programs/CVSNT/CVSMailer.exe -n "$USER" $CVSROOT %s
Back to contents
CVSNT has an administrative file CVSROOT/group that is not created by default when you initialize the repository.
So you have to cvs add this file in a checked out CVSROOT module yourself in order to use it.
This file groups users into usergroups and is used by CVSNT for the permission management. If this file exists
and has groups defined then you can specify group names in the loginfousers file as well as in the CVSMailer
command line user specification. When CVSMailer scans the command line users and finds a name that is a group
name then it will add all users in this group to the recipients list.
Likewise, if CVSMailer finds a name in the loginfousers file that matches a group name then the group members
will be added to the recipients list.
Comments can be added to the file by putting a # character in column 1 of a line.
Format of the CVSROOT/group file
The group file lists each group on a single line where the group name starts in column 1. The group name is
immediately followed by a cpolon (:) and then a space separated list of users that belong to the group.
Example:
#This is a comment and is not acted on by CVSNT or CVSMailer
cvsusers: bob charlie jane morgan franchesca john jimmie louise jennifer
cvsadmins: bob louise
project_ulima: morgan jimmie louise
project_zobre: morgan john jennifer bob
managers: mparks hutchinson logan
Using the cvs groups for mail distribution
So with this system you are able to more easily manage the users who will get mail via the command line users
as shown by this example loginfo file:
DEFAULT C:/Programs/CVSMailer/CVSMailer.exe -l$CVSPID $USER $CVSROOT %{sVv}
Note that with this system you can change mail distribution across the board by just changing the members of
the various groups via the CVSROOT/group file! Makes management a lot simpler!
ulima C:/Programs/CVSMailer/CVSMailer.exe -l$CVSPID $USER $CVSROOT -rproject_ulima,managers %{sVv}
zobre C:/Programs/CVSMailer/CVSMailer.exe -l$CVSPID $USER $CVSROOT -rproject_zobre,managers %{sVv}
CVSROOT C:/Programs/CVSMailer/CVSMailer.exe -l$CVSPID $USER $CVSROOT -rcvsadmins %{sVv}
User names with embedded spaces
If you are using user login names that contain embedded spaces then you are out of luck using the groups!
Since the format of the CVSROOT/group file is <groupname>: <space separated list of users> on single lines
then you cannot have users with spaces in their names, they will simply be split into their parts and not
found....
Back to contents
I get an error when tagging a module with many files
The tag operation fails sometimes when I have enabled email in the taginfo file. CVS complains
about some line being too long or similar....
Answer
This is a problem with standard CVS which is solved with CVSNT since a long time. The reason was that the
list of files and revisions were sent to the script on the command line and Windows has a maximum
length of that command line that can be exceeded if you tag a module with many files with long names.
Since some time now CVSNT has moved this info to standard input where there is no such limit.
So upgrading to the latest CVSNT on the server will solve this problem if you have it.
If you cannot do that then you have to switch off email on tag operations by commenting out the
CVSMailer line in the taginfo file.
Email is not sent and there is an error in the log
When I try to send email with CVSMailer nothing happens and the logfile shows an error
that the 'header is incomplete'. What can cause this?
Answer
This happens if the single user that you want to send an email to on commits is listed in the
CVSROOT/loginfousers file, but not in the CVSROOT/users file. The mail server rejects
the message because it does not have a To: field filled in. THis fact is logged in the logfile
if you have debug logging switched on.
All users that you are setting up to receive email must be listed in both files.
The users file follows standard
CVS formatting and is simply a translation from the login user name to the email address.
The loginfousers file contains all the users you want to send email to.
You should manage
the email addresses in the users file where all your CVS users should be listed, then it
is simple to switch on/off email to single persons by editing the loginfousers file only.
File diffs of all modified files?
I would like to get the diffs of the committed files included in the CVSMailer messages.
Is this possible or not?
Answer
From version 1.3.6 it is now possible to have HTML formatted email with included links to a
CvsWeb or ViewCvs server that can display the diffs. Apart from this there is no possibility to do this
as the potential size of the message can be massive if it was allowed.
Why are we getting two emails instead of one?
Whenever there is a commit we seem to get two emails instead of one. Both have the same contents. Why?
Answer
From version 1.5.2.47 the preferred email sending mechanism is to use the
postcommand script.
But in order for the old mail sending method to be disabled there are a few changes that need to
be made in the CVSMailer.ini file:
[setup]
If the postcommand script is containing the CVSMailer call and DelayedSend is set to 1 then 2 emails will
result for each commit. Using the settings above will cause email sending only from postcommand.
PostCommandSend=1
DelayedSend=0
Back to contents
If you can't get the system up and running at once, here are some hints on what you can do:
[setup]
enablelogging = 1
debuglog = 1
[setup]
TestMode = 1
[Mailsettings]
AuthenticateSender = 1
AuthenticateAccount = (enter a valid account identification here)
AuthenticateAccountPasswd =
[Mailsettings]
ForceIniSender = 1
Sender = (account email address)
SenderName = CVS-Server
There are probably some bugs that I don't know about, but here is a list of things that are on
my to-do list but are not yet fixed:
I have been asked to announce the availability of a new version somehow. The only way I can think
of right now is if you mail me with this request and I will create a maillist to which I will
send update messages. So if you want to be updated in the future, please use this link:
Join maillist for CVSMailer update announcements
CVSMailer setup file for version 1.5.2.50
CVSMailer exe file latest version (if you already have made a setup)
CVSMailer configurator latest version (now possible to check mail setup)
| Changes: | |
| 1.0.0.22 | Configurator improvement: Now makes it possible to check email connectivity while configuring CVSMailer (separate download needed above since it is not part of the setup file) |
| 1.5.2.50 |
|
| 1.5.2.47 |
|
| 1.5.2.41 |
|
| 1.5.2.40 |
|
| 1.5.1.34 |
|
| 1.5.1.31 |
|
| 1.5.1.30 |
|
| 1.4.1.25 |
|
| 1.4.1.21 |
|
| 1.4.1.19 |
|
| 1.3.11.15 |
|
| 1.3.11.13 |
|
| 1.3.11.12 |
|
| 1.3.11.11 |
|
| 1.3.11.10 |
|
| 1.3.10.8 |
|
| 1.3.10.7 |
|
| 1.3.10.6 |
|
| 1.3.9 |
|
| 1.3.8 |
|
| 1.3.7 |
|
| 1.3.6 |
|
| 1.3.6a |
|
| 1.3.5 |
|
| 1.3.4 |
|
| 1.3.3 |
|
| 1.3.2 |
|
If you have comments on the program or on my website, please use the link below to send an email:
Email Bo Berglund
Unique visit counter started 2002-12-08:
Back to contents