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