/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

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