PageRenderTime 234ms CodeModel.GetById 75ms app.highlight 124ms RepoModel.GetById 1ms app.codeStats 1ms

/contrib/cvs/FAQ

https://bitbucket.org/freebsd/freebsd-head/
#! | 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