Section 5.2. Watching a File


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 run cvs watch on for a file only once, unless someone clears the setting. Usually, your project leader decides which files can be watched and marks 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 command 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, run 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 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 menu


Figure 5-2. TkCVS showing a current editor


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

The default notify file assumes that the repository server is configured to send email with the command mail. If your server is not, you can use a different form of notification that is configured (such as some form of instant messaging), or set it up for mail.

I like the explanation of mail servers in Running Linux, by Matt Welsh et al. (O'Reilly). It is Linux-focused, but the explanation of email is valid for all systems, and their preferred mail transport agent (Postfix) will work on Unix, Linux, and Mac OS X.


Example 5-1. The file CVSROOT/notify

 ALL mail %s -s "CVS Notification" 

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:[*]

[*] The CVS username is usually the system username, but it may be a special username if you are connecting with pserver (see "The pserver Access Method" in Chapter 8).

 username:email_address 

Example 5-2 shows an example of a users file.

Example 5-2. CVSROOT/users

 jenn:jenn@helit.example.com doppel:doppel@teppic.example.com 

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

When working with the files in the CVSROOT directory, such as notify and users, check them out into a sandbox and edit them in the sandbox. When you commit them, CVS will automatically install the clear-text file it needs for its configurations. (See "CVSROOT Files" in Chapter 6.)

The command to create a CVSROOT sandbox is cvs -d repository_path checkout CVSROOT.


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

 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@example.com To:        jenn@helit.example.com Subject:   CVS Notification Date:      17 Apr 2006 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'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.

Before you run cvs edit on a file, check your notification (usually email) to determine whether someone else has claimed it.


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.

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

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'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 edit

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

If both the client and the server are CVS 1.12.10 or later, you can use edit and commit with the -c option. Used with commit, -c causes the commit to fail if the user is not the current listed editor of the file, and to succeed if the user is the listed editor. Used with edit, -c causes the edit to fail if anyone else is registered as the editor, but to succeed if the file is currently unclaimed.

If you want to use the -c options, it is useful to put them in the .cvsrc of all developers. The .cvsrc file is explained in Chapter 3.

CVS 1.12.10 also added the -f option to edit, which forces the edit through regardless of other editors. It overrides -c, and is useful when -c is in the user's .cvsrc but the user has reason to edit a file even though someone else has claimed exclusive development.


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

 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 Apr 17 12:13:44 2006 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.




Essential CVS
Essential CVS (Essentials)
ISBN: 0596527039
EAN: 2147483647
Year: 2006
Pages: 148

Similar book on Amazon

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net