/contrib/cvs/FAQ
#! | 8562 lines | 5961 code | 2601 blank | 0 comment | 0 complexity | e7f68e8ccfbae0343c7cab0e4a374579 MD5 | raw file
Large files files are truncated, but you can click here to view the full file
1------------------------------------------------------------------------------- 2 3 CVS is Copyright (C) 1986-2006 The Free Software Foundation, Inc. 4 5 CVS is free software; you can redistribute it and/or modify 6 it under the terms of the GNU General Public License as published by 7 the Free Software Foundation; either version 1, or (at your option) 8 any later version. 9 10 More details are available in the COPYING file but, in simplified 11 terms, this means that any distributed modifications you make to 12 this software must also be released under the GNU General Public 13 License. 14 15 CVS is distributed in the hope that it will be useful, 16 but WITHOUT ANY WARRANTY; without even the implied warranty of 17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 GNU General Public License for more details. 19 20------------------------------------------------------------------------------- 21 22This file contains a CVS FAQ. Until 1995 it was maintained by David 23Grubbs. It was out of date and not being maintained, but it had a 24certain following and in 1997 Pascal Molli decided to start 25maintaining it with the FAQ-O-Matic package which allows any 26contributor with a web browser to help maintain it. The following 27text is (mostly automatically) extracted from the FAQ-O-Matic. The 28odds are good that the file that you are currently reading is out of 29date with respect to the online FAQ-O-Matic, which is part of Pascal 30Molli's CVS web site at http://www.loria.fr/~molli/cvs-index.html 31(currently under "Documentation"). The online version is also 32somewhat better in terms of things like tables of contents (at least 33until someone can write some code to extract data from a FAQ-O-Matic 34and insert things like tables of contents). 35 36The answers which are dated "6/13/1997" below are really from the 1995 37FAQ, for the most part. Many of them are out of date. The current FAQ may 38be found at <http://ximbiot.com/cvs/wiki/index.php?title=CVS_FAQ>. If you have 39some time, you are encouraged to export that FAQ as text and import it here. 40If you don't have such time, take the answers in this file with at least a few 41grains of salt. 42 43Since August, 2005, many of the existing CVS resources have been centralized on 44<http://cvs.nongnu.org> & <http://ximbiot.com>. 45 46 Category: /, all questions 47 48 Category: / 49 50 " [INLINE] " 51 52 1. About FAQ-O-Matic 53 54This is FAQ-O-Matic, a quick-and-dirty Perl hack (aren't they all?) by 55Jon Howell. 56 57It seems like most FAQ maintainers make a valiant initial effort, then get 58a life and don't have time to keep their FAQs up to date. Also, I often 59find out a solution to a problem, and feel like I could write a single 60FAQ answer on it in a few minutes, but where to post it? 61 62Thus the FAQ-O-Matic was born. FAQ-O-Matic is a couple sleazy Perl scripts 63that allow people to submit FAQ answers to this database, so it can stay 64current, with just a tiny bit of work on any one person's part. 65 66Yes, a bad guy could come along and wipe out all the FAQ entries. Please don't. 67But to give the good guys some measure of comfort, each submission is stored 68in an RCS file, so if someone does tamper, we can recover the database. 69 70Guidelines for submissions: 71 721. Please _try to be fairly unbiased in matters of opinion._ Mailing lists are 73the place to start flame wars (just kidding :v), but definitely not here. 74 752. Please _use HTML only conservatively_ in your entries. Links are appropriate 76, 77but put the URL in the plaintext also so it's useable on printed versions of 78the FAQ. Inline images pointing off this site are inappropriate, as is much 79fancy formatting. This is meant to be bandwidth-light and dumb-browser-friendly 80. 81 823. If you feel there's a place for a _new category, or a reorganization of 83existing questions_, don't hesitate to mail me (molli@loria.fr). 84Category changes need to be done from my end. 85 864. Please _leave an email address_ at the bottom of your submission so that oth 87ers 88can drop you a note. 89 905. _If you only have a question_, not an answer, you should probably post 91it to a mailing list, not here. If there are frequently asked questions to whic 92h 93the answer is not forthcoming on mailing lists (or perhaps there's no 94useful answer yet other than "no one knows"), then it's appropriate to 95post here, in hopes that someone will see it and know the answer. 96 976. Please refrain from crude or inconsiderate language. Please don't use 98this as a forum for advertising. However, mention of worthy commercial 99products is certainly appropriate (even if you sell said product). Just 100don't overdo it. :v) 101 102 Last modified: _6/13/1997_ 103 104 2. Adding a new category ? 105 106just send me a mail at 107molli@loria.fr 108 109 Last modified: _6/13/1997_ 110 111 Category: /Advanced_Topics_/ 112 113 " Advanced Topics " 114 115 Category: /Advanced_Topics_/Branching_and_Mergin/ 116 117 " + Branching and Merging" 118 119 1. What is a branch? 120 121 Unfortunately, the word "branch" is an overloaded technical 122 term. It is used in too many different ways in three 123 categories. It might help to understand some of the issues by 124 going through the categories: 125 126 How Humans use the word "branch": 127 128 Most development starts with everyone working on the same 129 software, making changes and heading toward a single goal. This 130 is called something like "Main Line Development". Note that 131 though many people do main line development on CVS's "Main 132 Branch", that is a choice, not a requirement. 133 134 After a release or when one or more developers want to go off 135 and work on some project for a while, the Software Engineers 136 assigned to deal with large software issues generate a "Branch 137 in Development" to support the release or project. (Keep in 138 mind that a programmer is no more a Software Engineer than a 139 carpenter is a Civil Engineer.) 140 141 Essentially, the word "branch" implies a way to allow 142 simultaneous development on the same files by multiple people. 143 144 The above terms are human-oriented. They refer to actions that 145 people would like to take. They do *not* imply any particular 146 implementation or set of procedures. Branches in development 147 can be supported in many different ways. 148 149 How CVS uses the word "branch": 150 151 CVS uses the word "branch" in a number of ways. The two most 152 important are: 153 154 - The vendor branch holds releases from (normally) an outside 155 software vendor. It is implemented using a specific RCS branch 156 (i.e. 1.1.1). 157 158 - The "Main Branch", which normally holds your "Main Line 159 Development", but is defined as the collection of revisions you 160 get when you "checkout" something fresh, or when you use the 161 '-A' option to "update". 162 163 Important Note: The CVS "Main Branch" is *not* the same as the 164 RCS concept with the same name. If you are using Vendor 165 Branches, files you have never changed are on three branches at 166 the same time: 167 168 - The RCS 1.1.1 branch. 169 - The CVS Vendor branch. 170 - The CVS "Main Branch". 171 172 The concepts overlap, but they are not equivalent. 173 174 In referring to CVS, "branch" can be used in four other ways: 175 176 - A CVS working directory satisfies the definition of "branch" 177 for a single developer -- you are on a private "virtual branch" 178 that does not appear in any of the RCS files or the CVS control 179 files. 180 181 - The CVS "default branch" is the Repository source for the 182 collection of files in your working directory. It is *not* the 183 same as the RCS "default branch". Normally the CVS default 184 branch is the same as the CVS Main branch. If you use the "-r 185 <branch_tag>" option to the "checkout" command, you will record 186 a "sticky" tag that changes your default branch to the one you 187 checked out. 188 189 - A "magic" branch can be a branch that hasn't happened yet. It 190 is implemented by a special tag you can check out that is not 191 attached to a real RCS branch. When you commit a file to a 192 magic branch, the branch becomes real (i.e. a physical RCS 193 branch). 194 195 - And, of course, CVS uses "branch" to indicate a 196 human-oriented "branch in development". 197 198 How RCS uses the word "branch": 199 200 - The RCS "Main Branch" (Synonym: "The Trunk") contains a 201 series of two-part revision numbers separated by a single '.' 202 (e.g. 1.2). It is treated specially and is the initial default 203 branch. (The default default?) 204 205 - The RCS "Default" branch starts out attached to the RCS "Main 206 Branch". For RCS purposes, it can be changed to point to any 207 branch. Within CVS, you *must*not* alter the RCS default 208 branch. It is used to support the CVS idea of a "Main Branch" 209 and it must either point to the RCS Main Branch, or the Vendor 210 Branch (1.1.1) if you haven't made any changes to the file 211 since you executed "import". 212 213 Last modified: _6/13/1997_ 214 215 2. Why (or when) would I want to create a branch? 216 217 Remember that you can think of your working directory as a "branch for 218 one". You can consider yourself to be on a branch all the time because 219 you can work without interfering with others until your project (big 220 or small) is done. 221 222 The four major situations when you should create a branch: 223 224 When you expect to take a long time or make a large set of changes 225 that the merging process will be difficult. Both "long" and "large" 226 are defined in your own environment. 227 228 When you want to be able to "commit" and "tag" your work repeatedly 229 without affecting others. 230 231 If you ever think you need Source Control for your own work, but don't 232 want your changes to affect others, create a private branch. (Put your 233 username in the branch tag, to make it obvious that it is private.) 234 235 When you need to share code among a group of developers, but not the 236 whole development organization working on the files. 237 238 Rather than trying to share a working directory, you can move onto a 239 branch and share your work with others by "committing" your work onto 240 the branch. Developers not working on the branch won't see your work 241 unless they switch to your branch or explicitly merge your branch into 242 theirs. 243 244 When you need to make minor changes to a released system. 245 246 Normally a "release" is labeled by a branch tag, allowing later work 247 on the released files. If the release is labeled by a non-branch tag, 248 it is easy to add a branch tag to a previously tagged module with the 249 "rtag" command. If the release is not tagged, you made a mistake. 250 Recovery requires identifying all revisions involved in the release 251 and adding a tag to them. 252 253 Last modified: _6/13/1997_ 254 255 3. How do I create and checkout a branch? 256 257 Suggested technique: 258 259 Attach a non-branch tag to all the revisions you want to branch 260 from. (i.e. the branch point revisions) 261 262 When you decide you really need a branch, attach a branch tag to the 263 same revisions marked by the non-branch tag. 264 265 "Checkout" or "update" your working directory onto the branch. 266 267 Suggested procedure when using modules: 268 269 cvs rtag <branch_point_tag> module 270 271 cvs rtag -b -r <branch_point_tag> <branch_tag> <module> 272 273 cvs checkout -r <branch_tag> module 274 275 Suggested procedure when using your working directory, which 276 contains the revisions of your working files you want to branch from: 277 278 cvs tag <branch_point_tag> 279 280 cvs rtag -b -r <branch_point_tag> <branch_tag> <module> 281 282 cvs update -r <branch_tag> 283 284 In each procedure above, Step #1 applies a non-branch tag to all the 285 branch point revisions in the module/directory. Though this is not 286 strictly necessary, if you don't add a non-branch tag to the revisions 287 you branch from, you won't be able to refer to the branch point in the 288 future. 289 290 Between steps 1 & 2 you may commit changes. The result would be same 291 because "rtag -r <oldtag> <newtag>" applies <newtag> to the same 292 revision that <oldtag> is attached to. You can use this technique to 293 avoid attaching *any* branch tags until you need them. 294 295 Step B.2 has two corollaries: 296 297 If you plan to create the branch tag before committing anything in 298 your working directory, you can use "cvs tag -b <branch_tag>" instead 299 of the "rtag" command. 300 301 The <module> can be a relative path to a directory from which your 302 working directory was checked out. 303 304 If you have trouble figuring out what <module> to use (or pathname to 305 use in its place), you can aim it at whatever parent directories you 306 believe will cover all your work. 307 308 If you are sure the <branch_tag> is not being used anywhere else, you 309 can even aim it at the whole Repository ($CVSROOT), if you have to. It 310 might take some extra time, but assuming that your <tag> is a unique 311 string and you don't use the '-f' option to "rtag -r", "rtag" will 312 only add a <tag> to files in which it actually *finds* the earlier 313 <tag>. 314 315 In each procedure above, Step #3 may occur any time after step 2. 316 Unless you explicitly remove them with "tag -d", a <tag> is permanent. 317 318 The <branch_tag> is an unusual creature. It labels a branch in a way 319 that allows you to "checkout" the branch, to "commit" files to the end 320 of the branch and to refer to the end of the branch. It does not label 321 the base of the branch (the branch point). 322 323 There are two obvious ways to choose the <branch_point_tag> and 324 <branch_tag> names. But keep in mind that the <branch_tag> is typed by 325 any developer who wants to work on the branch -- you should make it 326 mean something to them. 327 328 Style #1 presumes that the simple version string refers to a set of 329 designed, documented or promised features, not to a specific set of 330 files. In this case, you tag the branch with the generic Version 331 string and assume that whenever you refer to "Version", you want the 332 "latest" set of files associated with that Version, including all 333 patches. (You can substitute whatever you like for "bp_", as long as 334 your <branch_point_tag> is some modification of the <branch_tag>.) 335 336 <branch_point_tag> Matching <branch_tag> 337 338 bp_V1_3 V1_3 339 bp_Release2-3-5 Release2-3-5 340 bp_Production4_5 Release4_5 341 342 Style #2 presumes that the simple version string refers to the 343 specific set of files used to construct the first release of 344 "version". In this case, you tag the branch-point revisions with the 345 generic Version string and assume that whenever you refer to this 346 Version, you want the original set of released revisions. To get the 347 latest patched revisions of the release, you refer to the branch tag 348 "latest_<branch_point_tag>". (You can substitute what ever you like 349 for "latest_", as long as your <branch_tag> is some modification of 350 the <branch_point_tag>.) 351 352 <branch_point_tag> Matching <branch_tag> 353 354 V1_3 latest_V1_3 355 Release2-3-5 latest_Release2-3-5 356 Release4_5 latest_Production4_5 357 358 In both styles you can find out what you had to change since the 359 original release of this Version by typing: 360 361 cvs diff -r <branch_point_tag> -r <branch_tag> 362 363 For Style 1, this is: 364 365 cvs diff -r bp_<branch_tag> -r <branch_tag> 366 367 For Style 2, this is: 368 369 cvs diff -r <branch_point_tag> -r latest_<branch_point_tag> 370 371 Notes on "being on a branch": 372 373 - "update -r <tag>" tells CVS to attach a "sticky tag" to working 374 directory (in ./CVS/Tag) and the checked-out files (on each line of 375 ./CVS/Entries). 376 377 - A "sticky" <tag> (including a <branch_tag>) causes most CVS commands 378 to act as if "-r <tag>" were on the command line. 379 380 - A "sticky" <branch_tag> indicates that the working directory (and 381 working files) are "on the branch". 382 383 Last modified: _6/13/1997_ 384 385 4. Once created, how do I manage a branch? 386 387 The most important thing you should know about managing a branch is 388 that the creation of a branch is not a lightweight act. When you 389 create a branch, you must also create a set of procedures to keep 390 track of it. 391 392 Specifically, you must: 393 394 - Remember that the branch exists. (This is non-trivial if you create 395 a lot of them.) 396 397 - Plan when to merge it back into the main line of development. 398 399 - Schedule the order that multiple branch merges are to be done. 400 401 - If you ever intend to merge branches into each other, instead of 402 limiting merges of branch work back into the "main line", you must 403 keep careful track of which parts of which branches have merged into 404 which other branches. 405 406 The simplest way to deal with branches is to limit their number, 407 "collapse" them back into the main line as quickly as is reasonable 408 and forget them. If a group wants to continue working, tell them to 409 create another branch off the fully merged main line. 410 411 Remember that CVS is just a tool. Over time, it will probably handle 412 branching better, requiring less careful attendance. But no matter how 413 good it becomes, the whole idea of "branching" is a complicated 414 management problem. Don't take it lightly. 415 416 Last modified: _6/13/1997_ 417 418 5. Are there any extra issues in managing multiple branches? 419 420 If you plan to split from the "main line" and merge back after a time, 421 the only problem will be scheduling the order of branch merges. As 422 each branch is merged, the main line must be rebuilt and tested. 423 Merging multiple branches (i.e. "lines of development") before 424 building and testing creates more problems than you are ready for. 425 426 If you plan to collapse some branches into others, then move the 427 combined branches back into the main line, you have to be careful with 428 the revisions and tags you hand to your "update -j" command, but it 429 shouldn't be much trouble. 430 431 If you plan to allow every branch to incrementally take the work done 432 on other branches, you are creating an almost insurmountable 433 bookkeeping problem. Every developer will say "Hey, I can handle 434 taking just this little bit," but for the system as a whole it is 435 disaster. Try it once and see. If you are forced into this situation, 436 you will need to keep track of the beginning and end points of every 437 merge ever done. Good Luck. 438 439 Last modified: _6/13/1997_ 440 441 6. How do I merge a whole branch back into the trunk? 442 443 If you don't have a working directory, you can checkout and merge in 444 one command: 445 446 cvs checkout -j <branch_tag> <module> 447 cd <module> 448 449 If you already have a working directory: 450 451 cd <working_directory> 452 cvs update <== Optional, to bring it up to date. 453 cvs update -j <branch_tag> 454 455 CVS will print lines beginning with 456 457 'U' for files that you hadn't changed, but the branch did. 458 459 'M' for files that you changed and the branch didn't 460 *and* for files that you both changed that were merged 461 without overlaps. (This overload is unfortunate.) 462 463 'C' for files that you both changed in a way that conflicts 464 with each other. 465 466 You need to go edit all the 'C' files and clean up the conflicts. Then 467 you must commit them. 468 469 Last modified: _6/13/1997_ 470 471 7. How do I merge changes from the trunk into my branch or between 472 branches? 473 474 The idea is similar to the above, but since CVS doesn't treat the main 475 branch like other branches, you'll have to be more careful. There are 476 5 different ways to look at the problem. 477 478 The way to merge *all* changes made on the trunk into a working 479 branch is to move to the branch you want via "checkout -r" or "update 480 -r": 481 482 cvs update -r <branch_tag> {optional files} 483 484 Then merge the changes from the trunk into your working branch using 485 the pseudo-tag named "HEAD": 486 487 cvs up -j HEAD {optional files} 488 489 You will get everything from the branch point of the branch named 490 <branch_tag> up to the HEAD of the main branch. This is still kind of 491 strange. If the file is on a branch, HEAD should be the latest thing 492 on the branch, not the HEAD of MAIN. But that's not the way CVS 493 (currently) works. 494 495 If you run "cvs up -j HEAD" again after adding more revisions to the 496 trunk, you may get overlaps for the text you have already merged. It 497 depends on your version of your RCS "merge" command (actually the "co 498 -j" option, which depends on the version of "diff3" you configured RCS 499 to use). 500 501 You can merge the difference between any two <tags> using two "-j" 502 options on "update" or "checkout". 503 504 Identify the two tags on the branch you want to merge from. 505 506 cvs update -j <tag1> -j <tag2> {optional files} 507 508 This step assumes you were careful about tagging milestones. You can 509 use this technique for any two <tags> on the same branch, even the 510 trunk. It is also possible to use tags on different branches, but 511 you'll have to ponder the meaning of the difference between those two 512 tags. 513 514 In place of one of the <tags>, you can use a <branch_tag> to refer to 515 the latest revision on that branch. See 4C.11 and 4C.3 for info on 516 branch points. 517 518 Merges can also be performed by handing RCS revisions to the '-j' 519 options, but since revision numbers aren't the same in all files, 520 merging by number is normally limited to one file. Sets of files with 521 the exact same trees of branches and revision numbers would work too, 522 but that's a rare situation. 523 524 To "take" revisions from other branches instead of merging them, see 525 4C.19 for an idea. 526 527 A way to gain the effect of merging the main to the branch is to 528 merge the branch into the main using the normal 529 530 cvs update -A {optional files} 531 cvs update -j <branch_tag> {optional files} 532 cvs commit 533 cvs tag -F -b <same_branch_tag> {optional files} 534 535 See part B of 4D.5 536 537 Other oddities. 538 539 This also works, but is probably not officially supported: 540 541 cvs update -j N {optional files} 542 543 where N is a number. This will merge all the changes from the branch 544 point up to the highest revision on the main branch starting with N. 545 For example, if your highest trunk revision is 1.52, you can use this 546 to grab revisions from the trunk: 547 548 cvs update -j 1 {optional files} 549 550 Another example: Say you have a branch point at rev 1.2 for a branch 551 named "BR1" and trunk revisions 1.3, 1.4, 2.1, 2.2, 2.3, 3.1, 3.2. 552 Then: 553 554 cvs update -j 1 {optional files} 555 556 will merge the changes from 1.2 to 1.4 557 558 cvs update -j 2 {optional files} 559 560 will merge the changes from 1.2 to 2.3 561 562 cvs update -j 3 {optional files} 563 564 will merge the changes from 1.2 to 3.2, which in this example, is 565 equivalent to the use of "-j HEAD" in part A above. 566 567 The intuitive (at least to me): 568 569 cvs up -j MAIN (or TRUNK) {optional files} 570 571 doesn't work. If the trunk (i.e. "main branch") had an implicit branch 572 named "MAIN", you could use: 573 574 cvs up -j MAIN:10/26 -j MAIN:now {optional files} 575 576 and refer to date-stamped revisions on the trunk using the 577 <branch_tag>:<date> support that works on other branches. 578 579 You might also think you could place an explicit tag on branch 1 (or 580 higher) (e.g. MAINHACK:1) and use it in place of the implicit "MAIN", 581 but I haven't found the right combination. 582 583 [[If you find working techniques, I'll add them here.]] 584 585 Last modified: _6/13/1997_ 586 587 8. How do I merge onto the Main Branch a file that exists only on a branch 588 other than the Main Branch? (i.e. it is in the Attic) 589 590 For how such a file can exist, see 3A.2 and 3A.3. 591 592 For how to avoid creating such a file, see 3A.5. 593 594 Though you might think that the "update -j" command could perform the 595 "merge" of a file from the side branch to the Main Branch, it isn't 596 (yet) smart enough. Unfortunately, there is no single CVS command to 597 do this -- it takes three steps: 598 599 To move something onto the Main Branch from the Attic, you have to 600 physically move the file from the Attic to the main Repository 601 directory associated with your working directory. 602 603 It is exactly like resurrecting a removed file. See 3L.4 604 605 I use something like this: (csh-like syntax) 606 607 set repos = `cat ./CVS/Repository` mv $repos/Attic/filename,v 608 $repos/filename,v 609 610 (If you use relative paths in your Repository files, that first line 611 becomes: set repos = $CVSROOT/`cat ./CVS/Repository`) 612 613 Now that the file is physically in the right place within the 614 Repository, "update -A" will make it appear in your working directory 615 on the Main Branch. Do that now. 616 617 You now have a choice. The act of physically moving the file has 618 fused together the <branch_tag> branch and the Main Branch for this 619 file. You can continue that way, making changes along the RCS Main 620 Branch which CVS will (for this type of file only) treat as both the 621 Main Branch and the <branch_tag> branch. 622 623 The other choice, which I would suggest, is to re-tag the file with 624 <branch_tag>, restoring a normal-looking magic branch tag to the file: 625 626 cvs tag -F -b <branch_tag> <file> 627 628 After you have done the above, you can run "update -A" or "update -r 629 <branch_tag>" to resume whatever you were doing before you started 630 this procedure. 631 632 Caveat: The final result is a file whose revision tree doesn't look 633 like it was ever on any branch but the Main Branch until the above 634 "tag -F -b" command was executed. CVS and RCS have no way of saving 635 the history of the actions you have just performed. 636 637 Last modified: _6/13/1997_ 638 639 9. How do I know what branch I'm (working) on? 640 641 Type: 642 cvs status 643 644 and look at the "Sticky Tag" field for each file. If: 645 646 The *same* tag is on *every* file in your working tree, *and* 647 648 That tag matches the contents of the ./CVS/Tag file, *and* 649 650 That tag is a branch tag, 651 652 then you know what branch you are working on. You can get sticky Tag 653 information directly from the ./CVS/Entries file instead of "cvs 654 status". 655 656 If all the sticky Tags don't agree, then your directory is temporarily 657 inconsistent. This is a feature allowing you to make changes (or 658 perform merges) to individual files on multiple branches without 659 checking out the whole directory. 660 661 The sticky Tag on each file in the ./CVS/Entries file (as displayed by 662 the "status" command) indicates what branch the working file is on. 663 New files are added to the Tag stored in ./CVS/Tag. 664 665 To force your entire working directory onto the same branch, type: 666 667 cvs update -r <branch_tag> 668 669 Last modified: _6/13/1997_ 670 671 10. Do I really have to know the name of the branch I'm working on? 672 673 If a developer can't be relied on to know what branch of development 674 to work on, then either the developer's manager isn't planning 675 branches properly or the developer has serious problems. 676 677 I have found that one of the hardest concepts to get across to 678 developers (and some managers) is that "a branch in development" (as 679 opposed to the use of RCS branches to support some other scheme) is a 680 heavyweight act. Every time you create a real branch in development, 681 you must spawn a set of managerial procedures and a schedule by which 682 you plan to merge each branch into each other branch. Unless you plan 683 to keep it simple and collapse (by merging and forgetting) branches 684 quickly, they are not to be created lightly. 685 686 In other words, if you don't regularly attend group meetings in which 687 the branch to be worked on is a major topic of discussion, then the 688 group is not managing branches properly. 689 690 We created a couple major branches a few months ago and even the 691 customer service people refer to the "XYZ branch" as a shorthand for 692 "continuing development on the XYZ project". 693 694 Last modified: _6/13/1997_ 695 696 11. How do I refer to the revision where I branched so I can see what 697 changed since the Branch Point on another branch? 698 699 Given the current <branch_tag> format, there is no direct way to refer 700 to the branch point, which is more useful in many ways than referring 701 to the branch, which always refers to the latest revision on the 702 branch. 703 704 When CVS adds a branch tag, it attaches an RCS symbol to a 705 non-existent revision number containing the revision number of the 706 branch point as a prefix. (See Section 3O, on the "tag" command.) RCS 707 can't use the CVS magic branch tag and many of the CVS commands can't 708 refer to it. 709 710 To be certain of your ability to refer to a branch point, you must 711 create a "branch point" tag at the same time as the Branch tag. See 712 4C.3. 713 714 Last modified: _6/13/1997_ 715 716 12. Why didn't the command "cvs admin -bBRANCH1 *" create a branch? 717 718 Because your command creates an RCS branch, not a CVS branch. See the 719 above discussion on branches. RCS branches are used to support CVS 720 branches, but they are not the same. You can't act as if you have 721 direct control over the RCS files. 722 723 The "admin" command was placed there as a convenience to allow you to 724 execute raw "rcs" commands on the Repository, taking advantage of 725 CVS's ability to find the files in the Repository. 726 727 But you have to remember that you are using RCS commands on a CVS 728 Repository, which is not generally safe unless you know exactly what 729 CVS depends on. 730 731 For one thing, CVS insists on control of the default branch. It is set 732 either to the Main branch or the Vendor branch depending on whether 733 you have changed the Vendor's code. If you change the default branch, 734 you are monkeying with the internals and you will get unexpected 735 results. 736 737 To set your "default CVS branch" to BRANCH1, you must use "checkout" 738 or "update" with the "-r BRANCH1" option. Then you have changed CVS's 739 idea of your "default branch", which has little to do with RCS's 740 default branch. 741 742 Last modified: _6/13/1997_ 743 744 13. Is it possible to set the "default CVS branch" for everyone? 745 746 No. It doesn't work that way. 747 748 When using CVS, all administrative information (such as what branch 749 you checked out) is stored in CVS sub-directories, local to the user. 750 There is no global state, other than the description and logging files 751 in the $CVSROOT/CVSROOT directory. 752 753 You tell "checkout" or "update" what branch you want to check out via 754 the "-r <tag>" option. The default is CVS's "Main Branch". 755 756 I don't see a problem in *designing* a new way to indicate what branch 757 you get by default, instead of the main one, but that's not how it 758 currently works. 759 760 Last modified: _6/13/1997_ 761 762 14. How do I perform a large merge? 763 764 Large merges require a bit more planning to be able to track what has 765 happened in the inevitable cases where something goes wrong. No tool 766 can force a "merge" to make perfect sense. 767 768 Though you can handle the details in many different ways, the two ends 769 of the spectrum of merge techniques are: gonzo and paranoid. 770 771 The gonzo method assumes that you know everything about your sources 772 so that recovery from failures is "just a matter of typing." You 773 created the branch this way: 774 775 cvs checkout <module> 776 cd <module> 777 cvs tag -b <branch_tag> 778 cvs update -r <branch_tag> 779 >>> Edit away. 780 cvs commit <<== Onto branch 781 782 Now you want to merge your branch back into the Main branch, you are 783 certain you can make it work, or at least detect all the failures, so 784 you dive in and hack away: (For simplicity, we will assume you are 785 collapsing (i.e. merging and forgetting) a side-branch into the Main 786 branch from your single working directory.) 787 788 cvs update -A 789 cvs update -j <branch_tag> 790 >>> Edit the 'C' files and remove the overlaps. 791 >>> Edit some more to make it all compile and work. 792 cvs commit 793 794 Looks simple. For more details on the output from the "update -j" 795 command, see 3P.2 and 4C.6. 796 797 Note: You could also checkout a whole new working directory and 798 perform the merge at the same time by replacing the two 799 update commands with these two commands: 800 801 cvs checkout -j <branch_tag> <module> 802 cd <module> 803 804 The paranoid way is more difficult, but it can catch all sorts of 805 problems. You created the branch this way: 806 807 cvs checkout <module> 808 cd <module> 809 cvs tag <branch_point_tag> 810 cvs tag -b <branch_tag> 811 cvs update -r <branch_tag> 812 >>> Edit away. 813 cvs commit <<== Onto branch 814 815 The extra tag command places a non-branch tag on the Branch Point, an 816 act that makes it easier to do "diffs" later. Now we decide to perform 817 the merge: 818 819 cvs tag <latest_on_branch_tag> 820 cvs update -A 821 *1* cvs diff -r <branch_point_tag> -r <latest_on_branch_tag> 822 >>> *1* shows all the changes on the branch. 823 *2* cvs diff -r <branch_point_tag> -r HEAD 824 >>> *2* shows the changes on the trunk since branching. 825 cvs tag <premerge_tag> 826 cvs update -j <branch_tag> 827 >>> Edit the 'C' files and remove the overlaps. 828 *3* cvs diff 829 >>> Verify that *3* matches *1*, except for line numbers. 830 cvs commit 831 cvs tag <just_merge_changes_tag> 832 >>> Edit some more to make it all compile and work. 833 cvs commit 834 cvs tag <after_merge_cleanup_tag> 835 836 The reason *3* and *1* match so closely is that they are the 837 differences between two pairs of starting points and ending points 838 after the same data was inserted. If they are significantly different, 839 you will want to figure out why. 840 841 NOTE: You will have to tell everyone to stay the hell out of the 842 Repository while you do this. If they commit something while you are 843 in the middle of a merge, your job will be much more difficult. If 844 they "update" at the wrong time, their work will be randomized until 845 you finish. It's better to call a halt. 846 847 See 3H.13 for some more information about dealing with merges after 848 import. The last part of the procedure is applicable to any large 849 merge. 850 851 Last modified: _6/13/1997_ 852 853 15. Is a Vendor merge any different from a branch merge? 854 855 No. In most ways, a Vendor branch is exactly the same as any other 856 branch. In a Vendor merge, the data is append to the branch by the 857 "import" command, rather than by hand-editing, but the merge process 858 is the same. 859 860 See the "import" command in section 3H. 861 862 Last modified: _6/13/1997_ 863 864 16. How do I go back to a previous version of the code on a branch? 865 866 867 868 869 You can avoid digging into RCS revision numbers (executing "update 870 -r (rev)" on each file) by trying one of these: 871 872Use non-branch tags as you normally would. Non-branch tags 873 attach to specific revisions, so a "tag (tag)" command would 874 mark the revisions you have in your working directory, which 875 are on your branch. If you need to retrieve them, use "update 876 -r (non-branch-tag)" 877 878 Doing this overrides the sticky (branch-tag) attached to your 879 working directory with a non-branch tag, which means you won't 880 be able to commit until you again move forward to the end of 881 the branch with "update -r (branch-tag)". 882 883Use the "update -r (branch-tag):(date)" trick. 884 885 This is almost like using the '-D' option, but it looks for 886 revisions extant on (date) only along the given branch. 887 888 As in #1, you can't commit to this kind of working area, 889 because it has a sticky date referring to revisions in the 890 middle of a branch. 891 892[comment from the audience: You are dreaming.. 893this does not work.. try it, you get 894No such tag: "MYTAG:May 1" 895or similar. I wish it did because I need it. julian@whistle.com] 896 897 898You can branch a branch. 899 900 If you add a branch tag to file in a working directory that was 901 checked out on a branch, you will branch the branch. This 902 works just fine, though you'll have to play some games to merge 903 everything back together again. You'll also create 6-part 904 revision numbers. (They'll be 8-part revision numbers if you 905 branch a branch that started out with some unmodified files on 906 the Vendor branch. Think about it. How does revision 907 1.2.4.2.4.2.2.1 grab you?) 908 909 910(fixed formatting, kingdon@cyclic.com) 911 912 Last modified: _9/8/1997_ 913 914 17. Once I've found the files I want, how do I start changing them? I keep 915 getting warnings about sticky tags. 916 917 What you probably did was type "cvs update -r <tag>" where <tag> is a 918 non-branch tag. "update" created a sticky tag for a specific revision, 919 not a branch. To start working right there, you have to create a 920 branch to work on. 921 922 You have two choices. 923 924 You can do it in place and keep working: 925 926 cvs tag -b <branch_tag> <<== To tag the current files. 927 cvs update -r <branch_tab> <<== To move onto the branch. 928 929 You can do it "externally" and create a new working directory: 930 931 cvs rtag -b -r <tag> <branch_tag> <module> 932 cvs checkout -r <branch_tag> <module> 933 934 <module> can be a relative path within the Repository. 935 936 <tag> in the above is the non-branch tag you placed earlier 937 that caused the error in your question. Be warned that 938 if <tag> is not set on all the files (or all the right 939 revisions) you won't get exactly what you wanted. 940 941 Last modified: _6/13/1997_ 942 943 18. Why do I get the latest files on the branch when I tried to "update -r 944 <tag>"? 945 946 If "update -r <tag>" always retrieves the latest files on a branch, 947 then <tag> is really a <branch_tag>. A branch tag is supposed to be 948 used to grab a branch to work on. Since you can't modify a file in the 949 middle of a branch, checking out a <branch_tag> will give you the 950 latest revision on the branch. 951 952 If you want to "checkout" a specific collection of revisions, you must 953 use a "non-branch" tag. See the first part of 4C.16. 954 955 Last modified: _6/13/1997_ 956 957 19. How can I avoid a merge? I just want to move the latest revision on my 958 working branch directly onto the trunk. 959 960 There is no direct way to do this using CVS, though the technique is 961 not difficult using shell commands. Here's one way: 962 963 Move your working directory to the Main Branch. 964 965 cvs update -A 966 967 Use "update -p" to grab the latest revision on the branch and write 968 it over your working files. Make sure you don't have an modified files 969 -- you will lose them. The following is in "csh" syntax. Change the 970 wildcard to grab the files you want 971 972 foreach i (Makefile *.cc *.hh) 973 cvs update -p -r <branch_tag> $i > $i 974 end 975 976 Commit all the working files onto the Main Branch. 977 978 cvs commit -m 'Moved branch <branch_tag> onto MAIN' 979 980 You should experiment with the above before blasting everything. 981 982 Last modified: _6/13/1997_ 983 984 20. How to I avoid merge collisions in the RCS $\Log$ data? 985 986 In short, you can't. The RCS $\Log$ keyword is handled differently 987 from all other RCS keywords. 988 989 On the info-cvs mailing list, there is a periodic discussion that goes 990 something like this: 991 992 Question: How do I deal with $\Log$? Answer1: You can't do much with 993 it. Here's how it works. . . Answer2: I've found a limited way to use 994 it. . . Answer3: Get rid of it. $\Log$ is an abomination. 995 996 I tend to lean toward answer #3. There are only two sets of people who 997 would ever have access to logs stored within sources files, developers 998 and source customers. 999 1000 For developers: 1001 1002 Log entries within sources files are notoriously incomplete, rushed, 1003 poorly phrased and in many cases incorrect, making them useless for 1004 debugging or file maintenance. I remember a maxim from "Software 1005 Tools" (I believe): "Read the code, not the comments." No managerial 1006 order or plan for programmer discipline will affect this in the real 1007 world. 1008 1009 Log entries are usually in an unreadable mixture of styles. Many log 1010 entries are just plain meaningless. Some are foolish. Some are even 1011 insulting. Examples: 1012 1013 "Corrected spelling of misspelling." "Bug fix." "Reversed stupid 1014 change in previous revisions." "If Joe could do his job, this would 1015 already have worked." 1016 1017 Log entries are not managed well by the tools. Any merge can cause 1018 conflicts in the $\Log$ data. Branch merges produce incomplete logs. 1019 They can be edited into chaos and they are not regenerated. They waste 1020 space duplicating information available to the developer with a single 1021 command. 1022 1023 Even if correct when originally entered, as changes are made to the 1024 file, log entries become false over time. Humans are not good at 1025 reading down through a list and remembering only the last change 1026 affecting something. Over time *most* of the log is wrong. 1027 1028 Even if still correct, the log data is almost useless to developers 1029 without the code diffs. If you can get code diffs, you can display the 1030 log. 1031 1032 For source customers the problem is even worse. The last thing you 1033 want to show customers is a hodge-podge of tiny comments about large 1034 changes followed by a series of emergency fixes before delivery. If 1035 you distribute sources, then you should provide documentation, or 1036 changelogs reviewed by people who won't let comments like "Fixed for 1037 stupid customer." out the door. 1038 1039 Conclusion: Though some people would prefer to see in this FAQ 1040 techniques for making the $\Log$ entries the best they can be, I 1041 believe them to be a lost cause. My suggestion is to hunt down, root 1042 out and destroy all occurrences of $\Log$ and the unusable data 1043 attached to it wherever you may find it. 1044 1045 Last modified: _6/13/1997_ 1046 1047 21. Why should I trust automatic merges? 1048 1049 Some developers have the feeling that three-way merging doesn't work. 1050 They fear and distrust the way the "update" command automatically 1051 merges committed changes from the Repository into the working file. 1052 1053 Experience has shown that most merges are utterly painless and most of 1054 the rest are easily resolved. The few conflicts that cause headaches 1055 are nearly all due to poor communication between developers, a problem 1056 no source control system can obviate. 1057 1058 Some developers were troubled in the past by flaky Unix software. I 1059 can't say that everything is perfect, but the tools CVS depends on 1060 (RCS and diff, mainly) are fairly solid nowadays. They work. 1061 1062 Since it does seem to work for most of us, the algorithm is unlikely 1063 to change soon. Why not test it on a couple trouble spots and if it 1064 works for you, use it for a while? Then you can make an informed 1065 decision. 1066 1067 Last modified: _6/13/1997_ 1068 1069 22. How does CVS decide if it can safely perform a merge? 1070 1071 CVS can merge any text file, possibly discovering a conflict and 1072 leaving overlaps for you to edit. Editing the conflict markers out of 1073 the file is a moment's work, but resolving the conflict could take an 1074 arbitrary amount of time. CVS works to determine if it *should* merge, 1075 not if it *can*. 1076 1077 See 2B.6 for how the merge proceeds. 1078 1079 Last modified: _6/13/1997_ 1080 1081 23. After resolving merge conflicts in a file, what if I want to keep my 1082 previous version, and not take any of the branch changes? 1083 1084 If you want to retain your previous version, a version on the MAIN 1085 branch greater than 1.1 (one you committed there), just throw the 1086 merged file away and "cvs update" the file. 1087 1088 You don't need to commit something to remember it. The tags you place 1089 before and after the merge should give all the handles you need to 1090 find various versions. You don't have to create a new version of the 1091 file. 1092 1093 If you want to retain the previous Vendor revision, you can grab a 1094 copy of it using "cvs update -p" and commit it or use the technique 1095 described in 3B.3 to revert back to the Vendor branch. 1096 1097 Last modified: _6/13/1997_ 1098 1099 Category: /Advanced_Topics_/Engineering/ 1100 1101 " + Engineering" 1102 1103 1. Where can I find out about Software Engineering? 1104 1105 A couple different people suggested this book: 1106 1107 Software Configuration Management: Coordination for Team Productivity; 1108 Wayne A. Babich; Addison Wesley; 1986; ISBN 0-201-10161-0 1109 1110 A number of others suggested Appendix B of the book "Decline and Fall 1111 of the American Programmer" by Ed Yourdon, called "The Programmer's 1112 Bookshelf". It list 87 books you are expected to have read. Since they 1113 publish many of the books, Prentice-Hall distributes this list as 1114 "Prentice Hall Professional Technical reference PTR-125-AA3. 1115 1116 One interesting item from the Yourdon book: The total number of 1117 professional computer books sold is less than the number of 1118 programmers currently in the United States. It wasn't clear from the 1119 book whether this meant "per year" or not, but it is still 1120 frightening. 1121 1122 Last modified: _6/13/1997_ 1123 1124 2. How do I flexibly arrange the modules file to describe my sources? 1125 1126 An equivalent question might be, "How do I structure my sources?" This 1127 can be a difficult question especially in the areas that are more 1128 political than technical. 1129 1130 Generally you want to think about which pieces of your system need to 1131 be checked out together, built as one system or tagged as a consistent 1132 whole. You should certainly create module names that correspond to 1133 complete, buildable collections that you would tag and release as one 1134 "product". It is also convenient to create module names for small 1135 sections of the Repository containing files that will all be worked on 1136 at the same time by the same person or group. 1137 1138 Once you have defined the structure of your work, you can usually see 1139 how to lay it out in a Repository. After that the modules file is 1140 easy. You set up module names and aliases to match what you need to 1141 check out by name. If you like relative directories, it is possible, 1142 but not recommended, to work completely without a modules file. See 1143 1D.11 and 2C.7 for some info about the modules file. 1144 1145 Here are a few types of modules. You should experiment to see what 1146 kind of structure each of these produces. They all have different 1147 uses. 1148 1149 Connected projects in one group with two separate helper 1150 directories. The helper directories can contain build tools, header 1151 files, libraries, or whatever you like. 1152 1153 These are all aliases that checkout relative pathnames. The equivalent 1154 results could be produced by placing the selected relative pathnames 1155 on the "cvs checkout" command line. 1156 1157 pr1 -a P1 HELPERS 1158 pr2 -a P2 HELPERS 1159 pr3 -a P3 HELPERS 1160 pr12 -a P1 P2 HELPERS 1161 pr13 -a P1 P3 HELPERS 1162 pr23 -a P2 P3 HELPERS 1163 1164 P1 -a group1/proj1 1165 P2 -a group1/proj2 1166 P3 -a group1/proj3 1167 HELPERS -a group1/helper1 group1/helper2 MAKEFILE 1168 MAKEFILE -a group1/Makefile 1169 1170 Actual Repository directory structure: (from $CVSROOT down) 1171 1172 group1/ Makefile The top level Makefile. helper1/ helper2/ Helper 1173 files and dirs proj1/ Files and dirs proj2/ Files and dirs proj3/ 1174 Files and dirs 1175 1176 "checkout group1" produces a duplicate of the above. "checkout projX" 1177 produces all but "projY" and "projZ". "checkout projXY" produces all 1178 but "projZ". 1179 1180 Here is the exact same set of module names describing the same 1181 Repository layout using module names (and aliases containing module 1182 names) instead of merely aliases for relative pathnames. 1183 1184 There is one difference in the result. The name of the top level 1185 directory in the checked out working tree w…
Large files files are truncated, but you can click here to view the full file