Advanced usage

Tagging and branching
We discuss here only the technical aspects of tagging and branching. If you are only a user, not the administrator of the repository, you will probably not be confronted with the problem. If however you are your own administrator, you should first read about the non-technical problems that accompany branching, in order to get an impression of how time-consuming and error-prone maintaining different branches of a project can be. The appendix includes some references about this topic.
Simple tagging is something you usually do when a release is made, so that you can at any time easily get back to the project state at that time. Tags are usually given a name consisting of the project name and the version number. For example, 1.0 is available under the tag CERVISIA_1_0. enforces CVS's strict rules about what constitutes valid tag name. It must begin with a letter and may contain letters, digits, hypens and underscores.
Normally, you will want to tag the whole project (although CVS of course allows you to tag only a subset). To this end, mark the toplevel directory in the view and choose Advanced Tag/Branch. Now enter the name of the tag, press Return and you are done!
Creating a branch is not significantly more difficult: In the tag dialog, check the box Create branch with this tag. You can also delete an existing tag: Choose Advanced Delete tag in the main view.
There are several ways to update to a certain state of the project:
You can update to a certain tag. Use Advanced Update to tag/date for this. The same procedure is used for updating to a branch. The command issued by is

cvs update -r tag

You can update to a certain date. This may be useful if an error was introduced in the project between two releases, you know approximately between, and have an opinion on when that was. You can go to some date by choosing Advanced Update to tag/date and checking the box Update to date. In the field below, you can enter a wide variety of date formats. One possible format is yyyy-mm-dd where yyyy is the year, mm is the month (numerically) and dd is the day. Alternatives are some english phrases like yesterday or 2 weeks ago. When you use this option, uses the command

cvs update -D date

Both options above make a tag or date 'sticky', i.e. you can not commit further modifications on that files (unless the tag is a branch tag). In order to get back to the trunk, also known as the branch with the name HEAD, use the menu item Advanced Update to HEAD. This results in a command

cvs update -A

A screenshot of 's update to tag dialog
Another aspect of branching is the merging of modifications from a branch to the current branch. If you are going to do this, choose Advanced Merge.... The dialog that appears now gives you two options:
Either you may merge all modifications done on a branch to the current branch. In that case, check the box Merge from branch and fill in the branch you want to merge from. will then execute the command

cvs update -j branchtag

The other possibility is that you want to merge only the modifications made between two tags on a branch. This usually happens when you merge from the same branch to the trunk several times. In that case, check the box Merge modifications and enter (in the correct order) the two relevant tags. This will result in a command

cvs update -j branchtag1 -j branchtag2

Using watches
A watch is the conventional name for CVS's feature to notify users of the repository whenever a file has been changed. The usage of watches requires that the file $CVSROOT/CVSROOT/notify has been set up properly. This is not discussed here; if you need further information on the setup from the administrator's point of view, read one of the books listed in the appendix.
's main support of watches are three menu items. In order to add a watch to one or several files, use Advanved Add watch.... In the dialog you get, you can choose to get notified for any of the types of events that CVS supports. For example, if you only want to get notified when a file is commited, check the boxes Only and Commits. If you want to get notified about any event related to the marked files, check the box All. The command line used when you accept the dialog is

cvs watch add -a commit filenames

or with a similar option, depending on the events you chose to watch.
If you not interested into some files anymore, you can remove your watches on them. To this end, use Advanved Remove watch.... In the dialog you get here, the same options are offered as in the form you filled out when adding the watch. When you confirm this dialog, issues the command

cvs watch remove filenames

possibly with an option -a for the chosen events.
Finally, you can get a list of the people who are watching a couple of files. Choose Advanved Show watchers. Using this menu item will result in a command

cvs watchers filenames

's editor interface helps you with projects that use watches. In such projeccts, files that are watched are checked out readonly. If you would just start an editor with such a readonly file, you cannot save your modifications later. This has of course a reason: Whenever you want to change a file, you should run cvs edit before, so that all people watching the file get a notification that you are working on it.
If you are working with watched files, it is advisable to check the option Settings Do cvs edit automatically when necessary. Now, whenever you edit a file by double-clicking it, will run cvs edit before the editor is actually executed. Then you can edit your file as usual. When you have finished your work, commit your files, and the commited files are readonly again.