Using command-line CVS to access project source files

Getting started with CVS

If you are participating in a development project on this site, you must use CVS as the versioning control tool for project source files. This the first in a series of three tool documents covering information and commands pertinent to using CVS.

Accessing a project's CVS repository

If you have CVS login access for a project hosted on this site, first you must set the CVSroot to access the project's source code repository. In your shell or terminal client, type:

substituting your login and project information.

If you are only working on one project at a time, you only have to set CVSroot the first time you log in to CVS

If you are participating in more than one project and need to access CVS repositories located on different servers, you need to set the CVSroot for each login session access the correct project's source repository.

To log in to CVS, use the following command:

CVS login

Enter your user password when prompted. This should be the same password associated with your user account on this site.

Getting source files

To get a "working copy" of the latest source files, you must check out the source files, a process which copies the files onto your system. First create a directory on your local machine by typing:

   mkdir my_working_dir (the directory name of your choosing)
   cd my_working_dir

Then, to check out or copy source file from the repository into your newly created local directory, type:

CVS checkout project_name

This top-level module would contain the entire source code tree (that is, the top level directory and any subdirectories) for that part of the project. There is a fairly common module structure for project CVS repositories initially. As the project grows, the project's source "tree" also grows as subdirectories are added to various modules.

To obtain the source code for a particular module called "module-name" within the project named "project_name", specify:

CVS checkout module_name/project_name

More about checking out a working copy of project files

The CVS annotate command

The annotate command displays information about every line in a committed revision of a file.

The general usage of the cvs annotate command, from a CVS working directory is:

cvs annotate [filename]

Where "filename" is the name of one or more versioned files in the current working directory. Annotate produces a tabular output, showing the following information for every line of the file(s).

  1. Last revision affecting the line
  2. Author of and date on which this line was last modified
  3. The actual line of text in the file

Viewing file revision history

Anyone with CVS read permission can view individual file histories to track revision information by typing:

CVS log filename

The result is a display of the file's revision information, starting with the most current revision, and includes such information as the log message, status, working revision number, and repository revision number.

Comparing file revisions

When someone has edited a file, it's a good idea to review the changes by looking at the original file and the revised file. You can look at files in your local copy or in the repository itself.

Comparing file revisions in your local copy

You can use the diff command to see the particulars of a file's modifications between two revisions in your local copy.

To do that, follow these steps:

  1. Get the file revision number with the "CVS log" command.
  2. Run the diff command like this:
    CVS diff -r revision_# -r revision_#

    The entire file contents display with lines from both versions where differences occur marked by revision number.

For more information about using the diff command, see Open Source Development with CVS.

Comparing file revisions in the repository

You can use the rdiff command to see the differences between files in the repository. This can be useful if you are away from the machine where your local copy resides.

To do this, follow these steps:

  1. Get the file revision number with the CVS rlog command.
  2. Run the rdiff command like this:
    cvs -d :pserver:<user>@<host>:/path/to/cvs/repository rdiff -r revision_# -r revision_#

    The entire file contents display with lines from both versions where differences occur marked by revision number.

    Note: To use rdiff, you must provide the CVSROOT of the repository, not the relative path. This is different from commands such as add and commit, which only require the relative path.

For more information about using the rdiff command, see Open Source Development with CVS.

Watching files in the CVS repository

You can turn on the "watch" command to tell CVS that you want to receive notifications about actions taken on a file. To add a current user to the list of people to receive notification of work done on files enter:

CVS watch add -a [action] -l [files]

The -a option specifies what kinds of events CVS should notify the user about. The -a option may appear more than once, or not at all. If omitted, the action defaults to all. An Action can be any one of the following:

The file that you are "watching" has the CVS "edit" command applied to it by another user. For example, when two or more people try to commit a file simultaneously there may be a conflict. Then CVS warns you with the "edit" action that the file is being edited by another user.
The file that you are "watching" has the CVS "unedit" command or the CVS "release" command applied to it. For example, suppose you had been editing a file but later decided to adandon the changes and revert the file to the state it was in before you imposed the "edit" command. Then you apply the "unedit or "release" command to let watchers know that the edited file has either been deleted or reverted to the repository version. If you have deleted the file this command allows CVS update to recreate the file in the repository.
Another user has committed changes to a file you are "watching."
All of the above.
None of the above.

The files and -l option are processed as for the CVS watch commands.

To remove a notification request established using CVS watch add, the arguments are the same:

CVS watch remove -a [action] -l [files]

If the -a option is present, only watches for the specified actions are removed.

When the conditions exist for notification, the users will receive an email from the CollabNet platform server notifying them of the action performed on the files they are watching.