-------------------------------------------------------------------------------

   CVS is Copyright (C) 1986-2006 The Free Software Foundation, Inc.

   CVS is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 1, or (at your option)
   any later version.

   More details are available in the COPYING file but, in simplified
   terms, this means that any distributed modifications you make to
   this software must also be released under the GNU General Public
   License.

   CVS is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

-------------------------------------------------------------------------------

This file contains a CVS FAQ.  Until 1995 it was maintained by David
Grubbs.  It was out of date and not being maintained, but it had a
certain following and in 1997 Pascal Molli decided to start
maintaining it with the FAQ-O-Matic package which allows any
contributor with a web browser to help maintain it.  The following
text is (mostly automatically) extracted from the FAQ-O-Matic.  The
odds are good that the file that you are currently reading is out of
date with respect to the online FAQ-O-Matic, which is part of Pascal
Molli's CVS web site at http://www.loria.fr/~molli/cvs-index.html
(currently under "Documentation").  The online version is also
somewhat better in terms of things like tables of contents (at least
until someone can write some code to extract data from a FAQ-O-Matic
and insert things like tables of contents).

The answers which are dated "6/13/1997" below are really from the 1995
FAQ, for the most part.  Many of them are out of date.  The current FAQ may
be found at <http://ximbiot.com/cvs/wiki/index.php?title=CVS_FAQ>.  If you have
some time, you are encouraged to export that FAQ as text and import it here.
If you don't have such time, take the answers in this file with at least a few
grains of salt.

Since August, 2005, many of the existing CVS resources have been centralized on
<http://cvs.nongnu.org> & <http://ximbiot.com>.

  Category: /, all questions
  
  Category: /
  
          " [INLINE] "
          
    1. About FAQ-O-Matic 
    
This is FAQ-O-Matic, a quick-and-dirty Perl hack (aren't they all?) by
Jon Howell.

It seems like most FAQ maintainers make a valiant initial effort, then get
a life and don't have time to keep their FAQs up to date. Also, I often
find out a solution to a problem, and feel like I could write a single
FAQ answer on it in a few minutes, but where to post it?

Thus the FAQ-O-Matic was born. FAQ-O-Matic is a couple sleazy Perl scripts
that allow people to submit FAQ answers to this database, so it can stay
current, with just a tiny bit of work on any one person's part.

Yes, a bad guy could come along and wipe out all the FAQ entries. Please don't.
But to give the good guys some measure of comfort, each submission is stored
in an RCS file, so if someone does tamper, we can recover the database.

Guidelines for submissions:

1. Please _try to be fairly unbiased in matters of opinion._ Mailing lists are
the place to start flame wars (just kidding :v), but definitely not here.

2. Please _use HTML only conservatively_ in your entries. Links are appropriate
,
but put the URL in the plaintext also so it's useable on printed versions of
the FAQ. Inline images pointing off this site are inappropriate, as is much
fancy formatting. This is meant to be bandwidth-light and dumb-browser-friendly
.

3. If you feel there's a place for a _new category, or a reorganization of
existing questions_, don't hesitate to mail me (molli@loria.fr).
Category changes need to be done from my end.

4. Please _leave an email address_ at the bottom of your submission so that oth
ers
can drop you a note.

5. _If you only have a question_, not an answer, you should probably post
it to a mailing list, not here. If there are frequently asked questions to whic
h
the answer is not forthcoming on mailing lists (or perhaps there's no
useful answer yet other than "no one knows"), then it's appropriate to
post here, in hopes that someone will see it and know the answer.

6. Please refrain from crude or inconsiderate language. Please don't use
this as a forum for advertising. However, mention of worthy commercial
products is certainly appropriate (even if you sell said product). Just
don't overdo it. :v)

          Last modified: _6/13/1997_
          
    2. Adding a new category ? 
    
just send me a mail at
molli@loria.fr

          Last modified: _6/13/1997_
          
  Category: /Advanced_Topics_/
  
          " Advanced Topics "
          
  Category: /Advanced_Topics_/Branching_and_Mergin/
  
          " + Branching and Merging"
          
    1. What is a branch? 
    
          Unfortunately, the word "branch" is an overloaded technical
          term. It is used in too many different ways in three
          categories. It might help to understand some of the issues by
          going through the categories:
          
     How Humans use the word "branch":
          
          Most development starts with everyone working on the same
          software, making changes and heading toward a single goal. This
          is called something like "Main Line Development". Note that
          though many people do main line development on CVS's "Main
          Branch", that is a choice, not a requirement.
          
          After a release or when one or more developers want to go off
          and work on some project for a while, the Software Engineers
          assigned to deal with large software issues generate a "Branch
          in Development" to support the release or project. (Keep in
          mind that a programmer is no more a Software Engineer than a
          carpenter is a Civil Engineer.)
          
          Essentially, the word "branch" implies a way to allow
          simultaneous development on the same files by multiple people.
          
          The above terms are human-oriented. They refer to actions that
          people would like to take. They do *not* imply any particular
          implementation or set of procedures. Branches in development
          can be supported in many different ways.
          
     How CVS uses the word "branch":
          
          CVS uses the word "branch" in a number of ways. The two most
          important are:
          
          - The vendor branch holds releases from (normally) an outside
          software vendor. It is implemented using a specific RCS branch
          (i.e. 1.1.1).
          
          - The "Main Branch", which normally holds your "Main Line
          Development", but is defined as the collection of revisions you
          get when you "checkout" something fresh, or when you use the
          '-A' option to "update".
          
          Important Note: The CVS "Main Branch" is *not* the same as the
          RCS concept with the same name. If you are using Vendor
          Branches, files you have never changed are on three branches at
          the same time:
          
          - The RCS 1.1.1 branch.
          - The CVS Vendor branch.
          - The CVS "Main Branch".
          
          The concepts overlap, but they are not equivalent.
          
          In referring to CVS, "branch" can be used in four other ways:
          
          - A CVS working directory satisfies the definition of "branch"
          for a single developer -- you are on a private "virtual branch"
          that does not appear in any of the RCS files or the CVS control
          files.
          
          - The CVS "default branch" is the Repository source for the
          collection of files in your working directory. It is *not* the
          same as the RCS "default branch". Normally the CVS default
          branch is the same as the CVS Main branch. If you use the "-r
          <branch_tag>" option to the "checkout" command, you will record
          a "sticky" tag that changes your default branch to the one you
          checked out.
          
          - A "magic" branch can be a branch that hasn't happened yet. It
          is implemented by a special tag you can check out that is not
          attached to a real RCS branch. When you commit a file to a
          magic branch, the branch becomes real (i.e. a physical RCS
          branch).
          
          - And, of course, CVS uses "branch" to indicate a
          human-oriented "branch in development".
          
     How RCS uses the word "branch":
          
          - The RCS "Main Branch" (Synonym: "The Trunk") contains a
          series of two-part revision numbers separated by a single '.'
          (e.g. 1.2). It is treated specially and is the initial default
          branch. (The default default?)
          
          - The RCS "Default" branch starts out attached to the RCS "Main
          Branch". For RCS purposes, it can be changed to point to any
          branch. Within CVS, you *must*not* alter the RCS default
          branch. It is used to support the CVS idea of a "Main Branch"
          and it must either point to the RCS Main Branch, or the Vendor
          Branch (1.1.1) if you haven't made any changes to the file
          since you executed "import".
          
   Last modified: _6/13/1997_
   
    2. Why (or when) would I want to create a branch? 
    
   Remember that you can think of your working directory as a "branch for
   one". You can consider yourself to be on a branch all the time because
   you can work without interfering with others until your project (big
   or small) is done.
   
   The four major situations when you should create a branch:
   
     When you expect to take a long time or make a large set of changes
   that the merging process will be difficult. Both "long" and "large"
   are defined in your own environment.
   
     When you want to be able to "commit" and "tag" your work repeatedly
   without affecting others.
   
   If you ever think you need Source Control for your own work, but don't
   want your changes to affect others, create a private branch. (Put your
   username in the branch tag, to make it obvious that it is private.)
   
     When you need to share code among a group of developers, but not the
   whole development organization working on the files.
   
   Rather than trying to share a working directory, you can move onto a
   branch and share your work with others by "committing" your work onto
   the branch. Developers not working on the branch won't see your work
   unless they switch to your branch or explicitly merge your branch into
   theirs.
   
     When you need to make minor changes to a released system.
   
   Normally a "release" is labeled by a branch tag, allowing later work
   on the released files. If the release is labeled by a non-branch tag,
   it is easy to add a branch tag to a previously tagged module with the
   "rtag" command. If the release is not tagged, you made a mistake.
   Recovery requires identifying all revisions involved in the release
   and adding a tag to them.
   
   Last modified: _6/13/1997_
   
    3. How do I create and checkout a branch? 
    
   Suggested technique:
   
     Attach a non-branch tag to all the revisions you want to branch
   from. (i.e. the branch point revisions)
   
     When you decide you really need a branch, attach a branch tag to the
   same revisions marked by the non-branch tag.
   
     "Checkout" or "update" your working directory onto the branch.
   
     Suggested procedure when using modules:
   
     cvs rtag <branch_point_tag> module
   
     cvs rtag -b -r <branch_point_tag> <branch_tag> <module>
   
     cvs checkout -r <branch_tag> module
   
     Suggested procedure when using your working directory, which
   contains the revisions of your working files you want to branch from:
   
     cvs tag <branch_point_tag>
   
     cvs rtag -b -r <branch_point_tag> <branch_tag> <module>
   
     cvs update -r <branch_tag>
   
   In each procedure above, Step #1 applies a non-branch tag to all the
   branch point revisions in the module/directory. Though this is not
   strictly necessary, if you don't add a non-branch tag to the revisions
   you branch from, you won't be able to refer to the branch point in the
   future.
   
   Between steps 1 & 2 you may commit changes. The result would be same
   because "rtag -r <oldtag> <newtag>" applies <newtag> to the same
   revision that <oldtag> is attached to. You can use this technique to
   avoid attaching *any* branch tags until you need them.
   
   Step B.2 has two corollaries:
   
     If you plan to create the branch tag before committing anything in
   your working directory, you can use "cvs tag -b <branch_tag>" instead
   of the "rtag" command.
   
     The <module> can be a relative path to a directory from which your
   working directory was checked out.
   
   If you have trouble figuring out what <module> to use (or pathname to
   use in its place), you can aim it at whatever parent directories you
   believe will cover all your work.
   
   If you are sure the <branch_tag> is not being used anywhere else, you
   can even aim it at the whole Repository ($CVSROOT), if you have to. It
   might take some extra time, but assuming that your <tag> is a unique
   string and you don't use the '-f' option to "rtag -r", "rtag" will
   only add a <tag> to files in which it actually *finds* the earlier
   <tag>.
   
   In each procedure above, Step #3 may occur any time after step 2.
   Unless you explicitly remove them with "tag -d", a <tag> is permanent.
   
   The <branch_tag> is an unusual creature. It labels a branch in a way
   that allows you to "checkout" the branch, to "commit" files to the end
   of the branch and to refer to the end of the branch. It does not label
   the base of the branch (the branch point).
   
   There are two obvious ways to choose the <branch_point_tag> and
   <branch_tag> names. But keep in mind that the <branch_tag> is typed by
   any developer who wants to work on the branch -- you should make it
   mean something to them.
   
   Style #1 presumes that the simple version string refers to a set of
   designed, documented or promised features, not to a specific set of
   files. In this case, you tag the branch with the generic Version
   string and assume that whenever you refer to "Version", you want the
   "latest" set of files associated with that Version, including all
   patches. (You can substitute whatever you like for "bp_", as long as
   your <branch_point_tag> is some modification of the <branch_tag>.)
   
                <branch_point_tag>      Matching <branch_tag>

                bp_V1_3                 V1_3
                bp_Release2-3-5         Release2-3-5
                bp_Production4_5        Release4_5

   Style #2 presumes that the simple version string refers to the
   specific set of files used to construct the first release of
   "version". In this case, you tag the branch-point revisions with the
   generic Version string and assume that whenever you refer to this
   Version, you want the original set of released revisions. To get the
   latest patched revisions of the release, you refer to the branch tag
   "latest_<branch_point_tag>". (You can substitute what ever you like
   for "latest_", as long as your <branch_tag> is some modification of
   the <branch_point_tag>.)
   
                <branch_point_tag>      Matching <branch_tag>

                V1_3                    latest_V1_3
                Release2-3-5            latest_Release2-3-5
                Release4_5              latest_Production4_5

   In both styles you can find out what you had to change since the
   original release of this Version by typing:
   
            cvs diff -r <branch_point_tag> -r <branch_tag>

   For Style 1, this is:
   
            cvs diff -r bp_<branch_tag> -r <branch_tag>

   For Style 2, this is:
   
            cvs diff -r <branch_point_tag> -r latest_<branch_point_tag>

   Notes on "being on a branch":
   
   - "update -r <tag>" tells CVS to attach a "sticky tag" to working
   directory (in ./CVS/Tag) and the checked-out files (on each line of
   ./CVS/Entries).
   
   - A "sticky" <tag> (including a <branch_tag>) causes most CVS commands
   to act as if "-r <tag>" were on the command line.
   
   - A "sticky" <branch_tag> indicates that the working directory (and
   working files) are "on the branch".
   
   Last modified: _6/13/1997_
   
    4. Once created, how do I manage a branch? 
    
   The most important thing you should know about managing a branch is
   that the creation of a branch is not a lightweight act. When you
   create a branch, you must also create a set of procedures to keep
   track of it.
   
   Specifically, you must:
   
   - Remember that the branch exists. (This is non-trivial if you create
   a lot of them.)
   
   - Plan when to merge it back into the main line of development.
   
   - Schedule the order that multiple branch merges are to be done.
   
   - If you ever intend to merge branches into each other, instead of
   limiting merges of branch work back into the "main line", you must
   keep careful track of which parts of which branches have merged into
   which other branches.
   
   The simplest way to deal with branches is to limit their number,
   "collapse" them back into the main line as quickly as is reasonable
   and forget them. If a group wants to continue working, tell them to
   create another branch off the fully merged main line.
   
   Remember that CVS is just a tool. Over time, it will probably handle
   branching better, requiring less careful attendance. But no matter how
   good it becomes, the whole idea of "branching" is a complicated
   management problem. Don't take it lightly.
   
   Last modified: _6/13/1997_
   
    5. Are there any extra issues in managing multiple branches? 
    
   If you plan to split from the "main line" and merge back after a time,
   the only problem will be scheduling the order of branch merges. As
   each branch is merged, the main line must be rebuilt and tested.
   Merging multiple branches (i.e. "lines of development") before
   building and testing creates more problems than you are ready for.
   
   If you plan to collapse some branches into others, then move the
   combined branches back into the main line, you have to be careful with
   the revisions and tags you hand to your "update -j" command, but it
   shouldn't be much trouble.
   
   If you plan to allow every branch to incrementally take the work done
   on other branches, you are creating an almost insurmountable
   bookkeeping problem. Every developer will say "Hey, I can handle
   taking just this little bit," but for the system as a whole it is
   disaster. Try it once and see. If you are forced into this situation,
   you will need to keep track of the beginning and end points of every
   merge ever done. Good Luck.
   
   Last modified: _6/13/1997_
   
    6. How do I merge a whole branch back into the trunk? 
    
   If you don't have a working directory, you can checkout and merge in
   one command:
   
                cvs checkout -j <branch_tag> <module>
                cd <module>

   If you already have a working directory:
   
                cd <working_directory>
                cvs update      <== Optional, to bring it up to date.
                cvs update -j <branch_tag>

   CVS will print lines beginning with
   
   'U' for files that you hadn't changed, but the branch did.
   
   'M' for files that you changed and the branch didn't
                *and* for files that you both changed that were merged
                without overlaps.  (This overload is unfortunate.)

   'C' for files that you both changed in a way that conflicts
                with each other.

   You need to go edit all the 'C' files and clean up the conflicts. Then
   you must commit them.
   
   Last modified: _6/13/1997_
   
    7. How do I merge changes from the trunk into my branch or between
    branches? 
    
   The idea is similar to the above, but since CVS doesn't treat the main
   branch like other branches, you'll have to be more careful. There are
   5 different ways to look at the problem.
   
     The way to merge *all* changes made on the trunk into a working
   branch is to move to the branch you want via "checkout -r" or "update
   -r":
   
                cvs update -r <branch_tag> {optional files}

   Then merge the changes from the trunk into your working branch using
   the pseudo-tag named "HEAD":
   
                cvs up -j HEAD {optional files}

   You will get everything from the branch point of the branch named
   <branch_tag> up to the HEAD of the main branch. This is still kind of
   strange. If the file is on a branch, HEAD should be the latest thing
   on the branch, not the HEAD of MAIN. But that's not the way CVS
   (currently) works.
   
   If you run "cvs up -j HEAD" again after adding more revisions to the
   trunk, you may get overlaps for the text you have already merged. It
   depends on your version of your RCS "merge" command (actually the "co
   -j" option, which depends on the version of "diff3" you configured RCS
   to use).
   
     You can merge the difference between any two <tags> using two "-j"
   options on "update" or "checkout".
   
   Identify the two tags on the branch you want to merge from.
   
                cvs update -j <tag1> -j <tag2> {optional files}

   This step assumes you were careful about tagging milestones. You can
   use this technique for any two <tags> on the same branch, even the
   trunk. It is also possible to use tags on different branches, but
   you'll have to ponder the meaning of the difference between those two
   tags.
   
   In place of one of the <tags>, you can use a <branch_tag> to refer to
   the latest revision on that branch. See 4C.11 and 4C.3 for info on
   branch points.
   
   Merges can also be performed by handing RCS revisions to the '-j'
   options, but since revision numbers aren't the same in all files,
   merging by number is normally limited to one file. Sets of files with
   the exact same trees of branches and revision numbers would work too,
   but that's a rare situation.
   
     To "take" revisions from other branches instead of merging them, see
   4C.19 for an idea.
   
     A way to gain the effect of merging the main to the branch is to
   merge the branch into the main using the normal
   
                cvs update -A {optional files}
                cvs update -j <branch_tag> {optional files}
                cvs commit
                cvs tag -F  -b <same_branch_tag> {optional files}

   See part B of 4D.5
   
     Other oddities.
   
   This also works, but is probably not officially supported:
   
                   cvs update -j N {optional files}

   where N is a number. This will merge all the changes from the branch
   point up to the highest revision on the main branch starting with N.
   For example, if your highest trunk revision is 1.52, you can use this
   to grab revisions from the trunk:
   
                   cvs update -j 1 {optional files}

   Another example: Say you have a branch point at rev 1.2 for a branch
   named "BR1" and trunk revisions 1.3, 1.4, 2.1, 2.2, 2.3, 3.1, 3.2.
   Then:
   
                   cvs update -j 1 {optional files}

   will merge the changes from 1.2 to 1.4
   
                   cvs update -j 2 {optional files}

   will merge the changes from 1.2 to 2.3
   
                   cvs update -j 3 {optional files}

   will merge the changes from 1.2 to 3.2, which in this example, is
   equivalent to the use of "-j HEAD" in part A above.
   
   The intuitive (at least to me):
   
                   cvs up -j MAIN (or TRUNK) {optional files}

   doesn't work. If the trunk (i.e. "main branch") had an implicit branch
   named "MAIN", you could use:
   
                   cvs up -j MAIN:10/26 -j MAIN:now {optional files}

   and refer to date-stamped revisions on the trunk using the
   <branch_tag>:<date> support that works on other branches.
   
   You might also think you could place an explicit tag on branch 1 (or
   higher) (e.g. MAINHACK:1) and use it in place of the implicit "MAIN",
   but I haven't found the right combination.
   
   [[If you find working techniques, I'll add them here.]]
   
   Last modified: _6/13/1997_
   
    8. How do I merge onto the Main Branch a file that exists only on a branch
    other than the Main Branch? (i.e. it is in the Attic) 
    
   For how such a file can exist, see 3A.2 and 3A.3.
   
   For how to avoid creating such a file, see 3A.5.
   
   Though you might think that the "update -j" command could perform the
   "merge" of a file from the side branch to the Main Branch, it isn't
   (yet) smart enough. Unfortunately, there is no single CVS command to
   do this -- it takes three steps:
   
     To move something onto the Main Branch from the Attic, you have to
   physically move the file from the Attic to the main Repository
   directory associated with your working directory.
   
   It is exactly like resurrecting a removed file. See 3L.4
   
   I use something like this: (csh-like syntax)
   
   set repos = `cat ./CVS/Repository` mv $repos/Attic/filename,v
   $repos/filename,v
   
   (If you use relative paths in your Repository files, that first line
   becomes: set repos = $CVSROOT/`cat ./CVS/Repository`)
   
     Now that the file is physically in the right place within the
   Repository, "update -A" will make it appear in your working directory
   on the Main Branch. Do that now.
   
     You now have a choice. The act of physically moving the file has
   fused together the <branch_tag> branch and the Main Branch for this
   file. You can continue that way, making changes along the RCS Main
   Branch which CVS will (for this type of file only) treat as both the
   Main Branch and the <branch_tag> branch.
   
   The other choice, which I would suggest, is to re-tag the file with
   <branch_tag>, restoring a normal-looking magic branch tag to the file:
   
                cvs tag -F -b <branch_tag> <file>

   After you have done the above, you can run "update -A" or "update -r
   <branch_tag>" to resume whatever you were doing before you started
   this procedure.
   
   Caveat: The final result is a file whose revision tree doesn't look
   like it was ever on any branch but the Main Branch until the above
   "tag -F -b" command was executed. CVS and RCS have no way of saving
   the history of the actions you have just performed.
   
   Last modified: _6/13/1997_
   
    9. How do I know what branch I'm (working) on? 
    
   Type:
                cvs status

   and look at the "Sticky Tag" field for each file. If:
   
     The *same* tag is on *every* file in your working tree, *and*
   
     That tag matches the contents of the ./CVS/Tag file, *and*
   
     That tag is a branch tag,
   
   then you know what branch you are working on. You can get sticky Tag
   information directly from the ./CVS/Entries file instead of "cvs
   status".
   
   If all the sticky Tags don't agree, then your directory is temporarily
   inconsistent. This is a feature allowing you to make changes (or
   perform merges) to individual files on multiple branches without
   checking out the whole directory.
   
   The sticky Tag on each file in the ./CVS/Entries file (as displayed by
   the "status" command) indicates what branch the working file is on.
   New files are added to the Tag stored in ./CVS/Tag.
   
   To force your entire working directory onto the same branch, type:
   
                cvs update -r <branch_tag>

   Last modified: _6/13/1997_
   
    10. Do I really have to know the name of the branch I'm working on? 
    
   If a developer can't be relied on to know what branch of development
   to work on, then either the developer's manager isn't planning
   branches properly or the developer has serious problems.
   
   I have found that one of the hardest concepts to get across to
   developers (and some managers) is that "a branch in development" (as
   opposed to the use of RCS branches to support some other scheme) is a
   heavyweight act. Every time you create a real branch in development,
   you must spawn a set of managerial procedures and a schedule by which
   you plan to merge each branch into each other branch. Unless you plan
   to keep it simple and collapse (by merging and forgetting) branches
   quickly, they are not to be created lightly.
   
   In other words, if you don't regularly attend group meetings in which
   the branch to be worked on is a major topic of discussion, then the
   group is not managing branches properly.
   
   We created a couple major branches a few months ago and even the
   customer service people refer to the "XYZ branch" as a shorthand for
   "continuing development on the XYZ project".
   
   Last modified: _6/13/1997_
   
    11. How do I refer to the revision where I branched so I can see what
    changed since the Branch Point on another branch? 
    
   Given the current <branch_tag> format, there is no direct way to refer
   to the branch point, which is more useful in many ways than referring
   to the branch, which always refers to the latest revision on the
   branch.
   
   When CVS adds a branch tag, it attaches an RCS symbol to a
   non-existent revision number containing the revision number of the
   branch point as a prefix. (See Section 3O, on the "tag" command.) RCS
   can't use the CVS magic branch tag and many of the CVS commands can't
   refer to it.
   
   To be certain of your ability to refer to a branch point, you must
   create a "branch point" tag at the same time as the Branch tag. See
   4C.3.
   
   Last modified: _6/13/1997_
   
    12. Why didn't the command "cvs admin -bBRANCH1 *" create a branch? 
    
   Because your command creates an RCS branch, not a CVS branch. See the
   above discussion on branches. RCS branches are used to support CVS
   branches, but they are not the same. You can't act as if you have
   direct control over the RCS files.
   
   The "admin" command was placed there as a convenience to allow you to
   execute raw "rcs" commands on the Repository, taking advantage of
   CVS's ability to find the files in the Repository.
   
   But you have to remember that you are using RCS commands on a CVS
   Repository, which is not generally safe unless you know exactly what
   CVS depends on.
   
   For one thing, CVS insists on control of the default branch. It is set
   either to the Main branch or the Vendor branch depending on whether
   you have changed the Vendor's code. If you change the default branch,
   you are monkeying with the internals and you will get unexpected
   results.
   
   To set your "default CVS branch" to BRANCH1, you must use "checkout"
   or "update" with the "-r BRANCH1" option. Then you have changed CVS's
   idea of your "default branch", which has little to do with RCS's
   default branch.
   
   Last modified: _6/13/1997_
   
    13. Is it possible to set the "default CVS branch" for everyone? 
    
   No. It doesn't work that way.
   
   When using CVS, all administrative information (such as what branch
   you checked out) is stored in CVS sub-directories, local to the user.
   There is no global state, other than the description and logging files
   in the $CVSROOT/CVSROOT directory.
   
   You tell "checkout" or "update" what branch you want to check out via
   the "-r <tag>" option. The default is CVS's "Main Branch".
   
   I don't see a problem in *designing* a new way to indicate what branch
   you get by default, instead of the main one, but that's not how it
   currently works.
   
   Last modified: _6/13/1997_
   
    14. How do I perform a large merge? 
    
   Large merges require a bit more planning to be able to track what has
   happened in the inevitable cases where something goes wrong. No tool
   can force a "merge" to make perfect sense.
   
   Though you can handle the details in many different ways, the two ends
   of the spectrum of merge techniques are: gonzo and paranoid.
   
     The gonzo method assumes that you know everything about your sources
   so that recovery from failures is "just a matter of typing." You
   created the branch this way:
   
                cvs checkout <module>
                cd <module>
                cvs tag -b <branch_tag>
                cvs update -r <branch_tag>
                >>> Edit away.
                cvs commit              <<== Onto branch

   Now you want to merge your branch back into the Main branch, you are
   certain you can make it work, or at least detect all the failures, so
   you dive in and hack away: (For simplicity, we will assume you are
   collapsing (i.e. merging and forgetting) a side-branch into the Main
   branch from your single working directory.)
   
                cvs update -A
                cvs update -j <branch_tag>
                >>> Edit the 'C' files and remove the overlaps.
                >>> Edit some more to make it all compile and work.
                cvs commit

   Looks simple. For more details on the output from the "update -j"
   command, see 3P.2 and 4C.6.
   
   Note: You could also checkout a whole new working directory and
                 perform the merge at the same time by replacing the two
                 update commands with these two commands:

                        cvs checkout -j <branch_tag> <module>
                        cd <module>

     The paranoid way is more difficult, but it can catch all sorts of
   problems. You created the branch this way:
   
                cvs checkout <module>
                cd <module>
                cvs tag <branch_point_tag>
                cvs tag -b <branch_tag>
                cvs update -r <branch_tag>
                >>> Edit away.
                cvs commit              <<== Onto branch

   The extra tag command places a non-branch tag on the Branch Point, an
   act that makes it easier to do "diffs" later. Now we decide to perform
   the merge:
   
                cvs tag <latest_on_branch_tag>
                cvs update -A
           *1*  cvs diff -r <branch_point_tag> -r <latest_on_branch_tag>
                >>> *1* shows all the changes on the branch.
           *2*  cvs diff -r <branch_point_tag> -r HEAD
                >>> *2* shows the changes on the trunk since branching.
                cvs tag <premerge_tag>
                cvs update -j <branch_tag>
                >>> Edit the 'C' files and remove the overlaps.
           *3*  cvs diff
                >>> Verify that *3* matches *1*, except for line numbers.
                cvs commit
                cvs tag <just_merge_changes_tag>
                >>> Edit some more to make it all compile and work.
                cvs commit
                cvs tag <after_merge_cleanup_tag>

   The reason *3* and *1* match so closely is that they are the
   differences between two pairs of starting points and ending points
   after the same data was inserted. If they are significantly different,
   you will want to figure out why.
   
   NOTE: You will have to tell everyone to stay the hell out of the
   Repository while you do this. If they commit something while you are
   in the middle of a merge, your job will be much more difficult. If
   they "update" at the wrong time, their work will be randomized until
   you finish. It's better to call a halt.
   
   See 3H.13 for some more information about dealing with merges after
   import. The last part of the procedure is applicable to any large
   merge.
   
   Last modified: _6/13/1997_
   
    15. Is a Vendor merge any different from a branch merge? 
    
   No. In most ways, a Vendor branch is exactly the same as any other
   branch. In a Vendor merge, the data is append to the branch by the
   "import" command, rather than by hand-editing, but the merge process
   is the same.
   
   See the "import" command in section 3H.
   
   Last modified: _6/13/1997_
   
    16. How do I go back to a previous version of the code on a branch? 
    



        You can avoid digging into RCS revision numbers (executing "update
        -r (rev)" on each file) by trying one of these:

Use non-branch tags as you normally would.  Non-branch tags
           attach to specific revisions, so a "tag (tag)" command would
           mark the revisions you have in your working directory, which
           are on your branch.  If you need to retrieve them, use "update
           -r (non-branch-tag)"

           Doing this overrides the sticky (branch-tag) attached to your
           working directory with a non-branch tag, which means you won't
           be able to commit until you again move forward to the end of
           the branch with "update -r (branch-tag)".

Use the "update -r (branch-tag):(date)" trick.

           This is almost like using the '-D' option, but it looks for
           revisions extant on (date) only along the given branch.

           As in #1, you can't commit to this kind of working area,
           because it has a sticky date referring to revisions in the
           middle of a branch.

[comment from the audience:  You are dreaming..
this does not work.. try it, you get
No such tag: "MYTAG:May 1"
or similar. I wish it did because I need it. julian@whistle.com]


You can branch a branch.

           If you add a branch tag to file in a working directory that was
           checked out on a branch, you will branch the branch.  This
           works just fine, though you'll have to play some games to merge
           everything back together again.  You'll also create 6-part
           revision numbers.  (They'll be 8-part revision numbers if you
           branch a branch that started out with some unmodified files on
           the Vendor branch.  Think about it.  How does revision
           1.2.4.2.4.2.2.1 grab you?)


(fixed formatting, kingdon@cyclic.com)

   Last modified: _9/8/1997_
   
    17. Once I've found the files I want, how do I start changing them? I keep
    getting warnings about sticky tags. 
    
   What you probably did was type "cvs update -r <tag>" where <tag> is a
   non-branch tag. "update" created a sticky tag for a specific revision,
   not a branch. To start working right there, you have to create a
   branch to work on.
   
   You have two choices.
   
     You can do it in place and keep working:
   
           cvs tag -b <branch_tag>      <<== To tag the current files.
           cvs update -r <branch_tab>   <<== To move onto the branch.

     You can do it "externally" and create a new working directory:
   
           cvs rtag -b -r <tag> <branch_tag> <module>
           cvs checkout -r <branch_tag> <module>

   <module> can be a relative path within the Repository.
   
   <tag> in the above is the non-branch tag you placed earlier
                 that caused the error in your question.  Be warned that
                 if <tag> is not set on all the files (or all the right
                 revisions) you won't get exactly what you wanted.

   Last modified: _6/13/1997_
   
    18. Why do I get the latest files on the branch when I tried to "update -r
    <tag>"? 
    
   If "update -r <tag>" always retrieves the latest files on a branch,
   then <tag> is really a <branch_tag>. A branch tag is supposed to be
   used to grab a branch to work on. Since you can't modify a file in the
   middle of a branch, checking out a <branch_tag> will give you the
   latest revision on the branch.
   
   If you want to "checkout" a specific collection of revisions, you must
   use a "non-branch" tag. See the first part of 4C.16.
   
   Last modified: _6/13/1997_
   
    19. How can I avoid a merge? I just want to move the latest revision on my
    working branch directly onto the trunk. 
    
   There is no direct way to do this using CVS, though the technique is
   not difficult using shell commands. Here's one way:
   
     Move your working directory to the Main Branch.
   
                cvs update -A

     Use "update -p" to grab the latest revision on the branch and write
   it over your working files. Make sure you don't have an modified files
   -- you will lose them. The following is in "csh" syntax. Change the
   wildcard to grab the files you want
   
   foreach i (Makefile *.cc *.hh)
                    cvs update -p -r <branch_tag> $i > $i
                end

     Commit all the working files onto the Main Branch.
   
                cvs commit -m 'Moved branch <branch_tag> onto MAIN'

   You should experiment with the above before blasting everything.
   
   Last modified: _6/13/1997_
   
    20. How to I avoid merge collisions in the RCS $\Log$ data? 
    
   In short, you can't. The RCS $\Log$ keyword is handled differently
   from all other RCS keywords.
   
   On the info-cvs mailing list, there is a periodic discussion that goes
   something like this:
   
   Question: How do I deal with $\Log$? Answer1: You can't do much with
   it. Here's how it works. . . Answer2: I've found a limited way to use
   it. . . Answer3: Get rid of it. $\Log$ is an abomination.
   
   I tend to lean toward answer #3. There are only two sets of people who
   would ever have access to logs stored within sources files, developers
   and source customers.
   
   For developers:
   
     Log entries within sources files are notoriously incomplete, rushed,
   poorly phrased and in many cases incorrect, making them useless for
   debugging or file maintenance. I remember a maxim from "Software
   Tools" (I believe): "Read the code, not the comments." No managerial
   order or plan for programmer discipline will affect this in the real
   world.
   
     Log entries are usually in an unreadable mixture of styles. Many log
   entries are just plain meaningless. Some are foolish. Some are even
   insulting. Examples:
   
   "Corrected spelling of misspelling." "Bug fix." "Reversed stupid
   change in previous revisions." "If Joe could do his job, this would
   already have worked."
   
     Log entries are not managed well by the tools. Any merge can cause
   conflicts in the $\Log$ data. Branch merges produce incomplete logs.
   They can be edited into chaos and they are not regenerated. They waste
   space duplicating information available to the developer with a single
   command.
   
     Even if correct when originally entered, as changes are made to the
   file, log entries become false over time. Humans are not good at
   reading down through a list and remembering only the last change
   affecting something. Over time *most* of the log is wrong.
   
     Even if still correct, the log data is almost useless to developers
   without the code diffs. If you can get code diffs, you can display the
   log.
   
   For source customers the problem is even worse. The last thing you
   want to show customers is a hodge-podge of tiny comments about large
   changes followed by a series of emergency fixes before delivery. If
   you distribute sources, then you should provide documentation, or
   changelogs reviewed by people who won't let comments like "Fixed for
   stupid customer." out the door.
   
   Conclusion: Though some people would prefer to see in this FAQ
   techniques for making the $\Log$ entries the best they can be, I
   believe them to be a lost cause. My suggestion is to hunt down, root
   out and destroy all occurrences of $\Log$ and the unusable data
   attached to it wherever you may find it.
   
   Last modified: _6/13/1997_
   
    21. Why should I trust automatic merges? 
    
   Some developers have the feeling that three-way merging doesn't work.
   They fear and distrust the way the "update" command automatically
   merges committed changes from the Repository into the working file.
   
   Experience has shown that most merges are utterly painless and most of
   the rest are easily resolved. The few conflicts that cause headaches
   are nearly all due to poor communication between developers, a problem
   no source control system can obviate.
   
   Some developers were troubled in the past by flaky Unix software. I
   can't say that everything is perfect, but the tools CVS depends on
   (RCS and diff, mainly) are fairly solid nowadays. They work.
   
   Since it does seem to work for most of us, the algorithm is unlikely
   to change soon. Why not test it on a couple trouble spots and if it
   works for you, use it for a while? Then you can make an informed
   decision.
   
   Last modified: _6/13/1997_
   
    22. How does CVS decide if it can safely perform a merge? 
    
   CVS can merge any text file, possibly discovering a conflict and
   leaving overlaps for you to edit. Editing the conflict markers out of
   the file is a moment's work, but resolving the conflict could take an
   arbitrary amount of time. CVS works to determine if it *should* merge,
   not if it *can*.
   
   See 2B.6 for how the merge proceeds.
   
   Last modified: _6/13/1997_
   
    23. After resolving merge conflicts in a file, what if I want to keep my
    previous version, and not take any of the branch changes? 
    
   If you want to retain your previous version, a version on the MAIN
   branch greater than 1.1 (one you committed there), just throw the
   merged file away and "cvs update" the file.
   
   You don't need to commit something to remember it. The tags you place
   before and after the merge should give all the handles you need to
   find various versions. You don't have to create a new version of the
   file.
   
   If you want to retain the previous Vendor revision, you can grab a
   copy of it using "cvs update -p" and commit it or use the technique
   described in 3B.3 to revert back to the Vendor branch.
   
   Last modified: _6/13/1997_
   
  Category: /Advanced_Topics_/Engineering/
  
   " + Engineering"
   
    1. Where can I find out about Software Engineering? 
    
   A couple different people suggested this book:
   
   Software Configuration Management: Coordination for Team Productivity;
   Wayne A. Babich; Addison Wesley; 1986; ISBN 0-201-10161-0
   
   A number of others suggested Appendix B of the book "Decline and Fall
   of the American Programmer" by Ed Yourdon, called "The Programmer's
   Bookshelf". It list 87 books you are expected to have read. Since they
   publish many of the books, Prentice-Hall distributes this list as
   "Prentice Hall Professional Technical reference PTR-125-AA3.
   
   One interesting item from the Yourdon book: The total number of
   professional computer books sold is less than the number of
   programmers currently in the United States. It wasn't clear from the
   book whether this meant "per year" or not, but it is still
   frightening.
   
   Last modified: _6/13/1997_
   
    2. How do I flexibly arrange the modules file to describe my sources? 
    
   An equivalent question might be, "How do I structure my sources?" This
   can be a difficult question especially in the areas that are more
   political than technical.
   
   Generally you want to think about which pieces of your system need to
   be checked out together, built as one system or tagged as a consistent
   whole. You should certainly create module names that correspond to
   complete, buildable collections that you would tag and release as one
   "product". It is also convenient to create module names for small
   sections of the Repository containing files that will all be worked on
   at the same time by the same person or group.
   
   Once you have defined the structure of your work, you can usually see
   how to lay it out in a Repository. After that the modules file is
   easy. You set up module names and aliases to match what you need to
   check out by name. If you like relative directories, it is possible,
   but not recommended, to work completely without a modules file. See
   1D.11 and 2C.7 for some info about the modules file.
   
   Here are a few types of modules. You should experiment to see what
   kind of structure each of these produces. They all have different
   uses.
   
     Connected projects in one group with two separate helper
   directories. The helper directories can contain build tools, header
   files, libraries, or whatever you like.
   
   These are all aliases that checkout relative pathnames. The equivalent
   results could be produced by placing the selected relative pathnames
   on the "cvs checkout" command line.
   
           pr1  -a P1 HELPERS
           pr2  -a P2 HELPERS
           pr3  -a P3 HELPERS
           pr12 -a P1 P2 HELPERS
           pr13 -a P1 P3 HELPERS
           pr23 -a P2 P3 HELPERS

           P1           -a group1/proj1
           P2           -a group1/proj2
           P3           -a group1/proj3
           HELPERS      -a group1/helper1 group1/helper2 MAKEFILE
           MAKEFILE     -a group1/Makefile

   Actual Repository directory structure: (from $CVSROOT down)
   
   group1/ Makefile The top level Makefile. helper1/ helper2/ Helper
   files and dirs proj1/ Files and dirs proj2/ Files and dirs proj3/
   Files and dirs
   
   "checkout group1" produces a duplicate of the above. "checkout projX"
   produces all but "projY" and "projZ". "checkout projXY" produces all
   but "projZ".
   
     Here is the exact same set of module names describing the same
   Repository layout using module names (and aliases containing module
   names) instead of merely aliases for relative pathnames.
   
   There is one difference in the result. The name of the top level
   directory in the checked out working tree w…