Mechanisms to track who is editing files

For many groups, use of cvsnt in its default mode is perfectly satisfactory. Users may sometimes go to check in a modification only to find that another modification has intervened, but they deal with it and proceed with their check in. Other groups prefer to be able to know who is editing what files, so that if two people try to edit the same file they can choose to talk about who is doing what when rather than be surprised at check in time. The features in this section allow such coordination, while retaining the ability of two developers to edit the same file at the same time.

For maximum benefit developers should use cvs edit (not chmod) to make files read-write to edit them, and cvs release (not rm) to discard a working directory which is no longer in use, but cvsnt is not able to enforce this behavior.

Setting up cooperative edits

cvs watch ro [-lR] files ... Specify that developers should run cvs edit before editing files. cvsnt will create working copies of files read-only, to remind developers to run the cvs edit command before working on them.

If files includes the name of a directory, cvsnt sets up cooperative edits for all files added to the corresponding repository directory, and sets a default for files added in the future; this allows the user to set notification policies on a per-directory basis. The contents of the directory are processed recursively, unless the -l option is given. The -R option can be used to force recursion if the -l option is set in ~/.cvsrc (the section called “Default options and the ~/.cvsrc and CVSROOT/cvsrc files”).

If files is omitted, it defaults to the current directory.

cvs watch rw [-lR] files ... Do not create files read-only on checkout; thus, developers will not be reminded to use cvs edit and cvs unedit.

The files and options are processed as for cvs watch ro.

Telling CVS to notify you when someone modifies a file

You can tell cvsnt that you want to receive notifications about various actions taken on a file. You can do this without using cvs watch ro for the file, however generally you will want to use cvs watch ro, so that developers are reminded to use the cvs edit command.

cvs watch add [-a action] [-lR] files ... Add the current user to the list of people to receive notification of work done on files.

The -a option specifies what kinds of events cvsnt should notify the user about. action is one of the following:

edit

Another user has applied the cvs edit command (described below) to a file.

unedit

Another user has applied the cvs unedit command (described below) or the cvs release command to a file, or has deleted the file and allowed cvs update to recreate it.

commit

Another user has committed changes to a file.

all

All of the above.

none

None of the above. (This is useful with cvs edit, described below.)

The -a option may appear more than once, or not at all. If omitted, the action defaults to all.

The files and options are processed as for the cvs watch commands.

cvs watch remove [-a action] [-lR] files ... Remove a notification request established using cvs watch add; the arguments are the same. If the -a option is present, only watches for the specified actions are removed.

When the conditions exist for notification, cvsnt calls the notify administrative file. Edit notify as one edits the other administrative files (the section called “The administrative files”). This file follows the usual conventions for administrative files (the section called “The common syntax”), where each line is a regular expression followed by a command to execute. The command should contain a single occurrence of %s which will be replaced by the user to notify; the rest of the information regarding the notification will be supplied to the command on standard input. A common thing to put in the notify file is the single line:

ALL mail %s -s "CVS notification for bug %b"

This causes users to be notified by electronic mail (assuming the command 'mail' exists).

Note that if you set this up in the straightforward way, users receive notifications on the server machine. One could of course write a notify script which directed notifications elsewhere, but to make this easy, cvsnt allows you to associate a notification address for each user. To do so create a file users in CVSROOT with a line for each user in the format user:value. Then instead of passing the name of the user to be notified to notify, cvsnt will pass the value (normally an email address on some other machine).

CVSNT does not notify you for your own changes. Currently this check is done based on whether the user name of the person taking the action which triggers notification matches the user name of the person getting notification. In fact, in general, the watches features only track one edit by each user. It probably would be more useful if watches tracked each working directory separately, so this behavior might be worth changing.

You can also pass information about the notification to the script, using the following substitution variables:

%s user being notified, or email (see above).

%b bug being edited.

%m reason for edit as supplied by user.

%d date and time of edit.

%u username of user performing the unedit (may not be the same as %s).

%t tag or branch being edited.

How to edit a file which is being watched

Since a file which is being watched is checked out read-only, you cannot simply edit it. To make it read-write, and inform others that you are planning to edit it, use the cvs edit command. Some systems call this a checkout, but cvsnt uses that term for obtaining a copy of the sources (the section called “Getting the source”), an operation which those systems call a get or a fetch.

cvs edit [options] files ... Prepare to edit the working files files. cvsnt makes the files read-write, and notifies users who have requested edit notification for any of files.

The cvs edit command accepts the same options as the cvs watch add command, and establishes a temporary watch for the user on files; cvsnt will remove the watch when files are unedited or committed. If the user does not wish to receive notifications, she should specify -a none.

The files and options are processed as for the cvs watch commands.

If the -c option is given, then the file is checked for existing editors before the edit can proceed. In this way a reasonable facsimile of 'reserved edits' can be achieved (note however this is a suboptimal way to use cvsnt).

If the -x is given, then the edit is marked as exclusive on the server, and other users will be prevented from creating further edits. This option will also prevent commits to the file by their users. (Implies -c).

The -z option stores the edited base revision in a compressed form. This is useful if you are using an IDE which tends to pick up the base revisions while searching files. Its also saves quite a bit of disk space on large edits.

Normally edits apply only to the branch that you are currently using. The -w causes the edit to apply to all branches within the file (which is the behaviour for pre-2.0.55 CVSNT).

The -b marks this edit as belonging to a specific bug. This information is stored and also sent to the CVSROOT/notify script.

The -m sets a reason message for this edit. This can be processed by the CVSROOT/notify script.

Normally when you are done with a set of changes, you use the cvs commit command, which checks in your changes and returns the watched files to their usual read-only state. But if you instead decide to abandon your changes, or not to make any changes, you can use the cvs unedit command.

cvs unedit [-lR] [-r] [-u user] [-w] [-b bug] [-m message] [files...]

Abandon work on the working files files, and revert them to the repository versions on which they are based. CVSNT by default also makes the files read only. Use the -w option to override this.. CVSNT then notifies users who have requested unedit notification for any of files.

The files and options are processed as for the cvs watch commands.

If watches are not in use, the unedit command probably does not work, and the way to revert to the repository version is to remove the file and then use cvs update to get a new copy. The meaning is not precisely the same; removing and updating may also bring in some changes which have been made in the repository since the last time you updated.

The reason message passed to this function is passed directly to the CVSROOT/Notify script. If the -b option is used then only those files edited under a specific bug are unedited.

Repository administrators can use the 'unedit others' option -u. Only use this as a last resort as it only does the server side of the unedit.

Information about who is watching and editing

cvs watchers [-lR] files ... List the users currently watching changes to files. The report includes the files being watched, and the mail address of each watcher.

The files and options are processed as for the cvs watch commands.

cvs editors [-lR] [-a] files ... List the users currently working on files. The report includes the mail address of each user, the time when the user began working with the file, and the host and path of the working directory containing the file.

The files and options are processed as for the cvs watch commands.

Using watches with old versions of CVS

If you use the watch features on a repository, it creates CVS directories in the repository and stores the information about watches in that directory. If you attempt to use cvsnt 1.6 or earlier with the repository, you get an error message such as the following (all on one line):

cvs update: cannot open CVS/Entries for reading:
No such file or directory

and your operation will likely be aborted. To use the watch features, you must upgrade all copies of cvsnt which use that repository in local or server mode. If you cannot upgrade, use the watch off and watch remove commands to remove all watches, and that will restore the repository to a state which cvsnt 1.6 can cope with.