Managing CVS

How we use CVS (maybe this is redundant)

“Checking Out:” Getting a copy of the KDE source

The first stage in using CVS is to make your own copy of the KDE source. This is known as “checking out.” To do this, make sure CVS is installed on your system, and follow these steps (from developer.kde.org):

  1. Install the following file as ~/.cvsrc:

    cvs -z4 -q
    diff -u3 -p
    update -dP
    checkout -P
    

    Please don't use a higher value than -z4. It just creates unnecessary high load on the server which slows down the access for everybody while it certainly does not increase throughput.

    Important

    The update -dP is essential. Without this it won't work.

  2. Execute the following commands (if you are not using the bash shell, substitute the appropriate command for export):

    export
    CVSROOT=:pserver:anonymous@anoncvs.kde.org:/home/kde
    cvs login
    

    Just press Enter if there is a question about a password. If you don't have a .cvspass file in your home directory create one (using touch ~/.cvspass - note the dot in .cvspass) and run cvs login again.

  3. Run cvs co arts kdelibs kdebase other modules where other modules is a list of the other modules you need. arts, kdelibs and kdebase are the minimum you will need to run a KDE desktop. If you are writing documentation for applications which live in any other modules, you will need to add them to other modules in the command above.

Updating Your Sources

Keeping your copy of the sources up-to-date with the repository is as simple as entering the directory of a module you want to update, and entering cvs up. Only the differences between your copy and the repository are downloaded, so this takes less bandwidth than running cvs co, as you did before.

It's a good idea to run cvs up before modifying files, since this helps prevent conflicts (see below).

Running cvs up produces a lot of output. Most of it consists of a letter followed by a filename. The meanings of the most common letters are:

P

The file has been updated to the latest version in the repository. Only the difference between your last copy and the latest version (a patch) was sent.

U

The file has been updated to the latest version in the repository, but a patch wasn't available, so the whole file was sent. This usually means that the file is new since your last update.

M

The file is modified in your private copy. This means you have made changes that haven't yet been committed to the repository.

C

There were changes in both your private copy and the repository, and they conflicted with one another. See the section called “Managing Conflicts and Other Problems” for more information.

There are other letters which might appear: for more information, see the CVS info page.

cvs commit: Making your changes available

Once you have made changes to your private copy of the documentation, you can add these changes to the repository with the cvs commit command. Run cvs commit file... where file... is a list of all the files that you have modified. You will be presented with an editor (the one set in your EDITOR environment variable) in which you should enter a brief log message describing the changes you've made.

In the log file you can use CCMAIL:email address to automatically send a copy of the log message to email address. If the change is a small one (for example, correcting a small number of typos), you can add CVS_SILENT to the log message. This will allow easier filtering for those who read the mailing list to which log messages are sent.

Write something about binary files.

Mention adding new files.

Managing Conflicts and Other Problems

CVS will try to automatically handle merging two sets of changes to a file. For example, take this situation:

  1. You and another writer are both working on a file, index.docbook.

  2. The other writer makes changes to the first half of the file and commits them to the CVS repository.

  3. You make changes to the second half of the file, but do not commit them (yet).

Now, if you run cvs up, cvs will add the changes from the other writer to your private copy, while leaving your changes in the file.

This works fine if two writers have made changes to different parts of the file, but if you make changes to the same part of the file, cvs cannot tell which changes should take precedence. It will therefore mark your file as having conflicts (shown with a C in the output of cvs up), and place markers in the file showing both your version and the version of the other writer. You must then read through the file and edit it to contain only the more appropriate of the two versions.

Another common problem is that you get errors about “sticky tags” when trying to commit a file. If this happens, run cvs up -A and commit again.