First, a developer checks out a working copy and adds herself to the list of watchers for one of the files in the project:
floss$ whoami jrandom floss$ cvs -q co myproj U myproj/README.txt U myproj/foo.gif U myproj/hello.c U myproj/a-subdir/whatever.c U myproj/a-subdir/subsubdir/fish.c U myproj/b-subdir/random.c floss$ cd myproj floss$ cvs watch add hello.c floss$
The last command, cvs watch add hello.c, tells CVS to notify jrandom if anyone else starts working on hello.c (that is, it adds jrandom to hello.c's watch list). For CVS to send notifications as soon as a file is being edited, the user who is editing it has to announce the fact by running cvs edit on the file first. CVS has no other way of knowing when someone starts working on a file. Once checkout is done, CVS isn't usually invoked until the next update or commit, which happens after the file has already been edited:
paste$ whoami qsmith paste$ cvs -q co myproj U myproj/README.txt U myproj/foo.gif U myproj/hello.c U myproj/a-subdir/whatever.c U myproj/a-subdir/subsubdir/fish.c U myproj/b-subdir/random.c paste$ cd myproj paste$ cvs edit hello.c paste$ emacs hello.c ...
When qsmith runs cvs edit hello.c, CVS looks at the watch list for hello.c, sees that jrandom is on it, and sends email to jrandom telling her that qsmith has started editing the file. The email even appears to come from qsmith:
From: qsmith Subject: CVS notification To: jrandom Date: Sat, 17 Jul 1999 22:14:43 -0500 myproj hello.c -- Triggered edit watch on /usr/local/newrepos/myproj By qsmith Furthermore, every time that qsmith (or anyone) commits a new revision of hello.c, jrandom will receive another email: myproj hello.c -- Triggered commit watch on /usr/local/newrepos/myproj By qsmith
After receiving these emails, jrandom may want to update hello.c immediately to see what qsmith has done, or perhaps she'll email qsmith to find out why he's working on that file. Note that nothing forced qsmith to remember to run cvs edit – presumably he did it because he wanted jrandom to know what he was up to (anyway, even if he forgot to do cvs edit, his commits would still trigger notifications). The reason to use cvs edit is that it notifies watchers before you start to work on a file. The watchers can contact you if they think there may be a conflict, before you've wasted a lot of time.
CVS assumes that anyone who runs cvs edit on a file wants to be added to the file's watch list, at least temporarily, in case someone else starts to edit it. When qsmith ran cvs edit, he became a watcher of hello.c. Both he and jrandom would have received notification if a third party had run cvs edit on that file (or committed it).
However, CVS also assumes that the person editing the file only wants to be on its watch list while he or she is editing it. Such users are taken off the watch list when they're done editing. If they prefer to be permanent watchers of the file, they would have to run cvs watch add. CVS makes a default assumption that someone is done editing when he or she commits a file (until the next time, anyway).
Anyone who gets on a file's watch list solely by virtue of having run
cvs edit on that file is known as a temporary watcher
and is taken off the watch list as soon as she commits a change to the
file. If she wants to edit it again, she has to rerun
CVS's assumption that the first commit ends the editing session is only a best guess, of course, because CVS doesn't know how many commits the person will need to finish their changes. The guess is probably accurate for one-off changes – changes where someone just needs to make one quick fix to a file and commit it. For more prolonged editing sessions involving several commits, users should add themselves permanently to the file's watch list:
paste$ cvs watch add hello.c paste$ cvs edit hello.c paste$ emacs hello.c ... paste$ cvs commit -m "print hello in Sanskrit"
Even after the commit, qsmith remains a watcher of hello.c because he ran watch add on it. (By the way, qsmith will not receive notification of his own edits; only other watchers will. CVS is smart enough not to notify you about actions that you took.)