1@c --------------------------------------------------------- 2@node Tips And Troubleshooting 3@unnumbered Tips And Troubleshooting 4 5I've said in earlier chapters that CVS is not "black box" software. 6Black boxes don't let you peek inside; they don't give you internal 7access so that you can fix (or break) things. The premise is that the 8black box usually doesn't need to be fixed. Most of the time, the 9software should work perfectly, so users don't need internal access. 10But when black boxes do fail, they tend to fail completely. Any problem 11at all is a showstopper, because there aren't many options for repair. 12 13CVS is more like a perfectly transparent box -- except without the box. 14Its moving parts are exposed directly to the environment, not 15hermetically sealed off, and bits of that environment (unexpected file 16permissions, interrupted commands, competing processes, whatever) can 17sometimes get inside the mechanism and gum up the gears. But even 18though CVS does not always work perfectly, it rarely fails completely, 19either. It has the advantage of graceful degradation; the degree to 20which it doesn't work is usually proportional to the number and severity 21of problems in its environment. If you know enough about what CVS is 22trying to do -- and how it's trying to do it -- you'll know what to do 23when things go wrong. 24 25Although I can't list all of the problems that you might encounter, I've 26included some of the more common ones here. This chapter is divided 27into two sections: The first describes those parts of the environment to 28which CVS is most sensitive (mainly repository permissions and the 29working copy administrative area), and the second describes some of the 30most frequently encountered problems and their solutions. By seeing how 31to handle these common situations, you will get a feeling for how to 32approach any unexpected problem in CVS. 33 34@menu 35* The Usual Suspects:: Things that often cause trouble. 36* General Troubleshooting Tips:: General diagnostic techniques. 37* Some Real Life Problems (With Solutions):: A compendium of actual problems. 38@end menu 39 40@c --------------------------------------------------------------- 41@node The Usual Suspects 42@section The Usual Suspects 43 44As a CVS administrator (read "field doctor"), you will find that 90 45percent of your users' problems are caused by inconsistent working 46copies, and the other 90 percent by incorrect repository permissions. 47Therefore, before looking at any specific situations, I'll give a quick 48overview of the working copy administrative area and review a few 49important things about repository permissions. 50 51@menu 52* The Working Copy Administrative Area:: 53* Repository Permissions:: 54@end menu 55 56@c ---------------------------------------------------------------- 57@node The Working Copy Administrative Area 58@subsection The Working Copy Administrative Area 59 60You've already seen the basics of working copy structure in @ref{An 61Overview of CVS}; in this section, we'll go into a bit more detail. 62Most of the details concern the files in the CVS/ administrative 63subdirectories. You already know about Entries, Root, and Repository, 64but the CVS/ subdirectory can also contain other files, depending on the 65circumstances. I'll describe those other files here, partly so they 66don't surprise you when you encounter them, and partly so you can fix 67them if they ever cause trouble. 68 69@heading @file{CVS/Entries.Log} 70 71Sometimes, a file named @file{CVS/Entries.Log} will mysteriously appear. 72The sole purpose of this file is to temporarily cache minor changes to 73CVS/Entries, until some operation significant enough to be worth 74rewriting the entire Entries file comes along. CVS has no ability to 75edit the Entries file in place; it must read the entire file in and 76write it back out to make any change. To avoid this effort, CVS 77sometimes records small changes in Entries.Log, until the next time it 78needs to rewrite Entries. 79 80The format of Entries.Log is like Entries, except for an extra letter at 81the beginning of each line. @code{A} means that the line is to be added 82to the main Entries file, and @code{R} means it is to be removed. 83 84For the most part, you can ignore Entries.Log; it's rare that a human 85has to understand the information it contains. However, if you're 86reading over an Entries file to debug some problem in a working copy, 87you should also examine Entries.Log. 88 89@heading @file{CVS/Entries.Backup} 90 91The CVS/Entries.Backup file is where CVS actually writes out a new 92Entries file, before renaming it to @file{Entries} (similar to the way 93it writes to temporary RCS files in the repository and then moves them 94to their proper name when they're complete). Because it becomes Entries 95when it's complete, you'll rarely see an Entries.Backup file; if you do 96see one, it probably means CVS got interrupted in the middle of some 97operation. 98 99@heading @file{CVS/Entries.Static} 100 101If the CVS/Entries.Static file exists, it means that the entire 102directory has not been fetched from the repository. (When CVS knows a 103working directory is in an incomplete state, it will not bring 104additional files into that directory.) 105 106The Entries.Static file is present during checkouts and updates and 107removed immediately when the operation is complete. If you see 108Entries.Static, it means that CVS was interrupted, and its presence 109prevents CVS from creating any new files in the working copy. (Often, 110running @w{@code{cvs update -d}} solves the problem and removes 111Entries.Static.) 112 113The absence of Entries.Static does not necessarily imply that the 114working copy contains all of the project's files. Whenever a new 115directory is created in the project's repository, and someone updates 116their working copy without passing the -d flag to update, the new 117directory will not be created in the working copy. Locally, CVS is 118unaware that there is a new directory in the repository, so it goes 119ahead and removes the Entries.Static file when the update is complete, 120even though the new directory is not present in the working copy. 121 122@heading @file{CVS/Tag} 123 124If the CVS/Tag file is present, it names a tag associated, in some 125sense, with the directory. I say "in some sense" because, as you know, 126CVS does not actually keep any revision history for directories and, 127strictly speaking, cannot attach tags to them. Tags are attached to 128regular files only or, more accurately, to particular revisions in 129regular files. 130 131However, if every file in a directory is on a particular tag, CVS likes 132to think of the entire directory as being on the tag, too. For example, 133if you were to check out a working copy on a particular branch: 134 135@example 136floss$ cvs co -r Bugfix_Branch_1 137@end example 138 139and then add a file inside it, you'd want the new file's initial 140revision to be on that branch, too. For similar reasons, CVS also needs 141to know if the directory has a nonbranch sticky tag or date set on it. 142 143Tag files contain one line. The first character on the line is a 144single-letter code telling what kind of tag it is, and the rest of the 145line is the tag's name. Currently, CVS uses only these three 146single-letter codes: 147 148@itemize 149 150@item 151T -- A branch tag 152 153@item 154N -- A nonbranch (regular) tag 155 156@item 157D -- A sticky date, which occurs if a command such as 158 159@example 160floss$ cvs checkout -D 1999-05-15 myproj 161@end example 162 163or 164 165@example 166floss$ cvs update -D 1999-05-15 myproj 167@end example 168 169is run. 170 171@end itemize 172 173(If you see some other single-letter code, it just means that CVS has 174added a new tag type since this chapter was written.) 175 176You should not remove the Tag file manually; instead, use @w{@code{cvs 177update -A}}. 178 179@heading Rarities 180 181There are a few other files you may occasionally find in a CVS/ subdirectory: 182 183@itemize 184@item CVS/Checkin.prog, CVS/Update.prog 185@item CVS/Notify, CVS/Notify.tmp 186@item CVS/Base/, CVS/Baserev, CVS/Baserev.tmp 187@item CVS/Template 188@end itemize 189 190These files are usually not the cause of problems, so I'm just listing 191them (see @ref{CVS Reference} for their full descriptions). 192 193@c ------------------------------------------------------------------- 194@heading Portability And Future Extension 195 196As features are added to CVS, new files (not listed here) may appear in 197working copy administrative areas. As new files are added, they'll 198probably be documented in the Cederqvist manual, in the node 199@cite{Working Directory Storage}. You can also start looking in 200src/cvs.h in the source distribution, if you prefer to learn from code. 201 202Finally, note that all CVS/* files -- present and future -- use whatever 203line-ending convention is appropriate for the working copy's local 204system (for example, LF for Unix or CRLF for Windows). This means that 205if you transport a working copy from one kind of machine to the other, 206CVS won't be able to handle it (but then, you'd have other problems, 207because the revision-controlled files themselves would have the wrong 208line-end conventions for their new location). 209 210@c -------------------------------------------------------- 211@node Repository Permissions 212@subsection Repository Permissions 213 214CVS does not require any particular repository permission scheme -- it 215can handle a wide variety of permission arrangements. However, to avoid 216getting confusing behaviors, you should make sure your repository setup 217meets at least the following criteria: 218 219@itemize 220 221@item 222If a user wants any kind of access at all -- even read-only access -- to 223a given subdirectory of the repository, she usually needs file 224system-level write permission to that subdirectory. This is necessary 225because CVS creates temporary lock files in the repository to ensure 226data consistency. Even read-only operations (such as checkout or 227update) create locks, to signal that they need the data to stay in one 228state until they're done. 229 230As noted in @ref{Repository Administration}, you can get around this 231writeability requirement by setting the LockDir parameter in 232CVSROOT/config, like this: 233 234@example 235LockDir=/usr/local/cvslocks 236@end example 237 238Of course, then you would need to make sure the directory 239/usr/local/cvslocks is writeable by all CVS users. Either way, most CVS 240operations, including read-only ones, are going to require a writeable 241directory somewhere. By default, that directory is the project's 242repository; if you're very security conscious, you can change it to be 243somewhere else. 244 245@item 246Make sure the CVSROOT/history file is world-writeable (if it exists at 247all). If the history file exists, most CVS operations attempt to append 248a record to it; if the attempt fails, the operation exits with an error. 249 250Unfortunately (and inexplicably), the history file is not born 251world-writeable when you create a new repository with cvs init. At 252least with the current version of CVS, you should explicitly change its 253permissions after you create a new repository (or just remove it, if you 254want to disable history logging entirely). 255 256(This problem may go away -- I just now submitted a patch to the CVS 257maintainers that makes the history file world-writeable when you 258initialize a new repository. So perhaps if you get a more recent 259version of CVS than the one available now (September 1999), it won't be 260a problem for you.) 261 262@item 263For security purposes, you almost certainly want to make sure that most 264CVS users do not have Unix-level write access to the CVSROOT directory 265in the repository. If someone has checkin access to CVSROOT, they can 266edit commitinfo, loginfo, or any of the other trigger files to invoke a 267program of their choice -- they could even commit a new program if the 268one they want isn't on the system already. Therefore, you should assume 269that anyone who has commit access to CVSROOT is able to run arbitrary 270commands on the system. 271 272@end itemize 273 274@c ------------------------------------------------------- 275@node General Troubleshooting Tips 276@section General Troubleshooting Tips 277 278The bulk of this chapter is organized into a series of questions and 279answers, similar to an Internet FAQ (Frequently Asked Questions) 280document. These are all based on actual CVS experiences. But before we 281look at individual cases, let's take a moment to consider CVS 282troubleshooting from a more general point of view. 283 284The first step in solving a CVS problem is usually to determine whether 285it's a working copy or repository problem. The best technique for doing 286that, not surprisingly, is to see if the problem occurs in working 287copies other than the one where it was first noticed. If it does, it's 288likely a repository issue; otherwise, it's probably just a local issue. 289 290Working copy problems tend to be encountered more frequently, not 291because working copies are somehow less reliable than repositories, but 292because each repository usually has many working copies. Although most 293working copy knots can be untied with enough patience, you may 294occasionally find it more time-efficient simply to delete the working 295copy and check it out again. 296 297Of course, if checking out again takes too long, or there is 298considerable uncommitted state in the working copy that you don't want 299to lose, or if you just want to know what's wrong, it's worth digging 300around to find the cause of the problem. When you start digging around, 301one of the first places to look is in the CVS/ subdirectories. Check 302the file contents and the file permissions. Very occasionally, the 303permissions can mysteriously become read-only or even unreadable. (I 304suspect this is caused by users accidentally mistyping Unix commands 305rather than any mistake on CVS's part.) 306 307Repository problems are almost always caused by incorrect file and 308directory permissions. If you suspect a problem may be due to bad 309repository permissions, first find out the effective repository user ID 310of the person who's having the trouble. For all local and most remote 311users, this is either their regular username or the username they 312specified when they checked out their working copy. If they're using 313the pserver method with user-aliasing (see the section @ref{Anonymous 314Access} in @ref{Repository Administration}), the effective user ID is 315the one on the right in the CVSROOT/passwd file. Failure to discover 316this early on can cause you to waste a lot of time debugging the wrong 317thing. 318 319And now, without further ado... 320 321@c --------------------------------------------------------------- 322@node Some Real Life Problems (With Solutions) 323@section Some Real Life Problems (With Solutions) 324 325All of these situations are ones I've encountered in my real-life 326adventures as a CVS troubleshooter (plus a few items that are not really 327problems, just questions that I've heard asked so often that they may as 328well be answered here). The list is meant to be fairly comprehensive, 329and it may repeat material you've seen in earlier chapters. 330 331The situations are listed according to how frequently they seem to 332arise, with the most common ones first. 333 334@menu 335* CVS says it is waiting for a lock; what does that mean?:: 336* CVS claims a file is failing Up-To-Date check; what do I do?:: 337* The pserver access method is not working:: 338* The pserver access method is STILL not working:: 339* My commits seem to happen in pieces instead of atomically:: 340* CVS keeps changing file permissions; why does it do that?:: 341* CVS on Windows complains it cannot find my .cvspass file; why?:: 342* My working copy is on several different branches; help?:: 343* When I do export -d I sometimes miss recent commits:: 344* I get an error about val-tags; what should I do?:: 345* I am having problems with sticky tags; how do I get rid of them?:: 346* Checkouts/updates exit with error saying cannot expand modules:: 347* I cannot seem to turn off watches:: 348* My binary files are messed up:: 349* CVS is not doing line-end conversion correctly:: 350* I need to remove a subdirectory in my project; how do I do it?:: 351* Can I copy .cvspass files or portions of them?:: 352* I just committed some files with the wrong log message:: 353* I need to move files around without losing revision history:: 354* How can I get a list of all tags in a project?:: 355* How can I get a list of all projects in a repository?:: 356* Some commands fail remotely but not locally; how should I debug?:: 357* I do not see my problem covered in this chapter:: 358* I think I have discovered a bug in CVS; what do I do?:: 359* I have implemented a new feature for CVS; to whom do I send it?:: 360* How can I keep up with changes to CVS?:: 361@end menu 362 363@c --------------------------------------------------------------------- 364@node CVS says it is waiting for a lock; what does that mean? 365@subsection CVS says it is waiting for a lock; what does that mean? 366 367If you see a message like this 368 369@example 370cvs update: [22:58:26] waiting for qsmith's lock in /usr/local/newrepos/myproj 371@end example 372 373it means you're trying to access a subdirectory of the repository that 374is locked by some other CVS process at the moment. A process is being 375run in that directory so it may not be in a consistent state for other 376CVS processes to use. 377 378However, if the wait message persists for a long time, it probably means 379that a CVS process failed to clean up after itself, for whatever reason. 380It can happen when CVS dies suddenly and unexpectedly, say, due to a 381power failure on the repository machine. 382 383The solution is to remove the lock files by hand from the repository 384subdirectory in question. Go into that part of the repository and look 385for files named @file{#cvs.lock} or that begin with @file{#cvs.wfl} or 386@file{#cvs.rfl}. Compare the file's timestamps with the start times of 387any currently running CVS processes. If the files could not possibly 388have been created by any of those processes, it's safe to delete them. 389The waiting CVS processes eventually notice when the lock files are gone 390-- this should take about 30 seconds -- and allow the requested 391operation to proceed. 392 393See the node @cite{Locks} in the Cederqvist manual for more details. 394 395@c --------------------------------------------------------------------- 396@node CVS claims a file is failing Up-To-Date check; what do I do? 397@subsection CVS claims a file is failing Up-To-Date check; what do I do? 398 399Don't panic -- it just means that the file has changed in the repository 400since the last time you checked it out or updated it. 401 402Run @w{@code{cvs update}} on the file to merge in the changes from the 403repository. If the received changes conflict with your local changes, 404edit the file to resolve the conflict. Then try your commit again -- it 405will succeed, barring the possibility that someone committed yet another 406revision while you were busy merging the last changes. 407 408@c --------------------------------------------------------------------- 409@node The pserver access method is not working 410@subsection The pserver access method is not working 411 412The most common, less obvious cause of this problem is that you forgot 413to list the repository using an @code{--allow-root} option in your inetd 414configuration file. 415 416Recall this example /etc/inetd.conf line from @ref{Repository 417Administration}: 418 419@example 420cvspserver stream tcp nowait root /usr/local/bin/cvs cvs \ 421 --allow-root=/usr/local/newrepos pserver 422@end example 423 424(In the actual file, this is all one long line, with no backslash.) 425 426The @code{--allow-root=/usr/local/newrepos} portion is a security 427measure, to make sure that people can't use CVS to get pserver access to 428repositories that are not supposed to be served remotely. Any 429repository intended to be accessible via pserver must be mentioned in an 430@code{--allow-root}. You can have as many different @code{--allow-root} 431options as you need for all of your system's repositories (or anyway, as 432many as you want until you bump up against your inetd's argument limit). 433 434See @ref{Repository Administration} for more details on setting up the 435password-authenticating server. 436 437@c --------------------------------------------------------------------- 438@node The pserver access method is STILL not working 439@subsection The pserver access method is STILL not working 440 441Okay, if the problem is not a missing @code{--allow-root}, here are a 442few other possibilities: 443 444@itemize 445 446@item 447The user has no entry in the CVSROOT/passwd file, and the CVSROOT/config 448file has SystemAuth=no so CVS will not fall back on the system password 449file (or SystemAuth=yes, but the system password file has no entry for 450this user either). 451 452@item 453The user has an entry in the CVSROOT/passwd file, but there is no user 454by that name on the system, and the CVSROOT/passwd entry does not map 455the user to any valid system username. 456 457@item 458The password is wrong (but CVS is usually pretty good about informing 459the user of this, so that's probably not the answer). 460 461@item 462Everything is set up correctly with the passwd files and in 463/etc/inetd.conf, but you forgot an entry like this in /etc/services: 464 465@example 466cvspserver 2401/tcp 467@end example 468 469so inetd is not even listening on that port to pass connections off to 470CVS. 471 472@end itemize 473 474@c --------------------------------------------------------------------- 475@node My commits seem to happen in pieces instead of atomically 476@subsection My commits seem to happen in pieces instead of atomically 477 478That's because CVS commits happen in pieces, not atomically. :-) 479 480More specifically, CVS operations happen directory by directory. When 481you do a commit (or an update, or anything else, for that matter) 482spanning multiple directories, CVS locks each corresponding repository 483directory in turn while it performs the operation for that directory. 484 485For small- to medium-sized projects, this is rarely a problem -- CVS 486manages to do its thing in each directory so quickly that you never 487notice the nonatomicity. Unfortunately, in large projects, scenarios 488like the following can occur (imagine this taking place in a project 489with at least two deep, many-filed subdirectories, A and B): 490 491@enumerate 492 493@item 494User qsmith starts a commit, involving files from both subdirectories. 495CVS commits the files in B first (perhaps because qsmith specified the 496directories on the command line in that order). 497 498@item 499User jrandom starts a cvs update. The update, for whatever reason, 500starts with working copy directory A (CVS makes no guarantees about the 501order in which it processes directories or files, if left to its own 502devices). Note that there is no locking contention, because qsmith is 503not active in A yet. 504 505@item 506Then, qsmith's commit finishes B, moves on to A, and finishes A. 507 508@item 509Finally, jrandom's update moves on to B and finishes it. 510 511@end enumerate 512 513Clearly, when this is all over, jrandom's working copy reflects qsmith's 514changes to B but not A. Even though qsmith intended the changes to be 515committed as a single unit, it didn't happen that way. Now jrandom's 516working copy is in a state that qsmith never anticipated. 517 518The solution, of course, is for jrandom to do another cvs update to 519fetch the uncaught changes from qsmith's commit. However, that assumes 520that jrandom has some way of finding out in the first place that he only 521got part of qsmith's changes. 522 523There's no easy answer to this quandary. You simply have to hope that 524the inconsistent state of the working copy will somehow become apparent 525(maybe the software won't build, or jrandom and qsmith will have a 526conversation that's confusing until they realize what must have 527happened). 528 529CVS's failure to provide @emph{atomic} transaction guarantees is widely 530considered a bug. The only reason that locks are not made at the top 531level of the repository is that this would result in intolerably 532frequent lock contentions for large projects with many developers. 533Therefore, CVS has chosen the lesser of two evils, reducing the 534contention frequency but allowing the possibility of interleaved reads 535and writes. Someday, someone may modify CVS (say, speeding up 536repository operations) so that it doesn't have to choose between two 537evils; until then, we're stuck with nonatomic actions. 538 539For more information, see the node @cite{Concurrency} in the Cederqvist 540manual. 541 542@c --------------------------------------------------------------------- 543@node CVS keeps changing file permissions; why does it do that? 544@subsection CVS keeps changing file permissions; why does it do that? 545 546In general, CVS doesn't do a very good job of preserving permissions on 547files. When you import a project and then check it out, there is no 548guarantee that the file permissions in the new working copy will be the 549same as when the project was imported. More likely, the working copy 550files will be created with the same standard permissions that you 551normally get on newly created files. 552 553However, there is at least one exception. If you want to store 554executable shell scripts in the project, you can keep them executable in 555all working copies by making the corresponding repository file 556executable: 557 558@example 559floss$ ls -l /usr/local/newrepos/someproj 560total 6 561-r--r--r-- 1 jrandom users 630 Aug 17 01:10 README.txt,v 562-r-xr-xr-x 1 jrandom users 1041 Aug 17 01:10 scrub.pl,v* 563-r--r--r-- 1 jrandom users 750 Aug 17 01:10 hello.c,v 564@end example 565 566Notice that although the file is executable, it is still read-only, as 567all repository files should be (remember that CVS works by making a 568temporary copy of the RCS file, doing everything in the copy, and then 569replacing the original with the copy when ready). 570 571When you import or add an executable file, CVS preserves the executable 572bits, so if the permissions were correct from the start, you have 573nothing to worry about. However, if you accidentally add the file 574before making it executable, you must go into the repository and 575manually set the RCS file to be executable. 576 577The repository permissions always dominate. If the file is 578nonexecutable in the repository, but executable in the working copy, the 579working copy file will also be nonexecutable after you do an update. 580Having your files' permissions silently change can be extremely 581frustrating. If this happens, first check the repository and see if you 582can solve it by setting the appropriate permissions on the corresponding 583RCS files. 584 585A feature called @code{PreservePermissions} has recently been added to 586CVS that may alleviate some of these problems. However, using this 587feature can cause other unexpected results (which is why I'm not 588recommending it unconditionally here). Make sure you read the nodes 589@cite{config} and @cite{Special Files} in the Cederqvist before putting 590@code{PreservePermissions=yes} in CVSROOT/config. 591 592@c --------------------------------------------------------------------- 593@node CVS on Windows complains it cannot find my .cvspass file; why? 594@subsection CVS on Windows complains it cannot find my .cvspass file; why? 595 596For pserver connections, CVS on the client side tries to find the 597.cvspass file in your home directory. Windows machines don't have a 598natural "home" directory, so CVS consults the environment variable 599@code{%HOME%}. However, you have to be very careful about how you set 600HOME. This will work: 601 602@example 603set HOME=C: 604@end example 605 606This will not: 607 608@example 609set HOME=C:\ 610@end example 611 612That extra backslash is enough to confuse CVS, and it will be unable to 613open @file{C:\\.cvspass}. 614 615So, the quick and permanent solution is to put 616 617@example 618set HOME=C: 619@end example 620 621into your autoexec.bat and reboot. CVS pserver should work fine after 622that. 623 624@c --------------------------------------------------------------------- 625@node My working copy is on several different branches; help? 626@subsection My working copy is on several different branches; help? 627 628You mean different subdirectories of your working copy somehow got on 629different branches? You probably ran updates with the -r flag, but from 630places other than the top level of the working copy. 631 632No big deal. If you want to return to the trunk, just run this 633 634@example 635cvs update -r HEAD 636@end example 637 638or this 639 640@example 641cvs update -A 642@end example 643 644from the top directory. Or, if you want to put the whole working copy 645on one of the branches, do this: 646 647@example 648cvs update -r Branch_Name 649@end example 650 651There's nothing necessarily wrong with having one or two subdirectories 652of your working copy on a different branch than the rest of it, if you 653need to do some temporary work on that branch just in those locations. 654However, it's usually a good idea to switch them back when you're done 655-- life is much less confusing when your whole working copy is on the 656same line of development. 657 658@c ------------------------------------------------------------------------ 659@node When I do export -d I sometimes miss recent commits 660@subsection When I do export -d I sometimes miss recent commits 661 662This is due to a clock difference between the repository and local 663machines. You can solve it by resetting one or both of the clocks, or 664specifying a different date as the argument to -D. It's perfectly 665acceptable to specify a date in the future (such as -D tomorrow), if 666that's what it takes to compensate for the time difference. 667 668@c --------------------------------------------------------------------- 669@node I get an error about val-tags; what should I do? 670@subsection I get an error about val-tags; what should I do? 671 672If you see an error like this: 673 674@example 675cvs [export aborted]: cannot write /usr/local/myproj/CVSROOT/val-tags: \ 676 Operation not permitted 677@end example 678 679it means the user CVS is running as does not have permission to write to 680the CVSROOT/val-tags file. This file stores valid tag names, to give 681CVS a fast way to determine what tags are valid. Unfortunately, CVS 682sometimes modifies this file even for operations that are read-only with 683respect to the repository, such as checking out a project. 684 685This is a bug in CVS and may be fixed by the time you read this. Until 686then, the solution is either to make val-tags world-writeable or, 687failing that, to remove it or change its ownership to the user running 688the CVS operation. (You'd think just changing the permissions would be 689enough, but on several occasions I've had to change the ownership, too.) 690 691@c --------------------------------------------------------------------- 692@node I am having problems with sticky tags; how do I get rid of them? 693@subsection I am having problems with sticky tags; how do I get rid of them? 694 695Various CVS operations cause the working copy to have a @dfn{sticky 696tag}, meaning a single tag that corresponds to each revision for each 697file (in the case of a branch, the sticky tag is applied to any new 698files added in the working copy). You get a sticky tagged working area 699whenever you check out or update by tag or date, for example: 700 701@example 702floss$ cvs update -r Tag_Name 703@end example 704 705or 706 707@example 708floss$ cvs checkout -D '1999-08-16' 709@end example 710 711If a date or a nonbranch tag name is used, the working copy will be a 712frozen snapshot of that moment in the project's history -- so naturally 713you will not be able to commit any changes from it. 714 715To remove a sticky tag, run update with the -A flag 716 717@example 718floss$ cvs update -A 719@end example 720 721which clears all the sticky tags and updates each file to its most 722recent trunk revision. 723 724@c --------------------------------------------------------------------- 725@node Checkouts/updates exit with error saying cannot expand modules 726@subsection Checkouts/updates exit with error saying cannot expand modules 727 728This is just a case of a bad error message in CVS; probably someone will 729get around to fixing it sooner or later, but meanwhile it may bite you. 730The error message looks something like this: 731 732@example 733floss$ cvs co -d bwf-misc user-space/bwf/writings/misc 734cvs server: cannot find module `user-space/bwf/writings/misc' - ignored 735cvs [checkout aborted]: cannot expand modules 736@end example 737 738CVS appears to be saying that there's something wrong with the 739CVSROOT/modules file. However, what's really going on is a permission 740problem in the repository. The directory I'm trying to check out isn't 741readable, or one of its parents isn't readable. In this case, it was a 742parent: 743 744@example 745floss$ ls -ld /usr/local/cvs/user-space/bwf 746 747drwx------ 19 bwf users 1024 Aug 17 01:24 bwf/ 748@end example 749 750Don't let that egregiously wrong error message fool you -- this is a 751repository permission problem. 752 753@c --------------------------------------------------------------------- 754@node I cannot seem to turn off watches 755@subsection I cannot seem to turn off watches 756 757You probably did 758 759@example 760floss$ cvs watch remove 761@end example 762 763on all the files, but forgot to also do: 764 765@example 766floss$ cvs watch off 767@end example 768 769A hint for diagnosing watch problems: Sometimes it can be immensely 770clarifying to just go into the repository and examine the CVS/fileattr 771files directly. See @ref{Repository Administration} for more 772information about them. 773 774@c --------------------------------------------------------------------- 775@node My binary files are messed up 776@subsection My binary files are messed up 777 778Did you remember to use -kb when you added them? If not, CVS may have 779performed line-end conversion or RCS keyword substitution on them. The 780easiest solution is usually to mark them as binary 781 782@example 783floss$ cvs admin -kb foo.gif 784@end example 785 786and then commit a fixed version of the file. CVS will not corrupt the 787new commit or any of the commits thereafter, because it now knows the 788file is binary. 789 790@c --------------------------------------------------------------------- 791@node CVS is not doing line-end conversion correctly 792@subsection CVS is not doing line-end conversion correctly 793 794If you're running the CVS client on a non-Unix platform and are not 795getting the line-end conventions that you want in some working copy 796files, it's usually because they were accidentally added with -kb when 797they shouldn't have been. This can be fixed in the repository with, 798believe it or not, the command: 799 800@example 801floss$ cvs admin -kkv FILE 802@end example 803 804The -kkv means to do normal keyword substitution and implies normal 805line-end conversions as well. (Internally, CVS is a bit confused about 806the difference between keyword substitution and line-end conversion. 807This confusion is reflected in the way the -k options can control both 808parameters.) 809 810Unfortunately, that admin command only fixes the file in the repository 811-- your working copy still thinks the file is binary. You can hand edit 812the CVS/Entries line for that file, removing the -kb, but that won't 813solve the problem for any other working copies out there. 814 815@c --------------------------------------------------------------------- 816@node I need to remove a subdirectory in my project; how do I do it? 817@subsection I need to remove a subdirectory in my project; how do I do it? 818 819Well, you can't exactly remove the subdirectory, but you can remove all 820of the files in it (first remove them, then cvs remove them, and then 821commit). Once the directory is empty, people can have it automatically 822pruned out of their working copies by passing the -P flag to update. 823 824@c --------------------------------------------------------------------- 825@node Can I copy .cvspass files or portions of them? 826@subsection Can I copy .cvspass files or portions of them? 827 828Yes, you can. You can copy @file{.cvspass} files from machine to 829machine, and you can even copy individual lines from one .cvspass file 830to another. For high-latency servers, this may be faster than running 831cvs login from each working copy machine. 832 833Remember that if you transport a .cvspass file between two machines with 834different line-ending conventions, it probably won't work (of course, 835you can probably do the line-end conversion manually without too much 836trouble). 837 838@c --------------------------------------------------------------------- 839@node I just committed some files with the wrong log message 840@subsection I just committed some files with the wrong log message 841 842You don't need to hand-edit anything in the repository to solve this. 843Just run admin with the -m flag. Remember to have no space between -m 844and its argument, and to quote the replacement log message as you would 845a normal one: 846 847@example 848floss$ cvs admin -m1.17:'I take back what I said about the customer.' hello.c 849@end example 850 851@c --------------------------------------------------------------------- 852@node I need to move files around without losing revision history 853@subsection I need to move files around without losing revision history 854 855In the repository, copy (don't move) the RCS files to the desired new 856location in the project. They must remain in their old locations as 857well. Then, in a working copy, do: 858 859@example 860floss$ rm oldfile1 oldfile2 ... 861floss$ cvs remove oldfile1 oldfile2 ... 862floss$ cvs commit -m ��removed from here�� oldfile1 oldfile2 ... 863@end example 864 865When people do updates after that, CVS correctly removes the old files 866and brings the new files into the working copies just as though they had 867been added to the repository in the usual way (except that they'll be at 868unusually high revision numbers for supposedly new files). 869 870@c --------------------------------------------------------------------- 871@node How can I get a list of all tags in a project? 872@subsection How can I get a list of all tags in a project? 873 874Currently, there is no convenient way to do this in CVS. The lack is 875sorely felt by all users, and I believe work is under way to make this 876feature available. By the time you read this, a @w{@code{cvs tags}} 877command or something similar may be available. 878 879Until then, there are workarounds. You can run cvs log -h and read the 880sections of the output following the header @code{symbolic names:}. Or, 881if you happen to be on the repository machine, you can just look at the 882beginnings of some of the RCS files directly in the repository. All of 883the tags (branches and nonbranches) are listed in the @code{symbols} 884field: 885 886@example 887floss$ head /usr/local/newrepos/hello.c,v 888head 2.0; 889access; 890symbols 891 Release_1_0:1.22 892 Exotic_Greetings-2:1.21 893 merged-Exotic_Greetings-1:1.21 894 Exotic_Greetings-1:1.21 895 merged-Exotic_Greetings:1.21 896 Exotic_Greetings-branch:1.21.0.2 897 Root-of-Exotic_Greetings:1.21 898 start:1.1.1.1 899 jrandom:1.1.1; 900locks; strict; 901comment @@ * @@; 902@end example 903 904@c --------------------------------------------------------------------- 905@node How can I get a list of all projects in a repository? 906@subsection How can I get a list of all projects in a repository? 907 908As with getting a list of tags, this is not implemented in the most 909current version of CVS, but it's highly likely that it will be 910implemented soon. I imagine the command will be called cvs list with a 911short form of cvs ls, and it probably will both parse the modules file 912and list the repository subdirectories. 913 914In the meantime, examining the CVSROOT/modules file (either directly or 915by running cvs checkout -c) is probably your best bet. However, if no 916one has explicitly made a module for a particular project, it won't show 917up there. 918 919@c --------------------------------------------------------------------- 920@node Some commands fail remotely but not locally; how should I debug? 921@subsection Some commands fail remotely but not locally; how should I debug? 922 923Sometimes there's a problem in the communication between the client and 924the server. If so, it's a bug in CVS, but how would you go about 925tracking down such a thing? 926 927CVS gives you a way to watch the protocol between the client and server. 928Before you run the command on the local (working copy) machine, set the 929environment variable @code{CVS_CLIENT_LOG}. Here's how in Bourne shell 930syntax: 931 932@example 933floss$ CVS_CLIENT_LOG=clog; export CVS_CLIENT_LOG 934@end example 935 936Once that variable is set, CVS will record all communications between 937client and server in two files whose names are based on the variable's 938value: 939 940@example 941floss$ ls 942CVS/ README.txt a-subdir/ b-subdir/ foo.gif hello.c 943floss$ cvs update 944? clog.in 945? clog.out 946cvs server: Updating . 947cvs server: Updating a-subdir 948cvs server: Updating a-subdir/subsubdir 949cvs server: Updating b-subdir 950floss$ ls 951CVS/ a-subdir/ clog.in foo.gif 952README.txt b-subdir/ clog.out hello.c 953floss$ 954@end example 955 956The @file{clog.in} file contains everything that the client sent into 957the server, and @file{clog.out} contains everything the server sent back 958out to the client. Here are the contents of clog.out, to give you a 959sense of what the protocol looks like: 960 961@example 962Valid-requests Root Valid-responses valid-requests Repository \ 963Directory Max-dotdot Static-directory Sticky Checkin-prog Update-prog \ 964Entry Kopt Checkin-time Modified Is-modified UseUnchanged Unchanged \ 965Notify Questionable Case Argument Argumentx Global_option Gzip-stream \ 966wrapper-sendme-rcsOptions Set expand-modules ci co update diff log add \ 967remove update-patches gzip-file-contents status rdiff tag rtag import \ 968admin export history release watch-on watch-off watch-add watch-remove \ 969watchers editors init annotate noop 970ok 971M ? clog.in 972M ? clog.out 973E cvs server: Updating . 974E cvs server: Updating a-subdir 975E cvs server: Updating a-subdir/subsubdir 976E cvs server: Updating b-subdir 977ok 978@end example 979 980The clog.in file is even more complex, because it has to send revision 981numbers and other per-file information to the server. 982 983There isn't space here to document the client/server protocol, but you 984can read the @code{cvsclient} Info pages that were distributed with CVS 985for a complete description. You may be able to figure out a good deal 986of it just from reading the raw protocol itself. Although you probably 987won't find yourself using client logging until you've eliminated all of 988the other possible causes of a problem, it is an invaluable tool for 989finding out what's really going on between the client and server. 990 991@c --------------------------------------------------------------------- 992@node I do not see my problem covered in this chapter 993@subsection I do not see my problem covered in this chapter 994 995Email an accurate and complete description of your problem to 996@email{info-cvs@@gnu.org}, the CVS discussion list. Its members are 997located in many different time zones, and I've usually gotten a response 998within an hour or two of sending a question. Please join the list by 999sending email to @email{info-cvs-request@@gnu.org}, so you can help 1000answer questions, too. 1001 1002@c --------------------------------------------------------------------- 1003@node I think I have discovered a bug in CVS; what do I do? 1004@subsection I think I have discovered a bug in CVS; what do I do? 1005 1006CVS is far from perfect -- if you've already tried reading the manual 1007and posting a question on the mailing list, and you still think you're 1008looking at a bug, then you probably are. 1009 1010Send as complete a description of the bug as you can to 1011@email{bug-cvs@@gnu.org} (you can also subscribe to that list; just use 1012@email{bug-cvs-request@@gnu.org} instead). Be sure to include the 1013version number of CVS (both client and server versions, if applicable), 1014and a recipe for reproducing the bug. 1015 1016If you have written a patch to fix the bug, include it and mention on 1017the subject line of your message that you have a patch. The maintainers 1018will be very grateful. 1019 1020(Further details about these procedures are outlined in the node 1021@cite{BUGS} in the Cederqvist manual and the file HACKING in the source 1022distribution.) 1023 1024@c --------------------------------------------------------------------- 1025@node I have implemented a new feature for CVS; to whom do I send it? 1026@subsection I have implemented a new feature for CVS; to whom do I send it? 1027 1028Same as with a bug: Send the patch to @email{bug-cvs@@gnu.org}. Make 1029sure you've read over the HACKING file first, though. 1030 1031@c --------------------------------------------------------------------- 1032@node How can I keep up with changes to CVS? 1033@subsection How can I keep up with changes to CVS? 1034 1035The troubleshooting techniques and known bugs described in this chapter 1036are accurate as of (approximately) CVS Version 1.10.7. Things move fast 1037in the CVS world, however. While I was writing the last few chapters, 1038the unofficial mantle of CVS maintainership passed from Cyclic Software 1039to SourceGear, Inc (@uref{http://www.sourcegear.com}), which purchased 1040Cyclic. SourceGear has publicly announced its intention to take an 1041active role in CVS maintainer-ship and has received Cyclic's approval, 1042which is more or less enough to make it the "lead maintainer" of CVS as 1043of right now. (The @uref{http://www.cyclic.com} address will continue 1044to work, however, so all of the URLs given previously in this book 1045should remain valid.) 1046 1047SourceGear is, at this very moment, busy organizing and cleaning up 1048various patches that have been floating around, with the intention of 1049incorporating many of them into CVS. Some of these patches will 1050probably fix bugs listed previously, and others may afford new 1051troubleshooting tools to CVS users. 1052 1053The best way to stay up to date with what's going on is to read the NEWS 1054file in your CVS distribution, watch the mailing lists, and look for 1055changes to the Cederqvist manual and the online version of this book 1056(@uref{http://cvsbook.red-bean.com}). 1057
