home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam  


  Previous section   Next section

5.2 Watching a File

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:

  1. Check out your sandbox, including the files you want to watch.

  2. 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.

    You need to use cvs watch on for a file only once, unless someone clears the setting. Usually, your project leader decides which files can be watched and will mark those files for watching.

  3. Issue the cvs watch add command to set yourself as a watcher of the files you want to watch.

  4. 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.

  5. Edit the file in any editor.

  6. 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.

  7. 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.

5.2.1 Configuring Watches

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.

Example 5-1. CVSROOT/notify
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.

Example 5-2. CVSROOT/users
jenn:jenn@helit.nosuch.com
doppel:doppel@teppic.nosuch.com

The full syntax for the notify and users files is explained in Chapter 6.

5.2.2 Marking a File for Watching

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.

5.2.3 Setting Your Watch

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.

Example 5-3. Using cvs watch
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.

Example 5-4. Mail from CVS
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.

Example 5-5. Using cvs watch options
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
.
.
.

The cvs watch command doesn't work if either the server or the client is running CVS version 1.6 or earlier.

5.2.4 Editing a File

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.

The cvs edit command does not restrict anyone else from editing the file you're working on; it only signals to them that you're editing it. It doesn't warn you if someone else is already editing the file.

5.2.4.1 Aborting an edit

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.

If you call cvs unedit on a file that is not currently set for watching, CVS can revert the file only if CVS can contact the server.

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.

5.2.4.2 Committing an edit

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.

5.2.5 Listing Watchers and Editors

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.

Example 5-6. Using cvs watchers and cvs editors
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.


  Previous section   Next section
Top