/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 are truncated click here to view the full file
- -------------------------------------------------------------------------------
- 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…