PageRenderTime 133ms CodeModel.GetById 22ms RepoModel.GetById 1ms app.codeStats 1ms

/contrib/cvs/FAQ

https://bitbucket.org/freebsd/freebsd-head/
#! | 8562 lines | 5961 code | 2601 blank | 0 comment | 0 complexity | e7f68e8ccfbae0343c7cab0e4a374579 MD5 | raw file
Possible License(s): MPL-2.0-no-copyleft-exception, BSD-3-Clause, LGPL-2.0, LGPL-2.1, BSD-2-Clause, 0BSD, JSON, AGPL-1.0, GPL-2.0
  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 will match the "module" name
  850. (e.g. pr1) instead of always being "group1" as it was in the first
  851. example above.
  852. pr1 group1 proj1 &HELPERS
  853. pr2 group1 proj2 &HELPERS
  854. pr3 group1 proj3 &HELPERS
  855. pr12 group1 proj1 proj2 &HELPERS
  856. pr13 group1 proj1 proj3 &HELPERS
  857. pr23 group1 proj2 proj3 &HELPERS
  858. HELPERS -a helper1 helper2 group1-Makefile
  859. helper1 group1/helper1
  860. helper2 group1/helper2
  861. group1-Makefile -d . group1 Makefile
  862. The above line (with the -d in it) says that when the module named
  863. "group1-Makefile" is checked out, the file named Makefile file will be
  864. found in a directory named $CVSROOT/group1 and will be checked out
  865. into a directory named '.', which obviously already exists.
  866. The & references say to interpret those pathnames relative to the
  867. directory where the whole module is stored. For the "pr1" module, that
  868. directory is "group1", so the &HELPERS reference winds up placing
  869. Makefile in '.' relative to "group1".
  870. A short one containing the basic "module" actions:
  871. m1 head/path file1 dir2 file3 dir4 file5
  872. When checked out, a directory named "m1" appears in your current
  873. directory. Elements named file1, dir2, file3, dir4, and file5 appear
  874. in it. They were originally taken as relative paths from
  875. $CVSROOT/head/path.
  876. Here's another way to construct a working directory out of pieces of
  877. the Repository:
  878. projX projX Makefile &projX_inc &projX_src &projX_doc
  879. # The first line selects a single file within projX, plus
  880. # the contents of three other modules. Those three other
  881. # modules rename their directories.
  882. projX_inc -d include projX/inc projX_src -d source projX/src projX_doc
  883. -d documentation projX/doc
  884. A Unix tree. This is similar to what CVS was developed for and the
  885. way I have used it for years.
  886. # Top level
  887. unix unix
  888. u_bin unix/bin
  889. u_etc unix/etc
  890. u_man unix/man
  891. usr-bin unix/usr.bin
  892. # Subdirs of top level dirs. (tiny subset)
  893. ls unix/bin/ls
  894. fsck unix/etc/fsck
  895. man8 unix/man/man8
  896. # Programs without subdirs. (tiny subset)
  897. cat unix/bin Makefile cat.c
  898. uniq unix/usr.bin Makefile uniq.c
  899. # /usr/local/src
  900. localsrc localsrc
  901. gnu localsrc/gnu
  902. public localsrc/public
  903. X11 localsrc/X11
  904. # GNU and PD tools
  905. cvs localsrc/gnu/cvs
  906. emacs localsrc/gnu/emacs
  907. rcs localsrc/gnu/rcs
  908. btoa localsrc/public/btoa
  909. tcsh localsrc/public/tcsh
  910. # X11 related items.
  911. tvtwm localsrc/X11/contrib/tvtwm
  912. "unix" was checked out and built from the top down, using a set of
  913. Makefiles that knew about the whole structure. "localsrc" was kept
  914. checked out in /usr/local/src.
  915. At any time I could run "checkout ls" or "checkout cat" and get a
  916. simple directory with only that tool in it, plus a subset Makefile
  917. that knew how to build that tool against the installed (or alternate,
  918. via environment variables) headers and libraries.
  919. I found it very handy to be able to run "ls" and see the three tools I
  920. was porting that week.
  921. Last modified: _6/13/1997_
  922. 3. Can I have multiple source repositories, one for each project?
  923. Yes, you can have as many Repositories as you like. But each
  924. Repository must be managed separately, creating additional work.
  925. Question 4A.1 provides a short description of setting up a single
  926. Repository. A few additional considerations:
  927. It is a good idea to start by creating a single Repository and split
  928. it up (or create additional Repositories) only if you believe it is
  929. really necessary. I would only create a new Repository if the data is
  930. completely disconnected from the rest of the main Repository.
  931. If there is a lot of overlap among the developers working on the
  932. collections of files you want to place in different Repositories, or
  933. if there is any connection between those collections, I would go out
  934. of my way to create a single Repository. It is much easier to manage.
  935. Disk space should not be a factor since you can build up a
  936. Repository using symbolic links and/or remote mounts.
  937. Each Repository is completely distinct. You can't check out modules
  938. from different Repositories at the same time. A better way of looking
  939. at it is that if you *can* check out two modules or directories with a
  940. single "checkout" command (without contortions or explicit absolute
  941. pathnames), then they are in the same Repository.
  942. To "checkout" modules from multiple Repositories, you must use the
  943. "cvs -d" option on all CVS commands or alter your $CVSROOT variable
  944. when you change focus to another Repository. If you work with multiple
  945. Repositories, it is a good idea to configure CVS to use absolute
  946. pathnames in the ./CVS/Repository file, since most commands (other
  947. than "checkout") will use that file rather than $CVSROOT.
  948. If you configure CVS to use relative pathnames in your
  949. ./CVS/Repository files, you must always be careful to set your
  950. $CVSROOT properly or you will get unexpected results.
  951. If you have two modules or directories by the same name at the same
  952. relative path inside two different Repositories, you are asking for
  953. disaster. You could unexpectedly update a directory with completely
  954. unrelated files. This is not a fanciful example -- a Repository is
  955. occasionally duplicated for release purposes in which case *all* the
  956. paths in the two Repositories are the same.
  957. Last modified: _6/13/1997_
  958. 4. Who should administer the Repository and manage the modules file?
  959. This is a "management style" question. In large or traditional groups,
  960. the CVS procedures are warped to conform to local conventions. In
  961. small groups, in groups with strong personalities or on new projects
  962. the choice of source control procedures can help create some of the
  963. working environment. Here is a taxonomy of environments I have worked
  964. in or helped set up:
  965. Situation 1.
  966. A small number of competent developers working on a medium size
  967. project. We all got along and we all respected each other (at least
  968. technically). Anyone edited anything.
  969. Modules and Repository admin was mostly left to me. I never found a
  970. problem in minor changes made by anyone else.
  971. Situation 2.
  972. A large number of experienced developers sprinkled with wackos. Many
  973. of the developers didn't want to deal with any kind of source control.
  974. They wanted a full-service source control system that caused them zero
  975. thought.
  976. I learned "big stick" diplomacy here. There was a small number of
  977. "designated" (by me) people who were allowed to do *anything* other
  978. than "update" and "commit". Even "checkouts" were controlled. This is
  979. where I found "history" and "release" the most useful.
  980. Situation 3.
  981. A small number of developers who wanted me to "help", but who didn't
  982. want to deal with anything other than their favorite algorithms.
  983. I didn't have the time to baby-sit this group, so I designated one of
  984. them to be my official contact and made him do it all. He felt sullied
  985. by the requirement to pay attention to anything other than his pet
  986. coding projects, but enjoyed the "status" of being the only one who
  987. could touch the control files without my kicking the chair out from
  988. under him.
  989. Situation 4.
  990. A huge number of developers of covering the whole spectrum of
  991. competence and experience split into 20 groups, none of which
  992. cooperated with the others, working on 57 different projects, most of
  993. which didn't inter-operate.
  994. Managing it in any coherent way was not my responsibility (and beyond
  995. my tolerance for chaos). Too many people. So I privately designated a
  996. person in each group to be the contact and kept watch on the
  997. Repository activity. When something went wrong, I notified the contact
  998. for the group and told him what was happening and *he* kept his troops
  999. in line. They were tougher with their own group that I would have
  1000. been.
  1001. Eventually only a few people were willing to touch the control files,
  1002. since they were flamed from all directions if they screwed up.
  1003. Situation 5.
  1004. In a medium group of really *serious*, and seriously overworked,
  1005. people, someone else was designated the "master". I convinced the
  1006. master I knew what I was doing and went on my way.
  1007. No one else in the world was allowed to touch anything.
  1008. Situation 6.
  1009. In a large amorphous group of beginners, experts and clowns, over whom
  1010. no one had official control, I was forced to employ a group of
  1011. relative beginners (who became experts rather quickly) to police the
  1012. world. The ultimate in locking the barn after the horse was stolen, we
  1013. kept Chaos from destroying us only by use of superior firepower.
  1014. My choice, if allowed, is to let anyone touch anything. I keep backups
  1015. of important items and let people know individually whether I want
  1016. them to touch things or not. If someone on my "no touch" list touches
  1017. and succeeds, they are allowed more slack. If they screw up after
  1018. being warned, their screwup becomes public. After a few months, I
  1019. usually have no trouble keeping the world running smoothly, at least
  1020. from my (and CVS's) perspective.
  1021. Last modified: _6/13/1997_
  1022. 5. Isn't disk space a big factor? CVS copies files out of the Repository,
  1023. duplicating everything.
  1024. Everyone knows that disk space is getting cheaper. How do we reconcile
  1025. this with the equally well-known problem that *all* disk is *always*
  1026. filled up?
  1027. In my opinion, the main reason disk space will never be an unlimited
  1028. resource is that it is the major variable in organizational time/space
  1029. tradeoffs. It isn't a problem of waste or an aspect of Murphy's law,
  1030. as some claim it is, but rather a direct consequence of good
  1031. management. Disk space is, and will always be, a limited resource.
  1032. First, the cost of *deploying* that disk is not dropping as fast as
  1033. the cost of the storage medium. The cost of machines to hold the disks
  1034. and the networks to connect them are dropping more slowly than disk
  1035. media. And the cost of the human time necessary to manage the
  1036. machines, networks, disks, and the developers using them, is not
  1037. dropping at all. The cost of human time continues to rise.
  1038. If management decides that expensive human time can be saved by using
  1039. all that new disk space to keep the last three releases online, then
  1040. that's what it will be used for. If each release takes up a Gigabyte
  1041. and you support 30 platforms, a simple time-saving suggestion has just
  1042. grabbed 100 Gigabytes of disk space. And we've ignored the potential
  1043. disk storage needed to support "better Customer Service", another
  1044. management refrain.
  1045. Even at 30 cents per Megabyte (next year's price), you've just used up
  1046. $30,000 of disk space. And that doesn't count the computers, tape
  1047. drives and humans necessary to maintain and deploy all of it. Spending
  1048. money to save time has its own overhead, too.
  1049. Binaries are getting bigger. Graphics and data collection devices can
  1050. eat up any amount of disk. There are more tools available, more
  1051. libraries, more raw data than you can ever store. My home computer has
  1052. a Gigabyte of disk on it. It could easily handle 30.
  1053. The "economy" of disk storage media will never remove the need to
  1054. manage disk space.
  1055. So, here's an un-reviewed suggestion originally from Graydon Dodson
  1056. <grdodson@lexmark.com>, which I've altered and edited heavily.
  1057. - Keep a directory where the whole tree is checked out. (It might be
  1058. built and tested once in a while to make sure it is worth linking to,
  1059. but that doesn't affect the source control aspect of this procedure).
  1060. Let's call it /master/build.
  1061. - Write a tool that creates a tree of directories (like the X11
  1062. "lndir" command) filled with links to the checked out files in the
  1063. /master/build tree.
  1064. This tool should also provide real copies of, not symlinks to, all the
  1065. files within the CVS administrative directories.
  1066. - You could also provide a way for the tool to take a list of whole
  1067. directories that you will never change, for which it would create a
  1068. single symlink to the directory and not a subtree of symlinks to
  1069. files. Or you could rm -r pieces of the resulting working directory
  1070. yourself and replace it with links.
  1071. - If you want to edit a file, you have to grab a real copy and keep it
  1072. until your revision shows up in the /master/build tree. I'd create a
  1073. script to do this: cvsgrab <file>
  1074. #!/bin/csh -f
  1075. set f = $1
  1076. if (! -l $f) then
  1077. echo "file $f is not a symlink"
  1078. exit 1
  1079. endif
  1080. rm $f
  1081. set rev = `grep "^/$f/" CVS/Entries | awk -F/ '{print $3}'`
  1082. cvs update -p -r $rev $f > $f
  1083. You can't do a plain "cvs update" since that would grab newer
  1084. revisions from the Repository, not the revision you wanted to start
  1085. with. After the file is no longer a symlink, you can work normally.
  1086. You'll have to run "update" before "commit" anyway if there are newer
  1087. revisions.
  1088. - Presumably there would also be a tool to traverse the link tree and
  1089. revert it to links if there are no modified files and/or if all the
  1090. real files match the revision of the /master/build tree.
  1091. - To avoid confusing CVS when the /master/build revisions are updated
  1092. but your CVS/Entries files is not, CVS would have to change to handle
  1093. symlinks. It currently causes problems with this scenario:
  1094. ./<file> is a symlink.
  1095. ./CVS/Entries says you are revision 1.2.
  1096. The corresponding CVS/Entries file in /master/build says the latest
  1097. revision is 1.3.
  1098. cvs update <file> shows a 'C' conflict flag.
  1099. Last modified: _6/13/1997_
  1100. Category: /Advanced_Topics_/Installing_CVS/
  1101. " + Installing CVS"
  1102. 1. What do I have to do before I install CVS?
  1103. You must decide where to set up a Repository.
  1104. Though you can construct a Repository tree structure using links and
  1105. mount points, there must be a single copy of each real file across
  1106. your entire organization. You may not "rdist" files and expect to edit
  1107. both copies.
  1108. CVS does not support a truly distributed Repository. You can have
  1109. multiple Repositories, but each one must be mounted (not copied or
  1110. "rdist"ed) from a single place onto all machines where it will be
  1111. used.
  1112. Initially, a Repository takes about same amount of disk space as the
  1113. sources you want to put into it, plus a bit of overhead for the RCS
  1114. files.
  1115. See Section 4B. For multiple Repositories, see 4G.3
  1116. You need a directory in everyone's $PATH variable where you can
  1117. install all the executables. /usr/local/bin is a common place.
  1118. You need some helper tools besides CVS such as "RCS" and a good set
  1119. of "diff" and "diff3" programs. See 1B.4 for suggestions.
  1120. Read the README, INSTALL and ChangeLog files to see what you are
  1121. getting into.
  1122. Though you can probably muddle along without it, you should appoint
  1123. one or more "Repository Administrators" who will be responsible for
  1124. maintaining the Repository structure, administrative files and the
  1125. "modules" interface.
  1126. Someone at your site should probably be on the info-cvs mailing list.
  1127. See 1B.5.
  1128. Last modified: _6/13/1997_
  1129. 2. How do I configure the CVS programs?
  1130. You should certainly start by reading the README file, the INSTALL
  1131. files and possibly the ChangeLogs in each directory, the Makefile.in
  1132. files and the "cvsinit.sh" program.
  1133. Execute the ./configure command.
  1134. Type "make".
  1135. After running "make" you might try running the "sanity.sh" script:
  1136. ./src/sanity.sh `pwd`/src/cvs
  1137. It writes into /tmp/cvs-sanity by default.
  1138. Finish reading the INSTALL file and test out the system.
  1139. Last modified: _6/13/1997_
  1140. 3. What do I have to install?
  1141. Install the "cvs" executable and "mkmodules" from the CVS sources.
  1142. The man page is useful too. If you plan to report bugs, you should
  1143. also install "cvsbug".
  1144. Set your $CVSROOT environment variable and create the Repository
  1145. (which you planned out in 4A.1) with the "cvsinit" command at the top
  1146. of the CVS sources.
  1147. You'll need to edit the Repository control files created by
  1148. "cvsinit".
  1149. Install any helper programs mentioned in the modules file.
  1150. Last modified: _6/13/1997_
  1151. 4. How do I work around the merge problems in GNU diff version 2.1 or
  1152. later?
  1153. See 1B.4 If you use recent versions of RCS and "diff", you won't run
  1154. into the above. If you do, see 5B.8
  1155. Last modified: _6/13/1997_
  1156. Category: /Advanced_Topics_/Internal_errors/
  1157. " + Internal errors"
  1158. 1. Explain: "ci error: unexpected EOF in diff output"
  1159. RCS versions earlier than 5.5 print the above error when a file does
  1160. not end in a newline character. It can be caused by:
  1161. - Editing with Emacs and not using "require-final-newline".
  1162. - Committing a binary file.
  1163. - Filesystem failures (NFS!) that put nulls in your file.
  1164. The solution is to upgrade to RCS 5.5 or later. (Of course, this won't
  1165. fix filesystem failures. It will merely allow RCS (and therefore CVS)
  1166. to handle the file without error.)
  1167. Last modified: _6/13/1997_
  1168. 2. Explain: "RCS file /Repository/module/file.c,v is in use"
  1169. This is an RCS error that occurs when its internal lock file has been
  1170. left around by an RCS command interrupted by some sort of system
  1171. crash, disk failure or SIGKILL signal.
  1172. Go into the Repository and look for files with names similar to
  1173. "file.c,v", usually starting with ',', '_' or '#'. Make sure they are
  1174. really crash remnants and do not belong to transactions in progress --
  1175. a recent last-modified timestamp is a good indicator of a live
  1176. transaction. Delete them if they are old.
  1177. Last modified: _6/13/1997_
  1178. 3. Explain: "co error, line 2: Missing access list"
  1179. This is an error message from RCS Version 3 when it tries to read a
  1180. file created by a later version of RCS.
  1181. HP decided to "standardize" on an ancient version of RCS some time
  1182. ago. You can't use it for CVS. See 4H.6.
  1183. Since the error comes from having a later version of RCS than HP
  1184. supports, you probably did install the later version but must have
  1185. recently changed your $PATH or installed the HP package that has RCS
  1186. in it.
  1187. You should either reconfigure CVS to use absolute pathnames to the
  1188. proper versions of the RCS programs that CVS uses, or change your PATH
  1189. to look there first. If you haven't installed the latest version of
  1190. RCS, you should upgrade. See 1B.4
  1191. Last modified: _6/13/1997_
  1192. 4. Explain: "error: RCS file name `xyz .c' contains white space"
  1193. RCS 5.6 doesn't allow white space in filenames. Apparently this
  1194. restriction will be removed in RCS 5.7, but CVS may still require that
  1195. filenames have no white space in them.
  1196. Last modified: _6/13/1997_
  1197. 5. Explain: cvs checkout: warning: <X> is not (any longer) pertinent
  1198. This message occurs in three instances:
  1199. When there is an entry in the ./CVS/Entries for file <X> and there
  1200. is no RCS file in the Repository to back it up.
  1201. If the working file exists, and hasn't changed (determined from the
  1202. timestamp) it is removed.
  1203. When you try to check out a piece of the Repository with:
  1204. cvs checkout some/place/in/repository/tree
  1205. and at least the first element of the path (i.e. "some" in the above)
  1206. exists, but some part of the rest of it does not.
  1207. The checkout command checks the modules file first for the whole path,
  1208. then for a prefix of the path as a module name. If it doesn't find
  1209. *any* portion of your path in the modules file, it says:
  1210. cvs checkout: cannot find module `<module/path>' - ignored
  1211. If it finds some set of prefix directories, it prints the message you
  1212. see.
  1213. In practice this is usually a spelling error.
  1214. If the Repository files you are trying to check out or update are
  1215. not readable by you, the same problems can occur. Check the
  1216. permissions on the files involved.
  1217. Last modified: _6/13/1997_
  1218. 6. Why did a Repository file change from <file>,v to ,<file>,?
  1219. This is an RCS problem, since the ,<file>, syntax for file names is
  1220. used by RCS and not CVS.
  1221. RCS constructs a new <file>,v in a temporary file named ,<file>,
  1222. (which doubles as a lock file) then renames it to <file>,v when it is
  1223. done. The only way this is reliable is if your system's version of
  1224. rename(2) is an atomic, as required by POSIX.
  1225. If your system has a non-atomic (and therefore non-POSIX) rename(2)
  1226. system call, RCS runs uses an internal version of this algorithm to
  1227. approximate the atomic rename:
  1228. rm <file>,v; ln ,<file>, <file>,v; rm ,<file>,
  1229. If the system crashes, or you lose your NFS connection between the
  1230. first "rm", but before the "ln", you can be left only with the
  1231. ,<file>, file. If the crash or network failure occurs between the "ln"
  1232. and the final "rm", you could be left with a pair of linked names.
  1233. Recovery:
  1234. - If only the ,<file>, exists, rename it to <file>,v.
  1235. - If both ,<file>, and <file>,v exist and are linked, remove the
  1236. ,<file>, file.
  1237. - If both ,<file>, and <file>,v exist and are separate files, look at
  1238. the dates, "diff" them and make your best guess. This sounds like the
  1239. remnants of two separate events.
  1240. Last modified: _6/13/1997_
  1241. Category: /Advanced_Topics_/Other_Systems/
  1242. " + Other Systems"
  1243. 1. I use a NeXT. Is there anything I need to know?
  1244. NeXTSTEP 3.0's Interface Builder uses "nib" directories, rather than
  1245. the files used in previous revisions. It removes files it doesn't
  1246. recognize, making it impossible to place such a directory under CVS --
  1247. the CVS admin directory will be removed.
  1248. Some time ago, <Bob_Vadnais@pdh.com> posted a palette named CVSPalette
  1249. that claimed to resolve this problem. It was intended to preserve the
  1250. CVS administrative directories within nib documents (directories) that
  1251. Interface Builder usually removes.
  1252. CVSPalette is no longer in its announced place:
  1253. ftp.cs.orst.edu:/pub/next/submissions
  1254. though I did find two other interesting files on ftp.cs.orst.edu:
  1255. /software/NeXT/sources/tools/cvs-next-2_1_1.tar.Z
  1256. which is a port of CVS 1.3 (along with RCS and diff) and:
  1257. /software/NeXT/sources/programming/cvs.postamble-2.4.gz
  1258. which appears to be a set of wrappers for CVS commands that claim to
  1259. allow you to use CVS effectively (and without need for the "command
  1260. line") on a NeXT machine.
  1261. [[Anyone know the truth about CVS and NeXT?]]
  1262. Last modified: _6/13/1997_
  1263. 2. I use OS/2 and/or DOS and/or Windows. Is there anything I need to know?
  1264. When using a local repository, be sure to specify the local access
  1265. method or CVS will interpret the drive letter as a remote host name
  1266. due to the : following it:
  1267. WRONG: CVSROOT=C:\SRC\CVSROOT
  1268. RIGHT: CVSROOT=:local:C:\SRC\CVSROOT
  1269. (larry.jones@sdrc.com)
  1270. You can share RCS files between Unix and DOS while avoiding the MS-DOS
  1271. file name limits by setting your RCSINIT environment variable to
  1272. '-x/,v'. New RCS files will be created without the standard ",v"
  1273. suffix, though files ending in ",v" will still be found if there is no
  1274. matching file in the same directory without the ",v".
  1275. Erik van Linstee offers an OS/2 and a DOS port of CVS 1.3 in:
  1276. ftp.informatik.tu-muenchen.de:/pub/comp/os/os2/gnu/devtools or
  1277. ftp.rrzn.uni-hannover.de:/pub/os2-local
  1278. The files are named:
  1279. cvs13p?[bs].zip
  1280. Where the ? stands for the patch level (currently 8) and the b is for
  1281. the binaries, the s for the sources.
  1282. There are three binaries. An OS/2 only one (32-bit), a DOS only one
  1283. (16-bit) and an EMX one that runs on both (32-bit).
  1284. There are many differences between the Unix and the DOS versions of
  1285. CVS. Read the material that comes with the DOS version before using
  1286. it.
  1287. [[Updates?]].
  1288. Last modified: _9/22/1997_
  1289. 3. I use SCO Unix. Is there anything I need to know?
  1290. On SCO/UNIX 3.2 V2.0 POSIX signals don't work. Unfortunately the
  1291. configure program detects POSIXness and configures in the use of POSIX
  1292. signals. Workaround : Edit out the check for POSIXness in the
  1293. configure script. [[You could also remove all occurrences of
  1294. "-DPOSIX=1" from the Makefiles after configure is run. -dgg-]]
  1295. SCO/UNIX doesn't understand #!/<some shell> syntax. This breaks the
  1296. use of log.pl as it gets invoked by /bin/sh instead of
  1297. !#/usr/local/bin/perl. WorkAround : edit log.pl and change it into a
  1298. shell script which invokes perl with log.perl (renamed from log.pl) as
  1299. input.
  1300. Contributed by Joe Drumgoole
  1301. Last modified: _6/13/1997_
  1302. 4. I use AIX. Is there anything I need to know?
  1303. The only report on AIX claims to have no trouble using it in concert
  1304. with SunOS and IRIX platforms.
  1305. Last modified: _6/13/1997_
  1306. 5. I use IRIX. Is there anything I need to know?
  1307. If you see "uid" numbers where you would expect user names, try adding
  1308. -lsun to the link line. Without it CVS is unable to retrieve "passwd"
  1309. data through NIS.
  1310. Last modified: _6/13/1997_
  1311. 6. I use an HP system. Is there anything I need to know?
  1312. HP distributes RCS version 3 (a circa 1983 release!) with HP-UX. CVS
  1313. does not work with RCS version 3; it requires RCS version 4 or later.
  1314. Your best bet is to find the latest version of RCS and install it
  1315. somewhere.
  1316. HP-UX 8.07 has a serious bug with the mmap system call and NFS files;
  1317. the bug can crash the operating system. Make sure that you configure
  1318. RCS to avoid mmap by setting has_mmap to 0 in RCS's conf.h. This bug
  1319. is fixed in HP-UX 9.
  1320. Contributed by Paul Eggert
  1321. If using the setgid() trick described in 4D.13, you will have to
  1322. create an entry in the /etc/privgroup file to give the group assigned
  1323. to the cvs executable setgid permission (see setprivgrp(1m)).
  1324. Additionally, if you are restricting "read" access to the Repository
  1325. by limiting access to the executable (this requires yet another
  1326. group), then you will require that /etc/logingroup exists and is
  1327. configured correctly (usually it's just alink to /etc/group).
  1328. Contributed by Dale Woolridge
  1329. Last modified: _6/13/1997_
  1330. 7. I use AFS. Is there anything I need to know?
  1331. There is a problem with the way CVS performs its locking when the
  1332. files are within AFS. When your current PTS id != your uid, the locks
  1333. are not deleted. The stat() system call returns the PTS id of the
  1334. owner. If that id != your uid, CVS assumes you did not lock it, and
  1335. leaves the lock files alone. The next time you try to use it, it
  1336. complains that someone has the repository locked.
  1337. Contributed by Michael Ganzberger
  1338. [[This was against CVS 1.3. Is it still in CVS 1.4?]]
  1339. Last modified: _6/13/1997_
  1340. 8. I use A/UX. Is there anything I need to know?
  1341. [[??]]
  1342. Last modified: _6/13/1997_
  1343. Category: /Advanced_Topics_/Related_Software/
  1344. " + Related Software"
  1345. 1. How do I use CVS under Emacs? Is there an Emacs cvs-mode?
  1346. The pcl-cvs package distributed with CVS is an emacs package that
  1347. helps with the update/commit process. When you are ready to update,
  1348. you use the 'cvs-update' command within emacs. This executes "update"
  1349. and fills a cvs-mode buffer with a line for each file that changed.
  1350. The most helpful features are: descriptive words for what happened
  1351. (i.e. Merged or Conflict rather than 'U' or 'C'), single keys bound to
  1352. diffs and commits, and the ability to mark arbitrary groups of files,
  1353. possibly from different directories, for commit as a whole.
  1354. All the developers in my group that use emacs find pcl-cvs a much
  1355. friendlier and more helpful way to update/commit than raw cvs. One vi
  1356. user even converted to emacs just to use pcl-cvs.
  1357. Contributed by Jeffrey M Loomis
  1358. Last modified: _6/13/1997_
  1359. 2. What is GIC (Graphical Interface to CVS)?
  1360. GIC provides a graphical user interface to the Concurrent Version
  1361. System (CVS), a powerful revision control system. GIC is
  1362. implemented in the Tcl/Tk programming language and is intended to
  1363. augment the sometimes cumbersome CVS command line interface.
  1364. Note that according to the official GIC page at
  1365. http://www.cpsc.ucalgary.ca/redirect/grouplab/projects/gic/
  1366. GIC is no longer being maintained and tkCVS is recommended
  1367. instead.
  1368. For more on tkCVS, see
  1369. <http://ximbiot.com/cvs/cvshome/dev/addontkcvs.html>.
  1370. kingdon@cyclic.com
  1371. Last modified: _9/6/1997_
  1372. 3. What is CAVEMAN?
  1373. CAVEMAN is a front end to CVS written in PERL providing a collection
  1374. of features desired by the site where it was developed.
  1375. - The ability to spread a "project" over multiple Repositories.
  1376. - Optional automatic tagging after each commit.
  1377. - Additional locking of files.
  1378. - Extra before and after program hooks.
  1379. - A layer of event logging.
  1380. - All sorts of error messages.
  1381. - Many changes to the semantics of commands.
  1382. It is available via anonymous ftp on ftp.llnl.gov [128.115.54.18] in
  1383. gnu/caveman_vX.Y.Z.tar.gz (The numbers X, Y, & Z vary.)
  1384. contact Kathleen Dyer kdyer@llnl.gov
  1385. (510)423-6803
  1386. (510)423-5112 FAX
  1387. [[Does someone want to elaborate?]]
  1388. Last modified: _6/13/1997_
  1389. Category: /Advanced_Topics_/Setting_up_and_Manag/
  1390. " + Setting up and Managing the Repository"
  1391. 1. What do I do first? How do I create a Repository?
  1392. First, install all the programs. (See Section 4A.)
  1393. Then create a Repository by executing "cvs -d init". (This works with
  1394. CVS 1.9.)
  1395. Now you can configure your repository by checking out CVSROOT: "cvs -d
  1396. checkout CVSROOT". Change into the created directory CVSROOT. Edit the
  1397. files you want to edit, and afterwards, commit the changes by typing
  1398. "cvs commit".
  1399. You will certainly want to add modules of your own. Edit the "modules"
  1400. file and add lines to describe the items you want to "checkout" by
  1401. module name. Here's a short list that could be used for storing a
  1402. small number of GNU and PD sources:
  1403. local local
  1404. gnu local/gnu
  1405. emacs local/gnu/emacs
  1406. cvs local/gnu/cvs
  1407. public local/public
  1408. pdprog1 local/public/pdprog1
  1409. pdprog2 local/public/pdprog2
  1410. test test
  1411. junk test/junk
  1412. Andreas Kostyrka
  1413. Last modified: _4/21/1998_
  1414. 2. What are those files in $CVSROOT/CVSROOT?
  1415. There are eight Repository control (or "database") files of interest
  1416. in the CVSROOT directory:
  1417. modules contains the "modules" database. See 1D.11, 2C.7, 4B.6 and
  1418. 4B.7 for more details.
  1419. commitinfo contains two columns: 1. a regular expression to match
  1420. against pathnames within the Repository and
  1421. a <command> to execute for matching pathnames.
  1422. When you execute "commit", CVS passes the Repository pathname for each
  1423. directory (and the files to commit within that directory) to
  1424. <command>. If <command> exits with a non-zero status, the commit is
  1425. blocked.
  1426. A <command> associated with a pathname of "DEFAULT" is executed if
  1427. nothing else matches. Every <command> associated with a pathname of
  1428. "ALL" is executed separately.
  1429. rcsinfo contains the same first column as commitinfo, but the second
  1430. column is a template file for specifying the log entry you are
  1431. required to enter for each commit.
  1432. "DEFAULT" and "ALL" work the same as in the commitinfo file.
  1433. editinfo contains the same two columns as commitinfo, but the
  1434. <command> in the second column is intended to do some consistency
  1435. checking on the commit log.
  1436. "DEFAULT" works as in commitinfo.
  1437. loginfo contains the same two columns as commitinfo, but the
  1438. <command> is expected to read a log message from its standard input.
  1439. The <command> can do anything it wants with the log information, but
  1440. normally it is appended to a log file or sent to mailing lists.
  1441. "DEFAULT" & "ALL" work the same as in commitinfo.
  1442. cvsignore contains "ignore" patterns that are added to the built-in
  1443. ignore list. See 2D.10.
  1444. checkoutlist contains a list of other files kept under RCS in
  1445. $CVSROOT/CVSROOT that should be checked out by mkmodules to provide a
  1446. readable copy.
  1447. history contains a stream of text records, one for each event that
  1448. the "history" command is interested in. Though the contents of the
  1449. history file can be read, it is intended to be read and displayed by
  1450. the "history" command. This file is the only one in the above list
  1451. that is not under RCS.
  1452. Last modified: _6/13/1997_
  1453. 3. Is there any other state stored in the Repository besides in the
  1454. $CVSROOT/CVSROOT directory?
  1455. Only in the RCS files. The Repository holds exactly two things: the
  1456. tree of RCS files (each usually ending in ",v") and the CVSROOT
  1457. directory described above.
  1458. Last modified: _6/13/1997_
  1459. 4. How do I put sources into the Repository?
  1460. There are three main ways to put files in the Repository:
  1461. Use the "import" command described in Section 3H.
  1462. This method is the fastest way to put trees of new code into the
  1463. Repository and the *only* way to handle source releases from a 3rd
  1464. party software vendor.
  1465. Use "add" followed by "commit".
  1466. This is how to add new files and directories to the Repository, a few
  1467. at a time. Directories don't need to be committed.
  1468. You can move RCS files directly into the Repository.
  1469. You should create a directory hierarchy to hold them, but you can just
  1470. move arbitrary ",v" files into the Repository. The only "state" in the
  1471. Repository other than within ",v" files is in the required CVSROOT
  1472. directory at the top of the Repository.
  1473. Last modified: _6/13/1997_
  1474. 5. What file permissions should I use on (and in) the Repository?
  1475. If you are using pserver (password-authenticated access), see below.
  1476. If you run a completely open environment (which usually means that you
  1477. don't have, or don't want to waste, the time to deal with it):
  1478. - Set all directory permissions to 777.
  1479. - Have everyone set their umasks to 0.
  1480. (BTW, I don't suggest this. I am merely reporting it.)
  1481. If you are a normal Unix shop and want to use groups effectively:
  1482. - Set all the directory permissions in the Repository to 775.
  1483. If you are using a system that handles both System V and BSD
  1484. filesystems, you might have to set the permissions to 2775.)
  1485. If you are using one of the many recent versions of Unix that don't
  1486. allow you to use the full octal mode, then you'll have to type: chmod
  1487. u=rwx,g=rwx,o=rx,g+s dir&gt;
  1488. - Change all the groups on the directories to match the groups you
  1489. want to write to various directories.
  1490. - Make sure every user is in the appropriate groups.
  1491. - Have everyone set their umask to 002, including root.
  1492. If you don't want non-group members to even read the files, do the
  1493. above, but change:
  1494. - Repository directory permissions to 770. (or 2770)
  1495. - umasks to 007.
  1496. If you work in an environment where people can't be trusted to set
  1497. their "umask" to something reasonable, you might want to set the umask
  1498. for them:
  1499. mv /usr/local/bin/cvs /usr/local/bin/cvs.real
  1500. cat > /usr/local/bin/cvs
  1501. #!/bin/sh
  1502. umask 2 # Or whatever your site standard is.
  1503. exec /usr/local/bin/cvs.real ${1+"$@"}
  1504. ^D
  1505. Pserver (Password-Authenticated Access) &lt;blome@de.ibm.com&gt;
  1506. The above suggestions are not valid when you use the pserver facility.
  1507. Be sure to read and understand the manual section about this (should
  1508. be 4.6.something). Above all: do /not/ make the repository and CVSROOT
  1509. group writeable. In CVSROOT, make `history´ group or world writeable
  1510. instead.
  1511. I suggest creating one unix group per project group. In the
  1512. repository, you would then create one directory for each group, group
  1513. writeable. New projects must then be created in these group
  1514. directories. If you don't want to say &lt;group&gt;/&lt;project&gt; on
  1515. checkout, create a &lt;project&gt; module and point it there.
  1516. Last modified: _9/24/1998_
  1517. 6. How do I structure my Repository?
  1518. The Repository holds your software. It can be all interrelated or it
  1519. can be a bunch of separately managed directories.
  1520. How you break a whole system down into its component parts, while
  1521. defining interfaces between them, is one aspect of "Software
  1522. Engineering", a discipline that requires the study of dozens of
  1523. strange and wonderful areas of the computer and management worlds.
  1524. CVS provides a way to keep track of changes to individual files, a way
  1525. to "tag" collections of files, and a way to "name" collections of
  1526. files and directories. That's all. Everything else is in the way you
  1527. apply it.
  1528. In other words, you should structure your Repository to match your
  1529. needs, usually tied in with the other tools you use to build, install
  1530. and distribute your work. Common needs include the ability to:
  1531. - mount (or automount) directories from many places in your
  1532. organization.
  1533. - check out just what you need and no more.
  1534. - check out multiple sections in a fixed relation to each other.
  1535. - check out large sections to match the assumptions built into your
  1536. build system. (Makefiles?)
  1537. In my opinion, you should start small and keep everything in one tree,
  1538. placing each major sub-system into a separate directory. Later, when
  1539. you know what you are doing, you can make it more sophisticated.
  1540. Last modified: _6/13/1997_
  1541. 7. Why would anyone use "modules"? They are too restrictive. I want to be
  1542. able to select just the files I want to edit.
  1543. Any form of structure is restrictive. If you believe that total chaos
  1544. is a viable working paradigm, or if you believe you can keep track of
  1545. the interrelations between all portions of your Repository in your
  1546. head, then you can do what you please.
  1547. If you believe that systems of files require management and structure,
  1548. then the "modules" idea is very useful. It is a way to impose a naming
  1549. scheme on a tree of files, a naming scheme that can be simpler than a
  1550. large list of relative pathnames.
  1551. The "modules" file represents a published interface to the Repository
  1552. set up by your Repository Administrator. If s/he did a creditable job,
  1553. the modules offered will be internally consistent and will smoothly
  1554. interact with the rest of your environment.
  1555. Last modified: _6/13/1997_
  1556. 8. How do I rename a file or directory? What are the consequences?
  1557. In CVS there is no single "rename" command.
  1558. See 2C.4 for the suggested way to rename a file or directory.
  1559. The rest of this section covers some of the consequences of renaming.
  1560. A "renaming database" has been proposed that would keep track of name
  1561. changes so that "update -r <tag>" would continue to work across the
  1562. renaming. But as it stands, you have to pick one of the following
  1563. options:
  1564. Use the technique described in 2C.4. (For each file, duplicate the
  1565. file in the Repository, "remove" the old version so it winds up in the
  1566. Attic and strip all Tags off the new version.)
  1567. - "update -r <tag>" produces the correct files.
  1568. - The duplicated revision history can be slightly misleading.
  1569. - A plain (i.e. without the "-r <tag>") "checkout" or "update -d" will
  1570. create directories "renamed" this way, but you can delete it and a
  1571. plain "update" won't bring it back.
  1572. Move the files and directories in the Repository to the new names.
  1573. - You save the revision history under a different file name.
  1574. - You save a little space.
  1575. - "update -r <tag>" produces the wrong files or directories.
  1576. This is not a good general solution, but if you plan never to look
  1577. back (someone may be gaining on you!), it is sometimes a useful
  1578. notion.
  1579. If you are clever with Makefiles, you might be able to rework them to
  1580. handle either the new or old names, depending on which ones exist at
  1581. the time. Then you can move an old <tag> onto the new, more
  1582. sophisticated, revision of the Makefile. (Yes, this changes the
  1583. "released" file if <tag> indicates a release. But it is an option.)
  1584. - Important Note: If you rename a directory, you must rename the
  1585. corresponding directory in every checked-out working directory. At the
  1586. same time, you must edit the pathname stored in the ./CVS/Repository
  1587. file within each of the moved directories.
  1588. The easiest way to move a lot of directories around is to tell
  1589. everyone to remove their working directories and check them out again
  1590. from scratch.
  1591. - The file exists in the working directory and in the ./CVS/Entries
  1592. file, but not in the Repository. For the old file, "update" prints:
  1593. cvs update: xyz.c is no longer in the repository
  1594. and deletes the file. If the file was modified, "update" prints:
  1595. cvs update: conflict: xyz.c is modified but no longer in the
  1596. repository C xyz.c
  1597. and leaves the file alone. In the new directory, you see:
  1598. U xyz.c
  1599. as you would if someone else executed "add" and "commit".
  1600. For each file, copy the working file to a new name in the working
  1601. directory and use the "cvs remove" to get rid of the old old file and
  1602. "cvs add" to add the new one. Since there is no way for CVS to remove
  1603. a directory, this only works for files.
  1604. - This is what most people think of first. Without a "rename" command,
  1605. the remove/add technique seems obvious.
  1606. - You lose the connection of your new working file to its past
  1607. revision history.
  1608. Last modified: _6/13/1997_
  1609. 9. What are "Attic" directories?
  1610. When you use the "remove" command on a file, CVS doesn't delete the
  1611. file, it only registers your desire to delete it.
  1612. When you "commit" a removed file, CVS moves the Repository's matching
  1613. RCS file into a sub-directory named "Attic" within the Repository.
  1614. Attic files are examined when the '-r' or '-D' option is used on
  1615. "checkout" or "update". If the specified revision, tag or date matches
  1616. one on a file in the Attic, that file is checked out with the others.
  1617. You can think of the Attic as a sort of dead branch, which is only
  1618. looked at when you refer to a <tag> or <date>.
  1619. Last modified: _6/13/1997_
  1620. 10. Is it OK to remove anything from the Repository?
  1621. In general, removing anything from the Repository is a bad idea. The
  1622. information in a deleted object is lost forever. There are many ways
  1623. to skip over files, directories and revisions without deleting them.
  1624. Here are some of the consequences of removing the following things
  1625. stored in the Repository:
  1626. CVSROOT files (Repository control files)
  1627. The Repository will work without any of them, but you should
  1628. understand what you are losing by deleting them. See 4B.2.
  1629. Revisions
  1630. The only way to remove revisions is to use the "admin -o" command (or
  1631. the equivalent RCS command "rcs -o").
  1632. They are lost forever. Any tags formerly attached to deleted revisions
  1633. are now pointing into the Phantom Zone. You'll need to contact Jor-el
  1634. to get them back.
  1635. Files
  1636. You should not remove a file unless you truly never want to see it
  1637. again. If you want to be able to check out an old revision of this
  1638. file, use "cvs remove" instead.
  1639. Tags
  1640. Tags take up little space and you can't recover from deleting them. If
  1641. you depend on tags for releases you will lose vital information.
  1642. Directories
  1643. There is no Attic for directories, so the only way to remove them is
  1644. to use "rm -r". They are gone forever.
  1645. If you delete (or move) a directory, all checked-out versions of that
  1646. directory will cause CVS to halt. You'll have to visit each
  1647. checked-out directory and remove the matching working directory by
  1648. hand.
  1649. Attic files
  1650. The "remove" command sends files to the Attic. To really delete them,
  1651. you have to go into the Attic and use "rm".
  1652. If a file in the Attic has a Tag on it that you might ever want to
  1653. check out again, you probably don't want to delete it.
  1654. Lock files (named: "#cvs.[wr]fl.<pid>")
  1655. These are lock files. If you are getting "lock" errors and the dates
  1656. on the lock files indicate that they are old, you can delete them.
  1657. Deleting lock files still in use by a CVS process might produce
  1658. unusual errors.
  1659. Last modified: _6/13/1997_
  1660. 11. Can I convert to CVS from RCS without losing my revision history?
  1661. Yes, you can simply move (or copy) your RCS files into a directory
  1662. within the Repository, check out that directory and start working.
  1663. Last modified: _6/13/1997_
  1664. 12. Can I move RCS files with branches in them into the Repository?
  1665. Yes, but they may not work if you created branches in a way that
  1666. conflicts with CVS's assumptions:
  1667. You can't use .0. branches. (They are reserved for "Magic" branch
  1668. tags.)
  1669. If you use branch 1.1.1, you can't use the Vendor branch.
  1670. You can use other RCS branches under CVS. There is no need to create
  1671. "magic" branch tags because the physical branch already exists.
  1672. Last modified: _6/13/1997_
  1673. 13. Can I use raw RCS commands on the Repository?
  1674. You can use raw rcs commands directly on the Repository if you take a
  1675. little care. The Repository itself contains no "CVS state" (as opposed
  1676. to RCS revision histories) outside the CVSROOT directory.
  1677. But using raw RCS commands to change branches, tags or other things
  1678. that CVS depends on may render the files unusable.
  1679. See 4D.7 on RCS/CVS sharing of the Repository and Section 3B on the
  1680. "admin" command.
  1681. Last modified: _6/13/1997_
  1682. 14. How do I convert from SCCS to RCS?
  1683. You'll have to execute something like "sccs2rcs" (in the CVS contrib
  1684. directory) on every file. Then you can move the resulting RCS files
  1685. into the Repository as described above.
  1686. Last modified: _6/13/1997_
  1687. 15. How do I limit access to the Repository?
  1688. There are all sorts of ways to restrict access to Repository files,
  1689. none of which are hooked directly into CVS.
  1690. Techniques for limiting access include:
  1691. Training, management and good backups.
  1692. The best form of Repository control is a combination of:
  1693. - A reliable backup scheme (verify it!)
  1694. - Enough training to ensure your developers are competent and
  1695. knowledgeable about all areas of your sources.
  1696. - Effective management of the boundaries and grey areas.
  1697. In many cases, technical solutions to "security" problems are
  1698. inadequate. You should first try to avoid them.
  1699. Personal Opinion: In an environment where "unknowns" are allowed to
  1700. touch important sources the "owner" of the CVS Repository must be a
  1701. large, loud, vigorous lout with a well-balanced truncheon and the
  1702. right to use it. Don't underestimate the effectiveness of letting
  1703. everyone know they will be strapped into the stocks on the Town Common
  1704. and pelted with vegetables if they break something they don't
  1705. understand without first asking the experts.
  1706. Set Unix groups and permissions. See 4B.5. You can set different
  1707. owners, groups and permissions for each sub-directory within the
  1708. Repository if that helps.
  1709. Catch invocations of "commit" by defining pre-commit programs in the
  1710. "commitinfo" file. This is fairly powerful, since it can block commits
  1711. based on anything you can program. Take a look at the programs in the
  1712. "contrib" directory of the CVS source tree.
  1713. Use multiple Repositories, each with its own protection scheme. If
  1714. you use NFS (or AFS) you can even use "export" restrictions to various
  1715. groups of machines to keep (for example) the Engineering Repository
  1716. off the Customer Service machines.
  1717. Try the "setgid" trick described in 4D.13.
  1718. Try to use the RCS access control lists, though I don't think CVS
  1719. will handle them cleanly.
  1720. Edit the source code to CVS to add your own access control.
  1721. Last modified: _6/13/1997_
  1722. 16. What are the Repository Administrator's responsibilities?
  1723. Generally, the Administrator should set "policy", create the
  1724. Repository and monitor its size and control files.
  1725. Some specific responsibilities include:
  1726. Examining the Repository once in a while to clean up:
  1727. Trash files left by misguided developers who mistake the Repository
  1728. for a working directory.
  1729. Non-RCS files. Other than the files CVS needs in the
  1730. $CVSROOT/CVSROOT directory, every file in the Repository should be an
  1731. RCS file.
  1732. Lock files (both CVS '#*' and RCS ',*' files) left around after
  1733. crashes.
  1734. Wrong permissions, groups and ownerships.
  1735. Locked files. (RCS locks, that is.)
  1736. Attic files that should never have been under CVS at all. Don't
  1737. blindly delete files from Attic directories -- they were mostly put
  1738. there (via the "cvs remove") for a reason. Files that should be
  1739. deleted are binary files (e.g. '*.o', 'core', executables) that were
  1740. mistakenly inserted by "import -I !".
  1741. Maintaining the modules file.
  1742. Storing site-specific ignore patterns in the
  1743. $CVSROOT/CVSROOT/cvsignore file.
  1744. Storing the names of non-standard CVSROOT files (See 4B.2) in the
  1745. $CVSROOT/CVSROOT/checkoutlist
  1746. Maintaining the other Repository control files: commitinfo, loginfo,
  1747. rcsinfo and editinfo.
  1748. Pruning the history file every once in a while. (Try the
  1749. "cln_hist.pl" script in the "contrib" directory.)
  1750. Staying aware of developments on the info-cvs mailing list and what
  1751. is available in the FTP and WWW archives.
  1752. Running "ps ax" once in a while and kill off any "update" programs
  1753. not running as "root". It is too easy to leave the "cvs" off the front
  1754. of the "cvs update" command.
  1755. Executing monitor programs to check the internal consistency of the
  1756. Repository files. Ideas:
  1757. Files that have a default RCS branch that is not 1.1.1 (From an
  1758. abuse of "admin -b".)
  1759. Files that have only Revisions 1.1 and 1.1.1.1, with a default
  1760. branch of "MAIN". (From an abuse of "admin -o".)
  1761. Existing branch tags and various branch consistency checks.
  1762. Last modified: _6/13/1997_
  1763. 17. How do I move the whole Repository?
  1764. Copy or move the tree. (On Unix systems, a set of piped "tar" commands
  1765. works great. If the Repository does not contain any symlinks, which it
  1766. normally doesn't, you can also use "cp -r".)
  1767. If you can avoid changing $CVSROOT (i.e. the "logical" pathname of the
  1768. Repository) by replacing the old location with a symbolic link to the
  1769. new location, you don't have to do anything else.
  1770. (You could also mount the new location on top of the old location if
  1771. you are using NFS or some other filesystem that allows it.)
  1772. If you must change $CVSROOT, you must also tell everyone to change the
  1773. CVSROOT environment variable in all running shells and in any personal
  1774. configuration files ('.' files on Unix) where it is set.
  1775. The Repository itself contains no references to its own name, except
  1776. possibly in some of the files in the CVSROOT directory. If your
  1777. modules (or loginfo, commitinfo, etc.) file mentions helper programs
  1778. directly in the Repository, you'll have to change the pathnames to
  1779. point to the new Repository location.
  1780. The main changes you'll have to make are to all the CVS administrative
  1781. files (./CVS/Repository and ./CVS/Root) in every working directory
  1782. ever checked out from the previous location of the Repository you just
  1783. moved.
  1784. You have three choices:
  1785. If all ./CVS/Repository files in all working directories contain
  1786. relative pathnames, you don't have to do anything else.
  1787. Have everyone "release" or delete their working directories (after
  1788. committing, or just saving, their work) and check them all out again
  1789. from the new Repository after the move.
  1790. Use "find . ( -name Repository -o -name Root )" and a PERL or shell
  1791. script to run through all the ./CVS/Repository and ./CVS/Root files
  1792. and edit the values in the files.
  1793. Last modified: _6/13/1997_
  1794. 18. How do I change permissions on a file in the Repository by using a CVS
  1795. command? (i.e. without using "chmod 777 $CVSROOT/dir/file")
  1796. When you first "import" or "add"/"commit" a file, the read and execute
  1797. bits on the Repository file are inherited from the original source
  1798. file, while the write bits on the Repository file are are turned off.
  1799. This is a standard RCS action.
  1800. After that, there is no way to alter the permissions on a file in the
  1801. Repository using CVS (or RCS) commands. You have to change the
  1802. permissions on both your working file and on the Repository file from
  1803. which it was retrieved.
  1804. Whenever you "checkout" the file or retrieve a new revision via
  1805. "update" (or after a "commit"), your working file is set to match the
  1806. permissions of the Repository file, minus any "umask" bits you have
  1807. set.
  1808. Last modified: _6/13/1997_
  1809. Category: /Advanced_Topics_/Tricks_of_the_Trade/
  1810. " + Tricks of the Trade"
  1811. 1. How can you even check in binary files, let alone allow CVS to do its
  1812. auto-merge trick on them?
  1813. First of all, if you want to use binary files, you should get RCS 5.7
  1814. and CVS 1.9 or later (earlier versions had some support, but there have been
  1815. bug fixes). Secondly, follow the instructions for installing RCS very
  1816. carefully (it is easy to get it installed so it works for everything
  1817. except binary files).
  1818. Then, specify 'cvs add -kb' instead of just 'cvs add' to add a binary
  1819. file. If you want to set an existing file to binary, run 'cvs admin
  1820. -kb' (and then check in a new copy of the file). Note that old
  1821. versions of CVS used -ko instead of -kb for binary files, so if you
  1822. see a reference to -ko in the context of binary files, you should
  1823. think -kb instead.
  1824. Of course when 'cvs update' finds that a merge is needed, it can't
  1825. do this for binary files the same way as for text files. With the
  1826. latest versions (e.g. CVS 1.9.14), it should be able to give you both
  1827. versions and let you merge manually. Another approach is to
  1828. run 'cvs admin -l' to lock files, as described in
  1829. "How can I lock files while I'm working on them the way RCS does?"
  1830. elsewhere in this FAQ. See also
  1831. "Is there any way to import binary files?" and
  1832. "How do I "add" a binary file?" elsewhere in this FAQ.
  1833. kingdon@cyclic.com
  1834. Last modified: _9/6/1997_
  1835. 2. Can I edit the RCS (",v") files in the Repository?
  1836. Yes, but be very careful. The RCS files are not free-form files, they
  1837. have a structure that is easily broken by hand-editing. The only time
  1838. I would suggest doing this is to recover from emergency failures that
  1839. are difficult to deal with using CVS commands, including the "admin"
  1840. command, which can talk directly to RCS.
  1841. Though no one actively encourages the editing of RCS files, many
  1842. people have succumbed to the urge to do so when pressed for time. The
  1843. reasons given, usually with evident contrition, include:
  1844. - Editing mistakes in, or adding text to, log entries. (If you have
  1845. RCS 5.6 or later, you should use `cvs admin -m'.)
  1846. - Renaming or moving symbolic names. (You should `cvs admin -N'
  1847. instead.)
  1848. - Unlocking a file by changing the "locker" from someone else to
  1849. yourself. (It's safer to use `cvs admin -u -l'.)
  1850. - Making global changes to past history. Example: Eradicating former
  1851. employees names from old documents and Author entries. (And someone
  1852. thought the "history" command was evidence of Big Brother! I never
  1853. realized how much help a wide-open revision control system could have
  1854. provided to The Ministry of Truth.)
  1855. Last modified: _6/13/1997_
  1856. 3. Can I edit the ./CVS/{Entries,Repository,Tag} files?
  1857. Yes, but with CVS 1.3 and later, there is almost no reason to edit any
  1858. of the CVS administrative files.
  1859. If you move pieces of your Repository around it can be faster to edit
  1860. all the ./CVS/Repository files rather than checking out a large tree.
  1861. But that is nearly the only reason to do so.
  1862. Last modified: _6/13/1997_
  1863. 4. Someone executed "admin -o" and removed revisions to which tags/symbols
  1864. were attached. How do I fix them?
  1865. It depends on what you mean by "fix". I can think of three ways to fix
  1866. your predicament:
  1867. Remove the tags.
  1868. Assuming you really wanted to get rid of the revision and its
  1869. associated tags, you can remove them with the "admin" command. The
  1870. "tag -d" command will only remove tags attached to existing revisions.
  1871. You can remove a tag, even if it is attached to a non-existent
  1872. revision, by typing:
  1873. cvs admin -N<tag> <file>
  1874. Retrieve the outdated revision.
  1875. You should first look in your backup system for recent versions of the
  1876. file. If you can't use them, you can carefully extract each revision
  1877. that followed the earliest outdated revision using RCS (or "cvs
  1878. admin") commands and reconstruct the file with all the right
  1879. revisions, branches and tags. This is a lot of work.
  1880. You *can't* insert a revision into the current RCS file.
  1881. Move the Tags to another revision in each file.
  1882. If you want to move the tags to another valid revision, you have two
  1883. choices, both of which require that you find all the revision numbers
  1884. of the files you want to "tag" and execute the following command
  1885. sequences on each <file>.
  1886. Use "update" to grab the revision you want, then execute a normal
  1887. "tag" command to Tag that revision:
  1888. cvs update -r <rev> <file>
  1889. cvs tag <tag> <file>
  1890. Use "admin" to set the tag to a specific revision:
  1891. cvs admin -N<tag>:<rev> <file>
  1892. Last modified: _6/13/1997_
  1893. 5. How do I move or rename a magic branch tag?
  1894. (To rename a non-branch <tag> see 3O.9.)
  1895. Before reading this, read 3M.3 and 3M.4 and understand exactly how tag
  1896. and rtag use '-r' and why it won't do the right job here.
  1897. First, I have to explain exactly what a magic branch tag is.
  1898. A magic <branch_tag> is an artificial tag attached to a non-existent
  1899. revision on a non-existent branch number zero. It looks like this:
  1900. TAG1:<X>.0.Y
  1901. <X> is the "branch point revision", a normal revision with an
  1902. odd number of '.'s in it. (e.g. 1.5, 1.3.1.6, etc)
  1903. Y is an even number (e.g. 2, 4, 6, etc.) All CVS branches,
  1904. other than the Vendor branch, are even numbered.
  1905. TAG1 is considered by CVS to be attached to revision <X>. The first
  1906. "update -r TAG1 <file>" after applying TAG1 will produce a copy of
  1907. revision <X> with a sticky tag of TAG1. The first "commit" to that
  1908. file will cause CVS to construct an RCS branch named <X>.Y and check
  1909. in revision <X>.Y.1 on the new branch.
  1910. Note: TAG1 is *not* considered to be attached to <X> by RCS, which
  1911. explains why you can't refer directly to the branch point revision for
  1912. some CVS commands.
  1913. Moving a magic <branch_tag> is the act of reapplying the same tag to
  1914. different revisions in the file:
  1915. TAG1:<X>.0.Y
  1916. to
  1917. TAG1:<X>.0.Z or TAG1:<A>.0.B
  1918. You can move a magic branch tag to the revisions of your choice by
  1919. using "update" to find the revisions you want to tag and reapplying
  1920. the tag to all the files with the '-F' option to force it to move the
  1921. existing <branch_tag>.
  1922. cvs update -r <tag/rev> (or '-A' for the Main Branch)
  1923. cvs tag -F -b <branch_tag>
  1924. If the earlier location of TAG1 refers to a physical branch within any
  1925. RCS file, moving it will make the existing branch in the file seem to
  1926. disappear from CVS's view. This is not a good idea unless you really
  1927. want to forget the existence of those RCS branches.
  1928. If the "update" above retrieves the original branch point revision
  1929. (<X>), the "tag" command above will create the tag:
  1930. TAG1:<X>.0.Z
  1931. Where Z is 2 greater than the highest magic branch already on revision
  1932. <X>. The TAG1 branch will still have the same branch point (i.e.
  1933. revision <X>), but the first commit to the new TAG1 branch will create
  1934. a different RCS branch number (<X>.Z instead of <X>.Y).
  1935. Renaming a magic <branch_tag> is the act of changing
  1936. TAG1:<X>.0.Y
  1937. to
  1938. TAG2:<X>.0.Y
  1939. There is no harm in changing a tag name as long as you forget that
  1940. TAG1 ever existed and you clean up any working directories with sticky
  1941. TAG1 tags on them by using "update -A", "update -r <other_tag>" or by
  1942. removing the working directories.
  1943. On the other hand, actually changing the tag is not easy.
  1944. See 3M.3 for why the seemingly obvious solution won't work:
  1945. cvs tag -b -r <old_branch_tag> <new_branch_tag>
  1946. The only direct way to rename a magic tag is to use the "admin"
  1947. command on each file: (You might want to use '-n'. Read "man rcs" and
  1948. look at the '-n' and '-N' options.)
  1949. cvs admin -N<new_branch_tag>:<old_branch_tag> .
  1950. cvs tag -d <old_branch_tag>
  1951. But you have to be careful because "admin" is different from other CVS
  1952. commands:
  1953. "admin" can be used recursively, but only by specifying directory
  1954. names in its argument list (e.g. '.'),
  1955. Where "rtag -r <old_branch_tag>" would interpret <old_branch_tag> as
  1956. a magic CVS branch tag, "admin" is a direct interface to RCS which
  1957. sees a magic branch tag as a simple (though non-existent) RCS revision
  1958. number.
  1959. This is good for us in this particular case, but different from normal
  1960. CVS.
  1961. "admin" also skips the Attic and produces different kinds of errors
  1962. than CVS usually does. (Because they are coming directly from RCS.)
  1963. The other way to rename a magic <branch_tag> is to edit the Repository
  1964. files with a script of some kind. I've done it in the past, but I'll
  1965. leave it as an exercise for the reader.
  1966. Last modified: _6/13/1997_
  1967. 6. Can I use RCS locally to record my changes without making them globally
  1968. visible by committing them?
  1969. You can, but it will probably confuse CVS to have ",v" files in your
  1970. working directory. And you will lose all your log entries when you
  1971. finally commit it.
  1972. Your best bet is to create your own CVS branch and work there. You can
  1973. commit as many revisions as you want, then merge it back into the main
  1974. line (or parent branch) when you are finished.
  1975. Last modified: _6/13/1997_
  1976. 7. How can I allow access to the Repository by both CVS and RCS?
  1977. The first step is to try not to. If some people are using CVS, there
  1978. is no reason for everyone not to. It is not hard to learn the basics
  1979. and CVS makes certain operations *easier* than a series of RCS
  1980. commands. Personal preference in what software tools can be applied to
  1981. a shared Repository has to take second place to system integration
  1982. needs. If you disagree, try writing some Lisp code for inclusion in
  1983. your Unix kernel and see what kind of reception you get.
  1984. If you really must allow routine RCS access to the CVS Repository, you
  1985. can link an RCS sub-directory into a piece of the Repository:
  1986. ln -s /Repository/some/directory/I/want RCS
  1987. and RCS will work just fine.
  1988. Those who are using RCS will have to keep the following in mind:
  1989. If a file was originally added to the Repository by "import" and has
  1990. not been changed using CVS, the *RCS* default branch will remain
  1991. attached to the Vendor branch, causing revisions checked-in by "ci" to
  1992. wind up on the Vendor branch, instead of the main branch. Only CVS
  1993. moves the RCS default branch on first commit.
  1994. The way around this is to checkin (using "ci") all the files first and
  1995. move them into the Repository. That way they won't have Vendor
  1996. branches. Then RCS will work OK.
  1997. It is possible to use "rcs" and "ci" to make the files unusable by
  1998. CVS. The same is true of the CVS "admin" command.
  1999. Normal RCS practice locks a file on checkout with "co -l". In such
  2000. an environment, RCS users should plan to keep survival gear and food
  2001. for at least 30 days near their desks. When faced with bizarre and
  2002. unexpected permission errors, howling mobs of slavering CVS users will
  2003. run the RCS users out of town with pitchforks and machetes.
  2004. See 3C.8 for a way to avoid machetes aroused by lock collisions.
  2005. Though files checked in by RCS users will correctly cause
  2006. "up-to-date" failures during CVS "commits" and they will be
  2007. auto-merged into CVS working directories during "update", the opposite
  2008. won't happen.
  2009. RCS users will get no warning and will not be required to merge older
  2010. work into their code. They can easily checkin an old file on top of a
  2011. new revision added by CVS, discarding work committed earlier by CVS
  2012. users.
  2013. See the howling mob scenario described above.
  2014. RCS is great. I have used it for years. But I wouldn't mix it this
  2015. way. In a two-camp society, you are asking for real trouble, both in
  2016. technical hassles to clean up and in political hassles to soothe.
  2017. Branch merges will also be a major problem.
  2018. Last modified: _6/13/1997_
  2019. 8. I "updated" a file my friend, "bubba", committed yesterday. Why doesn't
  2020. the file now have a modified date of yesterday?
  2021. CVS restores dates from the RCS files only on first "checkout". After
  2022. that, it is more important to maintain a timestamp relative to the
  2023. other files in the working directory.
  2024. Example: You committed a source file at 5PM. Bubba updated his copy of
  2025. the file, grabbing your changes, then changed and committed a new
  2026. revision of the file at 6PM. At 7PM, you compile your file. Then you
  2027. execute "update". If CVS sets the date to the one in the RCS file, the
  2028. file would be given a timestamp of 6PM and your Makefile wouldn't
  2029. rebuild anything that depended on it. Bad news.
  2030. Note that the same logic applies to retrieving a revision out of the
  2031. Repository to replace a deleted file. If CVS changes your file in an
  2032. existing working directory, whether it was because a new revision was
  2033. committed by someone else or because you deleted your working file,
  2034. the timestamp on the retrieved working file *must* be set to the
  2035. current time.
  2036. When you first retrieve a file, there is no reason to expect any
  2037. particular timestamp on the file within your working area. But later,
  2038. when dependency checking is performed during a build, it is more
  2039. important for the timestamps on the local files to be consistent with
  2040. each other than than it is for working files to match the timestamps
  2041. on the files in the Repository. See 4D.17 for some more about
  2042. timestamps.
  2043. Last modified: _6/13/1997_
  2044. 9. Why do timestamps sometimes get set to the date of the revision,
  2045. sometimes not? The inconsistency causes unnecessary recompiles.
  2046. The "checkout" command normally sets the timestamp of a working file
  2047. to match the timestamp stored on the revision in the Repository's RCS
  2048. file.
  2049. The "commit" command retains the timestamp of the file, if the act of
  2050. checking it in didn't change it (by expanding keywords).
  2051. The "update" command sets the time to the revision time the first time
  2052. it sees the file. After that, it sets the time of the file to the
  2053. current time. See 4D.8 for a reason why.
  2054. Here's a two-line PERL program to set timestamps on files based on
  2055. other timestamps. I've found this program useful. When you are certain
  2056. you don't want a source file to be recompiled, you can set its
  2057. timestamp to the stamp on the object file.
  2058. #!/usr/local/bin/perl
  2059. #
  2060. # Set timestamp of args 2nd-Last to that of the first arg.
  2061. #
  2062. ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,$atime,$mtime,$ctime)
  2063. = stat(shift);
  2064. utime($atime,$mtime,@ARGV);
  2065. Last modified: _6/13/1997_
  2066. 10. While in the middle of a large "commit", how do I run other commands,
  2067. like "diff" or "stat" without seeing lock errors?
  2068. Type:
  2069. cvs -n <command>
  2070. The '-n' option to the main cvs command turns off lock checking, a
  2071. reasonable act for read-only commands given the promise offered by
  2072. '-n' not to alter anything. The "diff", "log" and "stat" commands
  2073. provide the same information (for files that are not being committed)
  2074. when used with and without the '-n' option.
  2075. Warning: Ignoring locks can produce inconsistent information across a
  2076. collection of files if you are looking at the revisions affected by an
  2077. active commit. Be careful when creating "patches" from the output of
  2078. "cvs -n diff". If you are looking only at your working files, tagged
  2079. revisions, and BASE revisions (revisions whose numbers are read from
  2080. your ./CVS/Entries files), you should get consistent results. Of
  2081. course, if you catch a single file in the middle of RCS activity, you
  2082. might get some strange errors.
  2083. Note that the suggested command is "cvs -n <command>". The visually
  2084. similar command "cvs <command> -n" has no relation to the suggested
  2085. usage and has an entirely different meaning for each command.
  2086. "cvs -n update" also works in the middle of a commit, providing
  2087. slightly different information from a plain "cvs update". But, of
  2088. course, it also avoids modifying anything.
  2089. You could also use the RCS functions, "rlog" and "rcsdiff" to display
  2090. some of the information by referring directly to the Repository files.
  2091. You need RCS version 5 or later for the commands described above to
  2092. work reliably.
  2093. Last modified: _6/13/1997_
  2094. 11. Where did the ./CVS/Entries.Static file come from? What is it for?
  2095. Each CVS working directory contains a ./CVS/Entries file listing the
  2096. files managed by CVS in that working directory. Normally, if the
  2097. "update" command finds a file in the Repository that is not in the
  2098. ./CVS/Entries file, "update" copies the appropriate revision of the
  2099. "new" file out of the Repository and adds the filename to the Entries
  2100. file. This happens for files:
  2101. Added to the Repository from another working directory.
  2102. Dragged out of the Attic when switching branches with "update -A" or
  2103. "update -r".
  2104. Whose names were deleted from the ./CVS/Entries file.
  2105. If the ./CVS/Entries.Static file exists, CVS will only bring out
  2106. revisions of files that are contained in either ./CVS/Entries or
  2107. ./CVS/Entries.Static. If a Repository file is found in *neither* file,
  2108. it is ignored.
  2109. The ./CVS/Entries.Static file is created when you check out an
  2110. individual file or a module that creates working directories that
  2111. don't contain all files in the corresponding Repository directory. In
  2112. those cases, without an ./CVS/Entries.Static file, a simple "update"
  2113. would bring more files out of the Repository than the original
  2114. "checkout" wanted.
  2115. The ./CVS/Entries.Static file can be removed by hand. It is
  2116. automatically removed if you run "update -d" to create new directories
  2117. (even if no new directories are created). (Internally, since
  2118. "checkout" turns on the '-d' flag and calls the "update" routine, a
  2119. "checkout" of a module or directory that writes into an existing
  2120. directory will also remove the ./CVS/Entries.Static file.)
  2121. Last modified: _6/13/1997_
  2122. 12. Why did I get the wrong Repository in the loginfo message?
  2123. You probably:
  2124. Use multiple Repositories.
  2125. Configured CVS to use absolute pathnames in the ./CVS/Repository
  2126. file.
  2127. Configured CVS not to use the ./CVS/Root file.
  2128. Typed the "commit" command in one Repository with your $CVSROOT
  2129. pointing at another.
  2130. "commit" and all other CVS commands will heed an absolute pathname in
  2131. the ./CVS/Repository file (or in the "-d CVSrootdir" override), but
  2132. the log function doesn't take arguments -- it just looks at $CVSROOT.
  2133. If you avoid even one of the four steps above, you won't see this
  2134. problem. If you configure ./CVS/Root, you won't be allowed to execute
  2135. the program causing the error.
  2136. Last modified: _6/13/1997_
  2137. 13. How do I run CVS setuid so I can only allow access through the CVS
  2138. program itself?
  2139. Setuid to root is not a great idea. Any program that modifies files
  2140. and is used by a widely distributed group of users is not a good
  2141. candidate for a setuid program. (The worst suggestion I've ever heard
  2142. was to make *Emacs* setuid to root.)
  2143. Root access on Unix is too powerful. Also, it might not work in some
  2144. (secure?) environments.
  2145. Running it setuid to some user other than root might work, if you add
  2146. this line to main.c near the beginning:
  2147. setuid(geteuid());
  2148. Otherwise it uses *your* access rights, rather than the effective
  2149. uid's.
  2150. Also, you have to invent a fake user whose name will show up in
  2151. various places. But many sites, especially those who might want a
  2152. setuid CVS for "security", want personal accountability -- no generic
  2153. accounts. I don't know whether accountability outweighs file security.
  2154. And finally, unless you take action to limit the "admin" command, you
  2155. are leaving yourself unprotected anyway.
  2156. Last modified: _6/13/1997_
  2157. 14. How about using groups and setgid() then?
  2158. Here is a way to run CVS setgid in some environments:
  2159. Stick this near the front of the main() in main.c:
  2160. setgid(getegid());
  2161. This will allow "access" to work on systems where it only works on the
  2162. real gid.
  2163. Create a group named "cvsg". (This example uses "cvsg". You can name
  2164. it as you wish.)
  2165. Put *no* users in the "cvsg" group. You can put Repository
  2166. administrators in this group if you want to.
  2167. Set the cvs executable to setgid (not setuid):
  2168. cd /usr/local/bin; chown root.cvsg cvs; chmod 2755 cvs
  2169. Make sure every file in the Repository is in group "cvsg":
  2170. chown -R root.cvsg $CVSROOT
  2171. Change all directory permissions to 770. This allows all access to
  2172. the files by the "cvsg" group (which has no members!) and no access at
  2173. all to anyone else.
  2174. find $CVSROOT -type d -exec chmod 2770 {} \;
  2175. On some systems you might have to type:
  2176. find $CVSROOT -type d -exec chmod u=rwx,g=rwx,o=,g+s {} \;
  2177. This should allow only the cvs program (or other "setgid to group
  2178. cvsg") programs to write into the area, but no one else. Yes the user
  2179. winds up owning the file, but s/he can't find it again later since
  2180. s/he can't traverse the tree. (If you enable the world execute bit
  2181. (mode 2771) on directories, users can traverse the tree and the user
  2182. who last wrote the file can still write to it.)
  2183. If you want to allow read access, check out an entire tree somewhere.
  2184. You have to do this anyway to build it.
  2185. Note: If you are using a stupid file system that can't inherit file
  2186. groups from the parent directory (even with the "setgid" (Octal 2000)
  2187. bit set), you might have to modify CVS (or RCS) to reset the group
  2188. every time you create a new file. I have not tested this.
  2189. The setgid() method shares with the setuid() method the problem of
  2190. keeping "admin" from breaking things.
  2191. Last modified: _6/13/1997_
  2192. 15. How do I use the "commitinfo" file?
  2193. Go read 4B.2 first.
  2194. The "commitinfo" file allows you to execute "sanity check" functions
  2195. before allowing a commit. If any function called from within the
  2196. commitinfo file exits with a non-zero status, the commit is denied.
  2197. To fill out a "commitinfo" file, ask yourself (and those sharing your
  2198. Repository) these questions:
  2199. - Is there anything you want to check or change before someone is
  2200. allowed to commit a file? If not, forget commitinfo.
  2201. If you want to serialize binary files, you might consider something
  2202. like the rcslock.pl program in the contrib directory of the CVS
  2203. sources.
  2204. - Do you want to execute the same exact thing before committing to
  2205. every file in the Repository? (This is useful if you want to program
  2206. the restrictions yourself.) If so, set up a single line in the
  2207. commitinfo:
  2208. DEFAULT /absolute/path/to/program
  2209. CVS executes the program once for each directory that "commit"
  2210. traverses, passing as arguments the directory and the files to be
  2211. committed within that directory.
  2212. Write your program accordingly. Some examples exist in the contrib
  2213. directory.
  2214. - Do you want a different kind of sanity check performed for different
  2215. directories? If so, you'll have to decide what to do for all
  2216. directories and enter lines like this:
  2217. regexp1 /absolute/path/to/program-for-regexp1
  2218. regexp2 /absolute/path/to/program-for-regexp2
  2219. DEFAULT /absolute/path/to/program-for-all-else
  2220. - Is there anything you want to happen before *all* commits, in
  2221. addition to other pattern matches? If so, include a line like this:
  2222. ALL /absolute/path/to/program
  2223. It is executed independently of all the above. And it's repeatable --
  2224. you can have as many ALL lines as you like.
  2225. Last modified: _6/13/1997_
  2226. 16. How do I use the "loginfo" files?
  2227. See 4B.2 and the "commitinfo" question above.
  2228. The "loginfo" file has the same format as the "commitinfo" file, but
  2229. its function is different. Where the "commitinfo" information is used
  2230. before a commit, the "loginfo" file is used after a commit.
  2231. All the commands in the "loginfo" file should read data from standard
  2232. input, then either append it to a file or send a message to a mailing
  2233. list. If you want to make it simple, you can put shell (the shell used
  2234. by "popen(3)") command lines directly in the "loginfo" (or
  2235. "commitinfo") file. These seem to work:
  2236. ^special /usr/ucb/Mail -s %s special-mailing-list ^other /usr/ucb/Mail
  2237. -s %s other-mailing-list DEFAULT (echo '===='; echo %s; cat) >
  2238. /path/name/to/log/file
  2239. Last modified: _6/13/1997_
  2240. 17. How can I keep people with restrictive umask values from blocking
  2241. access to the Repository?
  2242. If a user creates a new file with restricted permissions (e.g. 0600),
  2243. and commits it, the Repository will have a file in it that is
  2244. unreadable by everyone. The 0600 example would be unreadable by
  2245. *anyone* but root and the user who created it.
  2246. There are 3 solutions to this:
  2247. Let it happen. This is a valid way to protect things. If everyone is
  2248. working alone, a umask of 077 is OK. If everyone is working only in
  2249. small groups, a umask of 007 is OK.
  2250. Train your users not to create such things if you expect to share
  2251. them.
  2252. See 4B.5 for a small script that will reset the umask.
  2253. I personally don't like the idea of a program automatically
  2254. *loosening* security. It would be better for you all to talk about the
  2255. issue and decide how to work together.
  2256. Last modified: _6/13/1997_
  2257. Category: /Commands_/
  2258. " Commands "
  2259. Category: /Commands_/add_ad_new/
  2260. " + "add", "ad", "new""
  2261. 1. What is "add" for?
  2262. To add a new directory to the Repository or to register the desire to
  2263. add a new file to the Repository.
  2264. The directory is created immediately, while the desire to add the file
  2265. is recorded in the local ./CVS administrative directory. To really add
  2266. the file to the Repository, you must then "commit" it.
  2267. Last modified: _6/13/1997_
  2268. 2. How do I add a new file to the branch I'm working on?
  2269. The user actions for adding a file to any branch, including the Main
  2270. Branch, are exactly the same.
  2271. You are in a directory checked out (or updated) with the '-A' option
  2272. (to place you on the Main Branch) or the "-r <branch_tag>" option (to
  2273. place you on a branch tagged with <branch_tag>). To add <file> to the
  2274. branch you are on, you type:
  2275. cvs add <file>
  2276. cvs commit <file>
  2277. If no ./CVS/Tag file exists (the '-A' option deletes it), the file
  2278. will be added to the Main Branch. If a ./CVS/Tag file exists (the "-r
  2279. <branch_tag>" option creates it), the file will be added to the branch
  2280. named (i.e. tagged with) <branch_tag>.
  2281. Unless you took steps to first add the file to the Main Branch, your
  2282. new file ends up in the Attic.
  2283. Last modified: _6/13/1997_
  2284. 3. Why did my new file end up in the Attic?
  2285. The file is thrown into the Attic to keep it from being visible when
  2286. you check out the Main Branch, since it was never committed to the
  2287. Main Branch.
  2288. Last modified: _6/13/1997_
  2289. 4. Now that it's in the Attic, how do I connect it to the Main branch?
  2290. That can be considered a kind of "merge". See 4C.8
  2291. Last modified: _6/13/1997_
  2292. 5. How do I avoid the hassle of reconnecting an Attic-only file to the Main
  2293. Branch?
  2294. You create it on the Main Branch first, then branch it.
  2295. If you haven't yet added the file or if you decided to delete the new
  2296. Attic file and start over, then do the following: (If you added the
  2297. file (or worse, the 157 files) to the Attic and don't want to start
  2298. over, try the procedure in 4C.8.)
  2299. Temporarily remove the sticky branch information. Either:
  2300. Move the whole directory back to the Main Branch. [This might not be
  2301. a good idea if you have modified files, since it will require a merge
  2302. in each direction.]
  2303. cvs update -A
  2304. *or*
  2305. Move the ./CVS/Tag file out of the way.
  2306. mv ./CVS/Tag HOLD_Tag
  2307. Add and branch the file "normally":
  2308. cvs add <file>
  2309. cvs commit <file>
  2310. cvs tag -b <branch_tag> <file>
  2311. [<branch_tag> is the same Branch Tag as you used on all the other
  2312. files. Look at ./CVS/Entries or the output from "cvs stat" for sticky
  2313. tags.]
  2314. Clean up the temporary step.
  2315. If you moved the ./CVS/Tag file, put it back. Then move the new file
  2316. onto the branch where you are working.
  2317. mv HOLD_Tag ./CVS/Tag
  2318. cvs update -r <branch_tag> <file>
  2319. If you ran "update -A" rather than moving the ./CVS/Tag file, move
  2320. the whole directory (including the new file) back onto the branch
  2321. where you were working:
  2322. cvs update -r <branch_tag>
  2323. Last modified: _6/13/1997_
  2324. 6. How do I cancel an "add"?
  2325. If you want to remove the file entirely and cancel the "add" at the
  2326. same time, type:
  2327. cvs remove -f <file>
  2328. If you want to cancel the "add", but leave the file as it was before
  2329. you typed "cvs add", then you have to fake it:
  2330. mv <file> <file>.hold
  2331. cvs remove <file>
  2332. mv <file>.hold <file>
  2333. Last modified: _6/13/1997_
  2334. 7. What are the ./CVS/file,p and ./CVS/file,t files for?
  2335. The ./CVS/file,p and ./CVS/file,t files are created by the "add"
  2336. command to hold command line options and message text between the time
  2337. of the "add" command and the expected "commit".
  2338. The ./CVS/file,p file is always null, since its function was absorbed
  2339. by the "options" field in the ./CVS/Entries file. If you put something
  2340. in this file it will be used as arguments to the RCS "ci" command that
  2341. commit uses to check the file in, but CVS itself doesn't put anything
  2342. there.
  2343. The ./CVS/file,t file is null unless you specify an initial message in
  2344. an "add -m 'message'" command. The text is handed to "rcs -i
  2345. -t./CVS/file,t" to create the initial RCS file container.
  2346. Both files must exist to commit a newly added file. If the
  2347. ./CVS/file,p file doesn't exist, CVS prints an error and aborts the
  2348. commit. If the ./CVS/file,t file doesn't exist, RCS prints an error
  2349. and CVS gets confused, but does no harm.
  2350. To recover from missing ,p and ,t files, just create two zero-length
  2351. files and rerun the "commit".
  2352. Last modified: _6/13/1997_
  2353. 8. How do I "add" a binary file?
  2354. If you configured CVS to use the GNU version of "diff" and "diff3",
  2355. you only need to turn off RCS keyword expansion.
  2356. First you turn off RCS keyword expansion for the initial checkin by
  2357. using "add -ko". It works like "update -ko" in creating a "sticky"
  2358. option only for the copy of the file in the current working directory.
  2359. cvs add -ko <file>
  2360. Commit the file normally. The sticky -ko option will be used.
  2361. cvs commit <file>
  2362. Then mark the RCS file in the Repository so that keyword expansion is
  2363. turned off for all checked out versions of the file.
  2364. cvs admin -ko <file>
  2365. Since "admin -ko" records the keyword substitution value in the
  2366. Repository's RCS file, you no longer need the sticky option. You can
  2367. turn it off with the "update -A" command, but if you were on a branch,
  2368. you'll have to follow it "update -r <branch_tag>" to put yourself back
  2369. on the branch.
  2370. Managing that binary file is another problem. See 4D.1.
  2371. Last modified: _6/13/1997_
  2372. Category: /Commands_/admin_adm_rcs/
  2373. " + "admin", "adm", "rcs""
  2374. 1. What is "admin" for?
  2375. To provide direct access to the underlying "rcs" command (which is not
  2376. documented in this FAQ) bypassing all safeguards and CVS assumptions.
  2377. Last modified: _6/13/1997_
  2378. 2. Wow! Isn't that dangerous?
  2379. Yes.
  2380. Though you can't hurt the internal structure of an RCS file using its
  2381. own "rcs" command, you *can* change the underlying RCS files using
  2382. "admin" in ways that CVS can't handle.
  2383. If you feel the need to use "admin", create some test files with the
  2384. RCS "ci" command and experiment on them with "rcs" before blasting any
  2385. CVS files.
  2386. Last modified: _6/13/1997_
  2387. 3. What would I normally use "admin" for?
  2388. Normally, you wouldn't use admin at all. In unusual circumstances,
  2389. experts can use it to set up or restore the internal RCS state that
  2390. CVS requires.
  2391. You can use "admin -o" (for "outdate") to remove revisions you don't
  2392. care about. This has its own problems, such as leaving dangling Tags
  2393. and confusing the "update" command.
  2394. There is some feeling among manipulators of binary files that "admin
  2395. -l" should be used to serialize access. See 3C.8.
  2396. An interesting use for "admin" came up while maintaining CVS itself. I
  2397. import versions of CVS onto the Vendor branch of my copy of CVS, make
  2398. changes to some files and ship the diffs (created by "cvs diff -c -r
  2399. TO_BRIAN") off to Brian Berliner. After creating the diff, I retag
  2400. ("cvs tag -F TO_BRIAN") the working directory, which is then ready to
  2401. produce the next patch.
  2402. I'll use "add.c" as an example (only because the name is short).
  2403. When the next release came out, I discovered that the released "add.c"
  2404. (version 1.1.1.3 on the Vendor branch) was exactly the same as my
  2405. modified file (version 1.3). I didn't care about the changelog on
  2406. versions 1.2 and 1.3 (or the evidence of having done the work), so I
  2407. decided to revert the file to the state where it looked like I had not
  2408. touched the file -- where I was just using the latest on the vendor
  2409. branch after a sequence of imports.
  2410. To do that, I removed all the revisions on the main branch, except for
  2411. the original 1.1 from which the Vendor branch sprouts:
  2412. cvs admin -o1.2: add.c
  2413. Then I set the RCS "default branch" back to the Vendor branch, the way
  2414. import would have created it:
  2415. cvs admin -b1.1.1 add.c
  2416. And I moved the "TO_BRIAN" Tag to the latest revision on the Vendor
  2417. branch, since that is the base from which further patches would be
  2418. created (if I made any):
  2419. cvs admin -NTO_BRIAN:1.1.1.3 add.c
  2420. Instead of 1.1.1.3, I could have used one of the "Release Tags" last
  2421. applied by "import" (3rd through Nth arguments).
  2422. Suggestion: Practice on non-essential files.
  2423. Last modified: _6/13/1997_
  2424. 4. What should I avoid when using "admin"?
  2425. If you know exactly what you are doing, hack away. But under normal
  2426. circumstances:
  2427. Never use "admin" to alter branches (using the '-b' option), which CVS
  2428. takes very seriously. If you change the default branch, CVS will not
  2429. work as expected. If you create new branches without using the "tag
  2430. -b" command, you may not be able to treat them as CVS branches.
  2431. See 3C.8 for a short discussion of how to use "admin -l" for
  2432. serializing access to binary files.
  2433. The "admin -o <file>" allows you to delete revisions, usually a bad
  2434. idea. You should commit a correction rather than back out a revision.
  2435. Outdating a revision is prone to all sorts of problems:
  2436. Discarding data is always a bad idea. Unless something in the
  2437. revision you just committed is a threat to your job or your life,
  2438. (like naming a function "<boss's name>_is_a_dweeb", or including the
  2439. combination to the local Mafioso's safe in a C comment), just leave it
  2440. there. No one cares about simple mistakes -- just commit a corrected
  2441. revision.
  2442. The time travel paradoxes you can cause by changing history are not
  2443. worth the trouble. Even if CVS can't interfere with your parents'
  2444. introduction, it *can* log commits in at least two ways (history and
  2445. loginfo). The reports now lie -- the revision referred to in the logs
  2446. no longer exists.
  2447. If you used "import" to place <file> into CVS, outdating all the
  2448. revisions on the Main branch back to and including revision 1.2 (or
  2449. worse, 1.1), will produce an invalid CVS file.
  2450. If the <file>,v file only contains revision 1.1 (and the connected
  2451. branch revision 1.1.1.1), then the default branch must be set to the
  2452. Vendor branch as it was when you first imported the file. Outdating
  2453. back through 1.2 doesn't restore the branch setting. Despite the above
  2454. admonition against it, "admin -b" is the only way to recover:
  2455. cvs admin -b1.1.1 <file>
  2456. Although you can't outdate a physical (RCS) branch point without
  2457. removing the whole branch, you *can* outdate a revision referred to by
  2458. a magic branch tag. If you do so, you will invalidate the branch.
  2459. If you "outdate" a tagged revision, you will invalidate all uses of
  2460. the <tag>, not just the one on <file>. A tag is supposed to be
  2461. attached to a consistent set of files, usually a set built as a unit.
  2462. By discarding one of the files in the set, you have destroyed the
  2463. utility of the <tag>. And it leaves a dangling tag, which points to
  2464. nothing.
  2465. And even worse, if you commit a revision already tagged, you will
  2466. alter what the <tag> pointed to without using the "tag" command. For
  2467. example, if revision 1.3 has <tag> attached to it and you "outdate"
  2468. the 1.3 revision, <tag> will point to a nonexistent revision. Although
  2469. this is annoying, it is nowhere near as much trouble as the problem
  2470. that will occur when you commit to this file again, recreating
  2471. revision 1.3. The old tag will point to the new revision, a file that
  2472. was not in existence when the <tag> was applied. And the discrepancy
  2473. is nearly undetectable.
  2474. If you don't understand the above, you should not use the admin
  2475. command at all.
  2476. Last modified: _6/13/1997_
  2477. 5. How do I restrict the "admin" command? The -i flag in the modules file
  2478. can restrict commits. What's the equivalent for "admin"?
  2479. At this writing, to disable the "admin" command, you will have to
  2480. change the program source code, recompile and reinstall.
  2481. Last modified: _6/13/1997_
  2482. 6. I backed out a revision with "admin -o" and committed a replacement. Why
  2483. doesn't "update" retrieve the new revision?
  2484. CVS is confused because the revision in the ./CVS/Entries file matches
  2485. the latest revision in the Repository *and* the timestamp in the
  2486. ./CVS/Entries file matches your working file. CVS believes that your
  2487. file is "up-to-date" and doesn't need to be updated.
  2488. You can cause CVS to notice the change by "touch"ing the file.
  2489. Unfortunately what CVS will tell you is that you have a "Modified"
  2490. file. If you then "commit" the file, you will bypass the normal CVS
  2491. check for "up-to-date" and will probably commit the revision that was
  2492. originally removed by "admin -o".
  2493. Changing a file without changing the revision number confuses CVS no
  2494. matter whether you did it by replacing the revision (using "admin -o"
  2495. and "commit" or raw RCS commands) or by applying an editor directly to
  2496. a Repository (",v") file. Don't do it unless you are absolutely
  2497. certain no one has the latest revision of the file checked out.
  2498. The best solution to this is to institute a program of deterrent
  2499. flogging of abusers of "admin -o".
  2500. The "admin" command has other problems." See 3B.4 above.
  2501. Last modified: _6/13/1997_
  2502. Category: /Commands_/checkout_co_get/
  2503. " + "checkout", "co", "get""
  2504. 1. What is "checkout" for?
  2505. To acquire a copy of a module (or set of files) to work on.
  2506. All work on files controlled by CVS starts with a "checkout".
  2507. Last modified: _6/13/1997_
  2508. 2. What is the "module" that "checkout" takes on the command line?
  2509. It is a name for a directory or a collection of files in the
  2510. Repository. It provides a compact name space and the ability to
  2511. execute before and after helper functions based on definitions in the
  2512. modules file.
  2513. See 1D.11.
  2514. Last modified: _6/13/1997_
  2515. 3. Isn't a CVS "checkout" just a bunch of RCS checkouts?
  2516. Like much of CVS, a similar RCS concept is used to support a CVS
  2517. function. But a CVS checkout is *not* the same as an RCS checkout.
  2518. Differences include:
  2519. CVS does not lock the files. Others may access them at the same
  2520. time.
  2521. CVS works best when you provide a name for a collection of files (a
  2522. module or a directory) rather than an explicit list of files to work
  2523. on.
  2524. CVS remembers what revisions you checked out and what branch you are
  2525. on, simplifying later commands.
  2526. Last modified: _6/13/1997_
  2527. 4. What's the difference between "update" and "checkout"?
  2528. The "checkout" and "update" commands are nearly equivalent in how they
  2529. treat individual files. They differ in the following ways:
  2530. The "checkout" command always creates a directory, moves into it,
  2531. then becomes equivalent to "update -d".
  2532. The "update" command does not create directories unless you add the
  2533. '-d' option.
  2534. "Update" is intended to be executed within a working directory
  2535. created by "checkout". It doesn't take a module or directory argument,
  2536. but figures out what Repository files to look at by reading the files
  2537. in the ./CVS administrative directory.
  2538. The two commands generate completely different types of records in
  2539. the "history" file.
  2540. Last modified: _6/13/1997_
  2541. 5. Why can't I check out a file from within my working directory?
  2542. Though you *can* check out a file, you normally check out a module or
  2543. directory. And you normally do it only once at the beginning of a
  2544. project.
  2545. After the initial "checkout", you can use the "update" command to
  2546. retrieve any file you want within the checked-out directory. There is
  2547. no need for further "checkout" commands.
  2548. If you want to retrieve another module or directory to work on, you
  2549. must provide two pathnames: where to find it in the Repository and
  2550. where to put it on disk. The "modules" file and your current directory
  2551. supply two pieces of naming information. While inside a checked-out
  2552. working directory, the CVS administrative information provides most of
  2553. the rest.
  2554. You should be careful not to confuse CVS with RCS and use "checkout"
  2555. in the RCS sense. An RCS "checkout" (which is performed by the RCS
  2556. "co" command) is closer to a "cvs update" than to a "cvs checkout".
  2557. Last modified: _6/13/1997_
  2558. 6. How do I avoid dealing with those long relative pathnames?
  2559. This question has also been phrased:
  2560. How do I avoid all those layers of directories on checkout? or Why do
  2561. I have to go to the top of my working directory and checkout some long
  2562. pathname to get a file or two?
  2563. This type of question occurs only among groups of people who decide
  2564. not to use "modules". The answer is to use "modules".
  2565. When you hand the "checkout" command a relative pathname rather than a
  2566. module name, all directories in the path are created, maintaining the
  2567. same directory hierarchy as in the Repository. The same kind of
  2568. environment results if you specify a "module" that is really an alias
  2569. expanding into a list of relative pathnames rather than a list of
  2570. module names.
  2571. If you use "module" names, "checkout" creates a single directory by
  2572. the name of the module in your current directory. This "module"
  2573. directory becomes your working directory.
  2574. The "module" concept combines the ability to "name" a collection of
  2575. files with the ability to structure the Repository so that consistent
  2576. sets of files are checked out together. It is the responsibility of
  2577. the Repository Administrators to set up a modules file that describes
  2578. the software within the Repository.
  2579. Last modified: _6/13/1997_
  2580. 7. Can I move a checked-out directory? Does CVS remember where it was
  2581. checked out?
  2582. Yes and Yes.
  2583. The ./CVS/Repository file in each working directory contains a
  2584. pathname pointing to the matching directory within the Repository. The
  2585. pathname is either absolute or relative to $CVSROOT, depending on how
  2586. you configured CVS.
  2587. When you move a checked-out directory, the CVS administrative files
  2588. will move along with it. As long as you don't move the Repository
  2589. itself, or alter your $CVSROOT variable, the moved directory will
  2590. continue to be usable.
  2591. CVS remembers where you checked out the directory in the "history"
  2592. file, which can be edited, or even ignored if you don't use the
  2593. "working directory" information displayed by the "history" command.
  2594. Last modified: _6/13/1997_
  2595. 8. How can I lock files while I'm working on them the way RCS does?
  2596. Until the day arrives of the all-powerful merge tool, there are still
  2597. files that must be accessed serially. For those instances, here's a
  2598. potential solution:
  2599. Install a pre-commit program in the "commitinfo" file to check for
  2600. RCS locks. The program "rcslock.pl" performs this function. It can be
  2601. found in the contrib directory of the CVS source distribution.
  2602. When you want to make a change to a file you know can't be merged,
  2603. first use "cvs admin -l" to lock the file. If you can't acquire the
  2604. lock, use the standard "locked out" protocol: go talk to the person
  2605. holding the lock.
  2606. Make sure the pre-commit program prints a message and exits with a
  2607. non-zero status if someone besides the user running "commit" has the
  2608. file locked. This non-zero exist status will cause the "commit" to
  2609. fail cleanly.
  2610. Make sure the pre-commit program exits with a zero status if the
  2611. file is either unlocked or locked by the user running "commit". The
  2612. "cvs commit" command that kicked off the pre-commit program will take
  2613. a zero exist status as an OK and checkin the file, which has the
  2614. side-effect of unlocking it.
  2615. ===> The following is opinion and context. Don't read it if you are
  2616. looking for a quick fix.
  2617. The topic of locking CVS files resurfaces on the network every so
  2618. often, producing the same results each time:
  2619. The Big Endians:
  2620. CVS was designed to avoid locks, using a copy-modify-merge model.
  2621. Locking is not necessary and you should take the time to learn the CVS
  2622. model which many people find workable. So why not get with the program
  2623. and learn how to think the CVS way?
  2624. The Little Endians:
  2625. The users determine how a tool is to be used, not the designers. We,
  2626. the users, have always used locking, our bosses demand locking,
  2627. locking is good, locking is God. I don't want to hear any more
  2628. lectures on the CVS model. Make locking work.
  2629. Any organization making active changes to a source base will
  2630. eventually face the need to do parallel development. Parallel
  2631. development implies merges. (If you plan to keep separate copies of
  2632. everything and never merge, good luck. Tell me who you work for so I
  2633. can buy stock in your disk suppliers this year and sell your stock
  2634. short next year.)
  2635. Merges will never go away. CVS chose to make "merges" stand front and
  2636. center as an important, common occurrence in development. It is one
  2637. way of looking at things.
  2638. For free-format text, the merge paradigm gives you a considerable
  2639. amount of freedom. It does take a bit of management, but any project
  2640. should be ready to deal with it.
  2641. On the other hand, there are many files that can't be merged using
  2642. text merge techniques. Straight text merge programs like "diff3" are
  2643. guaranteed to fail on executables (with relative branch statements),
  2644. files with self-referential counts stored in the file (such as TAGS
  2645. files), or files with relative motion statements in them (such as
  2646. Frame MIF files, many postscript files). They aren't all binary files.
  2647. For these types of files, and many others, there are only two
  2648. solutions:
  2649. Complex merge tools that are intimately aware of the contents of the
  2650. files to be merged. (ClearCase, and probably others, allow you to
  2651. define your own "files types" with associated "merge tools".)
  2652. Serialization of access to the file. The only technical solution to
  2653. the problem of serialization is "locking".
  2654. Since you can call a program that offers:
  2655. "Which one do you want? A/B?"
  2656. a "merge tool", more and more merge tools will appear which can be
  2657. hooked into a merge-intensive program like CVS. Think of a bitmap
  2658. "merge" tool that displays the bitmaps on the screen and offers a
  2659. "paint" interface to allow you to cut and paste, overlay, invert or
  2660. fuse the two images such that the result is a "merged" file.
  2661. My conclusion is that the need for locking is temporary, awaiting
  2662. better technology. For large development groups, locking is not an
  2663. alternative to merging for text files.
  2664. Last modified: _6/13/1997_
  2665. 9. What is "checkout -s"? How is it different from "checkout -c"?
  2666. The '-c' and '-s' options to "checkout" both cause the modules file to
  2667. appear on standard output, but formatted differently.
  2668. "checkout -c" lists the modules file alphabetized by the module name.
  2669. It also prints all data (including options like '-a' and "-o <prog>")
  2670. specified in the modules file.
  2671. "checkout -s" lists the modules file sorted by "status" field, then by
  2672. module name. The status field was intended to allow you to mark
  2673. modules with strings of your choice to get a quick sorted report based
  2674. on the data you chose to put in the status fields. I have used it for
  2675. priority ("Showstopper", etc as tied into a bug database), for porting
  2676. status ("Ported", "Compiled", etc. when porting a large collection of
  2677. modules), for "assignee" (the person responsible for maintenance), and
  2678. for "test suite" (which automatic test procedure to run for a
  2679. particular module).
  2680. Last modified: _6/13/1997_
  2681. Category: /Commands_/commit_ci_com/
  2682. " + "commit", "ci", "com""
  2683. 1. What is "commit" for?
  2684. To store new revisions in the Repository, making them visible to other
  2685. users.
  2686. Last modified: _6/13/1997_
  2687. 2. If I edit ten files, do I have to type "commit" ten times?
  2688. No. The "commit" command will take multiple filenames, directory names
  2689. and relative pathnames on the command line and commit them all with
  2690. the same log message. If a file is unchanged, even if it is explicitly
  2691. listed on the command line, CVS will skip it.
  2692. Like all CVS commands, "commit" will work on the whole directory by
  2693. default. Just type "cvs commit" to tell CVS to commit all modified
  2694. files (i.e. the files that "update" would display preceded by 'M') in
  2695. the current directory and in all sub-directories.
  2696. Last modified: _6/13/1997_
  2697. 3. Explain: cvs commit: Up-to-date check failed for `<file>'
  2698. You may not "commit" a file if your BASE revision (i.e. the revision
  2699. you last checked out, committed or retrieved via "update") doesn't
  2700. match the HEAD revision (i.e the latest revision on your branch,
  2701. usually the Main Branch).
  2702. In other words, someone committed a revision since you last executed
  2703. "checkout", "update" or "commit". You must now execute "update" to
  2704. merge the other person's changes into your working file before
  2705. "commit" will work. You are thus protected (somewhat) from a common
  2706. form of race condition in source control systems, where a checkin of a
  2707. minor alteration of a second copy of the same base file obliterates
  2708. the changes made in the first.
  2709. Normally, the "update" command's auto-merge should be followed by
  2710. another round of building and testing before the "commit".
  2711. Last modified: _6/13/1997_
  2712. 4. What happens if two people try to "commit" conflicting changes?
  2713. Conflicts can occur only when two developers check out the same
  2714. revision of the same file and make changes. The first developer to
  2715. commit the file has no chance of seeing the conflict. Only the second
  2716. developer runs into it, usually when faced with the "Up-to-date" error
  2717. explained in the previous question.
  2718. There are two types of conflicts:
  2719. When two developers make changes to the same section of code, the
  2720. auto-merge caused by "update" will print a 'C' on your terminal and
  2721. leave "overlap" markers in the file.
  2722. You are expected to examine and clean them up before committing the
  2723. file. (That may be obvious to *some* of you, but . . .)
  2724. A more difficult problem arises when two developers change different
  2725. sections of code, but make calls to, or somehow depend on, the old
  2726. version of each other's code.
  2727. The auto-merge does the "right" thing, if you view the file as a
  2728. series of text lines. But as a program, the two developers have
  2729. created a problem for themselves.
  2730. This is no different from making cross-referential changes in
  2731. *separate* files. CVS can't help you. In a perfect world, you would
  2732. each refer to the specification and resolve it independently. In the
  2733. real world you have to talk/argue, read code, test and debug until the
  2734. combined changes work again.
  2735. Welcome to the world of parallel development.
  2736. Last modified: _6/13/1997_
  2737. 5. I committed something and I don't like it. How do I remove it?
  2738. Though you *can* use the "admin -o" (synonym: "rcs -o") command to
  2739. delete revisions, unless the file you committed is so embarrassing
  2740. that the need to eradicate it overrides the need to be careful, you
  2741. should just grab an old version of the file ("update -p -r
  2742. <previous-rev>" might help here) and commit it on top of the offending
  2743. revision.
  2744. See Section 3B on "admin".
  2745. Last modified: _6/13/1997_
  2746. 6. Explain: cvs commit: sticky tag `V3' for file `X' is not a branch
  2747. The message implies two things:
  2748. You created your working directory by using "checkout -r V3", or you
  2749. recently executed "update -r V3".
  2750. The tag named V3 is not a branch tag.
  2751. CVS records (i.e. makes "sticky") any "-r <tag/rev>" argument handed
  2752. to the "checkout" or "update" commands. The <tag/rev> is recorded as
  2753. the CVS working branch, which is the branch to which "commit" will add
  2754. a new revision.
  2755. Branch tags are created when you use the -b switch on the "tag" or
  2756. "rtag" commands. Branch tags are magic tags that don't create a
  2757. physical branch, but merely mark the revision to branch from when the
  2758. branch is needed. The first commit to a magic branch creates a
  2759. physical branch in the RCS files.
  2760. You can commit onto the end of the Main Trunk, if you have no sticky
  2761. tag at all, or onto the end of a branch, if you have a sticky branch
  2762. tag. But you can't commit a file that has a sticky tag not pointing to
  2763. a branch. CVS assumes a sticky Tag or Revision that does not refer to
  2764. a branch is attached to the middle of a series of revisions. You can't
  2765. squeeze a new revision between two others. Sticky dates also block
  2766. commits since they never refer to a branch.
  2767. Scenario1:
  2768. If you don't want a branch and were just looking at an old revision,
  2769. then you can move back to the Main Branch by typing:
  2770. cvs update -A {files or dirs, default is '.'}
  2771. or you can move to the branch named <branch_tag> by:
  2772. cvs update -r <branch_tag> {files or dirs, default is '.'}
  2773. Scenario2:
  2774. If you really wanted to be on a branch and made an earlier mistake by
  2775. tagging your branch point with a non-branch tag, you can recover by
  2776. adding a new branch tag to the old non-branch tag:
  2777. cvs rtag -b -r <oldtag> <newtag> <module>
  2778. (It was not a big mistake. Branch-point tags can be useful. But the
  2779. <newtag> must have a different name.)
  2780. If you don't know the <module> name or don't use "modules", you can
  2781. also use "tag" this way:
  2782. cvs update -r <oldtag>
  2783. cvs tag -b <newtag> .
  2784. Then, to put your working directory onto the branch, you type:
  2785. cvs update -r <newtag>
  2786. You can't delete <oldtag> before adding <newtag>, and I would not
  2787. advise deleting the <oldtag> at all, because it is useful in referring
  2788. to the branch point. If you must, you can delete the non-branch tag
  2789. by:
  2790. cvs rtag -d <oldtag> <module>
  2791. or
  2792. cvs tag -d <oldtag> .
  2793. Scenario3:
  2794. If you made the same mistake as in Scenario2 (of placing a non-branch
  2795. tag where you wanted a branch tag), but really want <oldtag> to be the
  2796. name of your branch, you can execute a slightly different series of
  2797. commands to rename it and move your working directory onto the branch.
  2798. Warning: This is not a way to rename a branch tag. It is a way to turn
  2799. a non-branch tag into a branch tag with the same name.
  2800. cvs rtag -r <oldtag> <branch_point_tag> <module>
  2801. cvs rtag -d <oldtag> <module>
  2802. cvs rtag -b -r <branch_point_tag> <oldtag> <module>
  2803. Then, if you really must, delete the <branch_point_tag>:
  2804. cvs rtag -d <branch_point_tag> <module>
  2805. Note: The unwieldy mixture of "tag" and "rtag" is mostly because you
  2806. can't specify a revision (-r <tag>) to the "tag" command.
  2807. See 4C.3 for more info on creating a branch.
  2808. Last modified: _6/13/1997_
  2809. 7. Why does "commit -r <tag/rev>" put newly added files in the Attic?
  2810. If you specify "-r <rev>" (where <rev> is a dotted numeric number like
  2811. 2.4), it correctly sets the initial revision to <rev>, but it also
  2812. attaches the numeric <rev> as a sticky tag and throws the file into
  2813. the Attic. This is a bug. The obvious solution is to move the file out
  2814. of the Attic into the associated Repository directory and "update -A"
  2815. the file. There are no Tags to clean up.
  2816. If you specify "-r <tag>" to commit a newly added file, the <tag> is
  2817. treated like a <branch_tag>, which becomes a symbolic RCS label
  2818. pointing to the string '1', which can be considered to be the "Main
  2819. branch number" when the main branch is still at revision 1.N. The file
  2820. is also thrown into the Attic. See 4C.8 for a way to recover from
  2821. this.
  2822. In fact, a plain "commit" without the "-r" will throw a newly added
  2823. file into the Attic if you added it to a directory checked out on a
  2824. branch. See 3A.[2-5].
  2825. See Section 4C, on Branching, for many more details.
  2826. Last modified: _6/13/1997_
  2827. 8. Why would a "commit" of a newly added file not produce rev 1.1?
  2828. When committing a newly added file CVS looks for the highest main
  2829. branch major number in all files in the ./CVS/Entries file. Normally
  2830. it is '1', but if you have a file of revision 3.27 in your directory,
  2831. CVS will find the '3' and create revision 3.1 for the first rev of
  2832. <file>. Normally, the first revision is 1.1.
  2833. Last modified: _6/13/1997_
  2834. Category: /Commands_/diff_di_dif/
  2835. " + "diff", "di", "dif""
  2836. 1. What is "diff" for?
  2837. To display the difference between a working file and its BASE
  2838. revision (the revision last checked out, updated or committed):
  2839. cvs diff <file>
  2840. To display the difference between a working file and a committed
  2841. revision of the same file:
  2842. cvs diff -r <tag/rev> <file>
  2843. To display the difference between two committed revisions of the
  2844. same file:
  2845. cvs diff -r <tag1/rev1> -r <tag2/rev2> <file>
  2846. You can specify any number of <file> arguments. Without any <file>
  2847. arguments, it compares the whole directory.
  2848. In the examples above, "-D <date>" may be substituted wherever "-r
  2849. <tag/rev>" appears. The revision a <date> refers to is the revision
  2850. that existed on that date.
  2851. Last modified: _6/13/1997_
  2852. 2. Why did "diff" display nothing when I know there are later committed
  2853. revisions in the Repository?
  2854. By default, "diff" displays the difference between your working file
  2855. and the BASE revision. If you haven't made any changes to the file
  2856. since your last "checkout", "update" or "commit" there is no
  2857. difference to display.
  2858. To display the difference between your working file and the latest
  2859. revision committed to your current branch, type:
  2860. cvs diff -r HEAD <file>
  2861. Last modified: _6/13/1997_
  2862. 3. How do I display what changed in the Repository since I last executed
  2863. "checkout", "update" or "commit"?
  2864. A special tag (interpreted by CVS -- it does not appear in the Tag
  2865. list) named "BASE" always refers to the revision you last checked out,
  2866. updated or committed. Another special tag named "HEAD" always refers
  2867. to the latest revision on your working branch.
  2868. To compare BASE and HEAD, you type:
  2869. cvs diff -r BASE -r HEAD <file>
  2870. Last modified: _6/13/1997_
  2871. 4. How do I display the difference between my working file and what I
  2872. checked in last Thursday?
  2873. cvs diff -D "last Thursday" <file>
  2874. where "last Thursday" is a date string. To be more precise, the
  2875. argument to the '-D' option is a timestamp. Many formats are accepted.
  2876. See the man page under "-D date_spec" for details.
  2877. Last modified: _6/13/1997_
  2878. 5. Why can't I pass long options, like --unified, to "diff"?
  2879. CVS only handles single character '-X' arguments, not the FSF long
  2880. options. CVS also passes through only arguments it knows about,
  2881. because a few arguments are captured and interpreted by CVS.
  2882. If you didn't configure RCS and CVS to use the GNU version of diff,
  2883. long options wouldn't work even if future versions of CVS acquire the
  2884. ability to pass them through.
  2885. Most of the long options have equivalent single-character options,
  2886. which do work. The "--unified" option is equivalent to '-u' in
  2887. revisions of GNU diff since 1.15.
  2888. Last modified: _6/13/1997_
  2889. Category: /Commands_/export_exp_ex/
  2890. " + "export", "exp", "ex""
  2891. 1. What is "export" for?
  2892. "export" checks out a copy of a module in a form intended for export
  2893. outside the CVS environment. The "export" command produces the same
  2894. directory and file structure as the "checkout" command, but it doesn't
  2895. create "CVS" sub-directories and it removes all the RCS keywords from
  2896. the files.
  2897. Last modified: _6/13/1997_
  2898. 2. Why does it remove the RCS keywords so I can't use the "ident" command
  2899. on the source files?
  2900. It removes the RCS keywords, so that if the recipient of the exported
  2901. sources checks them into another set of RCS files (with or without
  2902. CVS), and then makes modifications through RCS or CVS commands, the
  2903. revision numbers that they had when you exported them will be
  2904. preserved. (That ident no longer works is just an unfortunate side
  2905. effect.)
  2906. The theory is that you are exporting the sources to someone else who
  2907. will make independent changes, and at some point you or they will want
  2908. to know what revisions from your Repository they started with
  2909. (probably to merge changes, or to try to decide whether to merge
  2910. changes).
  2911. A better way to handle this situation would be to give them their own
  2912. branch of your Repository. They would need to remember to checkin the
  2913. exported sources with RCS IDs intact (ci -k) so that their changes
  2914. would get revision numbers from the branch, rather than starting at
  2915. 1.1 again. Perhaps a future version of CVS will provide a way to
  2916. export sources this way.
  2917. Contributed by Dan Franklin
  2918. Last modified: _6/13/1997_
  2919. 3. Can I override the '-kv' flag CVS passes to RCS?
  2920. Not as of CVS version 1.4.
  2921. Last modified: _6/13/1997_
  2922. 4. Why doesn't "export" have a '-k' flag like "import" does?
  2923. Export is intended for a specific purpose -- to remove all trace of
  2924. revision control on the way *out* of CVS.
  2925. Last modified: _6/13/1997_
  2926. 5. Why does "export -D" check out every file in the Attic?
  2927. See 5B.3 for an explanation of the same problem with "update".
  2928. Last modified: _6/13/1997_
  2929. Category: /Commands_/history_hi_his/
  2930. " + "history", "hi", "his""
  2931. 1. What is "history" for?
  2932. To provide information difficult or impossible to extract out of the
  2933. RCS files, such as a "tag" history or a summary of module activities.
  2934. Last modified: _6/13/1997_
  2935. 2. Of what use is it?
  2936. I have found it useful in a number of ways, including:
  2937. Providing a list of files changed since
  2938. - A tagged release.
  2939. - Yesterday, last Thursday, or a specific date.
  2940. - Someone changed a specific file.
  2941. Providing a list of special events:
  2942. - Files added or removed since one of the above events.
  2943. - Merge failures since one of the above events. (Where did the
  2944. conflicts occur?)
  2945. - Has anyone (and who) grabbed the revision of this file I committed
  2946. last week, or are they still working blind?
  2947. Telling me how often a file/directory/module has been changed.
  2948. Dumping a summary of work done on a particular module, including who
  2949. last worked on it and what changed.
  2950. Displaying the checked-out modules and where they are being worked
  2951. on.
  2952. To tell me what users "joe" and "malcolm" have done this week.
  2953. Last modified: _6/13/1997_
  2954. 3. What is this, Big Brother?
  2955. War is Peace.
  2956. Freedom is Slavery.
  2957. Ignorance is Strength.
  2958. Normally manager types and those with the power to play Big Brother
  2959. don't care about this information. The Software Engineer responsible
  2960. for integration usually wants to know who is working on what and what
  2961. changed. Use your imagination.
  2962. Last modified: _6/13/1997_
  2963. 4. I deleted my working directory and "history" still says I have it
  2964. checked out. How do I fix it?
  2965. You can use "release -f" to forcibly add a "release" record to the
  2966. history file for a working directory associated with a "module". If
  2967. your version of "release" doesn't have the '-f' option, or you checked
  2968. out the directory using a relative path, you have to edit the
  2969. $CVSROOT/CVSROOT/history file.
  2970. You can remove the last 'O' line in the history file referring to the
  2971. module in question or add an 'F' record.
  2972. Last modified: _6/13/1997_
  2973. 5. So I *can* edit the History file?
  2974. Yes, but if you are using history at all, you should take a little
  2975. care not to lose information. I normally use Emacs on the file, since
  2976. it can detect that a file has changed out from under it. You could
  2977. also copy and zero out the history file, edit the copy and append any
  2978. new records to the edited copy before replacing it.
  2979. Last modified: _6/13/1997_
  2980. 6. Why does the history file grow so quickly?
  2981. It stores 'U' records, which come in handy sometimes when you are
  2982. tracking whether people have updated each other's code before testing.
  2983. There should (and probably will sometime) be a way to choose what
  2984. kinds of events go into the history file.
  2985. The contributed "cln_hist.pl" script will remove all the 'U' records,
  2986. plus matching pairs of 'O' and 'F' records during your normal clean up
  2987. of the history file.
  2988. Last modified: _6/13/1997_
  2989. 7. What is the difference between "cvs history -r <tag/rev>" and "cvs
  2990. history -t <tag>"?
  2991. The '-t' option looks for a Tag record stored by "rtag" in the history
  2992. file and limits the search to dates after the last <tag> of the given
  2993. name was added.
  2994. The '-r' option was intended to search all files looking for the <tag>
  2995. in the RCS files. It takes forever and needs to be rewritten.
  2996. Last modified: _6/13/1997_
  2997. 8. Why does "cvs history -c -t <tag>" fail to print anything?
  2998. You have been using "tag" instead of "rtag". The "tag" command
  2999. currently doesn't store a history record. This is another remnant of
  3000. CVS's earlier firm belief in "modules". But it also has a basis in how
  3001. "rtag" and "tag" were originally used.
  3002. "rtag" was intended for large-scale tagging of large chunks of the
  3003. Repository, an event work recording. "tag" was intended for adding and
  3004. updating tags on a few files or directories, though it could also be
  3005. used to tag the entire checked-out working tree when there is no
  3006. module defined to match the tree or when the working tree is the only
  3007. place where the right collection of revisions to tag can be found.
  3008. Last modified: _6/13/1997_
  3009. 9. "cvs history -a -o" only printed one line for each checked-out module.
  3010. Shouldn't it print all the directories where the modules are checked out?
  3011. Not as designed.
  3012. Command Question it is supposed to answer.
  3013. ---------------- ------------------------------------------
  3014. cvs history -o What modules do I have checked out?
  3015. cvs history -a -o <same for all users>
  3016. cvs history -o -w What working directories have I created
  3017. and what modules are in them?
  3018. cvs history -a -o -w <same for every user>
  3019. The -o option chooses the "checked out modules" report, which is the
  3020. default history report.
  3021. Last modified: _6/13/1997_
  3022. 10. I can't figure out "history", can you give me concrete examples?
  3023. Default output selects records only for the user who executes the
  3024. "history" command. To see records for other users, add one or more "-u
  3025. user" options or the '-a' option to select *all* users.
  3026. To list (for the selected users): Type "cvs history" and:
  3027. * Checked out modules: -o (the default)
  3028. * Files added since creation: -x A
  3029. * Modified files since creation: -c
  3030. * Modified files since last Friday: -c -D 'last Friday'
  3031. * Modified files since TAG was added: -c -t <tag>
  3032. * Modified files since TAG on files: -c -r <tag>
  3033. * Last modifier of file/Repository X? -c -l -[fp] X
  3034. * Modified files since string "str": -c -b str
  3035. * Tag history: (Actually "rtag".) -T
  3036. * History of file/Repository/module X: -[fpn] X
  3037. * Module report on "module": -m module
  3038. Last modified: _6/13/1997_
  3039. 11. Can we merge history files when we merge Repositories?
  3040. Assuming that the two Repositories have different sets of pathnames,
  3041. it should be possible to merge two history files by sorting them
  3042. together by the timestamp fields.
  3043. You should be able to run:
  3044. sort -k 1.2 ${dir1}/history ${dir2}/history > history
  3045. If you "diff" a standard history file before and after such a sort,
  3046. you might see other differences caused by garbage (split lines, nulls,
  3047. etc) in the file. If your Repository is mounted through NFS onto
  3048. multiple machines you will also see a few differences caused by
  3049. different clocks on different machines. (Especially if you don't use
  3050. NTP to keep the clocks in sync.)
  3051. Last modified: _6/13/1997_
  3052. Category: /Commands_/import_im_imp/
  3053. " + "import", "im", "imp""
  3054. 1. What is "import" for?
  3055. The "import" command is a fast way to insert a whole tree of files
  3056. into CVS.
  3057. The first "import" to a particular file within the Repository creates
  3058. an RCS file with a single revision on the "Vendor branch." Subsequent
  3059. "import"s of the same file within the Repository append a new revision
  3060. onto the Vendor branch. It does not, as some seem to believe, create a
  3061. new branch for each "import". All "imports" are appended to the single
  3062. Vendor branch.
  3063. If the file hasn't changed, no new revision is created -- the new
  3064. "Release-Tag" is added to the previous revision.
  3065. After the import is finished, files you have not changed locally are
  3066. considered to have changed in the "Main line of development". Files
  3067. you *have* changed locally must have the new Vendor code merged into
  3068. them before they are visible on the "Main line".
  3069. See 4C.6 and 4C.15
  3070. Last modified: _6/13/1997_
  3071. 2. How am I supposed to use "import"?
  3072. Create a source directory containing only the files you want to
  3073. import. Make sure you clean up any cruft left over from previous
  3074. builds or editing. You want to make sure that the directory contains
  3075. only what you want to call "source" from which everything else is
  3076. built.
  3077. If this is not the first import from this "Vendor", you should also
  3078. compare the output of "find . ! -name CVS -print | sort" executed both
  3079. at the head of a checked out working directory and at the head of the
  3080. sources to be imported. If you find any deleted or renamed files, you
  3081. have to deal with them by hand. (See 4B.8 on renaming.)
  3082. "cd" into your source directory and type:
  3083. cvs import -m "Message" <repos> <Vendor-Tag> <Release-Tag>
  3084. where <repos> is the relative directory pathname within the Repository
  3085. that corresponds to the sources you are importing.
  3086. You might also consider using the "-I !" option to avoid ignoring
  3087. anything. It is easier to remove bogus files from the Repository than
  3088. to create a sparse tree of the ignored files and rerun "import".
  3089. For example, if the FSF, CVS, Make and I are still active in the year
  3090. 2015, I'll import version 89.53 of GNU make this way:
  3091. cvs import -m "GNUmake V89.53" gnu/make GNU GNUMAKE_89_53
  3092. See 3H.13 for more details.
  3093. Last modified: _6/13/1997_
  3094. 3. Why does import put files on a branch? Why can't I work on the main
  3095. trunk instead of a Vendor branch?
  3096. This was a Design choice. The Vendor branch is the way "import" deals
  3097. with a Vendor release. It is a solution to the Engineering problem of
  3098. how to merge multiple external releases of Vendor-supplied sources
  3099. into your ongoing work. The Vendor releases are kept on a separate,
  3100. special, "Vendor" branch and your work is kept on the RCS trunk. New
  3101. Vendor releases are imported onto the Vendor branch and then merged
  3102. into your work, if there is any, on the trunk.
  3103. This way, you can use CVS to find out not only about your work, but
  3104. you can also find out what the Vendor changed by diffing between two
  3105. of the Release Tags you handed to "import".
  3106. CVS was designed to work this way. If you use CVS in some other way,
  3107. you should think carefully about what you are doing.
  3108. Note that the CVS "Main Branch" and the RCS Main Trunk are not the
  3109. same. Placing files on the Vendor Branch doesn't keep you from
  3110. creating a development branch to work on.
  3111. See Section 4C, on Branching.
  3112. If you are not working with 3rd party (i.e. Vendor) sources, you can
  3113. skip the "import" and avoid the Vendor branch entirely. It works just
  3114. as well to move pre-existing RCS files into Repository directories.
  3115. You can create a whole Repository tree by copying a directory
  3116. hierarchy of normal source files directly into the Repository and
  3117. applying CVS to it. Here's an idea you should *test* before using:
  3118. cd <your source tree>
  3119. set source = `pwd`
  3120. set module = xyzzy <<== Your choice of directory name
  3121. mkdir $CVSROOT/$module
  3122. cd $CVSROOT/$module
  3123. (cd $source; tar cf - .) | tar xvpBf -
  3124. find . -type f -exec ci -t-Original. {} \;
  3125. The RCS "ci" command, without -u or -l options, will turn your source
  3126. file into an RCS (",v") and delete the original source.
  3127. Last modified: _6/13/1997_
  3128. 4. Is there any way to import binary files?
  3129. If you configured CVS to use the GNU version of "diff" and "diff3",
  3130. then you can import any kind of file.
  3131. Binary files with RCS keywords in them are a problem, since you don't
  3132. want them to expand.
  3133. If the tree you are about to "import" is entirely filled with binary
  3134. files, you can use the '-ko' option on "import". Otherwise, I would
  3135. run the import normally, then fix the binary files as described below
  3136. in 3H.5.
  3137. See 4D.1 on Binary files.
  3138. Last modified: _6/13/1997_
  3139. 5. Why does "import" corrupt some binary files?
  3140. The RCS "co" command, when it is invoked by a CVS "checkout" or
  3141. "update" (or after a "commit") command, searches for and expands a
  3142. list of keywords within the file. They are documented in the RCS "co"
  3143. man page. Strings such as "$\Id$" (or "$\Id:"), or "$\Revision$" (or
  3144. "$\Revision:") are altered to the include the indicated information.
  3145. [[Note: The keywords should appear in the text without the '\'
  3146. character I have inserted to *avoid* expansion here. The only real RCS
  3147. keywords in this document are at the top of the file, where I store
  3148. the Revision and Date.]]
  3149. If RCS keyword strings show up in a binary file, they will be altered
  3150. unless you set the '-ko' option on the RCS files to tell RCS to keep
  3151. the original keyword values and not to expand new ones. After
  3152. "import", you can set the '-ko' option this way:
  3153. cvs admin -ko <file>
  3154. rm <file>
  3155. cvs update <file>
  3156. After an import that didn't use '-ko' (because the whole tree wasn't
  3157. of binary files) you should fix up the binary files as described above
  3158. before checking out any new copies of the files and before updating
  3159. any working directories you checked out earlier.
  3160. See 4D.1 on Binary files.
  3161. Last modified: _6/13/1997_
  3162. 6. How do I retain the original $\Revision$ strings in the sources?
  3163. If you want to leave old RCS keywords as they are, you can use the
  3164. '-ko' tricks described above.
  3165. Last modified: _6/13/1997_
  3166. 7. I imported some files for the Yarg compiler that compiles files with a
  3167. suffix of ".yarg" and whose comment prefix is "YARG> ". When I check them
  3168. out, they will no longer compile because they have this junk in them. Why?
  3169. YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>
  3170. YARG> $\Log:
  3171. # Revision 1.3 1998/03/03 00:16:16 bubba
  3172. # What is 2+2 anyway?
  3173. #
  3174. # Revision 1.2 1998/03/03 00:15:15 bubba
  3175. # Added scorekeeping.
  3176. YARG>
  3177. YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>
  3178. Well bubba, "Yarg" hasn't hit the big time yet. Neither RCS nor CVS
  3179. know about your suffix or your comment prefix. So you have two
  3180. choices:
  3181. Check out the Yarg-less module, and tell all the files about your
  3182. comment prefix. Visit each directory and type:
  3183. cvs admin -c"YARG> " *.yarg
  3184. If *all* files in the whole directory tree are Yarg files, you can use
  3185. this instead:
  3186. cvs admin -c"YARG> " .
  3187. Then save any changes you made, remove all the "*.yarg" files and grab
  3188. new copies from the Repository:
  3189. rm *.yarg (or: find . -name '*.yarg' -exec rm {} ';') (or: find .
  3190. -name '*.yarg' -print | xargs rm) (or: find . -name '*.yarg' -print0 |
  3191. xargs -0 rm if you have spaces in filenames and the GNU find/xargs.)
  3192. cvs update
  3193. It might be faster to remove the whole directory and check it out
  3194. again.
  3195. Change the import.c file in the CVS sources and add the .yarg
  3196. suffix, along with the "YARG> " comment prefix to the "comtable"
  3197. array.
  3198. If you ever plan to add new files with $\Log in them, you should also
  3199. go into the RCS sources and make the same change in the table
  3200. contained in the "rcsfnms.c" file.
  3201. Then delete the imported files from the Repository and re-"import" the
  3202. sources.
  3203. Last modified: _6/13/1997_
  3204. 8. How do I make "import" save the timestamps on the original files?
  3205. Use "import -d" to save the current timestamps on the files as the RCS
  3206. revision times.
  3207. See 4D.8 for another aspect of file timestamps.
  3208. Last modified: _6/13/1997_
  3209. 9. Why can't I "import" 3 releases on different branches?
  3210. I'll bet you typed something like this:
  3211. cd /src/blasto.v2
  3212. cvs import -b 1.1.2 VENDOR2 Version2
  3213. cd /src/blasto.v3
  3214. cvs import -b 1.1.3 VENDOR3 Version3
  3215. cd /src/blasto.v4
  3216. cvs import -b 1.1.4 VENDOR4 Version4
  3217. This is wrong, or at least it won't help you much. You have created
  3218. three separate Vendor branches, which is probably not what you wanted.
  3219. Earlier versions of CVS, as described in Brian Berliner's Usenix
  3220. paper, tried to support multiple Vendor branches on the theory that
  3221. you might receive source for the *same* program from multiple vendors.
  3222. It turns out that this is very rare, whereas the need to branch in
  3223. *your* development, for releases and for project branches, is much
  3224. greater.
  3225. So the model now is to use a single vendor branch to contain a series
  3226. of releases from the same vendor. Your work moves along on the Main
  3227. Trunk, or on a CVS branch to support a real "branch in development".
  3228. To set this up, you should type this instead of the above:
  3229. cd /src/blasto.v2
  3230. cvs import VENDOR Version2
  3231. cd /src/blasto.v3
  3232. cvs import VENDOR Version3
  3233. cd /src/blasto.v4
  3234. cvs import VENDOR Version4
  3235. Last modified: _6/13/1997_
  3236. 10. What do I do if the Vendor adds or deletes files between releases?
  3237. Added files show up with no extra effort. To handle "removed" files,
  3238. you should always compare the tree structure of the new release
  3239. against the one you have in your Repository. If the Vendor has removed
  3240. files since the previous release, go into a working directory
  3241. containing your current version of the sources and "cvs remove"
  3242. (followed by "cvs commit" to make it really take effect) each file
  3243. that is no longer in the latest release.
  3244. Using this scheme will allow you to "checkout" any version of the
  3245. vendor's code, with the correct revisions and files, by using
  3246. "checkout -r Version[234]".
  3247. Renames are harder to find, since you have to compare file contents to
  3248. determine that one has occurred. If you notice one, see 4B.8 on
  3249. renaming files.
  3250. Last modified: _6/13/1997_
  3251. 11. What about if the Vendor changes the names of files or directories, or
  3252. rearranges the whole structure between releases?
  3253. Currently CVS can't handle this cleanly. It requires "renaming" a
  3254. bunch of files or directories.
  3255. See 4B.8 on "renaming" for more details.
  3256. What I generally do is to close the Repository for a while and make
  3257. changes in both the Repository and in a copy of the vendor release
  3258. until the structure matches, then execute the import.
  3259. If you ever have to check out and build an old version, you may have
  3260. to use the new, or completely different Makefiles.
  3261. Last modified: _6/13/1997_
  3262. 12. I thought "import" was for Vendor releases, why would I use it for code
  3263. of my own? Do I have to use import?
  3264. For code you produce yourself, "import" is a convenience for fast
  3265. insertion of whole trees. It is not necessary. You can just as easily
  3266. create ",v" files using the RCS "ci" command and move them directly
  3267. into the Repository.
  3268. Other than the CVSROOT directory, the Repository consists entirely of
  3269. directories of ",v" files. The Repository contains no other state
  3270. information.
  3271. See Section 4B, on Setting up and Managing the Repository.
  3272. Last modified: _6/13/1997_
  3273. 13. How do I import a large Vendor release?
  3274. When the sum of the changes made by the Vendor and the changes made by
  3275. local developers is small, "import" is not a big problem. But when you
  3276. are managing a large Repository, any care taken up front will save you
  3277. time later.
  3278. First read the following, then, before executing "import", see the
  3279. questions in Section 4C dealing with branch merges and Vendor branch
  3280. merges.
  3281. If this is not the first import of this code, before starting, rtag
  3282. the whole directory you will be changing.
  3283. The first step is to make sure the structure of the new files
  3284. matches the structure of the current Repository.
  3285. Run "find . -print | sort" on both trees and "diff" the output.
  3286. Alter the "source" tree until the "diff" (of the list of filenames,
  3287. not of the whole trees) shows that the directory structures are
  3288. equivalent.
  3289. The "comm" command, if you have it, can help figure out what has been
  3290. added or deleted between releases.
  3291. If they deleted any files, you can handle them cleanly with "cvs
  3292. remove". The command "comm -23 files.old files.new" will show you a
  3293. list of files that need to be removed.
  3294. You should examine the list first to see if any have been renamed
  3295. rather than simply deleted.
  3296. If they renamed any files, see 4B.8 on renaming files.
  3297. Remember to *SAVE* the output from the import command.
  3298. When you have dealt with removed and renamed files, then you can
  3299. execute the import:
  3300. cd <new source>
  3301. cvs import -I ! -m "Message" <repos> <VendorTag> <ReleaseTag>
  3302. Where
  3303. "-I !" is an optional argument that keeps "import" from ignoring
  3304. files. The comparison of the "find" commands above will probably avoid
  3305. the need for this, but it is easier to remove files from the
  3306. Repository than to run a subset "import" to catch just the ignored
  3307. files. [You might have to quote or backwhack the '!'.]
  3308. Message is the log message to be stored in the RCS files.
  3309. <repos> is a relative path to a directory within the
  3310. Repository. The directory <new source> must be at
  3311. the same relative level within the new sources as
  3312. the <repos> you give is within the Repository. (I
  3313. realize this is not obvious. Experiment first.)
  3314. <VendorTag> is a Tag used to identify the Vendor who sent you
  3315. the files you are importing. All "imports" into
  3316. the same <repos> *must* use the same VendorTag.
  3317. You can find it later by using the "log" command.
  3318. <ReleaseTag> is a Tag used to identify the particular release of the
  3319. software you are importing. It must be unique and should be mnemonic
  3320. -- at least include the revision number in it. (Note: you can't use
  3321. '.' characters in a Tag. Substitute '_' or '-'.)
  3322. There will be six categories of files to deal with. (Actually there
  3323. are eight, but you have already dealt with "removed" and "renamed"
  3324. files.)
  3325. If this is the first "import" into a given <repos> directory, only the
  3326. first three of these ('I', 'L' and 'N') can occur.
  3327. Ignored file.
  3328. CVS prints: I filename
  3329. You'll need to examine it to see if it *should* have been ignored. If
  3330. you use "-I !", nothing will be ignored.
  3331. Symbolic link.
  3332. CVS prints: L linkname
  3333. Links are "ignored", but you'll probably want to create a "checkout
  3334. helper" function to regenerate them.
  3335. New file.
  3336. CVS prints: N filename
  3337. CVS creates a new file in the Repository. You don't have to do
  3338. anything to the file, but you might have to change Makefiles to refer
  3339. to it if this is really a new file.
  3340. A file unchanged by the Vendor since its last release.
  3341. CVS prints: U filename
  3342. CVS will notice this and simply add the new ReleaseTag to the latest
  3343. rev on the Vendor branch.
  3344. No work will be needed by you, whether you have changed the file or
  3345. not. No one will notice anything.
  3346. A file changed by the Vendor, but not by you.
  3347. CVS prints: U filename
  3348. CVS should add the file onto the vendor branch and attach the Release
  3349. Tag to it.
  3350. When you next execute "update" in any working directory you'll get the
  3351. new revision.
  3352. A file changed by both the Vendor and by you.
  3353. CVS prints: C filename
  3354. These are the trouble files. For each of these files (or in groups --
  3355. I usually do one directory at a time), you must execute:
  3356. cvs update -j <PreviousReleaseTag> -j <ReleaseTag>
  3357. or
  3358. cvs update -j <VendorTag:yesterday> -j <VendorTag>
  3359. It will print either 'M' (if no overlaps) or 'C', if overlaps. If a
  3360. 'C' shows up, you'll need to edit the file by hand.
  3361. Then, for every file, you'll need to execute "cvs commit".
  3362. See the part of Section 4C dealing with branch merges.
  3363. If you are truly performing a large import, you will most likely
  3364. need help. Managing those people is another problem area.
  3365. Since the merge of the Vendor branch is just like any other merge, you
  3366. should read section 4C for more info about performing and cleaning up
  3367. merges.
  3368. The larger the import, and the larger the group of people involved,
  3369. the more often you should use "tag" and "rtag" to record even trivial
  3370. milestones. See 4C.14, especially the "paranoid" section.
  3371. Before starting the import, you should install and test a "commitinfo"
  3372. procedure to record all commits in a file or via Email to a mail
  3373. archive. Along with the tags you placed on the Repository before the
  3374. import, this archive will help to track what was changed, if problems
  3375. occur
  3376. There are four stages to the recovery:
  3377. Parcel out the work -- Effective Emacs Engineering.
  3378. As input to the assignment process, you might want to examine the tree
  3379. and record the last person who changed the file. You can also
  3380. research, if you don't already know, who is expert in each area of the
  3381. software.
  3382. Examine the import log (you saved the output, right?), estimate how
  3383. much work is involved in each area and assign groups of files to
  3384. individual developers. Unless some directory is immense, it is easier
  3385. to manage if you assign whole directories to one person.
  3386. Keep a list. Suggest a completion date/time. Tell them to "commit" the
  3387. file when they are finished with the merge. If you tagged the
  3388. Repository before starting the import, you should have no trouble
  3389. figuring out what happened.
  3390. If you can, find out (or tell them) which working directory to use.
  3391. You should verify that the working directory they use is on the Main
  3392. Branch ("update -A") and without modified files.
  3393. If you trust your crew, have them notify you by Email. Have them send
  3394. you the output from "cvs update" in their working directory. You might
  3395. have to poll some people until you are certain they have finished, or
  3396. have given up. (This is not an invention. I've heard a false, "Yeah,
  3397. sure. I finished yesterday," more times that you'd believe.)
  3398. When all reports are in, go on to the Source Verification stage.
  3399. Source Verification -- CVS and other Tools.
  3400. If you didn't dictate which ones to use, find all working directories
  3401. and run "cvs -n update" in all of them. The history command and the
  3402. "commitinfo" log you set up might help to find checked out working
  3403. directories.
  3404. Sticky conflict flags will help, but they can't recover from
  3405. sloppiness or incompetence. You might want to check everything out
  3406. into a tree and grep for the parts of the merge conflict markers CVS
  3407. doesn't look for. CVS looks for the string '^>>>>>>> '. The merge
  3408. operation also puts '^<<<<<<< ' and '^======= ' markers in the file
  3409. that careless developers might leave there.
  3410. If you find problems simply by looking at the source files and working
  3411. directories, start the flogging now. Resolving the textual conflicts
  3412. is the easy part. Weed the turkeys out before reaching the next part
  3413. of the cleanup -- the resolution of logical conflicts.
  3414. Then apply a set of post-commit tags.
  3415. Logical Verification -- Diff and powerful eyeballs.
  3416. No source control system can solve the problem of resolving
  3417. distributed conflicts in program logic. If you change the argument
  3418. template for function A (defined in file A.c) and add new calls to
  3419. function A from within function B (defined in file B.c) using the old
  3420. argument format, you are outside the realm of CVS's competence.
  3421. Assign someone to understand what the Vendor changed by running "cvs
  3422. diff -c -r <PreviousReleaseTag> <ReleaseTag>", where the tags were
  3423. those handed to the last two invocations of "import".
  3424. Then have the same person compare that output (logically or you can
  3425. actually diff the diffs) to the output of the similar "cvs diff -c -r
  3426. <pre-import-tag> <post-commit-tag>". The two sets of differences
  3427. should be almost identical. They should both show only the work *you*
  3428. have performed.
  3429. Product Verification -- Build and Test.
  3430. Don't let your help off the hook until you verify that the merge
  3431. actually produced something that can compile and pass tests. Compiling
  3432. should really be part of the logical verification phase, but you
  3433. should test the output of the build system before declaring victory
  3434. and releasing the troops.
  3435. After it is all built, apply another set of tags to mark the end of
  3436. the "import process". You can delete the intermediate tags you added
  3437. during source and logic testing, but keep the "pre-import" and
  3438. "post-import" tags forever.
  3439. Of course, experience can tell you when to skip a step. But I'd start
  3440. out by considering each one as necessary unless you can prove
  3441. otherwise.
  3442. Last modified: _6/13/1997_
  3443. 14. Explain: ERROR: cannot create link to <file>: Permission denied
  3444. This error appears when you try to execute a second (or later)
  3445. "import" into the same module from a directory to which you don't have
  3446. write access.
  3447. The "link error" is caused by a feature purposely added to speed up
  3448. the import.
  3449. Though the error message is somewhat strange, it indicates that
  3450. "import" is supposed to be executed only in writable directories.
  3451. Last modified: _6/13/1997_
  3452. 15. Where does the -m <message> go when the file doesn't change?
  3453. The <message> handed to import is used as an RCS log message, but only
  3454. if the imported file changed since the last version on the Vendor
  3455. branch. If the imported file hasn't changed, then no new revision is
  3456. created. The <ReleaseTag> is still applied, but to the previous
  3457. revision. So the Tags are still correct, but the message is lost.
  3458. Maybe it should be appended to the previous log message. But currently
  3459. it isn't.
  3460. Last modified: _6/13/1997_
  3461. 16. How do I "import" just the files ignored by a previous "import"?
  3462. A real answer follows, but first, an editorial:
  3463. I am now convinced that you should always use the "-I !" option.
  3464. Removing a few extraneous files from the Repository is a lot easier
  3465. than the recovery step described below.
  3466. Let's assume your original import procedure was: (We assume there is
  3467. enough disk space in /tmp.)
  3468. cd <head-of-vendor-tree>
  3469. cvs import -m 'xyz 1.3' gnu/xyz GNU GNUXYZ_1_3 | tee /tmp/IMP
  3470. To import just the files ignored by "import", I would do this:
  3471. Create a list of the ignored files to import:
  3472. cd <head-of-vendor-tree> awk '/^I / {print $2}' /tmp/IMP | sed
  3473. 's|^gnu/xyz/||' > /tmp/IG [Edit the IG file to contain just the files
  3474. you want.]
  3475. Then create a sparse directory by handing your list to the GNU
  3476. version of "tar", installed in many places as "gtar":
  3477. mkdir /tmp/FIXUP gtar -T /tmp/IG -c -f - . | (cd /tmp/FIXUP; gtar xvBf
  3478. -)
  3479. Then rerun the import. Use the exact same command, but execute it in
  3480. the sparse directory tree you just created. And this time, tell it not
  3481. to ignore anything.
  3482. cd /tmp/FIXUP
  3483. cvs import -I ! -m 'xyz 1.3' gnu/xyz GNU GNUXYZ_1_3
  3484. Last modified: _6/13/1997_
  3485. 17. Why did "import" ignore all the symlinks?
  3486. This is another design choice.
  3487. Like the Unix "tar" command, "import" could sprout an option to follow
  3488. symbolic links, but I don't think CVS will ever follow symbolic links
  3489. by default.
  3490. Two possible future enhancements have been seriously discussed:
  3491. Treat symbolic links as data in its parent directory (the way
  3492. ClearCase does) in some sort of per-directory control file.
  3493. Treat symbolic links as version-controlled elements themselves,
  3494. whose data is the value of readlink(2).
  3495. For now, they are simply ignored.
  3496. If you want to save and reconstruct symlinks, you might want to define
  3497. a "checkout" or "update" program in the modules file which could
  3498. consult a file kept under CVS in your working directory and make sure
  3499. the specified links are in place.
  3500. Last modified: _6/13/1997_
  3501. Category: /Commands_/log_lo_rlog/
  3502. " + "log", "lo", "rlog""
  3503. 1. What is "log" for?
  3504. To provide an interface to the RCS "rlog" command, which displays
  3505. information about the underlying RCS files, including the revision
  3506. history and Tag (RCS calls it a "symbol") list.
  3507. Last modified: _6/13/1997_
  3508. 2. How do I extract the log entries between two revisions?
  3509. If both <rev1> and <rev2> are on the same branch, you can get what you
  3510. are looking for with: (If they aren't on the same branch you'll either
  3511. get an error or a display of the whole change log.)
  3512. cvs log -r<rev1>:<rev2> <file>
  3513. If you want all the revisions on the branch from <rev1> to the end of
  3514. the branch <rev1> is on, you can use:
  3515. cvs log -r<rev1>: <file>
  3516. (If <rev1> is a numeric RCS symbol attached to a branch revision with
  3517. an even number of '.'s in it, you get the whole branch.)
  3518. If you want all the revisions on the branch from the beginning of the
  3519. branch <rev2> is on up to revision <rev2>, you can use:
  3520. cvs log -r:<rev2> <file>
  3521. Note: Depending on whether <rev1> and <rev2> are:
  3522. - numeric or symbolic
  3523. - in the file or not
  3524. - on the same branch or not
  3525. the RCS "rlog" (and therefore the "cvs log") command will
  3526. display some combination of:
  3527. - error messages
  3528. - (intuitively correct) partial log listings
  3529. - a display of the entire change log.
  3530. Last modified: _6/13/1997_
  3531. 3. How do I extract the log entries on a whole branch?
  3532. cvs log -r<rev> <file>
  3533. where <rev> must be a branch revision (one with an even number of
  3534. dots) or a *non-branch* tag on a branch revision. Non-branch tags on a
  3535. branch revision are not normally attached by CVS, to add one you will
  3536. have to explicitly tag a physical branch number within each file.
  3537. Since these branch numbers are almost never the same in different
  3538. files, this command is not all that useful.
  3539. The intuitive command (at least from the CVS perspective):
  3540. cvs log -r<branch_tag> <file>
  3541. does not work.
  3542. Last modified: _6/13/1997_
  3543. 4. How do I generate ChangeLogs from RCS logs?
  3544. A program called rcs2log is distributed as part of GNU Emacs 19. A
  3545. (possibly older) version of this program appears in the contrib
  3546. directory of the cvs source tree.
  3547. Last modified: _6/13/1997_
  3548. 5. Why does "log" tell me a file was committed exactly 5 hours later
  3549. than I know it was?
  3550. I can tell by this question that you were working in a time zone that
  3551. is 5 hours behind GMT (e.g. the U.S. East Coast in winter).
  3552. RCS file dates are stored in GMT to allow users in different time
  3553. zones to agree on the meaning of a timestamp. At first glance this
  3554. doesn't seem necessary, but many companies use distributed file
  3555. systems, such as NFS or AFS, across multiple timezones.
  3556. Some standard form must be used. GMT, as the "grid origin", is an
  3557. obvious candidate. The only other reasonable choice is to put the
  3558. timezone information in all the time stamps, but that changes the RCS
  3559. file format incompatibly, a step which has been avoided in the last
  3560. few RCS releases.
  3561. Last modified: _6/13/1997_
  3562. Category: /Commands_/patch_pa_rdiff/
  3563. " + "patch", "pa", "rdiff""
  3564. 1. What is "patch" for?
  3565. To produce a "diff" between tagged releases to be handed to the
  3566. "patch" command at other sites. This is the standard way that source
  3567. patches are distributed on the network.
  3568. Last modified: _6/13/1997_
  3569. 2. Why does "patch" include files from the Attic when I use '-D'?
  3570. See the explanation of the same problem with "update -D" contained in
  3571. section 5B.
  3572. Last modified: _6/13/1997_
  3573. 3. How do I make "patch" produce a patch for one or two files? It seems to
  3574. work only with modules.
  3575. Patch is intended for producing patches of whole modules between
  3576. releases to be distributed to remote sites. Instead of "patch", you
  3577. can use the "diff" command with the '-c' context option:
  3578. cvs diff -c -r <rev/tag> -r <rev/tag> <file1> . . .
  3579. The patch command will be able to merge such a "diff" into the remote
  3580. source files.
  3581. If you configured CVS to use a version of "diff" that supports the
  3582. '-u' option, you can produce a more compact "patch" in "unidiff"
  3583. format. The latest revisions of the patch command can parse and apply
  3584. patches in "unidiff" format.
  3585. Last modified: _6/13/1997_
  3586. Category: /Commands_/release_re_rel/
  3587. " + "release", "re", "rel""
  3588. 1. What is "release" for?
  3589. To register that a module is no longer in use. It is intended to
  3590. reverse the effects of a "checkout" by adding a record to the history
  3591. file to balance the checkout record and by optionally allowing you to
  3592. delete the checked-out directory associated with the module name.
  3593. Last modified: _6/13/1997_
  3594. 2. Why can't I reverse a "cvs checkout path/name/subdir" with a "cvs
  3595. release path/name/subdir" without an "unknown module name"?
  3596. A simplistic implementation. (I can say this -- I wrote it.)
  3597. The "release" function was written for CVS 1.2 under the assumption
  3598. that the "module name" is a first class, unavoidable interface to the
  3599. Repository, allowing no way to retrieve anything other than by module
  3600. name. Though it is easier to program that way, many users of CVS
  3601. believe the modules support to be too primitive to allow such a
  3602. limitation.
  3603. Since "release" was written, other parts of CVS broke that assumption.
  3604. It needs to be revised.
  3605. Last modified: _6/13/1997_
  3606. 3. Why can't I "release" portions of a checked out directory? I should be
  3607. able to "release" any file or sub-directory within my working directory.
  3608. This isn't really a limitation in "release", per se. CVS doesn't try
  3609. to keep track of which files in which directories are "checked out"
  3610. and which are just lying there. You can delete directories and
  3611. "update" will not bring them back unless you add a special "-d"
  3612. option.
  3613. In other words, CVS doesn't keep track of how you adjust the partition
  3614. between files you consider part of your working set and files that
  3615. were checked out because they are part of the same module or
  3616. directory. And neither does "release".
  3617. In future CVS releases, "release" might become sophisticated enough to
  3618. handle both the reversal of a "checkout" and the deletion of random
  3619. portions of the working directory, but it isn't that way now.
  3620. Last modified: _6/13/1997_
  3621. 4. I removed the tree that I was about to start working on. How do I tell
  3622. cvs that I want to release it if I don't have it anymore?
  3623. See 3G.4.
  3624. Last modified: _6/13/1997_
  3625. 5. Why doesn't "release -d module" reverse a "checkout module"?
  3626. It does, if you are using "module" in a way that "release" expects: a
  3627. non-alias string in the left column of the "modules" database.
  3628. If "module" is really an alias, or if you are using a relative path in
  3629. the place of "module", or if you renamed the directory with the -d
  3630. option in the modules file or on the "checkout" command line, then the
  3631. current version of "release" won't work.
  3632. Future versions of "release" will probably fix most of these.
  3633. Last modified: _6/13/1997_
  3634. 6. Why can't I release a module renamed with "cvs checkout -d"?
  3635. The current version of "release" doesn't know how to track the
  3636. renaming option ('-d') of the "checkout" command. It will probably be
  3637. fixed in the future.
  3638. Last modified: _6/13/1997_
  3639. Category: /Commands_/remove_rm_delete/
  3640. " + "remove", "rm", "delete""
  3641. 1. What is "remove" for?
  3642. To remove a file from the working branch. It removes a file from the
  3643. main branch by placing it in an "Attic" directory.
  3644. Last modified: _6/13/1997_
  3645. 2. Why doesn't "remove" work on directories when it appears to try?
  3646. Oversight. It should be able to delete an empty directory, but you
  3647. still don't have a way to remember when it was there and when it
  3648. disappeared to allow the "-D " option to work.
  3649. You'll have to remove the working directory and the matching directory
  3650. in the Repository.
  3651. Note that you want to do a _cvs remove dir_ in the working directory,
  3652. do a cvs commit, and then do a _rmdir dir_ in the Repository.
  3653. (msusrtsp.mark at eds dot com)
  3654. Last modified: _12/18/1997_
  3655. 3. I don't like removing files. Is there another way to ignore them?
  3656. There's no reason to be hasty in using the "remove" command.
  3657. If there is a way to ignore files in your build procedures, I'd just
  3658. do that. Later, when you decide that the files are really ancient, you
  3659. can execute a "remove" command to clean up.
  3660. The CVS "ignore" concept can't ignore files already in CVS.
  3661. Last modified: _6/13/1997_
  3662. 4. I just removed a file. How do I resurrect it?
  3663. If you executed "remove", but haven't typed "commit" (you can tell
  3664. this by the 'R' notation that "update" prints next to the file), you
  3665. can execute "add" to reverse the "remove".
  3666. If you followed the "remove" with a "commit", you'll have to move it
  3667. back out of the Attic by hand:
  3668. I use something like this: (csh-like syntax)
  3669. set repos = `cat ./CVS/Repository`
  3670. mv $repos/Attic/filename,v $repos/filename,v
  3671. (If you use relative paths in your Repository files, that first line
  3672. becomes: set repos = $CVSROOT/`cat ./CVS/Repository`)
  3673. While a file is in the Attic, you can't "add" another file by the same
  3674. name. To add such a file you either have to move it by hand as in the
  3675. above, or delete it from the Attic.
  3676. The main reason for the Attic is to retain files with tags in them. If
  3677. you execute: "update -r <oldtag>", files with <oldtag> attached to
  3678. some revision will be taken from the normal Repository area and from
  3679. the Attic. That's why you can't "add" a file with the same name.
  3680. "remove" only moves a file off the main branch, it doesn't obliterate
  3681. it.
  3682. Last modified: _6/13/1997_
  3683. 5. Why doesn't "remove" delete the file? Instead, it prints an error
  3684. message and tells me to remove the file by hand.
  3685. Design choice. Unix software written within last decade, usually
  3686. requires an extra verification step, such as answering a question or
  3687. adding a flag on the command line. CVS currently requires that you
  3688. delete the file first unless you specify the '-f' (force) option,
  3689. which deletes the file before performing "cvs remove".
  3690. Last modified: _6/13/1997_
  3691. Category: /Commands_/rtag_rt_rfreeze/
  3692. " + "rtag", "rt", "rfreeze""
  3693. 1. What is "rtag" for?
  3694. To add a symbolic label (a "tag") to the last committed revisions of a
  3695. module directly in the Repository.
  3696. Last modified: _6/13/1997_
  3697. 2. Why use "rtag"? It assumes no one is changing the Repository.
  3698. Though the "tag" command is more useful in marking the revisions you
  3699. have in a particular working directory, "rtag" is much handier for
  3700. whole-Repository actions, which occur at major release boundaries.
  3701. Last modified: _6/13/1997_
  3702. 3. What revision does "rtag -r <tag1> <tag2>" actually put the tag on?
  3703. In short, the '-r' option is another way to select the revision to
  3704. tag. The revision is selected the same way for all commands that
  3705. accept a "-r <tag/rev>" option.
  3706. Depending on whether <tag1> is a <branch_tag>, or a non-branch <tag>
  3707. and on whether you use the '-b' option to "rtag", you get four
  3708. different results:
  3709. rtag -r <tag1> <tag2>
  3710. Adds the non-branch tag <tag2> to the same revision that the
  3711. non-branch tag <tag1> is attached to.
  3712. Example:
  3713. <tag1> --> TT1
  3714. <tag2> --> TT2
  3715. <file> --> Symbols: TT1:1.4
  3716. After --> Symbols: TT1:1.4,TT2:1.4
  3717. rtag -r <branch_tag1> <tag2>
  3718. Adds the non-branch tag <tag2> to the HEAD of (the highest revision
  3719. number on) the branch labelled with tag <branch_tag1>.
  3720. Example:
  3721. <branch_tag1> --> BR1
  3722. <tag2> --> TT2
  3723. <file> --> Symbols: BR1:1.2.0.2 (1.2.2.5 is HEAD)
  3724. After --> Symbols: BR1:1.2.0.2,TT2:1.2.2.5
  3725. If the branch tagged by <branch_tag1> has not been created, then the
  3726. tag shows up on the branch point revision:
  3727. Example:
  3728. <branch_tag1> --> BR1
  3729. <tag2> --> TT2
  3730. <file> --> Symbols: BR1:1.2.0.2 (No 1.2.X exists.)
  3731. After --> Symbols: BR1:1.2.0.2,TT2:1.2
  3732. rtag -b -r <tag1> <branch_tag2>
  3733. Adds the magic branch tag <branch_tag2> to the revision that the
  3734. non-branch tag <tag1> is attached to, preparing it to be a branch
  3735. point.
  3736. Example:
  3737. <tag1> --> TT1
  3738. <branch_tag2> --> BR2
  3739. <file> --> Symbol: TT1:1.4
  3740. After --> Symbol: TT1:1.4, BR2:1.4.0.2
  3741. rtag -b -r <branch_tag1> <branch_tag2>
  3742. Adds the magic branch tag <branch_tag2> to the revision at the HEAD of
  3743. (the highest revision number on) the branch labelled with
  3744. <branch_tag1>, preparing it to be a branch point.
  3745. Example:
  3746. <branch_tag1> --> BR1
  3747. <branch_tag2> --> BR2
  3748. <file> --> Symbol: BR1:1.2.0.2 (1.2.2.5 is HEAD)
  3749. After --> Symbol: BR1:1.2.0.2,BR2:1.2.2.5.0.2
  3750. If the branch tagged by <branch_tag1> has not been created, then the
  3751. tag shows up as a second branch off the same branch point revision:
  3752. Example:
  3753. <branch_tag1> --> BR1
  3754. <tag2> --> TT2
  3755. <file> --> Symbols: BR1:1.2.0.2 (No 1.2.X exists.)
  3756. After --> Symbols: BR1:1.2.0.2,TT2:1.2.0.4
  3757. In all four cases above, if <tag2> already exists on the file, you get
  3758. an error unless you specify the '-F' option.
  3759. In all four cases, if <tag1> does not exist on the file, <tag2> is not
  3760. added unless you specify the '-f' option.
  3761. Last modified: _6/13/1997_
  3762. 4. What happens if the tags are the same in "rtag -r <tag> <tag>"?
  3763. Again, there are four cases depending on whether <tag> is a branch
  3764. tag, or a non-branch tag and on whether you use the '-b' option to
  3765. "rtag":
  3766. rtag -r <tag> <tag>
  3767. Is a no-op. It does nothing even with '-F' specified.
  3768. If you add the '-f' option ("rtag -f -r <tag> <tag>"), then <tag> is
  3769. attached to the latest revision on the Main Branch if the file does
  3770. *not* already have <tag> on some revision.
  3771. If the <tag> is already on the file, using "rtag -f" is still a no-op.
  3772. rtag -r <branch_tag> <branch_tag>
  3773. Produces an error, since the <branch_tag> is already on some revision
  3774. of the file.
  3775. But, "rtag -F -r <branch_tag> <branch_tag>" turns the magic branch tag
  3776. into a non-branch tag.
  3777. Symbols: BR1:1.4.0.2 becomes Symbols: BR1:1.4
  3778. rtag -b -r <tag> <tag>
  3779. Produces an error, since the <tag> is already on the file.
  3780. But, "rtag -F -b -r <tag> <tag>" turns the non-branch tag into a magic
  3781. branch tag.
  3782. Symbols: BR1:1.4 becomes Symbols: BR1:1.4.0.2
  3783. rtag -b -r <branch_tag> <branch_tag>
  3784. Produces an error, since the <branch_tag> is already on the file.
  3785. But, "rtag -F -b -r <branch_tag> <branch_tag>" increments the branch
  3786. number. It essentially removes the branch and creates a new one by the
  3787. same name.
  3788. Symbols: BR1:1.2.0.4 becomes Symbols: BR1:1.2.0.6
  3789. Last modified: _6/13/1997_
  3790. 5. Why doesn't "rtag -b -r <branch_tag1> <branch_tag2>" rename or duplicate
  3791. a magic branch tag?
  3792. None of the "tag" or "rtag" options rename anything. They only apply
  3793. (or, with the '-F' option, move) tags to specific revisions in the
  3794. file.
  3795. See 3M.[3-4] above for details of how it works.
  3796. To rename a non-branch tag, see 3O.9. To rename a magic branch tag,
  3797. see 4D.5
  3798. Last modified: _6/13/1997_
  3799. Category: /Commands_/status_st_stat/
  3800. " + "status", "st", "stat""
  3801. 1. What is "status" for?
  3802. To display the status of files, including the revision and branch you
  3803. are working on and the existence of "sticky" information.
  3804. Last modified: _6/13/1997_
  3805. 2. Why does "status" limit the File: at the top to 17 characters?
  3806. Designed that way to line up with other data. You can find the whole
  3807. filename in the line beginning with "RCS version:", which is not
  3808. limited in length.
  3809. Last modified: _6/13/1997_
  3810. 3. Why does it print "Sticky" lines when the values are "(none)"?
  3811. Oversight. It should probably elide lines without information.
  3812. Last modified: _6/13/1997_
  3813. 4. Shouldn't the status "Needs Checkout" be "Needs Update"?
  3814. Probably.
  3815. [[Did this show up in CVS 1.4?]]
  3816. Last modified: _6/13/1997_
  3817. Category: /Commands_/tag_ta_freeze/
  3818. " + "tag", "ta", "freeze""
  3819. 1. What is "tag" for?
  3820. To add a symbolic label (a "tag") to the RCS files last checked out,
  3821. updated or committed in a working directory.
  3822. Last modified: _6/13/1997_
  3823. 2. What is the difference between "tag" and "rtag"?
  3824. The end result of both commands is that a <tag>, or symbolic name, is
  3825. attached to a single revision in each of a collection of files.
  3826. The differences lie in:
  3827. The collection of files they work on.
  3828. "rtag" works on the collection of files referred to by a "module" name
  3829. as defined in the "modules" file, or a relative path within the
  3830. Repository.
  3831. "tag" works on files and directories specified on the command line
  3832. within the user's working directory. (Default is '.')
  3833. Both commands recursively follow directory hierarchies within the
  3834. named files and directories.
  3835. The revisions they choose to tag.
  3836. "rtag" places a tag on the latest committed revision of each file on
  3837. the branch specified by the '-r' option. By default it tags the Main
  3838. Branch.
  3839. "tag" places a tag on the BASE (i.e. last checked out, updated or
  3840. committed) revision of each file found in the working directory. (The
  3841. BASE revision of a file is the one stored in the ./CVS/Entries file.)
  3842. A different set of command line options.
  3843. For example, "rtag" takes a "-r <oldtag>" option to retag an existing
  3844. tag. The "tag" command does not.
  3845. How it is logged.
  3846. Currently "rtag" records the <tag> and the module in the "history"
  3847. file, while "tag" does not.
  3848. Last modified: _6/13/1997_
  3849. 3. Why does "tag -b" not put a tag on the Branch Point revision? How do I
  3850. refer to the Branch Point?
  3851. This is probably an oversight, or a disbelief in the need for it. If
  3852. everything works perfectly, the "update -j" command will do the merge
  3853. you need and you don't need to check up on it by playing with the
  3854. branch point revision.
  3855. The '-b' option attaches a magic branch tag to allow CVS later to
  3856. figure out the branch point. The actual revision that <tag> is
  3857. attached to does not exist. References to the branch tag are
  3858. equivalent to references to the latest revision on the branch.
  3859. There is no way to refer to the branch point without adding a
  3860. non-branch tag. You might want to add non-branch tags as a habit and
  3861. add branch tags later, possibly immediate after adding the non-branch
  3862. tag. See 4C.3 on Creating a Branch.
  3863. Last modified: _6/13/1997_
  3864. 4. So "{r}tag" labels a bunch of files. What do you use a Tag for?
  3865. You use it to "checkout" the labeled collection of files as a single
  3866. object, referring to it by name.
  3867. Anywhere a revision number can be used a Tag can be used. In fact tags
  3868. are more useful because they draw a line through a collection of
  3869. files, marking a development milestone.
  3870. The way to think about a Tag is as a curve drawn through a matrix of
  3871. filename vs. revision number. Consider this:
  3872. Say we have 5 files (in some arbitrary modules, some may be in 2 or
  3873. more modules by name, some may be in 2 or more modules because of the
  3874. Repository tree structure) with the following revisions:
  3875. file1 file2 file3 file4 file5
  3876. 1.1 1.1 1.1 1.1 /--1.1* <-*- <tag>
  3877. 1.2*- 1.2 1.2 -1.2*-
  3878. 1.3 \- 1.3*- 1.3 / 1.3
  3879. 1.4 \ 1.4 / 1.4
  3880. \-1.5*- 1.5
  3881. 1.6
  3882. At some time in the past, the '*' versions were tagged. Think of the
  3883. <tag> as a handle attached to the curve drawn through the tagged
  3884. revisions. When you pull on the handle, you get all the tagged
  3885. revisions. Another way to look at it is that you draw a straight line
  3886. through the set of revisions you care about and shuffle the other
  3887. revisions accordingly. Like this:
  3888. file1 file2 file3 file4 file5
  3889. 1.1
  3890. 1.2
  3891. 1.1 1.3 _
  3892. 1.1 1.2 1.4 1.1 /
  3893. 1.2*----1.3*----1.5*----1.2*----1.1 (--- <-- Look here
  3894. 1.3 1.6 1.3 \_
  3895. 1.4 1.4
  3896. 1.5
  3897. I find that using these visual aids, it is much easier to understand
  3898. what a <tag> is and what it is useful for.
  3899. Last modified: _6/13/1997_
  3900. 5. How do I get "tag" and "rtag" to send mail the way "commit" does?
  3901. The "commit" command is supported by two files ("commitinfo" and
  3902. "loginfo") not used by other commands. To do logging the same way for
  3903. "tag" and "rtag" would require another file like loginfo, which
  3904. currently doesn't exist.
  3905. The "rtag" command requires a "module" entry, which can specify a
  3906. "tag" program using the "-t programname" option on the module line.
  3907. There is no equivalent support for "tag".
  3908. Last modified: _6/13/1997_
  3909. 6. Why can't "tag" handle the '-r' option that "rtag" takes?
  3910. Oversight. The answer is probably "Fixed in a Future Release."
  3911. Last modified: _6/13/1997_
  3912. 7. After a "tag <tag>" in my working directory, why doesn't "checkout -r
  3913. <tag>" somewhere else produce copies of my current files?
  3914. The only reason this would fail, other than misspelling the <tag>
  3915. string, is that you didn't "commit" your work before "tagging" it.
  3916. Only committed revisions may be tagged. Modified files are not marked
  3917. for later tagging.
  3918. Last modified: _6/13/1997_
  3919. 8. Why doesn't "tag" write a history record the way "rtag" does?
  3920. The "rtag" command was originally intended to place major "release"
  3921. tags onto modules. The "tag" functionality was developed to *move* the
  3922. more significant tag when slight changes to individual files sneaked
  3923. in after the release tag was stamped onto the Repository.
  3924. The significant event was the "rtag", which was recorded in the
  3925. "history" file for the "history -T" option to work.
  3926. It turns out that "tag" is generally more useful than "rtag", so the
  3927. model has changed. Future revisions of CVS will probably store both
  3928. kinds of tags in the history file.
  3929. Last modified: _6/13/1997_
  3930. 9. How do I rename a <tag>?
  3931. For a procedure to rename a branch tag, See section 4D.5 The following
  3932. covers only non-branch tags.
  3933. First, pick a <newtag> that is not in use. You could reuse (i.e. move)
  3934. an existing tag to the new revisions using the '-F' option, but that
  3935. will confuse matters when both tags are not already on a file. (It
  3936. will probably confuse "rtag -f" too.)
  3937. Use "rtag" to place <newtag> only on revisions attached to <oldtag> in
  3938. the whole Repository, then delete the old one.
  3939. cvs rtag -r <oldtag> <newtag> world
  3940. cvs rtag -d <oldtag> world.
  3941. You can also checkout or update your working directory to the <oldtag>
  3942. and "tag" rather than "rtag" the result. But that will take longer and
  3943. it has the chance of producing conflicts.
  3944. cvs update -r <oldtag>
  3945. cvs tag <newtag>
  3946. cvs tag -d <oldtag>
  3947. cvs update -A (or cvs update -r <previous_tag>)
  3948. Last modified: _6/13/1997_
  3949. Category: /Commands_/update_up_upd/
  3950. " + "update", "up", "upd""
  3951. 1. What is "update" for?
  3952. The "update" command is by far the most important command and is
  3953. probably also the most used command.
  3954. It has five purposes: (And many options.)
  3955. To display the status of your working files.
  3956. Though a plain "update" also displays the status, it does so after
  3957. possibly altering your working directory. To see the status of your
  3958. working files without changing anything, type:
  3959. cvs -n update {optional list of files}
  3960. To merge changes made by others to the branch you are working on
  3961. into your working files.
  3962. Each working directory is attached to a branch, usually the Main
  3963. branch. To merge changes made on your working branch since your last
  3964. checkout, update or commit, type:
  3965. cvs update {optional list of files}
  3966. To merge changes made on another branch into the branch you are
  3967. working on (your "working branch").
  3968. If you want to grab a whole branch, from the branch point, which is
  3969. assumed to be on the Main Branch, to the end of the branch, you type:
  3970. cvs update -j <branch_tag> {optional files}
  3971. If you want to grab the changes made between two tags or revisions,
  3972. you type:
  3973. cvs update -j <tag1> -j <tag2> {optional files}
  3974. (If you are working with a single file, the Tags could also be
  3975. revisions numbers. Unless you take great care to match revision
  3976. numbers across different files (a waste of time given the way Tags
  3977. work), using revision numbers in place of the Tags for multiple files
  3978. would be meaningless.)
  3979. To move your working directory to another branch.
  3980. A working directory is presumed to be attached to (or working on) a
  3981. particular branch, usually the Main branch. To alter what CVS believes
  3982. to be your working branch, you "move" to that branch.
  3983. To move to a tagged branch, type:
  3984. cvs update -r <branch_tag> {optional files}
  3985. To move to the Main Branch, type:
  3986. cvs update -A {optional files}
  3987. If you have modified files in your working directory, this is not a
  3988. clean move. CVS will attempt to merge the changes necessary to make it
  3989. look like you made the same changes to the new branch as you made in
  3990. the old one. But if you do this twice without resolving the merge
  3991. conflicts each time, you can lose work.
  3992. To retrieve old revisions of files.
  3993. This option is similar to 4 above but you are not restricted to using
  3994. a <branch_tag>. You may specify any revision or <tag> with '-r' and
  3995. get the specified revision or the tagged revision:
  3996. cvs update -r <tag/rev> {optional files}
  3997. Or you may specify any date with '-D':
  3998. cvs update -D <date> {optional files}
  3999. The '-p' option sends the revisions to standard output (normally your
  4000. terminal) rather than setting the "sticky" tag and changing the files.
  4001. Last modified: _6/13/1997_
  4002. 2. What do 'U', 'M' and 'C' mean when I type "update"? Are they different
  4003. for "cvs -n update"?
  4004. "cvs update" merges changes made to the Repository, since your last
  4005. "checkout", "update" or "commit", into your working files. You can
  4006. think of it as changing your BASE revision.
  4007. "cvs update" prints lines beginning with:
  4008. 'U' after replacing your unmodified file with a different
  4009. revision from the Repository.
  4010. 'M' for two different reasons:
  4011. for files you have modified that have not changed in the Repository.
  4012. after a merge, if it detected no conflicts.
  4013. 'C' after a merge, if it detected conflicts. See 2D.7 and 3P.6 for
  4014. more info on conflict resolution and "sticky conflicts."
  4015. "cvs -n update" shows what it *would* do, rather than doing it. Or,
  4016. another way of looking at it, "cvs -n update" displays the
  4017. relationship between your current BASE revisions (identified in your
  4018. ./CVS/Entries file) and the HEAD revisions (the latest revisions in
  4019. the Repository).
  4020. "cvs -n update" prints lines beginning with:
  4021. 'U' for files you have not modified that have changed in the
  4022. Repository.
  4023. 'M' for files you have modified that have not changed in the
  4024. Repository.
  4025. 'C' for files you have modified that have also been changed in the
  4026. Repository.
  4027. See 4C.6 for what the letters mean when merging in from another
  4028. branch. The output is almost the same for a normal update if you
  4029. consider the Repository as the branch and your working directory as
  4030. the "trunk".
  4031. Last modified: _6/13/1997_
  4032. 3. What's the difference between "update" and "checkout"?
  4033. See 3C.4 above.
  4034. Last modified: _6/13/1997_
  4035. 4. Why don't I get new files when I execute "update"?
  4036. There are six reasons for nothing to happen during an "update":
  4037. Nothing on your branch changed in the Repository.
  4038. If no one has committed anything to the branch you are working on
  4039. (normally the Main branch) since the last time you executed
  4040. "checkout", "update" or "commit", nothing will happen.
  4041. It's like shouting "xyzzy" or "plugh" in the wrong room.
  4042. You have a "sticky" non-branch <tag> or <date> attached to the
  4043. working files you are trying to "update".
  4044. At some time in the past you checked out or updated your directory
  4045. with the "-r <tag>" or "-D <date>" option. Until you do it again with
  4046. a different tag or date, or go back to the Main Branch with "update
  4047. -A", you will never again see any updates.
  4048. The ./CVS/Entries.Static file exists and you are expecting a new
  4049. file.
  4050. If your ./CVS administrative directory contains a file named
  4051. Entries.Static, no files will be checked out that aren't already in
  4052. the Entries or Entries.Static file.
  4053. You forgot to use the '-d' option and are looking for new
  4054. directories.
  4055. If you execute "update" without the '-d' option, it will not create
  4056. new directories that have been added to the Repository.
  4057. You typed "update" instead of "cvs update".
  4058. On most Unix systems, your disk caches are now furiously being flushed
  4059. by multiple update daemons, destroying performance and proving to
  4060. management that you need more CPU power. :-)
  4061. On HP systems you might be asked what package you want to install from
  4062. the "update server".
  4063. Someone removed (using "admin -o") your BASE revision (the revision
  4064. CVS thought you had in your working directory), then committed a
  4065. "replacement". CVS is now confused because the revision in the
  4066. Repository matches your BASE revision when the files themselves don't
  4067. match. See 3B.6.
  4068. Last modified: _6/13/1997_
  4069. 5. Why does "update" say 'M' both for plain modified files and for
  4070. successful (i.e. conflict-free) merges? Aren't they different?
  4071. A design choice. Yes, they are different internally, but that
  4072. shouldn't matter. Your files are in the same condition after the
  4073. "update" as they were before -- a "diff" will display only your
  4074. modifications. And you are expected to continue onward with parts two
  4075. and three of the normal development cycle: "emacs" (a synonym for
  4076. "edit" in most of the civilized world) and "commit".
  4077. Last modified: _6/13/1997_
  4078. 6. What's a "sticky conflict"? How does it know a conflict occurred?
  4079. When a "cvs update" (or an "update -j") creates a conflict, it prints
  4080. a 'C' and stores the timestamp of the file after the merge in a
  4081. special field in the ./CVS/Entries file.
  4082. This conflict indication implies that the merge command altered your
  4083. working file to contain conflict markers surrounding the overlapping
  4084. code segments. For example, say that
  4085. - Two developers acquire revision 1.2 of <file> via "checkout" or
  4086. "update".
  4087. - Developer A changes line 1 from "9999" to "5555", then commits the
  4088. file, creating revision 1.3.
  4089. - Developer B changes line 1 from "9999" to "7777", then tries to
  4090. commit the file, but is blocked because the file is not up to date.
  4091. Developer B then runs "update" and sees the conflict marker 'C'. The
  4092. beginning of the file would look like this:
  4093. <<<<<<< <file> The working <file> in question.
  4094. 7777 Change made to the working <file>.
  4095. =======
  4096. 5555 Change made in the first commit (1.3)
  4097. >>>>>>> 1.3 The revision created by the first commit.
  4098. The conflict is "sticky", which means that until the conflict is
  4099. cleared, the "update" command will continue to display the file's
  4100. status as 'C' and the "status" command will show the file's status as
  4101. "Unresolved Conflict".
  4102. Until the conflict is cleared, "commit" is blocked for this file.
  4103. The sticky conflict indicator can be cleared by:
  4104. Resolving the conflict by editing the file. Two things must happen
  4105. before the conflict is considered resolved:
  4106. The timestamp of the file must change. *and* The file must contain no
  4107. conflict markers. (The string searched for in the file is the regexp:
  4108. "^>>>>>>> ".)
  4109. After clearing the sticky conflict indicator, you may then commit the
  4110. file normally.
  4111. Removing the file and running "update". This throws away the local
  4112. changes and accepts the latest committed file on this branch. No
  4113. commit is needed.
  4114. Forcing the commit to happen by using "commit -f". This is probably
  4115. a mistake since there are few lines of real text that begin with
  4116. ">>>>>>> ".
  4117. Last modified: _6/13/1997_
  4118. 7. Is there a feature to tell me what I have changed, added and removed
  4119. without changing anything?
  4120. The command "cvs -n update" will do exactly that.
  4121. Last modified: _6/13/1997_
  4122. 8. Why were all my files deleted when I executed "update"?
  4123. You probably executed "update -r <tag>" some time ago, then removed
  4124. <tag> from the Repository files. "update -r <tag>" will delete a file
  4125. that doesn't contain <tag>.
  4126. A way to fix this is to "cd" into your working directory and type:
  4127. cvs update -A
  4128. If you don't want the latest revisions on the Main (or Vendor) Branch,
  4129. then decide what Tag (normal or branch) you want and type:
  4130. cvs update -r <the_tag_you_want>
  4131. Another way to make a file disappear is to execute "update -D <date>"
  4132. where <date> is before the date stamped onto the first revision in the
  4133. RCS file.
  4134. Last modified: _6/13/1997_
  4135. Category: /Past__Future_/
  4136. " Past & Future "
  4137. Category: /Past__Future_/Bugs_and_Patches/
  4138. " + Bugs and Patches"
  4139. 1. Why can't CVS handle deletion of directories?
  4140. An oversight, probably. [[Fixed in a future release?]]
  4141. Last modified: _6/13/1997_
  4142. 2. Why can't CVS handle the moving of sources from one place in the
  4143. directory hierarchy to another?
  4144. A "renaming database" has been proposed to track the history of
  4145. pathname changes in the Repository. A general solution is a difficult
  4146. problem. See 4B.8.
  4147. Last modified: _6/13/1997_
  4148. 3. When I typed "cvs update -D <date>", why did it check out all
  4149. sorts of ancient files from the Attic? Shouldn't it just create the
  4150. set of files and revisions that existed at that date?
  4151. This seems to be a bug, but is really the lack of any obvious place to
  4152. store the date when a file is "removed".
  4153. There are four ranges of dates that CVS has to deal with when trying
  4154. to determine what revision was available on <date>:
  4155. Dates before the earliest revision in the file.
  4156. Dates between any two revisions in the file.
  4157. Dates between the latest revision in the file and the date when the
  4158. file was moved to the Attic by "commit".
  4159. Dates after moving the file to the Attic.
  4160. Since the date when a file is moved to the Attic is not stored
  4161. anywhere, CVS can't tell the difference between #3 and #4. To avoid
  4162. not producing a file that should exist in case #3, it produces
  4163. extraneous files in case #4.
  4164. For the above reason, if you have removed files in the Attic, it is
  4165. better to use "-r <tag>, or even "-r HEAD" than to use a date spec.
  4166. If you must use "-D <date>", then you should either archive and delete
  4167. Attic files (losing some past history) or construct your Makefiles to
  4168. work with an explicit list of files and let the old source files stay
  4169. in the working directory. The contents of the revision-controlled
  4170. Makefile can then be considered to contain deletion "information".
  4171. Last modified: _6/13/1997_
  4172. 4. When I typed "cvs update -D <date>" in my branch, why did it screw up
  4173. all my files?
  4174. Currently, the internal routine ("version_ts") that looks up info
  4175. about a file, overrides both the tag and date if *either* the tag or
  4176. date is specified on the command line. If only the date is specified,
  4177. it should not override a branch tag, but it does.
  4178. In CVS 1.3, the documented "-D <branch_tag>:<date>" syntax only works
  4179. with the Main Branch and the Vendor Branch.
  4180. [[Is this fixed in CVS 1.4? This is one item I didn't check.]]
  4181. Last modified: _6/13/1997_
  4182. 5. When I executed "checkout" into an existing directory I got "No such
  4183. file or directory" errors. Why?
  4184. Though the man page says that "checkout" turns into an "update -d" in
  4185. directories that already exist, it is referring to directories that
  4186. already exist *and* were created by CVS.
  4187. When you try to run "checkout" on top of an existing directory
  4188. structure, some of which wasn't created by CVS, it will handle
  4189. directories and non-CVS files within directories already under CVS,
  4190. but it will display the above error on non-CVS files within non-CVS
  4191. directories.
  4192. Last modified: _6/13/1997_
  4193. 6. Why does "update" send all output to the terminal after 26 files have
  4194. been updated?
  4195. CVS uses the "tmpnam()" function to generate temporary file names. The
  4196. ANSI standard for the "tmpnam()" function says:
  4197. "The tmpnam function generates a different string each time it is
  4198. called, up to TMP_MAX times. If it is called more than TMP_MAX times,
  4199. the behavior is implementation defined."
  4200. Later it says that the value of "TMP_MAX shall be at least 25."
  4201. On some platforms, the above specification is taken literally by
  4202. turning "at least 25" into "exactly 26" and by doing something foolish
  4203. (i.e. "implementation defined") after that. Some systems return the
  4204. same name repeatedly, which causes one form of trouble. Others return
  4205. NULL or garbage, which causes a different form of trouble.
  4206. The broken systems appear to be cycling a single character through the
  4207. alphabet. SunOS cycles 3 characters through the alphabet, so it won't
  4208. cause trouble until 26 cubed or 17576 calls to "tmpnam()".
  4209. Since CVS doesn't depend on the exact format of the tmp files, the
  4210. workaround is to provide a "tmpnam()" that doesn't have a limit on the
  4211. number of calls to it.
  4212. Last modified: _6/13/1997_
  4213. 7. Why does the merge occasionally resurrect lines of code?
  4214. The diff3 program provided by GNU diff version 1.15 has a bug that
  4215. occasionally causes text to come back from the dead.
  4216. This is an old problem which you can avoid by upgrading to the latest
  4217. GNU "diffutils" package. If you were using GNU diff version 1.15 and
  4218. plan to upgrade to the latest GNU diff program, see the next question.
  4219. Last modified: _6/13/1997_
  4220. 8. Why does the merge fail when my "rcsmerge" program is configured to use
  4221. GNU diff version 2.1 or later?
  4222. A change in the overlap format was introduced in GNU diff3 between
  4223. versions 2.0 and 2.1 that causes RCS versions before 5.6.0.1 to fail
  4224. during a merge.
  4225. To get consistent rcsmerge behavior, you have four choices:
  4226. Go back to using GNU diff 1.15 or 2.0 with RCS versions 5.5 or 5.6.
  4227. If you want to use GNU diff 2.1 or later, you'll have to pick one of
  4228. the other three choices in this list.
  4229. Grab RCS version 5.6.0.1 from an FSF archive and set the DIFF3_A
  4230. macro to '1' as it tells you to in the Makefile:
  4231. #define DIFF3_A 1
  4232. Patch the RCS 5.6 source. Change line 84 in "merger.c" from:
  4233. DIFF3, "-am", "-L", label[0], "-L", label[1], to DIFF3, "-amE", "-L",
  4234. label[0], "-L", "", "-L", label[1],
  4235. Wait both for RCS version 5.7 to be released and for a new version
  4236. of CVS that can deal with it.
  4237. Last modified: _6/13/1997_
  4238. Category: /Past__Future_/Contributors/
  4239. " + Contributors"
  4240. 1. Who wrote CVS?
  4241. Brian Berliner <berliner@sun.com> converted a collection of scripts
  4242. written by Dick Grune <dick@cs.vu.nl> into a C program, then added all
  4243. sorts of features. He continues to maintain CVS.
  4244. Jeff Polk <polk@bsdi.com> wrote much of the code added between
  4245. revisions 1.2 and 1.3. Many others were involved at some level.
  4246. david d zuhn <zoo@armadillo.com> fixed a number of bugs, added some of
  4247. the new features, reworked the whole thing to be more portable, and
  4248. provided much of the energy to push CVS 1.4 out the door.
  4249. Jim Kingdon implemented CVS 1.5's remote repository access features,
  4250. fixed many bugs, and managed the release of version 1.5.
  4251. Take a look at the README and the ChangeLog files in the CVS sources
  4252. for more contributors.
  4253. Last modified: _6/13/1997_
  4254. 2. You didn't write all of this FAQ, did you?
  4255. In the original hunt for questions to answer (performed in Jan/Feb,
  4256. 1993), I polled hundreds of people and I rephrased all sorts of text
  4257. found on the net. Between 2/93 and 10/93, I released about 20
  4258. versions, with corrections and additions from the info-cvs mailing
  4259. list and private correspondence.
  4260. Between 10/93 and 10/94 I extracted frequently asked questions from
  4261. the 1200 mail messages to the info-cvs mailing list, turned them into
  4262. focused questions and tried to answer them.
  4263. 93/02/?? ~4000 lines 93/06/?? ~5000 lines 93/10/23 7839 lines 278K
  4264. 94/10/29 9856 lines 360K 95/05/09 9981 lines 365K
  4265. Because there are so many posers of questions, I will list only those
  4266. who contribute answers or help significantly with the content and
  4267. structure of this document.
  4268. If I used someone else's text verbatim, I mentioned it in the given
  4269. answer. The people whose email postings have added to this document or
  4270. who have added to my understanding are:
  4271. Brian Berliner <berliner@sun.com>, CVS maintainer. Paul Eggert
  4272. <eggert@twinsun.com>, RCS maintainer.
  4273. Gray Watson <gray@antaire.com> Per Cederqvist <ceder@signum.se> Pete
  4274. Clark <pclark@is.com>
  4275. all of whom have sent me copies of their tutorials and local CVS
  4276. documentation.
  4277. Additional contributors, who have sent me ideas, text, corrections and
  4278. support include (in alphabetical order):
  4279. Per Abrahamsen <amanda@iesd.auc.dk> Donald Amby
  4280. <amby@mixcom.mixcom.com> Mark D Baushke <mdb@cisco.com> Jim Blandy
  4281. <jimb@cyclic.com> Tom Cunningham <tomc@bouwsma,sps.mot.com> Graydon
  4282. Dodson <grdodson@lexmark.com> Joe Drumgoole
  4283. <joed@splatter.demon.co.uk> Don Dwiggins <dwig@markv.com> Bryant
  4284. Eastham <bryant@ced.utah.edu> Dan Franklin <dan@diamond.bbn.com>
  4285. Michael Ganzberger <ganzbergermd@ES.net> Steve Harris
  4286. <vsh%etnibsd@uunet.uu.net> Erik van Linstee
  4287. <linstee@dutecaj.et.tudelft.nl> Jeffrey M Loomis <jml@world.std.com>
  4288. Barry Margolin <barmar@near.net> Mark K. Mellis <mkm@ncd.com> Chris
  4289. Moore <Chris.Moore@src.bae.co.uk> Gary Oberbrunner <garyo@avs.com>
  4290. Steve Turner <stevet@carrier.sps.mot.com> Dave Wolfe
  4291. <dwolfe@pffft.sps.mot.com> Dale Woolridge <dwoolridge@cid.aes.doe.ca>
  4292. Please send corrections. If I forgot you, remind me and I'll add your
  4293. name to the list.
  4294. Last modified: _6/13/1997_
  4295. Category: /Past__Future_/Development/
  4296. " + Development"
  4297. 1. Where do I send bug reports?
  4298. First make sure it is a bug. Talk to your friends, coworkers and
  4299. anyone you know who uses CVS. Search this FAQ for related issues. Then
  4300. test it carefully. Try out variations to narrow down the problem. Make
  4301. sure it is repeatable. Look for workarounds so you can report them.
  4302. If you are still sure it's a bug and you tried to fix it, skip to the
  4303. next question. Otherwise, send a message to the info-cvs mailing list
  4304. containing one of the following:
  4305. If you have a good repeatable case and you think you know what is
  4306. going on, then describe the problem in detail. Include a workaround if
  4307. you have one.
  4308. If you have no idea what is going on, go ahead and send a question
  4309. to the info-cvs mailing list. Include any information you have
  4310. describing the symptoms.
  4311. Last modified: _6/13/1997_
  4312. 2. Where do I send fixes and patches?
  4313. First make sure the "fix" does something useful. Have someone review
  4314. your fix. Spend a bit of one person's time in a detailed analysis of
  4315. your vast idea before displaying a half-vast idea to hundreds of
  4316. people.
  4317. If you tried to fix it and the patch is small, include the patch in
  4318. your message. Make sure the patch is based on the latest released
  4319. version of CVS.
  4320. If you tried to fix it and the patch is large, you should think about
  4321. why it is so large. Did you add a generally useful feature, or did it
  4322. grow out of hand?
  4323. If you still believe it is solid, produce a patch file using the CVS
  4324. commands "patch" or "diff -c". [[You *are* keeping CVS under CVS,
  4325. right?]] The patch should be based on the latest released version of
  4326. CVS. Then use the "cvsbug" program (provided with the CVS sources) to
  4327. send it to the CVS maintainers. A self-contained patch that provides a
  4328. single useful feature or correction might show up independently in the
  4329. patches directory of the FTP archive.
  4330. If careful testing reveals an RCS bug rather than a CVS bug, you can
  4331. send bug reports to: rcs-bugs@cs.purdue.edu
  4332. Last modified: _6/13/1997_
  4333. 3. Where do I send ideas for future development?
  4334. If you have a bright idea, discuss it on the info-cvs mailing list. If
  4335. you have the time to implement something you can test, send the diffs
  4336. along too as described above.
  4337. Last modified: _6/13/1997_
  4338. 4. What plans are there for new features?
  4339. A "rename" or "per-directory" database has been bandied about on
  4340. the net for years. Many of the goals of the rename database have
  4341. been achieved by the so-called "death support" in recent versions of
  4342. CVS (such as 1.9). For more information on what may remain to be
  4343. done, see item #189 in the TODO file of a development version of CVS.
  4344. CVS version 1.5 supports remote repository access, but Paul
  4345. Kunz has produced another version
  4346. (rCVS) that also runs remotely. Note that as far as I know there
  4347. are no advantages to rCVS over the remote CVS in CVS 1.5 and later,
  4348. and the rCVS user community has migrated to remote CVS.
  4349. rCVS is *not* a multisite CVS (see item #186 in TODO for more on
  4350. multisite). For more on rCVS, see
  4351. ftp://ftp.slac.stanford.edu/software/rcvs
  4352. kingdon@cyclic.com
  4353. Last modified: _9/6/1997_
  4354. 5. I have some time and I'd like to help. What can I do for you?
  4355. You can review this document, correct errors and fill in any of
  4356. the incomplete sections.
  4357. You can write scripts or CVS add-ons and make them available by
  4358. web/FTP/etc.
  4359. You could work on the regression test suite (src/sanity.sh in the
  4360. CVS source distribution).
  4361. You can write specs for new features, fix bugs, review the
  4362. documentation or . . .
  4363. For more information, see the files HACKING and DEVEL-CVS in the
  4364. CVS source distribution or
  4365. http://www.cyclic.com/cyclic-pages/cvsdev.html
  4366. kingdon@cyclic.com
  4367. Last modified: _9/6/1997_
  4368. Category: /Past__Future_/Professional_Support/
  4369. " + Professional Support"
  4370. 1. Doesn't Cygnus support CVS?
  4371. Cygnus is a company that supports free software such as the GCC
  4372. compiler. They have never sold support for CVS, however. They
  4373. do use CVS internally and have contributed much code to CVS over
  4374. the years (for which CVS users should be grateful).
  4375. kingdon@cyclic.com
  4376. Last modified: _9/6/1997_
  4377. 2. What is Cyclic Software doing with CVS?
  4378. Cyclic Software exists to provide support for CVS. For details such
  4379. as prices and what this covers, see http://www.cyclic.com or ask
  4380. info@cyclic.com.
  4381. kingdon@cyclic.com
  4382. Last modified: _9/6/1997_
  4383. Category: /User_Tasks_/
  4384. " User Tasks "
  4385. Category: /User_Tasks_/Common_User_Tasks/
  4386. " + Common User Tasks"
  4387. 1. What is the absolute minimum I have to do to edit a file?
  4388. Tell your Repository Administrator to create a module covering the
  4389. directory or files you care about. You will be told that your module
  4390. name is <module>. Then type:
  4391. cvs checkout <module>
  4392. cd <module>
  4393. emacs <file> # Isn't Emacs a synonym for edit?
  4394. cvs commit <file>
  4395. If you don't use modules (in my opinion, a mistake), you can check out
  4396. a directory by substituting its relative path within the Repository
  4397. for <module> in the example above.
  4398. To work on a single file, you'll have to change "cd <module>" to "cd
  4399. `dirname <module>`".
  4400. Last modified: _6/13/1997_
  4401. 2. If I edit multiple files, must I type "commit" for each one?
  4402. No. You can commit a list of files and directories, including relative
  4403. paths into multiple directories. You can also commit every modified
  4404. file in the current directory or in all directories and subdirectories
  4405. from your current directory downward. See 3D.2.
  4406. Last modified: _6/13/1997_
  4407. 3. How do I get rid of the <module> directory that "checkout" created?
  4408. Change your directory to be the same as when you executed the
  4409. "checkout" command that created <module>.
  4410. If you want to get rid of the CVS control information, but leave the
  4411. files and directories, type:
  4412. cvs release <module>
  4413. If you want to obliterate the entire directory, type:
  4414. cvs release -d <module>
  4415. ("release -d" searches through the output of "cvs -n update" and
  4416. refuses to continue if the "update" command finds any modified files
  4417. or non-ignored foreign files. Foreign directories too.)
  4418. If you don't care about keeping "history", or checking for modified
  4419. and foreign files, you can just remove the whole directory. That's "rm
  4420. -rf <module>" under Unix.
  4421. Last modified: _6/13/1997_
  4422. 4. How do I find out what has changed since my last update?
  4423. There are many ways to answer this.
  4424. To find out what you've changed in your current working directory
  4425. since your last checkout, update or commit, type:
  4426. cvs diff
  4427. To find out what other people have added (to your branch) since you
  4428. last checked out or updated, type:
  4429. cvs diff -r BASE -r HEAD
  4430. To look at a revision history containing the comments for all changes,
  4431. you can use the "log" command.
  4432. You can also use "history" to trace a wide variety of events.
  4433. Last modified: _6/13/1997_
  4434. 5. I just created a new file. How do I add it to the Repository?
  4435. The "update" command will mark files CVS doesn't know about in your
  4436. working directory with a '?' indicator.
  4437. ? <file>
  4438. To add <file> to the Repository, type:
  4439. cvs add <file>
  4440. cvs commit <file>
  4441. See 3A.[2-5] and 4C.8 for branch and merge considerations.
  4442. Last modified: _6/13/1997_
  4443. 6. How do I merge changes made by others into my working directory?
  4444. If you are asking about other branches, see Section 4C on "Branching".
  4445. You will have to use the "update -j" command.
  4446. Retrieving changes made to the Repository on the *same* branch you are
  4447. working on is the main purpose of the "update" command. The "update"
  4448. command tries to merge work committed to the Repository by others
  4449. since you last executed "checkout", "update" or "commit" into your
  4450. working files.
  4451. For a single file, there are six possible results when you type the
  4452. "update" command:
  4453. If the file is lying in your working directory, but is not under
  4454. CVS, it will do nothing but print:
  4455. ? <file>
  4456. If neither you nor anyone else has committed changes to <file>,
  4457. since your last "checkout", "update" or "commit", "update" will print
  4458. nothing and do nothing.
  4459. If you have made no changes to a working file, but you or others
  4460. have committed changes to the Repository since your last "checkout",
  4461. "update" or "commit" of this working file, CVS will remove your
  4462. working file and replace it with a copy of the latest revision of that
  4463. file in the Repository. It will print:
  4464. U <file>
  4465. You might want to examine the changes (using the CVS "diff" command)
  4466. to see if they mesh with your own in related files.
  4467. If you have made changes to a working file, but no one has changed
  4468. your BASE revision (the revision you retrieved from the Repository in
  4469. your last "checkout", "update" or "commit"), "update" will print:
  4470. M <file>
  4471. Nothing changes. You were told that you have a modified file in your
  4472. directory.
  4473. If you have made changes to your working file and you or others have
  4474. committed changes to the Repository, but in different sections of the
  4475. file, CVS will merge the changes stored in the Repository since your
  4476. last "checkout", "update" or "commit" into your working file. "update"
  4477. will print:
  4478. RCS file: /Repository/module/<file> retrieving revision 1.X retrieving
  4479. revision 1.Y Merging differences between 1.X and 1.Y into <file> M
  4480. <file>
  4481. If you execute "diff" before and after this step, you should see the
  4482. same output, since both the base file and your working file changed in
  4483. parallel. This is one of the few times the otherwise nonsensical
  4484. phrase "same difference" means something.
  4485. If both you and those who committed files (since your last checkout,
  4486. update or commit) have made changes to the same section of a file, CVS
  4487. will merge the changes into your file as in #5 above, but it will
  4488. leave conflict indicators in the file. "update" will print:
  4489. RCS file: /Repository/module/<file> retrieving revision 1.X retrieving
  4490. revision 1.Y Merging differences between 1.X and 1.Y into <file>
  4491. rcsmerge warning: overlaps during merge
  4492. cvs update: conflicts found in <file>
  4493. C <file>
  4494. This is a "conflict". The file will contain markers surrounding the
  4495. overlapping text. The 'C' conflict indicator is sticky -- subsequent
  4496. "update" commands will continue to show a 'C' until you edit the file.
  4497. You must examine the overlaps with care and resolve the problem by
  4498. analyzing how to retain the features of both changes. See 2D.7 and
  4499. 3P.6 for more details on conflict resolution.
  4500. Last modified: _6/13/1997_
  4501. 7. How do I label a set of revisions so I can retrieve them later?
  4502. To "tag" the BASE revisions (the ones you last checked out, updated,
  4503. or committed) you should "cd" to the head of the working directory you
  4504. want to tag and type:
  4505. cvs tag <tag>
  4506. It recursively walks through your working directory tagging the BASE
  4507. revisions of all files.
  4508. To "tag" the latest revision on the Main branch in the Repository, you
  4509. can use the following from anywhere: (No "cd" is required -- it works
  4510. directly on the Repository.)
  4511. cvs rtag <tag> <module>
  4512. Last modified: _6/13/1997_
  4513. 8. How do I checkout an old release of a module, directory or file?
  4514. Module names and directories are simply ways to name sets of files.
  4515. Once the names are determined, there are 6 ways to specify which
  4516. revision of a particular file to check out:
  4517. By tag or symbolic name, via the "-r <tag>" option.
  4518. By date, via the "-D <date>" option.
  4519. By branch tag (a type of tag with a magic format), via the "-r
  4520. <branch_tag>" option.
  4521. By date within a branch, via the "-r <branch_tag>:<date>" option.
  4522. By an explicit branch revision number ("-r <rev>"), which refers to
  4523. the latest revision on the branch. This isn't really an "old"
  4524. revision, from the branch's perspective, but from the user's
  4525. perspective the whole branch might have been abandoned in the past.
  4526. An explicit revision number: "-r <rev>" Though this works, it is
  4527. almost useless for more than one file.
  4528. You type:
  4529. cvs checkout <option-specified-above> <module>
  4530. cd <module>
  4531. Last modified: _6/13/1997_
  4532. 9. What do I have to remember to do periodically?
  4533. You should execute "cvs -n update" fairly often to keep track of what
  4534. you and others have changed. It won't change anything -- it will just
  4535. give you a report.
  4536. Unless you are purposely delaying the inclusion of others' work, you
  4537. should execute "update" once in a while and resolve the conflicts. It
  4538. is not good to get too far out of sync with the rest of the developers
  4539. working on your branch.
  4540. It is assumed that your system administrators have arranged for editor
  4541. backup and Unix temp files (#* and .#*) to be deleted after a few
  4542. weeks. But you might want to look around for anything else that is
  4543. ignored or hidden. Try "cvs -n update -I !" to see all the ignored
  4544. files.
  4545. If you are the Repository Administrator, see 4B.16 on Administrator
  4546. responsibilities.
  4547. Last modified: _6/13/1997_
  4548. Category: /User_Tasks_/General_Questions/
  4549. " + General Questions"
  4550. 1. How do I see what CVS is trying to do?
  4551. The '-t' option on the main "cvs" command will display every external
  4552. command (mostly RCS commands and file deletions) it executes. When
  4553. combined with the '-n' option, which prevents the execution of any
  4554. command that might modify a file, you can see what it will do before
  4555. you let it fly. The '-t' option will *not* display every internal
  4556. action, only calls to external programs.
  4557. To see a harmless example, try typing:
  4558. cvs -nt update
  4559. Some systems offer a "trace" or "truss" command that will display all
  4560. system calls as they happen. This is a *very* low-level interface that
  4561. does not normally follow the execution of external commands, but it
  4562. can be useful.
  4563. The most complete answer is to read the source, compile it with the
  4564. '-g' option and step through it under a debugger.
  4565. Last modified: _6/13/1997_
  4566. 2. If I work with multiple modules, should I check them all out and commit
  4567. them occasionally? Is it OK to leave modules checked out?
  4568. The simple answers are "Yes."
  4569. There is no reason to remove working directories, other than to save
  4570. disk space. As long as you have committed the files you choose to make
  4571. public, your working directory is just like any other directory.
  4572. CVS doesn't care whether you leave modules checked out or not. The
  4573. advantage of leaving them checked out is that you can quickly visit
  4574. them to make and commit changes.
  4575. Last modified: _6/13/1997_
  4576. 3. What is a "sticky" tag? What makes it sticky? How do I loosen it?
  4577. When you execute "update -r <tag>", CVS remembers the <tag>. It has
  4578. become "sticky" in the sense that until you change it or remove it,
  4579. the tag is remembered and used in references to the file as if you had
  4580. typed "-r <tag>" on the command line.
  4581. It is most useful for a <branch_tag>, which is a sticky tag indicating
  4582. what branch you are working on.
  4583. A revision number ("-r <rev-number>") or date ("-D <date>") can also
  4584. become sticky when they are specified on the command line.
  4585. A sticky tag, revision or date remains until you specify another tag,
  4586. revision or date the same way. The "update -A" command moves back to
  4587. the Main branch, which has the side-effect of clearing all sticky
  4588. items on the updated files.
  4589. The "checkout" command creates sticky tags, revisions and dates the
  4590. same way "update" does.
  4591. Also, the '-k' option records a "sticky" keyword option that is used
  4592. in further "updates until "update -A" is specified.
  4593. Last modified: _6/13/1997_
  4594. 4. How do I get an old revision without updating the "sticky tag"?
  4595. Use the '-p' option to "pipe" data to standard output. The command
  4596. "update -p -r <tag/rev>" sends the selected revision to your standard
  4597. output (usually the terminal, unless redirected). The '-p' affects no
  4598. disk files, leaving a "sticky tag" unaltered and avoiding all other
  4599. side-effects of a normal "update".
  4600. If you want to save the result, you can redirect "stdout" to a file
  4601. using your shell's redirection capability. In most shells the
  4602. following command works:
  4603. cvs update -p -r <tag/rev> filename > diskfile
  4604. Last modified: _6/13/1997_
  4605. 5. What operations disregard sticky tags?
  4606. The functions that routinely disregard sticky tags are:
  4607. Those that work directly on the Repository or its administrative
  4608. files:
  4609. admin rtag log status remove history
  4610. Those that take Tags or revisions as arguments and ignore everything
  4611. else: (They also never *set* a sticky tag.)
  4612. rdiff import export
  4613. The "release" command itself ignores sticky tags, but it calls "cvs
  4614. -n update" (which *does* pay attention to a sticky tag) to figure out
  4615. what inconsistencies exist in the working directory. If no
  4616. discrepancies exist between the files you originally checked out
  4617. (possibly marked by a sticky tag) and what is there now, "release -d"
  4618. will delete them all.
  4619. The "tag" command works on the revision lying in the working
  4620. directory however it got there. That the revision lying there might
  4621. happen to have a sticky tag attached to it is not the "tag" command's
  4622. concern.
  4623. The main function that *does* read and write sticky tags is the
  4624. "update" command. You can avoid referring to or changing the sticky
  4625. tag by using the '-p' option, which sends files to your terminal,
  4626. touching nothing else.
  4627. The "checkout" command sets sticky tags when checking out a new module
  4628. and it acts like "update" when checking out a module into an existing
  4629. directory.
  4630. The "diff" and "commit" commands use the sticky tags, unless
  4631. overridden on the command line. They do not set sticky tags. Note that
  4632. you can only "commit" to a file checked out with a sticky tag, if the
  4633. tag identifies a branch.
  4634. There are really two types of sticky tags, one attached to individual
  4635. files (in the ./CVS/Entries file) and one attached to each directory
  4636. (in the ./CVS/Tag file). They can differ.
  4637. The "add" command registers the desire to add a new file. If the
  4638. "directory tag" (./CVS/Tag) file exists at the time of the "add", the
  4639. value stored in ./CVS/Tag becomes the "sticky tag" on the new file.
  4640. The file doesn't exist in the Repository until you "commit" it, but
  4641. the ./CVS/Entries file holds the sticky tag name from the time of the
  4642. "add" forward.
  4643. Last modified: _6/13/1997_
  4644. 6. Is there a way to avoid reverting my Emacs buffer after committing a
  4645. file? Is there a "cvs-mode" for Emacs?
  4646. See Section 4F.1
  4647. Last modified: _6/13/1997_
  4648. 7. How does conflict resolution work? What *really* happens if two of us
  4649. change the same file?
  4650. While editing files, there is no conflict. You are working on separate
  4651. copies of the file stored in the virtual "branch" represented by your
  4652. working directories. After one of you commits a file, the other may
  4653. not commit the same file until "update" has merged the earlier
  4654. committed changes into the later working file.
  4655. For example, say you both check out rev 1.2 of <file> and make change
  4656. to your working files. Your coworker commits revision 1.3. When you
  4657. try to commit your file, CVS says:
  4658. cvs commit: Up-to-date check failed for `<file>'
  4659. You must merge your coworker's changes into your working file by
  4660. typing:
  4661. cvs update <file>
  4662. which will produce the output described in 2B.6.
  4663. If a conflict occurs, the filename will be shown with a status of 'C'.
  4664. After you resolve any overlaps caused by the merging process, you may
  4665. then commit the file. See 3P.6 for info on "sticky conflicts".
  4666. Even if you get a simple 'M', you should examine the differences
  4667. before committing the file. A smooth, error-free text merge is still
  4668. no indication that the file is in proper shape. Compile and test it at
  4669. least.
  4670. The answer to two obvious questions is "Yes".
  4671. Yes, the first one who commits avoids the merge. Later developers have
  4672. to merge the earlier changes into their working files before
  4673. committing the merged result. Depending on how difficult the merge is
  4674. and how important the contending projects are, the order of commits
  4675. and updates might have to be carefully staged.
  4676. And yes, between the time you execute "update" and "commit" (while you
  4677. are fixing conflicts and testing the results) someone else may commit
  4678. another revision of <file>. You will have to execute "update" again to
  4679. merge the new work before committing. Most organizations don't have
  4680. this problem. If you do, you might consider splitting the file. Or
  4681. hiring a manager.
  4682. Last modified: _6/13/1997_
  4683. 8. How can I tell who has a module checked out?
  4684. If you "checkout" module names (not relative pathnames) and you use
  4685. the release command, the "history" command will display active
  4686. checkouts, who has them and where they were checked out. It is
  4687. advisory only; it can be circumvented by using the '-l' option on the
  4688. main "cvs" command.
  4689. Last modified: _6/13/1997_
  4690. 9. Where did the .#<file>.1.3 file in my working directory come from?
  4691. It was created during an "update" when CVS merged changes from the
  4692. Repository into your modified working file.
  4693. It serves the same purpose as any "backup" file: saving your bacon
  4694. often enough to be worth retaining. It is invaluable in recovering
  4695. when things go wrong.
  4696. Say Developers A (you) and B check out rev 1.3 of file <file>. You
  4697. both make changes -- different changes. B commits first, so <file>,v
  4698. in the Repository contains revisions up through 1.4.
  4699. At this point, there are 5 (yes, five) versions of the file of
  4700. interest to you:
  4701. Revision 1.3 (What you originally checked out.)
  4702. Revision 1.4 (What you need from developer B.)
  4703. Your old working file. (Before the update.)
  4704. Your new working file. (After the merge caused by "update".)
  4705. Revision 1.5 (Which you will commit shortly.)
  4706. In the case where your working file was not modified, #1 and #3 will
  4707. be the same, as will #2 and #4. In this degenerate case, there is no
  4708. need to create #5. The following assumes that your working file was
  4709. modified.
  4710. If the merge executed by the "update" caused no overlaps, and you
  4711. commit the file immediately, #4 and #5 will be the same. But you can
  4712. make arbitrary changes before committing, so the difference between #4
  4713. and #5 might be more than just the correction of overlaps. In general,
  4714. though, you don't need #4 after a commit.
  4715. But #3 (which is the one saved as ".#<file>.1.3") holds all of your
  4716. work, independent of B's work. It could represent a major effort that
  4717. you couldn't afford to lose. If you don't save it somewhere, the merge
  4718. makes #3 *disappear* under a potential blizzard of conflicts caused by
  4719. overlapping changes.
  4720. I have been saved a few times, and others I support have been saved
  4721. hundreds of times, by the ability to "diff <original file> <original
  4722. file with only my work added>", which can be done in the example above
  4723. by the Unix shell command:
  4724. cvs update -p -r 1.3 <file> | diff - .#<file>.1.3
  4725. The assumption is that the ".#" files will be useful far beyond the
  4726. "commit" point, but not forever. You are expected to run the "normal"
  4727. Unix cleanup script from "cron", which removes "#*" and ".#*" files
  4728. older than a some period chosen by your sysadmin, usually ranging from
  4729. 7 to 30 days.
  4730. A question was raised about the need for #3 after #5 has been
  4731. committed, under the assumption that you won't commit files until
  4732. everything is exactly as you like them.
  4733. This assumes perfect humans, which violates one of the Cardinal rules
  4734. of Software Engineering: Never assume any form of discipline on the
  4735. part of the users of software. If restrictions are not bound into the
  4736. software, then you, the toolsmith, have to arrange a recovery path.
  4737. In other words, I've seen every possible variety of screwup you can
  4738. imagine in #5. There is no way to make assumptions about what "should"
  4739. happen. I've seen #5 filled with zeros because of NFS failures, I've
  4740. seen emacs core dumps that leave #5 in an unreasonable state, I've
  4741. seen a foolish developer uppercase the whole file (with his "undo"
  4742. size set low so he couldn't undo it) and decide that it would be less
  4743. work to play with the uppercased file than to blow it away and start
  4744. over. I've even seen committed files with conflict markers still in
  4745. them, a sure sign of carelessness.
  4746. There are all sorts of scenarios where having #3 is incredibly useful.
  4747. You can move it back into place and try again.
  4748. Last modified: _6/13/1997_
  4749. 10. What is this "ignore" business? What is it ignoring?
  4750. The "update" and "import" commands use collections of Unix wildcards
  4751. to skip over files and directories matching any of those patterns.
  4752. You may add to the built-in ignore list by adding lines of
  4753. whitespace-separated wildcards to the following places: (They are read
  4754. in this order.)
  4755. In a file named "cvsignore" in $CVSROOT/CVSROOT.
  4756. A Repository Administrator uses this to add site-specific files and
  4757. patterns to the built-in ignore list.
  4758. In a file named ".cvsignore" in your home directory.
  4759. For user-specific files. For example, if you use "__" as your default
  4760. junk file prefix, you can put "__*" in your .cvsignore file.
  4761. People who play around exclusively in directory trees where the
  4762. Makefiles are generated by "imake" or "configure" might want to put
  4763. "Makefile" in their ignore list, since they are all generated and
  4764. usually don't end up in the Repository.
  4765. In the CVSIGNORE environment variable.
  4766. For session-specific files.
  4767. Via the '-I' option on "import" or "update" commands.
  4768. For this-command-only files.
  4769. In a file named ".cvsignore" within each directory.
  4770. The contents of a ".cvsignore" file in each directory is temporarily
  4771. added to the ignore list. This way you can ignore files that are
  4772. peculiar to that directory, such as executables and other generated
  4773. files without known wildcard patterns.
  4774. In any of the places listed above, a single '!' character nulls out
  4775. the ignore list. A Repository administrator can use this to override,
  4776. rather than enhance, the built-in ignore list. A user can choose to
  4777. override the system-wide ignore list. For example, if you place "! *.o
  4778. *.a" in your .cvsignore file, only *.o *.a files, plus any files a
  4779. local-directory .cvsignore file, are ignored.
  4780. A variant of the ignore-file scheme is used internally during
  4781. checkout. "Module names" found in the modules file (or on the
  4782. "checkout" command line) that begin with a '!' are ignored during
  4783. checkout. This is useful to permanently ignore (if the '!' path is in
  4784. the modules file) or temporarily ignore (if the '!' path is on the
  4785. command line) a sub-directory within a Repository hierarchy. For
  4786. example:
  4787. cvs checkout !gnu/emacs/tests gnu/emacs
  4788. would checkout the module (or relative path within $CVSROOT) named
  4789. "gnu/emacs", but ignore the "tests" directory within it.
  4790. Last modified: _6/13/1997_
  4791. 11. Is there a way to set user-specific configuration options?
  4792. User-specific configuration is available through use of a ".cvsrc"
  4793. file in your home directory.
  4794. CVS searches the first column of your ~/.cvsrc file for the cvs
  4795. command name you invoked. If the command is found, the rest of the
  4796. line is treated like a set of command line options, stuffed into the
  4797. command line before the arguments you actually typed.
  4798. For example, if you always want to see context diffs and you never
  4799. want to have to delete a file before you run "cvs remove", then you
  4800. should create a .cvsrc file containing the following:
  4801. diff -c
  4802. remove -f
  4803. which will add the given options to every invocation of the given
  4804. commands.
  4805. [[The rest of this will be removed someday, when CVS changes.]]
  4806. I would like to stop here with a comment that the command name to use
  4807. is the full, canonical one. But the command that the cvsrc support
  4808. uses is the string you typed on the command line, not the proper
  4809. command. So to get the full effect of the above example, you should
  4810. also add all the alternate command names:
  4811. di -c
  4812. dif -c
  4813. rm -f
  4814. delete -f
  4815. There are two other limitations that will probably be fixed when CVS
  4816. sprouts long option names:
  4817. It only affects options made available on the command line.
  4818. There is a limited number of short options. With long option names,
  4819. there is no problem. You can have as many long options as you like,
  4820. affecting anything that looks malleable.
  4821. The existing command line options do not come in on/off pairs, so
  4822. there is no easy way to override your ~/.cvsrc configuration for a
  4823. single invocation of a command.
  4824. Choosing a good set of long option pairs would fix this.
  4825. Last modified: _6/13/1997_
  4826. 12. Is it safe to interrupt CVS using Control-C?
  4827. It depends on what you mean by "safe". ("Ah," said Arthur, "this is
  4828. obviously some strange usage of the word *safe* that I wasn't
  4829. previously aware of." -- Hitchhiker's Guide to the Galaxy)
  4830. You won't hurt the underlying RCS files and if you are executing a
  4831. command that only *reads* data, you will have no cleanup to do.
  4832. But you may have to hit Control-C repeatedly to stop it. CVS uses the
  4833. Unix "system" routine which blocks signals in the CVS parent process.
  4834. A single Control-C during "system" will only halt the child process,
  4835. usually some form of RCS command.
  4836. If you don't hit another Control-C while the CVS process has control,
  4837. it is likely to continue onto the next task assuming that the earlier
  4838. one did its job. It is not enough to hit two Control-C's. You might
  4839. simply kill two child processes and not interrupt CVS at all.
  4840. Depending on the speed of your processor, your terminal and your
  4841. fingers, you might have to hit dozens of Control-C's to stop the damn
  4842. thing.
  4843. Executing a CVS command, such as "commit" or "tag" that writes to the
  4844. files is a different matter.
  4845. Since CVS is not a full-fledged database, with what database people
  4846. call "commit points", merely stopping the process will not back out
  4847. the "transaction" and place you back in the starting blocks. CVS has
  4848. no concept of an "atomic" transaction or of "backtracking", which
  4849. means that a command can be half-executed.
  4850. Hitting Control-C will usually leave lock files that you have to go
  4851. clean up in the Repository.
  4852. Example1:
  4853. If you interrupt a multi-file "commit" in the middle of
  4854. an RCS checkin, RCS will leave the file either fully
  4855. checked-in or in its original state. But CVS might have
  4856. been half-way through the list of files to commit. The
  4857. directory or module will be inconsistent.
  4858. To recover, you must remove the lock files, then decide
  4859. whether you want to back out or finish the job.
  4860. To back out, you'll have to apply the "admin -o"
  4861. command, very carefully, to remove the newly committed
  4862. revisions. This is usually a bad idea, but is
  4863. occasionally necessary.
  4864. To finish, you can simply retype the same commit command.
  4865. CVS will figure out what files are still modified and
  4866. commit them. It helps that RCS doesn't leave a file in an
  4867. intermediate state.
  4868. Example2:
  4869. If you interrupt a multi-file "tag" command, you have a
  4870. problem similar, but not equivalent, to interrupting a
  4871. "commit". The RCS file will still be consistent, but
  4872. unlike "commit", which only *adds* to the RCS file, "tag"
  4873. can *move* a tag and it doesn't keep a history of what
  4874. revision a tag used to be attached to.
  4875. Normally, you have little choice but to re-execute the
  4876. command and allow it to tag everything consistently.
  4877. You might be able to recover by carefully re-applying the
  4878. tags via the "cvs admin -N" command, but you'll still have
  4879. to dig up from outside sources the information you use to
  4880. determine what tag was on what revision in what file.
  4881. the Repository, or by using the equivalent: "cvs admin".
  4882. Halting a new "checkout" should cause no harm. If you don't want it,
  4883. "release" (or rm -rf) it. If you do want it, re-execute the command. A
  4884. repeated "checkout" from above a directory acts like a repeated
  4885. "update -d" within it.
  4886. Halting "update" half-way will give you an unpredictable collection of
  4887. files and revisions. To continue, you can rerun the update and it
  4888. should move you forward into in a known state. To back out, you'll
  4889. have to examine the output from the first "update" command, take a
  4890. look at each file that was modified and reconstruct the previous state
  4891. by editing the ./CVS/Entries file and by using "cvs admin". Good Luck.
  4892. Last modified: _6/13/1997_
  4893. 13. How do I turn off the "admin" command?
  4894. In the current revision, you'd have to edit the source code.
  4895. Last modified: _6/13/1997_
  4896. 14. How do I turn off the ability to disable history via "cvs -l"?
  4897. In the current revision, you'd have to edit the source code.
  4898. Last modified: _6/13/1997_
  4899. 15. How do I keep certain people from accessing certain directories?
  4900. If you don't try to run CVS set[ug]id, you can use Unix groups and
  4901. permissions to limit access to the Repository.
  4902. If you only want to limit "commit" commands, you can write a program
  4903. to put in the "commitinfo" file. In the "contrib" directory, there are
  4904. a few scripts that might help you out.
  4905. Last modified: _6/13/1997_
  4906. Category: /User_Tasks_/Getting_Started/
  4907. " + Getting Started"
  4908. 1. What is the first thing I have to know?
  4909. Your organization has most likely assigned one or more persons to
  4910. understand, baby-sit and administer the CVS programs and the data
  4911. Repository. I call these persons Repository Administrators. They
  4912. should have set up a Repository and "imported" files into it.
  4913. If you don't believe anyone has this responsibility, or you are just
  4914. testing CVS, then *you* are the Repository Administrator.
  4915. If you are a normal user of CVS ask your Repository Administrator what
  4916. module you should check out.
  4917. Then you can work.
  4918. If you *are* the Repository Administrator, you will want to read
  4919. everything you can get your hands on, including this FAQ. Source
  4920. control issues can be difficult, especially when you get to branches
  4921. and release planning. Expect to feel stupid for a few days/weeks.
  4922. No tool in the universe avoids the need for intelligent organization.
  4923. In other words, there are all sorts of related issues you will
  4924. probably have to learn. Don't expect to dive in without any
  4925. preparation, stuff your 300 Megabytes of sources into CVS and expect
  4926. to start working. If you don't prepare first, you will probably spend
  4927. a few sleepless nights.
  4928. Last modified: _6/13/1997_
  4929. 2. Where do I work?
  4930. Wherever you have disk space. That's one of the advantages of CVS: you
  4931. use the "checkout" command to copy files from the Repository to your
  4932. working directory, which can be anywhere you have the space.
  4933. Your local group might have conventions for where to work. Ask your
  4934. peers.
  4935. Last modified: _6/13/1997_
  4936. 3. What does CVS use from my environment?
  4937. You must set two environment variables. Some shells share these
  4938. variables with local shell variables using a different syntax. You'll
  4939. have to learn how your shell handles them.
  4940. Variable Value (or action)
  4941. --------- ---------------------
  4942. CVSROOT Absolute pathname of the head of your Repository.
  4943. PATH Normally set to a list of ':'-separated directory
  4944. pathnames searched to find executables. You must
  4945. make sure "cvs" is in one of the directories.
  4946. If your CVS was built with the RCSBIN directory set
  4947. to null (""), and you don't set the RCSBIN
  4948. variable mentioned below, then the RCS commands
  4949. also must be somewhere in your PATH.
  4950. Optional variables: (Used if set, but ignored otherwise.)
  4951. Variable Value (or action)
  4952. --------- ---------------------
  4953. CVSEDITOR The name of your favorite fast-start editor
  4954. program. You'll be kicked into your editor to
  4955. supply revision comments if you don't specify them
  4956. via -m "Log message" on the command line.
  4957. EDITOR Used if CVSEDITOR doesn't exist. If EDITOR
  4958. doesn't exist, CVS uses a configured constant,
  4959. usually, "vi".
  4960. CVSREAD Sets files to read-only on "checkout".
  4961. RCSBIN Changes where CVS finds the RCS commands.
  4962. CVSIGNORE Adds to the ignore list. See Section 2D.
  4963. Other variables used by CVS that are normally set upon login:
  4964. Variable Value (or action)
  4965. --------- ---------------------
  4966. LOGNAME Used to find the real user name.
  4967. USER Used to find the real user name if no LOGNAME.
  4968. HOME Used to determine your home directory, if set.
  4969. Otherwise LOGNAME/USER/getuid() are used to find
  4970. your home directory from the passwd file.
  4971. TMPDIR Used during import. It might also be used if your
  4972. platform's version of mktemp(3) is unusual, or
  4973. you have changed the source to use tmpnam(3).
  4974. Last modified: _6/13/1997_
  4975. 4. OK, I've been told that CVS is set up, my module is named "ralph" and I
  4976. have to start editing. What do I type?
  4977. cd <where you have some space to work>
  4978. cvs checkout ralph
  4979. cd ralph
  4980. And hack away.
  4981. Last modified: _6/13/1997_
  4982. 5. I have been using RCS for a while. Can I convert to CVS without losing
  4983. my revision history? How about converting from SCCS?
  4984. If you are asking such questions, you are not a mere user of CVS, but
  4985. one of its Administrators! You should take a look at Section 4A,
  4986. "Installing CVS" and Section 4B, "Setting up and Managing the
  4987. Repository".
  4988. Last modified: _6/13/1997_
  4989. Category: /User_Tasks_/Less_Common_User_Tas/
  4990. " + Less Common User Tasks"
  4991. 1. Can I create non-CVS sub-directories in my working directory?
  4992. Yes. Unless the directory exists in the Repository, "update" will skip
  4993. over them and print a '?' the way it does for files you forgot to add.
  4994. You can avoid seeing the '?' by adding the name of the foreign
  4995. directory to the ./.cvsignore file, just ask you can do with files.
  4996. If you explicitly mention a foreign directory on the "update" command
  4997. line, it will traverse the directory and waste a bit of time, but if
  4998. any directory or sub-directory lacks the ./CVS administrative
  4999. directory, CVS will print an error and abort.
  5000. Last modified: _6/13/1997_
  5001. 2. How do I add new sub-directories to the Repository?
  5002. The "add" command will work on directories. You type:
  5003. mkdir <dir>
  5004. cvs add <dir>
  5005. It will respond:
  5006. Directory /Repos/<dir> added to the repository
  5007. and will create both a matching directory in the Repository and a
  5008. ./CVS administrative directory within the local <dir> directory.
  5009. Last modified: _6/13/1997_
  5010. 3. How do I remove a file I don't need?
  5011. (See the questions in Section 4B on removing files from the
  5012. Repository.)
  5013. You type:
  5014. rm <file>
  5015. cvs remove <file>
  5016. CVS registers the file for removal. To complete the removal, you must
  5017. type:
  5018. cvs commit <file>
  5019. CVS moves the file to the Attic associated with your working
  5020. directory. Each directory in the Repository stores its deleted files
  5021. in an Attic sub-directory. A normal "checkout" doesn't look in the
  5022. Attic, but if you specify a tag, a date or a revision, the "checkout"
  5023. (or "update") command will retrieve files from the Attic with that
  5024. tag, date or revision.
  5025. Last modified: _6/13/1997_
  5026. 4. How do I rename a file?
  5027. CVS does not offer a way to rename a file in a way that CVS can track
  5028. later. See Section 4B for more information.
  5029. Here is the best (to some, the only acceptable) way to get the effect
  5030. of renaming, while preserving the change log:
  5031. Copy the RCS (",v") file directly in the Repository.
  5032. cp $CVSROOT/<odir>/<ofile>,v $CVSROOT/<ndir>/<nfile>,v
  5033. By duplicating the file, you will preserve the change history and the
  5034. ability to retrieve earlier revisions of the old file via the "-r
  5035. <tag/rev>" or "-D <date>" options to "checkout" and "update".
  5036. Remove the old file using CVS.
  5037. cd <working-dir>/<odir> rm <ofile>
  5038. cvs remove <ofile>
  5039. cvs commit <ofile>
  5040. This will move the <ofile> to the Attic associated with <odir>.
  5041. Retrieve <nfile> and remove all the Tags from it.
  5042. By stripping off all the old Tags, "checkout -r" and "update -r" won't
  5043. retrieve revisions Tagged before the renaming.
  5044. cd <working-dir>/<ndir>
  5045. cvs update <nfile>
  5046. cvs log <nfile> # Save the list of Tags
  5047. cvs tag -d <tag1> <nfile>
  5048. cvs tag -d <tag2> <nfile>
  5049. . . .
  5050. This technique can be used to rename files within one directory or
  5051. across different directories. You can apply this idea to directories
  5052. too, as long as you apply the above to each file and don't delete the
  5053. old directory.
  5054. Of course, you have to change your build system (e.g. Makefile) in
  5055. your <working-dir> to know about the name change.
  5056. Warning: Stripping the old tags from the copied file will allow "-r
  5057. <tag>" to do the right thing, but you will still have problems with
  5058. "-D <date>" because there is no place to store the "deletion time".
  5059. See 5B.3 for more details.
  5060. Last modified: _6/13/1997_
  5061. 5. How do I make sure that all the files and directories in my working
  5062. directory are really in the Repository?
  5063. A "cvs update", or "cvs -n update" (which won't modify your working
  5064. directory) will display foreign elements, which have no counterpart in
  5065. the Repository, preceded by a '?'. To register foreign directories,
  5066. you can use "cvs add". To register foreign files, you can use "cvs
  5067. add" followed by "cvs commit".
  5068. You could also checkout your module, or the Repository directory
  5069. associated with your working directory, a second time into another
  5070. work area and compare it to your working directory using the (non-CVS)
  5071. "diff -r" command.
  5072. By default many patterns of files are ignored. If you create a file
  5073. named "core" or a file ending in ".o", it is usually ignored. If you
  5074. really want to see all the files that aren't in the Repository, you
  5075. can use a special "ignore" pattern to say "ignore no files". Try
  5076. executing: (You may have to quote or backwhack (i.e. precede by '\')
  5077. the '!' in your shell.)
  5078. cvs -n update -I !
  5079. The above command will display not only the normal modified, update
  5080. and conflict indicators ('M', 'U', and 'C' respectively) on files
  5081. within the Repository, but it will also display each file not in the
  5082. Repository preceded by a '?' character.
  5083. The '-n' option will not allow "update" to alter your working
  5084. directory.
  5085. Last modified: _6/13/1997_
  5086. 6. How do I create a branch?
  5087. Type this in your working directory:
  5088. cvs tag -b <branch_tag>
  5089. and you will create a branch. No files have real branches in them yet,
  5090. but if you move onto the branch by typing:
  5091. cvs update -r <branch_tag>
  5092. and commit a file in the normal way:
  5093. cvs commit <file>
  5094. then a branch will be created in the underlying <file>,v file and the
  5095. new revision of <file> will appear only on that branch.
  5096. See Section 4C, on Branching.
  5097. Last modified: _6/13/1997_
  5098. 7. How do I modify the modules file? How about the other files in the
  5099. CVSROOT administrative area?
  5100. A module named "modules" has been provided in the default modules
  5101. file, so you can type:
  5102. cvs checkout modules
  5103. cd modules
  5104. Another module named CVSROOT has been provided in the default modules
  5105. file, covering all the administrative files. Type:
  5106. cvs checkout CVSROOT
  5107. cd CVSROOT
  5108. Then you can edit your files, followed by:
  5109. cvs commit
  5110. If you start with the provided template for the "modules" file, the
  5111. CVSROOT and the "modules" module will have the "mkmodules" program as
  5112. a "commit helper". After a file is committed to such a module,
  5113. "mkmodules" will convert a number of standard files (See 4B.2) in the
  5114. CVSROOT directory inside the Repository into a form that is usable by
  5115. CVS.
  5116. Last modified: _6/13/1997_
  5117. 8. How do I split a file into pieces, retaining revision histories?
  5118. If you and a coworker find yourselves repeatedly committing the same
  5119. file, but never for changes in the same area of the file, you might
  5120. want to split the file into two or more pieces. If you are both
  5121. changing the same section of code, splitting the file is of no use.
  5122. You should talk to each other instead.
  5123. If you decide to split the file, here's a suggestion. In many ways, it
  5124. is similar to multiple "renamings" as described in 2C.4 above.
  5125. Say you want to split , which already in the Repository, into three
  5126. pieces, , and .
  5127. Copy the RCS (",v") files directly in the Repository, creating the
  5128. new files, then bring readable copies of the new files into the
  5129. working directory via "update".
  5130. cp $CVSROOT//,v $CVSROOT//,v cp $CVSROOT//,v $CVSROOT//,v
  5131. cvs update
  5132. Then remove all the from the new files, either using:
  5133. cvs log # Save the list of
  5134. cvs tag -d
  5135. cvs tag -d
  5136. . . .
  5137. (eivind@freebsd.org) or using the following little script to
  5138. autmatically remove the tags directly from the repository files:
  5139. #!/bin/sh
  5140. for file in $*
  5141. do
  5142. TAGS=`rlog $file | awk '/^symbolic names:/,/^keyword subst/' | awk 'BEG
  5143. IN {FS=":"} /^\t/ {print $1}'`
  5144. echo The tags in $file are
  5145. echo $TAGS
  5146. echo Is it OK to remove these?
  5147. read confirm
  5148. if [ "$confirm" = "y" -o "$confirm" = "yes" ]
  5149. then
  5150. for tag in $TAGS
  5151. do
  5152. echo Removing $file:$tag
  5153. rcs -n$tag $file
  5154. done
  5155. fi
  5156. done
  5157. Edit each file until it has the data you want in it. This is a
  5158. hand-editing job, not something CVS can handle. Then commit all the
  5159. files.
  5160. [From experience, I'd suggest making sure that only one copy of each
  5161. line of code exists among the three files, except for "include"
  5162. statements, which must be duplicated. And make sure the code
  5163. compiles.]
  5164. emacs
  5165. cvs commit
  5166. As in the "rename" case, by duplicating the files, you'll preserve the
  5167. change history and the ability to retrieve earlier revisions.
  5168. Of course, you have to alter your build system (e.g. Makefiles) to
  5169. take the new names and the change in contents into account.
  5170. Last modified: _3/11/1998_
  5171. Category: /What_is_CVS_/
  5172. " What is CVS? "
  5173. Category: /What_is_CVS_/How_does_CVS_differ_/
  5174. " + How does CVS differ from other, similar software?"
  5175. 1. How does CVS differ from RCS?
  5176. CVS uses RCS to do much of its work and absolutely all the work of
  5177. changing the underlying RCS files in the Repository.
  5178. RCS comprises a set of programs designed to keep track of changes to
  5179. individual files. Of course, it also allows you to refer to multiple
  5180. files on the command line, but they are handled by iterating over
  5181. individual files. There is no pretense of coordinated interaction
  5182. among groups of files.
  5183. CVS's main intent is to provide a set of grouping functions that allow
  5184. you to treat a collection of RCS files as a single object. Of course,
  5185. CVS also has to do a lot of iteration, but it tries its best to hide
  5186. that it is doing so. In addition, CVS has some truly group-oriented
  5187. facets, such as the modules file and the CVS administrative files that
  5188. refer to a whole directory or module.
  5189. One group aspect that can be a bit confusing is that a CVS branch is
  5190. not the same as an RCS branch. To support a CVS branch, CVS uses
  5191. "tags" (what RCS calls "symbols") and some local state, in addition to
  5192. RCS branches.
  5193. Other features offered by CVS that are not supported directly by RCS
  5194. are
  5195. Automatic determination of the state of a file, (e.g. modified,
  5196. up-to-date with the Repository, already tagged with the same string,
  5197. etc.) which helps in limiting the amount of displayed text you have to
  5198. wade through to figure out what changed and what to do next.
  5199. A copy-modify-merge scheme that avoids locking the files and allows
  5200. simultaneous development on a single file.
  5201. Serialization of commits. CVS requires you to merge all changes
  5202. committed (via "update") since you checked out your working copy of
  5203. the file. Although it is still possible to commit a file filled with
  5204. old data, it is less likely than when using raw RCS.
  5205. Relatively easy merging of releases from external Vendors.
  5206. Last modified: _6/13/1997_
  5207. 2. How does CVS differ from SCCS?
  5208. SCCS is much closer to RCS than to CVS, so some of the previous entry
  5209. applies.
  5210. You might want to take a look at Walter Tichy's papers on RCS, which
  5211. are referred to in the RCS man pages.
  5212. [[More info here?]]
  5213. Last modified: _6/13/1997_
  5214. 3. How does CVS differ from ClearCase?
  5215. ClearCase is a distributed client-server version control system.
  5216. ClearCase is a variant DSEE tools, formerly available on Apollo
  5217. platforms. The ClearCase tool set includes a few X-based interface
  5218. tools, a command-line interface, and C programmer API. It is currently
  5219. available on Sun, HP, SGI and OSF/1 platforms.
  5220. ClearCase uses a special Unix filesystem type, called "mvfs" for
  5221. "multi-version file system". Conceptually, mvfs adds another dimension
  5222. to a regular Unix filesystem. The new axis is used to store the
  5223. different versions of files and to provide a tree-hierarchical view of
  5224. a collection of objects that might be scattered across any number of
  5225. separate hosts on your local network.
  5226. Each user acquires a "view" into the file database by creating a
  5227. special mvfs mount point on their machine. Each view has a
  5228. "configuration spec" containing a set of selection rules that specify
  5229. the particular version of each file to make visible in that view. You
  5230. can think of a "view" as a work area in CVS, except that the files
  5231. don't really exist on your local disk until you modify them. This
  5232. technique conserves disk space because it doesn't keep private copies
  5233. of read-only files.
  5234. Another advantage is that a view is "transparent" in the sense that
  5235. all of the files in a "view" appear to be regular Unix files to other
  5236. tools and Unix system calls. An extended naming convention allows
  5237. access to particular versions of a file directly:
  5238. "test.cc@@/main/bugfix/3" identifies the third version of test.c on
  5239. the bugfix branch.
  5240. ClearCase supports both the copy-modify-merge model of CVS (by using
  5241. what are called "unreserved checkouts" and the checkin/checkout
  5242. development model with file locking. Directories are
  5243. version-controlled objects as well as files. A graphical merge tool is
  5244. provided. Like RCS, ClearCase supports branches, symbolic tags, and
  5245. delta compression. ASCII as well as binary files are supported, and
  5246. converters from RCS, SCCS, DSEE formats are also included.
  5247. A make-compatible build facility is provided that can identify common
  5248. object code and share it among developers. A build auditing feature
  5249. automatically records file dependencies by tracking every file that is
  5250. opened when producing a derived object, thus making explicit
  5251. dependency lists unnecessary. Pre- and post-event triggers are
  5252. available for most ClearCase operations to invoke user programs or
  5253. shell scripts. User-defined attributes can be assigned to any version
  5254. or object. Hyper-links between version controlled objects can record
  5255. their relationship.
  5256. For more information, contact:
  5257. Atria Software, Inc. 24 Prime Park Way Natick, MA 01760 info@atria.com
  5258. (508) 650-1193 (phone) (508) 650-1196 (fax)
  5259. Originally contributed by Steve Turner
  5260. Edited by the author of this FAQ.
  5261. Last modified: _6/13/1997_
  5262. 4. How does CVS differ from TeamWare/SparcWorks?
  5263. TeamWare is a configuration management tool from Sun Microsystems, a
  5264. part of SparcWorks. It uses the same copy and merge model as CVS. The
  5265. central abstraction is a workspace, which corresponds to either a CVS
  5266. branch or a checked out module. TeamWare allows you to manipulate
  5267. workspaces directly, including moving and merging code between
  5268. workspaces. You can put your workspace on tape and continue to work
  5269. with it at home, just like you can with CVS. TeamWare is built upon
  5270. and compatible with SCCS.
  5271. TeamWare provides both a command line interface and a graphical
  5272. interface. The CodeManager tool will display the project as a tree of
  5273. workspaces, and allows you to manipulate them with drag and drop. The
  5274. other tools are VersionTool that displays and manipulates a dag with a
  5275. version history of a single file, CheckPoint that will create symbolic
  5276. tags, MakeTool, a make compatible tool with a GUI, and FileMerge which
  5277. will interactively merge files when needed (like emerge for emacs). If
  5278. you have a sun, you can try /usr/old/mergetool for an old SunView
  5279. version of FileMerge.
  5280. Email: sunprosig@sun.com
  5281. Originally extracted from TeamWare
  5282. Marketing literature by Per Abrahamsen.
  5283. Edited by the author of this FAQ.
  5284. For more information, contact:
  5285. SunExpress, Inc. P.O. Box 4426 Bridgeton, MO 63044-9863 (800)873-7869
  5286. Last modified: _6/13/1997_
  5287. 5. How does CVS differ from Aegis?
  5288. Aegis appears to be a policy-setting tool that allows you to use other
  5289. sub-programs (make, RCS, etc.) to implement pieces of the imposed
  5290. policy.
  5291. The initial document seems to say that most Unix tools are inadequate
  5292. for use under Aegis.
  5293. It is not really similar to CVS and requires a different mindset.
  5294. [[Need more info here.]]
  5295. Last modified: _6/13/1997_
  5296. 6. How does CVS differ from Shapetools?
  5297. Shapetools includes a build mechanism (called Shape, not surprisingly)
  5298. that is aware of the version mechanism, and some dependency tracking.
  5299. It is based on a file system extension called Attributed File System,
  5300. which allows arbitrary-sized "attributes" to be associated with a
  5301. file. Files are version controlled in a manner similar to RCS.
  5302. Configurations are managed through the Shapefile, an extension of the
  5303. Makefile syntax and functionality. Shape includes version selection
  5304. rules to allow sophisticated selection of component versions in a
  5305. build.
  5306. Shapetools' concurrency control is pessimistic, in contrast to that of
  5307. CVS. Also, there's very limited support for branching and merging. It
  5308. has a built-in policy for transitioning a system from initial
  5309. development to production.
  5310. Contributed by Don Dwiggins
  5311. Last modified: _6/13/1997_
  5312. 7. How does CVS differ from TeamNet?
  5313. TeamNet is a configuration management tool from TeamOne.
  5314. For more information, contact:
  5315. TeamOne 710 Lakeway Drive, Ste 100 Sunnyvale, CA 94086 (800) 442-6650
  5316. Contributed by Steve Turner
  5317. Last modified: _6/13/1997_
  5318. 8. How does CVS differ from ProFrame?
  5319. ProFrame is a new system integration framework from IBM. ProFrame is
  5320. compliant with the CFI (CAD Framework Initiative) industry standards,
  5321. including the Scheme extension language.
  5322. ProFrame consists of three major components: (1) the Process Manager
  5323. that automates your local design methodology (2) the Design Data
  5324. Manager handles configuration management, and (3) Inter-tool
  5325. Communication to provide a communication path among tools running on
  5326. heterogeneous servers.
  5327. The Design Data Manager(2) is probably the appropriate component to
  5328. compare to CVS. The Design Data Manager provides version control with
  5329. checkin/checkout capability, configuration management, and data
  5330. dependency tracking. A graphical data selection interface is provided.
  5331. Using this interface, you may create and manipulate objects and
  5332. hierarchy structures, view the revision history for an object, and
  5333. view and assign attributes to a design object.
  5334. The ProFrame server currently runs only on RS6000, but clients may be
  5335. a wide variety of Unix platforms. Contact IBM for the latest platform
  5336. information.
  5337. For more information, contact:
  5338. IBM EDA Marketing and Sales P.O. Box 950, M/S P121 Poughkeepsie, NY
  5339. 12602 (800) 332-0066
  5340. Contributed by Steve Turner
  5341. [extracted from the ProFrame 1.1.0 datasheet]
  5342. Last modified: _6/13/1997_
  5343. 9. How does CVS differ from CaseWare/CM?
  5344. CaseWare/CM is a software configuration management product from
  5345. CaseWare, Inc. CaseWare/CM may be customized to support a wide variety
  5346. of methodologies, including various phases of the software lifecycle,
  5347. and different access rights for users.
  5348. A GUI is provided to view version histories and configurations. A
  5349. merge tools is also included. CaseWare supports type-specific
  5350. lifecycles, which allows different types of files to move through
  5351. different lifecycles. Also provided is a build facility to support
  5352. automatic dependency analysis, parallel, distributed, and remote
  5353. builds, and variant releases.
  5354. CaseWare/CM has been integrated with other CASE tools, including
  5355. FrameMaker, ALSYS Ada, CodeCenter/Object Center, HP SoftBench, and
  5356. Software Through Pictures. CaseWare also offers CaseWare/PT, a problem
  5357. tracking system to integrate change requests with configuration
  5358. management.
  5359. Multiple vendors and operating systems are supported.
  5360. For more information, contact:
  5361. CaseWare, Inc. 108 Pacifica, 2nd Floor Irvine, CA 92718-3332 (714)
  5362. 453-2200 (phone) (714) 453-2276 (fax)
  5363. Contributed by Steve Turner
  5364. [extracted from the CaseWare/CM data sheet]
  5365. Last modified: _6/13/1997_
  5366. 10. How does CVS differ from SABLIME?
  5367. Produced by AT&T. Sablime uses SCCS as the underlying source code
  5368. control system. It uses some other control system (called sbcs I
  5369. think) for managing binary files. It uses lock, edit, comit, unlock
  5370. mechanism. It has a motif based GUI and curses based GUI (that works
  5371. only with ksh, not tcsh, or bash) to do more common tasks. It has even
  5372. a command line interface.
  5373. Changing source happens as a result of MR. A testing person or a
  5374. developer assigns an MR (modification request) to a group of people.
  5375. They are allowed to take out files under that MR and change them and
  5376. check them back in. You can set up dependencies between and MR and do
  5377. release management to say "I want the sources to include these MRs"
  5378. etc. It is a reasonably good maintanance system. It is bit heavy
  5379. weight though, and the interface is not too polished and does not work
  5380. on windows (though that may have changed). rama@savera.com
  5381. Last modified: _7/30/1998_
  5382. 11. How does CVS differ from PVCS?
  5383. PVCS works on single files like RCS and SCCS, CVS works on complete
  5384. subsystems. PVCS has a make utility (called a configuration builder),
  5385. CVS does not. PVCS has a GUI interface for Unix, DOS, OS/2, and MS
  5386. Windows.
  5387. Intersolv, Inc.
  5388. 1700 NW 167th Place
  5389. OR 97006
  5390. Contributed by Per Abrahamsen
  5391. [Extracted from Intersolv Marketing literature.]
  5392. Last modified: _6/13/1997_
  5393. 12. How does CVS differ from CMVC?
  5394. CMVC is an IBM Configuration Management and Version Control system.
  5395. (Though I'm not certain that's the right acronym expansion.) It runs
  5396. on Suns, HPs, RS6000s, OS/2 and Windows.
  5397. Other than revision control, it apparently has features to manage
  5398. releases, bug tracking and the connection between alterations and
  5399. reported bugs and feature requests. It is a client/server system,
  5400. based on a choice of commercial Relational Database systems, and it
  5401. provides a Motif or command line interface.
  5402. Unlike CVS, it uses a strict locking protocol to serialize source code
  5403. alterations.
  5404. Last modified: _6/13/1997_
  5405. Category: /What_is_CVS_/What_do_you_mean_by_/
  5406. " + What do you mean by . . .? (Definitions)"
  5407. 1. What are "The Repository", "$CVSROOT" and "CVSROOT"?
  5408. The Repository is a directory tree containing the CVS administrative
  5409. files and all the RCS files that constitute "imported" or "committed"
  5410. work. The Repository is kept in a shared area, separate from the
  5411. working areas of all developers.
  5412. Users of CVS must set their "CVSROOT" environment variable to the
  5413. absolute pathname of the head of the Repository. Most command line
  5414. interpreters replace an instance of "$CVSROOT" with the value of the
  5415. "CVSROOT" environment variable. By analogy, in this document
  5416. "$CVSROOT" is used as shorthand for "the absolute pathname of the
  5417. directory at the head of the Repository".
  5418. One of the things found in $CVSROOT is a directory named CVSROOT. It
  5419. contains all the "state", the administrative files, that CVS needs
  5420. during execution. The "modules", "history", "commitinfo", "loginfo"
  5421. and other files can be found there. See 4B.2 for more information
  5422. about CVSROOT files.
  5423. Last modified: _6/13/1997_
  5424. 2. What is an RCS file?
  5425. An RCS file is a text file containing the source text and the revision
  5426. history for all committed revisions of a source file. It is stored
  5427. separately from the working files, in a directory hierarchy, called
  5428. the Repository.
  5429. RCS is the "Revision Control System" that CVS uses to manage
  5430. individual files. RCS file names normally end in ",v", but that can be
  5431. altered (via the RCS -x option) to conform to file naming standards on
  5432. platforms with unusual filename limitations.
  5433. Last modified: _6/13/1997_
  5434. 3. What is a working file?
  5435. A working file is a disk file containing a checked-out copy of a
  5436. source file that earlier had been placed under CVS. If the working
  5437. file has been edited, the changes since the last committed revision
  5438. are invisible to other users of CVS.
  5439. Last modified: _6/13/1997_
  5440. 4. What is a working directory (or working area)?
  5441. A working directory is the place where you work and the place from
  5442. which you "commit" files.
  5443. The "checkout" command creates a tree of working directories, filling
  5444. them with working files. Each working directory contains a
  5445. sub-directory named ./CVS containing three administrative files, which
  5446. are created by "checkout" and are always present:
  5447. ./CVS/Entries
  5448. contains information about working files.
  5449. ./CVS/Repository
  5450. contains the location of the directory within the
  5451. Repository that was used to create the working directory.
  5452. ./CVS/Root
  5453. contains the value of $CVSROOT at the time you created
  5454. the working directory.
  5455. Other files may also appear in ./CVS depending on the state of your
  5456. working directory:
  5457. ./CVS/Tag
  5458. contains the "sticky tag" associated with the whole
  5459. directory. See 3A.2 for its main purpose.
  5460. [Created by "checkout" or "update" when using "-r <tag>".]
  5461. [Deleted by "checkout" or "update" when using '-A'.]
  5462. ./CVS/Entries.Static
  5463. contains a fixed list of working files. If this file
  5464. exists, an "update" doesn't automatically bring newly
  5465. added files out of the Repository.
  5466. [Created and maintained by hand.]
  5467. ./CVS/Checkin.prog
  5468. contains a program to run whenever anything in the
  5469. working directory is committed.
  5470. [Created by checkout if "-i <prog>" appears in the
  5471. modules file for the checked-out module.]
  5472. ./CVS/Update.prog
  5473. contains a program to run whenever anything in the
  5474. working directory is updated.
  5475. [Created by checkout if "-u <prog>" appears in the
  5476. modules file for the checked-out module.]
  5477. ./CVS/<file>,p ./CVS/<file>,t
  5478. contain (possibly zero-length) state information about an
  5479. "add" that has not been committed.
  5480. [Created by "add".]
  5481. [Deleted by "commit" or "remove".]
  5482. Last modified: _6/13/1997_
  5483. 5. What is "checking out"?
  5484. "Checking out" is the act of using the "checkout" command to copy a
  5485. particular revision from a set of RCS files into your working area.
  5486. You normally execute "checkout" only once per working directory (or
  5487. tree of working directories), maintaining them thereafter with the
  5488. "update" command.
  5489. See section 3C on the "checkout" command.
  5490. Last modified: _6/13/1997_
  5491. 6. What is a revision?
  5492. A "revision" is a version of a file that was "committed" ("checked
  5493. in", in RCS terms) some time in the past. CVS (and RCS) can retrieve
  5494. any file that was committed by specifying its revision number or its
  5495. "tag" ("symbolic name", in RCS terms).
  5496. In CVS, a "tag" is more useful than a revision number. It usually
  5497. marks a milestone in development represented by different revision
  5498. numbers in different files, all available as one "tagged" collection.
  5499. Sometimes the word "revision" is used as shorthand for "the file you
  5500. get if you retrieve (via "checkout" or "update") the given revision
  5501. from the Repository."
  5502. Last modified: _6/13/1997_
  5503. 7. What is a "Tag"?
  5504. A "Tag" is a symbolic name, a synonym or alias for a particular
  5505. revision number in a file. The CVS "tag" command places the same "Tag"
  5506. on all files in a working directory, allowing you to retrieve those
  5507. files by name in the future.
  5508. The CVS "Tag" is implemented by applying RCS "symbols" to each
  5509. individual file. The Tags on a file (or collection of files) may be
  5510. displayed using the "log" command.
  5511. Last modified: _6/13/1997_
  5512. 8. What are "HEAD" and "BASE"?
  5513. HEAD and BASE are built-in tags that don't show up in the "log" or
  5514. "status" listings. They are interpreted directly by CVS.
  5515. "HEAD" refers to the latest revision on the current branch in the
  5516. Repository. The current branch is either the main line of development,
  5517. or a branch in development created by placing a branch tag on a set of
  5518. files and checking out that branch.
  5519. "BASE" refers to the revision on the current branch you last checked
  5520. out, updated, or committed. If you have not modified your working
  5521. file, "BASE" is the committed revision matching it.
  5522. Most of the time BASE and HEAD refer to the same revision. They can
  5523. become different in two ways:
  5524. Someone else changed HEAD by committing a new revision of your file
  5525. to the Repository. You can pull BASE up to equal HEAD by executing
  5526. "update".
  5527. You moved BASE backward by executing "checkout" or "update" with the
  5528. option "-r <rev/tag>" or "-D <date>". CVS records a sticky tag and
  5529. moves your files to the specified earlier revision. You can clear the
  5530. sticky tag and pull BASE up to equal HEAD again by executing "update
  5531. -A".
  5532. Last modified: _6/13/1997_
  5533. 9. What is a Branch?
  5534. In general, a branch is any mechanism that allows one or more
  5535. developers to modify a file without affecting anyone other than those
  5536. working on the same branch.
  5537. There are four kinds of "branch" CVS can manage:
  5538. The Vendor Branch.
  5539. A single vendor branch is supported. The "import" command takes a
  5540. sequence of releases from a source code vendor (called a "vendor" even
  5541. if no money is involved), placing them on a special "Vendor" branch.
  5542. The Vendor branch is considered part of the "Main line" of
  5543. development, though it must be merged into locally modified files on
  5544. the RCS Main branch before the "import" is complete.
  5545. See Section 3H ("import").
  5546. Your Working directory.
  5547. A checked-out working directory, can be treated like a private branch.
  5548. No one but you can touch your files. You have complete control over
  5549. when you include work committed by others. However, you can't commit
  5550. or tag intermediate versions of your work.
  5551. A Development branch.
  5552. A group of developers can share changes among the group, without
  5553. affecting the Main line of development, by creating a branch. Only
  5554. those who have checked-out the branch see the changes committed to
  5555. that branch. This kind of branch is usually temporary, collapsing
  5556. (i.e. merge and forget) into the Main line when the project requiring
  5557. the branch is completed.
  5558. You can also create a private branch of this type, allowing an
  5559. individual to commit (and tag) intermediate revisions without changing
  5560. the Main line. It should be managed exactly like a Development Branch
  5561. -- collapsed into the Main line (or its parent branch, if that is not
  5562. the Main Branch) and forgotten when the work is done.
  5563. A Release branch.
  5564. At release time, a branch should be created marking what was released.
  5565. Later, small changes (sometimes called "patches") can be made to the
  5566. release without including everything else on the Main line of
  5567. development. You avoid forcing the customer to accept new, possibly
  5568. untested, features added since the release. This is also the way to
  5569. correct bugs found during testing in an environment where other
  5570. developers have continued to commit to the Main line while you are
  5571. testing and packaging the release.
  5572. Although the internal format of this type of branch (branch tag and
  5573. RCS branches) is the same as in a development branch, its purpose and
  5574. the way it is managed are different. The major difference is that a
  5575. Release branch is normally Permanent. Once you let a release out the
  5576. door to customers, or to the next stage of whatever process you are
  5577. using, you should retain forever the branch marking that release.
  5578. Since the branch is permanent, you cannot incorporate the branch fixes
  5579. into the Main line by "collapsing" (merging and forgetting) the
  5580. release branch. For large changes to many files on the release branch,
  5581. you will have to perform a branch merge using "update -j <rev> -j
  5582. <rev>". (See 4C.7)
  5583. The most common way to merge small changes back into Main line
  5584. development is to make the change in both places simultaneously. This
  5585. is faster than trying to perform a selective merge.
  5586. See 1D.12 (merges) and Section 4C, on Branching for more info.
  5587. Last modified: _6/13/1997_
  5588. 10. What is "the trunk"?
  5589. Another name for the RCS Main Branch. The RCS Main Branch is related,
  5590. but not equivalent, to both the CVS Main branch and what developers
  5591. consider to be the Main line of development. See 3H.3 and Section 4C
  5592. on Branching.
  5593. Last modified: _6/13/1997_
  5594. 11. What is a module?
  5595. In essence, a module is a name you hand to the "checkout" command to
  5596. retrieve one or more files to work on. It was originally intended to
  5597. be a simple, unique name in the "modules" file attached to a directory
  5598. or a subset of files within a directory.
  5599. The module idea is now a somewhat slippery concept that can be defined
  5600. in two different ways:
  5601. * A module is an argument to "checkout". There are three types:
  5602. 1. An entry in the modules file. A "module" name as described in
  5603. 'B.' below.
  5604. 2. A relative path to a directory or file in the Repository.
  5605. 3. A mixed-mode string of "modulename/relative-path". Everything
  5606. up to the first slash ('/') is looked up as a module. The
  5607. relative path is appended to the directory associated with
  5608. the module name and the resulting path is checked out as in
  5609. #2 above.
  5610. * A module is a unique (within the file) character string in the
  5611. first column of the modules file. There are five types:
  5612. 1. A name for a directory within the Repository that allows you
  5613. to ignore the parent directories above it.
  5614. Example:
  5615. emacs gnu/emacs
  5616. 2. A name for a subset of the files within such a directory.
  5617. Example:
  5618. ls unix/bin Makefile ls.c
  5619. The 2nd through Nth strings in the above can be files,
  5620. directories or module substitutions. No relative paths.
  5621. A module substitution occurs when you use a '&module-name'
  5622. reference. The module-name referred to is logically
  5623. substituted for the '&module-name' string.
  5624. 3. A relative pathname to a directory within the Repository
  5625. which, when checked out, creates an image of part of the
  5626. Repository structure in your current directory.
  5627. Example:
  5628. gnu/emacs -o /bin/emacs.helper gnu/emacs
  5629. The files checked out are exactly the same as the files
  5630. "checkout" would retrieve if the path weren't even in the
  5631. modules file. The only reason to put this kind of relative
  5632. pathname into the modules file is to hook one of the helper
  5633. functions onto it.
  5634. 4. A relative pathname to a single file within the Repository
  5635. which, when checked out, creates something you probably don't
  5636. want: It creates a directory by the name of the file and puts
  5637. the file in it.
  5638. Example:
  5639. gnu/emacs/Makefile -o /bin/emacs.helper gnu/emacs Makefile
  5640. The file checked out is the same as what you would get if you
  5641. handed the relative pathname to the "checkout" command. But
  5642. it puts it in a strange place. The only reason to do this is
  5643. to hook a helper function onto a specific file name.
  5644. 5. An alias consisting of a list of any of the above, including
  5645. other aliases, plus exceptions.
  5646. Example:
  5647. my_work -a emacs !emacs/tests gnu/bison unix/bin/ls.c
  5648. The exception "!emacs/test" above is functionally equivalent
  5649. to specifying "!emacs/tests" on the "checkout" command line.
  5650. Another way to look at it is that the modules file is simply another
  5651. way to "name" files. The hierarchical directory structure provides
  5652. another. You should use whatever turns out to be simplest for your
  5653. development group.
  5654. See 4G.2 for some specific ideas about how to use the modules file.
  5655. Last modified: _11/12/1997_
  5656. 12. What does "merge" mean?
  5657. A merge is a way of combining changes made in two independent copies
  5658. of a common starting file. Checking out an RCS revision produces a
  5659. file, so for the purposes of a merge "file" and "revision" are
  5660. equivalent. So, we can say there are always three "files" involved in
  5661. a merge:
  5662. The original, starting, "base" or "branch point" file.
  5663. A copy of the base file modified in one way.
  5664. Another copy of the base file modified in a different way.
  5665. Humans aren't very good at handling three things at once, so the
  5666. terminology dealing with merges can become strained. One way to think
  5667. about it is that all merges are performed by inserting the difference
  5668. between a base revision and a later revision (committed by someone
  5669. else) into your working file. Both the "later" revision and your
  5670. working file are presumed to have started life as a copy of the "base"
  5671. revision.
  5672. In CVS, there are three main types of "merge":
  5673. The "update" command automatically merges revisions committed by
  5674. others into your working file. In this case, the three files involved
  5675. in the merge are:
  5676. Base: The revision you originally checked out. Later: A revision
  5677. committed onto the current branch after you checked out the Base
  5678. revision. Working: Your working file. The one lying in the working
  5679. directory containing changes you have made.
  5680. The "update -j <branch_tag> {optional files}" command merges changes
  5681. made on the given branch into your working files, which is presumed to
  5682. be on the Main line of development.
  5683. See 4C.6
  5684. The "update -j <rev> -j <rev> {optional files}" command merges the
  5685. difference between two specified revisions into files in your working
  5686. directory. The two revisions <rev> are usually on the same branch and,
  5687. when updating multiple files, they are most useful when they are Tag
  5688. names rather than numeric revisions.
  5689. See 4C.7
  5690. Last modified: _6/13/1997_
  5691. Category: /What_is_CVS_/What_is_CVS_Whats_it/
  5692. " + What is CVS? What's it for? Why CVS?"
  5693. 1. What does CVS stand for? Can you describe it in one sentence?
  5694. "CVS" is an acronym for the "Concurrent Versions System".
  5695. CVS is a "Source Control" or "Revision Control" tool designed to keep
  5696. track of source changes made by groups of developers working on the
  5697. same files, allowing them to stay in sync with each other as each
  5698. individual chooses.
  5699. Last modified: _6/13/1997_
  5700. 2. What is CVS for? What does it do for me?
  5701. CVS is used to keep track of collections of files in a shared
  5702. directory called "The Repository". Each collection of files can be
  5703. given a "module" name, which is used to "checkout" that collection.
  5704. After checkout, files can be modified (using your favorite editor),
  5705. "committed" back into the Repository and compared against earlier
  5706. revisions. Collections of files can be "tagged" with a symbolic name
  5707. for later retrieval.
  5708. You can add new files, remove files you no longer want, ask for
  5709. information about sets of files in three different ways, produce patch
  5710. "diffs" from a base revision and merge the committed changes of other
  5711. developers into your working files.
  5712. Last modified: _6/13/1997_
  5713. 3. How does CVS work?
  5714. CVS saves its version-control information in RCS files stored in a
  5715. directory hierarchy, called the Repository, which is separate from the
  5716. user's working directory.
  5717. Files in the Repository are stored in a format dictated by the RCS
  5718. commands CVS uses to do much of its real work. RCS files are standard
  5719. byte-stream files with an internal format described by keywords stored
  5720. in the files themselves.
  5721. To begin work, you execute a "checkout" command, handing it a module
  5722. name or directory path (relative to the $CVSROOT variable) you want to
  5723. work on. CVS copies the latest revision of each file in the specified
  5724. module or directory out of the Repository and into a directory tree
  5725. created in your current directory. You may specify a particular branch
  5726. to work on by symbolic name if you don't want to work on the default
  5727. (main or trunk) branch.
  5728. You may then modify files in the new directory tree, build them into
  5729. output files and test the results. When you want to make your changes
  5730. available to other developers, you "commit" them back into the
  5731. Repository.
  5732. Other developers can check out the same files at the same time. To
  5733. merge the committed work of others into your working files you use the
  5734. "update" command. When your merged files build and test correctly, you
  5735. may commit the merged result. This method is referred to as
  5736. "copy-modify-merge", which does not require locks on the source files.
  5737. At any time, usually at some milestone, you can "tag" the committed
  5738. files, producing a symbolic name that can be handed to a future
  5739. "checkout" command. A special form of "tag" produces a branch in
  5740. development, as usually happens at "release" time.
  5741. When you no longer plan to modify or refer to your local copy of the
  5742. files, they can be removed.
  5743. Last modified: _6/13/1997_
  5744. 4. What is CVS useful for?
  5745. CVS is intended to handle source control for files in three major
  5746. situations:
  5747. Multiple developers working on the same files.
  5748. The major advantage of using CVS over the simpler tools like RCS or
  5749. SCCS is that it allows multiple developers to work on the same sources
  5750. at the same time.
  5751. The shared Repository provides a rendezvous for committed sources that
  5752. allows developers a fair amount of flexibility in how often to publish
  5753. (via the "commit" command) changes or include work committed by others
  5754. (via the "update" command).
  5755. Tracking a stream of releases from a source vendor.
  5756. If you are making changes to sources distributed by someone else, the
  5757. CVS feature, called the Vendor Branch, allows you to combine local
  5758. modifications with repeated vendor releases.
  5759. I have found this most useful when dealing with sources from three
  5760. major classes of source vendor:
  5761. Large companies who send you tapes full of the latest release (e.g.
  5762. Unix OS vendors, database companies).
  5763. Public Domain software which *always* requires work.
  5764. Pseudo-Public sources which may require work. (e.g. GNU programs, X,
  5765. CVS itself, etc.)
  5766. Branching development.
  5767. Aside from the "Vendor Branch", there are three kinds of "branches in
  5768. development" that CVS can support:
  5769. Your working directory can be treated as a private branch.
  5770. A Development branch can be shared by one or more developers.
  5771. At release time, a branch is usually created for bug fixes.
  5772. (See 1D.9 and Section 4C for more info on branches.)
  5773. CVS's branch support is a bit primitive, but it was designed to allow
  5774. you to create branches, work on them for while and merge them back
  5775. into the main line of development. You should also be able to merge
  5776. work performed on the main branch into the branch you are working on.
  5777. Arbitrary sharing and merging between branches is not currently
  5778. supported.
  5779. Last modified: _6/13/1997_
  5780. 5. What is CVS *not* useful for?
  5781. CVS is not a build system.
  5782. Though the structure of your Repository and modules file interact with
  5783. your build system (e.g. a tree of Makefiles), they are essentially
  5784. independent.
  5785. CVS does not dictate how you build anything. It merely stores files
  5786. for retrieval in a tree structure you devise.
  5787. CVS does not dictate how to use disk space in the checked out working
  5788. directories. If you require your Makefiles or build procedures to know
  5789. the relative positions of everything else, you wind up requiring the
  5790. entire Repository to be checked out. That's simply bad planning.
  5791. If you modularize your work, and construct a build system that will
  5792. share files (via links, mounts, VPATH in Makefiles, etc.), you can
  5793. arrange your disk usage however you like.
  5794. But you have to remember that *any* such system is a lot of work to
  5795. construct and maintain. CVS does not address the issues involved. You
  5796. must use your brain and a collection of other tools to provide a build
  5797. scheme to match your plans.
  5798. Of course, you should use CVS to maintain the tools created to support
  5799. such a build system (scripts, Makefiles, etc).
  5800. CVS is not a substitute for management.
  5801. You and your project leaders are expected to plan what you are doing.
  5802. Everyone involved must be aware of schedules, merge points, branch
  5803. names, release dates and the range of procedures needed to build
  5804. products. (If you produce it and someone else uses it, it is a
  5805. product.) CVS can't cover for a failure to manage your project.
  5806. CVS is an instrument for making sources dance to your tune. But you
  5807. are the piper and the composer. No instrument plays itself or writes
  5808. its own music.
  5809. CVS is not a substitute for developer communication.
  5810. When faced with conflicts within a single file, most developers manage
  5811. to resolve them without too much effort. But a more general definition
  5812. of "conflict" includes problems too difficult to solve without
  5813. communication between developers.
  5814. CVS cannot determine when simultaneous changes within a single file,
  5815. or across a whole collection of files, will logically conflict with
  5816. one another. Its concept of a "conflict" is purely textual, arising
  5817. when two changes to the same base file are near enough to spook the
  5818. merge command into dropping conflict markers into the merged file.
  5819. CVS is not capable of figuring out distributed conflicts in program
  5820. logic. For example, if you change the arguments to function X defined
  5821. in file A and, at the same time, edit file B, adding new calls to
  5822. function X using the old arguments. You are outside the realm of CVS's
  5823. competence.
  5824. Acquire the habit of reading specs and talking to your peers.
  5825. CVS is not a configuration management system.
  5826. CVS is a source control system. The phrase "configuration management"
  5827. is a marketing term, not an industry-recognized set of functions.
  5828. A true "configuration management system" would contain elements of the
  5829. following:
  5830. * Source control.
  5831. * Dependency tracking.
  5832. * Build systems (i.e. What to build and how to find
  5833. things during a build. What is shared? What is local?)
  5834. * Bug tracking.
  5835. * Automated Testing procedures.
  5836. * Release Engineering documentation and procedures.
  5837. * Tape Construction.
  5838. * Customer Installation.
  5839. * A way for users to run different versions of the same
  5840. software on the same host at the same time.
  5841. CVS provides only the first.
  5842. Last modified: _6/13/1997_
  5843. Category: /What_is_CVS_/Where_do_I_find_CVS_/
  5844. " + Where do I find CVS? Where can I find Help?"
  5845. 1. How do I get more information about CVS?
  5846. The first thing I would do is to read the Info file that comes with
  5847. the CVS sources under "doc". You can format and read the cvs.texinfo
  5848. file in two ways: 1. Use TeX to format it and a "dvips" command to
  5849. print it and 2. Install the cvs.info files that are created by the
  5850. Makefile and read them online using the Emacs "info-mode" or a
  5851. stand-alone "info" reader.
  5852. Then I'd run "cvsinit" to set up a Repository and read the man page
  5853. while trying out the commands.
  5854. Type "cvs -H" for general help or "cvs -H command" for
  5855. command-specific help.
  5856. For background, you can read the original CVS paper (in the source
  5857. tree, under "doc"). It describes the purpose of CVS and some of how it
  5858. was designed. Note that the emphasis of the document (especially on
  5859. multiple vendors providing the same sources) is somewhat out of date.
  5860. For more detailed information about "internals", read the man pages
  5861. for RCS. If you are a programmer, you can also read the source code to
  5862. CVS.
  5863. Other information and tutorials may be available in the "doc"
  5864. directory of the FTP archive described below.
  5865. For current information, and a fair amount of detail, join the
  5866. info-cvs mailing list described below.
  5867. Last modified: _6/13/1997_
  5868. 2. Is there an archive of CVS material?
  5869. An anonymous FTP area has been set up. It contains many of the CVS
  5870. files you might want, including extra documentation, patches and a
  5871. copy of the latest release.
  5872. ftp ftp.delos.com
  5873. >>> User: anonymous
  5874. >>> Passwd:
  5875. cd /pub/cvs
  5876. get README
  5877. get Index
  5878. The README has more (and more up-to-date) information. The Index
  5879. contains a terse list of what is in the archive.
  5880. A WWW home page is also available at http://www.delos.com/cvs.
  5881. This Didn't Exist 6/23/1998
  5882. Last modified: _6/24/1998_
  5883. 3. How do I get files out of the archive if I don't have FTP?
  5884. Use one of the FTP<->Email servers. These are the ones I've been told
  5885. about:
  5886. FTPMAIL service is available from the same host as the FTP server
  5887. described above. Send mail to "ftpmail@delos.com" containing "help" in
  5888. the body of the message. For example, on most Unix systems, you can
  5889. type:
  5890. echo help | Mail ftpmail@delos.com
  5891. The FTPMAIL server will respond with a document describing how to use
  5892. the server. If the "Mail" command doesn't exist on your system, try
  5893. "mailx", "/usr/ucb/mail" or "/bin/mail".
  5894. If you are on BITNET, use Princeton's BITFTP server. Type
  5895. echo 'send help' | Mail bitftp@pucc.princeton.edu
  5896. (It is likely that only BITNET addresses can use this one.)
  5897. Other possibilities I've heard of from the net: (Try the one closest
  5898. to you.)
  5899. ftpmail@decwrl.dec.com ftpmail@sunsite.unc.edu ftpmail@cs.arizona.edu
  5900. ftpmail@cs.uow.edu.au ftpmail@doc.ic.ac.uk
  5901. Last modified: _6/13/1997_
  5902. 4. How do I get a copy of the latest version of CVS?
  5903. The latest released version of CVS and all the programs it depends on
  5904. should be available through anonymous FTP on any FSF archive. The main
  5905. FSF archive is at "prep.ai.mit.edu". There are mirrors of the FSF
  5906. archive on UUNET and other large Internet sites.
  5907. Program(s) Suggested revision
  5908. ----------- -----------------------
  5909. CVS 1.5
  5910. RCS 5.7 (latest version available today)
  5911. GNU diff 2.7 (or later) [contained in diffutils-2.7]
  5912. GDBM 1.5 (or later) [optional]
  5913. The GNU version of diff is suggested by both the RCS and CVS
  5914. configuration instructions because it works better than the standard
  5915. version.
  5916. It is a good idea not to accept the versions of CVS, RCS or diff you
  5917. find lying on your system unless you have checked out their
  5918. provenance. Using inconsistent collections of tools can cause you more
  5919. trouble than you can probably afford.
  5920. The FTP archive mentioned above should contain the latest official
  5921. release of CVS, some official and unofficial patches and possibly
  5922. complete patched versions of CVS in use somewhere.
  5923. Last modified: _6/13/1997_
  5924. 5. Is there a mailing list devoted to CVS? How do I find it?
  5925. An Internet mailing list named "info-cvs" grew out of the private
  5926. mailing list used by the CVS 1.3 alpha testers in early 1992.
  5927. Throughout 1994, the list received an average of 100 messages per
  5928. month.
  5929. You can add yourself to the mailing list by sending an Email message
  5930. to:
  5931. info-cvs-request@prep.ai.mit.edu
  5932. (Don't forget the "-request" or you'll send a message to the whole
  5933. list, some of whom are capable of remote execution.)
  5934. Mail to the whole list should be sent to:
  5935. info-cvs@prep.ai.mit.edu
  5936. An archive of the mailing list is maintained in the FTP archive
  5937. mentioned above.
  5938. Last modified: _6/13/1997_
  5939. 6. What happened to the CVS Usenet newsgroup I heard about?
  5940. A Usenet newsgroup named "gnu.cvs.info" was announced in April
  5941. 1993, with an expected creation date of August, 1993. However,
  5942. nothing came of this.
  5943. If you want to discuss CVS on usenet, the correct group is
  5944. comp.software.config-mgmt (which also covers other configuration
  5945. management systems). Someday it might be possible to create a
  5946. comp.software.config-mgmt.cvs, but only if there is sufficient
  5947. CVS traffic on comp.software.config-mgmt.
  5948. kingdon@cyclic.com
  5949. Last modified: _9/6/1997_
  5950. _________________________________________________________________
  5951. [Add an answer to this category]
  5952. [Category /]
  5953. _________________________________________________________________
  5954. _Search the FAQ-O-Matic:_ ____________________ Search
  5955. [matching all words]
  5956. Or look for questions modified in the last: [7.] Days
  5957. _________________________________________________________________
  5958. The FAQ-O-Matic lives at http://gille.loria.fr:7000/cgi-bin/faqomatic.
  5959. The code was written by Jon Howell, and the content by folks from all
  5960. over the web.
  5961. _________________________________________________________________