1------------------------------------------------------------------------------- 2 3 CVS is Copyright (C) 1986-2006 The Free Software Foundation, Inc. 4 5 CVS is free software; you can redistribute it and/or modify 6 it under the terms of the GNU General Public License as published by 7 the Free Software Foundation; either version 1, or (at your option) 8 any later version. 9 10 More details are available in the COPYING file but, in simplified 11 terms, this means that any distributed modifications you make to 12 this software must also be released under the GNU General Public 13 License. 14 15 CVS is distributed in the hope that it will be useful, 16 but WITHOUT ANY WARRANTY; without even the implied warranty of 17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 GNU General Public License for more details. 19 20------------------------------------------------------------------------------- 21 22This file contains a CVS FAQ. Until 1995 it was maintained by David 23Grubbs. It was out of date and not being maintained, but it had a 24certain following and in 1997 Pascal Molli decided to start 25maintaining it with the FAQ-O-Matic package which allows any 26contributor with a web browser to help maintain it. The following 27text is (mostly automatically) extracted from the FAQ-O-Matic. The 28odds are good that the file that you are currently reading is out of 29date with respect to the online FAQ-O-Matic, which is part of Pascal 30Molli's CVS web site at http://www.loria.fr/~molli/cvs-index.html 31(currently under "Documentation"). The online version is also 32somewhat better in terms of things like tables of contents (at least 33until someone can write some code to extract data from a FAQ-O-Matic 34and insert things like tables of contents). 35 36The answers which are dated "6/13/1997" below are really from the 1995 37FAQ, for the most part. Many of them are out of date. The current FAQ may 38be found at <http://ximbiot.com/cvs/wiki/index.php?title=CVS_FAQ>. If you have 39some time, you are encouraged to export that FAQ as text and import it here. 40If you don't have such time, take the answers in this file with at least a few 41grains of salt. 42 43Since August, 2005, many of the existing CVS resources have been centralized on 44<http://cvs.nongnu.org> & <http://ximbiot.com>. 45 46 Category: /, all questions 47 48 Category: / 49 50 " [INLINE] " 51 52 1. About FAQ-O-Matic 53 54This is FAQ-O-Matic, a quick-and-dirty Perl hack (aren't they all?) by 55Jon Howell. 56 57It seems like most FAQ maintainers make a valiant initial effort, then get 58a life and don't have time to keep their FAQs up to date. Also, I often 59find out a solution to a problem, and feel like I could write a single 60FAQ answer on it in a few minutes, but where to post it? 61 62Thus the FAQ-O-Matic was born. FAQ-O-Matic is a couple sleazy Perl scripts 63that allow people to submit FAQ answers to this database, so it can stay 64current, with just a tiny bit of work on any one person's part. 65 66Yes, a bad guy could come along and wipe out all the FAQ entries. Please don't. 67But to give the good guys some measure of comfort, each submission is stored 68in an RCS file, so if someone does tamper, we can recover the database. 69 70Guidelines for submissions: 71 721. Please _try to be fairly unbiased in matters of opinion._ Mailing lists are 73the place to start flame wars (just kidding :v), but definitely not here. 74 752. Please _use HTML only conservatively_ in your entries. Links are appropriate 76, 77but put the URL in the plaintext also so it's useable on printed versions of 78the FAQ. Inline images pointing off this site are inappropriate, as is much 79fancy formatting. This is meant to be bandwidth-light and dumb-browser-friendly 80. 81 823. If you feel there's a place for a _new category, or a reorganization of 83existing questions_, don't hesitate to mail me (molli@loria.fr). 84Category changes need to be done from my end. 85 864. Please _leave an email address_ at the bottom of your submission so that oth 87ers 88can drop you a note. 89 905. _If you only have a question_, not an answer, you should probably post 91it to a mailing list, not here. If there are frequently asked questions to whic 92h 93the answer is not forthcoming on mailing lists (or perhaps there's no 94useful answer yet other than "no one knows"), then it's appropriate to 95post here, in hopes that someone will see it and know the answer. 96 976. Please refrain from crude or inconsiderate language. Please don't use 98this as a forum for advertising. However, mention of worthy commercial 99products is certainly appropriate (even if you sell said product). Just 100don't overdo it. :v) 101 102 Last modified: _6/13/1997_ 103 104 2. Adding a new category ? 105 106just send me a mail at 107molli@loria.fr 108 109 Last modified: _6/13/1997_ 110 111 Category: /Advanced_Topics_/ 112 113 " Advanced Topics " 114 115 Category: /Advanced_Topics_/Branching_and_Mergin/ 116 117 " + Branching and Merging" 118 119 1. What is a branch? 120 121 Unfortunately, the word "branch" is an overloaded technical 122 term. It is used in too many different ways in three 123 categories. It might help to understand some of the issues by 124 going through the categories: 125 126 How Humans use the word "branch": 127 128 Most development starts with everyone working on the same 129 software, making changes and heading toward a single goal. This 130 is called something like "Main Line Development". Note that 131 though many people do main line development on CVS's "Main 132 Branch", that is a choice, not a requirement. 133 134 After a release or when one or more developers want to go off 135 and work on some project for a while, the Software Engineers 136 assigned to deal with large software issues generate a "Branch 137 in Development" to support the release or project. (Keep in 138 mind that a programmer is no more a Software Engineer than a 139 carpenter is a Civil Engineer.) 140 141 Essentially, the word "branch" implies a way to allow 142 simultaneous development on the same files by multiple people. 143 144 The above terms are human-oriented. They refer to actions that 145 people would like to take. They do *not* imply any particular 146 implementation or set of procedures. Branches in development 147 can be supported in many different ways. 148 149 How CVS uses the word "branch": 150 151 CVS uses the word "branch" in a number of ways. The two most 152 important are: 153 154 - The vendor branch holds releases from (normally) an outside 155 software vendor. It is implemented using a specific RCS branch 156 (i.e. 1.1.1). 157 158 - The "Main Branch", which normally holds your "Main Line 159 Development", but is defined as the collection of revisions you 160 get when you "checkout" something fresh, or when you use the 161 '-A' option to "update". 162 163 Important Note: The CVS "Main Branch" is *not* the same as the 164 RCS concept with the same name. If you are using Vendor 165 Branches, files you have never changed are on three branches at 166 the same time: 167 168 - The RCS 1.1.1 branch. 169 - The CVS Vendor branch. 170 - The CVS "Main Branch". 171 172 The concepts overlap, but they are not equivalent. 173 174 In referring to CVS, "branch" can be used in four other ways: 175 176 - A CVS working directory satisfies the definition of "branch" 177 for a single developer -- you are on a private "virtual branch" 178 that does not appear in any of the RCS files or the CVS control 179 files. 180 181 - The CVS "default branch" is the Repository source for the 182 collection of files in your working directory. It is *not* the 183 same as the RCS "default branch". Normally the CVS default 184 branch is the same as the CVS Main branch. If you use the "-r 185 <branch_tag>" option to the "checkout" command, you will record 186 a "sticky" tag that changes your default branch to the one you 187 checked out. 188 189 - A "magic" branch can be a branch that hasn't happened yet. It 190 is implemented by a special tag you can check out that is not 191 attached to a real RCS branch. When you commit a file to a 192 magic branch, the branch becomes real (i.e. a physical RCS 193 branch). 194 195 - And, of course, CVS uses "branch" to indicate a 196 human-oriented "branch in development". 197 198 How RCS uses the word "branch": 199 200 - The RCS "Main Branch" (Synonym: "The Trunk") contains a 201 series of two-part revision numbers separated by a single '.' 202 (e.g. 1.2). It is treated specially and is the initial default 203 branch. (The default default?) 204 205 - The RCS "Default" branch starts out attached to the RCS "Main 206 Branch". For RCS purposes, it can be changed to point to any 207 branch. Within CVS, you *must*not* alter the RCS default 208 branch. It is used to support the CVS idea of a "Main Branch" 209 and it must either point to the RCS Main Branch, or the Vendor 210 Branch (1.1.1) if you haven't made any changes to the file 211 since you executed "import". 212 213 Last modified: _6/13/1997_ 214 215 2. Why (or when) would I want to create a branch? 216 217 Remember that you can think of your working directory as a "branch for 218 one". You can consider yourself to be on a branch all the time because 219 you can work without interfering with others until your project (big 220 or small) is done. 221 222 The four major situations when you should create a branch: 223 224 When you expect to take a long time or make a large set of changes 225 that the merging process will be difficult. Both "long" and "large" 226 are defined in your own environment. 227 228 When you want to be able to "commit" and "tag" your work repeatedly 229 without affecting others. 230 231 If you ever think you need Source Control for your own work, but don't 232 want your changes to affect others, create a private branch. (Put your 233 username in the branch tag, to make it obvious that it is private.) 234 235 When you need to share code among a group of developers, but not the 236 whole development organization working on the files. 237 238 Rather than trying to share a working directory, you can move onto a 239 branch and share your work with others by "committing" your work onto 240 the branch. Developers not working on the branch won't see your work 241 unless they switch to your branch or explicitly merge your branch into 242 theirs. 243 244 When you need to make minor changes to a released system. 245 246 Normally a "release" is labeled by a branch tag, allowing later work 247 on the released files. If the release is labeled by a non-branch tag, 248 it is easy to add a branch tag to a previously tagged module with the 249 "rtag" command. If the release is not tagged, you made a mistake. 250 Recovery requires identifying all revisions involved in the release 251 and adding a tag to them. 252 253 Last modified: _6/13/1997_ 254 255 3. How do I create and checkout a branch? 256 257 Suggested technique: 258 259 Attach a non-branch tag to all the revisions you want to branch 260 from. (i.e. the branch point revisions) 261 262 When you decide you really need a branch, attach a branch tag to the 263 same revisions marked by the non-branch tag. 264 265 "Checkout" or "update" your working directory onto the branch. 266 267 Suggested procedure when using modules: 268 269 cvs rtag <branch_point_tag> module 270 271 cvs rtag -b -r <branch_point_tag> <branch_tag> <module> 272 273 cvs checkout -r <branch_tag> module 274 275 Suggested procedure when using your working directory, which 276 contains the revisions of your working files you want to branch from: 277 278 cvs tag <branch_point_tag> 279 280 cvs rtag -b -r <branch_point_tag> <branch_tag> <module> 281 282 cvs update -r <branch_tag> 283 284 In each procedure above, Step #1 applies a non-branch tag to all the 285 branch point revisions in the module/directory. Though this is not 286 strictly necessary, if you don't add a non-branch tag to the revisions 287 you branch from, you won't be able to refer to the branch point in the 288 future. 289 290 Between steps 1 & 2 you may commit changes. The result would be same 291 because "rtag -r <oldtag> <newtag>" applies <newtag> to the same 292 revision that <oldtag> is attached to. You can use this technique to 293 avoid attaching *any* branch tags until you need them. 294 295 Step B.2 has two corollaries: 296 297 If you plan to create the branch tag before committing anything in 298 your working directory, you can use "cvs tag -b <branch_tag>" instead 299 of the "rtag" command. 300 301 The <module> can be a relative path to a directory from which your 302 working directory was checked out. 303 304 If you have trouble figuring out what <module> to use (or pathname to 305 use in its place), you can aim it at whatever parent directories you 306 believe will cover all your work. 307 308 If you are sure the <branch_tag> is not being used anywhere else, you 309 can even aim it at the whole Repository ($CVSROOT), if you have to. It 310 might take some extra time, but assuming that your <tag> is a unique 311 string and you don't use the '-f' option to "rtag -r", "rtag" will 312 only add a <tag> to files in which it actually *finds* the earlier 313 <tag>. 314 315 In each procedure above, Step #3 may occur any time after step 2. 316 Unless you explicitly remove them with "tag -d", a <tag> is permanent. 317 318 The <branch_tag> is an unusual creature. It labels a branch in a way 319 that allows you to "checkout" the branch, to "commit" files to the end 320 of the branch and to refer to the end of the branch. It does not label 321 the base of the branch (the branch point). 322 323 There are two obvious ways to choose the <branch_point_tag> and 324 <branch_tag> names. But keep in mind that the <branch_tag> is typed by 325 any developer who wants to work on the branch -- you should make it 326 mean something to them. 327 328 Style #1 presumes that the simple version string refers to a set of 329 designed, documented or promised features, not to a specific set of 330 files. In this case, you tag the branch with the generic Version 331 string and assume that whenever you refer to "Version", you want the 332 "latest" set of files associated with that Version, including all 333 patches. (You can substitute whatever you like for "bp_", as long as 334 your <branch_point_tag> is some modification of the <branch_tag>.) 335 336 <branch_point_tag> Matching <branch_tag> 337 338 bp_V1_3 V1_3 339 bp_Release2-3-5 Release2-3-5 340 bp_Production4_5 Release4_5 341 342 Style #2 presumes that the simple version string refers to the 343 specific set of files used to construct the first release of 344 "version". In this case, you tag the branch-point revisions with the 345 generic Version string and assume that whenever you refer to this 346 Version, you want the original set of released revisions. To get the 347 latest patched revisions of the release, you refer to the branch tag 348 "latest_<branch_point_tag>". (You can substitute what ever you like 349 for "latest_", as long as your <branch_tag> is some modification of 350 the <branch_point_tag>.) 351 352 <branch_point_tag> Matching <branch_tag> 353 354 V1_3 latest_V1_3 355 Release2-3-5 latest_Release2-3-5 356 Release4_5 latest_Production4_5 357 358 In both styles you can find out what you had to change since the 359 original release of this Version by typing: 360 361 cvs diff -r <branch_point_tag> -r <branch_tag> 362 363 For Style 1, this is: 364 365 cvs diff -r bp_<branch_tag> -r <branch_tag> 366 367 For Style 2, this is: 368 369 cvs diff -r <branch_point_tag> -r latest_<branch_point_tag> 370 371 Notes on "being on a branch": 372 373 - "update -r <tag>" tells CVS to attach a "sticky tag" to working 374 directory (in ./CVS/Tag) and the checked-out files (on each line of 375 ./CVS/Entries). 376 377 - A "sticky" <tag> (including a <branch_tag>) causes most CVS commands 378 to act as if "-r <tag>" were on the command line. 379 380 - A "sticky" <branch_tag> indicates that the working directory (and 381 working files) are "on the branch". 382 383 Last modified: _6/13/1997_ 384 385 4. Once created, how do I manage a branch? 386 387 The most important thing you should know about managing a branch is 388 that the creation of a branch is not a lightweight act. When you 389 create a branch, you must also create a set of procedures to keep 390 track of it. 391 392 Specifically, you must: 393 394 - Remember that the branch exists. (This is non-trivial if you create 395 a lot of them.) 396 397 - Plan when to merge it back into the main line of development. 398 399 - Schedule the order that multiple branch merges are to be done. 400 401 - If you ever intend to merge branches into each other, instead of 402 limiting merges of branch work back into the "main line", you must 403 keep careful track of which parts of which branches have merged into 404 which other branches. 405 406 The simplest way to deal with branches is to limit their number, 407 "collapse" them back into the main line as quickly as is reasonable 408 and forget them. If a group wants to continue working, tell them to 409 create another branch off the fully merged main line. 410 411 Remember that CVS is just a tool. Over time, it will probably handle 412 branching better, requiring less careful attendance. But no matter how 413 good it becomes, the whole idea of "branching" is a complicated 414 management problem. Don't take it lightly. 415 416 Last modified: _6/13/1997_ 417 418 5. Are there any extra issues in managing multiple branches? 419 420 If you plan to split from the "main line" and merge back after a time, 421 the only problem will be scheduling the order of branch merges. As 422 each branch is merged, the main line must be rebuilt and tested. 423 Merging multiple branches (i.e. "lines of development") before 424 building and testing creates more problems than you are ready for. 425 426 If you plan to collapse some branches into others, then move the 427 combined branches back into the main line, you have to be careful with 428 the revisions and tags you hand to your "update -j" command, but it 429 shouldn't be much trouble. 430 431 If you plan to allow every branch to incrementally take the work done 432 on other branches, you are creating an almost insurmountable 433 bookkeeping problem. Every developer will say "Hey, I can handle 434 taking just this little bit," but for the system as a whole it is 435 disaster. Try it once and see. If you are forced into this situation, 436 you will need to keep track of the beginning and end points of every 437 merge ever done. Good Luck. 438 439 Last modified: _6/13/1997_ 440 441 6. How do I merge a whole branch back into the trunk? 442 443 If you don't have a working directory, you can checkout and merge in 444 one command: 445 446 cvs checkout -j <branch_tag> <module> 447 cd <module> 448 449 If you already have a working directory: 450 451 cd <working_directory> 452 cvs update <== Optional, to bring it up to date. 453 cvs update -j <branch_tag> 454 455 CVS will print lines beginning with 456 457 'U' for files that you hadn't changed, but the branch did. 458 459 'M' for files that you changed and the branch didn't 460 *and* for files that you both changed that were merged 461 without overlaps. (This overload is unfortunate.) 462 463 'C' for files that you both changed in a way that conflicts 464 with each other. 465 466 You need to go edit all the 'C' files and clean up the conflicts. Then 467 you must commit them. 468 469 Last modified: _6/13/1997_ 470 471 7. How do I merge changes from the trunk into my branch or between 472 branches? 473 474 The idea is similar to the above, but since CVS doesn't treat the main 475 branch like other branches, you'll have to be more careful. There are 476 5 different ways to look at the problem. 477 478 The way to merge *all* changes made on the trunk into a working 479 branch is to move to the branch you want via "checkout -r" or "update 480 -r": 481 482 cvs update -r <branch_tag> {optional files} 483 484 Then merge the changes from the trunk into your working branch using 485 the pseudo-tag named "HEAD": 486 487 cvs up -j HEAD {optional files} 488 489 You will get everything from the branch point of the branch named 490 <branch_tag> up to the HEAD of the main branch. This is still kind of 491 strange. If the file is on a branch, HEAD should be the latest thing 492 on the branch, not the HEAD of MAIN. But that's not the way CVS 493 (currently) works. 494 495 If you run "cvs up -j HEAD" again after adding more revisions to the 496 trunk, you may get overlaps for the text you have already merged. It 497 depends on your version of your RCS "merge" command (actually the "co 498 -j" option, which depends on the version of "diff3" you configured RCS 499 to use). 500 501 You can merge the difference between any two <tags> using two "-j" 502 options on "update" or "checkout". 503 504 Identify the two tags on the branch you want to merge from. 505 506 cvs update -j <tag1> -j <tag2> {optional files} 507 508 This step assumes you were careful about tagging milestones. You can 509 use this technique for any two <tags> on the same branch, even the 510 trunk. It is also possible to use tags on different branches, but 511 you'll have to ponder the meaning of the difference between those two 512 tags. 513 514 In place of one of the <tags>, you can use a <branch_tag> to refer to 515 the latest revision on that branch. See 4C.11 and 4C.3 for info on 516 branch points. 517 518 Merges can also be performed by handing RCS revisions to the '-j' 519 options, but since revision numbers aren't the same in all files, 520 merging by number is normally limited to one file. Sets of files with 521 the exact same trees of branches and revision numbers would work too, 522 but that's a rare situation. 523 524 To "take" revisions from other branches instead of merging them, see 525 4C.19 for an idea. 526 527 A way to gain the effect of merging the main to the branch is to 528 merge the branch into the main using the normal 529 530 cvs update -A {optional files} 531 cvs update -j <branch_tag> {optional files} 532 cvs commit 533 cvs tag -F -b <same_branch_tag> {optional files} 534 535 See part B of 4D.5 536 537 Other oddities. 538 539 This also works, but is probably not officially supported: 540 541 cvs update -j N {optional files} 542 543 where N is a number. This will merge all the changes from the branch 544 point up to the highest revision on the main branch starting with N. 545 For example, if your highest trunk revision is 1.52, you can use this 546 to grab revisions from the trunk: 547 548 cvs update -j 1 {optional files} 549 550 Another example: Say you have a branch point at rev 1.2 for a branch 551 named "BR1" and trunk revisions 1.3, 1.4, 2.1, 2.2, 2.3, 3.1, 3.2. 552 Then: 553 554 cvs update -j 1 {optional files} 555 556 will merge the changes from 1.2 to 1.4 557 558 cvs update -j 2 {optional files} 559 560 will merge the changes from 1.2 to 2.3 561 562 cvs update -j 3 {optional files} 563 564 will merge the changes from 1.2 to 3.2, which in this example, is 565 equivalent to the use of "-j HEAD" in part A above. 566 567 The intuitive (at least to me): 568 569 cvs up -j MAIN (or TRUNK) {optional files} 570 571 doesn't work. If the trunk (i.e. "main branch") had an implicit branch 572 named "MAIN", you could use: 573 574 cvs up -j MAIN:10/26 -j MAIN:now {optional files} 575 576 and refer to date-stamped revisions on the trunk using the 577 <branch_tag>:<date> support that works on other branches. 578 579 You might also think you could place an explicit tag on branch 1 (or 580 higher) (e.g. MAINHACK:1) and use it in place of the implicit "MAIN", 581 but I haven't found the right combination. 582 583 [[If you find working techniques, I'll add them here.]] 584 585 Last modified: _6/13/1997_ 586 587 8. How do I merge onto the Main Branch a file that exists only on a branch 588 other than the Main Branch? (i.e. it is in the Attic) 589 590 For how such a file can exist, see 3A.2 and 3A.3. 591 592 For how to avoid creating such a file, see 3A.5. 593 594 Though you might think that the "update -j" command could perform the 595 "merge" of a file from the side branch to the Main Branch, it isn't 596 (yet) smart enough. Unfortunately, there is no single CVS command to 597 do this -- it takes three steps: 598 599 To move something onto the Main Branch from the Attic, you have to 600 physically move the file from the Attic to the main Repository 601 directory associated with your working directory. 602 603 It is exactly like resurrecting a removed file. See 3L.4 604 605 I use something like this: (csh-like syntax) 606 607 set repos = `cat ./CVS/Repository` mv $repos/Attic/filename,v 608 $repos/filename,v 609 610 (If you use relative paths in your Repository files, that first line 611 becomes: set repos = $CVSROOT/`cat ./CVS/Repository`) 612 613 Now that the file is physically in the right place within the 614 Repository, "update -A" will make it appear in your working directory 615 on the Main Branch. Do that now. 616 617 You now have a choice. The act of physically moving the file has 618 fused together the <branch_tag> branch and the Main Branch for this 619 file. You can continue that way, making changes along the RCS Main 620 Branch which CVS will (for this type of file only) treat as both the 621 Main Branch and the <branch_tag> branch. 622 623 The other choice, which I would suggest, is to re-tag the file with 624 <branch_tag>, restoring a normal-looking magic branch tag to the file: 625 626 cvs tag -F -b <branch_tag> <file> 627 628 After you have done the above, you can run "update -A" or "update -r 629 <branch_tag>" to resume whatever you were doing before you started 630 this procedure. 631 632 Caveat: The final result is a file whose revision tree doesn't look 633 like it was ever on any branch but the Main Branch until the above 634 "tag -F -b" command was executed. CVS and RCS have no way of saving 635 the history of the actions you have just performed. 636 637 Last modified: _6/13/1997_ 638 639 9. How do I know what branch I'm (working) on? 640 641 Type: 642 cvs status 643 644 and look at the "Sticky Tag" field for each file. If: 645 646 The *same* tag is on *every* file in your working tree, *and* 647 648 That tag matches the contents of the ./CVS/Tag file, *and* 649 650 That tag is a branch tag, 651 652 then you know what branch you are working on. You can get sticky Tag 653 information directly from the ./CVS/Entries file instead of "cvs 654 status". 655 656 If all the sticky Tags don't agree, then your directory is temporarily 657 inconsistent. This is a feature allowing you to make changes (or 658 perform merges) to individual files on multiple branches without 659 checking out the whole directory. 660 661 The sticky Tag on each file in the ./CVS/Entries file (as displayed by 662 the "status" command) indicates what branch the working file is on. 663 New files are added to the Tag stored in ./CVS/Tag. 664 665 To force your entire working directory onto the same branch, type: 666 667 cvs update -r <branch_tag> 668 669 Last modified: _6/13/1997_ 670 671 10. Do I really have to know the name of the branch I'm working on? 672 673 If a developer can't be relied on to know what branch of development 674 to work on, then either the developer's manager isn't planning 675 branches properly or the developer has serious problems. 676 677 I have found that one of the hardest concepts to get across to 678 developers (and some managers) is that "a branch in development" (as 679 opposed to the use of RCS branches to support some other scheme) is a 680 heavyweight act. Every time you create a real branch in development, 681 you must spawn a set of managerial procedures and a schedule by which 682 you plan to merge each branch into each other branch. Unless you plan 683 to keep it simple and collapse (by merging and forgetting) branches 684 quickly, they are not to be created lightly. 685 686 In other words, if you don't regularly attend group meetings in which 687 the branch to be worked on is a major topic of discussion, then the 688 group is not managing branches properly. 689 690 We created a couple major branches a few months ago and even the 691 customer service people refer to the "XYZ branch" as a shorthand for 692 "continuing development on the XYZ project". 693 694 Last modified: _6/13/1997_ 695 696 11. How do I refer to the revision where I branched so I can see what 697 changed since the Branch Point on another branch? 698 699 Given the current <branch_tag> format, there is no direct way to refer 700 to the branch point, which is more useful in many ways than referring 701 to the branch, which always refers to the latest revision on the 702 branch. 703 704 When CVS adds a branch tag, it attaches an RCS symbol to a 705 non-existent revision number containing the revision number of the 706 branch point as a prefix. (See Section 3O, on the "tag" command.) RCS 707 can't use the CVS magic branch tag and many of the CVS commands can't 708 refer to it. 709 710 To be certain of your ability to refer to a branch point, you must 711 create a "branch point" tag at the same time as the Branch tag. See 712 4C.3. 713 714 Last modified: _6/13/1997_ 715 716 12. Why didn't the command "cvs admin -bBRANCH1 *" create a branch? 717 718 Because your command creates an RCS branch, not a CVS branch. See the 719 above discussion on branches. RCS branches are used to support CVS 720 branches, but they are not the same. You can't act as if you have 721 direct control over the RCS files. 722 723 The "admin" command was placed there as a convenience to allow you to 724 execute raw "rcs" commands on the Repository, taking advantage of 725 CVS's ability to find the files in the Repository. 726 727 But you have to remember that you are using RCS commands on a CVS 728 Repository, which is not generally safe unless you know exactly what 729 CVS depends on. 730 731 For one thing, CVS insists on control of the default branch. It is set 732 either to the Main branch or the Vendor branch depending on whether 733 you have changed the Vendor's code. If you change the default branch, 734 you are monkeying with the internals and you will get unexpected 735 results. 736 737 To set your "default CVS branch" to BRANCH1, you must use "checkout" 738 or "update" with the "-r BRANCH1" option. Then you have changed CVS's 739 idea of your "default branch", which has little to do with RCS's 740 default branch. 741 742 Last modified: _6/13/1997_ 743 744 13. Is it possible to set the "default CVS branch" for everyone? 745 746 No. It doesn't work that way. 747 748 When using CVS, all administrative information (such as what branch 749 you checked out) is stored in CVS sub-directories, local to the user. 750 There is no global state, other than the description and logging files 751 in the $CVSROOT/CVSROOT directory. 752 753 You tell "checkout" or "update" what branch you want to check out via 754 the "-r <tag>" option. The default is CVS's "Main Branch". 755 756 I don't see a problem in *designing* a new way to indicate what branch 757 you get by default, instead of the main one, but that's not how it 758 currently works. 759 760 Last modified: _6/13/1997_ 761 762 14. How do I perform a large merge? 763 764 Large merges require a bit more planning to be able to track what has 765 happened in the inevitable cases where something goes wrong. No tool 766 can force a "merge" to make perfect sense. 767 768 Though you can handle the details in many different ways, the two ends 769 of the spectrum of merge techniques are: gonzo and paranoid. 770 771 The gonzo method assumes that you know everything about your sources 772 so that recovery from failures is "just a matter of typing." You 773 created the branch this way: 774 775 cvs checkout <module> 776 cd <module> 777 cvs tag -b <branch_tag> 778 cvs update -r <branch_tag> 779 >>> Edit away. 780 cvs commit <<== Onto branch 781 782 Now you want to merge your branch back into the Main branch, you are 783 certain you can make it work, or at least detect all the failures, so 784 you dive in and hack away: (For simplicity, we will assume you are 785 collapsing (i.e. merging and forgetting) a side-branch into the Main 786 branch from your single working directory.) 787 788 cvs update -A 789 cvs update -j <branch_tag> 790 >>> Edit the 'C' files and remove the overlaps. 791 >>> Edit some more to make it all compile and work. 792 cvs commit 793 794 Looks simple. For more details on the output from the "update -j" 795 command, see 3P.2 and 4C.6. 796 797 Note: You could also checkout a whole new working directory and 798 perform the merge at the same time by replacing the two 799 update commands with these two commands: 800 801 cvs checkout -j <branch_tag> <module> 802 cd <module> 803 804 The paranoid way is more difficult, but it can catch all sorts of 805 problems. You created the branch this way: 806 807 cvs checkout <module> 808 cd <module> 809 cvs tag <branch_point_tag> 810 cvs tag -b <branch_tag> 811 cvs update -r <branch_tag> 812 >>> Edit away. 813 cvs commit <<== Onto branch 814 815 The extra tag command places a non-branch tag on the Branch Point, an 816 act that makes it easier to do "diffs" later. Now we decide to perform 817 the merge: 818 819 cvs tag <latest_on_branch_tag> 820 cvs update -A 821 *1* cvs diff -r <branch_point_tag> -r <latest_on_branch_tag> 822 >>> *1* shows all the changes on the branch. 823 *2* cvs diff -r <branch_point_tag> -r HEAD 824 >>> *2* shows the changes on the trunk since branching. 825 cvs tag <premerge_tag> 826 cvs update -j <branch_tag> 827 >>> Edit the 'C' files and remove the overlaps. 828 *3* cvs diff 829 >>> Verify that *3* matches *1*, except for line numbers. 830 cvs commit 831 cvs tag <just_merge_changes_tag> 832 >>> Edit some more to make it all compile and work. 833 cvs commit 834 cvs tag <after_merge_cleanup_tag> 835 836 The reason *3* and *1* match so closely is that they are the 837 differences between two pairs of starting points and ending points 838 after the same data was inserted. If they are significantly different, 839 you will want to figure out why. 840 841 NOTE: You will have to tell everyone to stay the hell out of the 842 Repository while you do this. If they commit something while you are 843 in the middle of a merge, your job will be much more difficult. If 844 they "update" at the wrong time, their work will be randomized until 845 you finish. It's better to call a halt. 846 847 See 3H.13 for some more information about dealing with merges after 848 import. The last part of the procedure is applicable to any large 849 merge. 850 851 Last modified: _6/13/1997_ 852 853 15. Is a Vendor merge any different from a branch merge? 854 855 No. In most ways, a Vendor branch is exactly the same as any other 856 branch. In a Vendor merge, the data is append to the branch by the 857 "import" command, rather than by hand-editing, but the merge process 858 is the same. 859 860 See the "import" command in section 3H. 861 862 Last modified: _6/13/1997_ 863 864 16. How do I go back to a previous version of the code on a branch? 865 866 867 868 869 You can avoid digging into RCS revision numbers (executing "update 870 -r (rev)" on each file) by trying one of these: 871 872Use non-branch tags as you normally would. Non-branch tags 873 attach to specific revisions, so a "tag (tag)" command would 874 mark the revisions you have in your working directory, which 875 are on your branch. If you need to retrieve them, use "update 876 -r (non-branch-tag)" 877 878 Doing this overrides the sticky (branch-tag) attached to your 879 working directory with a non-branch tag, which means you won't 880 be able to commit until you again move forward to the end of 881 the branch with "update -r (branch-tag)". 882 883Use the "update -r (branch-tag):(date)" trick. 884 885 This is almost like using the '-D' option, but it looks for 886 revisions extant on (date) only along the given branch. 887 888 As in #1, you can't commit to this kind of working area, 889 because it has a sticky date referring to revisions in the 890 middle of a branch. 891 892[comment from the audience: You are dreaming.. 893this does not work.. try it, you get 894No such tag: "MYTAG:May 1" 895or similar. I wish it did because I need it. julian@whistle.com] 896 897 898You can branch a branch. 899 900 If you add a branch tag to file in a working directory that was 901 checked out on a branch, you will branch the branch. This 902 works just fine, though you'll have to play some games to merge 903 everything back together again. You'll also create 6-part 904 revision numbers. (They'll be 8-part revision numbers if you 905 branch a branch that started out with some unmodified files on 906 the Vendor branch. Think about it. How does revision 907 1.2.4.2.4.2.2.1 grab you?) 908 909 910(fixed formatting, kingdon@cyclic.com) 911 912 Last modified: _9/8/1997_ 913 914 17. Once I've found the files I want, how do I start changing them? I keep 915 getting warnings about sticky tags. 916 917 What you probably did was type "cvs update -r <tag>" where <tag> is a 918 non-branch tag. "update" created a sticky tag for a specific revision, 919 not a branch. To start working right there, you have to create a 920 branch to work on. 921 922 You have two choices. 923 924 You can do it in place and keep working: 925 926 cvs tag -b <branch_tag> <<== To tag the current files. 927 cvs update -r <branch_tab> <<== To move onto the branch. 928 929 You can do it "externally" and create a new working directory: 930 931 cvs rtag -b -r <tag> <branch_tag> <module> 932 cvs checkout -r <branch_tag> <module> 933 934 <module> can be a relative path within the Repository. 935 936 <tag> in the above is the non-branch tag you placed earlier 937 that caused the error in your question. Be warned that 938 if <tag> is not set on all the files (or all the right 939 revisions) you won't get exactly what you wanted. 940 941 Last modified: _6/13/1997_ 942 943 18. Why do I get the latest files on the branch when I tried to "update -r 944 <tag>"? 945 946 If "update -r <tag>" always retrieves the latest files on a branch, 947 then <tag> is really a <branch_tag>. A branch tag is supposed to be 948 used to grab a branch to work on. Since you can't modify a file in the 949 middle of a branch, checking out a <branch_tag> will give you the 950 latest revision on the branch. 951 952 If you want to "checkout" a specific collection of revisions, you must 953 use a "non-branch" tag. See the first part of 4C.16. 954 955 Last modified: _6/13/1997_ 956 957 19. How can I avoid a merge? I just want to move the latest revision on my 958 working branch directly onto the trunk. 959 960 There is no direct way to do this using CVS, though the technique is 961 not difficult using shell commands. Here's one way: 962 963 Move your working directory to the Main Branch. 964 965 cvs update -A 966 967 Use "update -p" to grab the latest revision on the branch and write 968 it over your working files. Make sure you don't have an modified files 969 -- you will lose them. The following is in "csh" syntax. Change the 970 wildcard to grab the files you want 971 972 foreach i (Makefile *.cc *.hh) 973 cvs update -p -r <branch_tag> $i > $i 974 end 975 976 Commit all the working files onto the Main Branch. 977 978 cvs commit -m 'Moved branch <branch_tag> onto MAIN' 979 980 You should experiment with the above before blasting everything. 981 982 Last modified: _6/13/1997_ 983 984 20. How to I avoid merge collisions in the RCS $\Log$ data? 985 986 In short, you can't. The RCS $\Log$ keyword is handled differently 987 from all other RCS keywords. 988 989 On the info-cvs mailing list, there is a periodic discussion that goes 990 something like this: 991 992 Question: How do I deal with $\Log$? Answer1: You can't do much with 993 it. Here's how it works. . . Answer2: I've found a limited way to use 994 it. . . Answer3: Get rid of it. $\Log$ is an abomination. 995 996 I tend to lean toward answer #3. There are only two sets of people who 997 would ever have access to logs stored within sources files, developers 998 and source customers. 999 1000 For developers: 1001 1002 Log entries within sources files are notoriously incomplete, rushed, 1003 poorly phrased and in many cases incorrect, making them useless for 1004 debugging or file maintenance. I remember a maxim from "Software 1005 Tools" (I believe): "Read the code, not the comments." No managerial 1006 order or plan for programmer discipline will affect this in the real 1007 world. 1008 1009 Log entries are usually in an unreadable mixture of styles. Many log 1010 entries are just plain meaningless. Some are foolish. Some are even 1011 insulting. Examples: 1012 1013 "Corrected spelling of misspelling." "Bug fix." "Reversed stupid 1014 change in previous revisions." "If Joe could do his job, this would 1015 already have worked." 1016 1017 Log entries are not managed well by the tools. Any merge can cause 1018 conflicts in the $\Log$ data. Branch merges produce incomplete logs. 1019 They can be edited into chaos and they are not regenerated. They waste 1020 space duplicating information available to the developer with a single 1021 command. 1022 1023 Even if correct when originally entered, as changes are made to the 1024 file, log entries become false over time. Humans are not good at 1025 reading down through a list and remembering only the last change 1026 affecting something. Over time *most* of the log is wrong. 1027 1028 Even if still correct, the log data is almost useless to developers 1029 without the code diffs. If you can get code diffs, you can display the 1030 log. 1031 1032 For source customers the problem is even worse. The last thing you 1033 want to show customers is a hodge-podge of tiny comments about large 1034 changes followed by a series of emergency fixes before delivery. If 1035 you distribute sources, then you should provide documentation, or 1036 changelogs reviewed by people who won't let comments like "Fixed for 1037 stupid customer." out the door. 1038 1039 Conclusion: Though some people would prefer to see in this FAQ 1040 techniques for making the $\Log$ entries the best they can be, I 1041 believe them to be a lost cause. My suggestion is to hunt down, root 1042 out and destroy all occurrences of $\Log$ and the unusable data 1043 attached to it wherever you may find it. 1044 1045 Last modified: _6/13/1997_ 1046 1047 21. Why should I trust automatic merges? 1048 1049 Some developers have the feeling that three-way merging doesn't work. 1050 They fear and distrust the way the "update" command automatically 1051 merges committed changes from the Repository into the working file. 1052 1053 Experience has shown that most merges are utterly painless and most of 1054 the rest are easily resolved. The few conflicts that cause headaches 1055 are nearly all due to poor communication between developers, a problem 1056 no source control system can obviate. 1057 1058 Some developers were troubled in the past by flaky Unix software. I 1059 can't say that everything is perfect, but the tools CVS depends on 1060 (RCS and diff, mainly) are fairly solid nowadays. They work. 1061 1062 Since it does seem to work for most of us, the algorithm is unlikely 1063 to change soon. Why not test it on a couple trouble spots and if it 1064 works for you, use it for a while? Then you can make an informed 1065 decision. 1066 1067 Last modified: _6/13/1997_ 1068 1069 22. How does CVS decide if it can safely perform a merge? 1070 1071 CVS can merge any text file, possibly discovering a conflict and 1072 leaving overlaps for you to edit. Editing the conflict markers out of 1073 the file is a moment's work, but resolving the conflict could take an 1074 arbitrary amount of time. CVS works to determine if it *should* merge, 1075 not if it *can*. 1076 1077 See 2B.6 for how the merge proceeds. 1078 1079 Last modified: _6/13/1997_ 1080 1081 23. After resolving merge conflicts in a file, what if I want to keep my 1082 previous version, and not take any of the branch changes? 1083 1084 If you want to retain your previous version, a version on the MAIN 1085 branch greater than 1.1 (one you committed there), just throw the 1086 merged file away and "cvs update" the file. 1087 1088 You don't need to commit something to remember it. The tags you place 1089 before and after the merge should give all the handles you need to 1090 find various versions. You don't have to create a new version of the 1091 file. 1092 1093 If you want to retain the previous Vendor revision, you can grab a 1094 copy of it using "cvs update -p" and commit it or use the technique 1095 described in 3B.3 to revert back to the Vendor branch. 1096 1097 Last modified: _6/13/1997_ 1098 1099 Category: /Advanced_Topics_/Engineering/ 1100 1101 " + Engineering" 1102 1103 1. Where can I find out about Software Engineering? 1104 1105 A couple different people suggested this book: 1106 1107 Software Configuration Management: Coordination for Team Productivity; 1108 Wayne A. Babich; Addison Wesley; 1986; ISBN 0-201-10161-0 1109 1110 A number of others suggested Appendix B of the book "Decline and Fall 1111 of the American Programmer" by Ed Yourdon, called "The Programmer's 1112 Bookshelf". It list 87 books you are expected to have read. Since they 1113 publish many of the books, Prentice-Hall distributes this list as 1114 "Prentice Hall Professional Technical reference PTR-125-AA3. 1115 1116 One interesting item from the Yourdon book: The total number of 1117 professional computer books sold is less than the number of 1118 programmers currently in the United States. It wasn't clear from the 1119 book whether this meant "per year" or not, but it is still 1120 frightening. 1121 1122 Last modified: _6/13/1997_ 1123 1124 2. How do I flexibly arrange the modules file to describe my sources? 1125 1126 An equivalent question might be, "How do I structure my sources?" This 1127 can be a difficult question especially in the areas that are more 1128 political than technical. 1129 1130 Generally you want to think about which pieces of your system need to 1131 be checked out together, built as one system or tagged as a consistent 1132 whole. You should certainly create module names that correspond to 1133 complete, buildable collections that you would tag and release as one 1134 "product". It is also convenient to create module names for small 1135 sections of the Repository containing files that will all be worked on 1136 at the same time by the same person or group. 1137 1138 Once you have defined the structure of your work, you can usually see 1139 how to lay it out in a Repository. After that the modules file is 1140 easy. You set up module names and aliases to match what you need to 1141 check out by name. If you like relative directories, it is possible, 1142 but not recommended, to work completely without a modules file. See 1143 1D.11 and 2C.7 for some info about the modules file. 1144 1145 Here are a few types of modules. You should experiment to see what 1146 kind of structure each of these produces. They all have different 1147 uses. 1148 1149 Connected projects in one group with two separate helper 1150 directories. The helper directories can contain build tools, header 1151 files, libraries, or whatever you like. 1152 1153 These are all aliases that checkout relative pathnames. The equivalent 1154 results could be produced by placing the selected relative pathnames 1155 on the "cvs checkout" command line. 1156 1157 pr1 -a P1 HELPERS 1158 pr2 -a P2 HELPERS 1159 pr3 -a P3 HELPERS 1160 pr12 -a P1 P2 HELPERS 1161 pr13 -a P1 P3 HELPERS 1162 pr23 -a P2 P3 HELPERS 1163 1164 P1 -a group1/proj1 1165 P2 -a group1/proj2 1166 P3 -a group1/proj3 1167 HELPERS -a group1/helper1 group1/helper2 MAKEFILE 1168 MAKEFILE -a group1/Makefile 1169 1170 Actual Repository directory structure: (from $CVSROOT down) 1171 1172 group1/ Makefile The top level Makefile. helper1/ helper2/ Helper 1173 files and dirs proj1/ Files and dirs proj2/ Files and dirs proj3/ 1174 Files and dirs 1175 1176 "checkout group1" produces a duplicate of the above. "checkout projX" 1177 produces all but "projY" and "projZ". "checkout projXY" produces all 1178 but "projZ". 1179 1180 Here is the exact same set of module names describing the same 1181 Repository layout using module names (and aliases containing module 1182 names) instead of merely aliases for relative pathnames. 1183 1184 There is one difference in the result. The name of the top level 1185 directory in the checked out working tree will match the "module" name 1186 (e.g. pr1) instead of always being "group1" as it was in the first 1187 example above. 1188 1189 pr1 group1 proj1 &HELPERS 1190 pr2 group1 proj2 &HELPERS 1191 pr3 group1 proj3 &HELPERS 1192 pr12 group1 proj1 proj2 &HELPERS 1193 pr13 group1 proj1 proj3 &HELPERS 1194 pr23 group1 proj2 proj3 &HELPERS 1195 1196 HELPERS -a helper1 helper2 group1-Makefile 1197 helper1 group1/helper1 1198 helper2 group1/helper2 1199 group1-Makefile -d . group1 Makefile 1200 1201 The above line (with the -d in it) says that when the module named 1202 "group1-Makefile" is checked out, the file named Makefile file will be 1203 found in a directory named $CVSROOT/group1 and will be checked out 1204 into a directory named '.', which obviously already exists. 1205 1206 The & references say to interpret those pathnames relative to the 1207 directory where the whole module is stored. For the "pr1" module, that 1208 directory is "group1", so the &HELPERS reference winds up placing 1209 Makefile in '.' relative to "group1". 1210 1211 A short one containing the basic "module" actions: 1212 1213 m1 head/path file1 dir2 file3 dir4 file5 1214 1215 When checked out, a directory named "m1" appears in your current 1216 directory. Elements named file1, dir2, file3, dir4, and file5 appear 1217 in it. They were originally taken as relative paths from 1218 $CVSROOT/head/path. 1219 1220 Here's another way to construct a working directory out of pieces of 1221 the Repository: 1222 1223 projX projX Makefile &projX_inc &projX_src &projX_doc 1224 1225 # The first line selects a single file within projX, plus 1226 # the contents of three other modules. Those three other 1227 # modules rename their directories. 1228 1229 projX_inc -d include projX/inc projX_src -d source projX/src projX_doc 1230 -d documentation projX/doc 1231 1232 A Unix tree. This is similar to what CVS was developed for and the 1233 way I have used it for years. 1234 1235 # Top level 1236 unix unix 1237 u_bin unix/bin 1238 u_etc unix/etc 1239 u_man unix/man 1240 usr-bin unix/usr.bin 1241 1242 # Subdirs of top level dirs. (tiny subset) 1243 ls unix/bin/ls 1244 fsck unix/etc/fsck 1245 man8 unix/man/man8 1246 1247 # Programs without subdirs. (tiny subset) 1248 cat unix/bin Makefile cat.c 1249 uniq unix/usr.bin Makefile uniq.c 1250 1251 # /usr/local/src 1252 localsrc localsrc 1253 gnu localsrc/gnu 1254 public localsrc/public 1255 X11 localsrc/X11 1256 1257 # GNU and PD tools 1258 cvs localsrc/gnu/cvs 1259 emacs localsrc/gnu/emacs 1260 rcs localsrc/gnu/rcs 1261 btoa localsrc/public/btoa 1262 tcsh localsrc/public/tcsh 1263 1264 # X11 related items. 1265 tvtwm localsrc/X11/contrib/tvtwm 1266 1267 "unix" was checked out and built from the top down, using a set of 1268 Makefiles that knew about the whole structure. "localsrc" was kept 1269 checked out in /usr/local/src. 1270 1271 At any time I could run "checkout ls" or "checkout cat" and get a 1272 simple directory with only that tool in it, plus a subset Makefile 1273 that knew how to build that tool against the installed (or alternate, 1274 via environment variables) headers and libraries. 1275 1276 I found it very handy to be able to run "ls" and see the three tools I 1277 was porting that week. 1278 1279 Last modified: _6/13/1997_ 1280 1281 3. Can I have multiple source repositories, one for each project? 1282 1283 Yes, you can have as many Repositories as you like. But each 1284 Repository must be managed separately, creating additional work. 1285 1286 Question 4A.1 provides a short description of setting up a single 1287 Repository. A few additional considerations: 1288 1289 It is a good idea to start by creating a single Repository and split 1290 it up (or create additional Repositories) only if you believe it is 1291 really necessary. I would only create a new Repository if the data is 1292 completely disconnected from the rest of the main Repository. 1293 1294 If there is a lot of overlap among the developers working on the 1295 collections of files you want to place in different Repositories, or 1296 if there is any connection between those collections, I would go out 1297 of my way to create a single Repository. It is much easier to manage. 1298 1299 Disk space should not be a factor since you can build up a 1300 Repository using symbolic links and/or remote mounts. 1301 1302 Each Repository is completely distinct. You can't check out modules 1303 from different Repositories at the same time. A better way of looking 1304 at it is that if you *can* check out two modules or directories with a 1305 single "checkout" command (without contortions or explicit absolute 1306 pathnames), then they are in the same Repository. 1307 1308 To "checkout" modules from multiple Repositories, you must use the 1309 "cvs -d" option on all CVS commands or alter your $CVSROOT variable 1310 when you change focus to another Repository. If you work with multiple 1311 Repositories, it is a good idea to configure CVS to use absolute 1312 pathnames in the ./CVS/Repository file, since most commands (other 1313 than "checkout") will use that file rather than $CVSROOT. 1314 1315 If you configure CVS to use relative pathnames in your 1316 ./CVS/Repository files, you must always be careful to set your 1317 $CVSROOT properly or you will get unexpected results. 1318 1319 If you have two modules or directories by the same name at the same 1320 relative path inside two different Repositories, you are asking for 1321 disaster. You could unexpectedly update a directory with completely 1322 unrelated files. This is not a fanciful example -- a Repository is 1323 occasionally duplicated for release purposes in which case *all* the 1324 paths in the two Repositories are the same. 1325 1326 Last modified: _6/13/1997_ 1327 1328 4. Who should administer the Repository and manage the modules file? 1329 1330 This is a "management style" question. In large or traditional groups, 1331 the CVS procedures are warped to conform to local conventions. In 1332 small groups, in groups with strong personalities or on new projects 1333 the choice of source control procedures can help create some of the 1334 working environment. Here is a taxonomy of environments I have worked 1335 in or helped set up: 1336 1337 Situation 1. 1338 1339 A small number of competent developers working on a medium size 1340 project. We all got along and we all respected each other (at least 1341 technically). Anyone edited anything. 1342 1343 Modules and Repository admin was mostly left to me. I never found a 1344 problem in minor changes made by anyone else. 1345 1346 Situation 2. 1347 1348 A large number of experienced developers sprinkled with wackos. Many 1349 of the developers didn't want to deal with any kind of source control. 1350 They wanted a full-service source control system that caused them zero 1351 thought. 1352 1353 I learned "big stick" diplomacy here. There was a small number of 1354 "designated" (by me) people who were allowed to do *anything* other 1355 than "update" and "commit". Even "checkouts" were controlled. This is 1356 where I found "history" and "release" the most useful. 1357 1358 Situation 3. 1359 1360 A small number of developers who wanted me to "help", but who didn't 1361 want to deal with anything other than their favorite algorithms. 1362 1363 I didn't have the time to baby-sit this group, so I designated one of 1364 them to be my official contact and made him do it all. He felt sullied 1365 by the requirement to pay attention to anything other than his pet 1366 coding projects, but enjoyed the "status" of being the only one who 1367 could touch the control files without my kicking the chair out from 1368 under him. 1369 1370 Situation 4. 1371 1372 A huge number of developers of covering the whole spectrum of 1373 competence and experience split into 20 groups, none of which 1374 cooperated with the others, working on 57 different projects, most of 1375 which didn't inter-operate. 1376 1377 Managing it in any coherent way was not my responsibility (and beyond 1378 my tolerance for chaos). Too many people. So I privately designated a 1379 person in each group to be the contact and kept watch on the 1380 Repository activity. When something went wrong, I notified the contact 1381 for the group and told him what was happening and *he* kept his troops 1382 in line. They were tougher with their own group that I would have 1383 been. 1384 1385 Eventually only a few people were willing to touch the control files, 1386 since they were flamed from all directions if they screwed up. 1387 1388 Situation 5. 1389 1390 In a medium group of really *serious*, and seriously overworked, 1391 people, someone else was designated the "master". I convinced the 1392 master I knew what I was doing and went on my way. 1393 1394 No one else in the world was allowed to touch anything. 1395 1396 Situation 6. 1397 1398 In a large amorphous group of beginners, experts and clowns, over whom 1399 no one had official control, I was forced to employ a group of 1400 relative beginners (who became experts rather quickly) to police the 1401 world. The ultimate in locking the barn after the horse was stolen, we 1402 kept Chaos from destroying us only by use of superior firepower. 1403 1404 My choice, if allowed, is to let anyone touch anything. I keep backups 1405 of important items and let people know individually whether I want 1406 them to touch things or not. If someone on my "no touch" list touches 1407 and succeeds, they are allowed more slack. If they screw up after 1408 being warned, their screwup becomes public. After a few months, I 1409 usually have no trouble keeping the world running smoothly, at least 1410 from my (and CVS's) perspective. 1411 1412 Last modified: _6/13/1997_ 1413 1414 5. Isn't disk space a big factor? CVS copies files out of the Repository, 1415 duplicating everything. 1416 1417 Everyone knows that disk space is getting cheaper. How do we reconcile 1418 this with the equally well-known problem that *all* disk is *always* 1419 filled up? 1420 1421 In my opinion, the main reason disk space will never be an unlimited 1422 resource is that it is the major variable in organizational time/space 1423 tradeoffs. It isn't a problem of waste or an aspect of Murphy's law, 1424 as some claim it is, but rather a direct consequence of good 1425 management. Disk space is, and will always be, a limited resource. 1426 1427 First, the cost of *deploying* that disk is not dropping as fast as 1428 the cost of the storage medium. The cost of machines to hold the disks 1429 and the networks to connect them are dropping more slowly than disk 1430 media. And the cost of the human time necessary to manage the 1431 machines, networks, disks, and the developers using them, is not 1432 dropping at all. The cost of human time continues to rise. 1433 1434 If management decides that expensive human time can be saved by using 1435 all that new disk space to keep the last three releases online, then 1436 that's what it will be used for. If each release takes up a Gigabyte 1437 and you support 30 platforms, a simple time-saving suggestion has just 1438 grabbed 100 Gigabytes of disk space. And we've ignored the potential 1439 disk storage needed to support "better Customer Service", another 1440 management refrain. 1441 1442 Even at 30 cents per Megabyte (next year's price), you've just used up 1443 $30,000 of disk space. And that doesn't count the computers, tape 1444 drives and humans necessary to maintain and deploy all of it. Spending 1445 money to save time has its own overhead, too. 1446 1447 Binaries are getting bigger. Graphics and data collection devices can 1448 eat up any amount of disk. There are more tools available, more 1449 libraries, more raw data than you can ever store. My home computer has 1450 a Gigabyte of disk on it. It could easily handle 30. 1451 1452 The "economy" of disk storage media will never remove the need to 1453 manage disk space. 1454 1455 So, here's an un-reviewed suggestion originally from Graydon Dodson 1456 <grdodson@lexmark.com>, which I've altered and edited heavily. 1457 1458 - Keep a directory where the whole tree is checked out. (It might be 1459 built and tested once in a while to make sure it is worth linking to, 1460 but that doesn't affect the source control aspect of this procedure). 1461 Let's call it /master/build. 1462 1463 - Write a tool that creates a tree of directories (like the X11 1464 "lndir" command) filled with links to the checked out files in the 1465 /master/build tree. 1466 1467 This tool should also provide real copies of, not symlinks to, all the 1468 files within the CVS administrative directories. 1469 1470 - You could also provide a way for the tool to take a list of whole 1471 directories that you will never change, for which it would create a 1472 single symlink to the directory and not a subtree of symlinks to 1473 files. Or you could rm -r pieces of the resulting working directory 1474 yourself and replace it with links. 1475 1476 - If you want to edit a file, you have to grab a real copy and keep it 1477 until your revision shows up in the /master/build tree. I'd create a 1478 script to do this: cvsgrab <file> 1479 1480 #!/bin/csh -f 1481 set f = $1 1482 if (! -l $f) then 1483 echo "file $f is not a symlink" 1484 exit 1 1485 endif 1486 rm $f 1487 set rev = `grep "^/$f/" CVS/Entries | awk -F/ '{print $3}'` 1488 cvs update -p -r $rev $f > $f 1489 1490 You can't do a plain "cvs update" since that would grab newer 1491 revisions from the Repository, not the revision you wanted to start 1492 with. After the file is no longer a symlink, you can work normally. 1493 You'll have to run "update" before "commit" anyway if there are newer 1494 revisions. 1495 1496 - Presumably there would also be a tool to traverse the link tree and 1497 revert it to links if there are no modified files and/or if all the 1498 real files match the revision of the /master/build tree. 1499 1500 - To avoid confusing CVS when the /master/build revisions are updated 1501 but your CVS/Entries files is not, CVS would have to change to handle 1502 symlinks. It currently causes problems with this scenario: 1503 1504 ./<file> is a symlink. 1505 1506 ./CVS/Entries says you are revision 1.2. 1507 1508 The corresponding CVS/Entries file in /master/build says the latest 1509 revision is 1.3. 1510 1511 cvs update <file> shows a 'C' conflict flag. 1512 1513 Last modified: _6/13/1997_ 1514 1515 Category: /Advanced_Topics_/Installing_CVS/ 1516 1517 " + Installing CVS" 1518 1519 1. What do I have to do before I install CVS? 1520 1521 You must decide where to set up a Repository. 1522 1523 Though you can construct a Repository tree structure using links and 1524 mount points, there must be a single copy of each real file across 1525 your entire organization. You may not "rdist" files and expect to edit 1526 both copies. 1527 1528 CVS does not support a truly distributed Repository. You can have 1529 multiple Repositories, but each one must be mounted (not copied or 1530 "rdist"ed) from a single place onto all machines where it will be 1531 used. 1532 1533 Initially, a Repository takes about same amount of disk space as the 1534 sources you want to put into it, plus a bit of overhead for the RCS 1535 files. 1536 1537 See Section 4B. For multiple Repositories, see 4G.3 1538 1539 You need a directory in everyone's $PATH variable where you can 1540 install all the executables. /usr/local/bin is a common place. 1541 1542 You need some helper tools besides CVS such as "RCS" and a good set 1543 of "diff" and "diff3" programs. See 1B.4 for suggestions. 1544 1545 Read the README, INSTALL and ChangeLog files to see what you are 1546 getting into. 1547 1548 Though you can probably muddle along without it, you should appoint 1549 one or more "Repository Administrators" who will be responsible for 1550 maintaining the Repository structure, administrative files and the 1551 "modules" interface. 1552 1553 Someone at your site should probably be on the info-cvs mailing list. 1554 See 1B.5. 1555 1556 Last modified: _6/13/1997_ 1557 1558 2. How do I configure the CVS programs? 1559 1560 You should certainly start by reading the README file, the INSTALL 1561 files and possibly the ChangeLogs in each directory, the Makefile.in 1562 files and the "cvsinit.sh" program. 1563 1564 Execute the ./configure command. 1565 1566 Type "make". 1567 1568 After running "make" you might try running the "sanity.sh" script: 1569 ./src/sanity.sh `pwd`/src/cvs 1570 1571 It writes into /tmp/cvs-sanity by default. 1572 1573 Finish reading the INSTALL file and test out the system. 1574 1575 Last modified: _6/13/1997_ 1576 1577 3. What do I have to install? 1578 1579 Install the "cvs" executable and "mkmodules" from the CVS sources. 1580 The man page is useful too. If you plan to report bugs, you should 1581 also install "cvsbug". 1582 1583 Set your $CVSROOT environment variable and create the Repository 1584 (which you planned out in 4A.1) with the "cvsinit" command at the top 1585 of the CVS sources. 1586 1587 You'll need to edit the Repository control files created by 1588 "cvsinit". 1589 1590 Install any helper programs mentioned in the modules file. 1591 1592 Last modified: _6/13/1997_ 1593 1594 4. How do I work around the merge problems in GNU diff version 2.1 or 1595 later? 1596 1597 See 1B.4 If you use recent versions of RCS and "diff", you won't run 1598 into the above. If you do, see 5B.8 1599 1600 Last modified: _6/13/1997_ 1601 1602 Category: /Advanced_Topics_/Internal_errors/ 1603 1604 " + Internal errors" 1605 1606 1. Explain: "ci error: unexpected EOF in diff output" 1607 1608 RCS versions earlier than 5.5 print the above error when a file does 1609 not end in a newline character. It can be caused by: 1610 1611 - Editing with Emacs and not using "require-final-newline". 1612 - Committing a binary file. 1613 - Filesystem failures (NFS!) that put nulls in your file. 1614 1615 The solution is to upgrade to RCS 5.5 or later. (Of course, this won't 1616 fix filesystem failures. It will merely allow RCS (and therefore CVS) 1617 to handle the file without error.) 1618 1619 Last modified: _6/13/1997_ 1620 1621 2. Explain: "RCS file /Repository/module/file.c,v is in use" 1622 1623 This is an RCS error that occurs when its internal lock file has been 1624 left around by an RCS command interrupted by some sort of system 1625 crash, disk failure or SIGKILL signal. 1626 1627 Go into the Repository and look for files with names similar to 1628 "file.c,v", usually starting with ',', '_' or '#'. Make sure they are 1629 really crash remnants and do not belong to transactions in progress -- 1630 a recent last-modified timestamp is a good indicator of a live 1631 transaction. Delete them if they are old. 1632 1633 Last modified: _6/13/1997_ 1634 1635 3. Explain: "co error, line 2: Missing access list" 1636 1637 This is an error message from RCS Version 3 when it tries to read a 1638 file created by a later version of RCS. 1639 1640 HP decided to "standardize" on an ancient version of RCS some time 1641 ago. You can't use it for CVS. See 4H.6. 1642 1643 Since the error comes from having a later version of RCS than HP 1644 supports, you probably did install the later version but must have 1645 recently changed your $PATH or installed the HP package that has RCS 1646 in it. 1647 1648 You should either reconfigure CVS to use absolute pathnames to the 1649 proper versions of the RCS programs that CVS uses, or change your PATH 1650 to look there first. If you haven't installed the latest version of 1651 RCS, you should upgrade. See 1B.4 1652 1653 Last modified: _6/13/1997_ 1654 1655 4. Explain: "error: RCS file name `xyz .c' contains white space" 1656 1657 RCS 5.6 doesn't allow white space in filenames. Apparently this 1658 restriction will be removed in RCS 5.7, but CVS may still require that 1659 filenames have no white space in them. 1660 1661 Last modified: _6/13/1997_ 1662 1663 5. Explain: cvs checkout: warning: <X> is not (any longer) pertinent 1664 1665 This message occurs in three instances: 1666 1667 When there is an entry in the ./CVS/Entries for file <X> and there 1668 is no RCS file in the Repository to back it up. 1669 1670 If the working file exists, and hasn't changed (determined from the 1671 timestamp) it is removed. 1672 1673 When you try to check out a piece of the Repository with: 1674 1675 cvs checkout some/place/in/repository/tree 1676 1677 and at least the first element of the path (i.e. "some" in the above) 1678 exists, but some part of the rest of it does not. 1679 1680 The checkout command checks the modules file first for the whole path, 1681 then for a prefix of the path as a module name. If it doesn't find 1682 *any* portion of your path in the modules file, it says: 1683 1684 cvs checkout: cannot find module `<module/path>' - ignored 1685 1686 If it finds some set of prefix directories, it prints the message you 1687 see. 1688 1689 In practice this is usually a spelling error. 1690 1691 If the Repository files you are trying to check out or update are 1692 not readable by you, the same problems can occur. Check the 1693 permissions on the files involved. 1694 1695 Last modified: _6/13/1997_ 1696 1697 6. Why did a Repository file change from <file>,v to ,<file>,? 1698 1699 This is an RCS problem, since the ,<file>, syntax for file names is 1700 used by RCS and not CVS. 1701 1702 RCS constructs a new <file>,v in a temporary file named ,<file>, 1703 (which doubles as a lock file) then renames it to <file>,v when it is 1704 done. The only way this is reliable is if your system's version of 1705 rename(2) is an atomic, as required by POSIX. 1706 1707 If your system has a non-atomic (and therefore non-POSIX) rename(2) 1708 system call, RCS runs uses an internal version of this algorithm to 1709 approximate the atomic rename: 1710 1711 rm <file>,v; ln ,<file>, <file>,v; rm ,<file>, 1712 1713 If the system crashes, or you lose your NFS connection between the 1714 first "rm", but before the "ln", you can be left only with the 1715 ,<file>, file. If the crash or network failure occurs between the "ln" 1716 and the final "rm", you could be left with a pair of linked names. 1717 1718 Recovery: 1719 - If only the ,<file>, exists, rename it to <file>,v. 1720 1721 - If both ,<file>, and <file>,v exist and are linked, remove the 1722 ,<file>, file. 1723 1724 - If both ,<file>, and <file>,v exist and are separate files, look at 1725 the dates, "diff" them and make your best guess. This sounds like the 1726 remnants of two separate events. 1727 1728 Last modified: _6/13/1997_ 1729 1730 Category: /Advanced_Topics_/Other_Systems/ 1731 1732 " + Other Systems" 1733 1734 1. I use a NeXT. Is there anything I need to know? 1735 1736 NeXTSTEP 3.0's Interface Builder uses "nib" directories, rather than 1737 the files used in previous revisions. It removes files it doesn't 1738 recognize, making it impossible to place such a directory under CVS -- 1739 the CVS admin directory will be removed. 1740 1741 Some time ago, <Bob_Vadnais@pdh.com> posted a palette named CVSPalette 1742 that claimed to resolve this problem. It was intended to preserve the 1743 CVS administrative directories within nib documents (directories) that 1744 Interface Builder usually removes. 1745 1746 CVSPalette is no longer in its announced place: 1747 1748 ftp.cs.orst.edu:/pub/next/submissions 1749 1750 though I did find two other interesting files on ftp.cs.orst.edu: 1751 1752 /software/NeXT/sources/tools/cvs-next-2_1_1.tar.Z 1753 1754 which is a port of CVS 1.3 (along with RCS and diff) and: 1755 1756 /software/NeXT/sources/programming/cvs.postamble-2.4.gz 1757 1758 which appears to be a set of wrappers for CVS commands that claim to 1759 allow you to use CVS effectively (and without need for the "command 1760 line") on a NeXT machine. 1761 1762 [[Anyone know the truth about CVS and NeXT?]] 1763 1764 Last modified: _6/13/1997_ 1765 1766 2. I use OS/2 and/or DOS and/or Windows. Is there anything I need to know? 1767 1768 When using a local repository, be sure to specify the local access 1769 method or CVS will interpret the drive letter as a remote host name 1770 due to the : following it: 1771 1772 WRONG: CVSROOT=C:\SRC\CVSROOT 1773 1774 RIGHT: CVSROOT=:local:C:\SRC\CVSROOT 1775 1776 (larry.jones@sdrc.com) 1777 1778 You can share RCS files between Unix and DOS while avoiding the MS-DOS 1779 file name limits by setting your RCSINIT environment variable to 1780 '-x/,v'. New RCS files will be created without the standard ",v" 1781 suffix, though files ending in ",v" will still be found if there is no 1782 matching file in the same directory without the ",v". 1783 1784 Erik van Linstee offers an OS/2 and a DOS port of CVS 1.3 in: 1785 1786 ftp.informatik.tu-muenchen.de:/pub/comp/os/os2/gnu/devtools or 1787 ftp.rrzn.uni-hannover.de:/pub/os2-local 1788 1789 The files are named: 1790 1791 cvs13p?[bs].zip 1792 1793 Where the ? stands for the patch level (currently 8) and the b is for 1794 the binaries, the s for the sources. 1795 1796 There are three binaries. An OS/2 only one (32-bit), a DOS only one 1797 (16-bit) and an EMX one that runs on both (32-bit). 1798 1799 There are many differences between the Unix and the DOS versions of 1800 CVS. Read the material that comes with the DOS version before using 1801 it. 1802 1803 [[Updates?]]. 1804 1805 Last modified: _9/22/1997_ 1806 1807 3. I use SCO Unix. Is there anything I need to know? 1808 1809 On SCO/UNIX 3.2 V2.0 POSIX signals don't work. Unfortunately the 1810 configure program detects POSIXness and configures in the use of POSIX 1811 signals. Workaround : Edit out the check for POSIXness in the 1812 configure script. [[You could also remove all occurrences of 1813 "-DPOSIX=1" from the Makefiles after configure is run. -dgg-]] 1814 1815 SCO/UNIX doesn't understand #!/<some shell> syntax. This breaks the 1816 use of log.pl as it gets invoked by /bin/sh instead of 1817 !#/usr/local/bin/perl. WorkAround : edit log.pl and change it into a 1818 shell script which invokes perl with log.perl (renamed from log.pl) as 1819 input. 1820 Contributed by Joe Drumgoole 1821 1822 Last modified: _6/13/1997_ 1823 1824 4. I use AIX. Is there anything I need to know? 1825 1826 The only report on AIX claims to have no trouble using it in concert 1827 with SunOS and IRIX platforms. 1828 1829 Last modified: _6/13/1997_ 1830 1831 5. I use IRIX. Is there anything I need to know? 1832 1833 If you see "uid" numbers where you would expect user names, try adding 1834 -lsun to the link line. Without it CVS is unable to retrieve "passwd" 1835 data through NIS. 1836 1837 Last modified: _6/13/1997_ 1838 1839 6. I use an HP system. Is there anything I need to know? 1840 1841 HP distributes RCS version 3 (a circa 1983 release!) with HP-UX. CVS 1842 does not work with RCS version 3; it requires RCS version 4 or later. 1843 Your best bet is to find the latest version of RCS and install it 1844 somewhere. 1845 1846 HP-UX 8.07 has a serious bug with the mmap system call and NFS files; 1847 the bug can crash the operating system. Make sure that you configure 1848 RCS to avoid mmap by setting has_mmap to 0 in RCS's conf.h. This bug 1849 is fixed in HP-UX 9. 1850 1851 Contributed by Paul Eggert 1852 1853 If using the setgid() trick described in 4D.13, you will have to 1854 create an entry in the /etc/privgroup file to give the group assigned 1855 to the cvs executable setgid permission (see setprivgrp(1m)). 1856 Additionally, if you are restricting "read" access to the Repository 1857 by limiting access to the executable (this requires yet another 1858 group), then you will require that /etc/logingroup exists and is 1859 configured correctly (usually it's just alink to /etc/group). 1860 1861 Contributed by Dale Woolridge 1862 1863 Last modified: _6/13/1997_ 1864 1865 7. I use AFS. Is there anything I need to know? 1866 1867 There is a problem with the way CVS performs its locking when the 1868 files are within AFS. When your current PTS id != your uid, the locks 1869 are not deleted. The stat() system call returns the PTS id of the 1870 owner. If that id != your uid, CVS assumes you did not lock it, and 1871 leaves the lock files alone. The next time you try to use it, it 1872 complains that someone has the repository locked. 1873 1874 Contributed by Michael Ganzberger 1875 1876 [[This was against CVS 1.3. Is it still in CVS 1.4?]] 1877 1878 Last modified: _6/13/1997_ 1879 1880 8. I use A/UX. Is there anything I need to know? 1881 1882 [[??]] 1883 1884 Last modified: _6/13/1997_ 1885 1886 Category: /Advanced_Topics_/Related_Software/ 1887 1888 " + Related Software" 1889 1890 1. How do I use CVS under Emacs? Is there an Emacs cvs-mode? 1891 1892 The pcl-cvs package distributed with CVS is an emacs package that 1893 helps with the update/commit process. When you are ready to update, 1894 you use the 'cvs-update' command within emacs. This executes "update" 1895 and fills a cvs-mode buffer with a line for each file that changed. 1896 The most helpful features are: descriptive words for what happened 1897 (i.e. Merged or Conflict rather than 'U' or 'C'), single keys bound to 1898 diffs and commits, and the ability to mark arbitrary groups of files, 1899 possibly from different directories, for commit as a whole. 1900 1901 All the developers in my group that use emacs find pcl-cvs a much 1902 friendlier and more helpful way to update/commit than raw cvs. One vi 1903 user even converted to emacs just to use pcl-cvs. 1904 1905 Contributed by Jeffrey M Loomis 1906 1907 Last modified: _6/13/1997_ 1908 1909 2. What is GIC (Graphical Interface to CVS)? 1910 1911 1912 1913 1914 GIC provides a graphical user interface to the Concurrent Version 1915 System (CVS), a powerful revision control system. GIC is 1916 implemented in the Tcl/Tk programming language and is intended to 1917 augment the sometimes cumbersome CVS command line interface. 1918 1919 Note that according to the official GIC page at 1920 http://www.cpsc.ucalgary.ca/redirect/grouplab/projects/gic/ 1921 GIC is no longer being maintained and tkCVS is recommended 1922 instead. 1923 1924 For more on tkCVS, see 1925 <http://ximbiot.com/cvs/cvshome/dev/addontkcvs.html>. 1926 1927 kingdon@cyclic.com 1928 1929 Last modified: _9/6/1997_ 1930 1931 3. What is CAVEMAN? 1932 1933 CAVEMAN is a front end to CVS written in PERL providing a collection 1934 of features desired by the site where it was developed. 1935 1936 - The ability to spread a "project" over multiple Repositories. 1937 - Optional automatic tagging after each commit. 1938 - Additional locking of files. 1939 - Extra before and after program hooks. 1940 - A layer of event logging. 1941 - All sorts of error messages. 1942 - Many changes to the semantics of commands. 1943 1944 It is available via anonymous ftp on ftp.llnl.gov [128.115.54.18] in 1945 gnu/caveman_vX.Y.Z.tar.gz (The numbers X, Y, & Z vary.) 1946 1947 contact Kathleen Dyer kdyer@llnl.gov 1948 (510)423-6803 1949 (510)423-5112 FAX 1950 1951 [[Does someone want to elaborate?]] 1952 1953 Last modified: _6/13/1997_ 1954 1955 Category: /Advanced_Topics_/Setting_up_and_Manag/ 1956 1957 " + Setting up and Managing the Repository" 1958 1959 1. What do I do first? How do I create a Repository? 1960 1961 First, install all the programs. (See Section 4A.) 1962 1963 Then create a Repository by executing "cvs -d init". (This works with 1964 CVS 1.9.) 1965 1966 Now you can configure your repository by checking out CVSROOT: "cvs -d 1967 checkout CVSROOT". Change into the created directory CVSROOT. Edit the 1968 files you want to edit, and afterwards, commit the changes by typing 1969 "cvs commit". 1970 1971 You will certainly want to add modules of your own. Edit the "modules" 1972 file and add lines to describe the items you want to "checkout" by 1973 module name. Here's a short list that could be used for storing a 1974 small number of GNU and PD sources: 1975 1976 local local 1977 1978 gnu local/gnu 1979 emacs local/gnu/emacs 1980 cvs local/gnu/cvs 1981 1982 public local/public 1983 pdprog1 local/public/pdprog1 1984 pdprog2 local/public/pdprog2 1985 1986 test test 1987 junk test/junk 1988 1989 Andreas Kostyrka 1990 1991 Last modified: _4/21/1998_ 1992 1993 2. What are those files in $CVSROOT/CVSROOT? 1994 1995 There are eight Repository control (or "database") files of interest 1996 in the CVSROOT directory: 1997 1998 modules contains the "modules" database. See 1D.11, 2C.7, 4B.6 and 1999 4B.7 for more details. 2000 2001 commitinfo contains two columns: 1. a regular expression to match 2002 against pathnames within the Repository and 2003 2004 a <command> to execute for matching pathnames. 2005 2006 When you execute "commit", CVS passes the Repository pathname for each 2007 directory (and the files to commit within that directory) to 2008 <command>. If <command> exits with a non-zero status, the commit is 2009 blocked. 2010 2011 A <command> associated with a pathname of "DEFAULT" is executed if 2012 nothing else matches. Every <command> associated with a pathname of 2013 "ALL" is executed separately. 2014 2015 rcsinfo contains the same first column as commitinfo, but the second 2016 column is a template file for specifying the log entry you are 2017 required to enter for each commit. 2018 2019 "DEFAULT" and "ALL" work the same as in the commitinfo file. 2020 2021 editinfo contains the same two columns as commitinfo, but the 2022 <command> in the second column is intended to do some consistency 2023 checking on the commit log. 2024 2025 "DEFAULT" works as in commitinfo. 2026 2027 loginfo contains the same two columns as commitinfo, but the 2028 <command> is expected to read a log message from its standard input. 2029 The <command> can do anything it wants with the log information, but 2030 normally it is appended to a log file or sent to mailing lists. 2031 2032 "DEFAULT" & "ALL" work the same as in commitinfo. 2033 2034 cvsignore contains "ignore" patterns that are added to the built-in 2035 ignore list. See 2D.10. 2036 2037 checkoutlist contains a list of other files kept under RCS in 2038 $CVSROOT/CVSROOT that should be checked out by mkmodules to provide a 2039 readable copy. 2040 2041 history contains a stream of text records, one for each event that 2042 the "history" command is interested in. Though the contents of the 2043 history file can be read, it is intended to be read and displayed by 2044 the "history" command. This file is the only one in the above list 2045 that is not under RCS. 2046 2047 Last modified: _6/13/1997_ 2048 2049 3. Is there any other state stored in the Repository besides in the 2050 $CVSROOT/CVSROOT directory? 2051 2052 Only in the RCS files. The Repository holds exactly two things: the 2053 tree of RCS files (each usually ending in ",v") and the CVSROOT 2054 directory described above. 2055 2056 Last modified: _6/13/1997_ 2057 2058 4. How do I put sources into the Repository? 2059 2060 There are three main ways to put files in the Repository: 2061 2062 Use the "import" command described in Section 3H. 2063 2064 This method is the fastest way to put trees of new code into the 2065 Repository and the *only* way to handle source releases from a 3rd 2066 party software vendor. 2067 2068 Use "add" followed by "commit". 2069 2070 This is how to add new files and directories to the Repository, a few 2071 at a time. Directories don't need to be committed. 2072 2073 You can move RCS files directly into the Repository. 2074 2075 You should create a directory hierarchy to hold them, but you can just 2076 move arbitrary ",v" files into the Repository. The only "state" in the 2077 Repository other than within ",v" files is in the required CVSROOT 2078 directory at the top of the Repository. 2079 2080 Last modified: _6/13/1997_ 2081 2082 5. What file permissions should I use on (and in) the Repository? 2083 2084 If you are using pserver (password-authenticated access), see below. 2085 2086 If you run a completely open environment (which usually means that you 2087 don't have, or don't want to waste, the time to deal with it): 2088 2089 - Set all directory permissions to 777. 2090 2091 - Have everyone set their umasks to 0. 2092 2093 (BTW, I don't suggest this. I am merely reporting it.) 2094 2095 If you are a normal Unix shop and want to use groups effectively: 2096 2097 - Set all the directory permissions in the Repository to 775. 2098 2099 If you are using a system that handles both System V and BSD 2100 filesystems, you might have to set the permissions to 2775.) 2101 2102 If you are using one of the many recent versions of Unix that don't 2103 allow you to use the full octal mode, then you'll have to type: chmod 2104 u=rwx,g=rwx,o=rx,g+s dir> 2105 2106 - Change all the groups on the directories to match the groups you 2107 want to write to various directories. 2108 2109 - Make sure every user is in the appropriate groups. 2110 2111 - Have everyone set their umask to 002, including root. 2112 2113 If you don't want non-group members to even read the files, do the 2114 above, but change: 2115 2116 - Repository directory permissions to 770. (or 2770) 2117 2118 - umasks to 007. 2119 2120 If you work in an environment where people can't be trusted to set 2121 their "umask" to something reasonable, you might want to set the umask 2122 for them: 2123 2124 mv /usr/local/bin/cvs /usr/local/bin/cvs.real 2125 cat > /usr/local/bin/cvs 2126 #!/bin/sh 2127 umask 2 # Or whatever your site standard is. 2128 exec /usr/local/bin/cvs.real ${1+"$@"} 2129 ^D 2130 2131 Pserver (Password-Authenticated Access) <blome@de.ibm.com> 2132 2133 The above suggestions are not valid when you use the pserver facility. 2134 Be sure to read and understand the manual section about this (should 2135 be 4.6.something). Above all: do /not/ make the repository and CVSROOT 2136 group writeable. In CVSROOT, make `history� group or world writeable 2137 instead. 2138 2139 I suggest creating one unix group per project group. In the 2140 repository, you would then create one directory for each group, group 2141 writeable. New projects must then be created in these group 2142 directories. If you don't want to say <group>/<project> on 2143 checkout, create a <project> module and point it there. 2144 2145 Last modified: _9/24/1998_ 2146 2147 6. How do I structure my Repository? 2148 2149 The Repository holds your software. It can be all interrelated or it 2150 can be a bunch of separately managed directories. 2151 2152 How you break a whole system down into its component parts, while 2153 defining interfaces between them, is one aspect of "Software 2154 Engineering", a discipline that requires the study of dozens of 2155 strange and wonderful areas of the computer and management worlds. 2156 2157 CVS provides a way to keep track of changes to individual files, a way 2158 to "tag" collections of files, and a way to "name" collections of 2159 files and directories. That's all. Everything else is in the way you 2160 apply it. 2161 2162 In other words, you should structure your Repository to match your 2163 needs, usually tied in with the other tools you use to build, install 2164 and distribute your work. Common needs include the ability to: 2165 2166 - mount (or automount) directories from many places in your 2167 organization. 2168 - check out just what you need and no more. 2169 - check out multiple sections in a fixed relation to each other. 2170 - check out large sections to match the assumptions built into your 2171 build system. (Makefiles?) 2172 2173 In my opinion, you should start small and keep everything in one tree, 2174 placing each major sub-system into a separate directory. Later, when 2175 you know what you are doing, you can make it more sophisticated. 2176 2177 Last modified: _6/13/1997_ 2178 2179 7. Why would anyone use "modules"? They are too restrictive. I want to be 2180 able to select just the files I want to edit. 2181 2182 Any form of structure is restrictive. If you believe that total chaos 2183 is a viable working paradigm, or if you believe you can keep track of 2184 the interrelations between all portions of your Repository in your 2185 head, then you can do what you please. 2186 2187 If you believe that systems of files require management and structure, 2188 then the "modules" idea is very useful. It is a way to impose a naming 2189 scheme on a tree of files, a naming scheme that can be simpler than a 2190 large list of relative pathnames. 2191 2192 The "modules" file represents a published interface to the Repository 2193 set up by your Repository Administrator. If s/he did a creditable job, 2194 the modules offered will be internally consistent and will smoothly 2195 interact with the rest of your environment. 2196 2197 Last modified: _6/13/1997_ 2198 2199 8. How do I rename a file or directory? What are the consequences? 2200 2201 In CVS there is no single "rename" command. 2202 2203 See 2C.4 for the suggested way to rename a file or directory. 2204 2205 The rest of this section covers some of the consequences of renaming. 2206 2207 A "renaming database" has been proposed that would keep track of name 2208 changes so that "update -r <tag>" would continue to work across the 2209 renaming. But as it stands, you have to pick one of the following 2210 options: 2211 2212 Use the technique described in 2C.4. (For each file, duplicate the 2213 file in the Repository, "remove" the old version so it winds up in the 2214 Attic and strip all Tags off the new version.) 2215 2216 - "update -r <tag>" produces the correct files. 2217 2218 - The duplicated revision history can be slightly misleading. 2219 2220 - A plain (i.e. without the "-r <tag>") "checkout" or "update -d" will 2221 create directories "renamed" this way, but you can delete it and a 2222 plain "update" won't bring it back. 2223 2224 Move the files and directories in the Repository to the new names. 2225 2226 - You save the revision history under a different file name. 2227 2228 - You save a little space. 2229 2230 - "update -r <tag>" produces the wrong files or directories. 2231 2232 This is not a good general solution, but if you plan never to look 2233 back (someone may be gaining on you!), it is sometimes a useful 2234 notion. 2235 2236 If you are clever with Makefiles, you might be able to rework them to 2237 handle either the new or old names, depending on which ones exist at 2238 the time. Then you can move an old <tag> onto the new, more 2239 sophisticated, revision of the Makefile. (Yes, this changes the 2240 "released" file if <tag> indicates a release. But it is an option.) 2241 2242 - Important Note: If you rename a directory, you must rename the 2243 corresponding directory in every checked-out working directory. At the 2244 same time, you must edit the pathname stored in the ./CVS/Repository 2245 file within each of the moved directories. 2246 2247 The easiest way to move a lot of directories around is to tell 2248 everyone to remove their working directories and check them out again 2249 from scratch. 2250 2251 - The file exists in the working directory and in the ./CVS/Entries 2252 file, but not in the Repository. For the old file, "update" prints: 2253 2254 cvs update: xyz.c is no longer in the repository 2255 2256 and deletes the file. If the file was modified, "update" prints: 2257 2258 cvs update: conflict: xyz.c is modified but no longer in the 2259 repository C xyz.c 2260 2261 and leaves the file alone. In the new directory, you see: 2262 2263 U xyz.c 2264 2265 as you would if someone else executed "add" and "commit". 2266 2267 For each file, copy the working file to a new name in the working 2268 directory and use the "cvs remove" to get rid of the old old file and 2269 "cvs add" to add the new one. Since there is no way for CVS to remove 2270 a directory, this only works for files. 2271 2272 - This is what most people think of first. Without a "rename" command, 2273 the remove/add technique seems obvious. 2274 2275 - You lose the connection of your new working file to its past 2276 revision history. 2277 2278 Last modified: _6/13/1997_ 2279 2280 9. What are "Attic" directories? 2281 2282 When you use the "remove" command on a file, CVS doesn't delete the 2283 file, it only registers your desire to delete it. 2284 2285 When you "commit" a removed file, CVS moves the Repository's matching 2286 RCS file into a sub-directory named "Attic" within the Repository. 2287 2288 Attic files are examined when the '-r' or '-D' option is used on 2289 "checkout" or "update". If the specified revision, tag or date matches 2290 one on a file in the Attic, that file is checked out with the others. 2291 2292 You can think of the Attic as a sort of dead branch, which is only 2293 looked at when you refer to a <tag> or <date>. 2294 2295 Last modified: _6/13/1997_ 2296 2297 10. Is it OK to remove anything from the Repository? 2298 2299 In general, removing anything from the Repository is a bad idea. The 2300 information in a deleted object is lost forever. There are many ways 2301 to skip over files, directories and revisions without deleting them. 2302 2303 Here are some of the consequences of removing the following things 2304 stored in the Repository: 2305 2306 CVSROOT files (Repository control files) 2307 2308 The Repository will work without any of them, but you should 2309 understand what you are losing by deleting them. See 4B.2. 2310 2311 Revisions 2312 2313 The only way to remove revisions is to use the "admin -o" command (or 2314 the equivalent RCS command "rcs -o"). 2315 2316 They are lost forever. Any tags formerly attached to deleted revisions 2317 are now pointing into the Phantom Zone. You'll need to contact Jor-el 2318 to get them back. 2319 2320 Files 2321 2322 You should not remove a file unless you truly never want to see it 2323 again. If you want to be able to check out an old revision of this 2324 file, use "cvs remove" instead. 2325 2326 Tags 2327 2328 Tags take up little space and you can't recover from deleting them. If 2329 you depend on tags for releases you will lose vital information. 2330 2331 Directories 2332 2333 There is no Attic for directories, so the only way to remove them is 2334 to use "rm -r". They are gone forever. 2335 2336 If you delete (or move) a directory, all checked-out versions of that 2337 directory will cause CVS to halt. You'll have to visit each 2338 checked-out directory and remove the matching working directory by 2339 hand. 2340 2341 Attic files 2342 2343 The "remove" command sends files to the Attic. To really delete them, 2344 you have to go into the Attic and use "rm". 2345 2346 If a file in the Attic has a Tag on it that you might ever want to 2347 check out again, you probably don't want to delete it. 2348 2349 Lock files (named: "#cvs.[wr]fl.<pid>") 2350 2351 These are lock files. If you are getting "lock" errors and the dates 2352 on the lock files indicate that they are old, you can delete them. 2353 2354 Deleting lock files still in use by a CVS process might produce 2355 unusual errors. 2356 2357 Last modified: _6/13/1997_ 2358 2359 11. Can I convert to CVS from RCS without losing my revision history? 2360 2361 Yes, you can simply move (or copy) your RCS files into a directory 2362 within the Repository, check out that directory and start working. 2363 2364 Last modified: _6/13/1997_ 2365 2366 12. Can I move RCS files with branches in them into the Repository? 2367 2368 Yes, but they may not work if you created branches in a way that 2369 conflicts with CVS's assumptions: 2370 2371 You can't use .0. branches. (They are reserved for "Magic" branch 2372 tags.) 2373 2374 If you use branch 1.1.1, you can't use the Vendor branch. 2375 2376 You can use other RCS branches under CVS. There is no need to create 2377 "magic" branch tags because the physical branch already exists. 2378 2379 Last modified: _6/13/1997_ 2380 2381 13. Can I use raw RCS commands on the Repository? 2382 2383 You can use raw rcs commands directly on the Repository if you take a 2384 little care. The Repository itself contains no "CVS state" (as opposed 2385 to RCS revision histories) outside the CVSROOT directory. 2386 2387 But using raw RCS commands to change branches, tags or other things 2388 that CVS depends on may render the files unusable. 2389 2390 See 4D.7 on RCS/CVS sharing of the Repository and Section 3B on the 2391 "admin" command. 2392 2393 Last modified: _6/13/1997_ 2394 2395 14. How do I convert from SCCS to RCS? 2396 2397 You'll have to execute something like "sccs2rcs" (in the CVS contrib 2398 directory) on every file. Then you can move the resulting RCS files 2399 into the Repository as described above. 2400 2401 Last modified: _6/13/1997_ 2402 2403 15. How do I limit access to the Repository? 2404 2405 There are all sorts of ways to restrict access to Repository files, 2406 none of which are hooked directly into CVS. 2407 2408 Techniques for limiting access include: 2409 2410 Training, management and good backups. 2411 2412 The best form of Repository control is a combination of: 2413 2414 - A reliable backup scheme (verify it!) 2415 - Enough training to ensure your developers are competent and 2416 knowledgeable about all areas of your sources. 2417 - Effective management of the boundaries and grey areas. 2418 2419 In many cases, technical solutions to "security" problems are 2420 inadequate. You should first try to avoid them. 2421 2422 Personal Opinion: In an environment where "unknowns" are allowed to 2423 touch important sources the "owner" of the CVS Repository must be a 2424 large, loud, vigorous lout with a well-balanced truncheon and the 2425 right to use it. Don't underestimate the effectiveness of letting 2426 everyone know they will be strapped into the stocks on the Town Common 2427 and pelted with vegetables if they break something they don't 2428 understand without first asking the experts. 2429 2430 Set Unix groups and permissions. See 4B.5. You can set different 2431 owners, groups and permissions for each sub-directory within the 2432 Repository if that helps. 2433 2434 Catch invocations of "commit" by defining pre-commit programs in the 2435 "commitinfo" file. This is fairly powerful, since it can block commits 2436 based on anything you can program. Take a look at the programs in the 2437 "contrib" directory of the CVS source tree. 2438 2439 Use multiple Repositories, each with its own protection scheme. If 2440 you use NFS (or AFS) you can even use "export" restrictions to various 2441 groups of machines to keep (for example) the Engineering Repository 2442 off the Customer Service machines. 2443 2444 Try the "setgid" trick described in 4D.13. 2445 2446 Try to use the RCS access control lists, though I don't think CVS 2447 will handle them cleanly. 2448 2449 Edit the source code to CVS to add your own access control. 2450 2451 Last modified: _6/13/1997_ 2452 2453 16. What are the Repository Administrator's responsibilities? 2454 2455 Generally, the Administrator should set "policy", create the 2456 Repository and monitor its size and control files. 2457 2458 Some specific responsibilities include: 2459 2460 Examining the Repository once in a while to clean up: 2461 2462 Trash files left by misguided developers who mistake the Repository 2463 for a working directory. 2464 2465 Non-RCS files. Other than the files CVS needs in the 2466 $CVSROOT/CVSROOT directory, every file in the Repository should be an 2467 RCS file. 2468 2469 Lock files (both CVS '#*' and RCS ',*' files) left around after 2470 crashes. 2471 2472 Wrong permissions, groups and ownerships. 2473 2474 Locked files. (RCS locks, that is.) 2475 2476 Attic files that should never have been under CVS at all. Don't 2477 blindly delete files from Attic directories -- they were mostly put 2478 there (via the "cvs remove") for a reason. Files that should be 2479 deleted are binary files (e.g. '*.o', 'core', executables) that were 2480 mistakenly inserted by "import -I !". 2481 2482 Maintaining the modules file. 2483 2484 Storing site-specific ignore patterns in the 2485 $CVSROOT/CVSROOT/cvsignore file. 2486 2487 Storing the names of non-standard CVSROOT files (See 4B.2) in the 2488 $CVSROOT/CVSROOT/checkoutlist 2489 2490 Maintaining the other Repository control files: commitinfo, loginfo, 2491 rcsinfo and editinfo. 2492 2493 Pruning the history file every once in a while. (Try the 2494 "cln_hist.pl" script in the "contrib" directory.) 2495 2496 Staying aware of developments on the info-cvs mailing list and what 2497 is available in the FTP and WWW archives. 2498 2499 Running "ps ax" once in a while and kill off any "update" programs 2500 not running as "root". It is too easy to leave the "cvs" off the front 2501 of the "cvs update" command. 2502 2503 Executing monitor programs to check the internal consistency of the 2504 Repository files. Ideas: 2505 2506 Files that have a default RCS branch that is not 1.1.1 (From an 2507 abuse of "admin -b".) 2508 2509 Files that have only Revisions 1.1 and 1.1.1.1, with a default 2510 branch of "MAIN". (From an abuse of "admin -o".) 2511 2512 Existing branch tags and various branch consistency checks. 2513 2514 Last modified: _6/13/1997_ 2515 2516 17. How do I move the whole Repository? 2517 2518 Copy or move the tree. (On Unix systems, a set of piped "tar" commands 2519 works great. If the Repository does not contain any symlinks, which it 2520 normally doesn't, you can also use "cp -r".) 2521 2522 If you can avoid changing $CVSROOT (i.e. the "logical" pathname of the 2523 Repository) by replacing the old location with a symbolic link to the 2524 new location, you don't have to do anything else. 2525 2526 (You could also mount the new location on top of the old location if 2527 you are using NFS or some other filesystem that allows it.) 2528 2529 If you must change $CVSROOT, you must also tell everyone to change the 2530 CVSROOT environment variable in all running shells and in any personal 2531 configuration files ('.' files on Unix) where it is set. 2532 2533 The Repository itself contains no references to its own name, except 2534 possibly in some of the files in the CVSROOT directory. If your 2535 modules (or loginfo, commitinfo, etc.) file mentions helper programs 2536 directly in the Repository, you'll have to change the pathnames to 2537 point to the new Repository location. 2538 2539 The main changes you'll have to make are to all the CVS administrative 2540 files (./CVS/Repository and ./CVS/Root) in every working directory 2541 ever checked out from the previous location of the Repository you just 2542 moved. 2543 2544 You have three choices: 2545 2546 If all ./CVS/Repository files in all working directories contain 2547 relative pathnames, you don't have to do anything else. 2548 2549 Have everyone "release" or delete their working directories (after 2550 committing, or just saving, their work) and check them all out again 2551 from the new Repository after the move. 2552 2553 Use "find . ( -name Repository -o -name Root )" and a PERL or shell 2554 script to run through all the ./CVS/Repository and ./CVS/Root files 2555 and edit the values in the files. 2556 2557 Last modified: _6/13/1997_ 2558 2559 18. How do I change permissions on a file in the Repository by using a CVS 2560 command? (i.e. without using "chmod 777 $CVSROOT/dir/file") 2561 2562 When you first "import" or "add"/"commit" a file, the read and execute 2563 bits on the Repository file are inherited from the original source 2564 file, while the write bits on the Repository file are are turned off. 2565 This is a standard RCS action. 2566 2567 After that, there is no way to alter the permissions on a file in the 2568 Repository using CVS (or RCS) commands. You have to change the 2569 permissions on both your working file and on the Repository file from 2570 which it was retrieved. 2571 2572 Whenever you "checkout" the file or retrieve a new revision via 2573 "update" (or after a "commit"), your working file is set to match the 2574 permissions of the Repository file, minus any "umask" bits you have 2575 set. 2576 2577 Last modified: _6/13/1997_ 2578 2579 Category: /Advanced_Topics_/Tricks_of_the_Trade/ 2580 2581 " + Tricks of the Trade" 2582 2583 1. How can you even check in binary files, let alone allow CVS to do its 2584 auto-merge trick on them? 2585 2586 2587First of all, if you want to use binary files, you should get RCS 5.7 2588and CVS 1.9 or later (earlier versions had some support, but there have been 2589bug fixes). Secondly, follow the instructions for installing RCS very 2590carefully (it is easy to get it installed so it works for everything 2591except binary files). 2592 2593Then, specify 'cvs add -kb' instead of just 'cvs add' to add a binary 2594file. If you want to set an existing file to binary, run 'cvs admin 2595-kb' (and then check in a new copy of the file). Note that old 2596versions of CVS used -ko instead of -kb for binary files, so if you 2597see a reference to -ko in the context of binary files, you should 2598think -kb instead. 2599 2600Of course when 'cvs update' finds that a merge is needed, it can't 2601do this for binary files the same way as for text files. With the 2602latest versions (e.g. CVS 1.9.14), it should be able to give you both 2603versions and let you merge manually. Another approach is to 2604run 'cvs admin -l' to lock files, as described in 2605"How can I lock files while I'm working on them the way RCS does?" 2606elsewhere in this FAQ. See also 2607"Is there any way to import binary files?" and 2608"How do I "add" a binary file?" elsewhere in this FAQ. 2609 2610kingdon@cyclic.com 2611 2612 Last modified: _9/6/1997_ 2613 2614 2. Can I edit the RCS (",v") files in the Repository? 2615 2616 Yes, but be very careful. The RCS files are not free-form files, they 2617 have a structure that is easily broken by hand-editing. The only time 2618 I would suggest doing this is to recover from emergency failures that 2619 are difficult to deal with using CVS commands, including the "admin" 2620 command, which can talk directly to RCS. 2621 2622 Though no one actively encourages the editing of RCS files, many 2623 people have succumbed to the urge to do so when pressed for time. The 2624 reasons given, usually with evident contrition, include: 2625 2626 - Editing mistakes in, or adding text to, log entries. (If you have 2627 RCS 5.6 or later, you should use `cvs admin -m'.) 2628 - Renaming or moving symbolic names. (You should `cvs admin -N' 2629 instead.) 2630 - Unlocking a file by changing the "locker" from someone else to 2631 yourself. (It's safer to use `cvs admin -u -l'.) 2632 - Making global changes to past history. Example: Eradicating former 2633 employees names from old documents and Author entries. (And someone 2634 thought the "history" command was evidence of Big Brother! I never 2635 realized how much help a wide-open revision control system could have 2636 provided to The Ministry of Truth.) 2637 2638 Last modified: _6/13/1997_ 2639 2640 3. Can I edit the ./CVS/{Entries,Repository,Tag} files? 2641 2642 Yes, but with CVS 1.3 and later, there is almost no reason to edit any 2643 of the CVS administrative files. 2644 2645 If you move pieces of your Repository around it can be faster to edit 2646 all the ./CVS/Repository files rather than checking out a large tree. 2647 But that is nearly the only reason to do so. 2648 2649 Last modified: _6/13/1997_ 2650 2651 4. Someone executed "admin -o" and removed revisions to which tags/symbols 2652 were attached. How do I fix them? 2653 2654 It depends on what you mean by "fix". I can think of three ways to fix 2655 your predicament: 2656 2657 Remove the tags. 2658 2659 Assuming you really wanted to get rid of the revision and its 2660 associated tags, you can remove them with the "admin" command. The 2661 "tag -d" command will only remove tags attached to existing revisions. 2662 You can remove a tag, even if it is attached to a non-existent 2663 revision, by typing: 2664 2665 cvs admin -N<tag> <file> 2666 2667 Retrieve the outdated revision. 2668 2669 You should first look in your backup system for recent versions of the 2670 file. If you can't use them, you can carefully extract each revision 2671 that followed the earliest outdated revision using RCS (or "cvs 2672 admin") commands and reconstruct the file with all the right 2673 revisions, branches and tags. This is a lot of work. 2674 2675 You *can't* insert a revision into the current RCS file. 2676 2677 Move the Tags to another revision in each file. 2678 2679 If you want to move the tags to another valid revision, you have two 2680 choices, both of which require that you find all the revision numbers 2681 of the files you want to "tag" and execute the following command 2682 sequences on each <file>. 2683 2684 Use "update" to grab the revision you want, then execute a normal 2685 "tag" command to Tag that revision: 2686 2687 cvs update -r <rev> <file> 2688 cvs tag <tag> <file> 2689 2690 Use "admin" to set the tag to a specific revision: 2691 2692 cvs admin -N<tag>:<rev> <file> 2693 2694 Last modified: _6/13/1997_ 2695 2696 5. How do I move or rename a magic branch tag? 2697 2698 (To rename a non-branch <tag> see 3O.9.) 2699 2700 Before reading this, read 3M.3 and 3M.4 and understand exactly how tag 2701 and rtag use '-r' and why it won't do the right job here. 2702 2703 First, I have to explain exactly what a magic branch tag is. 2704 2705 A magic <branch_tag> is an artificial tag attached to a non-existent 2706 revision on a non-existent branch number zero. It looks like this: 2707 2708 TAG1:<X>.0.Y 2709 2710 <X> is the "branch point revision", a normal revision with an 2711 odd number of '.'s in it. (e.g. 1.5, 1.3.1.6, etc) 2712 2713 Y is an even number (e.g. 2, 4, 6, etc.) All CVS branches, 2714 other than the Vendor branch, are even numbered. 2715 2716 TAG1 is considered by CVS to be attached to revision <X>. The first 2717 "update -r TAG1 <file>" after applying TAG1 will produce a copy of 2718 revision <X> with a sticky tag of TAG1. The first "commit" to that 2719 file will cause CVS to construct an RCS branch named <X>.Y and check 2720 in revision <X>.Y.1 on the new branch. 2721 2722 Note: TAG1 is *not* considered to be attached to <X> by RCS, which 2723 explains why you can't refer directly to the branch point revision for 2724 some CVS commands. 2725 2726 Moving a magic <branch_tag> is the act of reapplying the same tag to 2727 different revisions in the file: 2728 2729 TAG1:<X>.0.Y 2730 to 2731 TAG1:<X>.0.Z or TAG1:<A>.0.B 2732 2733 You can move a magic branch tag to the revisions of your choice by 2734 using "update" to find the revisions you want to tag and reapplying 2735 the tag to all the files with the '-F' option to force it to move the 2736 existing <branch_tag>. 2737 2738 cvs update -r <tag/rev> (or '-A' for the Main Branch) 2739 cvs tag -F -b <branch_tag> 2740 2741 If the earlier location of TAG1 refers to a physical branch within any 2742 RCS file, moving it will make the existing branch in the file seem to 2743 disappear from CVS's view. This is not a good idea unless you really 2744 want to forget the existence of those RCS branches. 2745 2746 If the "update" above retrieves the original branch point revision 2747 (<X>), the "tag" command above will create the tag: 2748 2749 TAG1:<X>.0.Z 2750 2751 Where Z is 2 greater than the highest magic branch already on revision 2752 <X>. The TAG1 branch will still have the same branch point (i.e. 2753 revision <X>), but the first commit to the new TAG1 branch will create 2754 a different RCS branch number (<X>.Z instead of <X>.Y). 2755 2756 Renaming a magic <branch_tag> is the act of changing 2757 2758 TAG1:<X>.0.Y 2759 to 2760 TAG2:<X>.0.Y 2761 2762 There is no harm in changing a tag name as long as you forget that 2763 TAG1 ever existed and you clean up any working directories with sticky 2764 TAG1 tags on them by using "update -A", "update -r <other_tag>" or by 2765 removing the working directories. 2766 2767 On the other hand, actually changing the tag is not easy. 2768 2769 See 3M.3 for why the seemingly obvious solution won't work: 2770 2771 cvs tag -b -r <old_branch_tag> <new_branch_tag> 2772 2773 The only direct way to rename a magic tag is to use the "admin" 2774 command on each file: (You might want to use '-n'. Read "man rcs" and 2775 look at the '-n' and '-N' options.) 2776 2777 cvs admin -N<new_branch_tag>:<old_branch_tag> . 2778 cvs tag -d <old_branch_tag> 2779 2780 But you have to be careful because "admin" is different from other CVS 2781 commands: 2782 2783 "admin" can be used recursively, but only by specifying directory 2784 names in its argument list (e.g. '.'), 2785 2786 Where "rtag -r <old_branch_tag>" would interpret <old_branch_tag> as 2787 a magic CVS branch tag, "admin" is a direct interface to RCS which 2788 sees a magic branch tag as a simple (though non-existent) RCS revision 2789 number. 2790 2791 This is good for us in this particular case, but different from normal 2792 CVS. 2793 2794 "admin" also skips the Attic and produces different kinds of errors 2795 than CVS usually does. (Because they are coming directly from RCS.) 2796 2797 The other way to rename a magic <branch_tag> is to edit the Repository 2798 files with a script of some kind. I've done it in the past, but I'll 2799 leave it as an exercise for the reader. 2800 2801 Last modified: _6/13/1997_ 2802 2803 6. Can I use RCS locally to record my changes without making them globally 2804 visible by committing them? 2805 2806 You can, but it will probably confuse CVS to have ",v" files in your 2807 working directory. And you will lose all your log entries when you 2808 finally commit it. 2809 2810 Your best bet is to create your own CVS branch and work there. You can 2811 commit as many revisions as you want, then merge it back into the main 2812 line (or parent branch) when you are finished. 2813 2814 Last modified: _6/13/1997_ 2815 2816 7. How can I allow access to the Repository by both CVS and RCS? 2817 2818 The first step is to try not to. If some people are using CVS, there 2819 is no reason for everyone not to. It is not hard to learn the basics 2820 and CVS makes certain operations *easier* than a series of RCS 2821 commands. Personal preference in what software tools can be applied to 2822 a shared Repository has to take second place to system integration 2823 needs. If you disagree, try writing some Lisp code for inclusion in 2824 your Unix kernel and see what kind of reception you get. 2825 2826 If you really must allow routine RCS access to the CVS Repository, you 2827 can link an RCS sub-directory into a piece of the Repository: 2828 2829 ln -s /Repository/some/directory/I/want RCS 2830 2831 and RCS will work just fine. 2832 2833 Those who are using RCS will have to keep the following in mind: 2834 2835 If a file was originally added to the Repository by "import" and has 2836 not been changed using CVS, the *RCS* default branch will remain 2837 attached to the Vendor branch, causing revisions checked-in by "ci" to 2838 wind up on the Vendor branch, instead of the main branch. Only CVS 2839 moves the RCS default branch on first commit. 2840 2841 The way around this is to checkin (using "ci") all the files first and 2842 move them into the Repository. That way they won't have Vendor 2843 branches. Then RCS will work OK. 2844 2845 It is possible to use "rcs" and "ci" to make the files unusable by 2846 CVS. The same is true of the CVS "admin" command. 2847 2848 Normal RCS practice locks a file on checkout with "co -l". In such 2849 an environment, RCS users should plan to keep survival gear and food 2850 for at least 30 days near their desks. When faced with bizarre and 2851 unexpected permission errors, howling mobs of slavering CVS users will 2852 run the RCS users out of town with pitchforks and machetes. 2853 2854 See 3C.8 for a way to avoid machetes aroused by lock collisions. 2855 2856 Though files checked in by RCS users will correctly cause 2857 "up-to-date" failures during CVS "commits" and they will be 2858 auto-merged into CVS working directories during "update", the opposite 2859 won't happen. 2860 2861 RCS users will get no warning and will not be required to merge older 2862 work into their code. They can easily checkin an old file on top of a 2863 new revision added by CVS, discarding work committed earlier by CVS 2864 users. 2865 2866 See the howling mob scenario described above. 2867 2868 RCS is great. I have used it for years. But I wouldn't mix it this 2869 way. In a two-camp society, you are asking for real trouble, both in 2870 technical hassles to clean up and in political hassles to soothe. 2871 Branch merges will also be a major problem. 2872 2873 Last modified: _6/13/1997_ 2874 2875 8. I "updated" a file my friend, "bubba", committed yesterday. Why doesn't 2876 the file now have a modified date of yesterday? 2877 2878 CVS restores dates from the RCS files only on first "checkout". After 2879 that, it is more important to maintain a timestamp relative to the 2880 other files in the working directory. 2881 2882 Example: You committed a source file at 5PM. Bubba updated his copy of 2883 the file, grabbing your changes, then changed and committed a new 2884 revision of the file at 6PM. At 7PM, you compile your file. Then you 2885 execute "update". If CVS sets the date to the one in the RCS file, the 2886 file would be given a timestamp of 6PM and your Makefile wouldn't 2887 rebuild anything that depended on it. Bad news. 2888 2889 Note that the same logic applies to retrieving a revision out of the 2890 Repository to replace a deleted file. If CVS changes your file in an 2891 existing working directory, whether it was because a new revision was 2892 committed by someone else or because you deleted your working file, 2893 the timestamp on the retrieved working file *must* be set to the 2894 current time. 2895 2896 When you first retrieve a file, there is no reason to expect any 2897 particular timestamp on the file within your working area. But later, 2898 when dependency checking is performed during a build, it is more 2899 important for the timestamps on the local files to be consistent with 2900 each other than than it is for working files to match the timestamps 2901 on the files in the Repository. See 4D.17 for some more about 2902 timestamps. 2903 2904 Last modified: _6/13/1997_ 2905 2906 9. Why do timestamps sometimes get set to the date of the revision, 2907 sometimes not? The inconsistency causes unnecessary recompiles. 2908 2909 The "checkout" command normally sets the timestamp of a working file 2910 to match the timestamp stored on the revision in the Repository's RCS 2911 file. 2912 2913 The "commit" command retains the timestamp of the file, if the act of 2914 checking it in didn't change it (by expanding keywords). 2915 2916 The "update" command sets the time to the revision time the first time 2917 it sees the file. After that, it sets the time of the file to the 2918 current time. See 4D.8 for a reason why. 2919 2920 Here's a two-line PERL program to set timestamps on files based on 2921 other timestamps. I've found this program useful. When you are certain 2922 you don't want a source file to be recompiled, you can set its 2923 timestamp to the stamp on the object file. 2924 2925 #!/usr/local/bin/perl 2926 # 2927 # Set timestamp of args 2nd-Last to that of the first arg. 2928 # 2929 ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,$atime,$mtime,$ctime) 2930 = stat(shift); 2931 utime($atime,$mtime,@ARGV); 2932 2933 Last modified: _6/13/1997_ 2934 2935 10. While in the middle of a large "commit", how do I run other commands, 2936 like "diff" or "stat" without seeing lock errors? 2937 2938 Type: 2939 cvs -n <command> 2940 2941 The '-n' option to the main cvs command turns off lock checking, a 2942 reasonable act for read-only commands given the promise offered by 2943 '-n' not to alter anything. The "diff", "log" and "stat" commands 2944 provide the same information (for files that are not being committed) 2945 when used with and without the '-n' option. 2946 2947 Warning: Ignoring locks can produce inconsistent information across a 2948 collection of files if you are looking at the revisions affected by an 2949 active commit. Be careful when creating "patches" from the output of 2950 "cvs -n diff". If you are looking only at your working files, tagged 2951 revisions, and BASE revisions (revisions whose numbers are read from 2952 your ./CVS/Entries files), you should get consistent results. Of 2953 course, if you catch a single file in the middle of RCS activity, you 2954 might get some strange errors. 2955 2956 Note that the suggested command is "cvs -n <command>". The visually 2957 similar command "cvs <command> -n" has no relation to the suggested 2958 usage and has an entirely different meaning for each command. 2959 2960 "cvs -n update" also works in the middle of a commit, providing 2961 slightly different information from a plain "cvs update". But, of 2962 course, it also avoids modifying anything. 2963 2964 You could also use the RCS functions, "rlog" and "rcsdiff" to display 2965 some of the information by referring directly to the Repository files. 2966 2967 You need RCS version 5 or later for the commands described above to 2968 work reliably. 2969 2970 Last modified: _6/13/1997_ 2971 2972 11. Where did the ./CVS/Entries.Static file come from? What is it for? 2973 2974 Each CVS working directory contains a ./CVS/Entries file listing the 2975 files managed by CVS in that working directory. Normally, if the 2976 "update" command finds a file in the Repository that is not in the 2977 ./CVS/Entries file, "update" copies the appropriate revision of the 2978 "new" file out of the Repository and adds the filename to the Entries 2979 file. This happens for files: 2980 2981 Added to the Repository from another working directory. 2982 2983 Dragged out of the Attic when switching branches with "update -A" or 2984 "update -r". 2985 2986 Whose names were deleted from the ./CVS/Entries file. 2987 2988 If the ./CVS/Entries.Static file exists, CVS will only bring out 2989 revisions of files that are contained in either ./CVS/Entries or 2990 ./CVS/Entries.Static. If a Repository file is found in *neither* file, 2991 it is ignored. 2992 2993 The ./CVS/Entries.Static file is created when you check out an 2994 individual file or a module that creates working directories that 2995 don't contain all files in the corresponding Repository directory. In 2996 those cases, without an ./CVS/Entries.Static file, a simple "update" 2997 would bring more files out of the Repository than the original 2998 "checkout" wanted. 2999 3000 The ./CVS/Entries.Static file can be removed by hand. It is 3001 automatically removed if you run "update -d" to create new directories 3002 (even if no new directories are created). (Internally, since 3003 "checkout" turns on the '-d' flag and calls the "update" routine, a 3004 "checkout" of a module or directory that writes into an existing 3005 directory will also remove the ./CVS/Entries.Static file.) 3006 3007 Last modified: _6/13/1997_ 3008 3009 12. Why did I get the wrong Repository in the loginfo message? 3010 3011 You probably: 3012 3013 Use multiple Repositories. 3014 3015 Configured CVS to use absolute pathnames in the ./CVS/Repository 3016 file. 3017 3018 Configured CVS not to use the ./CVS/Root file. 3019 3020 Typed the "commit" command in one Repository with your $CVSROOT 3021 pointing at another. 3022 3023 "commit" and all other CVS commands will heed an absolute pathname in 3024 the ./CVS/Repository file (or in the "-d CVSrootdir" override), but 3025 the log function doesn't take arguments -- it just looks at $CVSROOT. 3026 3027 If you avoid even one of the four steps above, you won't see this 3028 problem. If you configure ./CVS/Root, you won't be allowed to execute 3029 the program causing the error. 3030 3031 Last modified: _6/13/1997_ 3032 3033 13. How do I run CVS setuid so I can only allow access through the CVS 3034 program itself? 3035 3036 Setuid to root is not a great idea. Any program that modifies files 3037 and is used by a widely distributed group of users is not a good 3038 candidate for a setuid program. (The worst suggestion I've ever heard 3039 was to make *Emacs* setuid to root.) 3040 3041 Root access on Unix is too powerful. Also, it might not work in some 3042 (secure?) environments. 3043 3044 Running it setuid to some user other than root might work, if you add 3045 this line to main.c near the beginning: 3046 3047 setuid(geteuid()); 3048 3049 Otherwise it uses *your* access rights, rather than the effective 3050 uid's. 3051 3052 Also, you have to invent a fake user whose name will show up in 3053 various places. But many sites, especially those who might want a 3054 setuid CVS for "security", want personal accountability -- no generic 3055 accounts. I don't know whether accountability outweighs file security. 3056 3057 And finally, unless you take action to limit the "admin" command, you 3058 are leaving yourself unprotected anyway. 3059 3060 Last modified: _6/13/1997_ 3061 3062 14. How about using groups and setgid() then? 3063 3064 Here is a way to run CVS setgid in some environments: 3065 3066 Stick this near the front of the main() in main.c: 3067 3068 setgid(getegid()); 3069 3070 This will allow "access" to work on systems where it only works on the 3071 real gid. 3072 3073 Create a group named "cvsg". (This example uses "cvsg". You can name 3074 it as you wish.) 3075 3076 Put *no* users in the "cvsg" group. You can put Repository 3077 administrators in this group if you want to. 3078 3079 Set the cvs executable to setgid (not setuid): 3080 3081 cd /usr/local/bin; chown root.cvsg cvs; chmod 2755 cvs 3082 3083 Make sure every file in the Repository is in group "cvsg": 3084 3085 chown -R root.cvsg $CVSROOT 3086 3087 Change all directory permissions to 770. This allows all access to 3088 the files by the "cvsg" group (which has no members!) and no access at 3089 all to anyone else. 3090 3091 find $CVSROOT -type d -exec chmod 2770 {} \; 3092 3093 On some systems you might have to type: 3094 3095 find $CVSROOT -type d -exec chmod u=rwx,g=rwx,o=,g+s {} \; 3096 3097 This should allow only the cvs program (or other "setgid to group 3098 cvsg") programs to write into the area, but no one else. Yes the user 3099 winds up owning the file, but s/he can't find it again later since 3100 s/he can't traverse the tree. (If you enable the world execute bit 3101 (mode 2771) on directories, users can traverse the tree and the user 3102 who last wrote the file can still write to it.) 3103 3104 If you want to allow read access, check out an entire tree somewhere. 3105 You have to do this anyway to build it. 3106 3107 Note: If you are using a stupid file system that can't inherit file 3108 groups from the parent directory (even with the "setgid" (Octal 2000) 3109 bit set), you might have to modify CVS (or RCS) to reset the group 3110 every time you create a new file. I have not tested this. 3111 3112 The setgid() method shares with the setuid() method the problem of 3113 keeping "admin" from breaking things. 3114 3115 Last modified: _6/13/1997_ 3116 3117 15. How do I use the "commitinfo" file? 3118 3119 Go read 4B.2 first. 3120 3121 The "commitinfo" file allows you to execute "sanity check" functions 3122 before allowing a commit. If any function called from within the 3123 commitinfo file exits with a non-zero status, the commit is denied. 3124 3125 To fill out a "commitinfo" file, ask yourself (and those sharing your 3126 Repository) these questions: 3127 3128 - Is there anything you want to check or change before someone is 3129 allowed to commit a file? If not, forget commitinfo. 3130 3131 If you want to serialize binary files, you might consider something 3132 like the rcslock.pl program in the contrib directory of the CVS 3133 sources. 3134 3135 - Do you want to execute the same exact thing before committing to 3136 every file in the Repository? (This is useful if you want to program 3137 the restrictions yourself.) If so, set up a single line in the 3138 commitinfo: 3139 3140 DEFAULT /absolute/path/to/program 3141 3142 CVS executes the program once for each directory that "commit" 3143 traverses, passing as arguments the directory and the files to be 3144 committed within that directory. 3145 3146 Write your program accordingly. Some examples exist in the contrib 3147 directory. 3148 3149 - Do you want a different kind of sanity check performed for different 3150 directories? If so, you'll have to decide what to do for all 3151 directories and enter lines like this: 3152 3153 regexp1 /absolute/path/to/program-for-regexp1 3154 regexp2 /absolute/path/to/program-for-regexp2 3155 DEFAULT /absolute/path/to/program-for-all-else 3156 3157 - Is there anything you want to happen before *all* commits, in 3158 addition to other pattern matches? If so, include a line like this: 3159 3160 ALL /absolute/path/to/program 3161 3162 It is executed independently of all the above. And it's repeatable -- 3163 you can have as many ALL lines as you like. 3164 3165 Last modified: _6/13/1997_ 3166 3167 16. How do I use the "loginfo" files? 3168 3169 See 4B.2 and the "commitinfo" question above. 3170 3171 The "loginfo" file has the same format as the "commitinfo" file, but 3172 its function is different. Where the "commitinfo" information is used 3173 before a commit, the "loginfo" file is used after a commit. 3174 3175 All the commands in the "loginfo" file should read data from standard 3176 input, then either append it to a file or send a message to a mailing 3177 list. If you want to make it simple, you can put shell (the shell used 3178 by "popen(3)") command lines directly in the "loginfo" (or 3179 "commitinfo") file. These seem to work: 3180 3181 ^special /usr/ucb/Mail -s %s special-mailing-list ^other /usr/ucb/Mail 3182 -s %s other-mailing-list DEFAULT (echo '===='; echo %s; cat) > 3183 /path/name/to/log/file 3184 3185 Last modified: _6/13/1997_ 3186 3187 17. How can I keep people with restrictive umask values from blocking 3188 access to the Repository? 3189 3190 If a user creates a new file with restricted permissions (e.g. 0600), 3191 and commits it, the Repository will have a file in it that is 3192 unreadable by everyone. The 0600 example would be unreadable by 3193 *anyone* but root and the user who created it. 3194 3195 There are 3 solutions to this: 3196 3197 Let it happen. This is a valid way to protect things. If everyone is 3198 working alone, a umask of 077 is OK. If everyone is working only in 3199 small groups, a umask of 007 is OK. 3200 3201 Train your users not to create such things if you expect to share 3202 them. 3203 3204 See 4B.5 for a small script that will reset the umask. 3205 3206 I personally don't like the idea of a program automatically 3207 *loosening* security. It would be better for you all to talk about the 3208 issue and decide how to work together. 3209 3210 Last modified: _6/13/1997_ 3211 3212 Category: /Commands_/ 3213 3214 " Commands " 3215 3216 Category: /Commands_/add_ad_new/ 3217 3218 " + "add", "ad", "new"" 3219 3220 1. What is "add" for? 3221 3222 To add a new directory to the Repository or to register the desire to 3223 add a new file to the Repository. 3224 3225 The directory is created immediately, while the desire to add the file 3226 is recorded in the local ./CVS administrative directory. To really add 3227 the file to the Repository, you must then "commit" it. 3228 3229 Last modified: _6/13/1997_ 3230 3231 2. How do I add a new file to the branch I'm working on? 3232 3233 The user actions for adding a file to any branch, including the Main 3234 Branch, are exactly the same. 3235 3236 You are in a directory checked out (or updated) with the '-A' option 3237 (to place you on the Main Branch) or the "-r <branch_tag>" option (to 3238 place you on a branch tagged with <branch_tag>). To add <file> to the 3239 branch you are on, you type: 3240 3241 cvs add <file> 3242 cvs commit <file> 3243 3244 If no ./CVS/Tag file exists (the '-A' option deletes it), the file 3245 will be added to the Main Branch. If a ./CVS/Tag file exists (the "-r 3246 <branch_tag>" option creates it), the file will be added to the branch 3247 named (i.e. tagged with) <branch_tag>. 3248 3249 Unless you took steps to first add the file to the Main Branch, your 3250 new file ends up in the Attic. 3251 3252 Last modified: _6/13/1997_ 3253 3254 3. Why did my new file end up in the Attic? 3255 3256 The file is thrown into the Attic to keep it from being visible when 3257 you check out the Main Branch, since it was never committed to the 3258 Main Branch. 3259 3260 Last modified: _6/13/1997_ 3261 3262 4. Now that it's in the Attic, how do I connect it to the Main branch? 3263 3264 That can be considered a kind of "merge". See 4C.8 3265 3266 Last modified: _6/13/1997_ 3267 3268 5. How do I avoid the hassle of reconnecting an Attic-only file to the Main 3269 Branch? 3270 3271 You create it on the Main Branch first, then branch it. 3272 3273 If you haven't yet added the file or if you decided to delete the new 3274 Attic file and start over, then do the following: (If you added the 3275 file (or worse, the 157 files) to the Attic and don't want to start 3276 over, try the procedure in 4C.8.) 3277 3278 Temporarily remove the sticky branch information. Either: 3279 3280 Move the whole directory back to the Main Branch. [This might not be 3281 a good idea if you have modified files, since it will require a merge 3282 in each direction.] 3283 3284 cvs update -A 3285 3286 *or* 3287 3288 Move the ./CVS/Tag file out of the way. 3289 3290 mv ./CVS/Tag HOLD_Tag 3291 3292 Add and branch the file "normally": 3293 3294 cvs add <file> 3295 cvs commit <file> 3296 cvs tag -b <branch_tag> <file> 3297 3298 [<branch_tag> is the same Branch Tag as you used on all the other 3299 files. Look at ./CVS/Entries or the output from "cvs stat" for sticky 3300 tags.] 3301 3302 Clean up the temporary step. 3303 3304 If you moved the ./CVS/Tag file, put it back. Then move the new file 3305 onto the branch where you are working. 3306 3307 mv HOLD_Tag ./CVS/Tag 3308 cvs update -r <branch_tag> <file> 3309 3310 If you ran "update -A" rather than moving the ./CVS/Tag file, move 3311 the whole directory (including the new file) back onto the branch 3312 where you were working: 3313 3314 cvs update -r <branch_tag> 3315 3316 Last modified: _6/13/1997_ 3317 3318 6. How do I cancel an "add"? 3319 3320 If you want to remove the file entirely and cancel the "add" at the 3321 same time, type: 3322 3323 cvs remove -f <file> 3324 3325 If you want to cancel the "add", but leave the file as it was before 3326 you typed "cvs add", then you have to fake it: 3327 3328 mv <file> <file>.hold 3329 cvs remove <file> 3330 mv <file>.hold <file> 3331 3332 Last modified: _6/13/1997_ 3333 3334 7. What are the ./CVS/file,p and ./CVS/file,t files for? 3335 3336 The ./CVS/file,p and ./CVS/file,t files are created by the "add" 3337 command to hold command line options and message text between the time 3338 of the "add" command and the expected "commit". 3339 3340 The ./CVS/file,p file is always null, since its function was absorbed 3341 by the "options" field in the ./CVS/Entries file. If you put something 3342 in this file it will be used as arguments to the RCS "ci" command that 3343 commit uses to check the file in, but CVS itself doesn't put anything 3344 there. 3345 3346 The ./CVS/file,t file is null unless you specify an initial message in 3347 an "add -m 'message'" command. The text is handed to "rcs -i 3348 -t./CVS/file,t" to create the initial RCS file container. 3349 3350 Both files must exist to commit a newly added file. If the 3351 ./CVS/file,p file doesn't exist, CVS prints an error and aborts the 3352 commit. If the ./CVS/file,t file doesn't exist, RCS prints an error 3353 and CVS gets confused, but does no harm. 3354 3355 To recover from missing ,p and ,t files, just create two zero-length 3356 files and rerun the "commit". 3357 3358 Last modified: _6/13/1997_ 3359 3360 8. How do I "add" a binary file? 3361 3362 If you configured CVS to use the GNU version of "diff" and "diff3", 3363 you only need to turn off RCS keyword expansion. 3364 3365 First you turn off RCS keyword expansion for the initial checkin by 3366 using "add -ko". It works like "update -ko" in creating a "sticky" 3367 option only for the copy of the file in the current working directory. 3368 3369 cvs add -ko <file> 3370 3371 Commit the file normally. The sticky -ko option will be used. 3372 3373 cvs commit <file> 3374 3375 Then mark the RCS file in the Repository so that keyword expansion is 3376 turned off for all checked out versions of the file. 3377 3378 cvs admin -ko <file> 3379 3380 Since "admin -ko" records the keyword substitution value in the 3381 Repository's RCS file, you no longer need the sticky option. You can 3382 turn it off with the "update -A" command, but if you were on a branch, 3383 you'll have to follow it "update -r <branch_tag>" to put yourself back 3384 on the branch. 3385 3386 Managing that binary file is another problem. See 4D.1. 3387 3388 Last modified: _6/13/1997_ 3389 3390 Category: /Commands_/admin_adm_rcs/ 3391 3392 " + "admin", "adm", "rcs"" 3393 3394 1. What is "admin" for? 3395 3396 To provide direct access to the underlying "rcs" command (which is not 3397 documented in this FAQ) bypassing all safeguards and CVS assumptions. 3398 3399 Last modified: _6/13/1997_ 3400 3401 2. Wow! Isn't that dangerous? 3402 3403 Yes. 3404 3405 Though you can't hurt the internal structure of an RCS file using its 3406 own "rcs" command, you *can* change the underlying RCS files using 3407 "admin" in ways that CVS can't handle. 3408 3409 If you feel the need to use "admin", create some test files with the 3410 RCS "ci" command and experiment on them with "rcs" before blasting any 3411 CVS files. 3412 3413 Last modified: _6/13/1997_ 3414 3415 3. What would I normally use "admin" for? 3416 3417 Normally, you wouldn't use admin at all. In unusual circumstances, 3418 experts can use it to set up or restore the internal RCS state that 3419 CVS requires. 3420 3421 You can use "admin -o" (for "outdate") to remove revisions you don't 3422 care about. This has its own problems, such as leaving dangling Tags 3423 and confusing the "update" command. 3424 3425 There is some feeling among manipulators of binary files that "admin 3426 -l" should be used to serialize access. See 3C.8. 3427 3428 An interesting use for "admin" came up while maintaining CVS itself. I 3429 import versions of CVS onto the Vendor branch of my copy of CVS, make 3430 changes to some files and ship the diffs (created by "cvs diff -c -r 3431 TO_BRIAN") off to Brian Berliner. After creating the diff, I retag 3432 ("cvs tag -F TO_BRIAN") the working directory, which is then ready to 3433 produce the next patch. 3434 3435 I'll use "add.c" as an example (only because the name is short). 3436 3437 When the next release came out, I discovered that the released "add.c" 3438 (version 1.1.1.3 on the Vendor branch) was exactly the same as my 3439 modified file (version 1.3). I didn't care about the changelog on 3440 versions 1.2 and 1.3 (or the evidence of having done the work), so I 3441 decided to revert the file to the state where it looked like I had not 3442 touched the file -- where I was just using the latest on the vendor 3443 branch after a sequence of imports. 3444 3445 To do that, I removed all the revisions on the main branch, except for 3446 the original 1.1 from which the Vendor branch sprouts: 3447 3448 cvs admin -o1.2: add.c 3449 3450 Then I set the RCS "default branch" back to the Vendor branch, the way 3451 import would have created it: 3452 3453 cvs admin -b1.1.1 add.c 3454 3455 And I moved the "TO_BRIAN" Tag to the latest revision on the Vendor 3456 branch, since that is the base from which further patches would be 3457 created (if I made any): 3458 3459 cvs admin -NTO_BRIAN:1.1.1.3 add.c 3460 3461 Instead of 1.1.1.3, I could have used one of the "Release Tags" last 3462 applied by "import" (3rd through Nth arguments). 3463 3464 Suggestion: Practice on non-essential files. 3465 3466 Last modified: _6/13/1997_ 3467 3468 4. What should I avoid when using "admin"? 3469 3470 If you know exactly what you are doing, hack away. But under normal 3471 circumstances: 3472 3473 Never use "admin" to alter branches (using the '-b' option), which CVS 3474 takes very seriously. If you change the default branch, CVS will not 3475 work as expected. If you create new branches without using the "tag 3476 -b" command, you may not be able to treat them as CVS branches. 3477 3478 See 3C.8 for a short discussion of how to use "admin -l" for 3479 serializing access to binary files. 3480 3481 The "admin -o <file>" allows you to delete revisions, usually a bad 3482 idea. You should commit a correction rather than back out a revision. 3483 Outdating a revision is prone to all sorts of problems: 3484 3485 Discarding data is always a bad idea. Unless something in the 3486 revision you just committed is a threat to your job or your life, 3487 (like naming a function "<boss's name>_is_a_dweeb", or including the 3488 combination to the local Mafioso's safe in a C comment), just leave it 3489 there. No one cares about simple mistakes -- just commit a corrected 3490 revision. 3491 3492 The time travel paradoxes you can cause by changing history are not 3493 worth the trouble. Even if CVS can't interfere with your parents' 3494 introduction, it *can* log commits in at least two ways (history and 3495 loginfo). The reports now lie -- the revision referred to in the logs 3496 no longer exists. 3497 3498 If you used "import" to place <file> into CVS, outdating all the 3499 revisions on the Main branch back to and including revision 1.2 (or 3500 worse, 1.1), will produce an invalid CVS file. 3501 3502 If the <file>,v file only contains revision 1.1 (and the connected 3503 branch revision 1.1.1.1), then the default branch must be set to the 3504 Vendor branch as it was when you first imported the file. Outdating 3505 back through 1.2 doesn't restore the branch setting. Despite the above 3506 admonition against it, "admin -b" is the only way to recover: 3507 3508 cvs admin -b1.1.1 <file> 3509 3510 Although you can't outdate a physical (RCS) branch point without 3511 removing the whole branch, you *can* outdate a revision referred to by 3512 a magic branch tag. If you do so, you will invalidate the branch. 3513 3514 If you "outdate" a tagged revision, you will invalidate all uses of 3515 the <tag>, not just the one on <file>. A tag is supposed to be 3516 attached to a consistent set of files, usually a set built as a unit. 3517 By discarding one of the files in the set, you have destroyed the 3518 utility of the <tag>. And it leaves a dangling tag, which points to 3519 nothing. 3520 3521 And even worse, if you commit a revision already tagged, you will 3522 alter what the <tag> pointed to without using the "tag" command. For 3523 example, if revision 1.3 has <tag> attached to it and you "outdate" 3524 the 1.3 revision, <tag> will point to a nonexistent revision. Although 3525 this is annoying, it is nowhere near as much trouble as the problem 3526 that will occur when you commit to this file again, recreating 3527 revision 1.3. The old tag will point to the new revision, a file that 3528 was not in existence when the <tag> was applied. And the discrepancy 3529 is nearly undetectable. 3530 3531 If you don't understand the above, you should not use the admin 3532 command at all. 3533 3534 Last modified: _6/13/1997_ 3535 3536 5. How do I restrict the "admin" command? The -i flag in the modules file 3537 can restrict commits. What's the equivalent for "admin"? 3538 3539 At this writing, to disable the "admin" command, you will have to 3540 change the program source code, recompile and reinstall. 3541 3542 Last modified: _6/13/1997_ 3543 3544 6. I backed out a revision with "admin -o" and committed a replacement. Why 3545 doesn't "update" retrieve the new revision? 3546 3547 CVS is confused because the revision in the ./CVS/Entries file matches 3548 the latest revision in the Repository *and* the timestamp in the 3549 ./CVS/Entries file matches your working file. CVS believes that your 3550 file is "up-to-date" and doesn't need to be updated. 3551 3552 You can cause CVS to notice the change by "touch"ing the file. 3553 Unfortunately what CVS will tell you is that you have a "Modified" 3554 file. If you then "commit" the file, you will bypass the normal CVS 3555 check for "up-to-date" and will probably commit the revision that was 3556 originally removed by "admin -o". 3557 3558 Changing a file without changing the revision number confuses CVS no 3559 matter whether you did it by replacing the revision (using "admin -o" 3560 and "commit" or raw RCS commands) or by applying an editor directly to 3561 a Repository (",v") file. Don't do it unless you are absolutely 3562 certain no one has the latest revision of the file checked out. 3563 3564 The best solution to this is to institute a program of deterrent 3565 flogging of abusers of "admin -o". 3566 3567 The "admin" command has other problems." See 3B.4 above. 3568 3569 Last modified: _6/13/1997_ 3570 3571 Category: /Commands_/checkout_co_get/ 3572 3573 " + "checkout", "co", "get"" 3574 3575 1. What is "checkout" for? 3576 3577 To acquire a copy of a module (or set of files) to work on. 3578 3579 All work on files controlled by CVS starts with a "checkout". 3580 3581 Last modified: _6/13/1997_ 3582 3583 2. What is the "module" that "checkout" takes on the command line? 3584 3585 It is a name for a directory or a collection of files in the 3586 Repository. It provides a compact name space and the ability to 3587 execute before and after helper functions based on definitions in the 3588 modules file. 3589 3590 See 1D.11. 3591 3592 Last modified: _6/13/1997_ 3593 3594 3. Isn't a CVS "checkout" just a bunch of RCS checkouts? 3595 3596 Like much of CVS, a similar RCS concept is used to support a CVS 3597 function. But a CVS checkout is *not* the same as an RCS checkout. 3598 3599 Differences include: 3600 3601 CVS does not lock the files. Others may access them at the same 3602 time. 3603 3604 CVS works best when you provide a name for a collection of files (a 3605 module or a directory) rather than an explicit list of files to work 3606 on. 3607 3608 CVS remembers what revisions you checked out and what branch you are 3609 on, simplifying later commands. 3610 3611 Last modified: _6/13/1997_ 3612 3613 4. What's the difference between "update" and "checkout"? 3614 3615 The "checkout" and "update" commands are nearly equivalent in how they 3616 treat individual files. They differ in the following ways: 3617 3618 The "checkout" command always creates a directory, moves into it, 3619 then becomes equivalent to "update -d". 3620 3621 The "update" command does not create directories unless you add the 3622 '-d' option. 3623 3624 "Update" is intended to be executed within a working directory 3625 created by "checkout". It doesn't take a module or directory argument, 3626 but figures out what Repository files to look at by reading the files 3627 in the ./CVS administrative directory. 3628 3629 The two commands generate completely different types of records in 3630 the "history" file. 3631 3632 Last modified: _6/13/1997_ 3633 3634 5. Why can't I check out a file from within my working directory? 3635 3636 Though you *can* check out a file, you normally check out a module or 3637 directory. And you normally do it only once at the beginning of a 3638 project. 3639 3640 After the initial "checkout", you can use the "update" command to 3641 retrieve any file you want within the checked-out directory. There is 3642 no need for further "checkout" commands. 3643 3644 If you want to retrieve another module or directory to work on, you 3645 must provide two pathnames: where to find it in the Repository and 3646 where to put it on disk. The "modules" file and your current directory 3647 supply two pieces of naming information. While inside a checked-out 3648 working directory, the CVS administrative information provides most of 3649 the rest. 3650 3651 You should be careful not to confuse CVS with RCS and use "checkout" 3652 in the RCS sense. An RCS "checkout" (which is performed by the RCS 3653 "co" command) is closer to a "cvs update" than to a "cvs checkout". 3654 3655 Last modified: _6/13/1997_ 3656 3657 6. How do I avoid dealing with those long relative pathnames? 3658 3659 This question has also been phrased: 3660 3661 How do I avoid all those layers of directories on checkout? or Why do 3662 I have to go to the top of my working directory and checkout some long 3663 pathname to get a file or two? 3664 3665 This type of question occurs only among groups of people who decide 3666 not to use "modules". The answer is to use "modules". 3667 3668 When you hand the "checkout" command a relative pathname rather than a 3669 module name, all directories in the path are created, maintaining the 3670 same directory hierarchy as in the Repository. The same kind of 3671 environment results if you specify a "module" that is really an alias 3672 expanding into a list of relative pathnames rather than a list of 3673 module names. 3674 3675 If you use "module" names, "checkout" creates a single directory by 3676 the name of the module in your current directory. This "module" 3677 directory becomes your working directory. 3678 3679 The "module" concept combines the ability to "name" a collection of 3680 files with the ability to structure the Repository so that consistent 3681 sets of files are checked out together. It is the responsibility of 3682 the Repository Administrators to set up a modules file that describes 3683 the software within the Repository. 3684 3685 Last modified: _6/13/1997_ 3686 3687 7. Can I move a checked-out directory? Does CVS remember where it was 3688 checked out? 3689 3690 Yes and Yes. 3691 3692 The ./CVS/Repository file in each working directory contains a 3693 pathname pointing to the matching directory within the Repository. The 3694 pathname is either absolute or relative to $CVSROOT, depending on how 3695 you configured CVS. 3696 3697 When you move a checked-out directory, the CVS administrative files 3698 will move along with it. As long as you don't move the Repository 3699 itself, or alter your $CVSROOT variable, the moved directory will 3700 continue to be usable. 3701 3702 CVS remembers where you checked out the directory in the "history" 3703 file, which can be edited, or even ignored if you don't use the 3704 "working directory" information displayed by the "history" command. 3705 3706 Last modified: _6/13/1997_ 3707 3708 8. How can I lock files while I'm working on them the way RCS does? 3709 3710 Until the day arrives of the all-powerful merge tool, there are still 3711 files that must be accessed serially. For those instances, here's a 3712 potential solution: 3713 3714 Install a pre-commit program in the "commitinfo" file to check for 3715 RCS locks. The program "rcslock.pl" performs this function. It can be 3716 found in the contrib directory of the CVS source distribution. 3717 3718 When you want to make a change to a file you know can't be merged, 3719 first use "cvs admin -l" to lock the file. If you can't acquire the 3720 lock, use the standard "locked out" protocol: go talk to the person 3721 holding the lock. 3722 3723 Make sure the pre-commit program prints a message and exits with a 3724 non-zero status if someone besides the user running "commit" has the 3725 file locked. This non-zero exist status will cause the "commit" to 3726 fail cleanly. 3727 3728 Make sure the pre-commit program exits with a zero status if the 3729 file is either unlocked or locked by the user running "commit". The 3730 "cvs commit" command that kicked off the pre-commit program will take 3731 a zero exist status as an OK and checkin the file, which has the 3732 side-effect of unlocking it. 3733 3734 ===> The following is opinion and context. Don't read it if you are 3735 looking for a quick fix. 3736 3737 The topic of locking CVS files resurfaces on the network every so 3738 often, producing the same results each time: 3739 3740 The Big Endians: 3741 3742 CVS was designed to avoid locks, using a copy-modify-merge model. 3743 Locking is not necessary and you should take the time to learn the CVS 3744 model which many people find workable. So why not get with the program 3745 and learn how to think the CVS way? 3746 3747 The Little Endians: 3748 3749 The users determine how a tool is to be used, not the designers. We, 3750 the users, have always used locking, our bosses demand locking, 3751 locking is good, locking is God. I don't want to hear any more 3752 lectures on the CVS model. Make locking work. 3753 3754 Any organization making active changes to a source base will 3755 eventually face the need to do parallel development. Parallel 3756 development implies merges. (If you plan to keep separate copies of 3757 everything and never merge, good luck. Tell me who you work for so I 3758 can buy stock in your disk suppliers this year and sell your stock 3759 short next year.) 3760 3761 Merges will never go away. CVS chose to make "merges" stand front and 3762 center as an important, common occurrence in development. It is one 3763 way of looking at things. 3764 3765 For free-format text, the merge paradigm gives you a considerable 3766 amount of freedom. It does take a bit of management, but any project 3767 should be ready to deal with it. 3768 3769 On the other hand, there are many files that can't be merged using 3770 text merge techniques. Straight text merge programs like "diff3" are 3771 guaranteed to fail on executables (with relative branch statements), 3772 files with self-referential counts stored in the file (such as TAGS 3773 files), or files with relative motion statements in them (such as 3774 Frame MIF files, many postscript files). They aren't all binary files. 3775 3776 For these types of files, and many others, there are only two 3777 solutions: 3778 3779 Complex merge tools that are intimately aware of the contents of the 3780 files to be merged. (ClearCase, and probably others, allow you to 3781 define your own "files types" with associated "merge tools".) 3782 3783 Serialization of access to the file. The only technical solution to 3784 the problem of serialization is "locking". 3785 3786 Since you can call a program that offers: 3787 3788 "Which one do you want? A/B?" 3789 3790 a "merge tool", more and more merge tools will appear which can be 3791 hooked into a merge-intensive program like CVS. Think of a bitmap 3792 "merge" tool that displays the bitmaps on the screen and offers a 3793 "paint" interface to allow you to cut and paste, overlay, invert or 3794 fuse the two images such that the result is a "merged" file. 3795 3796 My conclusion is that the need for locking is temporary, awaiting 3797 better technology. For large development groups, locking is not an 3798 alternative to merging for text files. 3799 3800 Last modified: _6/13/1997_ 3801 3802 9. What is "checkout -s"? How is it different from "checkout -c"? 3803 3804 The '-c' and '-s' options to "checkout" both cause the modules file to 3805 appear on standard output, but formatted differently. 3806 3807 "checkout -c" lists the modules file alphabetized by the module name. 3808 It also prints all data (including options like '-a' and "-o <prog>") 3809 specified in the modules file. 3810 3811 "checkout -s" lists the modules file sorted by "status" field, then by 3812 module name. The status field was intended to allow you to mark 3813 modules with strings of your choice to get a quick sorted report based 3814 on the data you chose to put in the status fields. I have used it for 3815 priority ("Showstopper", etc as tied into a bug database), for porting 3816 status ("Ported", "Compiled", etc. when porting a large collection of 3817 modules), for "assignee" (the person responsible for maintenance), and 3818 for "test suite" (which automatic test procedure to run for a 3819 particular module). 3820 3821 Last modified: _6/13/1997_ 3822 3823 Category: /Commands_/commit_ci_com/ 3824 3825 " + "commit", "ci", "com"" 3826 3827 1. What is "commit" for? 3828 3829 To store new revisions in the Repository, making them visible to other 3830 users. 3831 3832 Last modified: _6/13/1997_ 3833 3834 2. If I edit ten files, do I have to type "commit" ten times? 3835 3836 No. The "commit" command will take multiple filenames, directory names 3837 and relative pathnames on the command line and commit them all with 3838 the same log message. If a file is unchanged, even if it is explicitly 3839 listed on the command line, CVS will skip it. 3840 3841 Like all CVS commands, "commit" will work on the whole directory by 3842 default. Just type "cvs commit" to tell CVS to commit all modified 3843 files (i.e. the files that "update" would display preceded by 'M') in 3844 the current directory and in all sub-directories. 3845 3846 Last modified: _6/13/1997_ 3847 3848 3. Explain: cvs commit: Up-to-date check failed for `<file>' 3849 3850 You may not "commit" a file if your BASE revision (i.e. the revision 3851 you last checked out, committed or retrieved via "update") doesn't 3852 match the HEAD revision (i.e the latest revision on your branch, 3853 usually the Main Branch). 3854 3855 In other words, someone committed a revision since you last executed 3856 "checkout", "update" or "commit". You must now execute "update" to 3857 merge the other person's changes into your working file before 3858 "commit" will work. You are thus protected (somewhat) from a common 3859 form of race condition in source control systems, where a checkin of a 3860 minor alteration of a second copy of the same base file obliterates 3861 the changes made in the first. 3862 3863 Normally, the "update" command's auto-merge should be followed by 3864 another round of building and testing before the "commit". 3865 3866 Last modified: _6/13/1997_ 3867 3868 4. What happens if two people try to "commit" conflicting changes? 3869 3870 Conflicts can occur only when two developers check out the same 3871 revision of the same file and make changes. The first developer to 3872 commit the file has no chance of seeing the conflict. Only the second 3873 developer runs into it, usually when faced with the "Up-to-date" error 3874 explained in the previous question. 3875 3876 There are two types of conflicts: 3877 3878 When two developers make changes to the same section of code, the 3879 auto-merge caused by "update" will print a 'C' on your terminal and 3880 leave "overlap" markers in the file. 3881 3882 You are expected to examine and clean them up before committing the 3883 file. (That may be obvious to *some* of you, but . . .) 3884 3885 A more difficult problem arises when two developers change different 3886 sections of code, but make calls to, or somehow depend on, the old 3887 version of each other's code. 3888 3889 The auto-merge does the "right" thing, if you view the file as a 3890 series of text lines. But as a program, the two developers have 3891 created a problem for themselves. 3892 3893 This is no different from making cross-referential changes in 3894 *separate* files. CVS can't help you. In a perfect world, you would 3895 each refer to the specification and resolve it independently. In the 3896 real world you have to talk/argue, read code, test and debug until the 3897 combined changes work again. 3898 3899 Welcome to the world of parallel development. 3900 3901 Last modified: _6/13/1997_ 3902 3903 5. I committed something and I don't like it. How do I remove it? 3904 3905 Though you *can* use the "admin -o" (synonym: "rcs -o") command to 3906 delete revisions, unless the file you committed is so embarrassing 3907 that the need to eradicate it overrides the need to be careful, you 3908 should just grab an old version of the file ("update -p -r 3909 <previous-rev>" might help here) and commit it on top of the offending 3910 revision. 3911 3912 See Section 3B on "admin". 3913 3914 Last modified: _6/13/1997_ 3915 3916 6. Explain: cvs commit: sticky tag `V3' for file `X' is not a branch 3917 3918 The message implies two things: 3919 3920 You created your working directory by using "checkout -r V3", or you 3921 recently executed "update -r V3". 3922 3923 The tag named V3 is not a branch tag. 3924 3925 CVS records (i.e. makes "sticky") any "-r <tag/rev>" argument handed 3926 to the "checkout" or "update" commands. The <tag/rev> is recorded as 3927 the CVS working branch, which is the branch to which "commit" will add 3928 a new revision. 3929 3930 Branch tags are created when you use the -b switch on the "tag" or 3931 "rtag" commands. Branch tags are magic tags that don't create a 3932 physical branch, but merely mark the revision to branch from when the 3933 branch is needed. The first commit to a magic branch creates a 3934 physical branch in the RCS files. 3935 3936 You can commit onto the end of the Main Trunk, if you have no sticky 3937 tag at all, or onto the end of a branch, if you have a sticky branch 3938 tag. But you can't commit a file that has a sticky tag not pointing to 3939 a branch. CVS assumes a sticky Tag or Revision that does not refer to 3940 a branch is attached to the middle of a series of revisions. You can't 3941 squeeze a new revision between two others. Sticky dates also block 3942 commits since they never refer to a branch. 3943 3944 Scenario1: 3945 3946 If you don't want a branch and were just looking at an old revision, 3947 then you can move back to the Main Branch by typing: 3948 3949 cvs update -A {files or dirs, default is '.'} 3950 3951 or you can move to the branch named <branch_tag> by: 3952 3953 cvs update -r <branch_tag> {files or dirs, default is '.'} 3954 3955 Scenario2: 3956 3957 If you really wanted to be on a branch and made an earlier mistake by 3958 tagging your branch point with a non-branch tag, you can recover by 3959 adding a new branch tag to the old non-branch tag: 3960 3961 cvs rtag -b -r <oldtag> <newtag> <module> 3962 3963 (It was not a big mistake. Branch-point tags can be useful. But the 3964 <newtag> must have a different name.) 3965 3966 If you don't know the <module> name or don't use "modules", you can 3967 also use "tag" this way: 3968 3969 cvs update -r <oldtag> 3970 cvs tag -b <newtag> . 3971 3972 Then, to put your working directory onto the branch, you type: 3973 3974 cvs update -r <newtag> 3975 3976 You can't delete <oldtag> before adding <newtag>, and I would not 3977 advise deleting the <oldtag> at all, because it is useful in referring 3978 to the branch point. If you must, you can delete the non-branch tag 3979 by: 3980 3981 cvs rtag -d <oldtag> <module> 3982 or 3983 cvs tag -d <oldtag> . 3984 3985 Scenario3: 3986 3987 If you made the same mistake as in Scenario2 (of placing a non-branch 3988 tag where you wanted a branch tag), but really want <oldtag> to be the 3989 name of your branch, you can execute a slightly different series of 3990 commands to rename it and move your working directory onto the branch. 3991 3992 Warning: This is not a way to rename a branch tag. It is a way to turn 3993 a non-branch tag into a branch tag with the same name. 3994 3995 cvs rtag -r <oldtag> <branch_point_tag> <module> 3996 cvs rtag -d <oldtag> <module> 3997 cvs rtag -b -r <branch_point_tag> <oldtag> <module> 3998 3999 Then, if you really must, delete the <branch_point_tag>: 4000 4001 cvs rtag -d <branch_point_tag> <module> 4002 4003 Note: The unwieldy mixture of "tag" and "rtag" is mostly because you 4004 can't specify a revision (-r <tag>) to the "tag" command. 4005 4006 See 4C.3 for more info on creating a branch. 4007 4008 Last modified: _6/13/1997_ 4009 4010 7. Why does "commit -r <tag/rev>" put newly added files in the Attic? 4011 4012 If you specify "-r <rev>" (where <rev> is a dotted numeric number like 4013 2.4), it correctly sets the initial revision to <rev>, but it also 4014 attaches the numeric <rev> as a sticky tag and throws the file into 4015 the Attic. This is a bug. The obvious solution is to move the file out 4016 of the Attic into the associated Repository directory and "update -A" 4017 the file. There are no Tags to clean up. 4018 4019 If you specify "-r <tag>" to commit a newly added file, the <tag> is 4020 treated like a <branch_tag>, which becomes a symbolic RCS label 4021 pointing to the string '1', which can be considered to be the "Main 4022 branch number" when the main branch is still at revision 1.N. The file 4023 is also thrown into the Attic. See 4C.8 for a way to recover from 4024 this. 4025 4026 In fact, a plain "commit" without the "-r" will throw a newly added 4027 file into the Attic if you added it to a directory checked out on a 4028 branch. See 3A.[2-5]. 4029 4030 See Section 4C, on Branching, for many more details. 4031 4032 Last modified: _6/13/1997_ 4033 4034 8. Why would a "commit" of a newly added file not produce rev 1.1? 4035 4036 When committing a newly added file CVS looks for the highest main 4037 branch major number in all files in the ./CVS/Entries file. Normally 4038 it is '1', but if you have a file of revision 3.27 in your directory, 4039 CVS will find the '3' and create revision 3.1 for the first rev of 4040 <file>. Normally, the first revision is 1.1. 4041 4042 Last modified: _6/13/1997_ 4043 4044 Category: /Commands_/diff_di_dif/ 4045 4046 " + "diff", "di", "dif"" 4047 4048 1. What is "diff" for? 4049 4050 To display the difference between a working file and its BASE 4051 revision (the revision last checked out, updated or committed): 4052 4053 cvs diff <file> 4054 4055 To display the difference between a working file and a committed 4056 revision of the same file: 4057 4058 cvs diff -r <tag/rev> <file> 4059 4060 To display the difference between two committed revisions of the 4061 same file: 4062 4063 cvs diff -r <tag1/rev1> -r <tag2/rev2> <file> 4064 4065 You can specify any number of <file> arguments. Without any <file> 4066 arguments, it compares the whole directory. 4067 4068 In the examples above, "-D <date>" may be substituted wherever "-r 4069 <tag/rev>" appears. The revision a <date> refers to is the revision 4070 that existed on that date. 4071 4072 Last modified: _6/13/1997_ 4073 4074 2. Why did "diff" display nothing when I know there are later committed 4075 revisions in the Repository? 4076 4077 By default, "diff" displays the difference between your working file 4078 and the BASE revision. If you haven't made any changes to the file 4079 since your last "checkout", "update" or "commit" there is no 4080 difference to display. 4081 4082 To display the difference between your working file and the latest 4083 revision committed to your current branch, type: 4084 4085 cvs diff -r HEAD <file> 4086 4087 Last modified: _6/13/1997_ 4088 4089 3. How do I display what changed in the Repository since I last executed 4090 "checkout", "update" or "commit"? 4091 4092 A special tag (interpreted by CVS -- it does not appear in the Tag 4093 list) named "BASE" always refers to the revision you last checked out, 4094 updated or committed. Another special tag named "HEAD" always refers 4095 to the latest revision on your working branch. 4096 4097 To compare BASE and HEAD, you type: 4098 4099 cvs diff -r BASE -r HEAD <file> 4100 4101 Last modified: _6/13/1997_ 4102 4103 4. How do I display the difference between my working file and what I 4104 checked in last Thursday? 4105 4106 cvs diff -D "last Thursday" <file> 4107 4108 where "last Thursday" is a date string. To be more precise, the 4109 argument to the '-D' option is a timestamp. Many formats are accepted. 4110 See the man page under "-D date_spec" for details. 4111 4112 Last modified: _6/13/1997_ 4113 4114 5. Why can't I pass long options, like --unified, to "diff"? 4115 4116 CVS only handles single character '-X' arguments, not the FSF long 4117 options. CVS also passes through only arguments it knows about, 4118 because a few arguments are captured and interpreted by CVS. 4119 4120 If you didn't configure RCS and CVS to use the GNU version of diff, 4121 long options wouldn't work even if future versions of CVS acquire the 4122 ability to pass them through. 4123 4124 Most of the long options have equivalent single-character options, 4125 which do work. The "--unified" option is equivalent to '-u' in 4126 revisions of GNU diff since 1.15. 4127 4128 Last modified: _6/13/1997_ 4129 4130 Category: /Commands_/export_exp_ex/ 4131 4132 " + "export", "exp", "ex"" 4133 4134 1. What is "export" for? 4135 4136 "export" checks out a copy of a module in a form intended for export 4137 outside the CVS environment. The "export" command produces the same 4138 directory and file structure as the "checkout" command, but it doesn't 4139 create "CVS" sub-directories and it removes all the RCS keywords from 4140 the files. 4141 4142 Last modified: _6/13/1997_ 4143 4144 2. Why does it remove the RCS keywords so I can't use the "ident" command 4145 on the source files? 4146 4147 It removes the RCS keywords, so that if the recipient of the exported 4148 sources checks them into another set of RCS files (with or without 4149 CVS), and then makes modifications through RCS or CVS commands, the 4150 revision numbers that they had when you exported them will be 4151 preserved. (That ident no longer works is just an unfortunate side 4152 effect.) 4153 4154 The theory is that you are exporting the sources to someone else who 4155 will make independent changes, and at some point you or they will want 4156 to know what revisions from your Repository they started with 4157 (probably to merge changes, or to try to decide whether to merge 4158 changes). 4159 4160 A better way to handle this situation would be to give them their own 4161 branch of your Repository. They would need to remember to checkin the 4162 exported sources with RCS IDs intact (ci -k) so that their changes 4163 would get revision numbers from the branch, rather than starting at 4164 1.1 again. Perhaps a future version of CVS will provide a way to 4165 export sources this way. 4166 4167 Contributed by Dan Franklin 4168 4169 Last modified: _6/13/1997_ 4170 4171 3. Can I override the '-kv' flag CVS passes to RCS? 4172 4173 Not as of CVS version 1.4. 4174 4175 Last modified: _6/13/1997_ 4176 4177 4. Why doesn't "export" have a '-k' flag like "import" does? 4178 4179 Export is intended for a specific purpose -- to remove all trace of 4180 revision control on the way *out* of CVS. 4181 4182 Last modified: _6/13/1997_ 4183 4184 5. Why does "export -D" check out every file in the Attic? 4185 4186 See 5B.3 for an explanation of the same problem with "update". 4187 4188 Last modified: _6/13/1997_ 4189 4190 Category: /Commands_/history_hi_his/ 4191 4192 " + "history", "hi", "his"" 4193 4194 1. What is "history" for? 4195 4196 To provide information difficult or impossible to extract out of the 4197 RCS files, such as a "tag" history or a summary of module activities. 4198 4199 Last modified: _6/13/1997_ 4200 4201 2. Of what use is it? 4202 4203 I have found it useful in a number of ways, including: 4204 4205 Providing a list of files changed since 4206 4207 - A tagged release. 4208 - Yesterday, last Thursday, or a specific date. 4209 - Someone changed a specific file. 4210 4211 Providing a list of special events: 4212 4213 - Files added or removed since one of the above events. 4214 - Merge failures since one of the above events. (Where did the 4215 conflicts occur?) 4216 - Has anyone (and who) grabbed the revision of this file I committed 4217 last week, or are they still working blind? 4218 4219 Telling me how often a file/directory/module has been changed. 4220 4221 Dumping a summary of work done on a particular module, including who 4222 last worked on it and what changed. 4223 4224 Displaying the checked-out modules and where they are being worked 4225 on. 4226 4227 To tell me what users "joe" and "malcolm" have done this week. 4228 4229 Last modified: _6/13/1997_ 4230 4231 3. What is this, Big Brother? 4232 4233 War is Peace. 4234 Freedom is Slavery. 4235 Ignorance is Strength. 4236 4237 Normally manager types and those with the power to play Big Brother 4238 don't care about this information. The Software Engineer responsible 4239 for integration usually wants to know who is working on what and what 4240 changed. Use your imagination. 4241 4242 Last modified: _6/13/1997_ 4243 4244 4. I deleted my working directory and "history" still says I have it 4245 checked out. How do I fix it? 4246 4247 You can use "release -f" to forcibly add a "release" record to the 4248 history file for a working directory associated with a "module". If 4249 your version of "release" doesn't have the '-f' option, or you checked 4250 out the directory using a relative path, you have to edit the 4251 $CVSROOT/CVSROOT/history file. 4252 4253 You can remove the last 'O' line in the history file referring to the 4254 module in question or add an 'F' record. 4255 4256 Last modified: _6/13/1997_ 4257 4258 5. So I *can* edit the History file? 4259 4260 Yes, but if you are using history at all, you should take a little 4261 care not to lose information. I normally use Emacs on the file, since 4262 it can detect that a file has changed out from under it. You could 4263 also copy and zero out the history file, edit the copy and append any 4264 new records to the edited copy before replacing it. 4265 4266 Last modified: _6/13/1997_ 4267 4268 6. Why does the history file grow so quickly? 4269 4270 It stores 'U' records, which come in handy sometimes when you are 4271 tracking whether people have updated each other's code before testing. 4272 There should (and probably will sometime) be a way to choose what 4273 kinds of events go into the history file. 4274 4275 The contributed "cln_hist.pl" script will remove all the 'U' records, 4276 plus matching pairs of 'O' and 'F' records during your normal clean up 4277 of the history file. 4278 4279 Last modified: _6/13/1997_ 4280 4281 7. What is the difference between "cvs history -r <tag/rev>" and "cvs 4282 history -t <tag>"? 4283 4284 The '-t' option looks for a Tag record stored by "rtag" in the history 4285 file and limits the search to dates after the last <tag> of the given 4286 name was added. 4287 4288 The '-r' option was intended to search all files looking for the <tag> 4289 in the RCS files. It takes forever and needs to be rewritten. 4290 4291 Last modified: _6/13/1997_ 4292 4293 8. Why does "cvs history -c -t <tag>" fail to print anything? 4294 4295 You have been using "tag" instead of "rtag". The "tag" command 4296 currently doesn't store a history record. This is another remnant of 4297 CVS's earlier firm belief in "modules". But it also has a basis in how 4298 "rtag" and "tag" were originally used. 4299 4300 "rtag" was intended for large-scale tagging of large chunks of the 4301 Repository, an event work recording. "tag" was intended for adding and 4302 updating tags on a few files or directories, though it could also be 4303 used to tag the entire checked-out working tree when there is no 4304 module defined to match the tree or when the working tree is the only 4305 place where the right collection of revisions to tag can be found. 4306 4307 Last modified: _6/13/1997_ 4308 4309 9. "cvs history -a -o" only printed one line for each checked-out module. 4310 Shouldn't it print all the directories where the modules are checked out? 4311 4312 Not as designed. 4313 4314 Command Question it is supposed to answer. 4315 ---------------- ------------------------------------------ 4316 cvs history -o What modules do I have checked out? 4317 cvs history -a -o <same for all users> 4318 4319 cvs history -o -w What working directories have I created 4320 and what modules are in them? 4321 cvs history -a -o -w <same for every user> 4322 4323 The -o option chooses the "checked out modules" report, which is the 4324 default history report. 4325 4326 Last modified: _6/13/1997_ 4327 4328 10. I can't figure out "history", can you give me concrete examples? 4329 4330 Default output selects records only for the user who executes the 4331 "history" command. To see records for other users, add one or more "-u 4332 user" options or the '-a' option to select *all* users. 4333 4334 To list (for the selected users): Type "cvs history" and: 4335 4336 * Checked out modules: -o (the default) 4337 * Files added since creation: -x A 4338 * Modified files since creation: -c 4339 * Modified files since last Friday: -c -D 'last Friday' 4340 * Modified files since TAG was added: -c -t <tag> 4341 * Modified files since TAG on files: -c -r <tag> 4342 * Last modifier of file/Repository X? -c -l -[fp] X 4343 * Modified files since string "str": -c -b str 4344 * Tag history: (Actually "rtag".) -T 4345 * History of file/Repository/module X: -[fpn] X 4346 * Module report on "module": -m module 4347 4348 Last modified: _6/13/1997_ 4349 4350 11. Can we merge history files when we merge Repositories? 4351 4352 Assuming that the two Repositories have different sets of pathnames, 4353 it should be possible to merge two history files by sorting them 4354 together by the timestamp fields. 4355 4356 You should be able to run: 4357 4358 sort -k 1.2 ${dir1}/history ${dir2}/history > history 4359 4360 If you "diff" a standard history file before and after such a sort, 4361 you might see other differences caused by garbage (split lines, nulls, 4362 etc) in the file. If your Repository is mounted through NFS onto 4363 multiple machines you will also see a few differences caused by 4364 different clocks on different machines. (Especially if you don't use 4365 NTP to keep the clocks in sync.) 4366 4367 Last modified: _6/13/1997_ 4368 4369 Category: /Commands_/import_im_imp/ 4370 4371 " + "import", "im", "imp"" 4372 4373 1. What is "import" for? 4374 4375 The "import" command is a fast way to insert a whole tree of files 4376 into CVS. 4377 4378 The first "import" to a particular file within the Repository creates 4379 an RCS file with a single revision on the "Vendor branch." Subsequent 4380 "import"s of the same file within the Repository append a new revision 4381 onto the Vendor branch. It does not, as some seem to believe, create a 4382 new branch for each "import". All "imports" are appended to the single 4383 Vendor branch. 4384 4385 If the file hasn't changed, no new revision is created -- the new 4386 "Release-Tag" is added to the previous revision. 4387 4388 After the import is finished, files you have not changed locally are 4389 considered to have changed in the "Main line of development". Files 4390 you *have* changed locally must have the new Vendor code merged into 4391 them before they are visible on the "Main line". 4392 4393 See 4C.6 and 4C.15 4394 4395 Last modified: _6/13/1997_ 4396 4397 2. How am I supposed to use "import"? 4398 4399 Create a source directory containing only the files you want to 4400 import. Make sure you clean up any cruft left over from previous 4401 builds or editing. You want to make sure that the directory contains 4402 only what you want to call "source" from which everything else is 4403 built. 4404 4405 If this is not the first import from this "Vendor", you should also 4406 compare the output of "find . ! -name CVS -print | sort" executed both 4407 at the head of a checked out working directory and at the head of the 4408 sources to be imported. If you find any deleted or renamed files, you 4409 have to deal with them by hand. (See 4B.8 on renaming.) 4410 4411 "cd" into your source directory and type: 4412 4413 cvs import -m "Message" <repos> <Vendor-Tag> <Release-Tag> 4414 4415 where <repos> is the relative directory pathname within the Repository 4416 that corresponds to the sources you are importing. 4417 4418 You might also consider using the "-I !" option to avoid ignoring 4419 anything. It is easier to remove bogus files from the Repository than 4420 to create a sparse tree of the ignored files and rerun "import". 4421 4422 For example, if the FSF, CVS, Make and I are still active in the year 4423 2015, I'll import version 89.53 of GNU make this way: 4424 4425 cvs import -m "GNUmake V89.53" gnu/make GNU GNUMAKE_89_53 4426 4427 See 3H.13 for more details. 4428 4429 Last modified: _6/13/1997_ 4430 4431 3. Why does import put files on a branch? Why can't I work on the main 4432 trunk instead of a Vendor branch? 4433 4434 This was a Design choice. The Vendor branch is the way "import" deals 4435 with a Vendor release. It is a solution to the Engineering problem of 4436 how to merge multiple external releases of Vendor-supplied sources 4437 into your ongoing work. The Vendor releases are kept on a separate, 4438 special, "Vendor" branch and your work is kept on the RCS trunk. New 4439 Vendor releases are imported onto the Vendor branch and then merged 4440 into your work, if there is any, on the trunk. 4441 4442 This way, you can use CVS to find out not only about your work, but 4443 you can also find out what the Vendor changed by diffing between two 4444 of the Release Tags you handed to "import". 4445 4446 CVS was designed to work this way. If you use CVS in some other way, 4447 you should think carefully about what you are doing. 4448 4449 Note that the CVS "Main Branch" and the RCS Main Trunk are not the 4450 same. Placing files on the Vendor Branch doesn't keep you from 4451 creating a development branch to work on. 4452 4453 See Section 4C, on Branching. 4454 4455 If you are not working with 3rd party (i.e. Vendor) sources, you can 4456 skip the "import" and avoid the Vendor branch entirely. It works just 4457 as well to move pre-existing RCS files into Repository directories. 4458 4459 You can create a whole Repository tree by copying a directory 4460 hierarchy of normal source files directly into the Repository and 4461 applying CVS to it. Here's an idea you should *test* before using: 4462 4463 cd <your source tree> 4464 set source = `pwd` 4465 set module = xyzzy <<== Your choice of directory name 4466 mkdir $CVSROOT/$module 4467 cd $CVSROOT/$module 4468 (cd $source; tar cf - .) | tar xvpBf - 4469 find . -type f -exec ci -t-Original. {} \; 4470 4471 The RCS "ci" command, without -u or -l options, will turn your source 4472 file into an RCS (",v") and delete the original source. 4473 4474 Last modified: _6/13/1997_ 4475 4476 4. Is there any way to import binary files? 4477 4478 If you configured CVS to use the GNU version of "diff" and "diff3", 4479 then you can import any kind of file. 4480 4481 Binary files with RCS keywords in them are a problem, since you don't 4482 want them to expand. 4483 4484 If the tree you are about to "import" is entirely filled with binary 4485 files, you can use the '-ko' option on "import". Otherwise, I would 4486 run the import normally, then fix the binary files as described below 4487 in 3H.5. 4488 4489 See 4D.1 on Binary files. 4490 4491 Last modified: _6/13/1997_ 4492 4493 5. Why does "import" corrupt some binary files? 4494 4495 The RCS "co" command, when it is invoked by a CVS "checkout" or 4496 "update" (or after a "commit") command, searches for and expands a 4497 list of keywords within the file. They are documented in the RCS "co" 4498 man page. Strings such as "$\Id$" (or "$\Id:"), or "$\Revision$" (or 4499 "$\Revision:") are altered to the include the indicated information. 4500 4501 [[Note: The keywords should appear in the text without the '\' 4502 character I have inserted to *avoid* expansion here. The only real RCS 4503 keywords in this document are at the top of the file, where I store 4504 the Revision and Date.]] 4505 4506 If RCS keyword strings show up in a binary file, they will be altered 4507 unless you set the '-ko' option on the RCS files to tell RCS to keep 4508 the original keyword values and not to expand new ones. After 4509 "import", you can set the '-ko' option this way: 4510 4511 cvs admin -ko <file> 4512 rm <file> 4513 cvs update <file> 4514 4515 After an import that didn't use '-ko' (because the whole tree wasn't 4516 of binary files) you should fix up the binary files as described above 4517 before checking out any new copies of the files and before updating 4518 any working directories you checked out earlier. 4519 4520 See 4D.1 on Binary files. 4521 4522 Last modified: _6/13/1997_ 4523 4524 6. How do I retain the original $\Revision$ strings in the sources? 4525 4526 If you want to leave old RCS keywords as they are, you can use the 4527 '-ko' tricks described above. 4528 4529 Last modified: _6/13/1997_ 4530 4531 7. I imported some files for the Yarg compiler that compiles files with a 4532 suffix of ".yarg" and whose comment prefix is "YARG> ". When I check them 4533 out, they will no longer compile because they have this junk in them. Why? 4534 4535 YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG> 4536 YARG> $\Log: 4537 # Revision 1.3 1998/03/03 00:16:16 bubba 4538 # What is 2+2 anyway? 4539 # 4540 # Revision 1.2 1998/03/03 00:15:15 bubba 4541 # Added scorekeeping. 4542 YARG> 4543 YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG> 4544 4545 Well bubba, "Yarg" hasn't hit the big time yet. Neither RCS nor CVS 4546 know about your suffix or your comment prefix. So you have two 4547 choices: 4548 4549 Check out the Yarg-less module, and tell all the files about your 4550 comment prefix. Visit each directory and type: 4551 4552 cvs admin -c"YARG> " *.yarg 4553 4554 If *all* files in the whole directory tree are Yarg files, you can use 4555 this instead: 4556 4557 cvs admin -c"YARG> " . 4558 4559 Then save any changes you made, remove all the "*.yarg" files and grab 4560 new copies from the Repository: 4561 4562 rm *.yarg (or: find . -name '*.yarg' -exec rm {} ';') (or: find . 4563 -name '*.yarg' -print | xargs rm) (or: find . -name '*.yarg' -print0 | 4564 xargs -0 rm if you have spaces in filenames and the GNU find/xargs.) 4565 cvs update 4566 4567 It might be faster to remove the whole directory and check it out 4568 again. 4569 4570 Change the import.c file in the CVS sources and add the .yarg 4571 suffix, along with the "YARG> " comment prefix to the "comtable" 4572 array. 4573 4574 If you ever plan to add new files with $\Log in them, you should also 4575 go into the RCS sources and make the same change in the table 4576 contained in the "rcsfnms.c" file. 4577 4578 Then delete the imported files from the Repository and re-"import" the 4579 sources. 4580 4581 Last modified: _6/13/1997_ 4582 4583 8. How do I make "import" save the timestamps on the original files? 4584 4585 Use "import -d" to save the current timestamps on the files as the RCS 4586 revision times. 4587 4588 See 4D.8 for another aspect of file timestamps. 4589 4590 Last modified: _6/13/1997_ 4591 4592 9. Why can't I "import" 3 releases on different branches? 4593 4594 I'll bet you typed something like this: 4595 4596 cd /src/blasto.v2 4597 cvs import -b 1.1.2 VENDOR2 Version2 4598 cd /src/blasto.v3 4599 cvs import -b 1.1.3 VENDOR3 Version3 4600 cd /src/blasto.v4 4601 cvs import -b 1.1.4 VENDOR4 Version4 4602 4603 This is wrong, or at least it won't help you much. You have created 4604 three separate Vendor branches, which is probably not what you wanted. 4605 4606 Earlier versions of CVS, as described in Brian Berliner's Usenix 4607 paper, tried to support multiple Vendor branches on the theory that 4608 you might receive source for the *same* program from multiple vendors. 4609 It turns out that this is very rare, whereas the need to branch in 4610 *your* development, for releases and for project branches, is much 4611 greater. 4612 4613 So the model now is to use a single vendor branch to contain a series 4614 of releases from the same vendor. Your work moves along on the Main 4615 Trunk, or on a CVS branch to support a real "branch in development". 4616 4617 To set this up, you should type this instead of the above: 4618 4619 cd /src/blasto.v2 4620 cvs import VENDOR Version2 4621 cd /src/blasto.v3 4622 cvs import VENDOR Version3 4623 cd /src/blasto.v4 4624 cvs import VENDOR Version4 4625 4626 Last modified: _6/13/1997_ 4627 4628 10. What do I do if the Vendor adds or deletes files between releases? 4629 4630 Added files show up with no extra effort. To handle "removed" files, 4631 you should always compare the tree structure of the new release 4632 against the one you have in your Repository. If the Vendor has removed 4633 files since the previous release, go into a working directory 4634 containing your current version of the sources and "cvs remove" 4635 (followed by "cvs commit" to make it really take effect) each file 4636 that is no longer in the latest release. 4637 4638 Using this scheme will allow you to "checkout" any version of the 4639 vendor's code, with the correct revisions and files, by using 4640 "checkout -r Version[234]". 4641 4642 Renames are harder to find, since you have to compare file contents to 4643 determine that one has occurred. If you notice one, see 4B.8 on 4644 renaming files. 4645 4646 Last modified: _6/13/1997_ 4647 4648 11. What about if the Vendor changes the names of files or directories, or 4649 rearranges the whole structure between releases? 4650 4651 Currently CVS can't handle this cleanly. It requires "renaming" a 4652 bunch of files or directories. 4653 4654 See 4B.8 on "renaming" for more details. 4655 4656 What I generally do is to close the Repository for a while and make 4657 changes in both the Repository and in a copy of the vendor release 4658 until the structure matches, then execute the import. 4659 4660 If you ever have to check out and build an old version, you may have 4661 to use the new, or completely different Makefiles. 4662 4663 Last modified: _6/13/1997_ 4664 4665 12. I thought "import" was for Vendor releases, why would I use it for code 4666 of my own? Do I have to use import? 4667 4668 For code you produce yourself, "import" is a convenience for fast 4669 insertion of whole trees. It is not necessary. You can just as easily 4670 create ",v" files using the RCS "ci" command and move them directly 4671 into the Repository. 4672 4673 Other than the CVSROOT directory, the Repository consists entirely of 4674 directories of ",v" files. The Repository contains no other state 4675 information. 4676 4677 See Section 4B, on Setting up and Managing the Repository. 4678 4679 Last modified: _6/13/1997_ 4680 4681 13. How do I import a large Vendor release? 4682 4683 When the sum of the changes made by the Vendor and the changes made by 4684 local developers is small, "import" is not a big problem. But when you 4685 are managing a large Repository, any care taken up front will save you 4686 time later. 4687 4688 First read the following, then, before executing "import", see the 4689 questions in Section 4C dealing with branch merges and Vendor branch 4690 merges. 4691 4692 If this is not the first import of this code, before starting, rtag 4693 the whole directory you will be changing. 4694 4695 The first step is to make sure the structure of the new files 4696 matches the structure of the current Repository. 4697 4698 Run "find . -print | sort" on both trees and "diff" the output. 4699 4700 Alter the "source" tree until the "diff" (of the list of filenames, 4701 not of the whole trees) shows that the directory structures are 4702 equivalent. 4703 4704 The "comm" command, if you have it, can help figure out what has been 4705 added or deleted between releases. 4706 4707 If they deleted any files, you can handle them cleanly with "cvs 4708 remove". The command "comm -23 files.old files.new" will show you a 4709 list of files that need to be removed. 4710 4711 You should examine the list first to see if any have been renamed 4712 rather than simply deleted. 4713 4714 If they renamed any files, see 4B.8 on renaming files. 4715 4716 Remember to *SAVE* the output from the import command. 4717 4718 When you have dealt with removed and renamed files, then you can 4719 execute the import: 4720 4721 cd <new source> 4722 cvs import -I ! -m "Message" <repos> <VendorTag> <ReleaseTag> 4723 4724 Where 4725 4726 "-I !" is an optional argument that keeps "import" from ignoring 4727 files. The comparison of the "find" commands above will probably avoid 4728 the need for this, but it is easier to remove files from the 4729 Repository than to run a subset "import" to catch just the ignored 4730 files. [You might have to quote or backwhack the '!'.] 4731 4732 Message is the log message to be stored in the RCS files. 4733 4734 <repos> is a relative path to a directory within the 4735 Repository. The directory <new source> must be at 4736 the same relative level within the new sources as 4737 the <repos> you give is within the Repository. (I 4738 realize this is not obvious. Experiment first.) 4739 4740 <VendorTag> is a Tag used to identify the Vendor who sent you 4741 the files you are importing. All "imports" into 4742 the same <repos> *must* use the same VendorTag. 4743 You can find it later by using the "log" command. 4744 4745 <ReleaseTag> is a Tag used to identify the particular release of the 4746 software you are importing. It must be unique and should be mnemonic 4747 -- at least include the revision number in it. (Note: you can't use 4748 '.' characters in a Tag. Substitute '_' or '-'.) 4749 4750 There will be six categories of files to deal with. (Actually there 4751 are eight, but you have already dealt with "removed" and "renamed" 4752 files.) 4753 4754 If this is the first "import" into a given <repos> directory, only the 4755 first three of these ('I', 'L' and 'N') can occur. 4756 4757 Ignored file. 4758 4759 CVS prints: I filename 4760 4761 You'll need to examine it to see if it *should* have been ignored. If 4762 you use "-I !", nothing will be ignored. 4763 4764 Symbolic link. 4765 4766 CVS prints: L linkname 4767 4768 Links are "ignored", but you'll probably want to create a "checkout 4769 helper" function to regenerate them. 4770 4771 New file. 4772 4773 CVS prints: N filename 4774 4775 CVS creates a new file in the Repository. You don't have to do 4776 anything to the file, but you might have to change Makefiles to refer 4777 to it if this is really a new file. 4778 4779 A file unchanged by the Vendor since its last release. 4780 4781 CVS prints: U filename 4782 4783 CVS will notice this and simply add the new ReleaseTag to the latest 4784 rev on the Vendor branch. 4785 4786 No work will be needed by you, whether you have changed the file or 4787 not. No one will notice anything. 4788 4789 A file changed by the Vendor, but not by you. 4790 4791 CVS prints: U filename 4792 4793 CVS should add the file onto the vendor branch and attach the Release 4794 Tag to it. 4795 4796 When you next execute "update" in any working directory you'll get the 4797 new revision. 4798 4799 A file changed by both the Vendor and by you. 4800 4801 CVS prints: C filename 4802 4803 These are the trouble files. For each of these files (or in groups -- 4804 I usually do one directory at a time), you must execute: 4805 4806 cvs update -j <PreviousReleaseTag> -j <ReleaseTag> 4807 or 4808 cvs update -j <VendorTag:yesterday> -j <VendorTag> 4809 4810 It will print either 'M' (if no overlaps) or 'C', if overlaps. If a 4811 'C' shows up, you'll need to edit the file by hand. 4812 4813 Then, for every file, you'll need to execute "cvs commit". 4814 4815 See the part of Section 4C dealing with branch merges. 4816 4817 If you are truly performing a large import, you will most likely 4818 need help. Managing those people is another problem area. 4819 4820 Since the merge of the Vendor branch is just like any other merge, you 4821 should read section 4C for more info about performing and cleaning up 4822 merges. 4823 4824 The larger the import, and the larger the group of people involved, 4825 the more often you should use "tag" and "rtag" to record even trivial 4826 milestones. See 4C.14, especially the "paranoid" section. 4827 4828 Before starting the import, you should install and test a "commitinfo" 4829 procedure to record all commits in a file or via Email to a mail 4830 archive. Along with the tags you placed on the Repository before the 4831 import, this archive will help to track what was changed, if problems 4832 occur 4833 4834 There are four stages to the recovery: 4835 4836 Parcel out the work -- Effective Emacs Engineering. 4837 4838 As input to the assignment process, you might want to examine the tree 4839 and record the last person who changed the file. You can also 4840 research, if you don't already know, who is expert in each area of the 4841 software. 4842 4843 Examine the import log (you saved the output, right?), estimate how 4844 much work is involved in each area and assign groups of files to 4845 individual developers. Unless some directory is immense, it is easier 4846 to manage if you assign whole directories to one person. 4847 4848 Keep a list. Suggest a completion date/time. Tell them to "commit" the 4849 file when they are finished with the merge. If you tagged the 4850 Repository before starting the import, you should have no trouble 4851 figuring out what happened. 4852 4853 If you can, find out (or tell them) which working directory to use. 4854 You should verify that the working directory they use is on the Main 4855 Branch ("update -A") and without modified files. 4856 4857 If you trust your crew, have them notify you by Email. Have them send 4858 you the output from "cvs update" in their working directory. You might 4859 have to poll some people until you are certain they have finished, or 4860 have given up. (This is not an invention. I've heard a false, "Yeah, 4861 sure. I finished yesterday," more times that you'd believe.) 4862 4863 When all reports are in, go on to the Source Verification stage. 4864 4865 Source Verification -- CVS and other Tools. 4866 4867 If you didn't dictate which ones to use, find all working directories 4868 and run "cvs -n update" in all of them. The history command and the 4869 "commitinfo" log you set up might help to find checked out working 4870 directories. 4871 4872 Sticky conflict flags will help, but they can't recover from 4873 sloppiness or incompetence. You might want to check everything out 4874 into a tree and grep for the parts of the merge conflict markers CVS 4875 doesn't look for. CVS looks for the string '^>>>>>>> '. The merge 4876 operation also puts '^<<<<<<< ' and '^======= ' markers in the file 4877 that careless developers might leave there. 4878 4879 If you find problems simply by looking at the source files and working 4880 directories, start the flogging now. Resolving the textual conflicts 4881 is the easy part. Weed the turkeys out before reaching the next part 4882 of the cleanup -- the resolution of logical conflicts. 4883 4884 Then apply a set of post-commit tags. 4885 4886 Logical Verification -- Diff and powerful eyeballs. 4887 4888 No source control system can solve the problem of resolving 4889 distributed conflicts in program logic. If you change the argument 4890 template for function A (defined in file A.c) and add new calls to 4891 function A from within function B (defined in file B.c) using the old 4892 argument format, you are outside the realm of CVS's competence. 4893 4894 Assign someone to understand what the Vendor changed by running "cvs 4895 diff -c -r <PreviousReleaseTag> <ReleaseTag>", where the tags were 4896 those handed to the last two invocations of "import". 4897 4898 Then have the same person compare that output (logically or you can 4899 actually diff the diffs) to the output of the similar "cvs diff -c -r 4900 <pre-import-tag> <post-commit-tag>". The two sets of differences 4901 should be almost identical. They should both show only the work *you* 4902 have performed. 4903 4904 Product Verification -- Build and Test. 4905 4906 Don't let your help off the hook until you verify that the merge 4907 actually produced something that can compile and pass tests. Compiling 4908 should really be part of the logical verification phase, but you 4909 should test the output of the build system before declaring victory 4910 and releasing the troops. 4911 4912 After it is all built, apply another set of tags to mark the end of 4913 the "import process". You can delete the intermediate tags you added 4914 during source and logic testing, but keep the "pre-import" and 4915 "post-import" tags forever. 4916 4917 Of course, experience can tell you when to skip a step. But I'd start 4918 out by considering each one as necessary unless you can prove 4919 otherwise. 4920 4921 Last modified: _6/13/1997_ 4922 4923 14. Explain: ERROR: cannot create link to <file>: Permission denied 4924 4925 This error appears when you try to execute a second (or later) 4926 "import" into the same module from a directory to which you don't have 4927 write access. 4928 4929 The "link error" is caused by a feature purposely added to speed up 4930 the import. 4931 4932 Though the error message is somewhat strange, it indicates that 4933 "import" is supposed to be executed only in writable directories. 4934 4935 Last modified: _6/13/1997_ 4936 4937 15. Where does the -m <message> go when the file doesn't change? 4938 4939 The <message> handed to import is used as an RCS log message, but only 4940 if the imported file changed since the last version on the Vendor 4941 branch. If the imported file hasn't changed, then no new revision is 4942 created. The <ReleaseTag> is still applied, but to the previous 4943 revision. So the Tags are still correct, but the message is lost. 4944 4945 Maybe it should be appended to the previous log message. But currently 4946 it isn't. 4947 4948 Last modified: _6/13/1997_ 4949 4950 16. How do I "import" just the files ignored by a previous "import"? 4951 4952 A real answer follows, but first, an editorial: 4953 4954 I am now convinced that you should always use the "-I !" option. 4955 Removing a few extraneous files from the Repository is a lot easier 4956 than the recovery step described below. 4957 4958 Let's assume your original import procedure was: (We assume there is 4959 enough disk space in /tmp.) 4960 4961 cd <head-of-vendor-tree> 4962 cvs import -m 'xyz 1.3' gnu/xyz GNU GNUXYZ_1_3 | tee /tmp/IMP 4963 4964 To import just the files ignored by "import", I would do this: 4965 4966 Create a list of the ignored files to import: 4967 4968 cd <head-of-vendor-tree> awk '/^I / {print $2}' /tmp/IMP | sed 4969 's|^gnu/xyz/||' > /tmp/IG [Edit the IG file to contain just the files 4970 you want.] 4971 4972 Then create a sparse directory by handing your list to the GNU 4973 version of "tar", installed in many places as "gtar": 4974 4975 mkdir /tmp/FIXUP gtar -T /tmp/IG -c -f - . | (cd /tmp/FIXUP; gtar xvBf 4976 -) 4977 4978 Then rerun the import. Use the exact same command, but execute it in 4979 the sparse directory tree you just created. And this time, tell it not 4980 to ignore anything. 4981 4982 cd /tmp/FIXUP 4983 cvs import -I ! -m 'xyz 1.3' gnu/xyz GNU GNUXYZ_1_3 4984 4985 Last modified: _6/13/1997_ 4986 4987 17. Why did "import" ignore all the symlinks? 4988 4989 This is another design choice. 4990 4991 Like the Unix "tar" command, "import" could sprout an option to follow 4992 symbolic links, but I don't think CVS will ever follow symbolic links 4993 by default. 4994 4995 Two possible future enhancements have been seriously discussed: 4996 4997 Treat symbolic links as data in its parent directory (the way 4998 ClearCase does) in some sort of per-directory control file. 4999 5000 Treat symbolic links as version-controlled elements themselves, 5001 whose data is the value of readlink(2). 5002 5003 For now, they are simply ignored. 5004 5005 If you want to save and reconstruct symlinks, you might want to define 5006 a "checkout" or "update" program in the modules file which could 5007 consult a file kept under CVS in your working directory and make sure 5008 the specified links are in place. 5009 5010 Last modified: _6/13/1997_ 5011 5012 Category: /Commands_/log_lo_rlog/ 5013 5014 " + "log", "lo", "rlog"" 5015 5016 1. What is "log" for? 5017 5018 To provide an interface to the RCS "rlog" command, which displays 5019 information about the underlying RCS files, including the revision 5020 history and Tag (RCS calls it a "symbol") list. 5021 5022 Last modified: _6/13/1997_ 5023 5024 2. How do I extract the log entries between two revisions? 5025 5026 If both <rev1> and <rev2> are on the same branch, you can get what you 5027 are looking for with: (If they aren't on the same branch you'll either 5028 get an error or a display of the whole change log.) 5029 5030 cvs log -r<rev1>:<rev2> <file> 5031 5032 If you want all the revisions on the branch from <rev1> to the end of 5033 the branch <rev1> is on, you can use: 5034 5035 cvs log -r<rev1>: <file> 5036 5037 (If <rev1> is a numeric RCS symbol attached to a branch revision with 5038 an even number of '.'s in it, you get the whole branch.) 5039 5040 If you want all the revisions on the branch from the beginning of the 5041 branch <rev2> is on up to revision <rev2>, you can use: 5042 5043 cvs log -r:<rev2> <file> 5044 5045 Note: Depending on whether <rev1> and <rev2> are: 5046 5047 - numeric or symbolic 5048 - in the file or not 5049 - on the same branch or not 5050 5051 the RCS "rlog" (and therefore the "cvs log") command will 5052 display some combination of: 5053 5054 - error messages 5055 - (intuitively correct) partial log listings 5056 - a display of the entire change log. 5057 5058 Last modified: _6/13/1997_ 5059 5060 3. How do I extract the log entries on a whole branch? 5061 5062 cvs log -r<rev> <file> 5063 5064 where <rev> must be a branch revision (one with an even number of 5065 dots) or a *non-branch* tag on a branch revision. Non-branch tags on a 5066 branch revision are not normally attached by CVS, to add one you will 5067 have to explicitly tag a physical branch number within each file. 5068 Since these branch numbers are almost never the same in different 5069 files, this command is not all that useful. 5070 5071 The intuitive command (at least from the CVS perspective): 5072 5073 cvs log -r<branch_tag> <file> 5074 5075 does not work. 5076 5077 Last modified: _6/13/1997_ 5078 5079 4. How do I generate ChangeLogs from RCS logs? 5080 5081 A program called rcs2log is distributed as part of GNU Emacs 19. A 5082 (possibly older) version of this program appears in the contrib 5083 directory of the cvs source tree. 5084 5085 Last modified: _6/13/1997_ 5086 5087 5. Why does "log" tell me a file was committed exactly 5 hours later 5088 5089 than I know it was? 5090 5091 I can tell by this question that you were working in a time zone that 5092 is 5 hours behind GMT (e.g. the U.S. East Coast in winter). 5093 5094 RCS file dates are stored in GMT to allow users in different time 5095 zones to agree on the meaning of a timestamp. At first glance this 5096 doesn't seem necessary, but many companies use distributed file 5097 systems, such as NFS or AFS, across multiple timezones. 5098 5099 Some standard form must be used. GMT, as the "grid origin", is an 5100 obvious candidate. The only other reasonable choice is to put the 5101 timezone information in all the time stamps, but that changes the RCS 5102 file format incompatibly, a step which has been avoided in the last 5103 few RCS releases. 5104 5105 Last modified: _6/13/1997_ 5106 5107 Category: /Commands_/patch_pa_rdiff/ 5108 5109 " + "patch", "pa", "rdiff"" 5110 5111 1. What is "patch" for? 5112 5113 To produce a "diff" between tagged releases to be handed to the 5114 "patch" command at other sites. This is the standard way that source 5115 patches are distributed on the network. 5116 5117 Last modified: _6/13/1997_ 5118 5119 2. Why does "patch" include files from the Attic when I use '-D'? 5120 5121 See the explanation of the same problem with "update -D" contained in 5122 section 5B. 5123 5124 Last modified: _6/13/1997_ 5125 5126 3. How do I make "patch" produce a patch for one or two files? It seems to 5127 work only with modules. 5128 5129 Patch is intended for producing patches of whole modules between 5130 releases to be distributed to remote sites. Instead of "patch", you 5131 can use the "diff" command with the '-c' context option: 5132 5133 cvs diff -c -r <rev/tag> -r <rev/tag> <file1> . . . 5134 5135 The patch command will be able to merge such a "diff" into the remote 5136 source files. 5137 5138 If you configured CVS to use a version of "diff" that supports the 5139 '-u' option, you can produce a more compact "patch" in "unidiff" 5140 format. The latest revisions of the patch command can parse and apply 5141 patches in "unidiff" format. 5142 5143 Last modified: _6/13/1997_ 5144 5145 Category: /Commands_/release_re_rel/ 5146 5147 " + "release", "re", "rel"" 5148 5149 1. What is "release" for? 5150 5151 To register that a module is no longer in use. It is intended to 5152 reverse the effects of a "checkout" by adding a record to the history 5153 file to balance the checkout record and by optionally allowing you to 5154 delete the checked-out directory associated with the module name. 5155 5156 Last modified: _6/13/1997_ 5157 5158 2. Why can't I reverse a "cvs checkout path/name/subdir" with a "cvs 5159 release path/name/subdir" without an "unknown module name"? 5160 5161 A simplistic implementation. (I can say this -- I wrote it.) 5162 5163 The "release" function was written for CVS 1.2 under the assumption 5164 that the "module name" is a first class, unavoidable interface to the 5165 Repository, allowing no way to retrieve anything other than by module 5166 name. Though it is easier to program that way, many users of CVS 5167 believe the modules support to be too primitive to allow such a 5168 limitation. 5169 5170 Since "release" was written, other parts of CVS broke that assumption. 5171 It needs to be revised. 5172 5173 Last modified: _6/13/1997_ 5174 5175 3. Why can't I "release" portions of a checked out directory? I should be 5176 able to "release" any file or sub-directory within my working directory. 5177 5178 This isn't really a limitation in "release", per se. CVS doesn't try 5179 to keep track of which files in which directories are "checked out" 5180 and which are just lying there. You can delete directories and 5181 "update" will not bring them back unless you add a special "-d" 5182 option. 5183 5184 In other words, CVS doesn't keep track of how you adjust the partition 5185 between files you consider part of your working set and files that 5186 were checked out because they are part of the same module or 5187 directory. And neither does "release". 5188 5189 In future CVS releases, "release" might become sophisticated enough to 5190 handle both the reversal of a "checkout" and the deletion of random 5191 portions of the working directory, but it isn't that way now. 5192 5193 Last modified: _6/13/1997_ 5194 5195 4. I removed the tree that I was about to start working on. How do I tell 5196 cvs that I want to release it if I don't have it anymore? 5197 5198 See 3G.4. 5199 5200 Last modified: _6/13/1997_ 5201 5202 5. Why doesn't "release -d module" reverse a "checkout module"? 5203 5204 It does, if you are using "module" in a way that "release" expects: a 5205 non-alias string in the left column of the "modules" database. 5206 5207 If "module" is really an alias, or if you are using a relative path in 5208 the place of "module", or if you renamed the directory with the -d 5209 option in the modules file or on the "checkout" command line, then the 5210 current version of "release" won't work. 5211 5212 Future versions of "release" will probably fix most of these. 5213 5214 Last modified: _6/13/1997_ 5215 5216 6. Why can't I release a module renamed with "cvs checkout -d"? 5217 5218 The current version of "release" doesn't know how to track the 5219 renaming option ('-d') of the "checkout" command. It will probably be 5220 fixed in the future. 5221 5222 Last modified: _6/13/1997_ 5223 5224 Category: /Commands_/remove_rm_delete/ 5225 5226 " + "remove", "rm", "delete"" 5227 5228 1. What is "remove" for? 5229 5230 To remove a file from the working branch. It removes a file from the 5231 main branch by placing it in an "Attic" directory. 5232 5233 Last modified: _6/13/1997_ 5234 5235 2. Why doesn't "remove" work on directories when it appears to try? 5236 5237 Oversight. It should be able to delete an empty directory, but you 5238 still don't have a way to remember when it was there and when it 5239 disappeared to allow the "-D " option to work. 5240 5241 You'll have to remove the working directory and the matching directory 5242 in the Repository. 5243 5244 Note that you want to do a _cvs remove dir_ in the working directory, 5245 do a cvs commit, and then do a _rmdir dir_ in the Repository. 5246 (msusrtsp.mark at eds dot com) 5247 5248 Last modified: _12/18/1997_ 5249 5250 3. I don't like removing files. Is there another way to ignore them? 5251 5252 There's no reason to be hasty in using the "remove" command. 5253 5254 If there is a way to ignore files in your build procedures, I'd just 5255 do that. Later, when you decide that the files are really ancient, you 5256 can execute a "remove" command to clean up. 5257 5258 The CVS "ignore" concept can't ignore files already in CVS. 5259 5260 Last modified: _6/13/1997_ 5261 5262 4. I just removed a file. How do I resurrect it? 5263 5264 If you executed "remove", but haven't typed "commit" (you can tell 5265 this by the 'R' notation that "update" prints next to the file), you 5266 can execute "add" to reverse the "remove". 5267 5268 If you followed the "remove" with a "commit", you'll have to move it 5269 back out of the Attic by hand: 5270 5271 I use something like this: (csh-like syntax) 5272 5273 set repos = `cat ./CVS/Repository` 5274 mv $repos/Attic/filename,v $repos/filename,v 5275 5276 (If you use relative paths in your Repository files, that first line 5277 becomes: set repos = $CVSROOT/`cat ./CVS/Repository`) 5278 5279 While a file is in the Attic, you can't "add" another file by the same 5280 name. To add such a file you either have to move it by hand as in the 5281 above, or delete it from the Attic. 5282 5283 The main reason for the Attic is to retain files with tags in them. If 5284 you execute: "update -r <oldtag>", files with <oldtag> attached to 5285 some revision will be taken from the normal Repository area and from 5286 the Attic. That's why you can't "add" a file with the same name. 5287 "remove" only moves a file off the main branch, it doesn't obliterate 5288 it. 5289 5290 Last modified: _6/13/1997_ 5291 5292 5. Why doesn't "remove" delete the file? Instead, it prints an error 5293 message and tells me to remove the file by hand. 5294 5295 Design choice. Unix software written within last decade, usually 5296 requires an extra verification step, such as answering a question or 5297 adding a flag on the command line. CVS currently requires that you 5298 delete the file first unless you specify the '-f' (force) option, 5299 which deletes the file before performing "cvs remove". 5300 5301 Last modified: _6/13/1997_ 5302 5303 Category: /Commands_/rtag_rt_rfreeze/ 5304 5305 " + "rtag", "rt", "rfreeze"" 5306 5307 1. What is "rtag" for? 5308 5309 To add a symbolic label (a "tag") to the last committed revisions of a 5310 module directly in the Repository. 5311 5312 Last modified: _6/13/1997_ 5313 5314 2. Why use "rtag"? It assumes no one is changing the Repository. 5315 5316 Though the "tag" command is more useful in marking the revisions you 5317 have in a particular working directory, "rtag" is much handier for 5318 whole-Repository actions, which occur at major release boundaries. 5319 5320 Last modified: _6/13/1997_ 5321 5322 3. What revision does "rtag -r <tag1> <tag2>" actually put the tag on? 5323 5324 In short, the '-r' option is another way to select the revision to 5325 tag. The revision is selected the same way for all commands that 5326 accept a "-r <tag/rev>" option. 5327 5328 Depending on whether <tag1> is a <branch_tag>, or a non-branch <tag> 5329 and on whether you use the '-b' option to "rtag", you get four 5330 different results: 5331 5332 rtag -r <tag1> <tag2> 5333 5334 Adds the non-branch tag <tag2> to the same revision that the 5335 non-branch tag <tag1> is attached to. 5336 5337 Example: 5338 <tag1> --> TT1 5339 <tag2> --> TT2 5340 <file> --> Symbols: TT1:1.4 5341 After --> Symbols: TT1:1.4,TT2:1.4 5342 5343 rtag -r <branch_tag1> <tag2> 5344 5345 Adds the non-branch tag <tag2> to the HEAD of (the highest revision 5346 number on) the branch labelled with tag <branch_tag1>. 5347 5348 Example: 5349 <branch_tag1> --> BR1 5350 <tag2> --> TT2 5351 <file> --> Symbols: BR1:1.2.0.2 (1.2.2.5 is HEAD) 5352 After --> Symbols: BR1:1.2.0.2,TT2:1.2.2.5 5353 5354 If the branch tagged by <branch_tag1> has not been created, then the 5355 tag shows up on the branch point revision: 5356 5357 Example: 5358 <branch_tag1> --> BR1 5359 <tag2> --> TT2 5360 <file> --> Symbols: BR1:1.2.0.2 (No 1.2.X exists.) 5361 After --> Symbols: BR1:1.2.0.2,TT2:1.2 5362 5363 rtag -b -r <tag1> <branch_tag2> 5364 5365 Adds the magic branch tag <branch_tag2> to the revision that the 5366 non-branch tag <tag1> is attached to, preparing it to be a branch 5367 point. 5368 5369 Example: 5370 <tag1> --> TT1 5371 <branch_tag2> --> BR2 5372 <file> --> Symbol: TT1:1.4 5373 After --> Symbol: TT1:1.4, BR2:1.4.0.2 5374 5375 rtag -b -r <branch_tag1> <branch_tag2> 5376 5377 Adds the magic branch tag <branch_tag2> to the revision at the HEAD of 5378 (the highest revision number on) the branch labelled with 5379 <branch_tag1>, preparing it to be a branch point. 5380 5381 Example: 5382 <branch_tag1> --> BR1 5383 <branch_tag2> --> BR2 5384 <file> --> Symbol: BR1:1.2.0.2 (1.2.2.5 is HEAD) 5385 After --> Symbol: BR1:1.2.0.2,BR2:1.2.2.5.0.2 5386 5387 If the branch tagged by <branch_tag1> has not been created, then the 5388 tag shows up as a second branch off the same branch point revision: 5389 5390 Example: 5391 <branch_tag1> --> BR1 5392 <tag2> --> TT2 5393 <file> --> Symbols: BR1:1.2.0.2 (No 1.2.X exists.) 5394 After --> Symbols: BR1:1.2.0.2,TT2:1.2.0.4 5395 5396 In all four cases above, if <tag2> already exists on the file, you get 5397 an error unless you specify the '-F' option. 5398 5399 In all four cases, if <tag1> does not exist on the file, <tag2> is not 5400 added unless you specify the '-f' option. 5401 5402 Last modified: _6/13/1997_ 5403 5404 4. What happens if the tags are the same in "rtag -r <tag> <tag>"? 5405 5406 Again, there are four cases depending on whether <tag> is a branch 5407 tag, or a non-branch tag and on whether you use the '-b' option to 5408 "rtag": 5409 5410 rtag -r <tag> <tag> 5411 5412 Is a no-op. It does nothing even with '-F' specified. 5413 5414 If you add the '-f' option ("rtag -f -r <tag> <tag>"), then <tag> is 5415 attached to the latest revision on the Main Branch if the file does 5416 *not* already have <tag> on some revision. 5417 5418 If the <tag> is already on the file, using "rtag -f" is still a no-op. 5419 5420 rtag -r <branch_tag> <branch_tag> 5421 5422 Produces an error, since the <branch_tag> is already on some revision 5423 of the file. 5424 5425 But, "rtag -F -r <branch_tag> <branch_tag>" turns the magic branch tag 5426 into a non-branch tag. 5427 5428 Symbols: BR1:1.4.0.2 becomes Symbols: BR1:1.4 5429 5430 rtag -b -r <tag> <tag> 5431 5432 Produces an error, since the <tag> is already on the file. 5433 5434 But, "rtag -F -b -r <tag> <tag>" turns the non-branch tag into a magic 5435 branch tag. 5436 5437 Symbols: BR1:1.4 becomes Symbols: BR1:1.4.0.2 5438 5439 rtag -b -r <branch_tag> <branch_tag> 5440 5441 Produces an error, since the <branch_tag> is already on the file. 5442 5443 But, "rtag -F -b -r <branch_tag> <branch_tag>" increments the branch 5444 number. It essentially removes the branch and creates a new one by the 5445 same name. 5446 5447 Symbols: BR1:1.2.0.4 becomes Symbols: BR1:1.2.0.6 5448 5449 Last modified: _6/13/1997_ 5450 5451 5. Why doesn't "rtag -b -r <branch_tag1> <branch_tag2>" rename or duplicate 5452 a magic branch tag? 5453 5454 None of the "tag" or "rtag" options rename anything. They only apply 5455 (or, with the '-F' option, move) tags to specific revisions in the 5456 file. 5457 5458 See 3M.[3-4] above for details of how it works. 5459 5460 To rename a non-branch tag, see 3O.9. To rename a magic branch tag, 5461 see 4D.5 5462 5463 Last modified: _6/13/1997_ 5464 5465 Category: /Commands_/status_st_stat/ 5466 5467 " + "status", "st", "stat"" 5468 5469 1. What is "status" for? 5470 5471 To display the status of files, including the revision and branch you 5472 are working on and the existence of "sticky" information. 5473 5474 Last modified: _6/13/1997_ 5475 5476 2. Why does "status" limit the File: at the top to 17 characters? 5477 5478 Designed that way to line up with other data. You can find the whole 5479 filename in the line beginning with "RCS version:", which is not 5480 limited in length. 5481 5482 Last modified: _6/13/1997_ 5483 5484 3. Why does it print "Sticky" lines when the values are "(none)"? 5485 5486 Oversight. It should probably elide lines without information. 5487 5488 Last modified: _6/13/1997_ 5489 5490 4. Shouldn't the status "Needs Checkout" be "Needs Update"? 5491 5492 Probably. 5493 5494 [[Did this show up in CVS 1.4?]] 5495 5496 Last modified: _6/13/1997_ 5497 5498 Category: /Commands_/tag_ta_freeze/ 5499 5500 " + "tag", "ta", "freeze"" 5501 5502 1. What is "tag" for? 5503 5504 To add a symbolic label (a "tag") to the RCS files last checked out, 5505 updated or committed in a working directory. 5506 5507 Last modified: _6/13/1997_ 5508 5509 2. What is the difference between "tag" and "rtag"? 5510 5511 The end result of both commands is that a <tag>, or symbolic name, is 5512 attached to a single revision in each of a collection of files. 5513 5514 The differences lie in: 5515 5516 The collection of files they work on. 5517 5518 "rtag" works on the collection of files referred to by a "module" name 5519 as defined in the "modules" file, or a relative path within the 5520 Repository. 5521 5522 "tag" works on files and directories specified on the command line 5523 within the user's working directory. (Default is '.') 5524 5525 Both commands recursively follow directory hierarchies within the 5526 named files and directories. 5527 5528 The revisions they choose to tag. 5529 5530 "rtag" places a tag on the latest committed revision of each file on 5531 the branch specified by the '-r' option. By default it tags the Main 5532 Branch. 5533 5534 "tag" places a tag on the BASE (i.e. last checked out, updated or 5535 committed) revision of each file found in the working directory. (The 5536 BASE revision of a file is the one stored in the ./CVS/Entries file.) 5537 5538 A different set of command line options. 5539 5540 For example, "rtag" takes a "-r <oldtag>" option to retag an existing 5541 tag. The "tag" command does not. 5542 5543 How it is logged. 5544 5545 Currently "rtag" records the <tag> and the module in the "history" 5546 file, while "tag" does not. 5547 5548 Last modified: _6/13/1997_ 5549 5550 3. Why does "tag -b" not put a tag on the Branch Point revision? How do I 5551 refer to the Branch Point? 5552 5553 This is probably an oversight, or a disbelief in the need for it. If 5554 everything works perfectly, the "update -j" command will do the merge 5555 you need and you don't need to check up on it by playing with the 5556 branch point revision. 5557 5558 The '-b' option attaches a magic branch tag to allow CVS later to 5559 figure out the branch point. The actual revision that <tag> is 5560 attached to does not exist. References to the branch tag are 5561 equivalent to references to the latest revision on the branch. 5562 5563 There is no way to refer to the branch point without adding a 5564 non-branch tag. You might want to add non-branch tags as a habit and 5565 add branch tags later, possibly immediate after adding the non-branch 5566 tag. See 4C.3 on Creating a Branch. 5567 5568 Last modified: _6/13/1997_ 5569 5570 4. So "{r}tag" labels a bunch of files. What do you use a Tag for? 5571 5572 You use it to "checkout" the labeled collection of files as a single 5573 object, referring to it by name. 5574 5575 Anywhere a revision number can be used a Tag can be used. In fact tags 5576 are more useful because they draw a line through a collection of 5577 files, marking a development milestone. 5578 5579 The way to think about a Tag is as a curve drawn through a matrix of 5580 filename vs. revision number. Consider this: 5581 5582 Say we have 5 files (in some arbitrary modules, some may be in 2 or 5583 more modules by name, some may be in 2 or more modules because of the 5584 Repository tree structure) with the following revisions: 5585 5586 file1 file2 file3 file4 file5 5587 5588 1.1 1.1 1.1 1.1 /--1.1* <-*- <tag> 5589 1.2*- 1.2 1.2 -1.2*- 5590 1.3 \- 1.3*- 1.3 / 1.3 5591 1.4 \ 1.4 / 1.4 5592 \-1.5*- 1.5 5593 1.6 5594 5595 At some time in the past, the '*' versions were tagged. Think of the 5596 <tag> as a handle attached to the curve drawn through the tagged 5597 revisions. When you pull on the handle, you get all the tagged 5598 revisions. Another way to look at it is that you draw a straight line 5599 through the set of revisions you care about and shuffle the other 5600 revisions accordingly. Like this: 5601 5602 file1 file2 file3 file4 file5 5603 5604 1.1 5605 1.2 5606 1.1 1.3 _ 5607 1.1 1.2 1.4 1.1 / 5608 1.2*----1.3*----1.5*----1.2*----1.1 (--- <-- Look here 5609 1.3 1.6 1.3 \_ 5610 1.4 1.4 5611 1.5 5612 5613 I find that using these visual aids, it is much easier to understand 5614 what a <tag> is and what it is useful for. 5615 5616 Last modified: _6/13/1997_ 5617 5618 5. How do I get "tag" and "rtag" to send mail the way "commit" does? 5619 5620 The "commit" command is supported by two files ("commitinfo" and 5621 "loginfo") not used by other commands. To do logging the same way for 5622 "tag" and "rtag" would require another file like loginfo, which 5623 currently doesn't exist. 5624 5625 The "rtag" command requires a "module" entry, which can specify a 5626 "tag" program using the "-t programname" option on the module line. 5627 5628 There is no equivalent support for "tag". 5629 5630 Last modified: _6/13/1997_ 5631 5632 6. Why can't "tag" handle the '-r' option that "rtag" takes? 5633 5634 Oversight. The answer is probably "Fixed in a Future Release." 5635 5636 Last modified: _6/13/1997_ 5637 5638 7. After a "tag <tag>" in my working directory, why doesn't "checkout -r 5639 <tag>" somewhere else produce copies of my current files? 5640 5641 The only reason this would fail, other than misspelling the <tag> 5642 string, is that you didn't "commit" your work before "tagging" it. 5643 Only committed revisions may be tagged. Modified files are not marked 5644 for later tagging. 5645 5646 Last modified: _6/13/1997_ 5647 5648 8. Why doesn't "tag" write a history record the way "rtag" does? 5649 5650 The "rtag" command was originally intended to place major "release" 5651 tags onto modules. The "tag" functionality was developed to *move* the 5652 more significant tag when slight changes to individual files sneaked 5653 in after the release tag was stamped onto the Repository. 5654 5655 The significant event was the "rtag", which was recorded in the 5656 "history" file for the "history -T" option to work. 5657 5658 It turns out that "tag" is generally more useful than "rtag", so the 5659 model has changed. Future revisions of CVS will probably store both 5660 kinds of tags in the history file. 5661 5662 Last modified: _6/13/1997_ 5663 5664 9. How do I rename a <tag>? 5665 5666 For a procedure to rename a branch tag, See section 4D.5 The following 5667 covers only non-branch tags. 5668 5669 First, pick a <newtag> that is not in use. You could reuse (i.e. move) 5670 an existing tag to the new revisions using the '-F' option, but that 5671 will confuse matters when both tags are not already on a file. (It 5672 will probably confuse "rtag -f" too.) 5673 5674 Use "rtag" to place <newtag> only on revisions attached to <oldtag> in 5675 the whole Repository, then delete the old one. 5676 5677 cvs rtag -r <oldtag> <newtag> world 5678 cvs rtag -d <oldtag> world. 5679 5680 You can also checkout or update your working directory to the <oldtag> 5681 and "tag" rather than "rtag" the result. But that will take longer and 5682 it has the chance of producing conflicts. 5683 5684 cvs update -r <oldtag> 5685 cvs tag <newtag> 5686 cvs tag -d <oldtag> 5687 cvs update -A (or cvs update -r <previous_tag>) 5688 5689 Last modified: _6/13/1997_ 5690 5691 Category: /Commands_/update_up_upd/ 5692 5693 " + "update", "up", "upd"" 5694 5695 1. What is "update" for? 5696 5697 The "update" command is by far the most important command and is 5698 probably also the most used command. 5699 5700 It has five purposes: (And many options.) 5701 5702 To display the status of your working files. 5703 5704 Though a plain "update" also displays the status, it does so after 5705 possibly altering your working directory. To see the status of your 5706 working files without changing anything, type: 5707 5708 cvs -n update {optional list of files} 5709 5710 To merge changes made by others to the branch you are working on 5711 into your working files. 5712 5713 Each working directory is attached to a branch, usually the Main 5714 branch. To merge changes made on your working branch since your last 5715 checkout, update or commit, type: 5716 5717 cvs update {optional list of files} 5718 5719 To merge changes made on another branch into the branch you are 5720 working on (your "working branch"). 5721 5722 If you want to grab a whole branch, from the branch point, which is 5723 assumed to be on the Main Branch, to the end of the branch, you type: 5724 5725 cvs update -j <branch_tag> {optional files} 5726 5727 If you want to grab the changes made between two tags or revisions, 5728 you type: 5729 5730 cvs update -j <tag1> -j <tag2> {optional files} 5731 5732 (If you are working with a single file, the Tags could also be 5733 revisions numbers. Unless you take great care to match revision 5734 numbers across different files (a waste of time given the way Tags 5735 work), using revision numbers in place of the Tags for multiple files 5736 would be meaningless.) 5737 5738 To move your working directory to another branch. 5739 5740 A working directory is presumed to be attached to (or working on) a 5741 particular branch, usually the Main branch. To alter what CVS believes 5742 to be your working branch, you "move" to that branch. 5743 5744 To move to a tagged branch, type: 5745 5746 cvs update -r <branch_tag> {optional files} 5747 5748 To move to the Main Branch, type: 5749 5750 cvs update -A {optional files} 5751 5752 If you have modified files in your working directory, this is not a 5753 clean move. CVS will attempt to merge the changes necessary to make it 5754 look like you made the same changes to the new branch as you made in 5755 the old one. But if you do this twice without resolving the merge 5756 conflicts each time, you can lose work. 5757 5758 To retrieve old revisions of files. 5759 5760 This option is similar to 4 above but you are not restricted to using 5761 a <branch_tag>. You may specify any revision or <tag> with '-r' and 5762 get the specified revision or the tagged revision: 5763 5764 cvs update -r <tag/rev> {optional files} 5765 5766 Or you may specify any date with '-D': 5767 5768 cvs update -D <date> {optional files} 5769 5770 The '-p' option sends the revisions to standard output (normally your 5771 terminal) rather than setting the "sticky" tag and changing the files. 5772 5773 Last modified: _6/13/1997_ 5774 5775 2. What do 'U', 'M' and 'C' mean when I type "update"? Are they different 5776 for "cvs -n update"? 5777 5778 "cvs update" merges changes made to the Repository, since your last 5779 "checkout", "update" or "commit", into your working files. You can 5780 think of it as changing your BASE revision. 5781 5782 "cvs update" prints lines beginning with: 5783 5784 'U' after replacing your unmodified file with a different 5785 revision from the Repository. 5786 5787 'M' for two different reasons: 5788 5789 for files you have modified that have not changed in the Repository. 5790 5791 after a merge, if it detected no conflicts. 5792 5793 'C' after a merge, if it detected conflicts. See 2D.7 and 3P.6 for 5794 more info on conflict resolution and "sticky conflicts." 5795 5796 "cvs -n update" shows what it *would* do, rather than doing it. Or, 5797 another way of looking at it, "cvs -n update" displays the 5798 relationship between your current BASE revisions (identified in your 5799 ./CVS/Entries file) and the HEAD revisions (the latest revisions in 5800 the Repository). 5801 5802 "cvs -n update" prints lines beginning with: 5803 5804 'U' for files you have not modified that have changed in the 5805 Repository. 5806 5807 'M' for files you have modified that have not changed in the 5808 Repository. 5809 5810 'C' for files you have modified that have also been changed in the 5811 Repository. 5812 5813 See 4C.6 for what the letters mean when merging in from another 5814 branch. The output is almost the same for a normal update if you 5815 consider the Repository as the branch and your working directory as 5816 the "trunk". 5817 5818 Last modified: _6/13/1997_ 5819 5820 3. What's the difference between "update" and "checkout"? 5821 5822 See 3C.4 above. 5823 5824 Last modified: _6/13/1997_ 5825 5826 4. Why don't I get new files when I execute "update"? 5827 5828 There are six reasons for nothing to happen during an "update": 5829 5830 Nothing on your branch changed in the Repository. 5831 5832 If no one has committed anything to the branch you are working on 5833 (normally the Main branch) since the last time you executed 5834 "checkout", "update" or "commit", nothing will happen. 5835 5836 It's like shouting "xyzzy" or "plugh" in the wrong room. 5837 5838 You have a "sticky" non-branch <tag> or <date> attached to the 5839 working files you are trying to "update". 5840 5841 At some time in the past you checked out or updated your directory 5842 with the "-r <tag>" or "-D <date>" option. Until you do it again with 5843 a different tag or date, or go back to the Main Branch with "update 5844 -A", you will never again see any updates. 5845 5846 The ./CVS/Entries.Static file exists and you are expecting a new 5847 file. 5848 5849 If your ./CVS administrative directory contains a file named 5850 Entries.Static, no files will be checked out that aren't already in 5851 the Entries or Entries.Static file. 5852 5853 You forgot to use the '-d' option and are looking for new 5854 directories. 5855 5856 If you execute "update" without the '-d' option, it will not create 5857 new directories that have been added to the Repository. 5858 5859 You typed "update" instead of "cvs update". 5860 5861 On most Unix systems, your disk caches are now furiously being flushed 5862 by multiple update daemons, destroying performance and proving to 5863 management that you need more CPU power. :-) 5864 5865 On HP systems you might be asked what package you want to install from 5866 the "update server". 5867 5868 Someone removed (using "admin -o") your BASE revision (the revision 5869 CVS thought you had in your working directory), then committed a 5870 "replacement". CVS is now confused because the revision in the 5871 Repository matches your BASE revision when the files themselves don't 5872 match. See 3B.6. 5873 5874 Last modified: _6/13/1997_ 5875 5876 5. Why does "update" say 'M' both for plain modified files and for 5877 successful (i.e. conflict-free) merges? Aren't they different? 5878 5879 A design choice. Yes, they are different internally, but that 5880 shouldn't matter. Your files are in the same condition after the 5881 "update" as they were before -- a "diff" will display only your 5882 modifications. And you are expected to continue onward with parts two 5883 and three of the normal development cycle: "emacs" (a synonym for 5884 "edit" in most of the civilized world) and "commit". 5885 5886 Last modified: _6/13/1997_ 5887 5888 6. What's a "sticky conflict"? How does it know a conflict occurred? 5889 5890 When a "cvs update" (or an "update -j") creates a conflict, it prints 5891 a 'C' and stores the timestamp of the file after the merge in a 5892 special field in the ./CVS/Entries file. 5893 5894 This conflict indication implies that the merge command altered your 5895 working file to contain conflict markers surrounding the overlapping 5896 code segments. For example, say that 5897 5898 - Two developers acquire revision 1.2 of <file> via "checkout" or 5899 "update". 5900 5901 - Developer A changes line 1 from "9999" to "5555", then commits the 5902 file, creating revision 1.3. 5903 5904 - Developer B changes line 1 from "9999" to "7777", then tries to 5905 commit the file, but is blocked because the file is not up to date. 5906 Developer B then runs "update" and sees the conflict marker 'C'. The 5907 beginning of the file would look like this: 5908 5909 <<<<<<< <file> The working <file> in question. 5910 7777 Change made to the working <file>. 5911 ======= 5912 5555 Change made in the first commit (1.3) 5913 >>>>>>> 1.3 The revision created by the first commit. 5914 5915 The conflict is "sticky", which means that until the conflict is 5916 cleared, the "update" command will continue to display the file's 5917 status as 'C' and the "status" command will show the file's status as 5918 "Unresolved Conflict". 5919 5920 Until the conflict is cleared, "commit" is blocked for this file. 5921 5922 The sticky conflict indicator can be cleared by: 5923 5924 Resolving the conflict by editing the file. Two things must happen 5925 before the conflict is considered resolved: 5926 5927 The timestamp of the file must change. *and* The file must contain no 5928 conflict markers. (The string searched for in the file is the regexp: 5929 "^>>>>>>> ".) 5930 5931 After clearing the sticky conflict indicator, you may then commit the 5932 file normally. 5933 5934 Removing the file and running "update". This throws away the local 5935 changes and accepts the latest committed file on this branch. No 5936 commit is needed. 5937 5938 Forcing the commit to happen by using "commit -f". This is probably 5939 a mistake since there are few lines of real text that begin with 5940 ">>>>>>> ". 5941 5942 Last modified: _6/13/1997_ 5943 5944 7. Is there a feature to tell me what I have changed, added and removed 5945 without changing anything? 5946 5947 The command "cvs -n update" will do exactly that. 5948 5949 Last modified: _6/13/1997_ 5950 5951 8. Why were all my files deleted when I executed "update"? 5952 5953 You probably executed "update -r <tag>" some time ago, then removed 5954 <tag> from the Repository files. "update -r <tag>" will delete a file 5955 that doesn't contain <tag>. 5956 5957 A way to fix this is to "cd" into your working directory and type: 5958 5959 cvs update -A 5960 5961 If you don't want the latest revisions on the Main (or Vendor) Branch, 5962 then decide what Tag (normal or branch) you want and type: 5963 5964 cvs update -r <the_tag_you_want> 5965 5966 Another way to make a file disappear is to execute "update -D <date>" 5967 where <date> is before the date stamped onto the first revision in the 5968 RCS file. 5969 5970 Last modified: _6/13/1997_ 5971 5972 Category: /Past__Future_/ 5973 5974 " Past & Future " 5975 5976 Category: /Past__Future_/Bugs_and_Patches/ 5977 5978 " + Bugs and Patches" 5979 5980 1. Why can't CVS handle deletion of directories? 5981 5982 An oversight, probably. [[Fixed in a future release?]] 5983 5984 Last modified: _6/13/1997_ 5985 5986 2. Why can't CVS handle the moving of sources from one place in the 5987 5988 directory hierarchy to another? 5989 5990 A "renaming database" has been proposed to track the history of 5991 pathname changes in the Repository. A general solution is a difficult 5992 problem. See 4B.8. 5993 5994 Last modified: _6/13/1997_ 5995 5996 3. When I typed "cvs update -D <date>", why did it check out all 5997 5998 sorts of ancient files from the Attic? Shouldn't it just create the 5999 set of files and revisions that existed at that date? 6000 6001 This seems to be a bug, but is really the lack of any obvious place to 6002 store the date when a file is "removed". 6003 6004 There are four ranges of dates that CVS has to deal with when trying 6005 to determine what revision was available on <date>: 6006 6007 Dates before the earliest revision in the file. 6008 6009 Dates between any two revisions in the file. 6010 6011 Dates between the latest revision in the file and the date when the 6012 file was moved to the Attic by "commit". 6013 6014 Dates after moving the file to the Attic. 6015 6016 Since the date when a file is moved to the Attic is not stored 6017 anywhere, CVS can't tell the difference between #3 and #4. To avoid 6018 not producing a file that should exist in case #3, it produces 6019 extraneous files in case #4. 6020 6021 For the above reason, if you have removed files in the Attic, it is 6022 better to use "-r <tag>, or even "-r HEAD" than to use a date spec. 6023 6024 If you must use "-D <date>", then you should either archive and delete 6025 Attic files (losing some past history) or construct your Makefiles to 6026 work with an explicit list of files and let the old source files stay 6027 in the working directory. The contents of the revision-controlled 6028 Makefile can then be considered to contain deletion "information". 6029 6030 Last modified: _6/13/1997_ 6031 6032 4. When I typed "cvs update -D <date>" in my branch, why did it screw up 6033 all my files? 6034 6035 Currently, the internal routine ("version_ts") that looks up info 6036 about a file, overrides both the tag and date if *either* the tag or 6037 date is specified on the command line. If only the date is specified, 6038 it should not override a branch tag, but it does. 6039 6040 In CVS 1.3, the documented "-D <branch_tag>:<date>" syntax only works 6041 with the Main Branch and the Vendor Branch. 6042 6043 [[Is this fixed in CVS 1.4? This is one item I didn't check.]] 6044 6045 Last modified: _6/13/1997_ 6046 6047 5. When I executed "checkout" into an existing directory I got "No such 6048 file or directory" errors. Why? 6049 6050 Though the man page says that "checkout" turns into an "update -d" in 6051 directories that already exist, it is referring to directories that 6052 already exist *and* were created by CVS. 6053 6054 When you try to run "checkout" on top of an existing directory 6055 structure, some of which wasn't created by CVS, it will handle 6056 directories and non-CVS files within directories already under CVS, 6057 but it will display the above error on non-CVS files within non-CVS 6058 directories. 6059 6060 Last modified: _6/13/1997_ 6061 6062 6. Why does "update" send all output to the terminal after 26 files have 6063 been updated? 6064 6065 CVS uses the "tmpnam()" function to generate temporary file names. The 6066 ANSI standard for the "tmpnam()" function says: 6067 6068 "The tmpnam function generates a different string each time it is 6069 called, up to TMP_MAX times. If it is called more than TMP_MAX times, 6070 the behavior is implementation defined." 6071 6072 Later it says that the value of "TMP_MAX shall be at least 25." 6073 6074 On some platforms, the above specification is taken literally by 6075 turning "at least 25" into "exactly 26" and by doing something foolish 6076 (i.e. "implementation defined") after that. Some systems return the 6077 same name repeatedly, which causes one form of trouble. Others return 6078 NULL or garbage, which causes a different form of trouble. 6079 6080 The broken systems appear to be cycling a single character through the 6081 alphabet. SunOS cycles 3 characters through the alphabet, so it won't 6082 cause trouble until 26 cubed or 17576 calls to "tmpnam()". 6083 6084 Since CVS doesn't depend on the exact format of the tmp files, the 6085 workaround is to provide a "tmpnam()" that doesn't have a limit on the 6086 number of calls to it. 6087 6088 Last modified: _6/13/1997_ 6089 6090 7. Why does the merge occasionally resurrect lines of code? 6091 6092 The diff3 program provided by GNU diff version 1.15 has a bug that 6093 occasionally causes text to come back from the dead. 6094 6095 This is an old problem which you can avoid by upgrading to the latest 6096 GNU "diffutils" package. If you were using GNU diff version 1.15 and 6097 plan to upgrade to the latest GNU diff program, see the next question. 6098 6099 Last modified: _6/13/1997_ 6100 6101 8. Why does the merge fail when my "rcsmerge" program is configured to use 6102 GNU diff version 2.1 or later? 6103 6104 A change in the overlap format was introduced in GNU diff3 between 6105 versions 2.0 and 2.1 that causes RCS versions before 5.6.0.1 to fail 6106 during a merge. 6107 6108 To get consistent rcsmerge behavior, you have four choices: 6109 6110 Go back to using GNU diff 1.15 or 2.0 with RCS versions 5.5 or 5.6. 6111 If you want to use GNU diff 2.1 or later, you'll have to pick one of 6112 the other three choices in this list. 6113 6114 Grab RCS version 5.6.0.1 from an FSF archive and set the DIFF3_A 6115 macro to '1' as it tells you to in the Makefile: 6116 6117 #define DIFF3_A 1 6118 6119 Patch the RCS 5.6 source. Change line 84 in "merger.c" from: 6120 6121 DIFF3, "-am", "-L", label[0], "-L", label[1], to DIFF3, "-amE", "-L", 6122 label[0], "-L", "", "-L", label[1], 6123 6124 Wait both for RCS version 5.7 to be released and for a new version 6125 of CVS that can deal with it. 6126 6127 Last modified: _6/13/1997_ 6128 6129 Category: /Past__Future_/Contributors/ 6130 6131 " + Contributors" 6132 6133 1. Who wrote CVS? 6134 6135 Brian Berliner <berliner@sun.com> converted a collection of scripts 6136 written by Dick Grune <dick@cs.vu.nl> into a C program, then added all 6137 sorts of features. He continues to maintain CVS. 6138 6139 Jeff Polk <polk@bsdi.com> wrote much of the code added between 6140 revisions 1.2 and 1.3. Many others were involved at some level. 6141 6142 david d zuhn <zoo@armadillo.com> fixed a number of bugs, added some of 6143 the new features, reworked the whole thing to be more portable, and 6144 provided much of the energy to push CVS 1.4 out the door. 6145 6146 Jim Kingdon implemented CVS 1.5's remote repository access features, 6147 fixed many bugs, and managed the release of version 1.5. 6148 6149 Take a look at the README and the ChangeLog files in the CVS sources 6150 for more contributors. 6151 6152 Last modified: _6/13/1997_ 6153 6154 2. You didn't write all of this FAQ, did you? 6155 6156 In the original hunt for questions to answer (performed in Jan/Feb, 6157 1993), I polled hundreds of people and I rephrased all sorts of text 6158 found on the net. Between 2/93 and 10/93, I released about 20 6159 versions, with corrections and additions from the info-cvs mailing 6160 list and private correspondence. 6161 6162 Between 10/93 and 10/94 I extracted frequently asked questions from 6163 the 1200 mail messages to the info-cvs mailing list, turned them into 6164 focused questions and tried to answer them. 6165 6166 93/02/?? ~4000 lines 93/06/?? ~5000 lines 93/10/23 7839 lines 278K 6167 94/10/29 9856 lines 360K 95/05/09 9981 lines 365K 6168 6169 Because there are so many posers of questions, I will list only those 6170 who contribute answers or help significantly with the content and 6171 structure of this document. 6172 6173 If I used someone else's text verbatim, I mentioned it in the given 6174 answer. The people whose email postings have added to this document or 6175 who have added to my understanding are: 6176 6177 Brian Berliner <berliner@sun.com>, CVS maintainer. Paul Eggert 6178 <eggert@twinsun.com>, RCS maintainer. 6179 6180 Gray Watson <gray@antaire.com> Per Cederqvist <ceder@signum.se> Pete 6181 Clark <pclark@is.com> 6182 6183 all of whom have sent me copies of their tutorials and local CVS 6184 documentation. 6185 6186 Additional contributors, who have sent me ideas, text, corrections and 6187 support include (in alphabetical order): 6188 6189 Per Abrahamsen <amanda@iesd.auc.dk> Donald Amby 6190 <amby@mixcom.mixcom.com> Mark D Baushke <mdb@cisco.com> Jim Blandy 6191 <jimb@cyclic.com> Tom Cunningham <tomc@bouwsma,sps.mot.com> Graydon 6192 Dodson <grdodson@lexmark.com> Joe Drumgoole 6193 <joed@splatter.demon.co.uk> Don Dwiggins <dwig@markv.com> Bryant 6194 Eastham <bryant@ced.utah.edu> Dan Franklin <dan@diamond.bbn.com> 6195 Michael Ganzberger <ganzbergermd@ES.net> Steve Harris 6196 <vsh%etnibsd@uunet.uu.net> Erik van Linstee 6197 <linstee@dutecaj.et.tudelft.nl> Jeffrey M Loomis <jml@world.std.com> 6198 Barry Margolin <barmar@near.net> Mark K. Mellis <mkm@ncd.com> Chris 6199 Moore <Chris.Moore@src.bae.co.uk> Gary Oberbrunner <garyo@avs.com> 6200 Steve Turner <stevet@carrier.sps.mot.com> Dave Wolfe 6201 <dwolfe@pffft.sps.mot.com> Dale Woolridge <dwoolridge@cid.aes.doe.ca> 6202 6203 Please send corrections. If I forgot you, remind me and I'll add your 6204 name to the list. 6205 6206 Last modified: _6/13/1997_ 6207 6208 Category: /Past__Future_/Development/ 6209 6210 " + Development" 6211 6212 1. Where do I send bug reports? 6213 6214 First make sure it is a bug. Talk to your friends, coworkers and 6215 anyone you know who uses CVS. Search this FAQ for related issues. Then 6216 test it carefully. Try out variations to narrow down the problem. Make 6217 sure it is repeatable. Look for workarounds so you can report them. 6218 6219 If you are still sure it's a bug and you tried to fix it, skip to the 6220 next question. Otherwise, send a message to the info-cvs mailing list 6221 containing one of the following: 6222 6223 If you have a good repeatable case and you think you know what is 6224 going on, then describe the problem in detail. Include a workaround if 6225 you have one. 6226 6227 If you have no idea what is going on, go ahead and send a question 6228 to the info-cvs mailing list. Include any information you have 6229 describing the symptoms. 6230 6231 Last modified: _6/13/1997_ 6232 6233 2. Where do I send fixes and patches? 6234 6235 First make sure the "fix" does something useful. Have someone review 6236 your fix. Spend a bit of one person's time in a detailed analysis of 6237 your vast idea before displaying a half-vast idea to hundreds of 6238 people. 6239 6240 If you tried to fix it and the patch is small, include the patch in 6241 your message. Make sure the patch is based on the latest released 6242 version of CVS. 6243 6244 If you tried to fix it and the patch is large, you should think about 6245 why it is so large. Did you add a generally useful feature, or did it 6246 grow out of hand? 6247 6248 If you still believe it is solid, produce a patch file using the CVS 6249 commands "patch" or "diff -c". [[You *are* keeping CVS under CVS, 6250 right?]] The patch should be based on the latest released version of 6251 CVS. Then use the "cvsbug" program (provided with the CVS sources) to 6252 send it to the CVS maintainers. A self-contained patch that provides a 6253 single useful feature or correction might show up independently in the 6254 patches directory of the FTP archive. 6255 6256 If careful testing reveals an RCS bug rather than a CVS bug, you can 6257 send bug reports to: rcs-bugs@cs.purdue.edu 6258 6259 Last modified: _6/13/1997_ 6260 6261 3. Where do I send ideas for future development? 6262 6263 If you have a bright idea, discuss it on the info-cvs mailing list. If 6264 you have the time to implement something you can test, send the diffs 6265 along too as described above. 6266 6267 Last modified: _6/13/1997_ 6268 6269 4. What plans are there for new features? 6270 6271 6272 6273A "rename" or "per-directory" database has been bandied about on 6274the net for years. Many of the goals of the rename database have 6275been achieved by the so-called "death support" in recent versions of 6276CVS (such as 1.9). For more information on what may remain to be 6277done, see item #189 in the TODO file of a development version of CVS. 6278 6279CVS version 1.5 supports remote repository access, but Paul 6280Kunz has produced another version 6281(rCVS) that also runs remotely. Note that as far as I know there 6282are no advantages to rCVS over the remote CVS in CVS 1.5 and later, 6283and the rCVS user community has migrated to remote CVS. 6284rCVS is *not* a multisite CVS (see item #186 in TODO for more on 6285multisite). For more on rCVS, see 6286 6287ftp://ftp.slac.stanford.edu/software/rcvs 6288 6289kingdon@cyclic.com 6290 6291 Last modified: _9/6/1997_ 6292 6293 5. I have some time and I'd like to help. What can I do for you? 6294 6295 6296 You can review this document, correct errors and fill in any of 6297 the incomplete sections. 6298 6299 You can write scripts or CVS add-ons and make them available by 6300 web/FTP/etc. 6301 6302 You could work on the regression test suite (src/sanity.sh in the 6303 CVS source distribution). 6304 6305 You can write specs for new features, fix bugs, review the 6306 documentation or . . . 6307 6308 For more information, see the files HACKING and DEVEL-CVS in the 6309 CVS source distribution or 6310 http://www.cyclic.com/cyclic-pages/cvsdev.html 6311 6312 kingdon@cyclic.com 6313 6314 Last modified: _9/6/1997_ 6315 6316 Category: /Past__Future_/Professional_Support/ 6317 6318 " + Professional Support" 6319 6320 1. Doesn't Cygnus support CVS? 6321 6322 6323 6324 6325 Cygnus is a company that supports free software such as the GCC 6326 compiler. They have never sold support for CVS, however. They 6327 do use CVS internally and have contributed much code to CVS over 6328 the years (for which CVS users should be grateful). 6329 6330 kingdon@cyclic.com 6331 6332 Last modified: _9/6/1997_ 6333 6334 2. What is Cyclic Software doing with CVS? 6335 6336 6337Cyclic Software exists to provide support for CVS. For details such 6338as prices and what this covers, see http://www.cyclic.com or ask 6339info@cyclic.com. 6340 6341kingdon@cyclic.com 6342 6343 Last modified: _9/6/1997_ 6344 6345 Category: /User_Tasks_/ 6346 6347 " User Tasks " 6348 6349 Category: /User_Tasks_/Common_User_Tasks/ 6350 6351 " + Common User Tasks" 6352 6353 1. What is the absolute minimum I have to do to edit a file? 6354 6355 Tell your Repository Administrator to create a module covering the 6356 directory or files you care about. You will be told that your module 6357 name is <module>. Then type: 6358 6359 cvs checkout <module> 6360 cd <module> 6361 emacs <file> # Isn't Emacs a synonym for edit? 6362 cvs commit <file> 6363 6364 If you don't use modules (in my opinion, a mistake), you can check out 6365 a directory by substituting its relative path within the Repository 6366 for <module> in the example above. 6367 6368 To work on a single file, you'll have to change "cd <module>" to "cd 6369 `dirname <module>`". 6370 6371 Last modified: _6/13/1997_ 6372 6373 2. If I edit multiple files, must I type "commit" for each one? 6374 6375 No. You can commit a list of files and directories, including relative 6376 paths into multiple directories. You can also commit every modified 6377 file in the current directory or in all directories and subdirectories 6378 from your current directory downward. See 3D.2. 6379 6380 Last modified: _6/13/1997_ 6381 6382 3. How do I get rid of the <module> directory that "checkout" created? 6383 6384 Change your directory to be the same as when you executed the 6385 "checkout" command that created <module>. 6386 6387 If you want to get rid of the CVS control information, but leave the 6388 files and directories, type: 6389 6390 cvs release <module> 6391 6392 If you want to obliterate the entire directory, type: 6393 6394 cvs release -d <module> 6395 6396 ("release -d" searches through the output of "cvs -n update" and 6397 refuses to continue if the "update" command finds any modified files 6398 or non-ignored foreign files. Foreign directories too.) 6399 6400 If you don't care about keeping "history", or checking for modified 6401 and foreign files, you can just remove the whole directory. That's "rm 6402 -rf <module>" under Unix. 6403 6404 Last modified: _6/13/1997_ 6405 6406 4. How do I find out what has changed since my last update? 6407 6408 There are many ways to answer this. 6409 6410 To find out what you've changed in your current working directory 6411 since your last checkout, update or commit, type: 6412 6413 cvs diff 6414 6415 To find out what other people have added (to your branch) since you 6416 last checked out or updated, type: 6417 6418 cvs diff -r BASE -r HEAD 6419 6420 To look at a revision history containing the comments for all changes, 6421 you can use the "log" command. 6422 6423 You can also use "history" to trace a wide variety of events. 6424 6425 Last modified: _6/13/1997_ 6426 6427 5. I just created a new file. How do I add it to the Repository? 6428 6429 The "update" command will mark files CVS doesn't know about in your 6430 working directory with a '?' indicator. 6431 6432 ? <file> 6433 6434 To add <file> to the Repository, type: 6435 6436 cvs add <file> 6437 cvs commit <file> 6438 6439 See 3A.[2-5] and 4C.8 for branch and merge considerations. 6440 6441 Last modified: _6/13/1997_ 6442 6443 6. How do I merge changes made by others into my working directory? 6444 6445 If you are asking about other branches, see Section 4C on "Branching". 6446 You will have to use the "update -j" command. 6447 6448 Retrieving changes made to the Repository on the *same* branch you are 6449 working on is the main purpose of the "update" command. The "update" 6450 command tries to merge work committed to the Repository by others 6451 since you last executed "checkout", "update" or "commit" into your 6452 working files. 6453 6454 For a single file, there are six possible results when you type the 6455 "update" command: 6456 6457 If the file is lying in your working directory, but is not under 6458 CVS, it will do nothing but print: 6459 6460 ? <file> 6461 6462 If neither you nor anyone else has committed changes to <file>, 6463 since your last "checkout", "update" or "commit", "update" will print 6464 nothing and do nothing. 6465 6466 If you have made no changes to a working file, but you or others 6467 have committed changes to the Repository since your last "checkout", 6468 "update" or "commit" of this working file, CVS will remove your 6469 working file and replace it with a copy of the latest revision of that 6470 file in the Repository. It will print: 6471 6472 U <file> 6473 6474 You might want to examine the changes (using the CVS "diff" command) 6475 to see if they mesh with your own in related files. 6476 6477 If you have made changes to a working file, but no one has changed 6478 your BASE revision (the revision you retrieved from the Repository in 6479 your last "checkout", "update" or "commit"), "update" will print: 6480 6481 M <file> 6482 6483 Nothing changes. You were told that you have a modified file in your 6484 directory. 6485 6486 If you have made changes to your working file and you or others have 6487 committed changes to the Repository, but in different sections of the 6488 file, CVS will merge the changes stored in the Repository since your 6489 last "checkout", "update" or "commit" into your working file. "update" 6490 will print: 6491 6492 RCS file: /Repository/module/<file> retrieving revision 1.X retrieving 6493 revision 1.Y Merging differences between 1.X and 1.Y into <file> M 6494 <file> 6495 6496 If you execute "diff" before and after this step, you should see the 6497 same output, since both the base file and your working file changed in 6498 parallel. This is one of the few times the otherwise nonsensical 6499 phrase "same difference" means something. 6500 6501 If both you and those who committed files (since your last checkout, 6502 update or commit) have made changes to the same section of a file, CVS 6503 will merge the changes into your file as in #5 above, but it will 6504 leave conflict indicators in the file. "update" will print: 6505 6506 RCS file: /Repository/module/<file> retrieving revision 1.X retrieving 6507 revision 1.Y Merging differences between 1.X and 1.Y into <file> 6508 rcsmerge warning: overlaps during merge 6509 cvs update: conflicts found in <file> 6510 C <file> 6511 6512 This is a "conflict". The file will contain markers surrounding the 6513 overlapping text. The 'C' conflict indicator is sticky -- subsequent 6514 "update" commands will continue to show a 'C' until you edit the file. 6515 6516 You must examine the overlaps with care and resolve the problem by 6517 analyzing how to retain the features of both changes. See 2D.7 and 6518 3P.6 for more details on conflict resolution. 6519 6520 Last modified: _6/13/1997_ 6521 6522 7. How do I label a set of revisions so I can retrieve them later? 6523 6524 To "tag" the BASE revisions (the ones you last checked out, updated, 6525 or committed) you should "cd" to the head of the working directory you 6526 want to tag and type: 6527 6528 cvs tag <tag> 6529 6530 It recursively walks through your working directory tagging the BASE 6531 revisions of all files. 6532 6533 To "tag" the latest revision on the Main branch in the Repository, you 6534 can use the following from anywhere: (No "cd" is required -- it works 6535 directly on the Repository.) 6536 6537 cvs rtag <tag> <module> 6538 6539 Last modified: _6/13/1997_ 6540 6541 8. How do I checkout an old release of a module, directory or file? 6542 6543 Module names and directories are simply ways to name sets of files. 6544 Once the names are determined, there are 6 ways to specify which 6545 revision of a particular file to check out: 6546 6547 By tag or symbolic name, via the "-r <tag>" option. 6548 6549 By date, via the "-D <date>" option. 6550 6551 By branch tag (a type of tag with a magic format), via the "-r 6552 <branch_tag>" option. 6553 6554 By date within a branch, via the "-r <branch_tag>:<date>" option. 6555 6556 By an explicit branch revision number ("-r <rev>"), which refers to 6557 the latest revision on the branch. This isn't really an "old" 6558 revision, from the branch's perspective, but from the user's 6559 perspective the whole branch might have been abandoned in the past. 6560 6561 An explicit revision number: "-r <rev>" Though this works, it is 6562 almost useless for more than one file. 6563 6564 You type: 6565 6566 cvs checkout <option-specified-above> <module> 6567 cd <module> 6568 6569 Last modified: _6/13/1997_ 6570 6571 9. What do I have to remember to do periodically? 6572 6573 You should execute "cvs -n update" fairly often to keep track of what 6574 you and others have changed. It won't change anything -- it will just 6575 give you a report. 6576 6577 Unless you are purposely delaying the inclusion of others' work, you 6578 should execute "update" once in a while and resolve the conflicts. It 6579 is not good to get too far out of sync with the rest of the developers 6580 working on your branch. 6581 6582 It is assumed that your system administrators have arranged for editor 6583 backup and Unix temp files (#* and .#*) to be deleted after a few 6584 weeks. But you might want to look around for anything else that is 6585 ignored or hidden. Try "cvs -n update -I !" to see all the ignored 6586 files. 6587 6588 If you are the Repository Administrator, see 4B.16 on Administrator 6589 responsibilities. 6590 6591 Last modified: _6/13/1997_ 6592 6593 Category: /User_Tasks_/General_Questions/ 6594 6595 " + General Questions" 6596 6597 1. How do I see what CVS is trying to do? 6598 6599 The '-t' option on the main "cvs" command will display every external 6600 command (mostly RCS commands and file deletions) it executes. When 6601 combined with the '-n' option, which prevents the execution of any 6602 command that might modify a file, you can see what it will do before 6603 you let it fly. The '-t' option will *not* display every internal 6604 action, only calls to external programs. 6605 6606 To see a harmless example, try typing: 6607 6608 cvs -nt update 6609 6610 Some systems offer a "trace" or "truss" command that will display all 6611 system calls as they happen. This is a *very* low-level interface that 6612 does not normally follow the execution of external commands, but it 6613 can be useful. 6614 6615 The most complete answer is to read the source, compile it with the 6616 '-g' option and step through it under a debugger. 6617 6618 Last modified: _6/13/1997_ 6619 6620 2. If I work with multiple modules, should I check them all out and commit 6621 them occasionally? Is it OK to leave modules checked out? 6622 6623 The simple answers are "Yes." 6624 6625 There is no reason to remove working directories, other than to save 6626 disk space. As long as you have committed the files you choose to make 6627 public, your working directory is just like any other directory. 6628 6629 CVS doesn't care whether you leave modules checked out or not. The 6630 advantage of leaving them checked out is that you can quickly visit 6631 them to make and commit changes. 6632 6633 Last modified: _6/13/1997_ 6634 6635 3. What is a "sticky" tag? What makes it sticky? How do I loosen it? 6636 6637 When you execute "update -r <tag>", CVS remembers the <tag>. It has 6638 become "sticky" in the sense that until you change it or remove it, 6639 the tag is remembered and used in references to the file as if you had 6640 typed "-r <tag>" on the command line. 6641 6642 It is most useful for a <branch_tag>, which is a sticky tag indicating 6643 what branch you are working on. 6644 6645 A revision number ("-r <rev-number>") or date ("-D <date>") can also 6646 become sticky when they are specified on the command line. 6647 6648 A sticky tag, revision or date remains until you specify another tag, 6649 revision or date the same way. The "update -A" command moves back to 6650 the Main branch, which has the side-effect of clearing all sticky 6651 items on the updated files. 6652 6653 The "checkout" command creates sticky tags, revisions and dates the 6654 same way "update" does. 6655 6656 Also, the '-k' option records a "sticky" keyword option that is used 6657 in further "updates until "update -A" is specified. 6658 6659 Last modified: _6/13/1997_ 6660 6661 4. How do I get an old revision without updating the "sticky tag"? 6662 6663 Use the '-p' option to "pipe" data to standard output. The command 6664 "update -p -r <tag/rev>" sends the selected revision to your standard 6665 output (usually the terminal, unless redirected). The '-p' affects no 6666 disk files, leaving a "sticky tag" unaltered and avoiding all other 6667 side-effects of a normal "update". 6668 6669 If you want to save the result, you can redirect "stdout" to a file 6670 using your shell's redirection capability. In most shells the 6671 following command works: 6672 6673 cvs update -p -r <tag/rev> filename > diskfile 6674 6675 Last modified: _6/13/1997_ 6676 6677 5. What operations disregard sticky tags? 6678 6679 The functions that routinely disregard sticky tags are: 6680 6681 Those that work directly on the Repository or its administrative 6682 files: 6683 6684 admin rtag log status remove history 6685 6686 Those that take Tags or revisions as arguments and ignore everything 6687 else: (They also never *set* a sticky tag.) 6688 6689 rdiff import export 6690 6691 The "release" command itself ignores sticky tags, but it calls "cvs 6692 -n update" (which *does* pay attention to a sticky tag) to figure out 6693 what inconsistencies exist in the working directory. If no 6694 discrepancies exist between the files you originally checked out 6695 (possibly marked by a sticky tag) and what is there now, "release -d" 6696 will delete them all. 6697 6698 The "tag" command works on the revision lying in the working 6699 directory however it got there. That the revision lying there might 6700 happen to have a sticky tag attached to it is not the "tag" command's 6701 concern. 6702 6703 The main function that *does* read and write sticky tags is the 6704 "update" command. You can avoid referring to or changing the sticky 6705 tag by using the '-p' option, which sends files to your terminal, 6706 touching nothing else. 6707 6708 The "checkout" command sets sticky tags when checking out a new module 6709 and it acts like "update" when checking out a module into an existing 6710 directory. 6711 6712 The "diff" and "commit" commands use the sticky tags, unless 6713 overridden on the command line. They do not set sticky tags. Note that 6714 you can only "commit" to a file checked out with a sticky tag, if the 6715 tag identifies a branch. 6716 6717 There are really two types of sticky tags, one attached to individual 6718 files (in the ./CVS/Entries file) and one attached to each directory 6719 (in the ./CVS/Tag file). They can differ. 6720 6721 The "add" command registers the desire to add a new file. If the 6722 "directory tag" (./CVS/Tag) file exists at the time of the "add", the 6723 value stored in ./CVS/Tag becomes the "sticky tag" on the new file. 6724 The file doesn't exist in the Repository until you "commit" it, but 6725 the ./CVS/Entries file holds the sticky tag name from the time of the 6726 "add" forward. 6727 6728 Last modified: _6/13/1997_ 6729 6730 6. Is there a way to avoid reverting my Emacs buffer after committing a 6731 file? Is there a "cvs-mode" for Emacs? 6732 6733 See Section 4F.1 6734 6735 Last modified: _6/13/1997_ 6736 6737 7. How does conflict resolution work? What *really* happens if two of us 6738 change the same file? 6739 6740 While editing files, there is no conflict. You are working on separate 6741 copies of the file stored in the virtual "branch" represented by your 6742 working directories. After one of you commits a file, the other may 6743 not commit the same file until "update" has merged the earlier 6744 committed changes into the later working file. 6745 6746 For example, say you both check out rev 1.2 of <file> and make change 6747 to your working files. Your coworker commits revision 1.3. When you 6748 try to commit your file, CVS says: 6749 6750 cvs commit: Up-to-date check failed for `<file>' 6751 6752 You must merge your coworker's changes into your working file by 6753 typing: 6754 6755 cvs update <file> 6756 6757 which will produce the output described in 2B.6. 6758 6759 If a conflict occurs, the filename will be shown with a status of 'C'. 6760 After you resolve any overlaps caused by the merging process, you may 6761 then commit the file. See 3P.6 for info on "sticky conflicts". 6762 6763 Even if you get a simple 'M', you should examine the differences 6764 before committing the file. A smooth, error-free text merge is still 6765 no indication that the file is in proper shape. Compile and test it at 6766 least. 6767 6768 The answer to two obvious questions is "Yes". 6769 6770 Yes, the first one who commits avoids the merge. Later developers have 6771 to merge the earlier changes into their working files before 6772 committing the merged result. Depending on how difficult the merge is 6773 and how important the contending projects are, the order of commits 6774 and updates might have to be carefully staged. 6775 6776 And yes, between the time you execute "update" and "commit" (while you 6777 are fixing conflicts and testing the results) someone else may commit 6778 another revision of <file>. You will have to execute "update" again to 6779 merge the new work before committing. Most organizations don't have 6780 this problem. If you do, you might consider splitting the file. Or 6781 hiring a manager. 6782 6783 Last modified: _6/13/1997_ 6784 6785 8. How can I tell who has a module checked out? 6786 6787 If you "checkout" module names (not relative pathnames) and you use 6788 the release command, the "history" command will display active 6789 checkouts, who has them and where they were checked out. It is 6790 advisory only; it can be circumvented by using the '-l' option on the 6791 main "cvs" command. 6792 6793 Last modified: _6/13/1997_ 6794 6795 9. Where did the .#<file>.1.3 file in my working directory come from? 6796 6797 It was created during an "update" when CVS merged changes from the 6798 Repository into your modified working file. 6799 6800 It serves the same purpose as any "backup" file: saving your bacon 6801 often enough to be worth retaining. It is invaluable in recovering 6802 when things go wrong. 6803 6804 Say Developers A (you) and B check out rev 1.3 of file <file>. You 6805 both make changes -- different changes. B commits first, so <file>,v 6806 in the Repository contains revisions up through 1.4. 6807 6808 At this point, there are 5 (yes, five) versions of the file of 6809 interest to you: 6810 6811 Revision 1.3 (What you originally checked out.) 6812 6813 Revision 1.4 (What you need from developer B.) 6814 6815 Your old working file. (Before the update.) 6816 6817 Your new working file. (After the merge caused by "update".) 6818 6819 Revision 1.5 (Which you will commit shortly.) 6820 6821 In the case where your working file was not modified, #1 and #3 will 6822 be the same, as will #2 and #4. In this degenerate case, there is no 6823 need to create #5. The following assumes that your working file was 6824 modified. 6825 6826 If the merge executed by the "update" caused no overlaps, and you 6827 commit the file immediately, #4 and #5 will be the same. But you can 6828 make arbitrary changes before committing, so the difference between #4 6829 and #5 might be more than just the correction of overlaps. In general, 6830 though, you don't need #4 after a commit. 6831 6832 But #3 (which is the one saved as ".#<file>.1.3") holds all of your 6833 work, independent of B's work. It could represent a major effort that 6834 you couldn't afford to lose. If you don't save it somewhere, the merge 6835 makes #3 *disappear* under a potential blizzard of conflicts caused by 6836 overlapping changes. 6837 6838 I have been saved a few times, and others I support have been saved 6839 hundreds of times, by the ability to "diff <original file> <original 6840 file with only my work added>", which can be done in the example above 6841 by the Unix shell command: 6842 6843 cvs update -p -r 1.3 <file> | diff - .#<file>.1.3 6844 6845 The assumption is that the ".#" files will be useful far beyond the 6846 "commit" point, but not forever. You are expected to run the "normal" 6847 Unix cleanup script from "cron", which removes "#*" and ".#*" files 6848 older than a some period chosen by your sysadmin, usually ranging from 6849 7 to 30 days. 6850 6851 A question was raised about the need for #3 after #5 has been 6852 committed, under the assumption that you won't commit files until 6853 everything is exactly as you like them. 6854 6855 This assumes perfect humans, which violates one of the Cardinal rules 6856 of Software Engineering: Never assume any form of discipline on the 6857 part of the users of software. If restrictions are not bound into the 6858 software, then you, the toolsmith, have to arrange a recovery path. 6859 6860 In other words, I've seen every possible variety of screwup you can 6861 imagine in #5. There is no way to make assumptions about what "should" 6862 happen. I've seen #5 filled with zeros because of NFS failures, I've 6863 seen emacs core dumps that leave #5 in an unreasonable state, I've 6864 seen a foolish developer uppercase the whole file (with his "undo" 6865 size set low so he couldn't undo it) and decide that it would be less 6866 work to play with the uppercased file than to blow it away and start 6867 over. I've even seen committed files with conflict markers still in 6868 them, a sure sign of carelessness. 6869 6870 There are all sorts of scenarios where having #3 is incredibly useful. 6871 You can move it back into place and try again. 6872 6873 Last modified: _6/13/1997_ 6874 6875 10. What is this "ignore" business? What is it ignoring? 6876 6877 The "update" and "import" commands use collections of Unix wildcards 6878 to skip over files and directories matching any of those patterns. 6879 6880 You may add to the built-in ignore list by adding lines of 6881 whitespace-separated wildcards to the following places: (They are read 6882 in this order.) 6883 6884 In a file named "cvsignore" in $CVSROOT/CVSROOT. 6885 6886 A Repository Administrator uses this to add site-specific files and 6887 patterns to the built-in ignore list. 6888 6889 In a file named ".cvsignore" in your home directory. 6890 6891 For user-specific files. For example, if you use "__" as your default 6892 junk file prefix, you can put "__*" in your .cvsignore file. 6893 6894 People who play around exclusively in directory trees where the 6895 Makefiles are generated by "imake" or "configure" might want to put 6896 "Makefile" in their ignore list, since they are all generated and 6897 usually don't end up in the Repository. 6898 6899 In the CVSIGNORE environment variable. 6900 6901 For session-specific files. 6902 6903 Via the '-I' option on "import" or "update" commands. 6904 6905 For this-command-only files. 6906 6907 In a file named ".cvsignore" within each directory. 6908 6909 The contents of a ".cvsignore" file in each directory is temporarily 6910 added to the ignore list. This way you can ignore files that are 6911 peculiar to that directory, such as executables and other generated 6912 files without known wildcard patterns. 6913 6914 In any of the places listed above, a single '!' character nulls out 6915 the ignore list. A Repository administrator can use this to override, 6916 rather than enhance, the built-in ignore list. A user can choose to 6917 override the system-wide ignore list. For example, if you place "! *.o 6918 *.a" in your .cvsignore file, only *.o *.a files, plus any files a 6919 local-directory .cvsignore file, are ignored. 6920 6921 A variant of the ignore-file scheme is used internally during 6922 checkout. "Module names" found in the modules file (or on the 6923 "checkout" command line) that begin with a '!' are ignored during 6924 checkout. This is useful to permanently ignore (if the '!' path is in 6925 the modules file) or temporarily ignore (if the '!' path is on the 6926 command line) a sub-directory within a Repository hierarchy. For 6927 example: 6928 6929 cvs checkout !gnu/emacs/tests gnu/emacs 6930 6931 would checkout the module (or relative path within $CVSROOT) named 6932 "gnu/emacs", but ignore the "tests" directory within it. 6933 6934 Last modified: _6/13/1997_ 6935 6936 11. Is there a way to set user-specific configuration options? 6937 6938 User-specific configuration is available through use of a ".cvsrc" 6939 file in your home directory. 6940 6941 CVS searches the first column of your ~/.cvsrc file for the cvs 6942 command name you invoked. If the command is found, the rest of the 6943 line is treated like a set of command line options, stuffed into the 6944 command line before the arguments you actually typed. 6945 6946 For example, if you always want to see context diffs and you never 6947 want to have to delete a file before you run "cvs remove", then you 6948 should create a .cvsrc file containing the following: 6949 6950 diff -c 6951 remove -f 6952 6953 which will add the given options to every invocation of the given 6954 commands. 6955 6956 [[The rest of this will be removed someday, when CVS changes.]] 6957 6958 I would like to stop here with a comment that the command name to use 6959 is the full, canonical one. But the command that the cvsrc support 6960 uses is the string you typed on the command line, not the proper 6961 command. So to get the full effect of the above example, you should 6962 also add all the alternate command names: 6963 6964 di -c 6965 dif -c 6966 rm -f 6967 delete -f 6968 6969 There are two other limitations that will probably be fixed when CVS 6970 sprouts long option names: 6971 6972 It only affects options made available on the command line. 6973 6974 There is a limited number of short options. With long option names, 6975 there is no problem. You can have as many long options as you like, 6976 affecting anything that looks malleable. 6977 6978 The existing command line options do not come in on/off pairs, so 6979 there is no easy way to override your ~/.cvsrc configuration for a 6980 single invocation of a command. 6981 6982 Choosing a good set of long option pairs would fix this. 6983 6984 Last modified: _6/13/1997_ 6985 6986 12. Is it safe to interrupt CVS using Control-C? 6987 6988 It depends on what you mean by "safe". ("Ah," said Arthur, "this is 6989 obviously some strange usage of the word *safe* that I wasn't 6990 previously aware of." -- Hitchhiker's Guide to the Galaxy) 6991 6992 You won't hurt the underlying RCS files and if you are executing a 6993 command that only *reads* data, you will have no cleanup to do. 6994 6995 But you may have to hit Control-C repeatedly to stop it. CVS uses the 6996 Unix "system" routine which blocks signals in the CVS parent process. 6997 A single Control-C during "system" will only halt the child process, 6998 usually some form of RCS command. 6999 7000 If you don't hit another Control-C while the CVS process has control, 7001 it is likely to continue onto the next task assuming that the earlier 7002 one did its job. It is not enough to hit two Control-C's. You might 7003 simply kill two child processes and not interrupt CVS at all. 7004 Depending on the speed of your processor, your terminal and your 7005 fingers, you might have to hit dozens of Control-C's to stop the damn 7006 thing. 7007 7008 Executing a CVS command, such as "commit" or "tag" that writes to the 7009 files is a different matter. 7010 7011 Since CVS is not a full-fledged database, with what database people 7012 call "commit points", merely stopping the process will not back out 7013 the "transaction" and place you back in the starting blocks. CVS has 7014 no concept of an "atomic" transaction or of "backtracking", which 7015 means that a command can be half-executed. 7016 7017 Hitting Control-C will usually leave lock files that you have to go 7018 clean up in the Repository. 7019 7020 Example1: 7021 7022 If you interrupt a multi-file "commit" in the middle of 7023 an RCS checkin, RCS will leave the file either fully 7024 checked-in or in its original state. But CVS might have 7025 been half-way through the list of files to commit. The 7026 directory or module will be inconsistent. 7027 7028 To recover, you must remove the lock files, then decide 7029 whether you want to back out or finish the job. 7030 7031 To back out, you'll have to apply the "admin -o" 7032 command, very carefully, to remove the newly committed 7033 revisions. This is usually a bad idea, but is 7034 occasionally necessary. 7035 7036 To finish, you can simply retype the same commit command. 7037 CVS will figure out what files are still modified and 7038 commit them. It helps that RCS doesn't leave a file in an 7039 intermediate state. 7040 7041 Example2: 7042 7043 If you interrupt a multi-file "tag" command, you have a 7044 problem similar, but not equivalent, to interrupting a 7045 "commit". The RCS file will still be consistent, but 7046 unlike "commit", which only *adds* to the RCS file, "tag" 7047 can *move* a tag and it doesn't keep a history of what 7048 revision a tag used to be attached to. 7049 7050 Normally, you have little choice but to re-execute the 7051 command and allow it to tag everything consistently. 7052 7053 You might be able to recover by carefully re-applying the 7054 tags via the "cvs admin -N" command, but you'll still have 7055 to dig up from outside sources the information you use to 7056 determine what tag was on what revision in what file. 7057 the Repository, or by using the equivalent: "cvs admin". 7058 7059 Halting a new "checkout" should cause no harm. If you don't want it, 7060 "release" (or rm -rf) it. If you do want it, re-execute the command. A 7061 repeated "checkout" from above a directory acts like a repeated 7062 "update -d" within it. 7063 7064 Halting "update" half-way will give you an unpredictable collection of 7065 files and revisions. To continue, you can rerun the update and it 7066 should move you forward into in a known state. To back out, you'll 7067 have to examine the output from the first "update" command, take a 7068 look at each file that was modified and reconstruct the previous state 7069 by editing the ./CVS/Entries file and by using "cvs admin". Good Luck. 7070 7071 Last modified: _6/13/1997_ 7072 7073 13. How do I turn off the "admin" command? 7074 7075 In the current revision, you'd have to edit the source code. 7076 7077 Last modified: _6/13/1997_ 7078 7079 14. How do I turn off the ability to disable history via "cvs -l"? 7080 7081 In the current revision, you'd have to edit the source code. 7082 7083 Last modified: _6/13/1997_ 7084 7085 15. How do I keep certain people from accessing certain directories? 7086 7087 If you don't try to run CVS set[ug]id, you can use Unix groups and 7088 permissions to limit access to the Repository. 7089 7090 If you only want to limit "commit" commands, you can write a program 7091 to put in the "commitinfo" file. In the "contrib" directory, there are 7092 a few scripts that might help you out. 7093 7094 Last modified: _6/13/1997_ 7095 7096 Category: /User_Tasks_/Getting_Started/ 7097 7098 " + Getting Started" 7099 7100 1. What is the first thing I have to know? 7101 7102 Your organization has most likely assigned one or more persons to 7103 understand, baby-sit and administer the CVS programs and the data 7104 Repository. I call these persons Repository Administrators. They 7105 should have set up a Repository and "imported" files into it. 7106 7107 If you don't believe anyone has this responsibility, or you are just 7108 testing CVS, then *you* are the Repository Administrator. 7109 7110 If you are a normal user of CVS ask your Repository Administrator what 7111 module you should check out. 7112 7113 Then you can work. 7114 7115 If you *are* the Repository Administrator, you will want to read 7116 everything you can get your hands on, including this FAQ. Source 7117 control issues can be difficult, especially when you get to branches 7118 and release planning. Expect to feel stupid for a few days/weeks. 7119 7120 No tool in the universe avoids the need for intelligent organization. 7121 In other words, there are all sorts of related issues you will 7122 probably have to learn. Don't expect to dive in without any 7123 preparation, stuff your 300 Megabytes of sources into CVS and expect 7124 to start working. If you don't prepare first, you will probably spend 7125 a few sleepless nights. 7126 7127 Last modified: _6/13/1997_ 7128 7129 2. Where do I work? 7130 7131 Wherever you have disk space. That's one of the advantages of CVS: you 7132 use the "checkout" command to copy files from the Repository to your 7133 working directory, which can be anywhere you have the space. 7134 7135 Your local group might have conventions for where to work. Ask your 7136 peers. 7137 7138 Last modified: _6/13/1997_ 7139 7140 3. What does CVS use from my environment? 7141 7142 You must set two environment variables. Some shells share these 7143 variables with local shell variables using a different syntax. You'll 7144 have to learn how your shell handles them. 7145 7146 Variable Value (or action) 7147 --------- --------------------- 7148 CVSROOT Absolute pathname of the head of your Repository. 7149 7150 PATH Normally set to a list of ':'-separated directory 7151 pathnames searched to find executables. You must 7152 make sure "cvs" is in one of the directories. 7153 7154 If your CVS was built with the RCSBIN directory set 7155 to null (""), and you don't set the RCSBIN 7156 variable mentioned below, then the RCS commands 7157 also must be somewhere in your PATH. 7158 7159 Optional variables: (Used if set, but ignored otherwise.) 7160 7161 Variable Value (or action) 7162 --------- --------------------- 7163 CVSEDITOR The name of your favorite fast-start editor 7164 program. You'll be kicked into your editor to 7165 supply revision comments if you don't specify them 7166 via -m "Log message" on the command line. 7167 7168 EDITOR Used if CVSEDITOR doesn't exist. If EDITOR 7169 doesn't exist, CVS uses a configured constant, 7170 usually, "vi". 7171 7172 CVSREAD Sets files to read-only on "checkout". 7173 7174 RCSBIN Changes where CVS finds the RCS commands. 7175 7176 CVSIGNORE Adds to the ignore list. See Section 2D. 7177 7178 Other variables used by CVS that are normally set upon login: 7179 7180 Variable Value (or action) 7181 --------- --------------------- 7182 LOGNAME Used to find the real user name. 7183 7184 USER Used to find the real user name if no LOGNAME. 7185 7186 HOME Used to determine your home directory, if set. 7187 Otherwise LOGNAME/USER/getuid() are used to find 7188 your home directory from the passwd file. 7189 7190 TMPDIR Used during import. It might also be used if your 7191 platform's version of mktemp(3) is unusual, or 7192 you have changed the source to use tmpnam(3). 7193 7194 Last modified: _6/13/1997_ 7195 7196 4. OK, I've been told that CVS is set up, my module is named "ralph" and I 7197 have to start editing. What do I type? 7198 7199 cd <where you have some space to work> 7200 cvs checkout ralph 7201 cd ralph 7202 7203 And hack away. 7204 7205 Last modified: _6/13/1997_ 7206 7207 5. I have been using RCS for a while. Can I convert to CVS without losing 7208 my revision history? How about converting from SCCS? 7209 7210 If you are asking such questions, you are not a mere user of CVS, but 7211 one of its Administrators! You should take a look at Section 4A, 7212 "Installing CVS" and Section 4B, "Setting up and Managing the 7213 Repository". 7214 7215 Last modified: _6/13/1997_ 7216 7217 Category: /User_Tasks_/Less_Common_User_Tas/ 7218 7219 " + Less Common User Tasks" 7220 7221 1. Can I create non-CVS sub-directories in my working directory? 7222 7223 Yes. Unless the directory exists in the Repository, "update" will skip 7224 over them and print a '?' the way it does for files you forgot to add. 7225 You can avoid seeing the '?' by adding the name of the foreign 7226 directory to the ./.cvsignore file, just ask you can do with files. 7227 7228 If you explicitly mention a foreign directory on the "update" command 7229 line, it will traverse the directory and waste a bit of time, but if 7230 any directory or sub-directory lacks the ./CVS administrative 7231 directory, CVS will print an error and abort. 7232 7233 Last modified: _6/13/1997_ 7234 7235 2. How do I add new sub-directories to the Repository? 7236 7237 The "add" command will work on directories. You type: 7238 7239 mkdir <dir> 7240 cvs add <dir> 7241 7242 It will respond: 7243 7244 Directory /Repos/<dir> added to the repository 7245 7246 and will create both a matching directory in the Repository and a 7247 ./CVS administrative directory within the local <dir> directory. 7248 7249 Last modified: _6/13/1997_ 7250 7251 3. How do I remove a file I don't need? 7252 7253 (See the questions in Section 4B on removing files from the 7254 Repository.) 7255 7256 You type: 7257 7258 rm <file> 7259 cvs remove <file> 7260 7261 CVS registers the file for removal. To complete the removal, you must 7262 type: 7263 7264 cvs commit <file> 7265 7266 CVS moves the file to the Attic associated with your working 7267 directory. Each directory in the Repository stores its deleted files 7268 in an Attic sub-directory. A normal "checkout" doesn't look in the 7269 Attic, but if you specify a tag, a date or a revision, the "checkout" 7270 (or "update") command will retrieve files from the Attic with that 7271 tag, date or revision. 7272 7273 Last modified: _6/13/1997_ 7274 7275 4. How do I rename a file? 7276 7277 CVS does not offer a way to rename a file in a way that CVS can track 7278 later. See Section 4B for more information. 7279 7280 Here is the best (to some, the only acceptable) way to get the effect 7281 of renaming, while preserving the change log: 7282 7283 Copy the RCS (",v") file directly in the Repository. 7284 7285 cp $CVSROOT/<odir>/<ofile>,v $CVSROOT/<ndir>/<nfile>,v 7286 7287 By duplicating the file, you will preserve the change history and the 7288 ability to retrieve earlier revisions of the old file via the "-r 7289 <tag/rev>" or "-D <date>" options to "checkout" and "update". 7290 7291 Remove the old file using CVS. 7292 7293 cd <working-dir>/<odir> rm <ofile> 7294 cvs remove <ofile> 7295 cvs commit <ofile> 7296 7297 This will move the <ofile> to the Attic associated with <odir>. 7298 7299 Retrieve <nfile> and remove all the Tags from it. 7300 7301 By stripping off all the old Tags, "checkout -r" and "update -r" won't 7302 retrieve revisions Tagged before the renaming. 7303 7304 cd <working-dir>/<ndir> 7305 cvs update <nfile> 7306 cvs log <nfile> # Save the list of Tags 7307 cvs tag -d <tag1> <nfile> 7308 cvs tag -d <tag2> <nfile> 7309 . . . 7310 7311 This technique can be used to rename files within one directory or 7312 across different directories. You can apply this idea to directories 7313 too, as long as you apply the above to each file and don't delete the 7314 old directory. 7315 7316 Of course, you have to change your build system (e.g. Makefile) in 7317 your <working-dir> to know about the name change. 7318 7319 Warning: Stripping the old tags from the copied file will allow "-r 7320 <tag>" to do the right thing, but you will still have problems with 7321 "-D <date>" because there is no place to store the "deletion time". 7322 See 5B.3 for more details. 7323 7324 Last modified: _6/13/1997_ 7325 7326 5. How do I make sure that all the files and directories in my working 7327 directory are really in the Repository? 7328 7329 A "cvs update", or "cvs -n update" (which won't modify your working 7330 directory) will display foreign elements, which have no counterpart in 7331 the Repository, preceded by a '?'. To register foreign directories, 7332 you can use "cvs add". To register foreign files, you can use "cvs 7333 add" followed by "cvs commit". 7334 7335 You could also checkout your module, or the Repository directory 7336 associated with your working directory, a second time into another 7337 work area and compare it to your working directory using the (non-CVS) 7338 "diff -r" command. 7339 7340 By default many patterns of files are ignored. If you create a file 7341 named "core" or a file ending in ".o", it is usually ignored. If you 7342 really want to see all the files that aren't in the Repository, you 7343 can use a special "ignore" pattern to say "ignore no files". Try 7344 executing: (You may have to quote or backwhack (i.e. precede by '\') 7345 the '!' in your shell.) 7346 7347 cvs -n update -I ! 7348 7349 The above command will display not only the normal modified, update 7350 and conflict indicators ('M', 'U', and 'C' respectively) on files 7351 within the Repository, but it will also display each file not in the 7352 Repository preceded by a '?' character. 7353 7354 The '-n' option will not allow "update" to alter your working 7355 directory. 7356 7357 Last modified: _6/13/1997_ 7358 7359 6. How do I create a branch? 7360 7361 Type this in your working directory: 7362 7363 cvs tag -b <branch_tag> 7364 7365 and you will create a branch. No files have real branches in them yet, 7366 but if you move onto the branch by typing: 7367 7368 cvs update -r <branch_tag> 7369 7370 and commit a file in the normal way: 7371 7372 cvs commit <file> 7373 7374 then a branch will be created in the underlying <file>,v file and the 7375 new revision of <file> will appear only on that branch. 7376 7377 See Section 4C, on Branching. 7378 7379 Last modified: _6/13/1997_ 7380 7381 7. How do I modify the modules file? How about the other files in the 7382 CVSROOT administrative area? 7383 7384 A module named "modules" has been provided in the default modules 7385 file, so you can type: 7386 7387 cvs checkout modules 7388 cd modules 7389 7390 Another module named CVSROOT has been provided in the default modules 7391 file, covering all the administrative files. Type: 7392 7393 cvs checkout CVSROOT 7394 cd CVSROOT 7395 7396 Then you can edit your files, followed by: 7397 7398 cvs commit 7399 7400 If you start with the provided template for the "modules" file, the 7401 CVSROOT and the "modules" module will have the "mkmodules" program as 7402 a "commit helper". After a file is committed to such a module, 7403 "mkmodules" will convert a number of standard files (See 4B.2) in the 7404 CVSROOT directory inside the Repository into a form that is usable by 7405 CVS. 7406 7407 Last modified: _6/13/1997_ 7408 7409 8. How do I split a file into pieces, retaining revision histories? 7410 7411 If you and a coworker find yourselves repeatedly committing the same 7412 file, but never for changes in the same area of the file, you might 7413 want to split the file into two or more pieces. If you are both 7414 changing the same section of code, splitting the file is of no use. 7415 You should talk to each other instead. 7416 7417 If you decide to split the file, here's a suggestion. In many ways, it 7418 is similar to multiple "renamings" as described in 2C.4 above. 7419 7420 Say you want to split , which already in the Repository, into three 7421 pieces, , and . 7422 7423 Copy the RCS (",v") files directly in the Repository, creating the 7424 new files, then bring readable copies of the new files into the 7425 working directory via "update". 7426 7427 cp $CVSROOT//,v $CVSROOT//,v cp $CVSROOT//,v $CVSROOT//,v 7428 cvs update 7429 7430 Then remove all the from the new files, either using: 7431 7432 cvs log # Save the list of 7433 cvs tag -d 7434 cvs tag -d 7435 . . . 7436 7437 (eivind@freebsd.org) or using the following little script to 7438 autmatically remove the tags directly from the repository files: 7439 7440#!/bin/sh 7441for file in $* 7442do 7443 TAGS=`rlog $file | awk '/^symbolic names:/,/^keyword subst/' | awk 'BEG 7444IN {FS=":"} /^\t/ {print $1}'` 7445 echo The tags in $file are 7446 echo $TAGS 7447 echo Is it OK to remove these? 7448 read confirm 7449 if [ "$confirm" = "y" -o "$confirm" = "yes" ] 7450 then 7451 for tag in $TAGS 7452 do 7453 echo Removing $file:$tag 7454 rcs -n$tag $file 7455 done 7456 fi 7457done 7458 7459 Edit each file until it has the data you want in it. This is a 7460 hand-editing job, not something CVS can handle. Then commit all the 7461 files. 7462 7463 [From experience, I'd suggest making sure that only one copy of each 7464 line of code exists among the three files, except for "include" 7465 statements, which must be duplicated. And make sure the code 7466 compiles.] 7467 7468 emacs 7469 cvs commit 7470 7471 As in the "rename" case, by duplicating the files, you'll preserve the 7472 change history and the ability to retrieve earlier revisions. 7473 7474 Of course, you have to alter your build system (e.g. Makefiles) to 7475 take the new names and the change in contents into account. 7476 7477 Last modified: _3/11/1998_ 7478 7479 Category: /What_is_CVS_/ 7480 7481 " What is CVS? " 7482 7483 Category: /What_is_CVS_/How_does_CVS_differ_/ 7484 7485 " + How does CVS differ from other, similar software?" 7486 7487 1. How does CVS differ from RCS? 7488 7489 CVS uses RCS to do much of its work and absolutely all the work of 7490 changing the underlying RCS files in the Repository. 7491 7492 RCS comprises a set of programs designed to keep track of changes to 7493 individual files. Of course, it also allows you to refer to multiple 7494 files on the command line, but they are handled by iterating over 7495 individual files. There is no pretense of coordinated interaction 7496 among groups of files. 7497 7498 CVS's main intent is to provide a set of grouping functions that allow 7499 you to treat a collection of RCS files as a single object. Of course, 7500 CVS also has to do a lot of iteration, but it tries its best to hide 7501 that it is doing so. In addition, CVS has some truly group-oriented 7502 facets, such as the modules file and the CVS administrative files that 7503 refer to a whole directory or module. 7504 7505 One group aspect that can be a bit confusing is that a CVS branch is 7506 not the same as an RCS branch. To support a CVS branch, CVS uses 7507 "tags" (what RCS calls "symbols") and some local state, in addition to 7508 RCS branches. 7509 7510 Other features offered by CVS that are not supported directly by RCS 7511 are 7512 7513 Automatic determination of the state of a file, (e.g. modified, 7514 up-to-date with the Repository, already tagged with the same string, 7515 etc.) which helps in limiting the amount of displayed text you have to 7516 wade through to figure out what changed and what to do next. 7517 7518 A copy-modify-merge scheme that avoids locking the files and allows 7519 simultaneous development on a single file. 7520 7521 Serialization of commits. CVS requires you to merge all changes 7522 committed (via "update") since you checked out your working copy of 7523 the file. Although it is still possible to commit a file filled with 7524 old data, it is less likely than when using raw RCS. 7525 7526 Relatively easy merging of releases from external Vendors. 7527 7528 Last modified: _6/13/1997_ 7529 7530 2. How does CVS differ from SCCS? 7531 7532 SCCS is much closer to RCS than to CVS, so some of the previous entry 7533 applies. 7534 7535 You might want to take a look at Walter Tichy's papers on RCS, which 7536 are referred to in the RCS man pages. 7537 7538 [[More info here?]] 7539 7540 Last modified: _6/13/1997_ 7541 7542 3. How does CVS differ from ClearCase? 7543 7544 ClearCase is a distributed client-server version control system. 7545 ClearCase is a variant DSEE tools, formerly available on Apollo 7546 platforms. The ClearCase tool set includes a few X-based interface 7547 tools, a command-line interface, and C programmer API. It is currently 7548 available on Sun, HP, SGI and OSF/1 platforms. 7549 7550 ClearCase uses a special Unix filesystem type, called "mvfs" for 7551 "multi-version file system". Conceptually, mvfs adds another dimension 7552 to a regular Unix filesystem. The new axis is used to store the 7553 different versions of files and to provide a tree-hierarchical view of 7554 a collection of objects that might be scattered across any number of 7555 separate hosts on your local network. 7556 7557 Each user acquires a "view" into the file database by creating a 7558 special mvfs mount point on their machine. Each view has a 7559 "configuration spec" containing a set of selection rules that specify 7560 the particular version of each file to make visible in that view. You 7561 can think of a "view" as a work area in CVS, except that the files 7562 don't really exist on your local disk until you modify them. This 7563 technique conserves disk space because it doesn't keep private copies 7564 of read-only files. 7565 7566 Another advantage is that a view is "transparent" in the sense that 7567 all of the files in a "view" appear to be regular Unix files to other 7568 tools and Unix system calls. An extended naming convention allows 7569 access to particular versions of a file directly: 7570 "test.cc@@/main/bugfix/3" identifies the third version of test.c on 7571 the bugfix branch. 7572 7573 ClearCase supports both the copy-modify-merge model of CVS (by using 7574 what are called "unreserved checkouts" and the checkin/checkout 7575 development model with file locking. Directories are 7576 version-controlled objects as well as files. A graphical merge tool is 7577 provided. Like RCS, ClearCase supports branches, symbolic tags, and 7578 delta compression. ASCII as well as binary files are supported, and 7579 converters from RCS, SCCS, DSEE formats are also included. 7580 7581 A make-compatible build facility is provided that can identify common 7582 object code and share it among developers. A build auditing feature 7583 automatically records file dependencies by tracking every file that is 7584 opened when producing a derived object, thus making explicit 7585 dependency lists unnecessary. Pre- and post-event triggers are 7586 available for most ClearCase operations to invoke user programs or 7587 shell scripts. User-defined attributes can be assigned to any version 7588 or object. Hyper-links between version controlled objects can record 7589 their relationship. 7590 7591 For more information, contact: 7592 7593 Atria Software, Inc. 24 Prime Park Way Natick, MA 01760 info@atria.com 7594 7595 (508) 650-1193 (phone) (508) 650-1196 (fax) 7596 7597 Originally contributed by Steve Turner 7598 Edited by the author of this FAQ. 7599 7600 Last modified: _6/13/1997_ 7601 7602 4. How does CVS differ from TeamWare/SparcWorks? 7603 7604 TeamWare is a configuration management tool from Sun Microsystems, a 7605 part of SparcWorks. It uses the same copy and merge model as CVS. The 7606 central abstraction is a workspace, which corresponds to either a CVS 7607 branch or a checked out module. TeamWare allows you to manipulate 7608 workspaces directly, including moving and merging code between 7609 workspaces. You can put your workspace on tape and continue to work 7610 with it at home, just like you can with CVS. TeamWare is built upon 7611 and compatible with SCCS. 7612 7613 TeamWare provides both a command line interface and a graphical 7614 interface. The CodeManager tool will display the project as a tree of 7615 workspaces, and allows you to manipulate them with drag and drop. The 7616 other tools are VersionTool that displays and manipulates a dag with a 7617 version history of a single file, CheckPoint that will create symbolic 7618 tags, MakeTool, a make compatible tool with a GUI, and FileMerge which 7619 will interactively merge files when needed (like emerge for emacs). If 7620 you have a sun, you can try /usr/old/mergetool for an old SunView 7621 version of FileMerge. 7622 7623 Email: sunprosig@sun.com 7624 7625 Originally extracted from TeamWare 7626 Marketing literature by Per Abrahamsen. 7627 Edited by the author of this FAQ. 7628 7629 For more information, contact: 7630 7631 SunExpress, Inc. P.O. Box 4426 Bridgeton, MO 63044-9863 (800)873-7869 7632 7633 Last modified: _6/13/1997_ 7634 7635 5. How does CVS differ from Aegis? 7636 7637 Aegis appears to be a policy-setting tool that allows you to use other 7638 sub-programs (make, RCS, etc.) to implement pieces of the imposed 7639 policy. 7640 7641 The initial document seems to say that most Unix tools are inadequate 7642 for use under Aegis. 7643 7644 It is not really similar to CVS and requires a different mindset. 7645 7646 [[Need more info here.]] 7647 7648 Last modified: _6/13/1997_ 7649 7650 6. How does CVS differ from Shapetools? 7651 7652 Shapetools includes a build mechanism (called Shape, not surprisingly) 7653 that is aware of the version mechanism, and some dependency tracking. 7654 It is based on a file system extension called Attributed File System, 7655 which allows arbitrary-sized "attributes" to be associated with a 7656 file. Files are version controlled in a manner similar to RCS. 7657 Configurations are managed through the Shapefile, an extension of the 7658 Makefile syntax and functionality. Shape includes version selection 7659 rules to allow sophisticated selection of component versions in a 7660 build. 7661 7662 Shapetools' concurrency control is pessimistic, in contrast to that of 7663 CVS. Also, there's very limited support for branching and merging. It 7664 has a built-in policy for transitioning a system from initial 7665 development to production. 7666 7667 Contributed by Don Dwiggins 7668 7669 Last modified: _6/13/1997_ 7670 7671 7. How does CVS differ from TeamNet? 7672 7673 TeamNet is a configuration management tool from TeamOne. 7674 7675 For more information, contact: 7676 7677 TeamOne 710 Lakeway Drive, Ste 100 Sunnyvale, CA 94086 (800) 442-6650 7678 7679 Contributed by Steve Turner 7680 7681 Last modified: _6/13/1997_ 7682 7683 8. How does CVS differ from ProFrame? 7684 7685 ProFrame is a new system integration framework from IBM. ProFrame is 7686 compliant with the CFI (CAD Framework Initiative) industry standards, 7687 including the Scheme extension language. 7688 7689 ProFrame consists of three major components: (1) the Process Manager 7690 that automates your local design methodology (2) the Design Data 7691 Manager handles configuration management, and (3) Inter-tool 7692 Communication to provide a communication path among tools running on 7693 heterogeneous servers. 7694 7695 The Design Data Manager(2) is probably the appropriate component to 7696 compare to CVS. The Design Data Manager provides version control with 7697 checkin/checkout capability, configuration management, and data 7698 dependency tracking. A graphical data selection interface is provided. 7699 Using this interface, you may create and manipulate objects and 7700 hierarchy structures, view the revision history for an object, and 7701 view and assign attributes to a design object. 7702 7703 The ProFrame server currently runs only on RS6000, but clients may be 7704 a wide variety of Unix platforms. Contact IBM for the latest platform 7705 information. 7706 7707 For more information, contact: 7708 7709 IBM EDA Marketing and Sales P.O. Box 950, M/S P121 Poughkeepsie, NY 7710 12602 (800) 332-0066 7711 7712 Contributed by Steve Turner 7713 [extracted from the ProFrame 1.1.0 datasheet] 7714 7715 Last modified: _6/13/1997_ 7716 7717 9. How does CVS differ from CaseWare/CM? 7718 7719 CaseWare/CM is a software configuration management product from 7720 CaseWare, Inc. CaseWare/CM may be customized to support a wide variety 7721 of methodologies, including various phases of the software lifecycle, 7722 and different access rights for users. 7723 7724 A GUI is provided to view version histories and configurations. A 7725 merge tools is also included. CaseWare supports type-specific 7726 lifecycles, which allows different types of files to move through 7727 different lifecycles. Also provided is a build facility to support 7728 automatic dependency analysis, parallel, distributed, and remote 7729 builds, and variant releases. 7730 7731 CaseWare/CM has been integrated with other CASE tools, including 7732 FrameMaker, ALSYS Ada, CodeCenter/Object Center, HP SoftBench, and 7733 Software Through Pictures. CaseWare also offers CaseWare/PT, a problem 7734 tracking system to integrate change requests with configuration 7735 management. 7736 7737 Multiple vendors and operating systems are supported. 7738 7739 For more information, contact: 7740 7741 CaseWare, Inc. 108 Pacifica, 2nd Floor Irvine, CA 92718-3332 (714) 7742 453-2200 (phone) (714) 453-2276 (fax) 7743 7744 Contributed by Steve Turner 7745 [extracted from the CaseWare/CM data sheet] 7746 7747 Last modified: _6/13/1997_ 7748 7749 10. How does CVS differ from SABLIME? 7750 7751 Produced by AT&T. Sablime uses SCCS as the underlying source code 7752 control system. It uses some other control system (called sbcs I 7753 think) for managing binary files. It uses lock, edit, comit, unlock 7754 mechanism. It has a motif based GUI and curses based GUI (that works 7755 only with ksh, not tcsh, or bash) to do more common tasks. It has even 7756 a command line interface. 7757 7758 Changing source happens as a result of MR. A testing person or a 7759 developer assigns an MR (modification request) to a group of people. 7760 They are allowed to take out files under that MR and change them and 7761 check them back in. You can set up dependencies between and MR and do 7762 release management to say "I want the sources to include these MRs" 7763 etc. It is a reasonably good maintanance system. It is bit heavy 7764 weight though, and the interface is not too polished and does not work 7765 on windows (though that may have changed). rama@savera.com 7766 7767 Last modified: _7/30/1998_ 7768 7769 11. How does CVS differ from PVCS? 7770 7771 PVCS works on single files like RCS and SCCS, CVS works on complete 7772 subsystems. PVCS has a make utility (called a configuration builder), 7773 CVS does not. PVCS has a GUI interface for Unix, DOS, OS/2, and MS 7774 Windows. 7775 7776 Intersolv, Inc. 7777 1700 NW 167th Place 7778 OR 97006 7779 7780 Contributed by Per Abrahamsen 7781 [Extracted from Intersolv Marketing literature.] 7782 7783 Last modified: _6/13/1997_ 7784 7785 12. How does CVS differ from CMVC? 7786 7787 CMVC is an IBM Configuration Management and Version Control system. 7788 (Though I'm not certain that's the right acronym expansion.) It runs 7789 on Suns, HPs, RS6000s, OS/2 and Windows. 7790 7791 Other than revision control, it apparently has features to manage 7792 releases, bug tracking and the connection between alterations and 7793 reported bugs and feature requests. It is a client/server system, 7794 based on a choice of commercial Relational Database systems, and it 7795 provides a Motif or command line interface. 7796 7797 Unlike CVS, it uses a strict locking protocol to serialize source code 7798 alterations. 7799 7800 Last modified: _6/13/1997_ 7801 7802 Category: /What_is_CVS_/What_do_you_mean_by_/ 7803 7804 " + What do you mean by . . .? (Definitions)" 7805 7806 1. What are "The Repository", "$CVSROOT" and "CVSROOT"? 7807 7808 The Repository is a directory tree containing the CVS administrative 7809 files and all the RCS files that constitute "imported" or "committed" 7810 work. The Repository is kept in a shared area, separate from the 7811 working areas of all developers. 7812 7813 Users of CVS must set their "CVSROOT" environment variable to the 7814 absolute pathname of the head of the Repository. Most command line 7815 interpreters replace an instance of "$CVSROOT" with the value of the 7816 "CVSROOT" environment variable. By analogy, in this document 7817 "$CVSROOT" is used as shorthand for "the absolute pathname of the 7818 directory at the head of the Repository". 7819 7820 One of the things found in $CVSROOT is a directory named CVSROOT. It 7821 contains all the "state", the administrative files, that CVS needs 7822 during execution. The "modules", "history", "commitinfo", "loginfo" 7823 and other files can be found there. See 4B.2 for more information 7824 about CVSROOT files. 7825 7826 Last modified: _6/13/1997_ 7827 7828 2. What is an RCS file? 7829 7830 An RCS file is a text file containing the source text and the revision 7831 history for all committed revisions of a source file. It is stored 7832 separately from the working files, in a directory hierarchy, called 7833 the Repository. 7834 7835 RCS is the "Revision Control System" that CVS uses to manage 7836 individual files. RCS file names normally end in ",v", but that can be 7837 altered (via the RCS -x option) to conform to file naming standards on 7838 platforms with unusual filename limitations. 7839 7840 Last modified: _6/13/1997_ 7841 7842 3. What is a working file? 7843 7844 A working file is a disk file containing a checked-out copy of a 7845 source file that earlier had been placed under CVS. If the working 7846 file has been edited, the changes since the last committed revision 7847 are invisible to other users of CVS. 7848 7849 Last modified: _6/13/1997_ 7850 7851 4. What is a working directory (or working area)? 7852 7853 A working directory is the place where you work and the place from 7854 which you "commit" files. 7855 7856 The "checkout" command creates a tree of working directories, filling 7857 them with working files. Each working directory contains a 7858 sub-directory named ./CVS containing three administrative files, which 7859 are created by "checkout" and are always present: 7860 7861 ./CVS/Entries 7862 contains information about working files. 7863 7864 ./CVS/Repository 7865 contains the location of the directory within the 7866 Repository that was used to create the working directory. 7867 7868 ./CVS/Root 7869 contains the value of $CVSROOT at the time you created 7870 the working directory. 7871 7872 Other files may also appear in ./CVS depending on the state of your 7873 working directory: 7874 7875 ./CVS/Tag 7876 contains the "sticky tag" associated with the whole 7877 directory. See 3A.2 for its main purpose. 7878 [Created by "checkout" or "update" when using "-r <tag>".] 7879 [Deleted by "checkout" or "update" when using '-A'.] 7880 7881 ./CVS/Entries.Static 7882 contains a fixed list of working files. If this file 7883 exists, an "update" doesn't automatically bring newly 7884 added files out of the Repository. 7885 [Created and maintained by hand.] 7886 7887 ./CVS/Checkin.prog 7888 contains a program to run whenever anything in the 7889 working directory is committed. 7890 [Created by checkout if "-i <prog>" appears in the 7891 modules file for the checked-out module.] 7892 7893 ./CVS/Update.prog 7894 contains a program to run whenever anything in the 7895 working directory is updated. 7896 [Created by checkout if "-u <prog>" appears in the 7897 modules file for the checked-out module.] 7898 7899 ./CVS/<file>,p ./CVS/<file>,t 7900 contain (possibly zero-length) state information about an 7901 "add" that has not been committed. 7902 [Created by "add".] 7903 [Deleted by "commit" or "remove".] 7904 7905 Last modified: _6/13/1997_ 7906 7907 5. What is "checking out"? 7908 7909 "Checking out" is the act of using the "checkout" command to copy a 7910 particular revision from a set of RCS files into your working area. 7911 You normally execute "checkout" only once per working directory (or 7912 tree of working directories), maintaining them thereafter with the 7913 "update" command. 7914 7915 See section 3C on the "checkout" command. 7916 7917 Last modified: _6/13/1997_ 7918 7919 6. What is a revision? 7920 7921 A "revision" is a version of a file that was "committed" ("checked 7922 in", in RCS terms) some time in the past. CVS (and RCS) can retrieve 7923 any file that was committed by specifying its revision number or its 7924 "tag" ("symbolic name", in RCS terms). 7925 7926 In CVS, a "tag" is more useful than a revision number. It usually 7927 marks a milestone in development represented by different revision 7928 numbers in different files, all available as one "tagged" collection. 7929 7930 Sometimes the word "revision" is used as shorthand for "the file you 7931 get if you retrieve (via "checkout" or "update") the given revision 7932 from the Repository." 7933 7934 Last modified: _6/13/1997_ 7935 7936 7. What is a "Tag"? 7937 7938 A "Tag" is a symbolic name, a synonym or alias for a particular 7939 revision number in a file. The CVS "tag" command places the same "Tag" 7940 on all files in a working directory, allowing you to retrieve those 7941 files by name in the future. 7942 7943 The CVS "Tag" is implemented by applying RCS "symbols" to each 7944 individual file. The Tags on a file (or collection of files) may be 7945 displayed using the "log" command. 7946 7947 Last modified: _6/13/1997_ 7948 7949 8. What are "HEAD" and "BASE"? 7950 7951 HEAD and BASE are built-in tags that don't show up in the "log" or 7952 "status" listings. They are interpreted directly by CVS. 7953 7954 "HEAD" refers to the latest revision on the current branch in the 7955 Repository. The current branch is either the main line of development, 7956 or a branch in development created by placing a branch tag on a set of 7957 files and checking out that branch. 7958 7959 "BASE" refers to the revision on the current branch you last checked 7960 out, updated, or committed. If you have not modified your working 7961 file, "BASE" is the committed revision matching it. 7962 7963 Most of the time BASE and HEAD refer to the same revision. They can 7964 become different in two ways: 7965 7966 Someone else changed HEAD by committing a new revision of your file 7967 to the Repository. You can pull BASE up to equal HEAD by executing 7968 "update". 7969 7970 You moved BASE backward by executing "checkout" or "update" with the 7971 option "-r <rev/tag>" or "-D <date>". CVS records a sticky tag and 7972 moves your files to the specified earlier revision. You can clear the 7973 sticky tag and pull BASE up to equal HEAD again by executing "update 7974 -A". 7975 7976 Last modified: _6/13/1997_ 7977 7978 9. What is a Branch? 7979 7980 In general, a branch is any mechanism that allows one or more 7981 developers to modify a file without affecting anyone other than those 7982 working on the same branch. 7983 7984 There are four kinds of "branch" CVS can manage: 7985 7986 The Vendor Branch. 7987 7988 A single vendor branch is supported. The "import" command takes a 7989 sequence of releases from a source code vendor (called a "vendor" even 7990 if no money is involved), placing them on a special "Vendor" branch. 7991 The Vendor branch is considered part of the "Main line" of 7992 development, though it must be merged into locally modified files on 7993 the RCS Main branch before the "import" is complete. 7994 7995 See Section 3H ("import"). 7996 7997 Your Working directory. 7998 7999 A checked-out working directory, can be treated like a private branch. 8000 No one but you can touch your files. You have complete control over 8001 when you include work committed by others. However, you can't commit 8002 or tag intermediate versions of your work. 8003 8004 A Development branch. 8005 8006 A group of developers can share changes among the group, without 8007 affecting the Main line of development, by creating a branch. Only 8008 those who have checked-out the branch see the changes committed to 8009 that branch. This kind of branch is usually temporary, collapsing 8010 (i.e. merge and forget) into the Main line when the project requiring 8011 the branch is completed. 8012 8013 You can also create a private branch of this type, allowing an 8014 individual to commit (and tag) intermediate revisions without changing 8015 the Main line. It should be managed exactly like a Development Branch 8016 -- collapsed into the Main line (or its parent branch, if that is not 8017 the Main Branch) and forgotten when the work is done. 8018 8019 A Release branch. 8020 8021 At release time, a branch should be created marking what was released. 8022 Later, small changes (sometimes called "patches") can be made to the 8023 release without including everything else on the Main line of 8024 development. You avoid forcing the customer to accept new, possibly 8025 untested, features added since the release. This is also the way to 8026 correct bugs found during testing in an environment where other 8027 developers have continued to commit to the Main line while you are 8028 testing and packaging the release. 8029 8030 Although the internal format of this type of branch (branch tag and 8031 RCS branches) is the same as in a development branch, its purpose and 8032 the way it is managed are different. The major difference is that a 8033 Release branch is normally Permanent. Once you let a release out the 8034 door to customers, or to the next stage of whatever process you are 8035 using, you should retain forever the branch marking that release. 8036 8037 Since the branch is permanent, you cannot incorporate the branch fixes 8038 into the Main line by "collapsing" (merging and forgetting) the 8039 release branch. For large changes to many files on the release branch, 8040 you will have to perform a branch merge using "update -j <rev> -j 8041 <rev>". (See 4C.7) 8042 8043 The most common way to merge small changes back into Main line 8044 development is to make the change in both places simultaneously. This 8045 is faster than trying to perform a selective merge. 8046 8047 See 1D.12 (merges) and Section 4C, on Branching for more info. 8048 8049 Last modified: _6/13/1997_ 8050 8051 10. What is "the trunk"? 8052 8053 Another name for the RCS Main Branch. The RCS Main Branch is related, 8054 but not equivalent, to both the CVS Main branch and what developers 8055 consider to be the Main line of development. See 3H.3 and Section 4C 8056 on Branching. 8057 8058 Last modified: _6/13/1997_ 8059 8060 11. What is a module? 8061 8062 In essence, a module is a name you hand to the "checkout" command to 8063 retrieve one or more files to work on. It was originally intended to 8064 be a simple, unique name in the "modules" file attached to a directory 8065 or a subset of files within a directory. 8066 8067 The module idea is now a somewhat slippery concept that can be defined 8068 in two different ways: 8069 * A module is an argument to "checkout". There are three types: 8070 1. An entry in the modules file. A "module" name as described in 8071 'B.' below. 8072 2. A relative path to a directory or file in the Repository. 8073 3. A mixed-mode string of "modulename/relative-path". Everything 8074 up to the first slash ('/') is looked up as a module. The 8075 relative path is appended to the directory associated with 8076 the module name and the resulting path is checked out as in 8077 #2 above. 8078 * A module is a unique (within the file) character string in the 8079 first column of the modules file. There are five types: 8080 1. A name for a directory within the Repository that allows you 8081 to ignore the parent directories above it. 8082 Example: 8083 emacs gnu/emacs 8084 2. A name for a subset of the files within such a directory. 8085 Example: 8086 ls unix/bin Makefile ls.c 8087 The 2nd through Nth strings in the above can be files, 8088 directories or module substitutions. No relative paths. 8089 A module substitution occurs when you use a '&module-name' 8090 reference. The module-name referred to is logically 8091 substituted for the '&module-name' string. 8092 3. A relative pathname to a directory within the Repository 8093 which, when checked out, creates an image of part of the 8094 Repository structure in your current directory. 8095 Example: 8096 gnu/emacs -o /bin/emacs.helper gnu/emacs 8097 The files checked out are exactly the same as the files 8098 "checkout" would retrieve if the path weren't even in the 8099 modules file. The only reason to put this kind of relative 8100 pathname into the modules file is to hook one of the helper 8101 functions onto it. 8102 4. A relative pathname to a single file within the Repository 8103 which, when checked out, creates something you probably don't 8104 want: It creates a directory by the name of the file and puts 8105 the file in it. 8106 Example: 8107 gnu/emacs/Makefile -o /bin/emacs.helper gnu/emacs Makefile 8108 The file checked out is the same as what you would get if you 8109 handed the relative pathname to the "checkout" command. But 8110 it puts it in a strange place. The only reason to do this is 8111 to hook a helper function onto a specific file name. 8112 5. An alias consisting of a list of any of the above, including 8113 other aliases, plus exceptions. 8114 Example: 8115 my_work -a emacs !emacs/tests gnu/bison unix/bin/ls.c 8116 The exception "!emacs/test" above is functionally equivalent 8117 to specifying "!emacs/tests" on the "checkout" command line. 8118 8119 Another way to look at it is that the modules file is simply another 8120 way to "name" files. The hierarchical directory structure provides 8121 another. You should use whatever turns out to be simplest for your 8122 development group. 8123 8124 See 4G.2 for some specific ideas about how to use the modules file. 8125 8126 Last modified: _11/12/1997_ 8127 8128 12. What does "merge" mean? 8129 8130 A merge is a way of combining changes made in two independent copies 8131 of a common starting file. Checking out an RCS revision produces a 8132 file, so for the purposes of a merge "file" and "revision" are 8133 equivalent. So, we can say there are always three "files" involved in 8134 a merge: 8135 8136 The original, starting, "base" or "branch point" file. 8137 8138 A copy of the base file modified in one way. 8139 8140 Another copy of the base file modified in a different way. 8141 8142 Humans aren't very good at handling three things at once, so the 8143 terminology dealing with merges can become strained. One way to think 8144 about it is that all merges are performed by inserting the difference 8145 between a base revision and a later revision (committed by someone 8146 else) into your working file. Both the "later" revision and your 8147 working file are presumed to have started life as a copy of the "base" 8148 revision. 8149 8150 In CVS, there are three main types of "merge": 8151 8152 The "update" command automatically merges revisions committed by 8153 others into your working file. In this case, the three files involved 8154 in the merge are: 8155 8156 Base: The revision you originally checked out. Later: A revision 8157 committed onto the current branch after you checked out the Base 8158 revision. Working: Your working file. The one lying in the working 8159 directory containing changes you have made. 8160 8161 The "update -j <branch_tag> {optional files}" command merges changes 8162 made on the given branch into your working files, which is presumed to 8163 be on the Main line of development. 8164 8165 See 4C.6 8166 8167 The "update -j <rev> -j <rev> {optional files}" command merges the 8168 difference between two specified revisions into files in your working 8169 directory. The two revisions <rev> are usually on the same branch and, 8170 when updating multiple files, they are most useful when they are Tag 8171 names rather than numeric revisions. 8172 8173 See 4C.7 8174 8175 Last modified: _6/13/1997_ 8176 8177 Category: /What_is_CVS_/What_is_CVS_Whats_it/ 8178 8179 " + What is CVS? What's it for? Why CVS?" 8180 8181 1. What does CVS stand for? Can you describe it in one sentence? 8182 8183 "CVS" is an acronym for the "Concurrent Versions System". 8184 8185 CVS is a "Source Control" or "Revision Control" tool designed to keep 8186 track of source changes made by groups of developers working on the 8187 same files, allowing them to stay in sync with each other as each 8188 individual chooses. 8189 8190 Last modified: _6/13/1997_ 8191 8192 2. What is CVS for? What does it do for me? 8193 8194 CVS is used to keep track of collections of files in a shared 8195 directory called "The Repository". Each collection of files can be 8196 given a "module" name, which is used to "checkout" that collection. 8197 8198 After checkout, files can be modified (using your favorite editor), 8199 "committed" back into the Repository and compared against earlier 8200 revisions. Collections of files can be "tagged" with a symbolic name 8201 for later retrieval. 8202 8203 You can add new files, remove files you no longer want, ask for 8204 information about sets of files in three different ways, produce patch 8205 "diffs" from a base revision and merge the committed changes of other 8206 developers into your working files. 8207 8208 Last modified: _6/13/1997_ 8209 8210 3. How does CVS work? 8211 8212 CVS saves its version-control information in RCS files stored in a 8213 directory hierarchy, called the Repository, which is separate from the 8214 user's working directory. 8215 8216 Files in the Repository are stored in a format dictated by the RCS 8217 commands CVS uses to do much of its real work. RCS files are standard 8218 byte-stream files with an internal format described by keywords stored 8219 in the files themselves. 8220 8221 To begin work, you execute a "checkout" command, handing it a module 8222 name or directory path (relative to the $CVSROOT variable) you want to 8223 work on. CVS copies the latest revision of each file in the specified 8224 module or directory out of the Repository and into a directory tree 8225 created in your current directory. You may specify a particular branch 8226 to work on by symbolic name if you don't want to work on the default 8227 (main or trunk) branch. 8228 8229 You may then modify files in the new directory tree, build them into 8230 output files and test the results. When you want to make your changes 8231 available to other developers, you "commit" them back into the 8232 Repository. 8233 8234 Other developers can check out the same files at the same time. To 8235 merge the committed work of others into your working files you use the 8236 "update" command. When your merged files build and test correctly, you 8237 may commit the merged result. This method is referred to as 8238 "copy-modify-merge", which does not require locks on the source files. 8239 8240 At any time, usually at some milestone, you can "tag" the committed 8241 files, producing a symbolic name that can be handed to a future 8242 "checkout" command. A special form of "tag" produces a branch in 8243 development, as usually happens at "release" time. 8244 8245 When you no longer plan to modify or refer to your local copy of the 8246 files, they can be removed. 8247 8248 Last modified: _6/13/1997_ 8249 8250 4. What is CVS useful for? 8251 8252 CVS is intended to handle source control for files in three major 8253 situations: 8254 8255 Multiple developers working on the same files. 8256 8257 The major advantage of using CVS over the simpler tools like RCS or 8258 SCCS is that it allows multiple developers to work on the same sources 8259 at the same time. 8260 8261 The shared Repository provides a rendezvous for committed sources that 8262 allows developers a fair amount of flexibility in how often to publish 8263 (via the "commit" command) changes or include work committed by others 8264 (via the "update" command). 8265 8266 Tracking a stream of releases from a source vendor. 8267 8268 If you are making changes to sources distributed by someone else, the 8269 CVS feature, called the Vendor Branch, allows you to combine local 8270 modifications with repeated vendor releases. 8271 8272 I have found this most useful when dealing with sources from three 8273 major classes of source vendor: 8274 8275 Large companies who send you tapes full of the latest release (e.g. 8276 Unix OS vendors, database companies). 8277 8278 Public Domain software which *always* requires work. 8279 8280 Pseudo-Public sources which may require work. (e.g. GNU programs, X, 8281 CVS itself, etc.) 8282 8283 Branching development. 8284 8285 Aside from the "Vendor Branch", there are three kinds of "branches in 8286 development" that CVS can support: 8287 8288 Your working directory can be treated as a private branch. 8289 8290 A Development branch can be shared by one or more developers. 8291 8292 At release time, a branch is usually created for bug fixes. 8293 8294 (See 1D.9 and Section 4C for more info on branches.) 8295 8296 CVS's branch support is a bit primitive, but it was designed to allow 8297 you to create branches, work on them for while and merge them back 8298 into the main line of development. You should also be able to merge 8299 work performed on the main branch into the branch you are working on. 8300 Arbitrary sharing and merging between branches is not currently 8301 supported. 8302 8303 Last modified: _6/13/1997_ 8304 8305 5. What is CVS *not* useful for? 8306 8307 CVS is not a build system. 8308 8309 Though the structure of your Repository and modules file interact with 8310 your build system (e.g. a tree of Makefiles), they are essentially 8311 independent. 8312 8313 CVS does not dictate how you build anything. It merely stores files 8314 for retrieval in a tree structure you devise. 8315 8316 CVS does not dictate how to use disk space in the checked out working 8317 directories. If you require your Makefiles or build procedures to know 8318 the relative positions of everything else, you wind up requiring the 8319 entire Repository to be checked out. That's simply bad planning. 8320 8321 If you modularize your work, and construct a build system that will 8322 share files (via links, mounts, VPATH in Makefiles, etc.), you can 8323 arrange your disk usage however you like. 8324 8325 But you have to remember that *any* such system is a lot of work to 8326 construct and maintain. CVS does not address the issues involved. You 8327 must use your brain and a collection of other tools to provide a build 8328 scheme to match your plans. 8329 8330 Of course, you should use CVS to maintain the tools created to support 8331 such a build system (scripts, Makefiles, etc). 8332 8333 CVS is not a substitute for management. 8334 8335 You and your project leaders are expected to plan what you are doing. 8336 Everyone involved must be aware of schedules, merge points, branch 8337 names, release dates and the range of procedures needed to build 8338 products. (If you produce it and someone else uses it, it is a 8339 product.) CVS can't cover for a failure to manage your project. 8340 8341 CVS is an instrument for making sources dance to your tune. But you 8342 are the piper and the composer. No instrument plays itself or writes 8343 its own music. 8344 8345 CVS is not a substitute for developer communication. 8346 8347 When faced with conflicts within a single file, most developers manage 8348 to resolve them without too much effort. But a more general definition 8349 of "conflict" includes problems too difficult to solve without 8350 communication between developers. 8351 8352 CVS cannot determine when simultaneous changes within a single file, 8353 or across a whole collection of files, will logically conflict with 8354 one another. Its concept of a "conflict" is purely textual, arising 8355 when two changes to the same base file are near enough to spook the 8356 merge command into dropping conflict markers into the merged file. 8357 8358 CVS is not capable of figuring out distributed conflicts in program 8359 logic. For example, if you change the arguments to function X defined 8360 in file A and, at the same time, edit file B, adding new calls to 8361 function X using the old arguments. You are outside the realm of CVS's 8362 competence. 8363 8364 Acquire the habit of reading specs and talking to your peers. 8365 8366 CVS is not a configuration management system. 8367 8368 CVS is a source control system. The phrase "configuration management" 8369 is a marketing term, not an industry-recognized set of functions. 8370 8371 A true "configuration management system" would contain elements of the 8372 following: 8373 8374 * Source control. 8375 * Dependency tracking. 8376 * Build systems (i.e. What to build and how to find 8377 things during a build. What is shared? What is local?) 8378 * Bug tracking. 8379 * Automated Testing procedures. 8380 * Release Engineering documentation and procedures. 8381 * Tape Construction. 8382 * Customer Installation. 8383 * A way for users to run different versions of the same 8384 software on the same host at the same time. 8385 8386 CVS provides only the first. 8387 8388 Last modified: _6/13/1997_ 8389 8390 Category: /What_is_CVS_/Where_do_I_find_CVS_/ 8391 8392 " + Where do I find CVS? Where can I find Help?" 8393 8394 1. How do I get more information about CVS? 8395 8396 The first thing I would do is to read the Info file that comes with 8397 the CVS sources under "doc". You can format and read the cvs.texinfo 8398 file in two ways: 1. Use TeX to format it and a "dvips" command to 8399 print it and 2. Install the cvs.info files that are created by the 8400 Makefile and read them online using the Emacs "info-mode" or a 8401 stand-alone "info" reader. 8402 8403 Then I'd run "cvsinit" to set up a Repository and read the man page 8404 while trying out the commands. 8405 8406 Type "cvs -H" for general help or "cvs -H command" for 8407 command-specific help. 8408 8409 For background, you can read the original CVS paper (in the source 8410 tree, under "doc"). It describes the purpose of CVS and some of how it 8411 was designed. Note that the emphasis of the document (especially on 8412 multiple vendors providing the same sources) is somewhat out of date. 8413 8414 For more detailed information about "internals", read the man pages 8415 for RCS. If you are a programmer, you can also read the source code to 8416 CVS. 8417 8418 Other information and tutorials may be available in the "doc" 8419 directory of the FTP archive described below. 8420 8421 For current information, and a fair amount of detail, join the 8422 info-cvs mailing list described below. 8423 8424 Last modified: _6/13/1997_ 8425 8426 2. Is there an archive of CVS material? 8427 8428 An anonymous FTP area has been set up. It contains many of the CVS 8429 files you might want, including extra documentation, patches and a 8430 copy of the latest release. 8431 8432 ftp ftp.delos.com 8433 >>> User: anonymous 8434 >>> Passwd: 8435 cd /pub/cvs 8436 get README 8437 get Index 8438 8439 The README has more (and more up-to-date) information. The Index 8440 contains a terse list of what is in the archive. 8441 8442 A WWW home page is also available at http://www.delos.com/cvs. 8443 8444 This Didn't Exist 6/23/1998 8445 8446 Last modified: _6/24/1998_ 8447 8448 3. How do I get files out of the archive if I don't have FTP? 8449 8450 Use one of the FTP<->Email servers. These are the ones I've been told 8451 about: 8452 8453 FTPMAIL service is available from the same host as the FTP server 8454 described above. Send mail to "ftpmail@delos.com" containing "help" in 8455 the body of the message. For example, on most Unix systems, you can 8456 type: 8457 8458 echo help | Mail ftpmail@delos.com 8459 8460 The FTPMAIL server will respond with a document describing how to use 8461 the server. If the "Mail" command doesn't exist on your system, try 8462 "mailx", "/usr/ucb/mail" or "/bin/mail". 8463 8464 If you are on BITNET, use Princeton's BITFTP server. Type 8465 8466 echo 'send help' | Mail bitftp@pucc.princeton.edu 8467 8468 (It is likely that only BITNET addresses can use this one.) 8469 8470 Other possibilities I've heard of from the net: (Try the one closest 8471 to you.) 8472 8473 ftpmail@decwrl.dec.com ftpmail@sunsite.unc.edu ftpmail@cs.arizona.edu 8474 ftpmail@cs.uow.edu.au ftpmail@doc.ic.ac.uk 8475 8476 Last modified: _6/13/1997_ 8477 8478 4. How do I get a copy of the latest version of CVS? 8479 8480 The latest released version of CVS and all the programs it depends on 8481 should be available through anonymous FTP on any FSF archive. The main 8482 FSF archive is at "prep.ai.mit.edu". There are mirrors of the FSF 8483 archive on UUNET and other large Internet sites. 8484 8485 Program(s) Suggested revision 8486 ----------- ----------------------- 8487 CVS 1.5 8488 RCS 5.7 (latest version available today) 8489 GNU diff 2.7 (or later) [contained in diffutils-2.7] 8490 GDBM 1.5 (or later) [optional] 8491 8492 The GNU version of diff is suggested by both the RCS and CVS 8493 configuration instructions because it works better than the standard 8494 version. 8495 8496 It is a good idea not to accept the versions of CVS, RCS or diff you 8497 find lying on your system unless you have checked out their 8498 provenance. Using inconsistent collections of tools can cause you more 8499 trouble than you can probably afford. 8500 8501 The FTP archive mentioned above should contain the latest official 8502 release of CVS, some official and unofficial patches and possibly 8503 complete patched versions of CVS in use somewhere. 8504 8505 Last modified: _6/13/1997_ 8506 8507 5. Is there a mailing list devoted to CVS? How do I find it? 8508 8509 An Internet mailing list named "info-cvs" grew out of the private 8510 mailing list used by the CVS 1.3 alpha testers in early 1992. 8511 Throughout 1994, the list received an average of 100 messages per 8512 month. 8513 8514 You can add yourself to the mailing list by sending an Email message 8515 to: 8516 8517 info-cvs-request@prep.ai.mit.edu 8518 8519 (Don't forget the "-request" or you'll send a message to the whole 8520 list, some of whom are capable of remote execution.) 8521 8522 Mail to the whole list should be sent to: 8523 8524 info-cvs@prep.ai.mit.edu 8525 8526 An archive of the mailing list is maintained in the FTP archive 8527 mentioned above. 8528 8529 Last modified: _6/13/1997_ 8530 8531 6. What happened to the CVS Usenet newsgroup I heard about? 8532 8533 8534 A Usenet newsgroup named "gnu.cvs.info" was announced in April 8535 1993, with an expected creation date of August, 1993. However, 8536 nothing came of this. 8537 8538 If you want to discuss CVS on usenet, the correct group is 8539 comp.software.config-mgmt (which also covers other configuration 8540 management systems). Someday it might be possible to create a 8541 comp.software.config-mgmt.cvs, but only if there is sufficient 8542 CVS traffic on comp.software.config-mgmt. 8543 8544 kingdon@cyclic.com 8545 8546 Last modified: _9/6/1997_ 8547 _________________________________________________________________ 8548 8549 [Add an answer to this category] 8550 8551 [Category /] 8552 _________________________________________________________________ 8553 8554 _Search the FAQ-O-Matic:_ ____________________ Search 8555 [matching all words] 8556 Or look for questions modified in the last: [7.] Days 8557 _________________________________________________________________ 8558 8559 The FAQ-O-Matic lives at http://gille.loria.fr:7000/cgi-bin/faqomatic. 8560 The code was written by Jon Howell, and the content by folks from all 8561 over the web. 8562 _________________________________________________________________ 8563