Essential CVS/CVS Administration/Troubleshooting
It would be nice if CVS were perfect, but it isn't. There will be times when CVS doesn't work as expected, but with the techniques and information in this chapter, you should be able to fix the most common problems.
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 can't read the repository and the problem doesn't seem to be a networking issue, check the repository permissions. Thankfully, permissions problems are easy to fix. Chapter 6 covers permissions in detail.
CVS is an open source software program, created by a group of programmers rather than a specific company. Because there is no company that created CVS — which means there is no company that gains revenue from selling it — there is no official source of commercial support. If you want commercial support, there are companies in many parts of the world that provide high-quality 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.
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.
When searching the Web for CVS information, you can avoid references to CVS pharmacies or curriculum vitae by using a search string like CVS -pharmacy -resumeor 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 technique is to search for the name of the command (such as "cvs commit") for which you received the error. This may lead to a tutorial, mailing-list archives, or other useful information.
If you believe 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: http://www.cvshome.org/. On Linux or Unix, you can display it with the info cvs command. If CVS does not work the way it is described in the official documentation you get from infocvs, there is a bug in either CVS or the documentation.
Report bugs to the location listed in the BUGS section of infocvs. In the current version (and for the foreseeable future), this location is through the email@example.com 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 infocvs 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.
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. You need to install the CVS source code before you can modify it.
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.
If you are having difficulty connecting to a repository, first check that the repository path is declared correctly. The most common mistake when checking out a new sandbox is to forget to specify the repository path at all. Another common mistake is to forget to specify the connection method if you are using a method other than local or ext.
If you want to examine the data sent to or received from the server, set the CVS_CLIENT_LOG environment variableto a file name. It must be set on the client computer, and the traffic is logged in files in the current working directory named for that filename, with the suffixes .in and .out. For instance, if you set CVS_CLIENT_LOG to cvslog, the traffic is logged to cvslog.in and cvslog.out. (Traffic to the server is logged to cvslog.in, and traffic from the server is logged tocvslog.out.)
The gserver, kserver, andpserver connection methods rely on a server that is started with inetd. inetd sets a limit on the number of connections per unit of time and delays further connections. If you expect heavy use of CVS, you may need to configure inetd to accept more connections per minute. Not doing so may cause connection refused error messages.
Root and Repository File Problems
If you are in an active sandbox and are receiving an error like the one shown in Example 9-2, the Root or Repository file in the CVS subdirectory of the current sandbox directory has become unreadable. Chapter 6 includes an explanation of these files and what they should contain, but the simplest way to correct a problem in a sandbox is to remove and recreate the sandbox. If there are changes in the sandbox files, be sure to preserve them before removing the sandbox.
Example 9-2. Repository undeclared
cvs update: No CVSROOT specified! Please use the `-d' option cvs [update aborted]: or set the CVSROOT environment variable.
Certain changes in a repository or a repository's host environment can cause the Root and Repository files in a sandbox to be out of date. Examples of these changes include a change to the repository computer's hostname, a change to the user's username, and a change in the preferred connection method. The traditional way to manage these changes is to commit and release the sandbox beforehand and create a new sandbox afterward.
If you do not want to create a new sandbox, you can edit the appropriate files in the sandbox. Example 9-3 is a small script that relies on bash and perl to change the hostname in a sandbox Root file automatically.
Example 9-3. Changing the Root files automatically
find ~/cvs/wizzard -name Root | xargs perl -p -i'.bak' -e "s/helit/lat/;"
Misconfigured Access Methods
Some of the access methods require configuration. The pserver , kserver, and gserver methods require configuration at the repository, and the ext, kserver, and gserver methods require configuration at the sandbox. Example 9-4 shows the error that occurs when the pserver method is used but the user does not exist in the repository's user database. Example 9-5 shows the error that occurs when kserver is used but the client is not compiled to support it.
Example 9-4. Pserver misconfiguration
bash-2.05a$ cvs -d :pserver:cvs:/var/lib/cvs checkout wizzard no such user jenn in CVSROOT/passwd
Example 9-5. Kserver misconfiguration
bash-2.05a$ cvs -d :kserver:cvs:/var/lib/cvs checkout wizzard cvs checkout: CVSROOT is set for a kerberos access method but your cvs checkout: CVS executable doesn't support it. cvs [checkout aborted]: Bad CVSROOT: `:kserver:cvs:/var/lib/cvs'.
In addition to checking the configuration of the access method, check that the username you're trying to use exists on the server and has access to the repository project files you are trying to reach.
If you are using the pserver access method, also check that the passwd file in the repository's CVSROOT directory is mapping your CVS username onto an existing system username with the appropriate permission. If you are using Kerberos 4 or the GSS-API with Kerberos 5, ensure that you have a Kerberos username and a current ticket and ensure that the CVS server has its ticket.
Isolating Connectivity Problems
Isolating a problem is a common and useful troubleshooting tactic. If you are having trouble accessing a repository, there may be a problem with the protocol you are using to connect with, the configuration of either CVS or the protocol, or, more rarely, the CVS code. To fix your problem, you need to figure out where it is.
There is a common set of client and server code used by all CVS remote-access methods. The fork connection method can be used to determine that this common CVS code is functioning correctly. To determine whether Kerberos, the GSS-API, rsh, or your rsh replacement are working, you can use a simple service with the same protocol as the method you are having trouble with.
To test whether a connection problem is caused in CVS itself, try using the fork access method to create a sandbox on the same computer as the repository. If this fails, check your repository path and check that the project name you are using is valid. If both are correct, there is a problem in the CVS client and server code that should probably be reported as a bug. Example 9-6 shows what should happen when you test the server with fork.
Example 9-6. Testing the server with fork
jenn@helit:/tmp$ cvs -d :fork:/var/lib/cvs checkout wizzard cvs server: Updating wizzard U wizzard/Changelog U wizzard/INSTALL U wizzard/Makefile U wizzard/README U wizzard/TODO cvs server: Updating wizzard/doc cvs server: Updating wizzard/doc/design . . .
If thefork test shows that your repository path and project name are valid and that the common CVS server is functioning correctly, you can isolate the problem further by testing the access method with a simple program that uses the same protocol. You must do this with the protocol client you are attempting to use with CVS, and you must use the same hostname. Kerberos 4 or 5 can be tested with the Kerberos rsh replacements, and ext or server can be tested with rsh. If ext is used with a replacement for rsh, that replacement should be used in the test. You can test pserver with telnet.
Example 9-7 shows a successful attempt to connect to a host named cvs using the SSH protocol. SSH clients are commonly used as rsh replacements.
Example 9-7. Testing ext
bash-2.05a$ ssh cvs Linux helit 2.4.19-686-smp #1 SMP Thu Aug 8 22:06:13 EST 2002 i686 unknown unknown GNU/ Linux . . . Last login: Mon Nov 11 04:24:55 2002 from 10.0.2.2 jenn@helit:~$
If you are using the ext connection method, you can choose from many programs to manage your connection; however, such a choice can cause problems.
The replacement must not convert line endings, as CVS expects to do that itself. If your replacement converts line endings, CVS is unable to determine where the end of each line is, so the merge methodology fails.
The replacement must accept the following syntax:
program [-b] [-l username] host commands
The -b is optional if you are not using OS/2, but the rest of the syntax is required.
The repository server must be running a server process that can accept the protocol the replacement is using and that can run the commands sent by the rsh-replacement program. To test most of these requirements, you can run a command that uses the full syntax, as shown in Example 9-8.
Example 9-8. Testing ssh for suitability
bash-2.05a$ ssh -l jenn cvs ls /tmp iio makemain wizzard
If you need to pass a command or call an option to your rsh replacement, you can do so by creating a small script and calling that script instead of the replacement program. Example 9-9 shows one such script.
Example 9-9. ssh script
#!/bin/bash exec ssh -i /home/jenn/.RSAkey "$@"
CVS reserves some filenames for its own uses, and other filenames are included in the default ignore list.
If you have a file that CVS appears to be ignoring, check the default ignore list and any cvsignore files in your repository, home directory, or sandbox. The default list is provided in Section 184.108.40.206 of Chapter 6. If the -I! option to a CVS command causes CVS to recognize the file, then you can be sure the file is in a cvsignore list. You can temporarily force CVS to recognize an ignored file by stating it explicitly as a command parameter.
CVS uses CVS and Attic directories in the repository. CVS prevents you from using the filename CVS but permits you to create files or directories called Attic. If you use an Attic directory and look in the repository, the Attic directory has files that don't exist on the trunk from the directory above it, as well as those you are currently using in your sandbox version of the Attic. You should avoid using Attic as a file or directory name.
CVS may ignore a filename with a # or .# prefix, as CVS reserves some files with the prefix.# for its own use. In the sandbox, CVS uses the .# prefix for copies of files it has overwritten during a merge. In the repository, lock files start with #.
Another cause of filename problems is a conflict between the filesystem on a client computer and the filesystem on a repository. For example, filename case is significant in Linux and Unix filesystems, but not in Windows filesystems. If two filenames vary only in case and you are checking them out to a filesystem that ignores case, the second file to be checked out may overwrite the first. This can also cause problems when you attempt to change the case of a file in Windows. Another possible, case-related problem is that if you are disconnected from the network, on an operating system that doesn't consider case relevant, then you cvsremove FiLe and try to cvs add file, CVS may search the pending requests, see that FiLe existed, and perceive cvs add as an unremove.
If CVS is reporting lines as longer or shorter than they should be, there may be a problem with the line-ending conversion from one filesystem to another.
If you are using the ext access method with an rsh replacement, your replacement may be trying to convert line endings. CVS relies on being able to do the conversion itself.
If this is not the problem and the file in question is a text file, you might have binary keyword-expansion mode set for the file. Use the command cvs status filename to show the keyword-expansion mode, and use cvs admin -kkv filename to fix the file in the repository by setting its keyword-expansion mode to the default for text files. If a binary file is corrupted, it might be set as a text file. The command cvs admin -kb filename sets the binary file's keyword-expansion mode correctly, but it might not repair the damage to the local file. To retrieve the original version of the file, use cvs update -r 1.1 -p > filename.
For all access methods except pserver, CVS relies exclusively on the filesystem to manage permissions. Each user must have a username on the repository server, and must have write access to every directory that contains files they will need to commit.
You can control permissions only at a directory level. If a user will need to commit to any file in a directory, she needs read and write access to the whole directory.
Once, I was working on a project where I had to connect to the repository server through an intermediate proxy server. We kept getting permission errors and eventually tracked it to the intermediary. We all had membership in the col group on the client and repository servers, but not on the intermediary. As files passed through the intermediate server, their group membership information was lost, so they were saved in the repository with no group ownership. We corrected this by setting the repository directories' SGID flags on the repository server.
The history and val-tags files in the repository's CVSROOT directory must be writable to all CVS users. The history file can be removed if none of your users use the cvs history command.
The pserver connection method uses a more complicated permission system than the one other connection methods use. The passwd file in the repository's CVSROOT directory can cause a user to have two effective usernames: one that affects only CVS and another that affects the filesystem. If a user has permission within one but not the other, he may be unable to access his project files. For instance, if his CVS username is in the writers file in the CVSROOT directory, CVS attempts to allow him to write to his project files. If, however, his system username is not allowed to write to the project directories, the operating system denies access and CVS is unable to write to the files.
The readers and writers files in the repository's CVSROOT directory are used to set read-only or read-write permission, based the on CVS username. These files must have a newline character after each username, including the last.
CVS removes its lock files when a CVS process completes properly, but processes that are killed can sometimes leave lock files in place. Chapter 6 explains the process of removing lock files and provides an example of the messages CVS displays when a lock file is present.
If you have to wait for valid lock files frequently, you may need to reduce the length of time a lock file is active in the repository. Locks are based on the directory that is being locked, so if you have frequently accessed project directories with many files or large files, you may benefit from splitting them into smaller directories.
If you are waiting for lock files frequently, you can also check whether your system is being overloaded. You may have network trouble, or large checkouts or commits may be overloading your system memory or swap space.