Mechanisms to track who is editing files


For many groups, use of CVS 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 CVS is not able to enforce this behavior.

Telling CVS to watch certain files

To enable the watch features, you first specify that certain files are to be watched.

cvs watch on [-l] files

Specify that developers should run cvs edit before editing files. CVS 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, CVS arranges to watch 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.

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

cvs watch off [-l] files

Do not provide notification about work on filesCVS will create working copies of files read-write.

The files and -l arguments are processed as for cvs watch on.

Telling CVS to notify you

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

cvs watch add [-a action] [-l] files

 

cvs watch remove [-a action] [-l] 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, CVS calls the notify administrative file, passing it the user to receive the notification and the user who is taking the action which results in notification. Normally notify will just send an email message.

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, CVS 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, CVS will pass the VALUE (normally an email address on some other machine).

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.

cvs edit [options] files

          Prepare to edit the working files

files 

          . CVS 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; CVS 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 -l option are processed as for the cvs watch commands.

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 [-l] 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 CVS 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 -l option are processed as for the cvs watch commands.

            Abandon work on the working files

files 

            , and revert them to the repository versions on which they are based. CVS makes those

files 

            read-only for which users have requested notification using

cvs watch on

            . CVS notifies users who have requested

unedit 

            notification for any of

files

          .

The files and -l option are processed as for the cvs watch commands.

When using client/server CVS, you can use the cvs edit and cvs unedit commands even if CVS is unable to successfully communicate with the server; the notifications will be sent upon the next successful CVS command.

Information about who is watching and editing

cvs watchers [-l] 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 -l arguments are processed as for the cvs watch commands.

cvs editors [-l] 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 -l arguments are processed as for the cvs watch commands.