Enabling Watches In The Repository

First, the CVSROOT/notify file must be edited to turn on email notification. One of the developers can do this, or the repository administrator can if the developers don't have permission to change the repository's administrative files. In any case, the first thing to do is check out the administrative area and edit the notify file:

     floss$ cvs -q co CVSROOT
     U CVSROOT/checkoutlist
     U CVSROOT/commitinfo
     U CVSROOT/config
     U CVSROOT/cvswrappers
     U CVSROOT/editinfo
     U CVSROOT/loginfo
     U CVSROOT/modules
     U CVSROOT/notify
     U CVSROOT/rcsinfo
     U CVSROOT/taginfo
     U CVSROOT/verifymsg
     floss$ cd CVSROOT
     floss$ emacs notify
     ...

When you edit the notify file for the first time, you'll see something like this:

     # The "notify" file controls where notifications from watches set by
     # "cvs watch add" or "cvs edit" are sent. The first entry on a line is
     # a regular expression which is tested against the directory that the
     # change is being made to, relative to the $CVSROOT. If it matches,
     # then the remainder of the line is a filter program that should contain
     # one occurrence of %s for the user to notify, and information on its
     # standard input.
     #
     # "ALL" or "DEFAULT" can be used in place of the regular expression.
     #
     # For example:
     # ALL mail %s -s "CVS notification"

All you really need to do is uncomment the last line by removing the initial # mark. Although the notify file provides the same flexible interface as the other administrative files, with regular expressions matching against directory names, the truth is that you almost never want to use any of that flexibility. The only reason to have multiple lines, with each line's regular expression matching a particular part of the repository, would be if you wanted to use a different notification method for each project. However, normal email is a perfectly good notification mechanism, so most projects just use that.

To specify email notification, the line

     ALL mail %s -s "CVS notification"

should work on any standard Unix machine. This command causes notifications to be sent as emails with the subject line CVS notification (the special expression ALL matches any directory, as usual). Having uncommented that line, commit the notify file so the repository is aware of the change:

     floss$ cvs ci -m "turned on watch notification"
     cvs commit: Examining .
     Checking in notify;
     /usr/local/newrepos/CVSROOT/notify,v  <--  notify
     new revision: 1.2; previous revision: 1.1
     done
     cvs commit: Rebuilding administrative file database
     floss$

Editing the notify file in this way may be all that you'll need to do for watches in the repository. However, if there are remote developers working on the project, you may need to edit the CVSROOT/users file, too. The purpose of the users file is to tell CVS where to send email notifications for those users who have external email addresses. The format of each line in the users file is:

     CVS_USERNAME:EMAIL_ADDRESS

For example,

     qsmith:quentinsmith@farawayplace.com

The CVS username at the beginning of the line corresponds to a CVS username in CVSROOT/password (if present and the pserver access method is being used), or failing that, the server-side system username of the person running CVS. Following the colon is an external email address to which CVS should send watch notifications for that user.

Unfortunately, as of this writing, the users file does not exist in the stock CVS distribution. Because it's an administrative file, you must not only create, cvs add, and commit it in the usual way, but also add it to CVSROOT/checkoutlist so that a checked-out copy is always maintained in the repository.

Here is a sample session demonstrating this:

     floss$ emacs checkoutlist
       ... (add the line for the users file) ...
     floss$ emacs users
       ... (add the line for qsmith) ...
     floss$ cvs add users
     floss$ cvs ci -m "added users to checkoutlist, qsmith to users"
     cvs commit: Examining .
     Checking in checkoutlist;
     /usr/local/newrepos/CVSROOT/checkoutlist,v  <--  checkoutlist
     new revision: 1.2; previous revision: 1.1
     done
     Checking in users;
     /usr/local/newrepos/CVSROOT/users,v  <--  users
     new revision: 1.2; previous revision: 1.1
     done
     cvs commit: Rebuilding administrative file database
     floss$

It's possible to use expanded-format email addresses in CVSROOT/users, but you have to be careful to encapsulate all whitespace within quotes. For example, the following will work

     qsmith:"Quentin Q. Smith <quentinsmith@farawayplace.com>"

or

     qsmith:'Quentin Q. Smith <quentinsmith@farawayplace.com>'

However, this will not work:

     qsmith:"Quentin Q. Smith" <quentinsmith@farawayplace.com>

When in doubt, you should test by running the command line given in the notify file manually. Just replace the %s in

     mail %s -s "CVS notification"

with what you have following the colon in users. If it works when you run it at a command prompt, it should work in the users file, too.

When it's over, the checkout file will look like this:

     # The "checkoutlist" file is used to support additional version controlled
     # administrative files in $CVSROOT/CVSROOT, such as template files.
     #
     # The first entry on a line is a filename which will be checked out from
     # the corresponding RCS file in the $CVSROOT/CVSROOT directory.
     # The remainder of the line is an error message to use if the file cannot
     # be checked out.
     #
     # File format:
     #
     #       [<whitespace>]<filename><whitespace><error message><end-of-line>
     #
     # comment lines begin with '#'
     
     users   Unable to check out 'users' file in CVSROOT.

The users file will look like this:

     qsmith:quentinsmith@farawayplace.com

Now that the repository is set up for watches, let's look at what developers need to do in their working copies.