In this section, we discuss how you put a new project into the CVS repository. If you just want to work with an existing project which is already in a repository, you may skip this section.

Figure 1.1. A screenshot of Cervisia's import dialog

---

---

In Figure 1.1 you can see the dialog which helps you to import a project as a module. After you have filled out this form and confirmed by OK, the following CVS command is used:

cvs -d repository import -m "" module vendortag releasetag

	The name of the CVS repository, also known as $CVSROOT. You must have write access to it, and the repository must be properly initialized. If the repository does not yet exist, initialize it with the command cvs -d repository init. If the repository is remote, make sure that authentication works (see the section called “Accessing The Repository”).
	The name of the module under which the project will be stored. After the import, the project can be checked out under this name. See the section called “Checkout a module from the repository” for more information. This is also the name of the corresponding folder in the repository.
	The vendor tag is historically used for tracking third-party sources. Just use your user name if you have no better idea. It does not matter much what you enter here.
	This tag is also historically used for importing different versions of third-party software. If you are not doing this, use the word start or a string FOO_1_0 where FOO is the name of your project and 1.0 is the version number of the imported release.

Working folder.  This is the toplevel folder of the project you want to import. The import starts from this folder and goes down recursively.

Ignore files.  If you fill out this field, an additional -I filenames option is given go the cvs import command. This entry is interpreted as a whitespace-separated list of file name patterns which are ignored. In general, a cleaner and less error-prone way to control which files go into the repository is to create a folder with only the files which you want to import and start from that. Nevertheless, this entry may be useful if the project contains files which are by default ignored by CVS, e.g. files with the name core. In such a case, simply enter the character ! in this field. This overrules CVS's scheme of ignored files, see the section called “Ignored files”.

Import as binaries.  If you check this box, all files are imported in binary mode, i.e. an argument -kb is given to cvs import.

Before you work on a project under revision control, you must check out a working copy.

Figure 1.2. A screenshot of Cervisia's checkout dialog

---

---

Repository.  The name of the CVS repository, also known as $CVSROOT. If the repository is remote, make sure that authentication works, see the section called “Accessing The Repository”.

Module.  The name of the module to be checked out. If you are working with an existing repository, you have probably got this name from the administrator. Alternatively, if the repository has a $CVSROOT/modules file, you can retrieve a list of available modules by clicking on the Fetch list button.

Working folder.  The folder under which the module should be checked out. Note that the toplevel folder of the working copy is always created as a folder with the name as the module under the folder given here.

When you start Cervisia, and open a working copy by choosing File->Open Sandbox... you see a hierarchical view of the current folder. According to the settings in your .cvsignore files, the files you usually do not want to include into the repository - like e.g. object files - are not shown. For each file, you see its corresponding status. In the default setting, this is "Unknown" because Cervisia delays the fetching of information until you choose Update or Status from the File menu. With this approach, you have a minimal amount of functionality available even if you do not have a permanent connection to the CVS server.

Figure 1.3. A screenshot of Cervisia's main view

---

---

The commands in the File menu usually act only on the files which you have marked. You may also mark folders. Now choose Update from the File menu. Cervisia issues a

cvs update -n filenames

command to get status information for the marked files. Note that Cervisia goes recursively into subfolders. only if you have the according option in the Settings menu set. According to the respective file's status, you now see an entry in the Status column:

Now that you have got an overview of the current status of the CVS, you may want to do an update. Mark some files (or the root of the folder tree which is equivalent to marking all files in this folder). Now choose Update from the File menu. (Of course, you could have chosen this at the beginning of the session). For some of the files the status may change now. Typically, files which had "Needs Patch" or "Needs Update" are updated. So the following new items are possible in the status column:

You may have noticed that according to the status of the file, its row has a different color. The colors are chosen to somehow reflect the priority of the status. For example, a file with a conflict is marked red to show you that you have to resolve a conflict before you can continue working with the file. If your folder contains a high number of files, you may nevertheless lose the overview. To get more concise information about which files have an unusual status, simply click on the header of the Status column. The file list is then sorted by priority, so you have all important information at the top of the list. To get back to the alphabetically sorted view, click on the header of the File name column.

Like adding files, removing files is done in two steps: First, the files have to be registered as removed by choosing File->Remove from repository which issues the command

cvs remove -f filenames

After that, this modification to the sandbox has to be committed, possibly together with other modifications to the project.

Folders are handled fundamentally different from ordinary files by CVS. They are not under revision control, i.e. you cannot tell which folders existed in the project at a certain time. Furthermore, folders can never be explicitly removed (expect by removing them directly in the repository).

As a substitute, CVS follows the convention that a folder is "not existent" in a version of the project if is is empty. This convention can be enforced by using the option -P to cvs update and cvs checkout. This option can be set in the menu Settings->Prune Empty Folders On Update.

A folder can be added to the repository with the command

cvs add dirname

which is implied by the menu item File->Add to repository. Note that in contrast to adding files, adding folders does not require a commit afterwards.

When you have made a certain amount of changes to your working copy, and you want other developers to have access to them, you 'commit' them. With a commit, you place your versions of the modified files as new revisions into the repository. A subsequent update by another developer will bring your modifications into his working copy.

In order to commit a couple of files, select them in Cervisia's main view and choose File->Commit....

Figure 2.1. A screenshot of Cervisia's commit dialog

---

---

You get a dialog that shows you on the top a list of the selected files and on the bottom a log message for your changes. When you have finished the dialog, the command

cvs commit -m message filenames

is used. Cervisia helps you in several ways to find a meaningful log message: First, in the file list you can double-click a file or press Return in order to see the changes you have made to the file. Second, it gives you a list of log messages you have previously used in a combo box. Third, this dialog is integrated with Cervisia's changelog editor described below.

%cvs update -r X

With Cervisia, it is quite easy to maintain a ChangeLog file that is compliant with the format laid out in the GNU coding guidelines. To use it, choose File->Insert ChangeLog entry.... If a file with the name ChangeLog exists in the toplevel folder of your sandbox, this file will be loaded and you have the possibility to edit it. To this end, at the top of the file, an entry with the current date and your user name (which can be configured as described in the section called “General”) is inserted. When you finish the dialog this dialog by clicking OK, the next commit dialog you open will have the log message set to the message you last entered in the change log.

Conflicts may occur whenever you have made changes to a file which was also modified by another developer. The conflict is detected by CVS when you update the modified file. CVS then tries to merge the modifications committed by the other developer into your working copy. The merge fails if both your and his modifications are in overlapping parts of the file, and the CVS server issues and error message.

It is your job now to resolve these conflicts before you commit the file. CVS will refuse to commit any files with conflicts until they have been edited. Of course, you have a great amount of freedom when resolving a set of conflicts: you can for each conflict decide to take one of the two alternative versions. You can also decide that both approaches are are broken and rewrite a whole routine or the complete file from scratch.

In Cervisia's main view, files with conflicts are indicated with "Conflict" in the status column and with a red color. From the main view, you can of course resolve conflicts the traditional way: just double-click the file in question and edit it with your favorite editor. But you can also choose to use the dialog available via File->Resolve....

Figure 2.2. A screenshot of Cervisia's resolve dialog

---

---

On the top of the dialog, you see your version the file on the left hand side and the version in the repository on the right hand side. The differences between them are marked in red color. Below these two versions, you can see the merged version which will be saved as soon as you click the Save button.

You can switch between the differing sections by pressing << and >>. In the lower middle of the dialog you can see which section is currently marked. For example, 2 of 8 means that you are currently at the second differing section of 8 total. Now can can decide section by section which of the both versions you want to have in the merged file. By pressing A, you take over the version you edited. By pressing B, you take over the version from the repository.

If the used repository has logging enabled, Cervisia can present you a history of certain events like checkouts, commits, rtags, updates and releases. Choose History from the View menu, and Cervisia will issue the command

cvs history -e -a

Now you can see the list of events, sorted by date. In the second column, the type of the event is shown:

Figure 3.2. A screenshot of Cervisia's history dialog

---

---

You can sort the list by other criteria simply by clicking on the respective column header. In order to sort out the history entries you are interested in, there are various filter options activated by check boxes:

Special characters recognized by the regular expression matcher are:

There are several places in Cervisia where you can ask for a window showing the differences between revisions of a file:

As you may have expected, Cervisia does not just dump the output of the diff command into your terminal, but shows you a graphical view as seen in Figure 3.3.

Figure 3.3. A screenshot of Cervisia's diff dialog

---

---

The text in the dialog is an improved variant of the text given by the diff command with the -u option. You can see the differing versions in two windows, with lines arranged such that you can do a side-by-side comparison. That means, where text has been added or deleted, the respective window shows empty lines with the marker +++++ at the left hand side. Elsewhere, you can see the running number of each line in the left column.

In the second column in the right window, you can see which kind of change has been made. Possible types are Add, Delete and Change. The respective lines are marked in blue, green and red color. In the middle of the dialog a compressed image of the color markers is shown. In this way, you can get a quick overview of the overall changes to the file. You can also use the position of the colored regions in the compressed image as an orientation when you using the scroll bars.

Normally, the scrollbars at the left and the right window are synchronized, i.e. if you scroll on the left hand side, the right hand side is scrolled by the same amount. You can change this by checking the box Synchronize scroll bars.

For information about how to customize the diff dialog, see the section called “Various commands”.

With the command cvs annotate, CVS offers the possibility to see - for each line in a file - who has modified a line the most recently. This view may be helpful in order to find out who has introduced a change in the behavior of a program or who should be asked about some change or bug in the code.

Cervisia gives you to access to this feature, but it further enriches the information in an interactive way. You obtain an annotate view by choosing View->Annotate.... Another possibility is to press the button Annotate in the Browse log dialog. In Figure 3.4 you can see a screenshot of the dialog.

Figure 3.4. A screenshot of Cervisia's annotate dialog

---

---

In the annotate dialog, you see in a window the latest version of the selected file. In the columns before the text, you get some information related to the latest change in each line. In the first column the revision number is displayed. In the second column you see the name of the author of that revision. Finally, in the third column you see the date of the latest change in the line.

Consequently, when a certain line appears strange to you or you assume a bug there, you can immediately see who is responsible for that line. But not only that, you can also find out why that line was changed. To this end, move the mouse cursor over the respective revision number. Then a tooltip appears that shows the log message and the date of the change.

A watch is the conventional name for CVS's feature to notify users of the repository whenever a file has been changed or a developer has started editing a file. 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.

Cervisia's main support of watches are six menu items.

In order to add a watch to one or several files, use Advanced->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 committed, 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 are not interested in some files anymore, you can remove your watches on them. To this end, use Advanced->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, Cervisia 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 Advanced->Show watchers. Using this menu item will result in a command

cvs watchers filenames

In the normal usage scenario of CVS, each developer works separately in his checked out sandbox. When he wants to modify some file, he can just open it in his editor and start working on it. Nobody else will know about this work until the file gets committed.

For some developer groups, this is not the preferred model of cooperation. They want to get notified about someone working on a file as soon as he starts with it. This can be achieved by some further CVS commands. Before you start editing a file, select it in Cervisia's main window and choose Advanced->Edit. This will execute the command

cvs edit filenames

This will send out a notification to everyone who has set an edit watch on this file. It will also register you as an editor of the file. You can obtain a list of all editors of a certain file by using Advanced->Show editors. This is equivalent to typing on the command line

cvs editors filenames

An editing session is automatically ended when you commit the affected file. At that moment, an unedit notification gets sent out to all people who have registered a respective watch on the file. Of course, sometimes you may not want to commit the file, but abort the editing session and revert to the previous version of the file. This is done by using Advanced->Unedit. Note that Cervisia will not ask you for confirmation! That means, if you use this menu item, all your work done since you used Advanced->Edit will get lost. Precisely, Cervisia uses the command line

echo y | cvs unedit filenames

So far, we have only the discussed the case where edits and unedits are used voluntarily be the developers. In addition CVS supports a model which enforces the usage of these commands. The responsible command to switch to this model is cvs watch on which we will not explain further because it is mostly used by the administrator of the repository. However, the important point from the developer's point of view is that when the project enforces edits, working copies are checked out readonly. That means you cannot edit a file by default (unless you use tricks like chmod). Only when you use Advanced->Edit, the file becomes writable. It is made readonly again when you commit the file or use Advanced->Unedit.

Cervisia's editor interface helps you with projects that enforce watches also in a different way. If you just started an editor with a readonly file by double-clicking on it or by using File->Edit, you would not be able to 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.

In such a case, it is advisable to check the option Settings->Do cvs edit automatically when necessary. Now, whenever you edit a file by double-clicking it, Cervisia 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 committed files are readonly again.

The development model usually followed when CVS is used is called unreserved checkouts. Each developer has his own sandbox where he can edit files as he likes. If when the watch features - like cvs edit - are used, multiple developers can work on files synchronously. Changes done by a different developer are merged into the local sandbox when an update is performed.

Other revision control systems - like RCS and SourceSafe use a different model. When a developer wants to a edit a file, he has to lock it. Only one developer at a time can a lock a file. When he has finished editing, the lock is released. On the one hand, with this model, conflicts can never happen. On the other hand, two developers can not work on the same file at the same time, even when their changes do not affect each other. This can be a bottleneck. We are not going to discuss the organizational benefits of both approaches. Nevertheless we mention that although CVS has some support for locking, it is not the preferred way of working with CVS. You should not use these features unless you are sure that your project manager allows them.

With Cervisia, you lock files as follows. Select the desired files in the main view. Then choose Advanced->Lock. This runs the command

cvs admin -l filenames

The reverse effect is achieved by using Advanced->Unlock. This runs the command

cvs admin -u filenames

Number of context lines in the diff dialog.  For the diff dialog, Cervisia uses the option -U to diff. This lets diff show only a limited number of lines around each difference region. Here you can set the argument to -U.

Additional options for cvs diff.  Here you can add additional arguments to the diff. A popular example is -b which lets diff ignore changes in the amount of whitespace.

Tab width in diff dialog.  In the diff dialog, tab characters present in your file or in the output of the diff command are expanded into a fixed number of space characters. By default, each tab is replaced by eight spaces, but here you can setup a different number.

External diff frontend.  When you use any of the features which show the diff dialog, like View->Difference to Repository..., Cervisia invokes its internal diff frontend. If you prefer a different one, like Kompare, TkDiff, or xxdiff, you can configure this here.

Start File->Status automatically.  When you check this option, the File->Status command is started whenever you open a sandbox. As this command may need some time and also needs a connection to the server for remote repositories (making it unusable for offline usage), you can set this option separately for local and remote repositories.

Timeout after which a progress dialog appears.  Practically all CVS commands started in a sandbox which belongs to a remote repository need a connection to the CVS server. This is affected by delays from the network connection or a high load on the server. For this reason, for commands like View->Difference to repository... Cervisia opens a dialog which indicates that the command is still running and which allows you to abort it. Furthermore, this dialog is used to show you error messages from CVS. As this dialog may become annoying after some time, it is shown only after a certain timeout which is 4 seconds by default. Here you can change this value.

Default compression level.  The cvs client compresses files and patches when they are transferred over a network. With the command line option -z, the compression level can be set. You can setup Cervisia to use this option by configuring the level here. The value set here is used only as a default; additionally there is a per-repository setting available in Repository->Repositories....

Split main window horizontally.  Cervisia's main window is normally splitted vertically into a window with the file tree and one with the output. Alternatively, you can arrange them horizontally.

Font for protocol window.  This is the font used in the protocol window. This is the window showing the output of the cvs client.

Font for annotate view.  This is the font used in the annotate view.

Font for diff view.  This is the font used in diff dialogs.