GNU Info

(cvsbook.info)Enabling Watches In The Repository

---

Next: Using Watches In Development Prev: How Watches Work Up: Watches (CVS As Telephone)

---

Enter node , (file) or (file)node

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.