Section 9.1. General Troubleshooting Techniques

9.1. General Troubleshooting Techniques

Most of the CVS error messages are helpful but concise. They usually tell you what is wrong and may contain key words or phrases that lead you toward a resolution to the problem. Few of the error messages actually provide a resolution, however, because usually there are several possible causes of any given problem.

If your problem seems to be confined to a single sandbox, the simplest solution is usually to check out a new sandbox. To save changed files, copy them to the new sandbox before erasing the old sandbox. (If the new sandbox has newer revisions of some files, don't copy over them.)

To fix problems in a single sandbox directory, check the sandbox administrative files in the CVS subdirectory. If a command has been aborted, the administrative files may have been partially changed. Chapter 6 explains the sandbox administrative files.

Many repository problems are caused by permissions errors. If a user (system username) can't read the repository and the problem doesn't seem to be a networking issue, check the repository permissions. The username of the user must be a member of a group with access to the files that they're trying to read. Thankfully, permissions problems are easy to fix. Chapter 6 covers permissions in detail.

9.1.1. Finding Help

CVS is an open source software program that was created by a group of programmers, rather than by a specific company.^[*] Because there is no company that created CVSwhich means that there is no company that gains revenue from selling itthere is no official source of commercial support. Companies in many parts of the world provide high-quality commercial support for open source products. CVS is a widely used version control system, so most of these companies have staff who are familiar with CVS.

^[*] Open source software is explained at http://www.opensource.org.

See the CVS wiki at http://ximbiot.com/cvs/wiki/ and http://ximbiot.com/cvs/wiki/index.php?title=Commercial_Support for a list of some of the commercial companies that provide CVS support.

9.1.1.1. Mail and newsgroups

There are also sources of help on the Internet, such as mailing lists and newsgroups. These are meeting places for people who are familiar with CVS, and for those who need help with it.

The official mailing list is monitored by several CVS developers. Subscribe to the list at http://mail.gnu.org/mailman/listinfo/info-cvs.

The fa.info-cvs and gnu.cvs.help newsgroups were established specifically for CVS. comp.software.config-mgmt is a general newsgroup for software-configuration management, defined in the comp.software.config-mgmt FAQ as:

The management of software development projects with respect to issues such as multiple developers working on the same code at the same time, targeting multiple platforms, supporting multiple versions, and controlling the status of code.

9.1.1.2. The Web

When searching the Web for CVS information, you can avoid references to CVS pharmacies or curriculum vitae by using a search string such as CVS -pharmacy -resume or CVS +version.

When you have an error message you don't understand, you can often find an explanation by pasting the text of the error message into a web search engine. Example 9-1 shows an attempt to retrieve a revision that does not yet exist (at the time, the highest revision of Makefile was 1.7).

Example 9-1. Web searching

 bash-2.05a$ cvs update -r 3.2 Makefile cvs server: Makefile is no longer in the repository 

To search for information on this error, use the search string "is no longer in the repository". This is the longest string that does not contain the name of a file. In many search engines, a quoted string is searched as the phrase, not as the individual words. The results from searching for a string like this often include a series of help requests and answers archived from a technical mailing list.

Another useful search is the name of the command (such as "cvs commit") for which you received the error. Results for this search may lead to a tutorial, mailing-list archives, or other useful information.

9.1.2. Reporting Bugs

If you believe that you've uncovered a bug in the CVS software, you can report that bug to the CVS development team. They can then verify, prioritize, and perhaps fix the bug in a future release of the CVS software.

The first step of reporting a bug is to decide whether the behavior you are experiencing is a bug or whether it is intentional. To do this, read the official documentation for CVS: Version Management with CVS, by Per Cederqvist et al. This document is provided with Linux and Unix distributions and is available at the official CVS web site at http://cvs.nongnu.org. On Linux or Unix, you can display it with the info cvs command. If CVS does not work as described in the official documentation you get from info cvs, there is a bug in either CVS or the documentation.

Report bugs to the location listed in the BUGS section of info cvs. In the current version (and for the foreseeable future), this location is the [e-mail] mailing list. You can subscribe to this mailing list at http://mail.gnu.org/mailman/listinfo/bug-cvs.

When reporting a bug, include the command you used, what you expected the command to do, and what the command actually did. It is also helpful to list the page in info cvs that describes the behavior you expected and to indicate the version of CVS you are using. Be prepared to answer questions about your computer's configuration and your CVS installation.

You can also use the cvsbug program, distributed with CVS, to report a bug to CVS. cvsbug opens an editor, provides a template for you to fill out, and automatically includes some information about your configuration. Once you close the editor, it sends the problem report to the CVS development team.

9.1.3. Making Your Own Changes to CVS

If you want to add new features to CVS or know how to correct a problem, you may want to make your own changes to CVS and run a modified version at your site.

The functions for most CVS commands are in the src subdirectory of the CVS source code, in files named after the command names. For example, the add command is implemented by the add.c file. Not all commands follow this pattern. The export command is in the checkout.c file, as it uses most of the same code, and both export and checkout use functions in update.c.

If you wish to submit your changes for inclusion in future versions of CVS, read the HACKING and DEVEL-CVS files in the CVS source code directory. The HACKING file also contains useful advice on CVS coding standards.