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 directory 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 directory.  This is the toplevel directory of the project you want to import. The import starts from this directory 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 directory 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 directory.  The directory under which the module should be checked out. Note that the toplevel directory of the working copy is always created as a directory with the name as the module under the directory given here.

When you start Cervisia, and open a working copy by choosing File->Open Sandbox... you see a hierarchical view of the current directory. 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 directories. 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 subdirectories. 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 directory tree which is equivalent to marking all files in this directory). 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 directory 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 commited, possibly together with other modifications to the project.

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

As a substitute, CVS follows the convention that a directory 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 Directories On Update.

A directory 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 directories 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 layed 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 directory 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 “Customizing various commands”) 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 commited 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 doubleclick the file in question and edit it with your favourite 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:

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 “Customizing various commands”.

Cervisia's annotate view is currently is simple frontend to the respective CVS command. It will be improved beyond these capabilities after the 1.0 release. For a preview, look at the script kdesdk/scripts/cvsblame in the KDE repository.

You can get to the annotate view either by choosing View->Annotate from the main view or from the Browse logs dialog. Then 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.

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.

Cervisia'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, 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 Advanved->Show watchers. Using this menu item will result in a command

cvs watchers filenames

Cervisia'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, 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 commited files are readonly again.

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.