5.2. Watching a FileCVS provides a set of commands to notify users when a file is being edited or committed. You can use these commands to monitor what each member of your team is doing and reduce the necessity of merging files when cvs update is run. Together, the cvs watch, cvs edit, and cvs unedit commands make up the watch method of exclusive development, which is a lightly enforced method of exclusive development. The watch method requires the repository administrator to set up the notify and users files in the CVSROOT directory of the CVS repository; it requires the developers to check whether a file is being edited before they attempt to edit it. Use cvs watch like this:
The watch method is voluntary; there is nothing preventing another user from making changes to a file you are editing. However, the cvs edit command automatically designates you as a temporary watcher on a file until you release the file. So, if another developer runs cvs edit on the file, you are notified and can contact them to coordinate your changes. The cvs edit and cvs unedit commands work in conjunction with CVS's watch feature to enable you to keep track of activity in your project's files. The watching and editing features can also be used independently of each other. The next few sections show how to use the watch method to coordinate development and monitor activity in your project files. Figure 5-1 shows the Cervisia menu for the watch-related commands. Figure 5-2 shows a TkCVS display with the server.cc file claimed by user jenn. Figure 5-1. Cervisia watch menuFigure 5-2. TkCVS showing a current editor5.2.1. Configuring WatchesBefore using the watch commands, you need to designate files as watchable and configure how you want CVS to notify watchers. You can designate which files are watchable with the cvs watch on command, which marks a file as watchable but does not make you a watcher. CVS notifies a file's watchers when the file is committed, marked for editing, or released from editing. When the conditions exist for CVS to notify a watching user, CVS runs the commands in the repository's CVSROOT/notify file. This file usually contains a single line that causes the watcher to be emailed with the notification. (It may be commented out at installation). Such a line is shown in Example 5-1.
Example 5-1. The file CVSROOT/notify
The notify file in Example 5-1 sends an email to the user's CVS username at the computer that the repository is on. If there are users whose mailboxes (or other notification method) are not on the same computer or use different usernames, create a users file in the repository's CVSROOT directory. The format of this file is a separate line for each user, consisting of the CVS username and the email address to send notifications to, in the following format:[*]
username:email_address Example 5-2 shows an example of a users file. Example 5-2. CVSROOT/users
The full syntax for the notify and users files is explained in Chapter 6.
5.2.2. Marking a File for WatchingBefore using the watch commands on a file, you need to set the file for watching. Files that are set for watching are checked out as read-only, and the intent is that you run cvs edit to set the file's permissions to allow editing, and to notify other watchers that you intend to edit it. If a directory is designated as being watched, all new files in that directory are set for watching. Use the command cvs watch on filename to set a file for watching, and use cvs watch off filename to revert it to normal mode. Note that setting the file for watching does not add you to the list of people watching the file; it only enables the watch system for that file. The watch system is honor-based. You can set a file read-write without using the cvs edit command and then edit it without ever notifying other users. (They get a message when you commit the file, however.) CVS also won't stop another user from using cvs watch off to turn off the watch you set. If you need a more restrictive system, consider using the rcslock system described in "Reserving Files," later in this chapter. 5.2.3. Setting Your WatchWatching a file sets CVS to notify you when someone signals their intent to edit the file, when someone commits that file, or when someone signals that they have stopped editing the file. CVS does not notify you of your own changes to the file. Use the command cvs watch add filename to add yourself to the list of people watching a file. cvs watch add takes the -a command option, which restricts the actions CVS should notify you of. The -a option has the parameters edit, unedit, commit, none, or all. The default case is all. To stop watching a file, use cvs watch remove filename. cvs watch remove also takes the -a option with the same parameters as cvs watch add. Both commands use -R to operate recursively down a directory tree and -l to operate locally. You can use cvs watch add or cvs watch remove without having the file set for watchingin other words, without executing cvs watch on firstbut CVS can inform you of an edit only if the other developer uses cvs edit. If the file is not set for watching, the other developer is not reminded to use cvs edit. Unfortunately, the cvs watch commands do not provide helpful feedback when they are called; they do provide error messages if appropriate. Example 5-3 shows the use of the cvs watch commands. Example 5-3. Using cvs watch
Example 5-4 shows the mail CVS sends as a result of a cvs edit command. Example 5-4. Mail from CVS
The syntax of the cvs watch command is: cvs [cvs-options] watch {on|off|add|remove} [command-options] [filenames] The cvs watch command can take filenames, directory names, or modules as parameters and use the sandbox directory as a parameter if no other parameter is given. If no -a option is given to cvs watch add or cvs watch remove, -a all is the default. Example 5-5 demonstrates using cvs watch locally to set a specific watch for a directory, but not subdirectories. It also uses the watchers command to show some of the results of the watch. Example 5-5. Using cvs watch options
5.2.4. Editing a FileSignal your intent to edit a file with the cvs edit filename command. This sets the file's permissions to read-write, signals CVS to notify all watchers who are interested in edits, and temporarily adds you as one of the file's watchers. If you do not wish to watch the file, you can use -a none.
Once you have signaled your intent to edit a file, use your usual editor to make your changes. When you are finished, use cvs commit to save changes or cvs unedit to revert them. The syntax of cvs edit is: cvs [cvs-options] edit [command-options] [filenames] The syntax of cvs unedit is: cvs [cvs-options] unedit [command-options] [filenames] Both commands can take filenames, directory names, or modules as parameters and use the sandbox directory as a parameter if no other parameter is given. Both commands use -R to operate recursively down a directory tree and -l to operate locally. The edit command also supports -a with the same parameters as cvs watch. If no -a option is given to cvs edit, -a all is set by default.
5.2.4.1. Aborting an editWhen you commit a file with cvs commit, CVS clears the file's edit mark. If you want to clear the edit on a file but don't want to commit your changes, you can use the cvs unedit filename command, use cvs release on the directory the file is in, or delete the file and use cvs checkout or cvs update to recreate it. The cvs unedit command sets the target file's permissions to read-only, notifies CVS to signal users watching for unedits, clears you from watching the file if you had a temporary, cvs edit-based watch, and reverts the file to the repository revision on which it was based.
Deleting the file and issuing cvs checkout or cvs update notifies watchers, clears you from watching the file, returns the file to the latest repository revision, and sets the file's permissions to read only if it is still a watched file. Issuing cvs release or deleting the file and then issuing cvs checkout or cvs update sends a notification to users watching for an unedit and clears you from a temporary watch. Using cvs release also sets the directory to no longer be a sandbox directory. 5.2.4.2. Committing an editUse cvs commit to save your changes to the repository. This command also clears your edit signal, sets any watched files' permissions to read only, signals users watching for commits, and clears you from watching the file if you were temporarily watching it (i.e., if you used cvs edit and didn't use the -a none option).
5.2.5. Listing Watchers and EditorsBefore editing a watched file, you should use the cvs editors command to see whether anyone else has issued cvs edit to indicate they are editing the file. You might also want to know who is watching the file you're about to edit. The cvs watchers filename command lists the people currently watching the file, showing their username as stored in the notify or users files in the repository's CVSROOT directory. The cvs editors filename command lists the people currently editing the file, their email addresses, the time they began working with the file, and the host and path of the directory containing the file. See Example 5-6 for an example of the cvs watchers and cvs editors commands. Example 5-6. Using cvs watchers and cvs editors
The syntax of cvs watchers is: cvs [cvs-options] watchers [command-options] [filenames] The syntax of cvs editors is: cvs [cvs-options] editors [command-options] [filenames] Both commands can take filenames, directory names, or modules as parameters and use the sandbox directory as a parameter if no other parameter is given. Both accept the -l (local) and -R (recursive) command options. |