|
|
CVS 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:
Check out your sandbox, including the files you want to watch.
Issue the cvs watch on command to mark files for watching. (This does not set you as the watcher for the files; it just informs CVS that the files can be watched.) Once a file has been marked for watching, it remains marked unless it is cleared with cvs watch off.
|
Issue the cvs watch add command to set yourself as a watcher of the files you want to watch.
Issue cvs edit to inform CVS and other users that you intend to edit a specific file. Other users watching the file will be notified that you are editing it.
Edit the file in any editor.
Commit your changes with cvs commit. This saves the changes to the repository and releases the file for others to edit. CVS notifies other users watching the file that you have committed it.
If you don't want to commit your changes, but instead want to revert to the state of the file before you edited it, use cvs unedit to release it for others to edit. CVS notifies anyone watching the file that you are no longer editing it.
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 will be 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 watch 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.
Before 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. This 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. Such a line is shown in Example 5-1.
ALL mail %s -s "CVS Notification"
By default, this command 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[1] and the email address to send notifications to, in the following format:
[1] The CVS username is usually the system username, but it may be a special username if you are connecting with pserver. See Section 8.7 in Chapter 8.
username:email_address
Example 5-2 shows an example of a users file.
jenn:jenn@helit.nosuch.com doppel:doppel@teppic.nosuch.com
The full syntax for the notify and users files is explained in Chapter 6.
Before using the watch commands on a file, you need to set the file for watching. Files that are set for watching are checked out read-only, and the intent is that you use cvs edit to set a file read-write and 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 will 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 Section 5.3 later in this chapter.
Watching 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 watching — in other words, without executing cvs watch on first — but 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. Example 5-3 shows the use of the cvs watch commands.
bash-2.05a$ cvs watch on Makefile bash-2.05a$ cvs watch add -a edit Makefile bash-2.05a$ cvs watch remove Makefile bash-2.05a$ cvs watch off Makefile bash-2.05a$
Example 5-4 shows the mail CVS sends as a result of a cvs edit command.
From: doppel@nosuch.com To: jenn@helit.nosuch.com Subject: CVS Notification Date: 17 Sep 2002 22:13:45 +1000 wizzard Makefile --- Triggered edit watch on /var/lib/cvs/wizzard By Poppel
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.
bash-2.05a$ cvs watch add -l -a commit . bash-2.05a$ cvs watchers . Changelog jenn unedit commit INSTALL jenn unedit commit Makefile jenn edit unedit commit README jenn unedit commit TODO jenn unedit commit doc/design/AcceptanceTest.doc jenn unedit doc/design/Analysis.rtf jenn unedit . . . src/config.h doppel edit unedit commit jenn edit unedit . . .
|
Signal your intent to edit a file with the cvs edit filename command. This sets the file 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 signalled 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.
|
When 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 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 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.
Use cvs commit to save your changes to the repository. This command also clears your edit signal, sets any watched files to read-only, signals users watching for commits, and clears you from watching the file if you had a temporary watch set on it.
Before 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 email addresses 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 watches and cvs editors commands.
bash-2.05a$ cvs watchers
Changelog doppel edit unedit commit
INSTALL doppel edit unedit commit
Makefile doppel edit unedit commit
jenn edit unedit commit
bash-2.05a$ cvs editors Makefile
Makefile jenn Tue Sep 17 12:13:44 2002 GMT helit /home/jenn/cvs/wizzard
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.
 |
|
|
| Top |