1 This file contains a CVS FAQ. Until 1995 it was maintained by David
2 Grubbs. It was out of date and not being maintained, but it had a
3 certain following and in 1997 Pascal Molli decided to start
4 maintaining it with the FAQ-O-Matic package which allows any
5 contributor with a web browser to help maintain it. The following
6 text is (mostly automatically) extracted from the FAQ-O-Matic. The
7 odds are good that the file that you are currently reading is out of
8 date with respect to the online FAQ-O-Matic, which is part of Pascal
9 Molli's CVS web site at http://www.loria.fr/~molli/cvs-index.html
10 (currently under "Documentation"). The online version is also
11 somewhat better in terms of things like tables of contents (at least
12 until someone can write some code to extract data from a FAQ-O-Matic
13 and insert things like tables of contents).
15 The answers which are dated "6/13/1997" below are really from the 1995
16 FAQ, for the most part. Many of them are out of date. If you have
17 some time, you are encouraged to double-check them against other
18 sources like the Cederqvist manual and update the FAQ. If you don't
19 have such time, take them with a grain of salt or a few.
21 Since Feb. 2000 CVS is being maintained by OpenAvenue, Inc. and many of
22 the existing resources have been centeralized on http://www.cvshome.org.
24 Category: /, all questions
32 This is FAQ-O-Matic, a quick-and-dirty Perl hack (aren't they all?) by
35 It seems like most FAQ maintainers make a valiant initial effort, then get
36 a life and don't have time to keep their FAQs up to date. Also, I often
37 find out a solution to a problem, and feel like I could write a single
38 FAQ answer on it in a few minutes, but where to post it?
40 Thus the FAQ-O-Matic was born. FAQ-O-Matic is a couple sleazy Perl scripts
41 that allow people to submit FAQ answers to this database, so it can stay
42 current, with just a tiny bit of work on any one person's part.
44 Yes, a bad guy could come along and wipe out all the FAQ entries. Please don't.
45 But to give the good guys some measure of comfort, each submission is stored
46 in an RCS file, so if someone does tamper, we can recover the database.
48 Guidelines for submissions:
50 1. Please _try to be fairly unbiased in matters of opinion._ Mailing lists are
51 the place to start flame wars (just kidding :v), but definitely not here.
53 2. Please _use HTML only conservatively_ in your entries. Links are appropriate
55 but put the URL in the plaintext also so it's useable on printed versions of
56 the FAQ. Inline images pointing off this site are inappropriate, as is much
57 fancy formatting. This is meant to be bandwidth-light and dumb-browser-friendly
60 3. If you feel there's a place for a _new category, or a reorganization of
61 existing questions_, don't hesitate to mail me (molli@loria.fr).
62 Category changes need to be done from my end.
64 4. Please _leave an email address_ at the bottom of your submission so that oth
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
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.
75 6. Please refrain from crude or inconsiderate language. Please don't use
76 this as a forum for advertising. However, mention of worthy commercial
77 products is certainly appropriate (even if you sell said product). Just
80 Last modified: _6/13/1997_
82 2. Adding a new category ?
84 just send me a mail at
87 Last modified: _6/13/1997_
89 Category: /Advanced_Topics_/
93 Category: /Advanced_Topics_/Branching_and_Mergin/
95 " + Branching and Merging"
99 Unfortunately, the word "branch" is an overloaded technical
100 term. It is used in too many different ways in three
101 categories. It might help to understand some of the issues by
102 going through the categories:
104 How Humans use the word "branch":
106 Most development starts with everyone working on the same
107 software, making changes and heading toward a single goal. This
108 is called something like "Main Line Development". Note that
109 though many people do main line development on CVS's "Main
110 Branch", that is a choice, not a requirement.
112 After a release or when one or more developers want to go off
113 and work on some project for a while, the Software Engineers
114 assigned to deal with large software issues generate a "Branch
115 in Development" to support the release or project. (Keep in
116 mind that a programmer is no more a Software Engineer than a
117 carpenter is a Civil Engineer.)
119 Essentially, the word "branch" implies a way to allow
120 simultaneous development on the same files by multiple people.
122 The above terms are human-oriented. They refer to actions that
123 people would like to take. They do *not* imply any particular
124 implementation or set of procedures. Branches in development
125 can be supported in many different ways.
127 How CVS uses the word "branch":
129 CVS uses the word "branch" in a number of ways. The two most
132 - The vendor branch holds releases from (normally) an outside
133 software vendor. It is implemented using a specific RCS branch
136 - The "Main Branch", which normally holds your "Main Line
137 Development", but is defined as the collection of revisions you
138 get when you "checkout" something fresh, or when you use the
139 '-A' option to "update".
141 Important Note: The CVS "Main Branch" is *not* the same as the
142 RCS concept with the same name. If you are using Vendor
143 Branches, files you have never changed are on three branches at
146 - The RCS 1.1.1 branch.
147 - The CVS Vendor branch.
148 - The CVS "Main Branch".
150 The concepts overlap, but they are not equivalent.
152 In referring to CVS, "branch" can be used in four other ways:
154 - A CVS working directory satisfies the definition of "branch"
155 for a single developer -- you are on a private "virtual branch"
156 that does not appear in any of the RCS files or the CVS control
159 - The CVS "default branch" is the Repository source for the
160 collection of files in your working directory. It is *not* the
161 same as the RCS "default branch". Normally the CVS default
162 branch is the same as the CVS Main branch. If you use the "-r
163 <branch_tag>" option to the "checkout" command, you will record
164 a "sticky" tag that changes your default branch to the one you
167 - A "magic" branch can be a branch that hasn't happened yet. It
168 is implemented by a special tag you can check out that is not
169 attached to a real RCS branch. When you commit a file to a
170 magic branch, the branch becomes real (i.e. a physical RCS
173 - And, of course, CVS uses "branch" to indicate a
174 human-oriented "branch in development".
176 How RCS uses the word "branch":
178 - The RCS "Main Branch" (Synonym: "The Trunk") contains a
179 series of two-part revision numbers separated by a single '.'
180 (e.g. 1.2). It is treated specially and is the initial default
181 branch. (The default default?)
183 - The RCS "Default" branch starts out attached to the RCS "Main
184 Branch". For RCS purposes, it can be changed to point to any
185 branch. Within CVS, you *must*not* alter the RCS default
186 branch. It is used to support the CVS idea of a "Main Branch"
187 and it must either point to the RCS Main Branch, or the Vendor
188 Branch (1.1.1) if you haven't made any changes to the file
189 since you executed "import".
191 Last modified: _6/13/1997_
193 2. Why (or when) would I want to create a branch?
195 Remember that you can think of your working directory as a "branch for
196 one". You can consider yourself to be on a branch all the time because
197 you can work without interfering with others until your project (big
200 The four major situations when you should create a branch:
202 When you expect to take a long time or make a large set of changes
203 that the merging process will be difficult. Both "long" and "large"
204 are defined in your own environment.
206 When you want to be able to "commit" and "tag" your work repeatedly
207 without affecting others.
209 If you ever think you need Source Control for your own work, but don't
210 want your changes to affect others, create a private branch. (Put your
211 username in the branch tag, to make it obvious that it is private.)
213 When you need to share code among a group of developers, but not the
214 whole development organization working on the files.
216 Rather than trying to share a working directory, you can move onto a
217 branch and share your work with others by "committing" your work onto
218 the branch. Developers not working on the branch won't see your work
219 unless they switch to your branch or explicitly merge your branch into
222 When you need to make minor changes to a released system.
224 Normally a "release" is labeled by a branch tag, allowing later work
225 on the released files. If the release is labeled by a non-branch tag,
226 it is easy to add a branch tag to a previously tagged module with the
227 "rtag" command. If the release is not tagged, you made a mistake.
228 Recovery requires identifying all revisions involved in the release
229 and adding a tag to them.
231 Last modified: _6/13/1997_
233 3. How do I create and checkout a branch?
237 Attach a non-branch tag to all the revisions you want to branch
238 from. (i.e. the branch point revisions)
240 When you decide you really need a branch, attach a branch tag to the
241 same revisions marked by the non-branch tag.
243 "Checkout" or "update" your working directory onto the branch.
245 Suggested procedure when using modules:
247 cvs rtag <branch_point_tag> module
249 cvs rtag -b -r <branch_point_tag> <branch_tag> <module>
251 cvs checkout -r <branch_tag> module
253 Suggested procedure when using your working directory, which
254 contains the revisions of your working files you want to branch from:
256 cvs tag <branch_point_tag>
258 cvs rtag -b -r <branch_point_tag> <branch_tag> <module>
260 cvs update -r <branch_tag>
262 In each procedure above, Step #1 applies a non-branch tag to all the
263 branch point revisions in the module/directory. Though this is not
264 strictly necessary, if you don't add a non-branch tag to the revisions
265 you branch from, you won't be able to refer to the branch point in the
268 Between steps 1 & 2 you may commit changes. The result would be same
269 because "rtag -r <oldtag> <newtag>" applies <newtag> to the same
270 revision that <oldtag> is attached to. You can use this technique to
271 avoid attaching *any* branch tags until you need them.
273 Step B.2 has two corollaries:
275 If you plan to create the branch tag before committing anything in
276 your working directory, you can use "cvs tag -b <branch_tag>" instead
277 of the "rtag" command.
279 The <module> can be a relative path to a directory from which your
280 working directory was checked out.
282 If you have trouble figuring out what <module> to use (or pathname to
283 use in its place), you can aim it at whatever parent directories you
284 believe will cover all your work.
286 If you are sure the <branch_tag> is not being used anywhere else, you
287 can even aim it at the whole Repository ($CVSROOT), if you have to. It
288 might take some extra time, but assuming that your <tag> is a unique
289 string and you don't use the '-f' option to "rtag -r", "rtag" will
290 only add a <tag> to files in which it actually *finds* the earlier
293 In each procedure above, Step #3 may occur any time after step 2.
294 Unless you explicitly remove them with "tag -d", a <tag> is permanent.
296 The <branch_tag> is an unusual creature. It labels a branch in a way
297 that allows you to "checkout" the branch, to "commit" files to the end
298 of the branch and to refer to the end of the branch. It does not label
299 the base of the branch (the branch point).
301 There are two obvious ways to choose the <branch_point_tag> and
302 <branch_tag> names. But keep in mind that the <branch_tag> is typed by
303 any developer who wants to work on the branch -- you should make it
304 mean something to them.
306 Style #1 presumes that the simple version string refers to a set of
307 designed, documented or promised features, not to a specific set of
308 files. In this case, you tag the branch with the generic Version
309 string and assume that whenever you refer to "Version", you want the
310 "latest" set of files associated with that Version, including all
311 patches. (You can substitute whatever you like for "bp_", as long as
312 your <branch_point_tag> is some modification of the <branch_tag>.)
314 <branch_point_tag> Matching <branch_tag>
317 bp_Release2-3-5 Release2-3-5
318 bp_Production4_5 Release4_5
320 Style #2 presumes that the simple version string refers to the
321 specific set of files used to construct the first release of
322 "version". In this case, you tag the branch-point revisions with the
323 generic Version string and assume that whenever you refer to this
324 Version, you want the original set of released revisions. To get the
325 latest patched revisions of the release, you refer to the branch tag
326 "latest_<branch_point_tag>". (You can substitute what ever you like
327 for "latest_", as long as your <branch_tag> is some modification of
328 the <branch_point_tag>.)
330 <branch_point_tag> Matching <branch_tag>
333 Release2-3-5 latest_Release2-3-5
334 Release4_5 latest_Production4_5
336 In both styles you can find out what you had to change since the
337 original release of this Version by typing:
339 cvs diff -r <branch_point_tag> -r <branch_tag>
341 For Style 1, this is:
343 cvs diff -r bp_<branch_tag> -r <branch_tag>
345 For Style 2, this is:
347 cvs diff -r <branch_point_tag> -r latest_<branch_point_tag>
349 Notes on "being on a branch":
351 - "update -r <tag>" tells CVS to attach a "sticky tag" to working
352 directory (in ./CVS/Tag) and the checked-out files (on each line of
355 - A "sticky" <tag> (including a <branch_tag>) causes most CVS commands
356 to act as if "-r <tag>" were on the command line.
358 - A "sticky" <branch_tag> indicates that the working directory (and
359 working files) are "on the branch".
361 Last modified: _6/13/1997_
363 4. Once created, how do I manage a branch?
365 The most important thing you should know about managing a branch is
366 that the creation of a branch is not a lightweight act. When you
367 create a branch, you must also create a set of procedures to keep
370 Specifically, you must:
372 - Remember that the branch exists. (This is non-trivial if you create
375 - Plan when to merge it back into the main line of development.
377 - Schedule the order that multiple branch merges are to be done.
379 - If you ever intend to merge branches into each other, instead of
380 limiting merges of branch work back into the "main line", you must
381 keep careful track of which parts of which branches have merged into
382 which other branches.
384 The simplest way to deal with branches is to limit their number,
385 "collapse" them back into the main line as quickly as is reasonable
386 and forget them. If a group wants to continue working, tell them to
387 create another branch off the fully merged main line.
389 Remember that CVS is just a tool. Over time, it will probably handle
390 branching better, requiring less careful attendance. But no matter how
391 good it becomes, the whole idea of "branching" is a complicated
392 management problem. Don't take it lightly.
394 Last modified: _6/13/1997_
396 5. Are there any extra issues in managing multiple branches?
398 If you plan to split from the "main line" and merge back after a time,
399 the only problem will be scheduling the order of branch merges. As
400 each branch is merged, the main line must be rebuilt and tested.
401 Merging multiple branches (i.e. "lines of development") before
402 building and testing creates more problems than you are ready for.
404 If you plan to collapse some branches into others, then move the
405 combined branches back into the main line, you have to be careful with
406 the revisions and tags you hand to your "update -j" command, but it
407 shouldn't be much trouble.
409 If you plan to allow every branch to incrementally take the work done
410 on other branches, you are creating an almost insurmountable
411 bookkeeping problem. Every developer will say "Hey, I can handle
412 taking just this little bit," but for the system as a whole it is
413 disaster. Try it once and see. If you are forced into this situation,
414 you will need to keep track of the beginning and end points of every
415 merge ever done. Good Luck.
417 Last modified: _6/13/1997_
419 6. How do I merge a whole branch back into the trunk?
421 If you don't have a working directory, you can checkout and merge in
424 cvs checkout -j <branch_tag> <module>
427 If you already have a working directory:
429 cd <working_directory>
430 cvs update <== Optional, to bring it up to date.
431 cvs update -j <branch_tag>
433 CVS will print lines beginning with
435 'U' for files that you hadn't changed, but the branch did.
437 'M' for files that you changed and the branch didn't
438 *and* for files that you both changed that were merged
439 without overlaps. (This overload is unfortunate.)
441 'C' for files that you both changed in a way that conflicts
444 You need to go edit all the 'C' files and clean up the conflicts. Then
445 you must commit them.
447 Last modified: _6/13/1997_
449 7. How do I merge changes from the trunk into my branch or between
452 The idea is similar to the above, but since CVS doesn't treat the main
453 branch like other branches, you'll have to be more careful. There are
454 5 different ways to look at the problem.
456 The way to merge *all* changes made on the trunk into a working
457 branch is to move to the branch you want via "checkout -r" or "update
460 cvs update -r <branch_tag> {optional files}
462 Then merge the changes from the trunk into your working branch using
463 the pseudo-tag named "HEAD":
465 cvs up -j HEAD {optional files}
467 You will get everything from the branch point of the branch named
468 <branch_tag> up to the HEAD of the main branch. This is still kind of
469 strange. If the file is on a branch, HEAD should be the latest thing
470 on the branch, not the HEAD of MAIN. But that's not the way CVS
473 If you run "cvs up -j HEAD" again after adding more revisions to the
474 trunk, you may get overlaps for the text you have already merged. It
475 depends on your version of your RCS "merge" command (actually the "co
476 -j" option, which depends on the version of "diff3" you configured RCS
479 You can merge the difference between any two <tags> using two "-j"
480 options on "update" or "checkout".
482 Identify the two tags on the branch you want to merge from.
484 cvs update -j <tag1> -j <tag2> {optional files}
486 This step assumes you were careful about tagging milestones. You can
487 use this technique for any two <tags> on the same branch, even the
488 trunk. It is also possible to use tags on different branches, but
489 you'll have to ponder the meaning of the difference between those two
492 In place of one of the <tags>, you can use a <branch_tag> to refer to
493 the latest revision on that branch. See 4C.11 and 4C.3 for info on
496 Merges can also be performed by handing RCS revisions to the '-j'
497 options, but since revision numbers aren't the same in all files,
498 merging by number is normally limited to one file. Sets of files with
499 the exact same trees of branches and revision numbers would work too,
500 but that's a rare situation.
502 To "take" revisions from other branches instead of merging them, see
505 A way to gain the effect of merging the main to the branch is to
506 merge the branch into the main using the normal
508 cvs update -A {optional files}
509 cvs update -j <branch_tag> {optional files}
511 cvs tag -F -b <same_branch_tag> {optional files}
517 This also works, but is probably not officially supported:
519 cvs update -j N {optional files}
521 where N is a number. This will merge all the changes from the branch
522 point up to the highest revision on the main branch starting with N.
523 For example, if your highest trunk revision is 1.52, you can use this
524 to grab revisions from the trunk:
526 cvs update -j 1 {optional files}
528 Another example: Say you have a branch point at rev 1.2 for a branch
529 named "BR1" and trunk revisions 1.3, 1.4, 2.1, 2.2, 2.3, 3.1, 3.2.
532 cvs update -j 1 {optional files}
534 will merge the changes from 1.2 to 1.4
536 cvs update -j 2 {optional files}
538 will merge the changes from 1.2 to 2.3
540 cvs update -j 3 {optional files}
542 will merge the changes from 1.2 to 3.2, which in this example, is
543 equivalent to the use of "-j HEAD" in part A above.
545 The intuitive (at least to me):
547 cvs up -j MAIN (or TRUNK) {optional files}
549 doesn't work. If the trunk (i.e. "main branch") had an implicit branch
550 named "MAIN", you could use:
552 cvs up -j MAIN:10/26 -j MAIN:now {optional files}
554 and refer to date-stamped revisions on the trunk using the
555 <branch_tag>:<date> support that works on other branches.
557 You might also think you could place an explicit tag on branch 1 (or
558 higher) (e.g. MAINHACK:1) and use it in place of the implicit "MAIN",
559 but I haven't found the right combination.
561 [[If you find working techniques, I'll add them here.]]
563 Last modified: _6/13/1997_
565 8. How do I merge onto the Main Branch a file that exists only on a branch
566 other than the Main Branch? (i.e. it is in the Attic)
568 For how such a file can exist, see 3A.2 and 3A.3.
570 For how to avoid creating such a file, see 3A.5.
572 Though you might think that the "update -j" command could perform the
573 "merge" of a file from the side branch to the Main Branch, it isn't
574 (yet) smart enough. Unfortunately, there is no single CVS command to
575 do this -- it takes three steps:
577 To move something onto the Main Branch from the Attic, you have to
578 physically move the file from the Attic to the main Repository
579 directory associated with your working directory.
581 It is exactly like resurrecting a removed file. See 3L.4
583 I use something like this: (csh-like syntax)
585 set repos = `cat ./CVS/Repository` mv $repos/Attic/filename,v
588 (If you use relative paths in your Repository files, that first line
589 becomes: set repos = $CVSROOT/`cat ./CVS/Repository`)
591 Now that the file is physically in the right place within the
592 Repository, "update -A" will make it appear in your working directory
593 on the Main Branch. Do that now.
595 You now have a choice. The act of physically moving the file has
596 fused together the <branch_tag> branch and the Main Branch for this
597 file. You can continue that way, making changes along the RCS Main
598 Branch which CVS will (for this type of file only) treat as both the
599 Main Branch and the <branch_tag> branch.
601 The other choice, which I would suggest, is to re-tag the file with
602 <branch_tag>, restoring a normal-looking magic branch tag to the file:
604 cvs tag -F -b <branch_tag> <file>
606 After you have done the above, you can run "update -A" or "update -r
607 <branch_tag>" to resume whatever you were doing before you started
610 Caveat: The final result is a file whose revision tree doesn't look
611 like it was ever on any branch but the Main Branch until the above
612 "tag -F -b" command was executed. CVS and RCS have no way of saving
613 the history of the actions you have just performed.
615 Last modified: _6/13/1997_
617 9. How do I know what branch I'm (working) on?
622 and look at the "Sticky Tag" field for each file. If:
624 The *same* tag is on *every* file in your working tree, *and*
626 That tag matches the contents of the ./CVS/Tag file, *and*
628 That tag is a branch tag,
630 then you know what branch you are working on. You can get sticky Tag
631 information directly from the ./CVS/Entries file instead of "cvs
634 If all the sticky Tags don't agree, then your directory is temporarily
635 inconsistent. This is a feature allowing you to make changes (or
636 perform merges) to individual files on multiple branches without
637 checking out the whole directory.
639 The sticky Tag on each file in the ./CVS/Entries file (as displayed by
640 the "status" command) indicates what branch the working file is on.
641 New files are added to the Tag stored in ./CVS/Tag.
643 To force your entire working directory onto the same branch, type:
645 cvs update -r <branch_tag>
647 Last modified: _6/13/1997_
649 10. Do I really have to know the name of the branch I'm working on?
651 If a developer can't be relied on to know what branch of development
652 to work on, then either the developer's manager isn't planning
653 branches properly or the developer has serious problems.
655 I have found that one of the hardest concepts to get across to
656 developers (and some managers) is that "a branch in development" (as
657 opposed to the use of RCS branches to support some other scheme) is a
658 heavyweight act. Every time you create a real branch in development,
659 you must spawn a set of managerial procedures and a schedule by which
660 you plan to merge each branch into each other branch. Unless you plan
661 to keep it simple and collapse (by merging and forgetting) branches
662 quickly, they are not to be created lightly.
664 In other words, if you don't regularly attend group meetings in which
665 the branch to be worked on is a major topic of discussion, then the
666 group is not managing branches properly.
668 We created a couple major branches a few months ago and even the
669 customer service people refer to the "XYZ branch" as a shorthand for
670 "continuing development on the XYZ project".
672 Last modified: _6/13/1997_
674 11. How do I refer to the revision where I branched so I can see what
675 changed since the Branch Point on another branch?
677 Given the current <branch_tag> format, there is no direct way to refer
678 to the branch point, which is more useful in many ways than referring
679 to the branch, which always refers to the latest revision on the
682 When CVS adds a branch tag, it attaches an RCS symbol to a
683 non-existent revision number containing the revision number of the
684 branch point as a prefix. (See Section 3O, on the "tag" command.) RCS
685 can't use the CVS magic branch tag and many of the CVS commands can't
688 To be certain of your ability to refer to a branch point, you must
689 create a "branch point" tag at the same time as the Branch tag. See
692 Last modified: _6/13/1997_
694 12. Why didn't the command "cvs admin -bBRANCH1 *" create a branch?
696 Because your command creates an RCS branch, not a CVS branch. See the
697 above discussion on branches. RCS branches are used to support CVS
698 branches, but they are not the same. You can't act as if you have
699 direct control over the RCS files.
701 The "admin" command was placed there as a convenience to allow you to
702 execute raw "rcs" commands on the Repository, taking advantage of
703 CVS's ability to find the files in the Repository.
705 But you have to remember that you are using RCS commands on a CVS
706 Repository, which is not generally safe unless you know exactly what
709 For one thing, CVS insists on control of the default branch. It is set
710 either to the Main branch or the Vendor branch depending on whether
711 you have changed the Vendor's code. If you change the default branch,
712 you are monkeying with the internals and you will get unexpected
715 To set your "default CVS branch" to BRANCH1, you must use "checkout"
716 or "update" with the "-r BRANCH1" option. Then you have changed CVS's
717 idea of your "default branch", which has little to do with RCS's
720 Last modified: _6/13/1997_
722 13. Is it possible to set the "default CVS branch" for everyone?
724 No. It doesn't work that way.
726 When using CVS, all administrative information (such as what branch
727 you checked out) is stored in CVS sub-directories, local to the user.
728 There is no global state, other than the description and logging files
729 in the $CVSROOT/CVSROOT directory.
731 You tell "checkout" or "update" what branch you want to check out via
732 the "-r <tag>" option. The default is CVS's "Main Branch".
734 I don't see a problem in *designing* a new way to indicate what branch
735 you get by default, instead of the main one, but that's not how it
738 Last modified: _6/13/1997_
740 14. How do I perform a large merge?
742 Large merges require a bit more planning to be able to track what has
743 happened in the inevitable cases where something goes wrong. No tool
744 can force a "merge" to make perfect sense.
746 Though you can handle the details in many different ways, the two ends
747 of the spectrum of merge techniques are: gonzo and paranoid.
749 The gonzo method assumes that you know everything about your sources
750 so that recovery from failures is "just a matter of typing." You
751 created the branch this way:
753 cvs checkout <module>
755 cvs tag -b <branch_tag>
756 cvs update -r <branch_tag>
758 cvs commit <<== Onto branch
760 Now you want to merge your branch back into the Main branch, you are
761 certain you can make it work, or at least detect all the failures, so
762 you dive in and hack away: (For simplicity, we will assume you are
763 collapsing (i.e. merging and forgetting) a side-branch into the Main
764 branch from your single working directory.)
767 cvs update -j <branch_tag>
768 >>> Edit the 'C' files and remove the overlaps.
769 >>> Edit some more to make it all compile and work.
772 Looks simple. For more details on the output from the "update -j"
773 command, see 3P.2 and 4C.6.
775 Note: You could also checkout a whole new working directory and
776 perform the merge at the same time by replacing the two
777 update commands with these two commands:
779 cvs checkout -j <branch_tag> <module>
782 The paranoid way is more difficult, but it can catch all sorts of
783 problems. You created the branch this way:
785 cvs checkout <module>
787 cvs tag <branch_point_tag>
788 cvs tag -b <branch_tag>
789 cvs update -r <branch_tag>
791 cvs commit <<== Onto branch
793 The extra tag command places a non-branch tag on the Branch Point, an
794 act that makes it easier to do "diffs" later. Now we decide to perform
797 cvs tag <latest_on_branch_tag>
799 *1* cvs diff -r <branch_point_tag> -r <latest_on_branch_tag>
800 >>> *1* shows all the changes on the branch.
801 *2* cvs diff -r <branch_point_tag> -r HEAD
802 >>> *2* shows the changes on the trunk since branching.
803 cvs tag <premerge_tag>
804 cvs update -j <branch_tag>
805 >>> Edit the 'C' files and remove the overlaps.
807 >>> Verify that *3* matches *1*, except for line numbers.
809 cvs tag <just_merge_changes_tag>
810 >>> Edit some more to make it all compile and work.
812 cvs tag <after_merge_cleanup_tag>
814 The reason *3* and *1* match so closely is that they are the
815 differences between two pairs of starting points and ending points
816 after the same data was inserted. If they are significantly different,
817 you will want to figure out why.
819 NOTE: You will have to tell everyone to stay the hell out of the
820 Repository while you do this. If they commit something while you are
821 in the middle of a merge, your job will be much more difficult. If
822 they "update" at the wrong time, their work will be randomized until
823 you finish. It's better to call a halt.
825 See 3H.13 for some more information about dealing with merges after
826 import. The last part of the procedure is applicable to any large
829 Last modified: _6/13/1997_
831 15. Is a Vendor merge any different from a branch merge?
833 No. In most ways, a Vendor branch is exactly the same as any other
834 branch. In a Vendor merge, the data is append to the branch by the
835 "import" command, rather than by hand-editing, but the merge process
838 See the "import" command in section 3H.
840 Last modified: _6/13/1997_
842 16. How do I go back to a previous version of the code on a branch?
847 You can avoid digging into RCS revision numbers (executing "update
848 -r (rev)" on each file) by trying one of these:
850 Use non-branch tags as you normally would. Non-branch tags
851 attach to specific revisions, so a "tag (tag)" command would
852 mark the revisions you have in your working directory, which
853 are on your branch. If you need to retrieve them, use "update
856 Doing this overrides the sticky (branch-tag) attached to your
857 working directory with a non-branch tag, which means you won't
858 be able to commit until you again move forward to the end of
859 the branch with "update -r (branch-tag)".
861 Use the "update -r (branch-tag):(date)" trick.
863 This is almost like using the '-D' option, but it looks for
864 revisions extant on (date) only along the given branch.
866 As in #1, you can't commit to this kind of working area,
867 because it has a sticky date referring to revisions in the
870 [comment from the audience: You are dreaming..
871 this does not work.. try it, you get
872 No such tag: "MYTAG:May 1"
873 or similar. I wish it did because I need it. julian@whistle.com]
876 You can branch a branch.
878 If you add a branch tag to file in a working directory that was
879 checked out on a branch, you will branch the branch. This
880 works just fine, though you'll have to play some games to merge
881 everything back together again. You'll also create 6-part
882 revision numbers. (They'll be 8-part revision numbers if you
883 branch a branch that started out with some unmodified files on
884 the Vendor branch. Think about it. How does revision
885 1.2.4.2.4.2.2.1 grab you?)
888 (fixed formatting, kingdon@cyclic.com)
890 Last modified: _9/8/1997_
892 17. Once I've found the files I want, how do I start changing them? I keep
893 getting warnings about sticky tags.
895 What you probably did was type "cvs update -r <tag>" where <tag> is a
896 non-branch tag. "update" created a sticky tag for a specific revision,
897 not a branch. To start working right there, you have to create a
900 You have two choices.
902 You can do it in place and keep working:
904 cvs tag -b <branch_tag> <<== To tag the current files.
905 cvs update -r <branch_tab> <<== To move onto the branch.
907 You can do it "externally" and create a new working directory:
909 cvs rtag -b -r <tag> <branch_tag> <module>
910 cvs checkout -r <branch_tag> <module>
912 <module> can be a relative path within the Repository.
914 <tag> in the above is the non-branch tag you placed earlier
915 that caused the error in your question. Be warned that
916 if <tag> is not set on all the files (or all the right
917 revisions) you won't get exactly what you wanted.
919 Last modified: _6/13/1997_
921 18. Why do I get the latest files on the branch when I tried to "update -r
924 If "update -r <tag>" always retrieves the latest files on a branch,
925 then <tag> is really a <branch_tag>. A branch tag is supposed to be
926 used to grab a branch to work on. Since you can't modify a file in the
927 middle of a branch, checking out a <branch_tag> will give you the
928 latest revision on the branch.
930 If you want to "checkout" a specific collection of revisions, you must
931 use a "non-branch" tag. See the first part of 4C.16.
933 Last modified: _6/13/1997_
935 19. How can I avoid a merge? I just want to move the latest revision on my
936 working branch directly onto the trunk.
938 There is no direct way to do this using CVS, though the technique is
939 not difficult using shell commands. Here's one way:
941 Move your working directory to the Main Branch.
945 Use "update -p" to grab the latest revision on the branch and write
946 it over your working files. Make sure you don't have an modified files
947 -- you will lose them. The following is in "csh" syntax. Change the
948 wildcard to grab the files you want
950 foreach i (Makefile *.cc *.hh)
951 cvs update -p -r <branch_tag> $i > $i
954 Commit all the working files onto the Main Branch.
956 cvs commit -m 'Moved branch <branch_tag> onto MAIN'
958 You should experiment with the above before blasting everything.
960 Last modified: _6/13/1997_
962 20. How to I avoid merge collisions in the RCS $\Log$ data?
964 In short, you can't. The RCS $\Log$ keyword is handled differently
965 from all other RCS keywords.
967 On the info-cvs mailing list, there is a periodic discussion that goes
970 Question: How do I deal with $\Log$? Answer1: You can't do much with
971 it. Here's how it works. . . Answer2: I've found a limited way to use
972 it. . . Answer3: Get rid of it. $\Log$ is an abomination.
974 I tend to lean toward answer #3. There are only two sets of people who
975 would ever have access to logs stored within sources files, developers
976 and source customers.
980 Log entries within sources files are notoriously incomplete, rushed,
981 poorly phrased and in many cases incorrect, making them useless for
982 debugging or file maintenance. I remember a maxim from "Software
983 Tools" (I believe): "Read the code, not the comments." No managerial
984 order or plan for programmer discipline will affect this in the real
987 Log entries are usually in an unreadable mixture of styles. Many log
988 entries are just plain meaningless. Some are foolish. Some are even
991 "Corrected spelling of misspelling." "Bug fix." "Reversed stupid
992 change in previous revisions." "If Joe could do his job, this would
993 already have worked."
995 Log entries are not managed well by the tools. Any merge can cause
996 conflicts in the $\Log$ data. Branch merges produce incomplete logs.
997 They can be edited into chaos and they are not regenerated. They waste
998 space duplicating information available to the developer with a single
1001 Even if correct when originally entered, as changes are made to the
1002 file, log entries become false over time. Humans are not good at
1003 reading down through a list and remembering only the last change
1004 affecting something. Over time *most* of the log is wrong.
1006 Even if still correct, the log data is almost useless to developers
1007 without the code diffs. If you can get code diffs, you can display the
1010 For source customers the problem is even worse. The last thing you
1011 want to show customers is a hodge-podge of tiny comments about large
1012 changes followed by a series of emergency fixes before delivery. If
1013 you distribute sources, then you should provide documentation, or
1014 changelogs reviewed by people who won't let comments like "Fixed for
1015 stupid customer." out the door.
1017 Conclusion: Though some people would prefer to see in this FAQ
1018 techniques for making the $\Log$ entries the best they can be, I
1019 believe them to be a lost cause. My suggestion is to hunt down, root
1020 out and destroy all occurrences of $\Log$ and the unusable data
1021 attached to it wherever you may find it.
1023 Last modified: _6/13/1997_
1025 21. Why should I trust automatic merges?
1027 Some developers have the feeling that three-way merging doesn't work.
1028 They fear and distrust the way the "update" command automatically
1029 merges committed changes from the Repository into the working file.
1031 Experience has shown that most merges are utterly painless and most of
1032 the rest are easily resolved. The few conflicts that cause headaches
1033 are nearly all due to poor communication between developers, a problem
1034 no source control system can obviate.
1036 Some developers were troubled in the past by flaky Unix software. I
1037 can't say that everything is perfect, but the tools CVS depends on
1038 (RCS and diff, mainly) are fairly solid nowadays. They work.
1040 Since it does seem to work for most of us, the algorithm is unlikely
1041 to change soon. Why not test it on a couple trouble spots and if it
1042 works for you, use it for a while? Then you can make an informed
1045 Last modified: _6/13/1997_
1047 22. How does CVS decide if it can safely perform a merge?
1049 CVS can merge any text file, possibly discovering a conflict and
1050 leaving overlaps for you to edit. Editing the conflict markers out of
1051 the file is a moment's work, but resolving the conflict could take an
1052 arbitrary amount of time. CVS works to determine if it *should* merge,
1055 See 2B.6 for how the merge proceeds.
1057 Last modified: _6/13/1997_
1059 23. After resolving merge conflicts in a file, what if I want to keep my
1060 previous version, and not take any of the branch changes?
1062 If you want to retain your previous version, a version on the MAIN
1063 branch greater than 1.1 (one you committed there), just throw the
1064 merged file away and "cvs update" the file.
1066 You don't need to commit something to remember it. The tags you place
1067 before and after the merge should give all the handles you need to
1068 find various versions. You don't have to create a new version of the
1071 If you want to retain the previous Vendor revision, you can grab a
1072 copy of it using "cvs update -p" and commit it or use the technique
1073 described in 3B.3 to revert back to the Vendor branch.
1075 Last modified: _6/13/1997_
1077 Category: /Advanced_Topics_/Engineering/
1081 1. Where can I find out about Software Engineering?
1083 A couple different people suggested this book:
1085 Software Configuration Management: Coordination for Team Productivity;
1086 Wayne A. Babich; Addison Wesley; 1986; ISBN 0-201-10161-0
1088 A number of others suggested Appendix B of the book "Decline and Fall
1089 of the American Programmer" by Ed Yourdon, called "The Programmer's
1090 Bookshelf". It list 87 books you are expected to have read. Since they
1091 publish many of the books, Prentice-Hall distributes this list as
1092 "Prentice Hall Professional Technical reference PTR-125-AA3.
1094 One interesting item from the Yourdon book: The total number of
1095 professional computer books sold is less than the number of
1096 programmers currently in the United States. It wasn't clear from the
1097 book whether this meant "per year" or not, but it is still
1100 Last modified: _6/13/1997_
1102 2. How do I flexibly arrange the modules file to describe my sources?
1104 An equivalent question might be, "How do I structure my sources?" This
1105 can be a difficult question especially in the areas that are more
1106 political than technical.
1108 Generally you want to think about which pieces of your system need to
1109 be checked out together, built as one system or tagged as a consistent
1110 whole. You should certainly create module names that correspond to
1111 complete, buildable collections that you would tag and release as one
1112 "product". It is also convenient to create module names for small
1113 sections of the Repository containing files that will all be worked on
1114 at the same time by the same person or group.
1116 Once you have defined the structure of your work, you can usually see
1117 how to lay it out in a Repository. After that the modules file is
1118 easy. You set up module names and aliases to match what you need to
1119 check out by name. If you like relative directories, it is possible,
1120 but not recommended, to work completely without a modules file. See
1121 1D.11 and 2C.7 for some info about the modules file.
1123 Here are a few types of modules. You should experiment to see what
1124 kind of structure each of these produces. They all have different
1127 Connected projects in one group with two separate helper
1128 directories. The helper directories can contain build tools, header
1129 files, libraries, or whatever you like.
1131 These are all aliases that checkout relative pathnames. The equivalent
1132 results could be produced by placing the selected relative pathnames
1133 on the "cvs checkout" command line.
1138 pr12 -a P1 P2 HELPERS
1139 pr13 -a P1 P3 HELPERS
1140 pr23 -a P2 P3 HELPERS
1145 HELPERS -a group1/helper1 group1/helper2 MAKEFILE
1146 MAKEFILE -a group1/Makefile
1148 Actual Repository directory structure: (from $CVSROOT down)
1150 group1/ Makefile The top level Makefile. helper1/ helper2/ Helper
1151 files and dirs proj1/ Files and dirs proj2/ Files and dirs proj3/
1154 "checkout group1" produces a duplicate of the above. "checkout projX"
1155 produces all but "projY" and "projZ". "checkout projXY" produces all
1158 Here is the exact same set of module names describing the same
1159 Repository layout using module names (and aliases containing module
1160 names) instead of merely aliases for relative pathnames.
1162 There is one difference in the result. The name of the top level
1163 directory in the checked out working tree will match the "module" name
1164 (e.g. pr1) instead of always being "group1" as it was in the first
1167 pr1 group1 proj1 &HELPERS
1168 pr2 group1 proj2 &HELPERS
1169 pr3 group1 proj3 &HELPERS
1170 pr12 group1 proj1 proj2 &HELPERS
1171 pr13 group1 proj1 proj3 &HELPERS
1172 pr23 group1 proj2 proj3 &HELPERS
1174 HELPERS -a helper1 helper2 group1-Makefile
1175 helper1 group1/helper1
1176 helper2 group1/helper2
1177 group1-Makefile -d . group1 Makefile
1179 The above line (with the -d in it) says that when the module named
1180 "group1-Makefile" is checked out, the file named Makefile file will be
1181 found in a directory named $CVSROOT/group1 and will be checked out
1182 into a directory named '.', which obviously already exists.
1184 The & references say to interpret those pathnames relative to the
1185 directory where the whole module is stored. For the "pr1" module, that
1186 directory is "group1", so the &HELPERS reference winds up placing
1187 Makefile in '.' relative to "group1".
1189 A short one containing the basic "module" actions:
1191 m1 head/path file1 dir2 file3 dir4 file5
1193 When checked out, a directory named "m1" appears in your current
1194 directory. Elements named file1, dir2, file3, dir4, and file5 appear
1195 in it. They were originally taken as relative paths from
1198 Here's another way to construct a working directory out of pieces of
1201 projX projX Makefile &projX_inc &projX_src &projX_doc
1203 # The first line selects a single file within projX, plus
1204 # the contents of three other modules. Those three other
1205 # modules rename their directories.
1207 projX_inc -d include projX/inc projX_src -d source projX/src projX_doc
1208 -d documentation projX/doc
1210 A Unix tree. This is similar to what CVS was developed for and the
1211 way I have used it for years.
1218 usr-bin unix/usr.bin
1220 # Subdirs of top level dirs. (tiny subset)
1225 # Programs without subdirs. (tiny subset)
1226 cat unix/bin Makefile cat.c
1227 uniq unix/usr.bin Makefile uniq.c
1232 public localsrc/public
1236 cvs localsrc/gnu/cvs
1237 emacs localsrc/gnu/emacs
1238 rcs localsrc/gnu/rcs
1239 btoa localsrc/public/btoa
1240 tcsh localsrc/public/tcsh
1242 # X11 related items.
1243 tvtwm localsrc/X11/contrib/tvtwm
1245 "unix" was checked out and built from the top down, using a set of
1246 Makefiles that knew about the whole structure. "localsrc" was kept
1247 checked out in /usr/local/src.
1249 At any time I could run "checkout ls" or "checkout cat" and get a
1250 simple directory with only that tool in it, plus a subset Makefile
1251 that knew how to build that tool against the installed (or alternate,
1252 via environment variables) headers and libraries.
1254 I found it very handy to be able to run "ls" and see the three tools I
1255 was porting that week.
1257 Last modified: _6/13/1997_
1259 3. Can I have multiple source repositories, one for each project?
1261 Yes, you can have as many Repositories as you like. But each
1262 Repository must be managed separately, creating additional work.
1264 Question 4A.1 provides a short description of setting up a single
1265 Repository. A few additional considerations:
1267 It is a good idea to start by creating a single Repository and split
1268 it up (or create additional Repositories) only if you believe it is
1269 really necessary. I would only create a new Repository if the data is
1270 completely disconnected from the rest of the main Repository.
1272 If there is a lot of overlap among the developers working on the
1273 collections of files you want to place in different Repositories, or
1274 if there is any connection between those collections, I would go out
1275 of my way to create a single Repository. It is much easier to manage.
1277 Disk space should not be a factor since you can build up a
1278 Repository using symbolic links and/or remote mounts.
1280 Each Repository is completely distinct. You can't check out modules
1281 from different Repositories at the same time. A better way of looking
1282 at it is that if you *can* check out two modules or directories with a
1283 single "checkout" command (without contortions or explicit absolute
1284 pathnames), then they are in the same Repository.
1286 To "checkout" modules from multiple Repositories, you must use the
1287 "cvs -d" option on all CVS commands or alter your $CVSROOT variable
1288 when you change focus to another Repository. If you work with multiple
1289 Repositories, it is a good idea to configure CVS to use absolute
1290 pathnames in the ./CVS/Repository file, since most commands (other
1291 than "checkout") will use that file rather than $CVSROOT.
1293 If you configure CVS to use relative pathnames in your
1294 ./CVS/Repository files, you must always be careful to set your
1295 $CVSROOT properly or you will get unexpected results.
1297 If you have two modules or directories by the same name at the same
1298 relative path inside two different Repositories, you are asking for
1299 disaster. You could unexpectedly update a directory with completely
1300 unrelated files. This is not a fanciful example -- a Repository is
1301 occasionally duplicated for release purposes in which case *all* the
1302 paths in the two Repositories are the same.
1304 Last modified: _6/13/1997_
1306 4. Who should administer the Repository and manage the modules file?
1308 This is a "management style" question. In large or traditional groups,
1309 the CVS procedures are warped to conform to local conventions. In
1310 small groups, in groups with strong personalities or on new projects
1311 the choice of source control procedures can help create some of the
1312 working environment. Here is a taxonomy of environments I have worked
1313 in or helped set up:
1317 A small number of competent developers working on a medium size
1318 project. We all got along and we all respected each other (at least
1319 technically). Anyone edited anything.
1321 Modules and Repository admin was mostly left to me. I never found a
1322 problem in minor changes made by anyone else.
1326 A large number of experienced developers sprinkled with wackos. Many
1327 of the developers didn't want to deal with any kind of source control.
1328 They wanted a full-service source control system that caused them zero
1331 I learned "big stick" diplomacy here. There was a small number of
1332 "designated" (by me) people who were allowed to do *anything* other
1333 than "update" and "commit". Even "checkouts" were controlled. This is
1334 where I found "history" and "release" the most useful.
1338 A small number of developers who wanted me to "help", but who didn't
1339 want to deal with anything other than their favorite algorithms.
1341 I didn't have the time to baby-sit this group, so I designated one of
1342 them to be my official contact and made him do it all. He felt sullied
1343 by the requirement to pay attention to anything other than his pet
1344 coding projects, but enjoyed the "status" of being the only one who
1345 could touch the control files without my kicking the chair out from
1350 A huge number of developers of covering the whole spectrum of
1351 competence and experience split into 20 groups, none of which
1352 cooperated with the others, working on 57 different projects, most of
1353 which didn't inter-operate.
1355 Managing it in any coherent way was not my responsibility (and beyond
1356 my tolerance for chaos). Too many people. So I privately designated a
1357 person in each group to be the contact and kept watch on the
1358 Repository activity. When something went wrong, I notified the contact
1359 for the group and told him what was happening and *he* kept his troops
1360 in line. They were tougher with their own group that I would have
1363 Eventually only a few people were willing to touch the control files,
1364 since they were flamed from all directions if they screwed up.
1368 In a medium group of really *serious*, and seriously overworked,
1369 people, someone else was designated the "master". I convinced the
1370 master I knew what I was doing and went on my way.
1372 No one else in the world was allowed to touch anything.
1376 In a large amorphous group of beginners, experts and clowns, over whom
1377 no one had official control, I was forced to employ a group of
1378 relative beginners (who became experts rather quickly) to police the
1379 world. The ultimate in locking the barn after the horse was stolen, we
1380 kept Chaos from destroying us only by use of superior firepower.
1382 My choice, if allowed, is to let anyone touch anything. I keep backups
1383 of important items and let people know individually whether I want
1384 them to touch things or not. If someone on my "no touch" list touches
1385 and succeeds, they are allowed more slack. If they screw up after
1386 being warned, their screwup becomes public. After a few months, I
1387 usually have no trouble keeping the world running smoothly, at least
1388 from my (and CVS's) perspective.
1390 Last modified: _6/13/1997_
1392 5. Isn't disk space a big factor? CVS copies files out of the Repository,
1393 duplicating everything.
1395 Everyone knows that disk space is getting cheaper. How do we reconcile
1396 this with the equally well-known problem that *all* disk is *always*
1399 In my opinion, the main reason disk space will never be an unlimited
1400 resource is that it is the major variable in organizational time/space
1401 tradeoffs. It isn't a problem of waste or an aspect of Murphy's law,
1402 as some claim it is, but rather a direct consequence of good
1403 management. Disk space is, and will always be, a limited resource.
1405 First, the cost of *deploying* that disk is not dropping as fast as
1406 the cost of the storage medium. The cost of machines to hold the disks
1407 and the networks to connect them are dropping more slowly than disk
1408 media. And the cost of the human time necessary to manage the
1409 machines, networks, disks, and the developers using them, is not
1410 dropping at all. The cost of human time continues to rise.
1412 If management decides that expensive human time can be saved by using
1413 all that new disk space to keep the last three releases online, then
1414 that's what it will be used for. If each release takes up a Gigabyte
1415 and you support 30 platforms, a simple time-saving suggestion has just
1416 grabbed 100 Gigabytes of disk space. And we've ignored the potential
1417 disk storage needed to support "better Customer Service", another
1420 Even at 30 cents per Megabyte (next year's price), you've just used up
1421 $30,000 of disk space. And that doesn't count the computers, tape
1422 drives and humans necessary to maintain and deploy all of it. Spending
1423 money to save time has its own overhead, too.
1425 Binaries are getting bigger. Graphics and data collection devices can
1426 eat up any amount of disk. There are more tools available, more
1427 libraries, more raw data than you can ever store. My home computer has
1428 a Gigabyte of disk on it. It could easily handle 30.
1430 The "economy" of disk storage media will never remove the need to
1433 So, here's an un-reviewed suggestion originally from Graydon Dodson
1434 <grdodson@lexmark.com>, which I've altered and edited heavily.
1436 - Keep a directory where the whole tree is checked out. (It might be
1437 built and tested once in a while to make sure it is worth linking to,
1438 but that doesn't affect the source control aspect of this procedure).
1439 Let's call it /master/build.
1441 - Write a tool that creates a tree of directories (like the X11
1442 "lndir" command) filled with links to the checked out files in the
1445 This tool should also provide real copies of, not symlinks to, all the
1446 files within the CVS administrative directories.
1448 - You could also provide a way for the tool to take a list of whole
1449 directories that you will never change, for which it would create a
1450 single symlink to the directory and not a subtree of symlinks to
1451 files. Or you could rm -r pieces of the resulting working directory
1452 yourself and replace it with links.
1454 - If you want to edit a file, you have to grab a real copy and keep it
1455 until your revision shows up in the /master/build tree. I'd create a
1456 script to do this: cvsgrab <file>
1461 echo "file $f is not a symlink"
1465 set rev = `grep "^/$f/" CVS/Entries | awk -F/ '{print $3}'`
1466 cvs update -p -r $rev $f > $f
1468 You can't do a plain "cvs update" since that would grab newer
1469 revisions from the Repository, not the revision you wanted to start
1470 with. After the file is no longer a symlink, you can work normally.
1471 You'll have to run "update" before "commit" anyway if there are newer
1474 - Presumably there would also be a tool to traverse the link tree and
1475 revert it to links if there are no modified files and/or if all the
1476 real files match the revision of the /master/build tree.
1478 - To avoid confusing CVS when the /master/build revisions are updated
1479 but your CVS/Entries files is not, CVS would have to change to handle
1480 symlinks. It currently causes problems with this scenario:
1482 ./<file> is a symlink.
1484 ./CVS/Entries says you are revision 1.2.
1486 The corresponding CVS/Entries file in /master/build says the latest
1489 cvs update <file> shows a 'C' conflict flag.
1491 Last modified: _6/13/1997_
1493 Category: /Advanced_Topics_/Installing_CVS/
1497 1. What do I have to do before I install CVS?
1499 You must decide where to set up a Repository.
1501 Though you can construct a Repository tree structure using links and
1502 mount points, there must be a single copy of each real file across
1503 your entire organization. You may not "rdist" files and expect to edit
1506 CVS does not support a truly distributed Repository. You can have
1507 multiple Repositories, but each one must be mounted (not copied or
1508 "rdist"ed) from a single place onto all machines where it will be
1511 Initially, a Repository takes about same amount of disk space as the
1512 sources you want to put into it, plus a bit of overhead for the RCS
1515 See Section 4B. For multiple Repositories, see 4G.3
1517 You need a directory in everyone's $PATH variable where you can
1518 install all the executables. /usr/local/bin is a common place.
1520 You need some helper tools besides CVS such as "RCS" and a good set
1521 of "diff" and "diff3" programs. See 1B.4 for suggestions.
1523 Read the README, INSTALL and ChangeLog files to see what you are
1526 Though you can probably muddle along without it, you should appoint
1527 one or more "Repository Administrators" who will be responsible for
1528 maintaining the Repository structure, administrative files and the
1529 "modules" interface.
1531 Someone at your site should probably be on the info-cvs mailing list.
1534 Last modified: _6/13/1997_
1536 2. How do I configure the CVS programs?
1538 You should certainly start by reading the README file, the INSTALL
1539 files and possibly the ChangeLogs in each directory, the Makefile.in
1540 files and the "cvsinit.sh" program.
1542 Execute the ./configure command.
1546 After running "make" you might try running the "sanity.sh" script:
1547 ./src/sanity.sh `pwd`/src/cvs
1549 It writes into /tmp/cvs-sanity by default.
1551 Finish reading the INSTALL file and test out the system.
1553 Last modified: _6/13/1997_
1555 3. What do I have to install?
1557 Install the "cvs" executable and "mkmodules" from the CVS sources.
1558 The man page is useful too. If you plan to report bugs, you should
1559 also install "cvsbug".
1561 Set your $CVSROOT environment variable and create the Repository
1562 (which you planned out in 4A.1) with the "cvsinit" command at the top
1565 You'll need to edit the Repository control files created by
1568 Install any helper programs mentioned in the modules file.
1570 Last modified: _6/13/1997_
1572 4. How do I work around the merge problems in GNU diff version 2.1 or
1575 See 1B.4 If you use recent versions of RCS and "diff", you won't run
1576 into the above. If you do, see 5B.8
1578 Last modified: _6/13/1997_
1580 Category: /Advanced_Topics_/Internal_errors/
1582 " + Internal errors"
1584 1. Explain: "ci error: unexpected EOF in diff output"
1586 RCS versions earlier than 5.5 print the above error when a file does
1587 not end in a newline character. It can be caused by:
1589 - Editing with Emacs and not using "require-final-newline".
1590 - Committing a binary file.
1591 - Filesystem failures (NFS!) that put nulls in your file.
1593 The solution is to upgrade to RCS 5.5 or later. (Of course, this won't
1594 fix filesystem failures. It will merely allow RCS (and therefore CVS)
1595 to handle the file without error.)
1597 Last modified: _6/13/1997_
1599 2. Explain: "RCS file /Repository/module/file.c,v is in use"
1601 This is an RCS error that occurs when its internal lock file has been
1602 left around by an RCS command interrupted by some sort of system
1603 crash, disk failure or SIGKILL signal.
1605 Go into the Repository and look for files with names similar to
1606 "file.c,v", usually starting with ',', '_' or '#'. Make sure they are
1607 really crash remnants and do not belong to transactions in progress --
1608 a recent last-modified timestamp is a good indicator of a live
1609 transaction. Delete them if they are old.
1611 Last modified: _6/13/1997_
1613 3. Explain: "co error, line 2: Missing access list"
1615 This is an error message from RCS Version 3 when it tries to read a
1616 file created by a later version of RCS.
1618 HP decided to "standardize" on an ancient version of RCS some time
1619 ago. You can't use it for CVS. See 4H.6.
1621 Since the error comes from having a later version of RCS than HP
1622 supports, you probably did install the later version but must have
1623 recently changed your $PATH or installed the HP package that has RCS
1626 You should either reconfigure CVS to use absolute pathnames to the
1627 proper versions of the RCS programs that CVS uses, or change your PATH
1628 to look there first. If you haven't installed the latest version of
1629 RCS, you should upgrade. See 1B.4
1631 Last modified: _6/13/1997_
1633 4. Explain: "error: RCS file name `xyz .c' contains white space"
1635 RCS 5.6 doesn't allow white space in filenames. Apparently this
1636 restriction will be removed in RCS 5.7, but CVS may still require that
1637 filenames have no white space in them.
1639 Last modified: _6/13/1997_
1641 5. Explain: cvs checkout: warning: <X> is not (any longer) pertinent
1643 This message occurs in three instances:
1645 When there is an entry in the ./CVS/Entries for file <X> and there
1646 is no RCS file in the Repository to back it up.
1648 If the working file exists, and hasn't changed (determined from the
1649 timestamp) it is removed.
1651 When you try to check out a piece of the Repository with:
1653 cvs checkout some/place/in/repository/tree
1655 and at least the first element of the path (i.e. "some" in the above)
1656 exists, but some part of the rest of it does not.
1658 The checkout command checks the modules file first for the whole path,
1659 then for a prefix of the path as a module name. If it doesn't find
1660 *any* portion of your path in the modules file, it says:
1662 cvs checkout: cannot find module `<module/path>' - ignored
1664 If it finds some set of prefix directories, it prints the message you
1667 In practice this is usually a spelling error.
1669 If the Repository files you are trying to check out or update are
1670 not readable by you, the same problems can occur. Check the
1671 permissions on the files involved.
1673 Last modified: _6/13/1997_
1675 6. Why did a Repository file change from <file>,v to ,<file>,?
1677 This is an RCS problem, since the ,<file>, syntax for file names is
1678 used by RCS and not CVS.
1680 RCS constructs a new <file>,v in a temporary file named ,<file>,
1681 (which doubles as a lock file) then renames it to <file>,v when it is
1682 done. The only way this is reliable is if your system's version of
1683 rename(2) is an atomic, as required by POSIX.
1685 If your system has a non-atomic (and therefore non-POSIX) rename(2)
1686 system call, RCS runs uses an internal version of this algorithm to
1687 approximate the atomic rename:
1689 rm <file>,v; ln ,<file>, <file>,v; rm ,<file>,
1691 If the system crashes, or you lose your NFS connection between the
1692 first "rm", but before the "ln", you can be left only with the
1693 ,<file>, file. If the crash or network failure occurs between the "ln"
1694 and the final "rm", you could be left with a pair of linked names.
1697 - If only the ,<file>, exists, rename it to <file>,v.
1699 - If both ,<file>, and <file>,v exist and are linked, remove the
1702 - If both ,<file>, and <file>,v exist and are separate files, look at
1703 the dates, "diff" them and make your best guess. This sounds like the
1704 remnants of two separate events.
1706 Last modified: _6/13/1997_
1708 Category: /Advanced_Topics_/Other_Systems/
1712 1. I use a NeXT. Is there anything I need to know?
1714 NeXTSTEP 3.0's Interface Builder uses "nib" directories, rather than
1715 the files used in previous revisions. It removes files it doesn't
1716 recognize, making it impossible to place such a directory under CVS --
1717 the CVS admin directory will be removed.
1719 Some time ago, <Bob_Vadnais@pdh.com> posted a palette named CVSPalette
1720 that claimed to resolve this problem. It was intended to preserve the
1721 CVS administrative directories within nib documents (directories) that
1722 Interface Builder usually removes.
1724 CVSPalette is no longer in its announced place:
1726 ftp.cs.orst.edu:/pub/next/submissions
1728 though I did find two other interesting files on ftp.cs.orst.edu:
1730 /software/NeXT/sources/tools/cvs-next-2_1_1.tar.Z
1732 which is a port of CVS 1.3 (along with RCS and diff) and:
1734 /software/NeXT/sources/programming/cvs.postamble-2.4.gz
1736 which appears to be a set of wrappers for CVS commands that claim to
1737 allow you to use CVS effectively (and without need for the "command
1738 line") on a NeXT machine.
1740 [[Anyone know the truth about CVS and NeXT?]]
1742 Last modified: _6/13/1997_
1744 2. I use OS/2 and/or DOS and/or Windows. Is there anything I need to know?
1746 When using a local repository, be sure to specify the local access
1747 method or CVS will interpret the drive letter as a remote host name
1748 due to the : following it:
1750 WRONG: CVSROOT=C:\SRC\CVSROOT
1752 RIGHT: CVSROOT=:local:C:\SRC\CVSROOT
1754 (larry.jones@sdrc.com)
1756 You can share RCS files between Unix and DOS while avoiding the MS-DOS
1757 file name limits by setting your RCSINIT environment variable to
1758 '-x/,v'. New RCS files will be created without the standard ",v"
1759 suffix, though files ending in ",v" will still be found if there is no
1760 matching file in the same directory without the ",v".
1762 Erik van Linstee offers an OS/2 and a DOS port of CVS 1.3 in:
1764 ftp.informatik.tu-muenchen.de:/pub/comp/os/os2/gnu/devtools or
1765 ftp.rrzn.uni-hannover.de:/pub/os2-local
1767 The files are named:
1771 Where the ? stands for the patch level (currently 8) and the b is for
1772 the binaries, the s for the sources.
1774 There are three binaries. An OS/2 only one (32-bit), a DOS only one
1775 (16-bit) and an EMX one that runs on both (32-bit).
1777 There are many differences between the Unix and the DOS versions of
1778 CVS. Read the material that comes with the DOS version before using
1783 Last modified: _9/22/1997_
1785 3. I use SCO Unix. Is there anything I need to know?
1787 On SCO/UNIX 3.2 V2.0 POSIX signals don't work. Unfortunately the
1788 configure program detects POSIXness and configures in the use of POSIX
1789 signals. Workaround : Edit out the check for POSIXness in the
1790 configure script. [[You could also remove all occurrences of
1791 "-DPOSIX=1" from the Makefiles after configure is run. -dgg-]]
1793 SCO/UNIX doesn't understand #!/<some shell> syntax. This breaks the
1794 use of log.pl as it gets invoked by /bin/sh instead of
1795 !#/usr/local/bin/perl. WorkAround : edit log.pl and change it into a
1796 shell script which invokes perl with log.perl (renamed from log.pl) as
1798 Contributed by Joe Drumgoole
1800 Last modified: _6/13/1997_
1802 4. I use AIX. Is there anything I need to know?
1804 The only report on AIX claims to have no trouble using it in concert
1805 with SunOS and IRIX platforms.
1807 Last modified: _6/13/1997_
1809 5. I use IRIX. Is there anything I need to know?
1811 If you see "uid" numbers where you would expect user names, try adding
1812 -lsun to the link line. Without it CVS is unable to retrieve "passwd"
1815 Last modified: _6/13/1997_
1817 6. I use an HP system. Is there anything I need to know?
1819 HP distributes RCS version 3 (a circa 1983 release!) with HP-UX. CVS
1820 does not work with RCS version 3; it requires RCS version 4 or later.
1821 Your best bet is to find the latest version of RCS and install it
1824 HP-UX 8.07 has a serious bug with the mmap system call and NFS files;
1825 the bug can crash the operating system. Make sure that you configure
1826 RCS to avoid mmap by setting has_mmap to 0 in RCS's conf.h. This bug
1827 is fixed in HP-UX 9.
1829 Contributed by Paul Eggert
1831 If using the setgid() trick described in 4D.13, you will have to
1832 create an entry in the /etc/privgroup file to give the group assigned
1833 to the cvs executable setgid permission (see setprivgrp(1m)).
1834 Additionally, if you are restricting "read" access to the Repository
1835 by limiting access to the executable (this requires yet another
1836 group), then you will require that /etc/logingroup exists and is
1837 configured correctly (usually it's just alink to /etc/group).
1839 Contributed by Dale Woolridge
1841 Last modified: _6/13/1997_
1843 7. I use AFS. Is there anything I need to know?
1845 There is a problem with the way CVS performs its locking when the
1846 files are within AFS. When your current PTS id != your uid, the locks
1847 are not deleted. The stat() system call returns the PTS id of the
1848 owner. If that id != your uid, CVS assumes you did not lock it, and
1849 leaves the lock files alone. The next time you try to use it, it
1850 complains that someone has the repository locked.
1852 Contributed by Michael Ganzberger
1854 [[This was against CVS 1.3. Is it still in CVS 1.4?]]
1856 Last modified: _6/13/1997_
1858 8. I use A/UX. Is there anything I need to know?
1862 Last modified: _6/13/1997_
1864 Category: /Advanced_Topics_/Related_Software/
1866 " + Related Software"
1868 1. How do I use CVS under Emacs? Is there an Emacs cvs-mode?
1870 The pcl-cvs package distributed with CVS is an emacs package that
1871 helps with the update/commit process. When you are ready to update,
1872 you use the 'cvs-update' command within emacs. This executes "update"
1873 and fills a cvs-mode buffer with a line for each file that changed.
1874 The most helpful features are: descriptive words for what happened
1875 (i.e. Merged or Conflict rather than 'U' or 'C'), single keys bound to
1876 diffs and commits, and the ability to mark arbitrary groups of files,
1877 possibly from different directories, for commit as a whole.
1879 All the developers in my group that use emacs find pcl-cvs a much
1880 friendlier and more helpful way to update/commit than raw cvs. One vi
1881 user even converted to emacs just to use pcl-cvs.
1883 Contributed by Jeffrey M Loomis
1885 Last modified: _6/13/1997_
1887 2. What is GIC (Graphical Interface to CVS)?
1892 GIC provides a graphical user interface to the Concurrent Version
1893 System (CVS), a powerful revision control system. GIC is
1894 implemented in the Tcl/Tk programming language and is intended to
1895 augment the sometimes cumbersome CVS command line interface.
1897 Note that according to the official GIC page at
1898 http://www.cpsc.ucalgary.ca/redirect/grouplab/projects/gic/
1899 GIC is no longer being maintained and tkCVS is recommended
1902 For more on tkCVS, see http://www.cvshome.org/dev/addontkcvs.html.
1906 Last modified: _9/6/1997_
1910 CAVEMAN is a front end to CVS written in PERL providing a collection
1911 of features desired by the site where it was developed.
1913 - The ability to spread a "project" over multiple Repositories.
1914 - Optional automatic tagging after each commit.
1915 - Additional locking of files.
1916 - Extra before and after program hooks.
1917 - A layer of event logging.
1918 - All sorts of error messages.
1919 - Many changes to the semantics of commands.
1921 It is available via anonymous ftp on ftp.llnl.gov [128.115.54.18] in
1922 gnu/caveman_vX.Y.Z.tar.gz (The numbers X, Y, & Z vary.)
1924 contact Kathleen Dyer kdyer@llnl.gov
1928 [[Does someone want to elaborate?]]
1930 Last modified: _6/13/1997_
1932 Category: /Advanced_Topics_/Setting_up_and_Manag/
1934 " + Setting up and Managing the Repository"
1936 1. What do I do first? How do I create a Repository?
1938 First, install all the programs. (See Section 4A.)
1940 Then create a Repository by executing "cvs -d init". (This works with
1943 Now you can configure your repository by checking out CVSROOT: "cvs -d
1944 checkout CVSROOT". Change into the created directory CVSROOT. Edit the
1945 files you want to edit, and afterwards, commit the changes by typing
1948 You will certainly want to add modules of your own. Edit the "modules"
1949 file and add lines to describe the items you want to "checkout" by
1950 module name. Here's a short list that could be used for storing a
1951 small number of GNU and PD sources:
1956 emacs local/gnu/emacs
1960 pdprog1 local/public/pdprog1
1961 pdprog2 local/public/pdprog2
1968 Last modified: _4/21/1998_
1970 2. What are those files in $CVSROOT/CVSROOT?
1972 There are eight Repository control (or "database") files of interest
1973 in the CVSROOT directory:
1975 modules contains the "modules" database. See 1D.11, 2C.7, 4B.6 and
1976 4B.7 for more details.
1978 commitinfo contains two columns: 1. a regular expression to match
1979 against pathnames within the Repository and
1981 a <command> to execute for matching pathnames.
1983 When you execute "commit", CVS passes the Repository pathname for each
1984 directory (and the files to commit within that directory) to
1985 <command>. If <command> exits with a non-zero status, the commit is
1988 A <command> associated with a pathname of "DEFAULT" is executed if
1989 nothing else matches. Every <command> associated with a pathname of
1990 "ALL" is executed separately.
1992 rcsinfo contains the same first column as commitinfo, but the second
1993 column is a template file for specifying the log entry you are
1994 required to enter for each commit.
1996 "DEFAULT" and "ALL" work the same as in the commitinfo file.
1998 editinfo contains the same two columns as commitinfo, but the
1999 <command> in the second column is intended to do some consistency
2000 checking on the commit log.
2002 "DEFAULT" works as in commitinfo.
2004 loginfo contains the same two columns as commitinfo, but the
2005 <command> is expected to read a log message from its standard input.
2006 The <command> can do anything it wants with the log information, but
2007 normally it is appended to a log file or sent to mailing lists.
2009 "DEFAULT" & "ALL" work the same as in commitinfo.
2011 cvsignore contains "ignore" patterns that are added to the built-in
2012 ignore list. See 2D.10.
2014 checkoutlist contains a list of other files kept under RCS in
2015 $CVSROOT/CVSROOT that should be checked out by mkmodules to provide a
2018 history contains a stream of text records, one for each event that
2019 the "history" command is interested in. Though the contents of the
2020 history file can be read, it is intended to be read and displayed by
2021 the "history" command. This file is the only one in the above list
2022 that is not under RCS.
2024 Last modified: _6/13/1997_
2026 3. Is there any other state stored in the Repository besides in the
2027 $CVSROOT/CVSROOT directory?
2029 Only in the RCS files. The Repository holds exactly two things: the
2030 tree of RCS files (each usually ending in ",v") and the CVSROOT
2031 directory described above.
2033 Last modified: _6/13/1997_
2035 4. How do I put sources into the Repository?
2037 There are three main ways to put files in the Repository:
2039 Use the "import" command described in Section 3H.
2041 This method is the fastest way to put trees of new code into the
2042 Repository and the *only* way to handle source releases from a 3rd
2043 party software vendor.
2045 Use "add" followed by "commit".
2047 This is how to add new files and directories to the Repository, a few
2048 at a time. Directories don't need to be committed.
2050 You can move RCS files directly into the Repository.
2052 You should create a directory hierarchy to hold them, but you can just
2053 move arbitrary ",v" files into the Repository. The only "state" in the
2054 Repository other than within ",v" files is in the required CVSROOT
2055 directory at the top of the Repository.
2057 Last modified: _6/13/1997_
2059 5. What file permissions should I use on (and in) the Repository?
2061 If you are using pserver (password-authenticated access), see below.
2063 If you run a completely open environment (which usually means that you
2064 don't have, or don't want to waste, the time to deal with it):
2066 - Set all directory permissions to 777.
2068 - Have everyone set their umasks to 0.
2070 (BTW, I don't suggest this. I am merely reporting it.)
2072 If you are a normal Unix shop and want to use groups effectively:
2074 - Set all the directory permissions in the Repository to 775.
2076 If you are using a system that handles both System V and BSD
2077 filesystems, you might have to set the permissions to 2775.)
2079 If you are using one of the many recent versions of Unix that don't
2080 allow you to use the full octal mode, then you'll have to type: chmod
2081 u=rwx,g=rwx,o=rx,g+s dir>
2083 - Change all the groups on the directories to match the groups you
2084 want to write to various directories.
2086 - Make sure every user is in the appropriate groups.
2088 - Have everyone set their umask to 002, including root.
2090 If you don't want non-group members to even read the files, do the
2093 - Repository directory permissions to 770. (or 2770)
2097 If you work in an environment where people can't be trusted to set
2098 their "umask" to something reasonable, you might want to set the umask
2101 mv /usr/local/bin/cvs /usr/local/bin/cvs.real
2102 cat > /usr/local/bin/cvs
2104 umask 2 # Or whatever your site standard is.
2105 exec /usr/local/bin/cvs.real ${1+"$@"}
2108 Pserver (Password-Authenticated Access) <blome@de.ibm.com>
2110 The above suggestions are not valid when you use the pserver facility.
2111 Be sure to read and understand the manual section about this (should
2112 be 4.6.something). Above all: do /not/ make the repository and CVSROOT
2113 group writeable. In CVSROOT, make `history´ group or world writeable
2116 I suggest creating one unix group per project group. In the
2117 repository, you would then create one directory for each group, group
2118 writeable. New projects must then be created in these group
2119 directories. If you don't want to say <group>/<project> on
2120 checkout, create a <project> module and point it there.
2122 Last modified: _9/24/1998_
2124 6. How do I structure my Repository?
2126 The Repository holds your software. It can be all interrelated or it
2127 can be a bunch of separately managed directories.
2129 How you break a whole system down into its component parts, while
2130 defining interfaces between them, is one aspect of "Software
2131 Engineering", a discipline that requires the study of dozens of
2132 strange and wonderful areas of the computer and management worlds.
2134 CVS provides a way to keep track of changes to individual files, a way
2135 to "tag" collections of files, and a way to "name" collections of
2136 files and directories. That's all. Everything else is in the way you
2139 In other words, you should structure your Repository to match your
2140 needs, usually tied in with the other tools you use to build, install
2141 and distribute your work. Common needs include the ability to:
2143 - mount (or automount) directories from many places in your
2145 - check out just what you need and no more.
2146 - check out multiple sections in a fixed relation to each other.
2147 - check out large sections to match the assumptions built into your
2148 build system. (Makefiles?)
2150 In my opinion, you should start small and keep everything in one tree,
2151 placing each major sub-system into a separate directory. Later, when
2152 you know what you are doing, you can make it more sophisticated.
2154 Last modified: _6/13/1997_
2156 7. Why would anyone use "modules"? They are too restrictive. I want to be
2157 able to select just the files I want to edit.
2159 Any form of structure is restrictive. If you believe that total chaos
2160 is a viable working paradigm, or if you believe you can keep track of
2161 the interrelations between all portions of your Repository in your
2162 head, then you can do what you please.
2164 If you believe that systems of files require management and structure,
2165 then the "modules" idea is very useful. It is a way to impose a naming
2166 scheme on a tree of files, a naming scheme that can be simpler than a
2167 large list of relative pathnames.
2169 The "modules" file represents a published interface to the Repository
2170 set up by your Repository Administrator. If s/he did a creditable job,
2171 the modules offered will be internally consistent and will smoothly
2172 interact with the rest of your environment.
2174 Last modified: _6/13/1997_
2176 8. How do I rename a file or directory? What are the consequences?
2178 In CVS there is no single "rename" command.
2180 See 2C.4 for the suggested way to rename a file or directory.
2182 The rest of this section covers some of the consequences of renaming.
2184 A "renaming database" has been proposed that would keep track of name
2185 changes so that "update -r <tag>" would continue to work across the
2186 renaming. But as it stands, you have to pick one of the following
2189 Use the technique described in 2C.4. (For each file, duplicate the
2190 file in the Repository, "remove" the old version so it winds up in the
2191 Attic and strip all Tags off the new version.)
2193 - "update -r <tag>" produces the correct files.
2195 - The duplicated revision history can be slightly misleading.
2197 - A plain (i.e. without the "-r <tag>") "checkout" or "update -d" will
2198 create directories "renamed" this way, but you can delete it and a
2199 plain "update" won't bring it back.
2201 Move the files and directories in the Repository to the new names.
2203 - You save the revision history under a different file name.
2205 - You save a little space.
2207 - "update -r <tag>" produces the wrong files or directories.
2209 This is not a good general solution, but if you plan never to look
2210 back (someone may be gaining on you!), it is sometimes a useful
2213 If you are clever with Makefiles, you might be able to rework them to
2214 handle either the new or old names, depending on which ones exist at
2215 the time. Then you can move an old <tag> onto the new, more
2216 sophisticated, revision of the Makefile. (Yes, this changes the
2217 "released" file if <tag> indicates a release. But it is an option.)
2219 - Important Note: If you rename a directory, you must rename the
2220 corresponding directory in every checked-out working directory. At the
2221 same time, you must edit the pathname stored in the ./CVS/Repository
2222 file within each of the moved directories.
2224 The easiest way to move a lot of directories around is to tell
2225 everyone to remove their working directories and check them out again
2228 - The file exists in the working directory and in the ./CVS/Entries
2229 file, but not in the Repository. For the old file, "update" prints:
2231 cvs update: xyz.c is no longer in the repository
2233 and deletes the file. If the file was modified, "update" prints:
2235 cvs update: conflict: xyz.c is modified but no longer in the
2238 and leaves the file alone. In the new directory, you see:
2242 as you would if someone else executed "add" and "commit".
2244 For each file, copy the working file to a new name in the working
2245 directory and use the "cvs remove" to get rid of the old old file and
2246 "cvs add" to add the new one. Since there is no way for CVS to remove
2247 a directory, this only works for files.
2249 - This is what most people think of first. Without a "rename" command,
2250 the remove/add technique seems obvious.
2252 - You lose the connection of your new working file to its past
2255 Last modified: _6/13/1997_
2257 9. What are "Attic" directories?
2259 When you use the "remove" command on a file, CVS doesn't delete the
2260 file, it only registers your desire to delete it.
2262 When you "commit" a removed file, CVS moves the Repository's matching
2263 RCS file into a sub-directory named "Attic" within the Repository.
2265 Attic files are examined when the '-r' or '-D' option is used on
2266 "checkout" or "update". If the specified revision, tag or date matches
2267 one on a file in the Attic, that file is checked out with the others.
2269 You can think of the Attic as a sort of dead branch, which is only
2270 looked at when you refer to a <tag> or <date>.
2272 Last modified: _6/13/1997_
2274 10. Is it OK to remove anything from the Repository?
2276 In general, removing anything from the Repository is a bad idea. The
2277 information in a deleted object is lost forever. There are many ways
2278 to skip over files, directories and revisions without deleting them.
2280 Here are some of the consequences of removing the following things
2281 stored in the Repository:
2283 CVSROOT files (Repository control files)
2285 The Repository will work without any of them, but you should
2286 understand what you are losing by deleting them. See 4B.2.
2290 The only way to remove revisions is to use the "admin -o" command (or
2291 the equivalent RCS command "rcs -o").
2293 They are lost forever. Any tags formerly attached to deleted revisions
2294 are now pointing into the Phantom Zone. You'll need to contact Jor-el
2299 You should not remove a file unless you truly never want to see it
2300 again. If you want to be able to check out an old revision of this
2301 file, use "cvs remove" instead.
2305 Tags take up little space and you can't recover from deleting them. If
2306 you depend on tags for releases you will lose vital information.
2310 There is no Attic for directories, so the only way to remove them is
2311 to use "rm -r". They are gone forever.
2313 If you delete (or move) a directory, all checked-out versions of that
2314 directory will cause CVS to halt. You'll have to visit each
2315 checked-out directory and remove the matching working directory by
2320 The "remove" command sends files to the Attic. To really delete them,
2321 you have to go into the Attic and use "rm".
2323 If a file in the Attic has a Tag on it that you might ever want to
2324 check out again, you probably don't want to delete it.
2326 Lock files (named: "#cvs.[wr]fl.<pid>")
2328 These are lock files. If you are getting "lock" errors and the dates
2329 on the lock files indicate that they are old, you can delete them.
2331 Deleting lock files still in use by a CVS process might produce
2334 Last modified: _6/13/1997_
2336 11. Can I convert to CVS from RCS without losing my revision history?
2338 Yes, you can simply move (or copy) your RCS files into a directory
2339 within the Repository, check out that directory and start working.
2341 Last modified: _6/13/1997_
2343 12. Can I move RCS files with branches in them into the Repository?
2345 Yes, but they may not work if you created branches in a way that
2346 conflicts with CVS's assumptions:
2348 You can't use .0. branches. (They are reserved for "Magic" branch
2351 If you use branch 1.1.1, you can't use the Vendor branch.
2353 You can use other RCS branches under CVS. There is no need to create
2354 "magic" branch tags because the physical branch already exists.
2356 Last modified: _6/13/1997_
2358 13. Can I use raw RCS commands on the Repository?
2360 You can use raw rcs commands directly on the Repository if you take a
2361 little care. The Repository itself contains no "CVS state" (as opposed
2362 to RCS revision histories) outside the CVSROOT directory.
2364 But using raw RCS commands to change branches, tags or other things
2365 that CVS depends on may render the files unusable.
2367 See 4D.7 on RCS/CVS sharing of the Repository and Section 3B on the
2370 Last modified: _6/13/1997_
2372 14. How do I convert from SCCS to RCS?
2374 You'll have to execute something like "sccs2rcs" (in the CVS contrib
2375 directory) on every file. Then you can move the resulting RCS files
2376 into the Repository as described above.
2378 Last modified: _6/13/1997_
2380 15. How do I limit access to the Repository?
2382 There are all sorts of ways to restrict access to Repository files,
2383 none of which are hooked directly into CVS.
2385 Techniques for limiting access include:
2387 Training, management and good backups.
2389 The best form of Repository control is a combination of:
2391 - A reliable backup scheme (verify it!)
2392 - Enough training to ensure your developers are competent and
2393 knowledgeable about all areas of your sources.
2394 - Effective management of the boundaries and grey areas.
2396 In many cases, technical solutions to "security" problems are
2397 inadequate. You should first try to avoid them.
2399 Personal Opinion: In an environment where "unknowns" are allowed to
2400 touch important sources the "owner" of the CVS Repository must be a
2401 large, loud, vigorous lout with a well-balanced truncheon and the
2402 right to use it. Don't underestimate the effectiveness of letting
2403 everyone know they will be strapped into the stocks on the Town Common
2404 and pelted with vegetables if they break something they don't
2405 understand without first asking the experts.
2407 Set Unix groups and permissions. See 4B.5. You can set different
2408 owners, groups and permissions for each sub-directory within the
2409 Repository if that helps.
2411 Catch invocations of "commit" by defining pre-commit programs in the
2412 "commitinfo" file. This is fairly powerful, since it can block commits
2413 based on anything you can program. Take a look at the programs in the
2414 "contrib" directory of the CVS source tree.
2416 Use multiple Repositories, each with its own protection scheme. If
2417 you use NFS (or AFS) you can even use "export" restrictions to various
2418 groups of machines to keep (for example) the Engineering Repository
2419 off the Customer Service machines.
2421 Try the "setgid" trick described in 4D.13.
2423 Try to use the RCS access control lists, though I don't think CVS
2424 will handle them cleanly.
2426 Edit the source code to CVS to add your own access control.
2428 Last modified: _6/13/1997_
2430 16. What are the Repository Administrator's responsibilities?
2432 Generally, the Administrator should set "policy", create the
2433 Repository and monitor its size and control files.
2435 Some specific responsibilities include:
2437 Examining the Repository once in a while to clean up:
2439 Trash files left by misguided developers who mistake the Repository
2440 for a working directory.
2442 Non-RCS files. Other than the files CVS needs in the
2443 $CVSROOT/CVSROOT directory, every file in the Repository should be an
2446 Lock files (both CVS '#*' and RCS ',*' files) left around after
2449 Wrong permissions, groups and ownerships.
2451 Locked files. (RCS locks, that is.)
2453 Attic files that should never have been under CVS at all. Don't
2454 blindly delete files from Attic directories -- they were mostly put
2455 there (via the "cvs remove") for a reason. Files that should be
2456 deleted are binary files (e.g. '*.o', 'core', executables) that were
2457 mistakenly inserted by "import -I !".
2459 Maintaining the modules file.
2461 Storing site-specific ignore patterns in the
2462 $CVSROOT/CVSROOT/cvsignore file.
2464 Storing the names of non-standard CVSROOT files (See 4B.2) in the
2465 $CVSROOT/CVSROOT/checkoutlist
2467 Maintaining the other Repository control files: commitinfo, loginfo,
2468 rcsinfo and editinfo.
2470 Pruning the history file every once in a while. (Try the
2471 "cln_hist.pl" script in the "contrib" directory.)
2473 Staying aware of developments on the info-cvs mailing list and what
2474 is available in the FTP and WWW archives.
2476 Running "ps ax" once in a while and kill off any "update" programs
2477 not running as "root". It is too easy to leave the "cvs" off the front
2478 of the "cvs update" command.
2480 Executing monitor programs to check the internal consistency of the
2481 Repository files. Ideas:
2483 Files that have a default RCS branch that is not 1.1.1 (From an
2484 abuse of "admin -b".)
2486 Files that have only Revisions 1.1 and 1.1.1.1, with a default
2487 branch of "MAIN". (From an abuse of "admin -o".)
2489 Existing branch tags and various branch consistency checks.
2491 Last modified: _6/13/1997_
2493 17. How do I move the whole Repository?
2495 Copy or move the tree. (On Unix systems, a set of piped "tar" commands
2496 works great. If the Repository does not contain any symlinks, which it
2497 normally doesn't, you can also use "cp -r".)
2499 If you can avoid changing $CVSROOT (i.e. the "logical" pathname of the
2500 Repository) by replacing the old location with a symbolic link to the
2501 new location, you don't have to do anything else.
2503 (You could also mount the new location on top of the old location if
2504 you are using NFS or some other filesystem that allows it.)
2506 If you must change $CVSROOT, you must also tell everyone to change the
2507 CVSROOT environment variable in all running shells and in any personal
2508 configuration files ('.' files on Unix) where it is set.
2510 The Repository itself contains no references to its own name, except
2511 possibly in some of the files in the CVSROOT directory. If your
2512 modules (or loginfo, commitinfo, etc.) file mentions helper programs
2513 directly in the Repository, you'll have to change the pathnames to
2514 point to the new Repository location.
2516 The main changes you'll have to make are to all the CVS administrative
2517 files (./CVS/Repository and ./CVS/Root) in every working directory
2518 ever checked out from the previous location of the Repository you just
2521 You have three choices:
2523 If all ./CVS/Repository files in all working directories contain
2524 relative pathnames, you don't have to do anything else.
2526 Have everyone "release" or delete their working directories (after
2527 committing, or just saving, their work) and check them all out again
2528 from the new Repository after the move.
2530 Use "find . ( -name Repository -o -name Root )" and a PERL or shell
2531 script to run through all the ./CVS/Repository and ./CVS/Root files
2532 and edit the values in the files.
2534 Last modified: _6/13/1997_
2536 18. How do I change permissions on a file in the Repository by using a CVS
2537 command? (i.e. without using "chmod 777 $CVSROOT/dir/file")
2539 When you first "import" or "add"/"commit" a file, the read and execute
2540 bits on the Repository file are inherited from the original source
2541 file, while the write bits on the Repository file are are turned off.
2542 This is a standard RCS action.
2544 After that, there is no way to alter the permissions on a file in the
2545 Repository using CVS (or RCS) commands. You have to change the
2546 permissions on both your working file and on the Repository file from
2547 which it was retrieved.
2549 Whenever you "checkout" the file or retrieve a new revision via
2550 "update" (or after a "commit"), your working file is set to match the
2551 permissions of the Repository file, minus any "umask" bits you have
2554 Last modified: _6/13/1997_
2556 Category: /Advanced_Topics_/Tricks_of_the_Trade/
2558 " + Tricks of the Trade"
2560 1. How can you even check in binary files, let alone allow CVS to do its
2561 auto-merge trick on them?
2564 First of all, if you want to use binary files, you should get RCS 5.7
2565 and CVS 1.9 or later (earlier versions had some support, but there have been
2566 bug fixes). Secondly, follow the instructions for installing RCS very
2567 carefully (it is easy to get it installed so it works for everything
2568 except binary files).
2570 Then, specify 'cvs add -kb' instead of just 'cvs add' to add a binary
2571 file. If you want to set an existing file to binary, run 'cvs admin
2572 -kb' (and then check in a new copy of the file). Note that old
2573 versions of CVS used -ko instead of -kb for binary files, so if you
2574 see a reference to -ko in the context of binary files, you should
2577 Of course when 'cvs update' finds that a merge is needed, it can't
2578 do this for binary files the same way as for text files. With the
2579 latest versions (e.g. CVS 1.9.14), it should be able to give you both
2580 versions and let you merge manually. Another approach is to
2581 run 'cvs admin -l' to lock files, as described in
2582 "How can I lock files while I'm working on them the way RCS does?"
2583 elsewhere in this FAQ. See also
2584 "Is there any way to import binary files?" and
2585 "How do I "add" a binary file?" elsewhere in this FAQ.
2589 Last modified: _9/6/1997_
2591 2. Can I edit the RCS (",v") files in the Repository?
2593 Yes, but be very careful. The RCS files are not free-form files, they
2594 have a structure that is easily broken by hand-editing. The only time
2595 I would suggest doing this is to recover from emergency failures that
2596 are difficult to deal with using CVS commands, including the "admin"
2597 command, which can talk directly to RCS.
2599 Though no one actively encourages the editing of RCS files, many
2600 people have succumbed to the urge to do so when pressed for time. The
2601 reasons given, usually with evident contrition, include:
2603 - Editing mistakes in, or adding text to, log entries. (If you have
2604 RCS 5.6 or later, you should use `cvs admin -m'.)
2605 - Renaming or moving symbolic names. (You should `cvs admin -N'
2607 - Unlocking a file by changing the "locker" from someone else to
2608 yourself. (It's safer to use `cvs admin -u -l'.)
2609 - Making global changes to past history. Example: Eradicating former
2610 employees names from old documents and Author entries. (And someone
2611 thought the "history" command was evidence of Big Brother! I never
2612 realized how much help a wide-open revision control system could have
2613 provided to The Ministry of Truth.)
2615 Last modified: _6/13/1997_
2617 3. Can I edit the ./CVS/{Entries,Repository,Tag} files?
2619 Yes, but with CVS 1.3 and later, there is almost no reason to edit any
2620 of the CVS administrative files.
2622 If you move pieces of your Repository around it can be faster to edit
2623 all the ./CVS/Repository files rather than checking out a large tree.
2624 But that is nearly the only reason to do so.
2626 Last modified: _6/13/1997_
2628 4. Someone executed "admin -o" and removed revisions to which tags/symbols
2629 were attached. How do I fix them?
2631 It depends on what you mean by "fix". I can think of three ways to fix
2636 Assuming you really wanted to get rid of the revision and its
2637 associated tags, you can remove them with the "admin" command. The
2638 "tag -d" command will only remove tags attached to existing revisions.
2639 You can remove a tag, even if it is attached to a non-existent
2640 revision, by typing:
2642 cvs admin -N<tag> <file>
2644 Retrieve the outdated revision.
2646 You should first look in your backup system for recent versions of the
2647 file. If you can't use them, you can carefully extract each revision
2648 that followed the earliest outdated revision using RCS (or "cvs
2649 admin") commands and reconstruct the file with all the right
2650 revisions, branches and tags. This is a lot of work.
2652 You *can't* insert a revision into the current RCS file.
2654 Move the Tags to another revision in each file.
2656 If you want to move the tags to another valid revision, you have two
2657 choices, both of which require that you find all the revision numbers
2658 of the files you want to "tag" and execute the following command
2659 sequences on each <file>.
2661 Use "update" to grab the revision you want, then execute a normal
2662 "tag" command to Tag that revision:
2664 cvs update -r <rev> <file>
2665 cvs tag <tag> <file>
2667 Use "admin" to set the tag to a specific revision:
2669 cvs admin -N<tag>:<rev> <file>
2671 Last modified: _6/13/1997_
2673 5. How do I move or rename a magic branch tag?
2675 (To rename a non-branch <tag> see 3O.9.)
2677 Before reading this, read 3M.3 and 3M.4 and understand exactly how tag
2678 and rtag use '-r' and why it won't do the right job here.
2680 First, I have to explain exactly what a magic branch tag is.
2682 A magic <branch_tag> is an artificial tag attached to a non-existent
2683 revision on a non-existent branch number zero. It looks like this:
2687 <X> is the "branch point revision", a normal revision with an
2688 odd number of '.'s in it. (e.g. 1.5, 1.3.1.6, etc)
2690 Y is an even number (e.g. 2, 4, 6, etc.) All CVS branches,
2691 other than the Vendor branch, are even numbered.
2693 TAG1 is considered by CVS to be attached to revision <X>. The first
2694 "update -r TAG1 <file>" after applying TAG1 will produce a copy of
2695 revision <X> with a sticky tag of TAG1. The first "commit" to that
2696 file will cause CVS to construct an RCS branch named <X>.Y and check
2697 in revision <X>.Y.1 on the new branch.
2699 Note: TAG1 is *not* considered to be attached to <X> by RCS, which
2700 explains why you can't refer directly to the branch point revision for
2703 Moving a magic <branch_tag> is the act of reapplying the same tag to
2704 different revisions in the file:
2708 TAG1:<X>.0.Z or TAG1:<A>.0.B
2710 You can move a magic branch tag to the revisions of your choice by
2711 using "update" to find the revisions you want to tag and reapplying
2712 the tag to all the files with the '-F' option to force it to move the
2713 existing <branch_tag>.
2715 cvs update -r <tag/rev> (or '-A' for the Main Branch)
2716 cvs tag -F -b <branch_tag>
2718 If the earlier location of TAG1 refers to a physical branch within any
2719 RCS file, moving it will make the existing branch in the file seem to
2720 disappear from CVS's view. This is not a good idea unless you really
2721 want to forget the existence of those RCS branches.
2723 If the "update" above retrieves the original branch point revision
2724 (<X>), the "tag" command above will create the tag:
2728 Where Z is 2 greater than the highest magic branch already on revision
2729 <X>. The TAG1 branch will still have the same branch point (i.e.
2730 revision <X>), but the first commit to the new TAG1 branch will create
2731 a different RCS branch number (<X>.Z instead of <X>.Y).
2733 Renaming a magic <branch_tag> is the act of changing
2739 There is no harm in changing a tag name as long as you forget that
2740 TAG1 ever existed and you clean up any working directories with sticky
2741 TAG1 tags on them by using "update -A", "update -r <other_tag>" or by
2742 removing the working directories.
2744 On the other hand, actually changing the tag is not easy.
2746 See 3M.3 for why the seemingly obvious solution won't work:
2748 cvs tag -b -r <old_branch_tag> <new_branch_tag>
2750 The only direct way to rename a magic tag is to use the "admin"
2751 command on each file: (You might want to use '-n'. Read "man rcs" and
2752 look at the '-n' and '-N' options.)
2754 cvs admin -N<new_branch_tag>:<old_branch_tag> .
2755 cvs tag -d <old_branch_tag>
2757 But you have to be careful because "admin" is different from other CVS
2760 "admin" can be used recursively, but only by specifying directory
2761 names in its argument list (e.g. '.'),
2763 Where "rtag -r <old_branch_tag>" would interpret <old_branch_tag> as
2764 a magic CVS branch tag, "admin" is a direct interface to RCS which
2765 sees a magic branch tag as a simple (though non-existent) RCS revision
2768 This is good for us in this particular case, but different from normal
2771 "admin" also skips the Attic and produces different kinds of errors
2772 than CVS usually does. (Because they are coming directly from RCS.)
2774 The other way to rename a magic <branch_tag> is to edit the Repository
2775 files with a script of some kind. I've done it in the past, but I'll
2776 leave it as an exercise for the reader.
2778 Last modified: _6/13/1997_
2780 6. Can I use RCS locally to record my changes without making them globally
2781 visible by committing them?
2783 You can, but it will probably confuse CVS to have ",v" files in your
2784 working directory. And you will lose all your log entries when you
2787 Your best bet is to create your own CVS branch and work there. You can
2788 commit as many revisions as you want, then merge it back into the main
2789 line (or parent branch) when you are finished.
2791 Last modified: _6/13/1997_
2793 7. How can I allow access to the Repository by both CVS and RCS?
2795 The first step is to try not to. If some people are using CVS, there
2796 is no reason for everyone not to. It is not hard to learn the basics
2797 and CVS makes certain operations *easier* than a series of RCS
2798 commands. Personal preference in what software tools can be applied to
2799 a shared Repository has to take second place to system integration
2800 needs. If you disagree, try writing some Lisp code for inclusion in
2801 your Unix kernel and see what kind of reception you get.
2803 If you really must allow routine RCS access to the CVS Repository, you
2804 can link an RCS sub-directory into a piece of the Repository:
2806 ln -s /Repository/some/directory/I/want RCS
2808 and RCS will work just fine.
2810 Those who are using RCS will have to keep the following in mind:
2812 If a file was originally added to the Repository by "import" and has
2813 not been changed using CVS, the *RCS* default branch will remain
2814 attached to the Vendor branch, causing revisions checked-in by "ci" to
2815 wind up on the Vendor branch, instead of the main branch. Only CVS
2816 moves the RCS default branch on first commit.
2818 The way around this is to checkin (using "ci") all the files first and
2819 move them into the Repository. That way they won't have Vendor
2820 branches. Then RCS will work OK.
2822 It is possible to use "rcs" and "ci" to make the files unusable by
2823 CVS. The same is true of the CVS "admin" command.
2825 Normal RCS practice locks a file on checkout with "co -l". In such
2826 an environment, RCS users should plan to keep survival gear and food
2827 for at least 30 days near their desks. When faced with bizarre and
2828 unexpected permission errors, howling mobs of slavering CVS users will
2829 run the RCS users out of town with pitchforks and machetes.
2831 See 3C.8 for a way to avoid machetes aroused by lock collisions.
2833 Though files checked in by RCS users will correctly cause
2834 "up-to-date" failures during CVS "commits" and they will be
2835 auto-merged into CVS working directories during "update", the opposite
2838 RCS users will get no warning and will not be required to merge older
2839 work into their code. They can easily checkin an old file on top of a
2840 new revision added by CVS, discarding work committed earlier by CVS
2843 See the howling mob scenario described above.
2845 RCS is great. I have used it for years. But I wouldn't mix it this
2846 way. In a two-camp society, you are asking for real trouble, both in
2847 technical hassles to clean up and in political hassles to soothe.
2848 Branch merges will also be a major problem.
2850 Last modified: _6/13/1997_
2852 8. I "updated" a file my friend, "bubba", committed yesterday. Why doesn't
2853 the file now have a modified date of yesterday?
2855 CVS restores dates from the RCS files only on first "checkout". After
2856 that, it is more important to maintain a timestamp relative to the
2857 other files in the working directory.
2859 Example: You committed a source file at 5PM. Bubba updated his copy of
2860 the file, grabbing your changes, then changed and committed a new
2861 revision of the file at 6PM. At 7PM, you compile your file. Then you
2862 execute "update". If CVS sets the date to the one in the RCS file, the
2863 file would be given a timestamp of 6PM and your Makefile wouldn't
2864 rebuild anything that depended on it. Bad news.
2866 Note that the same logic applies to retrieving a revision out of the
2867 Repository to replace a deleted file. If CVS changes your file in an
2868 existing working directory, whether it was because a new revision was
2869 committed by someone else or because you deleted your working file,
2870 the timestamp on the retrieved working file *must* be set to the
2873 When you first retrieve a file, there is no reason to expect any
2874 particular timestamp on the file within your working area. But later,
2875 when dependency checking is performed during a build, it is more
2876 important for the timestamps on the local files to be consistent with
2877 each other than than it is for working files to match the timestamps
2878 on the files in the Repository. See 4D.17 for some more about
2881 Last modified: _6/13/1997_
2883 9. Why do timestamps sometimes get set to the date of the revision,
2884 sometimes not? The inconsistency causes unnecessary recompiles.
2886 The "checkout" command normally sets the timestamp of a working file
2887 to match the timestamp stored on the revision in the Repository's RCS
2890 The "commit" command retains the timestamp of the file, if the act of
2891 checking it in didn't change it (by expanding keywords).
2893 The "update" command sets the time to the revision time the first time
2894 it sees the file. After that, it sets the time of the file to the
2895 current time. See 4D.8 for a reason why.
2897 Here's a two-line PERL program to set timestamps on files based on
2898 other timestamps. I've found this program useful. When you are certain
2899 you don't want a source file to be recompiled, you can set its
2900 timestamp to the stamp on the object file.
2902 #!/usr/local/bin/perl
2904 # Set timestamp of args 2nd-Last to that of the first arg.
2906 ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,$atime,$mtime,$ctime)
2908 utime($atime,$mtime,@ARGV);
2910 Last modified: _6/13/1997_
2912 10. While in the middle of a large "commit", how do I run other commands,
2913 like "diff" or "stat" without seeing lock errors?
2918 The '-n' option to the main cvs command turns off lock checking, a
2919 reasonable act for read-only commands given the promise offered by
2920 '-n' not to alter anything. The "diff", "log" and "stat" commands
2921 provide the same information (for files that are not being committed)
2922 when used with and without the '-n' option.
2924 Warning: Ignoring locks can produce inconsistent information across a
2925 collection of files if you are looking at the revisions affected by an
2926 active commit. Be careful when creating "patches" from the output of
2927 "cvs -n diff". If you are looking only at your working files, tagged
2928 revisions, and BASE revisions (revisions whose numbers are read from
2929 your ./CVS/Entries files), you should get consistent results. Of
2930 course, if you catch a single file in the middle of RCS activity, you
2931 might get some strange errors.
2933 Note that the suggested command is "cvs -n <command>". The visually
2934 similar command "cvs <command> -n" has no relation to the suggested
2935 usage and has an entirely different meaning for each command.
2937 "cvs -n update" also works in the middle of a commit, providing
2938 slightly different information from a plain "cvs update". But, of
2939 course, it also avoids modifying anything.
2941 You could also use the RCS functions, "rlog" and "rcsdiff" to display
2942 some of the information by referring directly to the Repository files.
2944 You need RCS version 5 or later for the commands described above to
2947 Last modified: _6/13/1997_
2949 11. Where did the ./CVS/Entries.Static file come from? What is it for?
2951 Each CVS working directory contains a ./CVS/Entries file listing the
2952 files managed by CVS in that working directory. Normally, if the
2953 "update" command finds a file in the Repository that is not in the
2954 ./CVS/Entries file, "update" copies the appropriate revision of the
2955 "new" file out of the Repository and adds the filename to the Entries
2956 file. This happens for files:
2958 Added to the Repository from another working directory.
2960 Dragged out of the Attic when switching branches with "update -A" or
2963 Whose names were deleted from the ./CVS/Entries file.
2965 If the ./CVS/Entries.Static file exists, CVS will only bring out
2966 revisions of files that are contained in either ./CVS/Entries or
2967 ./CVS/Entries.Static. If a Repository file is found in *neither* file,
2970 The ./CVS/Entries.Static file is created when you check out an
2971 individual file or a module that creates working directories that
2972 don't contain all files in the corresponding Repository directory. In
2973 those cases, without an ./CVS/Entries.Static file, a simple "update"
2974 would bring more files out of the Repository than the original
2977 The ./CVS/Entries.Static file can be removed by hand. It is
2978 automatically removed if you run "update -d" to create new directories
2979 (even if no new directories are created). (Internally, since
2980 "checkout" turns on the '-d' flag and calls the "update" routine, a
2981 "checkout" of a module or directory that writes into an existing
2982 directory will also remove the ./CVS/Entries.Static file.)
2984 Last modified: _6/13/1997_
2986 12. Why did I get the wrong Repository in the loginfo message?
2990 Use multiple Repositories.
2992 Configured CVS to use absolute pathnames in the ./CVS/Repository
2995 Configured CVS not to use the ./CVS/Root file.
2997 Typed the "commit" command in one Repository with your $CVSROOT
2998 pointing at another.
3000 "commit" and all other CVS commands will heed an absolute pathname in
3001 the ./CVS/Repository file (or in the "-d CVSrootdir" override), but
3002 the log function doesn't take arguments -- it just looks at $CVSROOT.
3004 If you avoid even one of the four steps above, you won't see this
3005 problem. If you configure ./CVS/Root, you won't be allowed to execute
3006 the program causing the error.
3008 Last modified: _6/13/1997_
3010 13. How do I run CVS setuid so I can only allow access through the CVS
3013 Setuid to root is not a great idea. Any program that modifies files
3014 and is used by a widely distributed group of users is not a good
3015 candidate for a setuid program. (The worst suggestion I've ever heard
3016 was to make *Emacs* setuid to root.)
3018 Root access on Unix is too powerful. Also, it might not work in some
3019 (secure?) environments.
3021 Running it setuid to some user other than root might work, if you add
3022 this line to main.c near the beginning:
3026 Otherwise it uses *your* access rights, rather than the effective
3029 Also, you have to invent a fake user whose name will show up in
3030 various places. But many sites, especially those who might want a
3031 setuid CVS for "security", want personal accountability -- no generic
3032 accounts. I don't know whether accountability outweighs file security.
3034 And finally, unless you take action to limit the "admin" command, you
3035 are leaving yourself unprotected anyway.
3037 Last modified: _6/13/1997_
3039 14. How about using groups and setgid() then?
3041 Here is a way to run CVS setgid in some environments:
3043 Stick this near the front of the main() in main.c:
3047 This will allow "access" to work on systems where it only works on the
3050 Create a group named "cvsg". (This example uses "cvsg". You can name
3053 Put *no* users in the "cvsg" group. You can put Repository
3054 administrators in this group if you want to.
3056 Set the cvs executable to setgid (not setuid):
3058 cd /usr/local/bin; chown root.cvsg cvs; chmod 2755 cvs
3060 Make sure every file in the Repository is in group "cvsg":
3062 chown -R root.cvsg $CVSROOT
3064 Change all directory permissions to 770. This allows all access to
3065 the files by the "cvsg" group (which has no members!) and no access at
3068 find $CVSROOT -type d -exec chmod 2770 {} \;
3070 On some systems you might have to type:
3072 find $CVSROOT -type d -exec chmod u=rwx,g=rwx,o=,g+s {} \;
3074 This should allow only the cvs program (or other "setgid to group
3075 cvsg") programs to write into the area, but no one else. Yes the user
3076 winds up owning the file, but s/he can't find it again later since
3077 s/he can't traverse the tree. (If you enable the world execute bit
3078 (mode 2771) on directories, users can traverse the tree and the user
3079 who last wrote the file can still write to it.)
3081 If you want to allow read access, check out an entire tree somewhere.
3082 You have to do this anyway to build it.
3084 Note: If you are using a stupid file system that can't inherit file
3085 groups from the parent directory (even with the "setgid" (Octal 2000)
3086 bit set), you might have to modify CVS (or RCS) to reset the group
3087 every time you create a new file. I have not tested this.
3089 The setgid() method shares with the setuid() method the problem of
3090 keeping "admin" from breaking things.
3092 Last modified: _6/13/1997_
3094 15. How do I use the "commitinfo" file?
3098 The "commitinfo" file allows you to execute "sanity check" functions
3099 before allowing a commit. If any function called from within the
3100 commitinfo file exits with a non-zero status, the commit is denied.
3102 To fill out a "commitinfo" file, ask yourself (and those sharing your
3103 Repository) these questions:
3105 - Is there anything you want to check or change before someone is
3106 allowed to commit a file? If not, forget commitinfo.
3108 If you want to serialize binary files, you might consider something
3109 like the rcslock.pl program in the contrib directory of the CVS
3112 - Do you want to execute the same exact thing before committing to
3113 every file in the Repository? (This is useful if you want to program
3114 the restrictions yourself.) If so, set up a single line in the
3117 DEFAULT /absolute/path/to/program
3119 CVS executes the program once for each directory that "commit"
3120 traverses, passing as arguments the directory and the files to be
3121 committed within that directory.
3123 Write your program accordingly. Some examples exist in the contrib
3126 - Do you want a different kind of sanity check performed for different
3127 directories? If so, you'll have to decide what to do for all
3128 directories and enter lines like this:
3130 regexp1 /absolute/path/to/program-for-regexp1
3131 regexp2 /absolute/path/to/program-for-regexp2
3132 DEFAULT /absolute/path/to/program-for-all-else
3134 - Is there anything you want to happen before *all* commits, in
3135 addition to other pattern matches? If so, include a line like this:
3137 ALL /absolute/path/to/program
3139 It is executed independently of all the above. And it's repeatable --
3140 you can have as many ALL lines as you like.
3142 Last modified: _6/13/1997_
3144 16. How do I use the "loginfo" files?
3146 See 4B.2 and the "commitinfo" question above.
3148 The "loginfo" file has the same format as the "commitinfo" file, but
3149 its function is different. Where the "commitinfo" information is used
3150 before a commit, the "loginfo" file is used after a commit.
3152 All the commands in the "loginfo" file should read data from standard
3153 input, then either append it to a file or send a message to a mailing
3154 list. If you want to make it simple, you can put shell (the shell used
3155 by "popen(3)") command lines directly in the "loginfo" (or
3156 "commitinfo") file. These seem to work:
3158 ^special /usr/ucb/Mail -s %s special-mailing-list ^other /usr/ucb/Mail
3159 -s %s other-mailing-list DEFAULT (echo '===='; echo %s; cat) >
3160 /path/name/to/log/file
3162 Last modified: _6/13/1997_
3164 17. How can I keep people with restrictive umask values from blocking
3165 access to the Repository?
3167 If a user creates a new file with restricted permissions (e.g. 0600),
3168 and commits it, the Repository will have a file in it that is
3169 unreadable by everyone. The 0600 example would be unreadable by
3170 *anyone* but root and the user who created it.
3172 There are 3 solutions to this:
3174 Let it happen. This is a valid way to protect things. If everyone is
3175 working alone, a umask of 077 is OK. If everyone is working only in
3176 small groups, a umask of 007 is OK.
3178 Train your users not to create such things if you expect to share
3181 See 4B.5 for a small script that will reset the umask.
3183 I personally don't like the idea of a program automatically
3184 *loosening* security. It would be better for you all to talk about the
3185 issue and decide how to work together.
3187 Last modified: _6/13/1997_
3189 Category: /Commands_/
3193 Category: /Commands_/add_ad_new/
3195 " + "add", "ad", "new""
3197 1. What is "add" for?
3199 To add a new directory to the Repository or to register the desire to
3200 add a new file to the Repository.
3202 The directory is created immediately, while the desire to add the file
3203 is recorded in the local ./CVS administrative directory. To really add
3204 the file to the Repository, you must then "commit" it.
3206 Last modified: _6/13/1997_
3208 2. How do I add a new file to the branch I'm working on?
3210 The user actions for adding a file to any branch, including the Main
3211 Branch, are exactly the same.
3213 You are in a directory checked out (or updated) with the '-A' option
3214 (to place you on the Main Branch) or the "-r <branch_tag>" option (to
3215 place you on a branch tagged with <branch_tag>). To add <file> to the
3216 branch you are on, you type:
3221 If no ./CVS/Tag file exists (the '-A' option deletes it), the file
3222 will be added to the Main Branch. If a ./CVS/Tag file exists (the "-r
3223 <branch_tag>" option creates it), the file will be added to the branch
3224 named (i.e. tagged with) <branch_tag>.
3226 Unless you took steps to first add the file to the Main Branch, your
3227 new file ends up in the Attic.
3229 Last modified: _6/13/1997_
3231 3. Why did my new file end up in the Attic?
3233 The file is thrown into the Attic to keep it from being visible when
3234 you check out the Main Branch, since it was never committed to the
3237 Last modified: _6/13/1997_
3239 4. Now that it's in the Attic, how do I connect it to the Main branch?
3241 That can be considered a kind of "merge". See 4C.8
3243 Last modified: _6/13/1997_
3245 5. How do I avoid the hassle of reconnecting an Attic-only file to the Main
3248 You create it on the Main Branch first, then branch it.
3250 If you haven't yet added the file or if you decided to delete the new
3251 Attic file and start over, then do the following: (If you added the
3252 file (or worse, the 157 files) to the Attic and don't want to start
3253 over, try the procedure in 4C.8.)
3255 Temporarily remove the sticky branch information. Either:
3257 Move the whole directory back to the Main Branch. [This might not be
3258 a good idea if you have modified files, since it will require a merge
3265 Move the ./CVS/Tag file out of the way.
3267 mv ./CVS/Tag HOLD_Tag
3269 Add and branch the file "normally":
3273 cvs tag -b <branch_tag> <file>
3275 [<branch_tag> is the same Branch Tag as you used on all the other
3276 files. Look at ./CVS/Entries or the output from "cvs stat" for sticky
3279 Clean up the temporary step.
3281 If you moved the ./CVS/Tag file, put it back. Then move the new file
3282 onto the branch where you are working.
3284 mv HOLD_Tag ./CVS/Tag
3285 cvs update -r <branch_tag> <file>
3287 If you ran "update -A" rather than moving the ./CVS/Tag file, move
3288 the whole directory (including the new file) back onto the branch
3289 where you were working:
3291 cvs update -r <branch_tag>
3293 Last modified: _6/13/1997_
3295 6. How do I cancel an "add"?
3297 If you want to remove the file entirely and cancel the "add" at the
3300 cvs remove -f <file>
3302 If you want to cancel the "add", but leave the file as it was before
3303 you typed "cvs add", then you have to fake it:
3305 mv <file> <file>.hold
3307 mv <file>.hold <file>
3309 Last modified: _6/13/1997_
3311 7. What are the ./CVS/file,p and ./CVS/file,t files for?
3313 The ./CVS/file,p and ./CVS/file,t files are created by the "add"
3314 command to hold command line options and message text between the time
3315 of the "add" command and the expected "commit".
3317 The ./CVS/file,p file is always null, since its function was absorbed
3318 by the "options" field in the ./CVS/Entries file. If you put something
3319 in this file it will be used as arguments to the RCS "ci" command that
3320 commit uses to check the file in, but CVS itself doesn't put anything
3323 The ./CVS/file,t file is null unless you specify an initial message in
3324 an "add -m 'message'" command. The text is handed to "rcs -i
3325 -t./CVS/file,t" to create the initial RCS file container.
3327 Both files must exist to commit a newly added file. If the
3328 ./CVS/file,p file doesn't exist, CVS prints an error and aborts the
3329 commit. If the ./CVS/file,t file doesn't exist, RCS prints an error
3330 and CVS gets confused, but does no harm.
3332 To recover from missing ,p and ,t files, just create two zero-length
3333 files and rerun the "commit".
3335 Last modified: _6/13/1997_
3337 8. How do I "add" a binary file?
3339 If you configured CVS to use the GNU version of "diff" and "diff3",
3340 you only need to turn off RCS keyword expansion.
3342 First you turn off RCS keyword expansion for the initial checkin by
3343 using "add -ko". It works like "update -ko" in creating a "sticky"
3344 option only for the copy of the file in the current working directory.
3348 Commit the file normally. The sticky -ko option will be used.
3352 Then mark the RCS file in the Repository so that keyword expansion is
3353 turned off for all checked out versions of the file.
3355 cvs admin -ko <file>
3357 Since "admin -ko" records the keyword substitution value in the
3358 Repository's RCS file, you no longer need the sticky option. You can
3359 turn it off with the "update -A" command, but if you were on a branch,
3360 you'll have to follow it "update -r <branch_tag>" to put yourself back
3363 Managing that binary file is another problem. See 4D.1.
3365 Last modified: _6/13/1997_
3367 Category: /Commands_/admin_adm_rcs/
3369 " + "admin", "adm", "rcs""
3371 1. What is "admin" for?
3373 To provide direct access to the underlying "rcs" command (which is not
3374 documented in this FAQ) bypassing all safeguards and CVS assumptions.
3376 Last modified: _6/13/1997_
3378 2. Wow! Isn't that dangerous?
3382 Though you can't hurt the internal structure of an RCS file using its
3383 own "rcs" command, you *can* change the underlying RCS files using
3384 "admin" in ways that CVS can't handle.
3386 If you feel the need to use "admin", create some test files with the
3387 RCS "ci" command and experiment on them with "rcs" before blasting any
3390 Last modified: _6/13/1997_
3392 3. What would I normally use "admin" for?
3394 Normally, you wouldn't use admin at all. In unusual circumstances,
3395 experts can use it to set up or restore the internal RCS state that
3398 You can use "admin -o" (for "outdate") to remove revisions you don't
3399 care about. This has its own problems, such as leaving dangling Tags
3400 and confusing the "update" command.
3402 There is some feeling among manipulators of binary files that "admin
3403 -l" should be used to serialize access. See 3C.8.
3405 An interesting use for "admin" came up while maintaining CVS itself. I
3406 import versions of CVS onto the Vendor branch of my copy of CVS, make
3407 changes to some files and ship the diffs (created by "cvs diff -c -r
3408 TO_BRIAN") off to Brian Berliner. After creating the diff, I retag
3409 ("cvs tag -F TO_BRIAN") the working directory, which is then ready to
3410 produce the next patch.
3412 I'll use "add.c" as an example (only because the name is short).
3414 When the next release came out, I discovered that the released "add.c"
3415 (version 1.1.1.3 on the Vendor branch) was exactly the same as my
3416 modified file (version 1.3). I didn't care about the changelog on
3417 versions 1.2 and 1.3 (or the evidence of having done the work), so I
3418 decided to revert the file to the state where it looked like I had not
3419 touched the file -- where I was just using the latest on the vendor
3420 branch after a sequence of imports.
3422 To do that, I removed all the revisions on the main branch, except for
3423 the original 1.1 from which the Vendor branch sprouts:
3425 cvs admin -o1.2: add.c
3427 Then I set the RCS "default branch" back to the Vendor branch, the way
3428 import would have created it:
3430 cvs admin -b1.1.1 add.c
3432 And I moved the "TO_BRIAN" Tag to the latest revision on the Vendor
3433 branch, since that is the base from which further patches would be
3434 created (if I made any):
3436 cvs admin -NTO_BRIAN:1.1.1.3 add.c
3438 Instead of 1.1.1.3, I could have used one of the "Release Tags" last
3439 applied by "import" (3rd through Nth arguments).
3441 Suggestion: Practice on non-essential files.
3443 Last modified: _6/13/1997_
3445 4. What should I avoid when using "admin"?
3447 If you know exactly what you are doing, hack away. But under normal
3450 Never use "admin" to alter branches (using the '-b' option), which CVS
3451 takes very seriously. If you change the default branch, CVS will not
3452 work as expected. If you create new branches without using the "tag
3453 -b" command, you may not be able to treat them as CVS branches.
3455 See 3C.8 for a short discussion of how to use "admin -l" for
3456 serializing access to binary files.
3458 The "admin -o <file>" allows you to delete revisions, usually a bad
3459 idea. You should commit a correction rather than back out a revision.
3460 Outdating a revision is prone to all sorts of problems:
3462 Discarding data is always a bad idea. Unless something in the
3463 revision you just committed is a threat to your job or your life,
3464 (like naming a function "<boss's name>_is_a_dweeb", or including the
3465 combination to the local Mafioso's safe in a C comment), just leave it
3466 there. No one cares about simple mistakes -- just commit a corrected
3469 The time travel paradoxes you can cause by changing history are not
3470 worth the trouble. Even if CVS can't interfere with your parents'
3471 introduction, it *can* log commits in at least two ways (history and
3472 loginfo). The reports now lie -- the revision referred to in the logs
3475 If you used "import" to place <file> into CVS, outdating all the
3476 revisions on the Main branch back to and including revision 1.2 (or
3477 worse, 1.1), will produce an invalid CVS file.
3479 If the <file>,v file only contains revision 1.1 (and the connected
3480 branch revision 1.1.1.1), then the default branch must be set to the
3481 Vendor branch as it was when you first imported the file. Outdating
3482 back through 1.2 doesn't restore the branch setting. Despite the above
3483 admonition against it, "admin -b" is the only way to recover:
3485 cvs admin -b1.1.1 <file>
3487 Although you can't outdate a physical (RCS) branch point without
3488 removing the whole branch, you *can* outdate a revision referred to by
3489 a magic branch tag. If you do so, you will invalidate the branch.
3491 If you "outdate" a tagged revision, you will invalidate all uses of
3492 the <tag>, not just the one on <file>. A tag is supposed to be
3493 attached to a consistent set of files, usually a set built as a unit.
3494 By discarding one of the files in the set, you have destroyed the
3495 utility of the <tag>. And it leaves a dangling tag, which points to
3498 And even worse, if you commit a revision already tagged, you will
3499 alter what the <tag> pointed to without using the "tag" command. For
3500 example, if revision 1.3 has <tag> attached to it and you "outdate"
3501 the 1.3 revision, <tag> will point to a nonexistent revision. Although
3502 this is annoying, it is nowhere near as much trouble as the problem
3503 that will occur when you commit to this file again, recreating
3504 revision 1.3. The old tag will point to the new revision, a file that
3505 was not in existence when the <tag> was applied. And the discrepancy
3506 is nearly undetectable.
3508 If you don't understand the above, you should not use the admin
3511 Last modified: _6/13/1997_
3513 5. How do I restrict the "admin" command? The -i flag in the modules file
3514 can restrict commits. What's the equivalent for "admin"?
3516 At this writing, to disable the "admin" command, you will have to
3517 change the program source code, recompile and reinstall.
3519 Last modified: _6/13/1997_
3521 6. I backed out a revision with "admin -o" and committed a replacement. Why
3522 doesn't "update" retrieve the new revision?
3524 CVS is confused because the revision in the ./CVS/Entries file matches
3525 the latest revision in the Repository *and* the timestamp in the
3526 ./CVS/Entries file matches your working file. CVS believes that your
3527 file is "up-to-date" and doesn't need to be updated.
3529 You can cause CVS to notice the change by "touch"ing the file.
3530 Unfortunately what CVS will tell you is that you have a "Modified"
3531 file. If you then "commit" the file, you will bypass the normal CVS
3532 check for "up-to-date" and will probably commit the revision that was
3533 originally removed by "admin -o".
3535 Changing a file without changing the revision number confuses CVS no
3536 matter whether you did it by replacing the revision (using "admin -o"
3537 and "commit" or raw RCS commands) or by applying an editor directly to
3538 a Repository (",v") file. Don't do it unless you are absolutely
3539 certain no one has the latest revision of the file checked out.
3541 The best solution to this is to institute a program of deterrent
3542 flogging of abusers of "admin -o".
3544 The "admin" command has other problems." See 3B.4 above.
3546 Last modified: _6/13/1997_
3548 Category: /Commands_/checkout_co_get/
3550 " + "checkout", "co", "get""
3552 1. What is "checkout" for?
3554 To acquire a copy of a module (or set of files) to work on.
3556 All work on files controlled by CVS starts with a "checkout".
3558 Last modified: _6/13/1997_
3560 2. What is the "module" that "checkout" takes on the command line?
3562 It is a name for a directory or a collection of files in the
3563 Repository. It provides a compact name space and the ability to
3564 execute before and after helper functions based on definitions in the
3569 Last modified: _6/13/1997_
3571 3. Isn't a CVS "checkout" just a bunch of RCS checkouts?
3573 Like much of CVS, a similar RCS concept is used to support a CVS
3574 function. But a CVS checkout is *not* the same as an RCS checkout.
3576 Differences include:
3578 CVS does not lock the files. Others may access them at the same
3581 CVS works best when you provide a name for a collection of files (a
3582 module or a directory) rather than an explicit list of files to work
3585 CVS remembers what revisions you checked out and what branch you are
3586 on, simplifying later commands.
3588 Last modified: _6/13/1997_
3590 4. What's the difference between "update" and "checkout"?
3592 The "checkout" and "update" commands are nearly equivalent in how they
3593 treat individual files. They differ in the following ways:
3595 The "checkout" command always creates a directory, moves into it,
3596 then becomes equivalent to "update -d".
3598 The "update" command does not create directories unless you add the
3601 "Update" is intended to be executed within a working directory
3602 created by "checkout". It doesn't take a module or directory argument,
3603 but figures out what Repository files to look at by reading the files
3604 in the ./CVS administrative directory.
3606 The two commands generate completely different types of records in
3609 Last modified: _6/13/1997_
3611 5. Why can't I check out a file from within my working directory?
3613 Though you *can* check out a file, you normally check out a module or
3614 directory. And you normally do it only once at the beginning of a
3617 After the initial "checkout", you can use the "update" command to
3618 retrieve any file you want within the checked-out directory. There is
3619 no need for further "checkout" commands.
3621 If you want to retrieve another module or directory to work on, you
3622 must provide two pathnames: where to find it in the Repository and
3623 where to put it on disk. The "modules" file and your current directory
3624 supply two pieces of naming information. While inside a checked-out
3625 working directory, the CVS administrative information provides most of
3628 You should be careful not to confuse CVS with RCS and use "checkout"
3629 in the RCS sense. An RCS "checkout" (which is performed by the RCS
3630 "co" command) is closer to a "cvs update" than to a "cvs checkout".
3632 Last modified: _6/13/1997_
3634 6. How do I avoid dealing with those long relative pathnames?
3636 This question has also been phrased:
3638 How do I avoid all those layers of directories on checkout? or Why do
3639 I have to go to the top of my working directory and checkout some long
3640 pathname to get a file or two?
3642 This type of question occurs only among groups of people who decide
3643 not to use "modules". The answer is to use "modules".
3645 When you hand the "checkout" command a relative pathname rather than a
3646 module name, all directories in the path are created, maintaining the
3647 same directory hierarchy as in the Repository. The same kind of
3648 environment results if you specify a "module" that is really an alias
3649 expanding into a list of relative pathnames rather than a list of
3652 If you use "module" names, "checkout" creates a single directory by
3653 the name of the module in your current directory. This "module"
3654 directory becomes your working directory.
3656 The "module" concept combines the ability to "name" a collection of
3657 files with the ability to structure the Repository so that consistent
3658 sets of files are checked out together. It is the responsibility of
3659 the Repository Administrators to set up a modules file that describes
3660 the software within the Repository.
3662 Last modified: _6/13/1997_
3664 7. Can I move a checked-out directory? Does CVS remember where it was
3669 The ./CVS/Repository file in each working directory contains a
3670 pathname pointing to the matching directory within the Repository. The
3671 pathname is either absolute or relative to $CVSROOT, depending on how
3674 When you move a checked-out directory, the CVS administrative files
3675 will move along with it. As long as you don't move the Repository
3676 itself, or alter your $CVSROOT variable, the moved directory will
3677 continue to be usable.
3679 CVS remembers where you checked out the directory in the "history"
3680 file, which can be edited, or even ignored if you don't use the
3681 "working directory" information displayed by the "history" command.
3683 Last modified: _6/13/1997_
3685 8. How can I lock files while I'm working on them the way RCS does?
3687 Until the day arrives of the all-powerful merge tool, there are still
3688 files that must be accessed serially. For those instances, here's a
3691 Install a pre-commit program in the "commitinfo" file to check for
3692 RCS locks. The program "rcslock.pl" performs this function. It can be
3693 found in the contrib directory of the CVS source distribution.
3695 When you want to make a change to a file you know can't be merged,
3696 first use "cvs admin -l" to lock the file. If you can't acquire the
3697 lock, use the standard "locked out" protocol: go talk to the person
3700 Make sure the pre-commit program prints a message and exits with a
3701 non-zero status if someone besides the user running "commit" has the
3702 file locked. This non-zero exist status will cause the "commit" to
3705 Make sure the pre-commit program exits with a zero status if the
3706 file is either unlocked or locked by the user running "commit". The
3707 "cvs commit" command that kicked off the pre-commit program will take
3708 a zero exist status as an OK and checkin the file, which has the
3709 side-effect of unlocking it.
3711 ===> The following is opinion and context. Don't read it if you are
3712 looking for a quick fix.
3714 The topic of locking CVS files resurfaces on the network every so
3715 often, producing the same results each time:
3719 CVS was designed to avoid locks, using a copy-modify-merge model.
3720 Locking is not necessary and you should take the time to learn the CVS
3721 model which many people find workable. So why not get with the program
3722 and learn how to think the CVS way?
3726 The users determine how a tool is to be used, not the designers. We,
3727 the users, have always used locking, our bosses demand locking,
3728 locking is good, locking is God. I don't want to hear any more
3729 lectures on the CVS model. Make locking work.
3731 Any organization making active changes to a source base will
3732 eventually face the need to do parallel development. Parallel
3733 development implies merges. (If you plan to keep separate copies of
3734 everything and never merge, good luck. Tell me who you work for so I
3735 can buy stock in your disk suppliers this year and sell your stock
3738 Merges will never go away. CVS chose to make "merges" stand front and
3739 center as an important, common occurrence in development. It is one
3740 way of looking at things.
3742 For free-format text, the merge paradigm gives you a considerable
3743 amount of freedom. It does take a bit of management, but any project
3744 should be ready to deal with it.
3746 On the other hand, there are many files that can't be merged using
3747 text merge techniques. Straight text merge programs like "diff3" are
3748 guaranteed to fail on executables (with relative branch statements),
3749 files with self-referential counts stored in the file (such as TAGS
3750 files), or files with relative motion statements in them (such as
3751 Frame MIF files, many postscript files). They aren't all binary files.
3753 For these types of files, and many others, there are only two
3756 Complex merge tools that are intimately aware of the contents of the
3757 files to be merged. (ClearCase, and probably others, allow you to
3758 define your own "files types" with associated "merge tools".)
3760 Serialization of access to the file. The only technical solution to
3761 the problem of serialization is "locking".
3763 Since you can call a program that offers:
3765 "Which one do you want? A/B?"
3767 a "merge tool", more and more merge tools will appear which can be
3768 hooked into a merge-intensive program like CVS. Think of a bitmap
3769 "merge" tool that displays the bitmaps on the screen and offers a
3770 "paint" interface to allow you to cut and paste, overlay, invert or
3771 fuse the two images such that the result is a "merged" file.
3773 My conclusion is that the need for locking is temporary, awaiting
3774 better technology. For large development groups, locking is not an
3775 alternative to merging for text files.
3777 Last modified: _6/13/1997_
3779 9. What is "checkout -s"? How is it different from "checkout -c"?
3781 The '-c' and '-s' options to "checkout" both cause the modules file to
3782 appear on standard output, but formatted differently.
3784 "checkout -c" lists the modules file alphabetized by the module name.
3785 It also prints all data (including options like '-a' and "-o <prog>")
3786 specified in the modules file.
3788 "checkout -s" lists the modules file sorted by "status" field, then by
3789 module name. The status field was intended to allow you to mark
3790 modules with strings of your choice to get a quick sorted report based
3791 on the data you chose to put in the status fields. I have used it for
3792 priority ("Showstopper", etc as tied into a bug database), for porting
3793 status ("Ported", "Compiled", etc. when porting a large collection of
3794 modules), for "assignee" (the person responsible for maintenance), and
3795 for "test suite" (which automatic test procedure to run for a
3798 Last modified: _6/13/1997_
3800 Category: /Commands_/commit_ci_com/
3802 " + "commit", "ci", "com""
3804 1. What is "commit" for?
3806 To store new revisions in the Repository, making them visible to other
3809 Last modified: _6/13/1997_
3811 2. If I edit ten files, do I have to type "commit" ten times?
3813 No. The "commit" command will take multiple filenames, directory names
3814 and relative pathnames on the command line and commit them all with
3815 the same log message. If a file is unchanged, even if it is explicitly
3816 listed on the command line, CVS will skip it.
3818 Like all CVS commands, "commit" will work on the whole directory by
3819 default. Just type "cvs commit" to tell CVS to commit all modified
3820 files (i.e. the files that "update" would display preceded by 'M') in
3821 the current directory and in all sub-directories.
3823 Last modified: _6/13/1997_
3825 3. Explain: cvs commit: Up-to-date check failed for `<file>'
3827 You may not "commit" a file if your BASE revision (i.e. the revision
3828 you last checked out, committed or retrieved via "update") doesn't
3829 match the HEAD revision (i.e the latest revision on your branch,
3830 usually the Main Branch).
3832 In other words, someone committed a revision since you last executed
3833 "checkout", "update" or "commit". You must now execute "update" to
3834 merge the other person's changes into your working file before
3835 "commit" will work. You are thus protected (somewhat) from a common
3836 form of race condition in source control systems, where a checkin of a
3837 minor alteration of a second copy of the same base file obliterates
3838 the changes made in the first.
3840 Normally, the "update" command's auto-merge should be followed by
3841 another round of building and testing before the "commit".
3843 Last modified: _6/13/1997_
3845 4. What happens if two people try to "commit" conflicting changes?
3847 Conflicts can occur only when two developers check out the same
3848 revision of the same file and make changes. The first developer to
3849 commit the file has no chance of seeing the conflict. Only the second
3850 developer runs into it, usually when faced with the "Up-to-date" error
3851 explained in the previous question.
3853 There are two types of conflicts:
3855 When two developers make changes to the same section of code, the
3856 auto-merge caused by "update" will print a 'C' on your terminal and
3857 leave "overlap" markers in the file.
3859 You are expected to examine and clean them up before committing the
3860 file. (That may be obvious to *some* of you, but . . .)
3862 A more difficult problem arises when two developers change different
3863 sections of code, but make calls to, or somehow depend on, the old
3864 version of each other's code.
3866 The auto-merge does the "right" thing, if you view the file as a
3867 series of text lines. But as a program, the two developers have
3868 created a problem for themselves.
3870 This is no different from making cross-referential changes in
3871 *separate* files. CVS can't help you. In a perfect world, you would
3872 each refer to the specification and resolve it independently. In the
3873 real world you have to talk/argue, read code, test and debug until the
3874 combined changes work again.
3876 Welcome to the world of parallel development.
3878 Last modified: _6/13/1997_
3880 5. I committed something and I don't like it. How do I remove it?
3882 Though you *can* use the "admin -o" (synonym: "rcs -o") command to
3883 delete revisions, unless the file you committed is so embarrassing
3884 that the need to eradicate it overrides the need to be careful, you
3885 should just grab an old version of the file ("update -p -r
3886 <previous-rev>" might help here) and commit it on top of the offending
3889 See Section 3B on "admin".
3891 Last modified: _6/13/1997_
3893 6. Explain: cvs commit: sticky tag `V3' for file `X' is not a branch
3895 The message implies two things:
3897 You created your working directory by using "checkout -r V3", or you
3898 recently executed "update -r V3".
3900 The tag named V3 is not a branch tag.
3902 CVS records (i.e. makes "sticky") any "-r <tag/rev>" argument handed
3903 to the "checkout" or "update" commands. The <tag/rev> is recorded as
3904 the CVS working branch, which is the branch to which "commit" will add
3907 Branch tags are created when you use the -b switch on the "tag" or
3908 "rtag" commands. Branch tags are magic tags that don't create a
3909 physical branch, but merely mark the revision to branch from when the
3910 branch is needed. The first commit to a magic branch creates a
3911 physical branch in the RCS files.
3913 You can commit onto the end of the Main Trunk, if you have no sticky
3914 tag at all, or onto the end of a branch, if you have a sticky branch
3915 tag. But you can't commit a file that has a sticky tag not pointing to
3916 a branch. CVS assumes a sticky Tag or Revision that does not refer to
3917 a branch is attached to the middle of a series of revisions. You can't
3918 squeeze a new revision between two others. Sticky dates also block
3919 commits since they never refer to a branch.
3923 If you don't want a branch and were just looking at an old revision,
3924 then you can move back to the Main Branch by typing:
3926 cvs update -A {files or dirs, default is '.'}
3928 or you can move to the branch named <branch_tag> by:
3930 cvs update -r <branch_tag> {files or dirs, default is '.'}
3934 If you really wanted to be on a branch and made an earlier mistake by
3935 tagging your branch point with a non-branch tag, you can recover by
3936 adding a new branch tag to the old non-branch tag:
3938 cvs rtag -b -r <oldtag> <newtag> <module>
3940 (It was not a big mistake. Branch-point tags can be useful. But the
3941 <newtag> must have a different name.)
3943 If you don't know the <module> name or don't use "modules", you can
3944 also use "tag" this way:
3946 cvs update -r <oldtag>
3947 cvs tag -b <newtag> .
3949 Then, to put your working directory onto the branch, you type:
3951 cvs update -r <newtag>
3953 You can't delete <oldtag> before adding <newtag>, and I would not
3954 advise deleting the <oldtag> at all, because it is useful in referring
3955 to the branch point. If you must, you can delete the non-branch tag
3958 cvs rtag -d <oldtag> <module>
3960 cvs tag -d <oldtag> .
3964 If you made the same mistake as in Scenario2 (of placing a non-branch
3965 tag where you wanted a branch tag), but really want <oldtag> to be the
3966 name of your branch, you can execute a slightly different series of
3967 commands to rename it and move your working directory onto the branch.
3969 Warning: This is not a way to rename a branch tag. It is a way to turn
3970 a non-branch tag into a branch tag with the same name.
3972 cvs rtag -r <oldtag> <branch_point_tag> <module>
3973 cvs rtag -d <oldtag> <module>
3974 cvs rtag -b -r <branch_point_tag> <oldtag> <module>
3976 Then, if you really must, delete the <branch_point_tag>:
3978 cvs rtag -d <branch_point_tag> <module>
3980 Note: The unwieldy mixture of "tag" and "rtag" is mostly because you
3981 can't specify a revision (-r <tag>) to the "tag" command.
3983 See 4C.3 for more info on creating a branch.
3985 Last modified: _6/13/1997_
3987 7. Why does "commit -r <tag/rev>" put newly added files in the Attic?
3989 If you specify "-r <rev>" (where <rev> is a dotted numeric number like
3990 2.4), it correctly sets the initial revision to <rev>, but it also
3991 attaches the numeric <rev> as a sticky tag and throws the file into
3992 the Attic. This is a bug. The obvious solution is to move the file out
3993 of the Attic into the associated Repository directory and "update -A"
3994 the file. There are no Tags to clean up.
3996 If you specify "-r <tag>" to commit a newly added file, the <tag> is
3997 treated like a <branch_tag>, which becomes a symbolic RCS label
3998 pointing to the string '1', which can be considered to be the "Main
3999 branch number" when the main branch is still at revision 1.N. The file
4000 is also thrown into the Attic. See 4C.8 for a way to recover from
4003 In fact, a plain "commit" without the "-r" will throw a newly added
4004 file into the Attic if you added it to a directory checked out on a
4005 branch. See 3A.[2-5].
4007 See Section 4C, on Branching, for many more details.
4009 Last modified: _6/13/1997_
4011 8. Why would a "commit" of a newly added file not produce rev 1.1?
4013 When committing a newly added file CVS looks for the highest main
4014 branch major number in all files in the ./CVS/Entries file. Normally
4015 it is '1', but if you have a file of revision 3.27 in your directory,
4016 CVS will find the '3' and create revision 3.1 for the first rev of
4017 <file>. Normally, the first revision is 1.1.
4019 Last modified: _6/13/1997_
4021 Category: /Commands_/diff_di_dif/
4023 " + "diff", "di", "dif""
4025 1. What is "diff" for?
4027 To display the difference between a working file and its BASE
4028 revision (the revision last checked out, updated or committed):
4032 To display the difference between a working file and a committed
4033 revision of the same file:
4035 cvs diff -r <tag/rev> <file>
4037 To display the difference between two committed revisions of the
4040 cvs diff -r <tag1/rev1> -r <tag2/rev2> <file>
4042 You can specify any number of <file> arguments. Without any <file>
4043 arguments, it compares the whole directory.
4045 In the examples above, "-D <date>" may be substituted wherever "-r
4046 <tag/rev>" appears. The revision a <date> refers to is the revision
4047 that existed on that date.
4049 Last modified: _6/13/1997_
4051 2. Why did "diff" display nothing when I know there are later committed
4052 revisions in the Repository?
4054 By default, "diff" displays the difference between your working file
4055 and the BASE revision. If you haven't made any changes to the file
4056 since your last "checkout", "update" or "commit" there is no
4057 difference to display.
4059 To display the difference between your working file and the latest
4060 revision committed to your current branch, type:
4062 cvs diff -r HEAD <file>
4064 Last modified: _6/13/1997_
4066 3. How do I display what changed in the Repository since I last executed
4067 "checkout", "update" or "commit"?
4069 A special tag (interpreted by CVS -- it does not appear in the Tag
4070 list) named "BASE" always refers to the revision you last checked out,
4071 updated or committed. Another special tag named "HEAD" always refers
4072 to the latest revision on your working branch.
4074 To compare BASE and HEAD, you type:
4076 cvs diff -r BASE -r HEAD <file>
4078 Last modified: _6/13/1997_
4080 4. How do I display the difference between my working file and what I
4081 checked in last Thursday?
4083 cvs diff -D "last Thursday" <file>
4085 where "last Thursday" is a date string. To be more precise, the
4086 argument to the '-D' option is a timestamp. Many formats are accepted.
4087 See the man page under "-D date_spec" for details.
4089 Last modified: _6/13/1997_
4091 5. Why can't I pass long options, like --unified, to "diff"?
4093 CVS only handles single character '-X' arguments, not the FSF long
4094 options. CVS also passes through only arguments it knows about,
4095 because a few arguments are captured and interpreted by CVS.
4097 If you didn't configure RCS and CVS to use the GNU version of diff,
4098 long options wouldn't work even if future versions of CVS acquire the
4099 ability to pass them through.
4101 Most of the long options have equivalent single-character options,
4102 which do work. The "--unified" option is equivalent to '-u' in
4103 revisions of GNU diff since 1.15.
4105 Last modified: _6/13/1997_
4107 Category: /Commands_/export_exp_ex/
4109 " + "export", "exp", "ex""
4111 1. What is "export" for?
4113 "export" checks out a copy of a module in a form intended for export
4114 outside the CVS environment. The "export" command produces the same
4115 directory and file structure as the "checkout" command, but it doesn't
4116 create "CVS" sub-directories and it removes all the RCS keywords from
4119 Last modified: _6/13/1997_
4121 2. Why does it remove the RCS keywords so I can't use the "ident" command
4122 on the source files?
4124 It removes the RCS keywords, so that if the recipient of the exported
4125 sources checks them into another set of RCS files (with or without
4126 CVS), and then makes modifications through RCS or CVS commands, the
4127 revision numbers that they had when you exported them will be
4128 preserved. (That ident no longer works is just an unfortunate side
4131 The theory is that you are exporting the sources to someone else who
4132 will make independent changes, and at some point you or they will want
4133 to know what revisions from your Repository they started with
4134 (probably to merge changes, or to try to decide whether to merge
4137 A better way to handle this situation would be to give them their own
4138 branch of your Repository. They would need to remember to checkin the
4139 exported sources with RCS IDs intact (ci -k) so that their changes
4140 would get revision numbers from the branch, rather than starting at
4141 1.1 again. Perhaps a future version of CVS will provide a way to
4142 export sources this way.
4144 Contributed by Dan Franklin
4146 Last modified: _6/13/1997_
4148 3. Can I override the '-kv' flag CVS passes to RCS?
4150 Not as of CVS version 1.4.
4152 Last modified: _6/13/1997_
4154 4. Why doesn't "export" have a '-k' flag like "import" does?
4156 Export is intended for a specific purpose -- to remove all trace of
4157 revision control on the way *out* of CVS.
4159 Last modified: _6/13/1997_
4161 5. Why does "export -D" check out every file in the Attic?
4163 See 5B.3 for an explanation of the same problem with "update".
4165 Last modified: _6/13/1997_
4167 Category: /Commands_/history_hi_his/
4169 " + "history", "hi", "his""
4171 1. What is "history" for?
4173 To provide information difficult or impossible to extract out of the
4174 RCS files, such as a "tag" history or a summary of module activities.
4176 Last modified: _6/13/1997_
4178 2. Of what use is it?
4180 I have found it useful in a number of ways, including:
4182 Providing a list of files changed since
4185 - Yesterday, last Thursday, or a specific date.
4186 - Someone changed a specific file.
4188 Providing a list of special events:
4190 - Files added or removed since one of the above events.
4191 - Merge failures since one of the above events. (Where did the
4193 - Has anyone (and who) grabbed the revision of this file I committed
4194 last week, or are they still working blind?
4196 Telling me how often a file/directory/module has been changed.
4198 Dumping a summary of work done on a particular module, including who
4199 last worked on it and what changed.
4201 Displaying the checked-out modules and where they are being worked
4204 To tell me what users "joe" and "malcolm" have done this week.
4206 Last modified: _6/13/1997_
4208 3. What is this, Big Brother?
4212 Ignorance is Strength.
4214 Normally manager types and those with the power to play Big Brother
4215 don't care about this information. The Software Engineer responsible
4216 for integration usually wants to know who is working on what and what
4217 changed. Use your imagination.
4219 Last modified: _6/13/1997_
4221 4. I deleted my working directory and "history" still says I have it
4222 checked out. How do I fix it?
4224 You can use "release -f" to forcibly add a "release" record to the
4225 history file for a working directory associated with a "module". If
4226 your version of "release" doesn't have the '-f' option, or you checked
4227 out the directory using a relative path, you have to edit the
4228 $CVSROOT/CVSROOT/history file.
4230 You can remove the last 'O' line in the history file referring to the
4231 module in question or add an 'F' record.
4233 Last modified: _6/13/1997_
4235 5. So I *can* edit the History file?
4237 Yes, but if you are using history at all, you should take a little
4238 care not to lose information. I normally use Emacs on the file, since
4239 it can detect that a file has changed out from under it. You could
4240 also copy and zero out the history file, edit the copy and append any
4241 new records to the edited copy before replacing it.
4243 Last modified: _6/13/1997_
4245 6. Why does the history file grow so quickly?
4247 It stores 'U' records, which come in handy sometimes when you are
4248 tracking whether people have updated each other's code before testing.
4249 There should (and probably will sometime) be a way to choose what
4250 kinds of events go into the history file.
4252 The contributed "cln_hist.pl" script will remove all the 'U' records,
4253 plus matching pairs of 'O' and 'F' records during your normal clean up
4254 of the history file.
4256 Last modified: _6/13/1997_
4258 7. What is the difference between "cvs history -r <tag/rev>" and "cvs
4261 The '-t' option looks for a Tag record stored by "rtag" in the history
4262 file and limits the search to dates after the last <tag> of the given
4265 The '-r' option was intended to search all files looking for the <tag>
4266 in the RCS files. It takes forever and needs to be rewritten.
4268 Last modified: _6/13/1997_
4270 8. Why does "cvs history -c -t <tag>" fail to print anything?
4272 You have been using "tag" instead of "rtag". The "tag" command
4273 currently doesn't store a history record. This is another remnant of
4274 CVS's earlier firm belief in "modules". But it also has a basis in how
4275 "rtag" and "tag" were originally used.
4277 "rtag" was intended for large-scale tagging of large chunks of the
4278 Repository, an event work recording. "tag" was intended for adding and
4279 updating tags on a few files or directories, though it could also be
4280 used to tag the entire checked-out working tree when there is no
4281 module defined to match the tree or when the working tree is the only
4282 place where the right collection of revisions to tag can be found.
4284 Last modified: _6/13/1997_
4286 9. "cvs history -a -o" only printed one line for each checked-out module.
4287 Shouldn't it print all the directories where the modules are checked out?
4291 Command Question it is supposed to answer.
4292 ---------------- ------------------------------------------
4293 cvs history -o What modules do I have checked out?
4294 cvs history -a -o <same for all users>
4296 cvs history -o -w What working directories have I created
4297 and what modules are in them?
4298 cvs history -a -o -w <same for every user>
4300 The -o option chooses the "checked out modules" report, which is the
4301 default history report.
4303 Last modified: _6/13/1997_
4305 10. I can't figure out "history", can you give me concrete examples?
4307 Default output selects records only for the user who executes the
4308 "history" command. To see records for other users, add one or more "-u
4309 user" options or the '-a' option to select *all* users.
4311 To list (for the selected users): Type "cvs history" and:
4313 * Checked out modules: -o (the default)
4314 * Files added since creation: -x A
4315 * Modified files since creation: -c
4316 * Modified files since last Friday: -c -D 'last Friday'
4317 * Modified files since TAG was added: -c -t <tag>
4318 * Modified files since TAG on files: -c -r <tag>
4319 * Last modifier of file/Repository X? -c -l -[fp] X
4320 * Modified files since string "str": -c -b str
4321 * Tag history: (Actually "rtag".) -T
4322 * History of file/Repository/module X: -[fpn] X
4323 * Module report on "module": -m module
4325 Last modified: _6/13/1997_
4327 11. Can we merge history files when we merge Repositories?
4329 Assuming that the two Repositories have different sets of pathnames,
4330 it should be possible to merge two history files by sorting them
4331 together by the timestamp fields.
4333 You should be able to run:
4335 sort -k 1.2 ${dir1}/history ${dir2}/history > history
4337 If you "diff" a standard history file before and after such a sort,
4338 you might see other differences caused by garbage (split lines, nulls,
4339 etc) in the file. If your Repository is mounted through NFS onto
4340 multiple machines you will also see a few differences caused by
4341 different clocks on different machines. (Especially if you don't use
4342 NTP to keep the clocks in sync.)
4344 Last modified: _6/13/1997_
4346 Category: /Commands_/import_im_imp/
4348 " + "import", "im", "imp""
4350 1. What is "import" for?
4352 The "import" command is a fast way to insert a whole tree of files
4355 The first "import" to a particular file within the Repository creates
4356 an RCS file with a single revision on the "Vendor branch." Subsequent
4357 "import"s of the same file within the Repository append a new revision
4358 onto the Vendor branch. It does not, as some seem to believe, create a
4359 new branch for each "import". All "imports" are appended to the single
4362 If the file hasn't changed, no new revision is created -- the new
4363 "Release-Tag" is added to the previous revision.
4365 After the import is finished, files you have not changed locally are
4366 considered to have changed in the "Main line of development". Files
4367 you *have* changed locally must have the new Vendor code merged into
4368 them before they are visible on the "Main line".
4372 Last modified: _6/13/1997_
4374 2. How am I supposed to use "import"?
4376 Create a source directory containing only the files you want to
4377 import. Make sure you clean up any cruft left over from previous
4378 builds or editing. You want to make sure that the directory contains
4379 only what you want to call "source" from which everything else is
4382 If this is not the first import from this "Vendor", you should also
4383 compare the output of "find . ! -name CVS -print | sort" executed both
4384 at the head of a checked out working directory and at the head of the
4385 sources to be imported. If you find any deleted or renamed files, you
4386 have to deal with them by hand. (See 4B.8 on renaming.)
4388 "cd" into your source directory and type:
4390 cvs import -m "Message" <repos> <Vendor-Tag> <Release-Tag>
4392 where <repos> is the relative directory pathname within the Repository
4393 that corresponds to the sources you are importing.
4395 You might also consider using the "-I !" option to avoid ignoring
4396 anything. It is easier to remove bogus files from the Repository than
4397 to create a sparse tree of the ignored files and rerun "import".
4399 For example, if the FSF, CVS, Make and I are still active in the year
4400 2015, I'll import version 89.53 of GNU make this way:
4402 cvs import -m "GNUmake V89.53" gnu/make GNU GNUMAKE_89_53
4404 See 3H.13 for more details.
4406 Last modified: _6/13/1997_
4408 3. Why does import put files on a branch? Why can't I work on the main
4409 trunk instead of a Vendor branch?
4411 This was a Design choice. The Vendor branch is the way "import" deals
4412 with a Vendor release. It is a solution to the Engineering problem of
4413 how to merge multiple external releases of Vendor-supplied sources
4414 into your ongoing work. The Vendor releases are kept on a separate,
4415 special, "Vendor" branch and your work is kept on the RCS trunk. New
4416 Vendor releases are imported onto the Vendor branch and then merged
4417 into your work, if there is any, on the trunk.
4419 This way, you can use CVS to find out not only about your work, but
4420 you can also find out what the Vendor changed by diffing between two
4421 of the Release Tags you handed to "import".
4423 CVS was designed to work this way. If you use CVS in some other way,
4424 you should think carefully about what you are doing.
4426 Note that the CVS "Main Branch" and the RCS Main Trunk are not the
4427 same. Placing files on the Vendor Branch doesn't keep you from
4428 creating a development branch to work on.
4430 See Section 4C, on Branching.
4432 If you are not working with 3rd party (i.e. Vendor) sources, you can
4433 skip the "import" and avoid the Vendor branch entirely. It works just
4434 as well to move pre-existing RCS files into Repository directories.
4436 You can create a whole Repository tree by copying a directory
4437 hierarchy of normal source files directly into the Repository and
4438 applying CVS to it. Here's an idea you should *test* before using:
4440 cd <your source tree>
4442 set module = xyzzy <<== Your choice of directory name
4443 mkdir $CVSROOT/$module
4445 (cd $source; tar cf - .) | tar xvpBf -
4446 find . -type f -exec ci -t-Original. {} \;
4448 The RCS "ci" command, without -u or -l options, will turn your source
4449 file into an RCS (",v") and delete the original source.
4451 Last modified: _6/13/1997_
4453 4. Is there any way to import binary files?
4455 If you configured CVS to use the GNU version of "diff" and "diff3",
4456 then you can import any kind of file.
4458 Binary files with RCS keywords in them are a problem, since you don't
4459 want them to expand.
4461 If the tree you are about to "import" is entirely filled with binary
4462 files, you can use the '-ko' option on "import". Otherwise, I would
4463 run the import normally, then fix the binary files as described below
4466 See 4D.1 on Binary files.
4468 Last modified: _6/13/1997_
4470 5. Why does "import" corrupt some binary files?
4472 The RCS "co" command, when it is invoked by a CVS "checkout" or
4473 "update" (or after a "commit") command, searches for and expands a
4474 list of keywords within the file. They are documented in the RCS "co"
4475 man page. Strings such as "$\Id$" (or "$\Id:"), or "$\Revision$" (or
4476 "$\Revision:") are altered to the include the indicated information.
4478 [[Note: The keywords should appear in the text without the '\'
4479 character I have inserted to *avoid* expansion here. The only real RCS
4480 keywords in this document are at the top of the file, where I store
4481 the Revision and Date.]]
4483 If RCS keyword strings show up in a binary file, they will be altered
4484 unless you set the '-ko' option on the RCS files to tell RCS to keep
4485 the original keyword values and not to expand new ones. After
4486 "import", you can set the '-ko' option this way:
4488 cvs admin -ko <file>
4492 After an import that didn't use '-ko' (because the whole tree wasn't
4493 of binary files) you should fix up the binary files as described above
4494 before checking out any new copies of the files and before updating
4495 any working directories you checked out earlier.
4497 See 4D.1 on Binary files.
4499 Last modified: _6/13/1997_
4501 6. How do I retain the original $\Revision$ strings in the sources?
4503 If you want to leave old RCS keywords as they are, you can use the
4504 '-ko' tricks described above.
4506 Last modified: _6/13/1997_
4508 7. I imported some files for the Yarg compiler that compiles files with a
4509 suffix of ".yarg" and whose comment prefix is "YARG> ". When I check them
4510 out, they will no longer compile because they have this junk in them. Why?
4512 YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>
4514 # Revision 1.3 1998/03/03 00:16:16 bubba
4515 # What is 2+2 anyway?
4517 # Revision 1.2 1998/03/03 00:15:15 bubba
4518 # Added scorekeeping.
4520 YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>
4522 Well bubba, "Yarg" hasn't hit the big time yet. Neither RCS nor CVS
4523 know about your suffix or your comment prefix. So you have two
4526 Check out the Yarg-less module, and tell all the files about your
4527 comment prefix. Visit each directory and type:
4529 cvs admin -c"YARG> " *.yarg
4531 If *all* files in the whole directory tree are Yarg files, you can use
4534 cvs admin -c"YARG> " .
4536 Then save any changes you made, remove all the "*.yarg" files and grab
4537 new copies from the Repository:
4539 rm *.yarg (or: find . -name '*.yarg' -exec rm {} ';') (or: find .
4540 -name '*.yarg' -print | xargs rm) (or: find . -name '*.yarg' -print0 |
4541 xargs -0 rm if you have spaces in filenames and the GNU find/xargs.)
4544 It might be faster to remove the whole directory and check it out
4547 Change the import.c file in the CVS sources and add the .yarg
4548 suffix, along with the "YARG> " comment prefix to the "comtable"
4551 If you ever plan to add new files with $\Log in them, you should also
4552 go into the RCS sources and make the same change in the table
4553 contained in the "rcsfnms.c" file.
4555 Then delete the imported files from the Repository and re-"import" the
4558 Last modified: _6/13/1997_
4560 8. How do I make "import" save the timestamps on the original files?
4562 Use "import -d" to save the current timestamps on the files as the RCS
4565 See 4D.8 for another aspect of file timestamps.
4567 Last modified: _6/13/1997_
4569 9. Why can't I "import" 3 releases on different branches?
4571 I'll bet you typed something like this:
4574 cvs import -b 1.1.2 VENDOR2 Version2
4576 cvs import -b 1.1.3 VENDOR3 Version3
4578 cvs import -b 1.1.4 VENDOR4 Version4
4580 This is wrong, or at least it won't help you much. You have created
4581 three separate Vendor branches, which is probably not what you wanted.
4583 Earlier versions of CVS, as described in Brian Berliner's Usenix
4584 paper, tried to support multiple Vendor branches on the theory that
4585 you might receive source for the *same* program from multiple vendors.
4586 It turns out that this is very rare, whereas the need to branch in
4587 *your* development, for releases and for project branches, is much
4590 So the model now is to use a single vendor branch to contain a series
4591 of releases from the same vendor. Your work moves along on the Main
4592 Trunk, or on a CVS branch to support a real "branch in development".
4594 To set this up, you should type this instead of the above:
4597 cvs import VENDOR Version2
4599 cvs import VENDOR Version3
4601 cvs import VENDOR Version4
4603 Last modified: _6/13/1997_
4605 10. What do I do if the Vendor adds or deletes files between releases?
4607 Added files show up with no extra effort. To handle "removed" files,
4608 you should always compare the tree structure of the new release
4609 against the one you have in your Repository. If the Vendor has removed
4610 files since the previous release, go into a working directory
4611 containing your current version of the sources and "cvs remove"
4612 (followed by "cvs commit" to make it really take effect) each file
4613 that is no longer in the latest release.
4615 Using this scheme will allow you to "checkout" any version of the
4616 vendor's code, with the correct revisions and files, by using
4617 "checkout -r Version[234]".
4619 Renames are harder to find, since you have to compare file contents to
4620 determine that one has occurred. If you notice one, see 4B.8 on
4623 Last modified: _6/13/1997_
4625 11. What about if the Vendor changes the names of files or directories, or
4626 rearranges the whole structure between releases?
4628 Currently CVS can't handle this cleanly. It requires "renaming" a
4629 bunch of files or directories.
4631 See 4B.8 on "renaming" for more details.
4633 What I generally do is to close the Repository for a while and make
4634 changes in both the Repository and in a copy of the vendor release
4635 until the structure matches, then execute the import.
4637 If you ever have to check out and build an old version, you may have
4638 to use the new, or completely different Makefiles.
4640 Last modified: _6/13/1997_
4642 12. I thought "import" was for Vendor releases, why would I use it for code
4643 of my own? Do I have to use import?
4645 For code you produce yourself, "import" is a convenience for fast
4646 insertion of whole trees. It is not necessary. You can just as easily
4647 create ",v" files using the RCS "ci" command and move them directly
4648 into the Repository.
4650 Other than the CVSROOT directory, the Repository consists entirely of
4651 directories of ",v" files. The Repository contains no other state
4654 See Section 4B, on Setting up and Managing the Repository.
4656 Last modified: _6/13/1997_
4658 13. How do I import a large Vendor release?
4660 When the sum of the changes made by the Vendor and the changes made by
4661 local developers is small, "import" is not a big problem. But when you
4662 are managing a large Repository, any care taken up front will save you
4665 First read the following, then, before executing "import", see the
4666 questions in Section 4C dealing with branch merges and Vendor branch
4669 If this is not the first import of this code, before starting, rtag
4670 the whole directory you will be changing.
4672 The first step is to make sure the structure of the new files
4673 matches the structure of the current Repository.
4675 Run "find . -print | sort" on both trees and "diff" the output.
4677 Alter the "source" tree until the "diff" (of the list of filenames,
4678 not of the whole trees) shows that the directory structures are
4681 The "comm" command, if you have it, can help figure out what has been
4682 added or deleted between releases.
4684 If they deleted any files, you can handle them cleanly with "cvs
4685 remove". The command "comm -23 files.old files.new" will show you a
4686 list of files that need to be removed.
4688 You should examine the list first to see if any have been renamed
4689 rather than simply deleted.
4691 If they renamed any files, see 4B.8 on renaming files.
4693 Remember to *SAVE* the output from the import command.
4695 When you have dealt with removed and renamed files, then you can
4699 cvs import -I ! -m "Message" <repos> <VendorTag> <ReleaseTag>
4703 "-I !" is an optional argument that keeps "import" from ignoring
4704 files. The comparison of the "find" commands above will probably avoid
4705 the need for this, but it is easier to remove files from the
4706 Repository than to run a subset "import" to catch just the ignored
4707 files. [You might have to quote or backwhack the '!'.]
4709 Message is the log message to be stored in the RCS files.
4711 <repos> is a relative path to a directory within the
4712 Repository. The directory <new source> must be at
4713 the same relative level within the new sources as
4714 the <repos> you give is within the Repository. (I
4715 realize this is not obvious. Experiment first.)
4717 <VendorTag> is a Tag used to identify the Vendor who sent you
4718 the files you are importing. All "imports" into
4719 the same <repos> *must* use the same VendorTag.
4720 You can find it later by using the "log" command.
4722 <ReleaseTag> is a Tag used to identify the particular release of the
4723 software you are importing. It must be unique and should be mnemonic
4724 -- at least include the revision number in it. (Note: you can't use
4725 '.' characters in a Tag. Substitute '_' or '-'.)
4727 There will be six categories of files to deal with. (Actually there
4728 are eight, but you have already dealt with "removed" and "renamed"
4731 If this is the first "import" into a given <repos> directory, only the
4732 first three of these ('I', 'L' and 'N') can occur.
4736 CVS prints: I filename
4738 You'll need to examine it to see if it *should* have been ignored. If
4739 you use "-I !", nothing will be ignored.
4743 CVS prints: L linkname
4745 Links are "ignored", but you'll probably want to create a "checkout
4746 helper" function to regenerate them.
4750 CVS prints: N filename
4752 CVS creates a new file in the Repository. You don't have to do
4753 anything to the file, but you might have to change Makefiles to refer
4754 to it if this is really a new file.
4756 A file unchanged by the Vendor since its last release.
4758 CVS prints: U filename
4760 CVS will notice this and simply add the new ReleaseTag to the latest
4761 rev on the Vendor branch.
4763 No work will be needed by you, whether you have changed the file or
4764 not. No one will notice anything.
4766 A file changed by the Vendor, but not by you.
4768 CVS prints: U filename
4770 CVS should add the file onto the vendor branch and attach the Release
4773 When you next execute "update" in any working directory you'll get the
4776 A file changed by both the Vendor and by you.
4778 CVS prints: C filename
4780 These are the trouble files. For each of these files (or in groups --
4781 I usually do one directory at a time), you must execute:
4783 cvs update -j <PreviousReleaseTag> -j <ReleaseTag>
4785 cvs update -j <VendorTag:yesterday> -j <VendorTag>
4787 It will print either 'M' (if no overlaps) or 'C', if overlaps. If a
4788 'C' shows up, you'll need to edit the file by hand.
4790 Then, for every file, you'll need to execute "cvs commit".
4792 See the part of Section 4C dealing with branch merges.
4794 If you are truly performing a large import, you will most likely
4795 need help. Managing those people is another problem area.
4797 Since the merge of the Vendor branch is just like any other merge, you
4798 should read section 4C for more info about performing and cleaning up
4801 The larger the import, and the larger the group of people involved,
4802 the more often you should use "tag" and "rtag" to record even trivial
4803 milestones. See 4C.14, especially the "paranoid" section.
4805 Before starting the import, you should install and test a "commitinfo"
4806 procedure to record all commits in a file or via Email to a mail
4807 archive. Along with the tags you placed on the Repository before the
4808 import, this archive will help to track what was changed, if problems
4811 There are four stages to the recovery:
4813 Parcel out the work -- Effective Emacs Engineering.
4815 As input to the assignment process, you might want to examine the tree
4816 and record the last person who changed the file. You can also
4817 research, if you don't already know, who is expert in each area of the
4820 Examine the import log (you saved the output, right?), estimate how
4821 much work is involved in each area and assign groups of files to
4822 individual developers. Unless some directory is immense, it is easier
4823 to manage if you assign whole directories to one person.
4825 Keep a list. Suggest a completion date/time. Tell them to "commit" the
4826 file when they are finished with the merge. If you tagged the
4827 Repository before starting the import, you should have no trouble
4828 figuring out what happened.
4830 If you can, find out (or tell them) which working directory to use.
4831 You should verify that the working directory they use is on the Main
4832 Branch ("update -A") and without modified files.
4834 If you trust your crew, have them notify you by Email. Have them send
4835 you the output from "cvs update" in their working directory. You might
4836 have to poll some people until you are certain they have finished, or
4837 have given up. (This is not an invention. I've heard a false, "Yeah,
4838 sure. I finished yesterday," more times that you'd believe.)
4840 When all reports are in, go on to the Source Verification stage.
4842 Source Verification -- CVS and other Tools.
4844 If you didn't dictate which ones to use, find all working directories
4845 and run "cvs -n update" in all of them. The history command and the
4846 "commitinfo" log you set up might help to find checked out working
4849 Sticky conflict flags will help, but they can't recover from
4850 sloppiness or incompetence. You might want to check everything out
4851 into a tree and grep for the parts of the merge conflict markers CVS
4852 doesn't look for. CVS looks for the string '^>>>>>>> '. The merge
4853 operation also puts '^<<<<<<< ' and '^======= ' markers in the file
4854 that careless developers might leave there.
4856 If you find problems simply by looking at the source files and working
4857 directories, start the flogging now. Resolving the textual conflicts
4858 is the easy part. Weed the turkeys out before reaching the next part
4859 of the cleanup -- the resolution of logical conflicts.
4861 Then apply a set of post-commit tags.
4863 Logical Verification -- Diff and powerful eyeballs.
4865 No source control system can solve the problem of resolving
4866 distributed conflicts in program logic. If you change the argument
4867 template for function A (defined in file A.c) and add new calls to
4868 function A from within function B (defined in file B.c) using the old
4869 argument format, you are outside the realm of CVS's competence.
4871 Assign someone to understand what the Vendor changed by running "cvs
4872 diff -c -r <PreviousReleaseTag> <ReleaseTag>", where the tags were
4873 those handed to the last two invocations of "import".
4875 Then have the same person compare that output (logically or you can
4876 actually diff the diffs) to the output of the similar "cvs diff -c -r
4877 <pre-import-tag> <post-commit-tag>". The two sets of differences
4878 should be almost identical. They should both show only the work *you*
4881 Product Verification -- Build and Test.
4883 Don't let your help off the hook until you verify that the merge
4884 actually produced something that can compile and pass tests. Compiling
4885 should really be part of the logical verification phase, but you
4886 should test the output of the build system before declaring victory
4887 and releasing the troops.
4889 After it is all built, apply another set of tags to mark the end of
4890 the "import process". You can delete the intermediate tags you added
4891 during source and logic testing, but keep the "pre-import" and
4892 "post-import" tags forever.
4894 Of course, experience can tell you when to skip a step. But I'd start
4895 out by considering each one as necessary unless you can prove
4898 Last modified: _6/13/1997_
4900 14. Explain: ERROR: cannot create link to <file>: Permission denied
4902 This error appears when you try to execute a second (or later)
4903 "import" into the same module from a directory to which you don't have
4906 The "link error" is caused by a feature purposely added to speed up
4909 Though the error message is somewhat strange, it indicates that
4910 "import" is supposed to be executed only in writable directories.
4912 Last modified: _6/13/1997_
4914 15. Where does the -m <message> go when the file doesn't change?
4916 The <message> handed to import is used as an RCS log message, but only
4917 if the imported file changed since the last version on the Vendor
4918 branch. If the imported file hasn't changed, then no new revision is
4919 created. The <ReleaseTag> is still applied, but to the previous
4920 revision. So the Tags are still correct, but the message is lost.
4922 Maybe it should be appended to the previous log message. But currently
4925 Last modified: _6/13/1997_
4927 16. How do I "import" just the files ignored by a previous "import"?
4929 A real answer follows, but first, an editorial:
4931 I am now convinced that you should always use the "-I !" option.
4932 Removing a few extraneous files from the Repository is a lot easier
4933 than the recovery step described below.
4935 Let's assume your original import procedure was: (We assume there is
4936 enough disk space in /tmp.)
4938 cd <head-of-vendor-tree>
4939 cvs import -m 'xyz 1.3' gnu/xyz GNU GNUXYZ_1_3 | tee /tmp/IMP
4941 To import just the files ignored by "import", I would do this:
4943 Create a list of the ignored files to import:
4945 cd <head-of-vendor-tree> awk '/^I / {print $2}' /tmp/IMP | sed
4946 's|^gnu/xyz/||' > /tmp/IG [Edit the IG file to contain just the files
4949 Then create a sparse directory by handing your list to the GNU
4950 version of "tar", installed in many places as "gtar":
4952 mkdir /tmp/FIXUP gtar -T /tmp/IG -c -f - . | (cd /tmp/FIXUP; gtar xvBf
4955 Then rerun the import. Use the exact same command, but execute it in
4956 the sparse directory tree you just created. And this time, tell it not
4960 cvs import -I ! -m 'xyz 1.3' gnu/xyz GNU GNUXYZ_1_3
4962 Last modified: _6/13/1997_
4964 17. Why did "import" ignore all the symlinks?
4966 This is another design choice.
4968 Like the Unix "tar" command, "import" could sprout an option to follow
4969 symbolic links, but I don't think CVS will ever follow symbolic links
4972 Two possible future enhancements have been seriously discussed:
4974 Treat symbolic links as data in its parent directory (the way
4975 ClearCase does) in some sort of per-directory control file.
4977 Treat symbolic links as version-controlled elements themselves,
4978 whose data is the value of readlink(2).
4980 For now, they are simply ignored.
4982 If you want to save and reconstruct symlinks, you might want to define
4983 a "checkout" or "update" program in the modules file which could
4984 consult a file kept under CVS in your working directory and make sure
4985 the specified links are in place.
4987 Last modified: _6/13/1997_
4989 Category: /Commands_/log_lo_rlog/
4991 " + "log", "lo", "rlog""
4993 1. What is "log" for?
4995 To provide an interface to the RCS "rlog" command, which displays
4996 information about the underlying RCS files, including the revision
4997 history and Tag (RCS calls it a "symbol") list.
4999 Last modified: _6/13/1997_
5001 2. How do I extract the log entries between two revisions?
5003 If both <rev1> and <rev2> are on the same branch, you can get what you
5004 are looking for with: (If they aren't on the same branch you'll either
5005 get an error or a display of the whole change log.)
5007 cvs log -r<rev1>:<rev2> <file>
5009 If you want all the revisions on the branch from <rev1> to the end of
5010 the branch <rev1> is on, you can use:
5012 cvs log -r<rev1>: <file>
5014 (If <rev1> is a numeric RCS symbol attached to a branch revision with
5015 an even number of '.'s in it, you get the whole branch.)
5017 If you want all the revisions on the branch from the beginning of the
5018 branch <rev2> is on up to revision <rev2>, you can use:
5020 cvs log -r:<rev2> <file>
5022 Note: Depending on whether <rev1> and <rev2> are:
5024 - numeric or symbolic
5025 - in the file or not
5026 - on the same branch or not
5028 the RCS "rlog" (and therefore the "cvs log") command will
5029 display some combination of:
5032 - (intuitively correct) partial log listings
5033 - a display of the entire change log.
5035 Last modified: _6/13/1997_
5037 3. How do I extract the log entries on a whole branch?
5039 cvs log -r<rev> <file>
5041 where <rev> must be a branch revision (one with an even number of
5042 dots) or a *non-branch* tag on a branch revision. Non-branch tags on a
5043 branch revision are not normally attached by CVS, to add one you will
5044 have to explicitly tag a physical branch number within each file.
5045 Since these branch numbers are almost never the same in different
5046 files, this command is not all that useful.
5048 The intuitive command (at least from the CVS perspective):
5050 cvs log -r<branch_tag> <file>
5054 Last modified: _6/13/1997_
5056 4. How do I generate ChangeLogs from RCS logs?
5058 A program called rcs2log is distributed as part of GNU Emacs 19. A
5059 (possibly older) version of this program appears in the contrib
5060 directory of the cvs source tree.
5062 Last modified: _6/13/1997_
5064 5. Why does "log" tell me a file was committed exactly 5 hours later
5068 I can tell by this question that you were working in a time zone that
5069 is 5 hours behind GMT (e.g. the U.S. East Coast in winter).
5071 RCS file dates are stored in GMT to allow users in different time
5072 zones to agree on the meaning of a timestamp. At first glance this
5073 doesn't seem necessary, but many companies use distributed file
5074 systems, such as NFS or AFS, across multiple timezones.
5076 Some standard form must be used. GMT, as the "grid origin", is an
5077 obvious candidate. The only other reasonable choice is to put the
5078 timezone information in all the time stamps, but that changes the RCS
5079 file format incompatibly, a step which has been avoided in the last
5082 Last modified: _6/13/1997_
5084 Category: /Commands_/patch_pa_rdiff/
5086 " + "patch", "pa", "rdiff""
5088 1. What is "patch" for?
5090 To produce a "diff" between tagged releases to be handed to the
5091 "patch" command at other sites. This is the standard way that source
5092 patches are distributed on the network.
5094 Last modified: _6/13/1997_
5096 2. Why does "patch" include files from the Attic when I use '-D'?
5098 See the explanation of the same problem with "update -D" contained in
5101 Last modified: _6/13/1997_
5103 3. How do I make "patch" produce a patch for one or two files? It seems to
5104 work only with modules.
5106 Patch is intended for producing patches of whole modules between
5107 releases to be distributed to remote sites. Instead of "patch", you
5108 can use the "diff" command with the '-c' context option:
5110 cvs diff -c -r <rev/tag> -r <rev/tag> <file1> . . .
5112 The patch command will be able to merge such a "diff" into the remote
5115 If you configured CVS to use a version of "diff" that supports the
5116 '-u' option, you can produce a more compact "patch" in "unidiff"
5117 format. The latest revisions of the patch command can parse and apply
5118 patches in "unidiff" format.
5120 Last modified: _6/13/1997_
5122 Category: /Commands_/release_re_rel/
5124 " + "release", "re", "rel""
5126 1. What is "release" for?
5128 To register that a module is no longer in use. It is intended to
5129 reverse the effects of a "checkout" by adding a record to the history
5130 file to balance the checkout record and by optionally allowing you to
5131 delete the checked-out directory associated with the module name.
5133 Last modified: _6/13/1997_
5135 2. Why can't I reverse a "cvs checkout path/name/subdir" with a "cvs
5136 release path/name/subdir" without an "unknown module name"?
5138 A simplistic implementation. (I can say this -- I wrote it.)
5140 The "release" function was written for CVS 1.2 under the assumption
5141 that the "module name" is a first class, unavoidable interface to the
5142 Repository, allowing no way to retrieve anything other than by module
5143 name. Though it is easier to program that way, many users of CVS
5144 believe the modules support to be too primitive to allow such a
5147 Since "release" was written, other parts of CVS broke that assumption.
5148 It needs to be revised.
5150 Last modified: _6/13/1997_
5152 3. Why can't I "release" portions of a checked out directory? I should be
5153 able to "release" any file or sub-directory within my working directory.
5155 This isn't really a limitation in "release", per se. CVS doesn't try
5156 to keep track of which files in which directories are "checked out"
5157 and which are just lying there. You can delete directories and
5158 "update" will not bring them back unless you add a special "-d"
5161 In other words, CVS doesn't keep track of how you adjust the partition
5162 between files you consider part of your working set and files that
5163 were checked out because they are part of the same module or
5164 directory. And neither does "release".
5166 In future CVS releases, "release" might become sophisticated enough to
5167 handle both the reversal of a "checkout" and the deletion of random
5168 portions of the working directory, but it isn't that way now.
5170 Last modified: _6/13/1997_
5172 4. I removed the tree that I was about to start working on. How do I tell
5173 cvs that I want to release it if I don't have it anymore?
5177 Last modified: _6/13/1997_
5179 5. Why doesn't "release -d module" reverse a "checkout module"?
5181 It does, if you are using "module" in a way that "release" expects: a
5182 non-alias string in the left column of the "modules" database.
5184 If "module" is really an alias, or if you are using a relative path in
5185 the place of "module", or if you renamed the directory with the -d
5186 option in the modules file or on the "checkout" command line, then the
5187 current version of "release" won't work.
5189 Future versions of "release" will probably fix most of these.
5191 Last modified: _6/13/1997_
5193 6. Why can't I release a module renamed with "cvs checkout -d"?
5195 The current version of "release" doesn't know how to track the
5196 renaming option ('-d') of the "checkout" command. It will probably be
5197 fixed in the future.
5199 Last modified: _6/13/1997_
5201 Category: /Commands_/remove_rm_delete/
5203 " + "remove", "rm", "delete""
5205 1. What is "remove" for?
5207 To remove a file from the working branch. It removes a file from the
5208 main branch by placing it in an "Attic" directory.
5210 Last modified: _6/13/1997_
5212 2. Why doesn't "remove" work on directories when it appears to try?
5214 Oversight. It should be able to delete an empty directory, but you
5215 still don't have a way to remember when it was there and when it
5216 disappeared to allow the "-D " option to work.
5218 You'll have to remove the working directory and the matching directory
5221 Note that you want to do a _cvs remove dir_ in the working directory,
5222 do a cvs commit, and then do a _rmdir dir_ in the Repository.
5223 (msusrtsp.mark at eds dot com)
5225 Last modified: _12/18/1997_
5227 3. I don't like removing files. Is there another way to ignore them?
5229 There's no reason to be hasty in using the "remove" command.
5231 If there is a way to ignore files in your build procedures, I'd just
5232 do that. Later, when you decide that the files are really ancient, you
5233 can execute a "remove" command to clean up.
5235 The CVS "ignore" concept can't ignore files already in CVS.
5237 Last modified: _6/13/1997_
5239 4. I just removed a file. How do I resurrect it?
5241 If you executed "remove", but haven't typed "commit" (you can tell
5242 this by the 'R' notation that "update" prints next to the file), you
5243 can execute "add" to reverse the "remove".
5245 If you followed the "remove" with a "commit", you'll have to move it
5246 back out of the Attic by hand:
5248 I use something like this: (csh-like syntax)
5250 set repos = `cat ./CVS/Repository`
5251 mv $repos/Attic/filename,v $repos/filename,v
5253 (If you use relative paths in your Repository files, that first line
5254 becomes: set repos = $CVSROOT/`cat ./CVS/Repository`)
5256 While a file is in the Attic, you can't "add" another file by the same
5257 name. To add such a file you either have to move it by hand as in the
5258 above, or delete it from the Attic.
5260 The main reason for the Attic is to retain files with tags in them. If
5261 you execute: "update -r <oldtag>", files with <oldtag> attached to
5262 some revision will be taken from the normal Repository area and from
5263 the Attic. That's why you can't "add" a file with the same name.
5264 "remove" only moves a file off the main branch, it doesn't obliterate
5267 Last modified: _6/13/1997_
5269 5. Why doesn't "remove" delete the file? Instead, it prints an error
5270 message and tells me to remove the file by hand.
5272 Design choice. Unix software written within last decade, usually
5273 requires an extra verification step, such as answering a question or
5274 adding a flag on the command line. CVS currently requires that you
5275 delete the file first unless you specify the '-f' (force) option,
5276 which deletes the file before performing "cvs remove".
5278 Last modified: _6/13/1997_
5280 Category: /Commands_/rtag_rt_rfreeze/
5282 " + "rtag", "rt", "rfreeze""
5284 1. What is "rtag" for?
5286 To add a symbolic label (a "tag") to the last committed revisions of a
5287 module directly in the Repository.
5289 Last modified: _6/13/1997_
5291 2. Why use "rtag"? It assumes no one is changing the Repository.
5293 Though the "tag" command is more useful in marking the revisions you
5294 have in a particular working directory, "rtag" is much handier for
5295 whole-Repository actions, which occur at major release boundaries.
5297 Last modified: _6/13/1997_
5299 3. What revision does "rtag -r <tag1> <tag2>" actually put the tag on?
5301 In short, the '-r' option is another way to select the revision to
5302 tag. The revision is selected the same way for all commands that
5303 accept a "-r <tag/rev>" option.
5305 Depending on whether <tag1> is a <branch_tag>, or a non-branch <tag>
5306 and on whether you use the '-b' option to "rtag", you get four
5309 rtag -r <tag1> <tag2>
5311 Adds the non-branch tag <tag2> to the same revision that the
5312 non-branch tag <tag1> is attached to.
5317 <file> --> Symbols: TT1:1.4
5318 After --> Symbols: TT1:1.4,TT2:1.4
5320 rtag -r <branch_tag1> <tag2>
5322 Adds the non-branch tag <tag2> to the HEAD of (the highest revision
5323 number on) the branch labelled with tag <branch_tag1>.
5326 <branch_tag1> --> BR1
5328 <file> --> Symbols: BR1:1.2.0.2 (1.2.2.5 is HEAD)
5329 After --> Symbols: BR1:1.2.0.2,TT2:1.2.2.5
5331 If the branch tagged by <branch_tag1> has not been created, then the
5332 tag shows up on the branch point revision:
5335 <branch_tag1> --> BR1
5337 <file> --> Symbols: BR1:1.2.0.2 (No 1.2.X exists.)
5338 After --> Symbols: BR1:1.2.0.2,TT2:1.2
5340 rtag -b -r <tag1> <branch_tag2>
5342 Adds the magic branch tag <branch_tag2> to the revision that the
5343 non-branch tag <tag1> is attached to, preparing it to be a branch
5348 <branch_tag2> --> BR2
5349 <file> --> Symbol: TT1:1.4
5350 After --> Symbol: TT1:1.4, BR2:1.4.0.2
5352 rtag -b -r <branch_tag1> <branch_tag2>
5354 Adds the magic branch tag <branch_tag2> to the revision at the HEAD of
5355 (the highest revision number on) the branch labelled with
5356 <branch_tag1>, preparing it to be a branch point.
5359 <branch_tag1> --> BR1
5360 <branch_tag2> --> BR2
5361 <file> --> Symbol: BR1:1.2.0.2 (1.2.2.5 is HEAD)
5362 After --> Symbol: BR1:1.2.0.2,BR2:1.2.2.5.0.2
5364 If the branch tagged by <branch_tag1> has not been created, then the
5365 tag shows up as a second branch off the same branch point revision:
5368 <branch_tag1> --> BR1
5370 <file> --> Symbols: BR1:1.2.0.2 (No 1.2.X exists.)
5371 After --> Symbols: BR1:1.2.0.2,TT2:1.2.0.4
5373 In all four cases above, if <tag2> already exists on the file, you get
5374 an error unless you specify the '-F' option.
5376 In all four cases, if <tag1> does not exist on the file, <tag2> is not
5377 added unless you specify the '-f' option.
5379 Last modified: _6/13/1997_
5381 4. What happens if the tags are the same in "rtag -r <tag> <tag>"?
5383 Again, there are four cases depending on whether <tag> is a branch
5384 tag, or a non-branch tag and on whether you use the '-b' option to
5389 Is a no-op. It does nothing even with '-F' specified.
5391 If you add the '-f' option ("rtag -f -r <tag> <tag>"), then <tag> is
5392 attached to the latest revision on the Main Branch if the file does
5393 *not* already have <tag> on some revision.
5395 If the <tag> is already on the file, using "rtag -f" is still a no-op.
5397 rtag -r <branch_tag> <branch_tag>
5399 Produces an error, since the <branch_tag> is already on some revision
5402 But, "rtag -F -r <branch_tag> <branch_tag>" turns the magic branch tag
5403 into a non-branch tag.
5405 Symbols: BR1:1.4.0.2 becomes Symbols: BR1:1.4
5407 rtag -b -r <tag> <tag>
5409 Produces an error, since the <tag> is already on the file.
5411 But, "rtag -F -b -r <tag> <tag>" turns the non-branch tag into a magic
5414 Symbols: BR1:1.4 becomes Symbols: BR1:1.4.0.2
5416 rtag -b -r <branch_tag> <branch_tag>
5418 Produces an error, since the <branch_tag> is already on the file.
5420 But, "rtag -F -b -r <branch_tag> <branch_tag>" increments the branch
5421 number. It essentially removes the branch and creates a new one by the
5424 Symbols: BR1:1.2.0.4 becomes Symbols: BR1:1.2.0.6
5426 Last modified: _6/13/1997_
5428 5. Why doesn't "rtag -b -r <branch_tag1> <branch_tag2>" rename or duplicate
5431 None of the "tag" or "rtag" options rename anything. They only apply
5432 (or, with the '-F' option, move) tags to specific revisions in the
5435 See 3M.[3-4] above for details of how it works.
5437 To rename a non-branch tag, see 3O.9. To rename a magic branch tag,
5440 Last modified: _6/13/1997_
5442 Category: /Commands_/status_st_stat/
5444 " + "status", "st", "stat""
5446 1. What is "status" for?
5448 To display the status of files, including the revision and branch you
5449 are working on and the existence of "sticky" information.
5451 Last modified: _6/13/1997_
5453 2. Why does "status" limit the File: at the top to 17 characters?
5455 Designed that way to line up with other data. You can find the whole
5456 filename in the line beginning with "RCS version:", which is not
5459 Last modified: _6/13/1997_
5461 3. Why does it print "Sticky" lines when the values are "(none)"?
5463 Oversight. It should probably elide lines without information.
5465 Last modified: _6/13/1997_
5467 4. Shouldn't the status "Needs Checkout" be "Needs Update"?
5471 [[Did this show up in CVS 1.4?]]
5473 Last modified: _6/13/1997_
5475 Category: /Commands_/tag_ta_freeze/
5477 " + "tag", "ta", "freeze""
5479 1. What is "tag" for?
5481 To add a symbolic label (a "tag") to the RCS files last checked out,
5482 updated or committed in a working directory.
5484 Last modified: _6/13/1997_
5486 2. What is the difference between "tag" and "rtag"?
5488 The end result of both commands is that a <tag>, or symbolic name, is
5489 attached to a single revision in each of a collection of files.
5491 The differences lie in:
5493 The collection of files they work on.
5495 "rtag" works on the collection of files referred to by a "module" name
5496 as defined in the "modules" file, or a relative path within the
5499 "tag" works on files and directories specified on the command line
5500 within the user's working directory. (Default is '.')
5502 Both commands recursively follow directory hierarchies within the
5503 named files and directories.
5505 The revisions they choose to tag.
5507 "rtag" places a tag on the latest committed revision of each file on
5508 the branch specified by the '-r' option. By default it tags the Main
5511 "tag" places a tag on the BASE (i.e. last checked out, updated or
5512 committed) revision of each file found in the working directory. (The
5513 BASE revision of a file is the one stored in the ./CVS/Entries file.)
5515 A different set of command line options.
5517 For example, "rtag" takes a "-r <oldtag>" option to retag an existing
5518 tag. The "tag" command does not.
5522 Currently "rtag" records the <tag> and the module in the "history"
5523 file, while "tag" does not.
5525 Last modified: _6/13/1997_
5527 3. Why does "tag -b" not put a tag on the Branch Point revision? How do I
5528 refer to the Branch Point?
5530 This is probably an oversight, or a disbelief in the need for it. If
5531 everything works perfectly, the "update -j" command will do the merge
5532 you need and you don't need to check up on it by playing with the
5533 branch point revision.
5535 The '-b' option attaches a magic branch tag to allow CVS later to
5536 figure out the branch point. The actual revision that <tag> is
5537 attached to does not exist. References to the branch tag are
5538 equivalent to references to the latest revision on the branch.
5540 There is no way to refer to the branch point without adding a
5541 non-branch tag. You might want to add non-branch tags as a habit and
5542 add branch tags later, possibly immediate after adding the non-branch
5543 tag. See 4C.3 on Creating a Branch.
5545 Last modified: _6/13/1997_
5547 4. So "{r}tag" labels a bunch of files. What do you use a Tag for?
5549 You use it to "checkout" the labeled collection of files as a single
5550 object, referring to it by name.
5552 Anywhere a revision number can be used a Tag can be used. In fact tags
5553 are more useful because they draw a line through a collection of
5554 files, marking a development milestone.
5556 The way to think about a Tag is as a curve drawn through a matrix of
5557 filename vs. revision number. Consider this:
5559 Say we have 5 files (in some arbitrary modules, some may be in 2 or
5560 more modules by name, some may be in 2 or more modules because of the
5561 Repository tree structure) with the following revisions:
5563 file1 file2 file3 file4 file5
5565 1.1 1.1 1.1 1.1 /--1.1* <-*- <tag>
5566 1.2*- 1.2 1.2 -1.2*-
5567 1.3 \- 1.3*- 1.3 / 1.3
5572 At some time in the past, the '*' versions were tagged. Think of the
5573 <tag> as a handle attached to the curve drawn through the tagged
5574 revisions. When you pull on the handle, you get all the tagged
5575 revisions. Another way to look at it is that you draw a straight line
5576 through the set of revisions you care about and shuffle the other
5577 revisions accordingly. Like this:
5579 file1 file2 file3 file4 file5
5585 1.2*----1.3*----1.5*----1.2*----1.1 (--- <-- Look here
5590 I find that using these visual aids, it is much easier to understand
5591 what a <tag> is and what it is useful for.
5593 Last modified: _6/13/1997_
5595 5. How do I get "tag" and "rtag" to send mail the way "commit" does?
5597 The "commit" command is supported by two files ("commitinfo" and
5598 "loginfo") not used by other commands. To do logging the same way for
5599 "tag" and "rtag" would require another file like loginfo, which
5600 currently doesn't exist.
5602 The "rtag" command requires a "module" entry, which can specify a
5603 "tag" program using the "-t programname" option on the module line.
5605 There is no equivalent support for "tag".
5607 Last modified: _6/13/1997_
5609 6. Why can't "tag" handle the '-r' option that "rtag" takes?
5611 Oversight. The answer is probably "Fixed in a Future Release."
5613 Last modified: _6/13/1997_
5615 7. After a "tag <tag>" in my working directory, why doesn't "checkout -r
5616 <tag>" somewhere else produce copies of my current files?
5618 The only reason this would fail, other than misspelling the <tag>
5619 string, is that you didn't "commit" your work before "tagging" it.
5620 Only committed revisions may be tagged. Modified files are not marked
5623 Last modified: _6/13/1997_
5625 8. Why doesn't "tag" write a history record the way "rtag" does?
5627 The "rtag" command was originally intended to place major "release"
5628 tags onto modules. The "tag" functionality was developed to *move* the
5629 more significant tag when slight changes to individual files sneaked
5630 in after the release tag was stamped onto the Repository.
5632 The significant event was the "rtag", which was recorded in the
5633 "history" file for the "history -T" option to work.
5635 It turns out that "tag" is generally more useful than "rtag", so the
5636 model has changed. Future revisions of CVS will probably store both
5637 kinds of tags in the history file.
5639 Last modified: _6/13/1997_
5641 9. How do I rename a <tag>?
5643 For a procedure to rename a branch tag, See section 4D.5 The following
5644 covers only non-branch tags.
5646 First, pick a <newtag> that is not in use. You could reuse (i.e. move)
5647 an existing tag to the new revisions using the '-F' option, but that
5648 will confuse matters when both tags are not already on a file. (It
5649 will probably confuse "rtag -f" too.)
5651 Use "rtag" to place <newtag> only on revisions attached to <oldtag> in
5652 the whole Repository, then delete the old one.
5654 cvs rtag -r <oldtag> <newtag> world
5655 cvs rtag -d <oldtag> world.
5657 You can also checkout or update your working directory to the <oldtag>
5658 and "tag" rather than "rtag" the result. But that will take longer and
5659 it has the chance of producing conflicts.
5661 cvs update -r <oldtag>
5664 cvs update -A (or cvs update -r <previous_tag>)
5666 Last modified: _6/13/1997_
5668 Category: /Commands_/update_up_upd/
5670 " + "update", "up", "upd""
5672 1. What is "update" for?
5674 The "update" command is by far the most important command and is
5675 probably also the most used command.
5677 It has five purposes: (And many options.)
5679 To display the status of your working files.
5681 Though a plain "update" also displays the status, it does so after
5682 possibly altering your working directory. To see the status of your
5683 working files without changing anything, type:
5685 cvs -n update {optional list of files}
5687 To merge changes made by others to the branch you are working on
5688 into your working files.
5690 Each working directory is attached to a branch, usually the Main
5691 branch. To merge changes made on your working branch since your last
5692 checkout, update or commit, type:
5694 cvs update {optional list of files}
5696 To merge changes made on another branch into the branch you are
5697 working on (your "working branch").
5699 If you want to grab a whole branch, from the branch point, which is
5700 assumed to be on the Main Branch, to the end of the branch, you type:
5702 cvs update -j <branch_tag> {optional files}
5704 If you want to grab the changes made between two tags or revisions,
5707 cvs update -j <tag1> -j <tag2> {optional files}
5709 (If you are working with a single file, the Tags could also be
5710 revisions numbers. Unless you take great care to match revision
5711 numbers across different files (a waste of time given the way Tags
5712 work), using revision numbers in place of the Tags for multiple files
5713 would be meaningless.)
5715 To move your working directory to another branch.
5717 A working directory is presumed to be attached to (or working on) a
5718 particular branch, usually the Main branch. To alter what CVS believes
5719 to be your working branch, you "move" to that branch.
5721 To move to a tagged branch, type:
5723 cvs update -r <branch_tag> {optional files}
5725 To move to the Main Branch, type:
5727 cvs update -A {optional files}
5729 If you have modified files in your working directory, this is not a
5730 clean move. CVS will attempt to merge the changes necessary to make it
5731 look like you made the same changes to the new branch as you made in
5732 the old one. But if you do this twice without resolving the merge
5733 conflicts each time, you can lose work.
5735 To retrieve old revisions of files.
5737 This option is similar to 4 above but you are not restricted to using
5738 a <branch_tag>. You may specify any revision or <tag> with '-r' and
5739 get the specified revision or the tagged revision:
5741 cvs update -r <tag/rev> {optional files}
5743 Or you may specify any date with '-D':
5745 cvs update -D <date> {optional files}
5747 The '-p' option sends the revisions to standard output (normally your
5748 terminal) rather than setting the "sticky" tag and changing the files.
5750 Last modified: _6/13/1997_
5752 2. What do 'U', 'M' and 'C' mean when I type "update"? Are they different
5753 for "cvs -n update"?
5755 "cvs update" merges changes made to the Repository, since your last
5756 "checkout", "update" or "commit", into your working files. You can
5757 think of it as changing your BASE revision.
5759 "cvs update" prints lines beginning with:
5761 'U' after replacing your unmodified file with a different
5762 revision from the Repository.
5764 'M' for two different reasons:
5766 for files you have modified that have not changed in the Repository.
5768 after a merge, if it detected no conflicts.
5770 'C' after a merge, if it detected conflicts. See 2D.7 and 3P.6 for
5771 more info on conflict resolution and "sticky conflicts."
5773 "cvs -n update" shows what it *would* do, rather than doing it. Or,
5774 another way of looking at it, "cvs -n update" displays the
5775 relationship between your current BASE revisions (identified in your
5776 ./CVS/Entries file) and the HEAD revisions (the latest revisions in
5779 "cvs -n update" prints lines beginning with:
5781 'U' for files you have not modified that have changed in the
5784 'M' for files you have modified that have not changed in the
5787 'C' for files you have modified that have also been changed in the
5790 See 4C.6 for what the letters mean when merging in from another
5791 branch. The output is almost the same for a normal update if you
5792 consider the Repository as the branch and your working directory as
5795 Last modified: _6/13/1997_
5797 3. What's the difference between "update" and "checkout"?
5801 Last modified: _6/13/1997_
5803 4. Why don't I get new files when I execute "update"?
5805 There are six reasons for nothing to happen during an "update":
5807 Nothing on your branch changed in the Repository.
5809 If no one has committed anything to the branch you are working on
5810 (normally the Main branch) since the last time you executed
5811 "checkout", "update" or "commit", nothing will happen.
5813 It's like shouting "xyzzy" or "plugh" in the wrong room.
5815 You have a "sticky" non-branch <tag> or <date> attached to the
5816 working files you are trying to "update".
5818 At some time in the past you checked out or updated your directory
5819 with the "-r <tag>" or "-D <date>" option. Until you do it again with
5820 a different tag or date, or go back to the Main Branch with "update
5821 -A", you will never again see any updates.
5823 The ./CVS/Entries.Static file exists and you are expecting a new
5826 If your ./CVS administrative directory contains a file named
5827 Entries.Static, no files will be checked out that aren't already in
5828 the Entries or Entries.Static file.
5830 You forgot to use the '-d' option and are looking for new
5833 If you execute "update" without the '-d' option, it will not create
5834 new directories that have been added to the Repository.
5836 You typed "update" instead of "cvs update".
5838 On most Unix systems, your disk caches are now furiously being flushed
5839 by multiple update daemons, destroying performance and proving to
5840 management that you need more CPU power. :-)
5842 On HP systems you might be asked what package you want to install from
5843 the "update server".
5845 Someone removed (using "admin -o") your BASE revision (the revision
5846 CVS thought you had in your working directory), then committed a
5847 "replacement". CVS is now confused because the revision in the
5848 Repository matches your BASE revision when the files themselves don't
5851 Last modified: _6/13/1997_
5853 5. Why does "update" say 'M' both for plain modified files and for
5854 successful (i.e. conflict-free) merges? Aren't they different?
5856 A design choice. Yes, they are different internally, but that
5857 shouldn't matter. Your files are in the same condition after the
5858 "update" as they were before -- a "diff" will display only your
5859 modifications. And you are expected to continue onward with parts two
5860 and three of the normal development cycle: "emacs" (a synonym for
5861 "edit" in most of the civilized world) and "commit".
5863 Last modified: _6/13/1997_
5865 6. What's a "sticky conflict"? How does it know a conflict occurred?
5867 When a "cvs update" (or an "update -j") creates a conflict, it prints
5868 a 'C' and stores the timestamp of the file after the merge in a
5869 special field in the ./CVS/Entries file.
5871 This conflict indication implies that the merge command altered your
5872 working file to contain conflict markers surrounding the overlapping
5873 code segments. For example, say that
5875 - Two developers acquire revision 1.2 of <file> via "checkout" or
5878 - Developer A changes line 1 from "9999" to "5555", then commits the
5879 file, creating revision 1.3.
5881 - Developer B changes line 1 from "9999" to "7777", then tries to
5882 commit the file, but is blocked because the file is not up to date.
5883 Developer B then runs "update" and sees the conflict marker 'C'. The
5884 beginning of the file would look like this:
5886 <<<<<<< <file> The working <file> in question.
5887 7777 Change made to the working <file>.
5889 5555 Change made in the first commit (1.3)
5890 >>>>>>> 1.3 The revision created by the first commit.
5892 The conflict is "sticky", which means that until the conflict is
5893 cleared, the "update" command will continue to display the file's
5894 status as 'C' and the "status" command will show the file's status as
5895 "Unresolved Conflict".
5897 Until the conflict is cleared, "commit" is blocked for this file.
5899 The sticky conflict indicator can be cleared by:
5901 Resolving the conflict by editing the file. Two things must happen
5902 before the conflict is considered resolved:
5904 The timestamp of the file must change. *and* The file must contain no
5905 conflict markers. (The string searched for in the file is the regexp:
5908 After clearing the sticky conflict indicator, you may then commit the
5911 Removing the file and running "update". This throws away the local
5912 changes and accepts the latest committed file on this branch. No
5915 Forcing the commit to happen by using "commit -f". This is probably
5916 a mistake since there are few lines of real text that begin with
5919 Last modified: _6/13/1997_
5921 7. Is there a feature to tell me what I have changed, added and removed
5922 without changing anything?
5924 The command "cvs -n update" will do exactly that.
5926 Last modified: _6/13/1997_
5928 8. Why were all my files deleted when I executed "update"?
5930 You probably executed "update -r <tag>" some time ago, then removed
5931 <tag> from the Repository files. "update -r <tag>" will delete a file
5932 that doesn't contain <tag>.
5934 A way to fix this is to "cd" into your working directory and type:
5938 If you don't want the latest revisions on the Main (or Vendor) Branch,
5939 then decide what Tag (normal or branch) you want and type:
5941 cvs update -r <the_tag_you_want>
5943 Another way to make a file disappear is to execute "update -D <date>"
5944 where <date> is before the date stamped onto the first revision in the
5947 Last modified: _6/13/1997_
5949 Category: /Past__Future_/
5953 Category: /Past__Future_/Bugs_and_Patches/
5955 " + Bugs and Patches"
5957 1. Why can't CVS handle deletion of directories?
5959 An oversight, probably. [[Fixed in a future release?]]
5961 Last modified: _6/13/1997_
5963 2. Why can't CVS handle the moving of sources from one place in the
5965 directory hierarchy to another?
5967 A "renaming database" has been proposed to track the history of
5968 pathname changes in the Repository. A general solution is a difficult
5971 Last modified: _6/13/1997_
5973 3. When I typed "cvs update -D <date>", why did it check out all
5975 sorts of ancient files from the Attic? Shouldn't it just create the
5976 set of files and revisions that existed at that date?
5978 This seems to be a bug, but is really the lack of any obvious place to
5979 store the date when a file is "removed".
5981 There are four ranges of dates that CVS has to deal with when trying
5982 to determine what revision was available on <date>:
5984 Dates before the earliest revision in the file.
5986 Dates between any two revisions in the file.
5988 Dates between the latest revision in the file and the date when the
5989 file was moved to the Attic by "commit".
5991 Dates after moving the file to the Attic.
5993 Since the date when a file is moved to the Attic is not stored
5994 anywhere, CVS can't tell the difference between #3 and #4. To avoid
5995 not producing a file that should exist in case #3, it produces
5996 extraneous files in case #4.
5998 For the above reason, if you have removed files in the Attic, it is
5999 better to use "-r <tag>, or even "-r HEAD" than to use a date spec.
6001 If you must use "-D <date>", then you should either archive and delete
6002 Attic files (losing some past history) or construct your Makefiles to
6003 work with an explicit list of files and let the old source files stay
6004 in the working directory. The contents of the revision-controlled
6005 Makefile can then be considered to contain deletion "information".
6007 Last modified: _6/13/1997_
6009 4. When I typed "cvs update -D <date>" in my branch, why did it screw up
6012 Currently, the internal routine ("version_ts") that looks up info
6013 about a file, overrides both the tag and date if *either* the tag or
6014 date is specified on the command line. If only the date is specified,
6015 it should not override a branch tag, but it does.
6017 In CVS 1.3, the documented "-D <branch_tag>:<date>" syntax only works
6018 with the Main Branch and the Vendor Branch.
6020 [[Is this fixed in CVS 1.4? This is one item I didn't check.]]
6022 Last modified: _6/13/1997_
6024 5. When I executed "checkout" into an existing directory I got "No such
6025 file or directory" errors. Why?
6027 Though the man page says that "checkout" turns into an "update -d" in
6028 directories that already exist, it is referring to directories that
6029 already exist *and* were created by CVS.
6031 When you try to run "checkout" on top of an existing directory
6032 structure, some of which wasn't created by CVS, it will handle
6033 directories and non-CVS files within directories already under CVS,
6034 but it will display the above error on non-CVS files within non-CVS
6037 Last modified: _6/13/1997_
6039 6. Why does "update" send all output to the terminal after 26 files have
6042 CVS uses the "tmpnam()" function to generate temporary file names. The
6043 ANSI standard for the "tmpnam()" function says:
6045 "The tmpnam function generates a different string each time it is
6046 called, up to TMP_MAX times. If it is called more than TMP_MAX times,
6047 the behavior is implementation defined."
6049 Later it says that the value of "TMP_MAX shall be at least 25."
6051 On some platforms, the above specification is taken literally by
6052 turning "at least 25" into "exactly 26" and by doing something foolish
6053 (i.e. "implementation defined") after that. Some systems return the
6054 same name repeatedly, which causes one form of trouble. Others return
6055 NULL or garbage, which causes a different form of trouble.
6057 The broken systems appear to be cycling a single character through the
6058 alphabet. SunOS cycles 3 characters through the alphabet, so it won't
6059 cause trouble until 26 cubed or 17576 calls to "tmpnam()".
6061 Since CVS doesn't depend on the exact format of the tmp files, the
6062 workaround is to provide a "tmpnam()" that doesn't have a limit on the
6063 number of calls to it.
6065 Last modified: _6/13/1997_
6067 7. Why does the merge occasionally resurrect lines of code?
6069 The diff3 program provided by GNU diff version 1.15 has a bug that
6070 occasionally causes text to come back from the dead.
6072 This is an old problem which you can avoid by upgrading to the latest
6073 GNU "diffutils" package. If you were using GNU diff version 1.15 and
6074 plan to upgrade to the latest GNU diff program, see the next question.
6076 Last modified: _6/13/1997_
6078 8. Why does the merge fail when my "rcsmerge" program is configured to use
6079 GNU diff version 2.1 or later?
6081 A change in the overlap format was introduced in GNU diff3 between
6082 versions 2.0 and 2.1 that causes RCS versions before 5.6.0.1 to fail
6085 To get consistent rcsmerge behavior, you have four choices:
6087 Go back to using GNU diff 1.15 or 2.0 with RCS versions 5.5 or 5.6.
6088 If you want to use GNU diff 2.1 or later, you'll have to pick one of
6089 the other three choices in this list.
6091 Grab RCS version 5.6.0.1 from an FSF archive and set the DIFF3_A
6092 macro to '1' as it tells you to in the Makefile:
6096 Patch the RCS 5.6 source. Change line 84 in "merger.c" from:
6098 DIFF3, "-am", "-L", label[0], "-L", label[1], to DIFF3, "-amE", "-L",
6099 label[0], "-L", "", "-L", label[1],
6101 Wait both for RCS version 5.7 to be released and for a new version
6102 of CVS that can deal with it.
6104 Last modified: _6/13/1997_
6106 Category: /Past__Future_/Contributors/
6112 Brian Berliner <berliner@sun.com> converted a collection of scripts
6113 written by Dick Grune <dick@cs.vu.nl> into a C program, then added all
6114 sorts of features. He continues to maintain CVS.
6116 Jeff Polk <polk@bsdi.com> wrote much of the code added between
6117 revisions 1.2 and 1.3. Many others were involved at some level.
6119 david d zuhn <zoo@armadillo.com> fixed a number of bugs, added some of
6120 the new features, reworked the whole thing to be more portable, and
6121 provided much of the energy to push CVS 1.4 out the door.
6123 Jim Kingdon implemented CVS 1.5's remote repository access features,
6124 fixed many bugs, and managed the release of version 1.5.
6126 Take a look at the README and the ChangeLog files in the CVS sources
6127 for more contributors.
6129 Last modified: _6/13/1997_
6131 2. You didn't write all of this FAQ, did you?
6133 In the original hunt for questions to answer (performed in Jan/Feb,
6134 1993), I polled hundreds of people and I rephrased all sorts of text
6135 found on the net. Between 2/93 and 10/93, I released about 20
6136 versions, with corrections and additions from the info-cvs mailing
6137 list and private correspondence.
6139 Between 10/93 and 10/94 I extracted frequently asked questions from
6140 the 1200 mail messages to the info-cvs mailing list, turned them into
6141 focused questions and tried to answer them.
6143 93/02/?? ~4000 lines 93/06/?? ~5000 lines 93/10/23 7839 lines 278K
6144 94/10/29 9856 lines 360K 95/05/09 9981 lines 365K
6146 Because there are so many posers of questions, I will list only those
6147 who contribute answers or help significantly with the content and
6148 structure of this document.
6150 If I used someone else's text verbatim, I mentioned it in the given
6151 answer. The people whose email postings have added to this document or
6152 who have added to my understanding are:
6154 Brian Berliner <berliner@sun.com>, CVS maintainer. Paul Eggert
6155 <eggert@twinsun.com>, RCS maintainer.
6157 Gray Watson <gray@antaire.com> Per Cederqvist <ceder@signum.se> Pete
6158 Clark <pclark@is.com>
6160 all of whom have sent me copies of their tutorials and local CVS
6163 Additional contributors, who have sent me ideas, text, corrections and
6164 support include (in alphabetical order):
6166 Per Abrahamsen <amanda@iesd.auc.dk> Donald Amby
6167 <amby@mixcom.mixcom.com> Mark D Baushke <mdb@cisco.com> Jim Blandy
6168 <jimb@cyclic.com> Tom Cunningham <tomc@bouwsma,sps.mot.com> Graydon
6169 Dodson <grdodson@lexmark.com> Joe Drumgoole
6170 <joed@splatter.demon.co.uk> Don Dwiggins <dwig@markv.com> Bryant
6171 Eastham <bryant@ced.utah.edu> Dan Franklin <dan@diamond.bbn.com>
6172 Michael Ganzberger <ganzbergermd@ES.net> Steve Harris
6173 <vsh%etnibsd@uunet.uu.net> Erik van Linstee
6174 <linstee@dutecaj.et.tudelft.nl> Jeffrey M Loomis <jml@world.std.com>
6175 Barry Margolin <barmar@near.net> Mark K. Mellis <mkm@ncd.com> Chris
6176 Moore <Chris.Moore@src.bae.co.uk> Gary Oberbrunner <garyo@avs.com>
6177 Steve Turner <stevet@carrier.sps.mot.com> Dave Wolfe
6178 <dwolfe@pffft.sps.mot.com> Dale Woolridge <dwoolridge@cid.aes.doe.ca>
6180 Please send corrections. If I forgot you, remind me and I'll add your
6183 Last modified: _6/13/1997_
6185 Category: /Past__Future_/Development/
6189 1. Where do I send bug reports?
6191 First make sure it is a bug. Talk to your friends, coworkers and
6192 anyone you know who uses CVS. Search this FAQ for related issues. Then
6193 test it carefully. Try out variations to narrow down the problem. Make
6194 sure it is repeatable. Look for workarounds so you can report them.
6196 If you are still sure it's a bug and you tried to fix it, skip to the
6197 next question. Otherwise, send a message to the info-cvs mailing list
6198 containing one of the following:
6200 If you have a good repeatable case and you think you know what is
6201 going on, then describe the problem in detail. Include a workaround if
6204 If you have no idea what is going on, go ahead and send a question
6205 to the info-cvs mailing list. Include any information you have
6206 describing the symptoms.
6208 Last modified: _6/13/1997_
6210 2. Where do I send fixes and patches?
6212 First make sure the "fix" does something useful. Have someone review
6213 your fix. Spend a bit of one person's time in a detailed analysis of
6214 your vast idea before displaying a half-vast idea to hundreds of
6217 If you tried to fix it and the patch is small, include the patch in
6218 your message. Make sure the patch is based on the latest released
6221 If you tried to fix it and the patch is large, you should think about
6222 why it is so large. Did you add a generally useful feature, or did it
6225 If you still believe it is solid, produce a patch file using the CVS
6226 commands "patch" or "diff -c". [[You *are* keeping CVS under CVS,
6227 right?]] The patch should be based on the latest released version of
6228 CVS. Then use the "cvsbug" program (provided with the CVS sources) to
6229 send it to the CVS maintainers. A self-contained patch that provides a
6230 single useful feature or correction might show up independently in the
6231 patches directory of the FTP archive.
6233 If careful testing reveals an RCS bug rather than a CVS bug, you can
6234 send bug reports to: rcs-bugs@cs.purdue.edu
6236 Last modified: _6/13/1997_
6238 3. Where do I send ideas for future development?
6240 If you have a bright idea, discuss it on the info-cvs mailing list. If
6241 you have the time to implement something you can test, send the diffs
6242 along too as described above.
6244 Last modified: _6/13/1997_
6246 4. What plans are there for new features?
6250 A "rename" or "per-directory" database has been bandied about on
6251 the net for years. Many of the goals of the rename database have
6252 been achieved by the so-called "death support" in recent versions of
6253 CVS (such as 1.9). For more information on what may remain to be
6254 done, see item #189 in the TODO file of a development version of CVS.
6256 CVS version 1.5 supports remote repository access, but Paul
6257 Kunz has produced another version
6258 (rCVS) that also runs remotely. Note that as far as I know there
6259 are no advantages to rCVS over the remote CVS in CVS 1.5 and later,
6260 and the rCVS user community has migrated to remote CVS.
6261 rCVS is *not* a multisite CVS (see item #186 in TODO for more on
6262 multisite). For more on rCVS, see
6264 ftp://ftp.slac.stanford.edu/software/rcvs
6268 Last modified: _9/6/1997_
6270 5. I have some time and I'd like to help. What can I do for you?
6273 You can review this document, correct errors and fill in any of
6274 the incomplete sections.
6276 You can write scripts or CVS add-ons and make them available by
6279 You could work on the regression test suite (src/sanity.sh in the
6280 CVS source distribution).
6282 You can write specs for new features, fix bugs, review the
6283 documentation or . . .
6285 For more information, see the files HACKING and DEVEL-CVS in the
6286 CVS source distribution or
6287 http://www.cyclic.com/cyclic-pages/cvsdev.html
6291 Last modified: _9/6/1997_
6293 Category: /Past__Future_/Professional_Support/
6295 " + Professional Support"
6297 1. Doesn't Cygnus support CVS?
6302 Cygnus is a company that supports free software such as the GCC
6303 compiler. They have never sold support for CVS, however. They
6304 do use CVS internally and have contributed much code to CVS over
6305 the years (for which CVS users should be grateful).
6309 Last modified: _9/6/1997_
6311 2. What is Cyclic Software doing with CVS?
6314 Cyclic Software exists to provide support for CVS. For details such
6315 as prices and what this covers, see http://www.cyclic.com or ask
6320 Last modified: _9/6/1997_
6322 Category: /User_Tasks_/
6326 Category: /User_Tasks_/Common_User_Tasks/
6328 " + Common User Tasks"
6330 1. What is the absolute minimum I have to do to edit a file?
6332 Tell your Repository Administrator to create a module covering the
6333 directory or files you care about. You will be told that your module
6334 name is <module>. Then type:
6336 cvs checkout <module>
6338 emacs <file> # Isn't Emacs a synonym for edit?
6341 If you don't use modules (in my opinion, a mistake), you can check out
6342 a directory by substituting its relative path within the Repository
6343 for <module> in the example above.
6345 To work on a single file, you'll have to change "cd <module>" to "cd
6346 `dirname <module>`".
6348 Last modified: _6/13/1997_
6350 2. If I edit multiple files, must I type "commit" for each one?
6352 No. You can commit a list of files and directories, including relative
6353 paths into multiple directories. You can also commit every modified
6354 file in the current directory or in all directories and subdirectories
6355 from your current directory downward. See 3D.2.
6357 Last modified: _6/13/1997_
6359 3. How do I get rid of the <module> directory that "checkout" created?
6361 Change your directory to be the same as when you executed the
6362 "checkout" command that created <module>.
6364 If you want to get rid of the CVS control information, but leave the
6365 files and directories, type:
6367 cvs release <module>
6369 If you want to obliterate the entire directory, type:
6371 cvs release -d <module>
6373 ("release -d" searches through the output of "cvs -n update" and
6374 refuses to continue if the "update" command finds any modified files
6375 or non-ignored foreign files. Foreign directories too.)
6377 If you don't care about keeping "history", or checking for modified
6378 and foreign files, you can just remove the whole directory. That's "rm
6379 -rf <module>" under Unix.
6381 Last modified: _6/13/1997_
6383 4. How do I find out what has changed since my last update?
6385 There are many ways to answer this.
6387 To find out what you've changed in your current working directory
6388 since your last checkout, update or commit, type:
6392 To find out what other people have added (to your branch) since you
6393 last checked out or updated, type:
6395 cvs diff -r BASE -r HEAD
6397 To look at a revision history containing the comments for all changes,
6398 you can use the "log" command.
6400 You can also use "history" to trace a wide variety of events.
6402 Last modified: _6/13/1997_
6404 5. I just created a new file. How do I add it to the Repository?
6406 The "update" command will mark files CVS doesn't know about in your
6407 working directory with a '?' indicator.
6411 To add <file> to the Repository, type:
6416 See 3A.[2-5] and 4C.8 for branch and merge considerations.
6418 Last modified: _6/13/1997_
6420 6. How do I merge changes made by others into my working directory?
6422 If you are asking about other branches, see Section 4C on "Branching".
6423 You will have to use the "update -j" command.
6425 Retrieving changes made to the Repository on the *same* branch you are
6426 working on is the main purpose of the "update" command. The "update"
6427 command tries to merge work committed to the Repository by others
6428 since you last executed "checkout", "update" or "commit" into your
6431 For a single file, there are six possible results when you type the
6434 If the file is lying in your working directory, but is not under
6435 CVS, it will do nothing but print:
6439 If neither you nor anyone else has committed changes to <file>,
6440 since your last "checkout", "update" or "commit", "update" will print
6441 nothing and do nothing.
6443 If you have made no changes to a working file, but you or others
6444 have committed changes to the Repository since your last "checkout",
6445 "update" or "commit" of this working file, CVS will remove your
6446 working file and replace it with a copy of the latest revision of that
6447 file in the Repository. It will print:
6451 You might want to examine the changes (using the CVS "diff" command)
6452 to see if they mesh with your own in related files.
6454 If you have made changes to a working file, but no one has changed
6455 your BASE revision (the revision you retrieved from the Repository in
6456 your last "checkout", "update" or "commit"), "update" will print:
6460 Nothing changes. You were told that you have a modified file in your
6463 If you have made changes to your working file and you or others have
6464 committed changes to the Repository, but in different sections of the
6465 file, CVS will merge the changes stored in the Repository since your
6466 last "checkout", "update" or "commit" into your working file. "update"
6469 RCS file: /Repository/module/<file> retrieving revision 1.X retrieving
6470 revision 1.Y Merging differences between 1.X and 1.Y into <file> M
6473 If you execute "diff" before and after this step, you should see the
6474 same output, since both the base file and your working file changed in
6475 parallel. This is one of the few times the otherwise nonsensical
6476 phrase "same difference" means something.
6478 If both you and those who committed files (since your last checkout,
6479 update or commit) have made changes to the same section of a file, CVS
6480 will merge the changes into your file as in #5 above, but it will
6481 leave conflict indicators in the file. "update" will print:
6483 RCS file: /Repository/module/<file> retrieving revision 1.X retrieving
6484 revision 1.Y Merging differences between 1.X and 1.Y into <file>
6485 rcsmerge warning: overlaps during merge
6486 cvs update: conflicts found in <file>
6489 This is a "conflict". The file will contain markers surrounding the
6490 overlapping text. The 'C' conflict indicator is sticky -- subsequent
6491 "update" commands will continue to show a 'C' until you edit the file.
6493 You must examine the overlaps with care and resolve the problem by
6494 analyzing how to retain the features of both changes. See 2D.7 and
6495 3P.6 for more details on conflict resolution.
6497 Last modified: _6/13/1997_
6499 7. How do I label a set of revisions so I can retrieve them later?
6501 To "tag" the BASE revisions (the ones you last checked out, updated,
6502 or committed) you should "cd" to the head of the working directory you
6503 want to tag and type:
6507 It recursively walks through your working directory tagging the BASE
6508 revisions of all files.
6510 To "tag" the latest revision on the Main branch in the Repository, you
6511 can use the following from anywhere: (No "cd" is required -- it works
6512 directly on the Repository.)
6514 cvs rtag <tag> <module>
6516 Last modified: _6/13/1997_
6518 8. How do I checkout an old release of a module, directory or file?
6520 Module names and directories are simply ways to name sets of files.
6521 Once the names are determined, there are 6 ways to specify which
6522 revision of a particular file to check out:
6524 By tag or symbolic name, via the "-r <tag>" option.
6526 By date, via the "-D <date>" option.
6528 By branch tag (a type of tag with a magic format), via the "-r
6529 <branch_tag>" option.
6531 By date within a branch, via the "-r <branch_tag>:<date>" option.
6533 By an explicit branch revision number ("-r <rev>"), which refers to
6534 the latest revision on the branch. This isn't really an "old"
6535 revision, from the branch's perspective, but from the user's
6536 perspective the whole branch might have been abandoned in the past.
6538 An explicit revision number: "-r <rev>" Though this works, it is
6539 almost useless for more than one file.
6543 cvs checkout <option-specified-above> <module>
6546 Last modified: _6/13/1997_
6548 9. What do I have to remember to do periodically?
6550 You should execute "cvs -n update" fairly often to keep track of what
6551 you and others have changed. It won't change anything -- it will just
6554 Unless you are purposely delaying the inclusion of others' work, you
6555 should execute "update" once in a while and resolve the conflicts. It
6556 is not good to get too far out of sync with the rest of the developers
6557 working on your branch.
6559 It is assumed that your system administrators have arranged for editor
6560 backup and Unix temp files (#* and .#*) to be deleted after a few
6561 weeks. But you might want to look around for anything else that is
6562 ignored or hidden. Try "cvs -n update -I !" to see all the ignored
6565 If you are the Repository Administrator, see 4B.16 on Administrator
6568 Last modified: _6/13/1997_
6570 Category: /User_Tasks_/General_Questions/
6572 " + General Questions"
6574 1. How do I see what CVS is trying to do?
6576 The '-t' option on the main "cvs" command will display every external
6577 command (mostly RCS commands and file deletions) it executes. When
6578 combined with the '-n' option, which prevents the execution of any
6579 command that might modify a file, you can see what it will do before
6580 you let it fly. The '-t' option will *not* display every internal
6581 action, only calls to external programs.
6583 To see a harmless example, try typing:
6587 Some systems offer a "trace" or "truss" command that will display all
6588 system calls as they happen. This is a *very* low-level interface that
6589 does not normally follow the execution of external commands, but it
6592 The most complete answer is to read the source, compile it with the
6593 '-g' option and step through it under a debugger.
6595 Last modified: _6/13/1997_
6597 2. If I work with multiple modules, should I check them all out and commit
6598 them occasionally? Is it OK to leave modules checked out?
6600 The simple answers are "Yes."
6602 There is no reason to remove working directories, other than to save
6603 disk space. As long as you have committed the files you choose to make
6604 public, your working directory is just like any other directory.
6606 CVS doesn't care whether you leave modules checked out or not. The
6607 advantage of leaving them checked out is that you can quickly visit
6608 them to make and commit changes.
6610 Last modified: _6/13/1997_
6612 3. What is a "sticky" tag? What makes it sticky? How do I loosen it?
6614 When you execute "update -r <tag>", CVS remembers the <tag>. It has
6615 become "sticky" in the sense that until you change it or remove it,
6616 the tag is remembered and used in references to the file as if you had
6617 typed "-r <tag>" on the command line.
6619 It is most useful for a <branch_tag>, which is a sticky tag indicating
6620 what branch you are working on.
6622 A revision number ("-r <rev-number>") or date ("-D <date>") can also
6623 become sticky when they are specified on the command line.
6625 A sticky tag, revision or date remains until you specify another tag,
6626 revision or date the same way. The "update -A" command moves back to
6627 the Main branch, which has the side-effect of clearing all sticky
6628 items on the updated files.
6630 The "checkout" command creates sticky tags, revisions and dates the
6631 same way "update" does.
6633 Also, the '-k' option records a "sticky" keyword option that is used
6634 in further "updates until "update -A" is specified.
6636 Last modified: _6/13/1997_
6638 4. How do I get an old revision without updating the "sticky tag"?
6640 Use the '-p' option to "pipe" data to standard output. The command
6641 "update -p -r <tag/rev>" sends the selected revision to your standard
6642 output (usually the terminal, unless redirected). The '-p' affects no
6643 disk files, leaving a "sticky tag" unaltered and avoiding all other
6644 side-effects of a normal "update".
6646 If you want to save the result, you can redirect "stdout" to a file
6647 using your shell's redirection capability. In most shells the
6648 following command works:
6650 cvs update -p -r <tag/rev> filename > diskfile
6652 Last modified: _6/13/1997_
6654 5. What operations disregard sticky tags?
6656 The functions that routinely disregard sticky tags are:
6658 Those that work directly on the Repository or its administrative
6661 admin rtag log status remove history
6663 Those that take Tags or revisions as arguments and ignore everything
6664 else: (They also never *set* a sticky tag.)
6668 The "release" command itself ignores sticky tags, but it calls "cvs
6669 -n update" (which *does* pay attention to a sticky tag) to figure out
6670 what inconsistencies exist in the working directory. If no
6671 discrepancies exist between the files you originally checked out
6672 (possibly marked by a sticky tag) and what is there now, "release -d"
6673 will delete them all.
6675 The "tag" command works on the revision lying in the working
6676 directory however it got there. That the revision lying there might
6677 happen to have a sticky tag attached to it is not the "tag" command's
6680 The main function that *does* read and write sticky tags is the
6681 "update" command. You can avoid referring to or changing the sticky
6682 tag by using the '-p' option, which sends files to your terminal,
6683 touching nothing else.
6685 The "checkout" command sets sticky tags when checking out a new module
6686 and it acts like "update" when checking out a module into an existing
6689 The "diff" and "commit" commands use the sticky tags, unless
6690 overridden on the command line. They do not set sticky tags. Note that
6691 you can only "commit" to a file checked out with a sticky tag, if the
6692 tag identifies a branch.
6694 There are really two types of sticky tags, one attached to individual
6695 files (in the ./CVS/Entries file) and one attached to each directory
6696 (in the ./CVS/Tag file). They can differ.
6698 The "add" command registers the desire to add a new file. If the
6699 "directory tag" (./CVS/Tag) file exists at the time of the "add", the
6700 value stored in ./CVS/Tag becomes the "sticky tag" on the new file.
6701 The file doesn't exist in the Repository until you "commit" it, but
6702 the ./CVS/Entries file holds the sticky tag name from the time of the
6705 Last modified: _6/13/1997_
6707 6. Is there a way to avoid reverting my Emacs buffer after committing a
6708 file? Is there a "cvs-mode" for Emacs?
6712 Last modified: _6/13/1997_
6714 7. How does conflict resolution work? What *really* happens if two of us
6715 change the same file?
6717 While editing files, there is no conflict. You are working on separate
6718 copies of the file stored in the virtual "branch" represented by your
6719 working directories. After one of you commits a file, the other may
6720 not commit the same file until "update" has merged the earlier
6721 committed changes into the later working file.
6723 For example, say you both check out rev 1.2 of <file> and make change
6724 to your working files. Your coworker commits revision 1.3. When you
6725 try to commit your file, CVS says:
6727 cvs commit: Up-to-date check failed for `<file>'
6729 You must merge your coworker's changes into your working file by
6734 which will produce the output described in 2B.6.
6736 If a conflict occurs, the filename will be shown with a status of 'C'.
6737 After you resolve any overlaps caused by the merging process, you may
6738 then commit the file. See 3P.6 for info on "sticky conflicts".
6740 Even if you get a simple 'M', you should examine the differences
6741 before committing the file. A smooth, error-free text merge is still
6742 no indication that the file is in proper shape. Compile and test it at
6745 The answer to two obvious questions is "Yes".
6747 Yes, the first one who commits avoids the merge. Later developers have
6748 to merge the earlier changes into their working files before
6749 committing the merged result. Depending on how difficult the merge is
6750 and how important the contending projects are, the order of commits
6751 and updates might have to be carefully staged.
6753 And yes, between the time you execute "update" and "commit" (while you
6754 are fixing conflicts and testing the results) someone else may commit
6755 another revision of <file>. You will have to execute "update" again to
6756 merge the new work before committing. Most organizations don't have
6757 this problem. If you do, you might consider splitting the file. Or
6760 Last modified: _6/13/1997_
6762 8. How can I tell who has a module checked out?
6764 If you "checkout" module names (not relative pathnames) and you use
6765 the release command, the "history" command will display active
6766 checkouts, who has them and where they were checked out. It is
6767 advisory only; it can be circumvented by using the '-l' option on the
6770 Last modified: _6/13/1997_
6772 9. Where did the .#<file>.1.3 file in my working directory come from?
6774 It was created during an "update" when CVS merged changes from the
6775 Repository into your modified working file.
6777 It serves the same purpose as any "backup" file: saving your bacon
6778 often enough to be worth retaining. It is invaluable in recovering
6779 when things go wrong.
6781 Say Developers A (you) and B check out rev 1.3 of file <file>. You
6782 both make changes -- different changes. B commits first, so <file>,v
6783 in the Repository contains revisions up through 1.4.
6785 At this point, there are 5 (yes, five) versions of the file of
6788 Revision 1.3 (What you originally checked out.)
6790 Revision 1.4 (What you need from developer B.)
6792 Your old working file. (Before the update.)
6794 Your new working file. (After the merge caused by "update".)
6796 Revision 1.5 (Which you will commit shortly.)
6798 In the case where your working file was not modified, #1 and #3 will
6799 be the same, as will #2 and #4. In this degenerate case, there is no
6800 need to create #5. The following assumes that your working file was
6803 If the merge executed by the "update" caused no overlaps, and you
6804 commit the file immediately, #4 and #5 will be the same. But you can
6805 make arbitrary changes before committing, so the difference between #4
6806 and #5 might be more than just the correction of overlaps. In general,
6807 though, you don't need #4 after a commit.
6809 But #3 (which is the one saved as ".#<file>.1.3") holds all of your
6810 work, independent of B's work. It could represent a major effort that
6811 you couldn't afford to lose. If you don't save it somewhere, the merge
6812 makes #3 *disappear* under a potential blizzard of conflicts caused by
6813 overlapping changes.
6815 I have been saved a few times, and others I support have been saved
6816 hundreds of times, by the ability to "diff <original file> <original
6817 file with only my work added>", which can be done in the example above
6818 by the Unix shell command:
6820 cvs update -p -r 1.3 <file> | diff - .#<file>.1.3
6822 The assumption is that the ".#" files will be useful far beyond the
6823 "commit" point, but not forever. You are expected to run the "normal"
6824 Unix cleanup script from "cron", which removes "#*" and ".#*" files
6825 older than a some period chosen by your sysadmin, usually ranging from
6828 A question was raised about the need for #3 after #5 has been
6829 committed, under the assumption that you won't commit files until
6830 everything is exactly as you like them.
6832 This assumes perfect humans, which violates one of the Cardinal rules
6833 of Software Engineering: Never assume any form of discipline on the
6834 part of the users of software. If restrictions are not bound into the
6835 software, then you, the toolsmith, have to arrange a recovery path.
6837 In other words, I've seen every possible variety of screwup you can
6838 imagine in #5. There is no way to make assumptions about what "should"
6839 happen. I've seen #5 filled with zeros because of NFS failures, I've
6840 seen emacs core dumps that leave #5 in an unreasonable state, I've
6841 seen a foolish developer uppercase the whole file (with his "undo"
6842 size set low so he couldn't undo it) and decide that it would be less
6843 work to play with the uppercased file than to blow it away and start
6844 over. I've even seen committed files with conflict markers still in
6845 them, a sure sign of carelessness.
6847 There are all sorts of scenarios where having #3 is incredibly useful.
6848 You can move it back into place and try again.
6850 Last modified: _6/13/1997_
6852 10. What is this "ignore" business? What is it ignoring?
6854 The "update" and "import" commands use collections of Unix wildcards
6855 to skip over files and directories matching any of those patterns.
6857 You may add to the built-in ignore list by adding lines of
6858 whitespace-separated wildcards to the following places: (They are read
6861 In a file named "cvsignore" in $CVSROOT/CVSROOT.
6863 A Repository Administrator uses this to add site-specific files and
6864 patterns to the built-in ignore list.
6866 In a file named ".cvsignore" in your home directory.
6868 For user-specific files. For example, if you use "__" as your default
6869 junk file prefix, you can put "__*" in your .cvsignore file.
6871 People who play around exclusively in directory trees where the
6872 Makefiles are generated by "imake" or "configure" might want to put
6873 "Makefile" in their ignore list, since they are all generated and
6874 usually don't end up in the Repository.
6876 In the CVSIGNORE environment variable.
6878 For session-specific files.
6880 Via the '-I' option on "import" or "update" commands.
6882 For this-command-only files.
6884 In a file named ".cvsignore" within each directory.
6886 The contents of a ".cvsignore" file in each directory is temporarily
6887 added to the ignore list. This way you can ignore files that are
6888 peculiar to that directory, such as executables and other generated
6889 files without known wildcard patterns.
6891 In any of the places listed above, a single '!' character nulls out
6892 the ignore list. A Repository administrator can use this to override,
6893 rather than enhance, the built-in ignore list. A user can choose to
6894 override the system-wide ignore list. For example, if you place "! *.o
6895 *.a" in your .cvsignore file, only *.o *.a files, plus any files a
6896 local-directory .cvsignore file, are ignored.
6898 A variant of the ignore-file scheme is used internally during
6899 checkout. "Module names" found in the modules file (or on the
6900 "checkout" command line) that begin with a '!' are ignored during
6901 checkout. This is useful to permanently ignore (if the '!' path is in
6902 the modules file) or temporarily ignore (if the '!' path is on the
6903 command line) a sub-directory within a Repository hierarchy. For
6906 cvs checkout !gnu/emacs/tests gnu/emacs
6908 would checkout the module (or relative path within $CVSROOT) named
6909 "gnu/emacs", but ignore the "tests" directory within it.
6911 Last modified: _6/13/1997_
6913 11. Is there a way to set user-specific configuration options?
6915 User-specific configuration is available through use of a ".cvsrc"
6916 file in your home directory.
6918 CVS searches the first column of your ~/.cvsrc file for the cvs
6919 command name you invoked. If the command is found, the rest of the
6920 line is treated like a set of command line options, stuffed into the
6921 command line before the arguments you actually typed.
6923 For example, if you always want to see context diffs and you never
6924 want to have to delete a file before you run "cvs remove", then you
6925 should create a .cvsrc file containing the following:
6930 which will add the given options to every invocation of the given
6933 [[The rest of this will be removed someday, when CVS changes.]]
6935 I would like to stop here with a comment that the command name to use
6936 is the full, canonical one. But the command that the cvsrc support
6937 uses is the string you typed on the command line, not the proper
6938 command. So to get the full effect of the above example, you should
6939 also add all the alternate command names:
6946 There are two other limitations that will probably be fixed when CVS
6947 sprouts long option names:
6949 It only affects options made available on the command line.
6951 There is a limited number of short options. With long option names,
6952 there is no problem. You can have as many long options as you like,
6953 affecting anything that looks malleable.
6955 The existing command line options do not come in on/off pairs, so
6956 there is no easy way to override your ~/.cvsrc configuration for a
6957 single invocation of a command.
6959 Choosing a good set of long option pairs would fix this.
6961 Last modified: _6/13/1997_
6963 12. Is it safe to interrupt CVS using Control-C?
6965 It depends on what you mean by "safe". ("Ah," said Arthur, "this is
6966 obviously some strange usage of the word *safe* that I wasn't
6967 previously aware of." -- Hitchhiker's Guide to the Galaxy)
6969 You won't hurt the underlying RCS files and if you are executing a
6970 command that only *reads* data, you will have no cleanup to do.
6972 But you may have to hit Control-C repeatedly to stop it. CVS uses the
6973 Unix "system" routine which blocks signals in the CVS parent process.
6974 A single Control-C during "system" will only halt the child process,
6975 usually some form of RCS command.
6977 If you don't hit another Control-C while the CVS process has control,
6978 it is likely to continue onto the next task assuming that the earlier
6979 one did its job. It is not enough to hit two Control-C's. You might
6980 simply kill two child processes and not interrupt CVS at all.
6981 Depending on the speed of your processor, your terminal and your
6982 fingers, you might have to hit dozens of Control-C's to stop the damn
6985 Executing a CVS command, such as "commit" or "tag" that writes to the
6986 files is a different matter.
6988 Since CVS is not a full-fledged database, with what database people
6989 call "commit points", merely stopping the process will not back out
6990 the "transaction" and place you back in the starting blocks. CVS has
6991 no concept of an "atomic" transaction or of "backtracking", which
6992 means that a command can be half-executed.
6994 Hitting Control-C will usually leave lock files that you have to go
6995 clean up in the Repository.
6999 If you interrupt a multi-file "commit" in the middle of
7000 an RCS checkin, RCS will leave the file either fully
7001 checked-in or in its original state. But CVS might have
7002 been half-way through the list of files to commit. The
7003 directory or module will be inconsistent.
7005 To recover, you must remove the lock files, then decide
7006 whether you want to back out or finish the job.
7008 To back out, you'll have to apply the "admin -o"
7009 command, very carefully, to remove the newly committed
7010 revisions. This is usually a bad idea, but is
7011 occasionally necessary.
7013 To finish, you can simply retype the same commit command.
7014 CVS will figure out what files are still modified and
7015 commit them. It helps that RCS doesn't leave a file in an
7020 If you interrupt a multi-file "tag" command, you have a
7021 problem similar, but not equivalent, to interrupting a
7022 "commit". The RCS file will still be consistent, but
7023 unlike "commit", which only *adds* to the RCS file, "tag"
7024 can *move* a tag and it doesn't keep a history of what
7025 revision a tag used to be attached to.
7027 Normally, you have little choice but to re-execute the
7028 command and allow it to tag everything consistently.
7030 You might be able to recover by carefully re-applying the
7031 tags via the "cvs admin -N" command, but you'll still have
7032 to dig up from outside sources the information you use to
7033 determine what tag was on what revision in what file.
7034 the Repository, or by using the equivalent: "cvs admin".
7036 Halting a new "checkout" should cause no harm. If you don't want it,
7037 "release" (or rm -rf) it. If you do want it, re-execute the command. A
7038 repeated "checkout" from above a directory acts like a repeated
7039 "update -d" within it.
7041 Halting "update" half-way will give you an unpredictable collection of
7042 files and revisions. To continue, you can rerun the update and it
7043 should move you forward into in a known state. To back out, you'll
7044 have to examine the output from the first "update" command, take a
7045 look at each file that was modified and reconstruct the previous state
7046 by editing the ./CVS/Entries file and by using "cvs admin". Good Luck.
7048 Last modified: _6/13/1997_
7050 13. How do I turn off the "admin" command?
7052 In the current revision, you'd have to edit the source code.
7054 Last modified: _6/13/1997_
7056 14. How do I turn off the ability to disable history via "cvs -l"?
7058 In the current revision, you'd have to edit the source code.
7060 Last modified: _6/13/1997_
7062 15. How do I keep certain people from accessing certain directories?
7064 If you don't try to run CVS set[ug]id, you can use Unix groups and
7065 permissions to limit access to the Repository.
7067 If you only want to limit "commit" commands, you can write a program
7068 to put in the "commitinfo" file. In the "contrib" directory, there are
7069 a few scripts that might help you out.
7071 Last modified: _6/13/1997_
7073 Category: /User_Tasks_/Getting_Started/
7075 " + Getting Started"
7077 1. What is the first thing I have to know?
7079 Your organization has most likely assigned one or more persons to
7080 understand, baby-sit and administer the CVS programs and the data
7081 Repository. I call these persons Repository Administrators. They
7082 should have set up a Repository and "imported" files into it.
7084 If you don't believe anyone has this responsibility, or you are just
7085 testing CVS, then *you* are the Repository Administrator.
7087 If you are a normal user of CVS ask your Repository Administrator what
7088 module you should check out.
7092 If you *are* the Repository Administrator, you will want to read
7093 everything you can get your hands on, including this FAQ. Source
7094 control issues can be difficult, especially when you get to branches
7095 and release planning. Expect to feel stupid for a few days/weeks.
7097 No tool in the universe avoids the need for intelligent organization.
7098 In other words, there are all sorts of related issues you will
7099 probably have to learn. Don't expect to dive in without any
7100 preparation, stuff your 300 Megabytes of sources into CVS and expect
7101 to start working. If you don't prepare first, you will probably spend
7102 a few sleepless nights.
7104 Last modified: _6/13/1997_
7108 Wherever you have disk space. That's one of the advantages of CVS: you
7109 use the "checkout" command to copy files from the Repository to your
7110 working directory, which can be anywhere you have the space.
7112 Your local group might have conventions for where to work. Ask your
7115 Last modified: _6/13/1997_
7117 3. What does CVS use from my environment?
7119 You must set two environment variables. Some shells share these
7120 variables with local shell variables using a different syntax. You'll
7121 have to learn how your shell handles them.
7123 Variable Value (or action)
7124 --------- ---------------------
7125 CVSROOT Absolute pathname of the head of your Repository.
7127 PATH Normally set to a list of ':'-separated directory
7128 pathnames searched to find executables. You must
7129 make sure "cvs" is in one of the directories.
7131 If your CVS was built with the RCSBIN directory set
7132 to null (""), and you don't set the RCSBIN
7133 variable mentioned below, then the RCS commands
7134 also must be somewhere in your PATH.
7136 Optional variables: (Used if set, but ignored otherwise.)
7138 Variable Value (or action)
7139 --------- ---------------------
7140 CVSEDITOR The name of your favorite fast-start editor
7141 program. You'll be kicked into your editor to
7142 supply revision comments if you don't specify them
7143 via -m "Log message" on the command line.
7145 EDITOR Used if CVSEDITOR doesn't exist. If EDITOR
7146 doesn't exist, CVS uses a configured constant,
7149 CVSREAD Sets files to read-only on "checkout".
7151 RCSBIN Changes where CVS finds the RCS commands.
7153 CVSIGNORE Adds to the ignore list. See Section 2D.
7155 Other variables used by CVS that are normally set upon login:
7157 Variable Value (or action)
7158 --------- ---------------------
7159 LOGNAME Used to find the real user name.
7161 USER Used to find the real user name if no LOGNAME.
7163 HOME Used to determine your home directory, if set.
7164 Otherwise LOGNAME/USER/getuid() are used to find
7165 your home directory from the passwd file.
7167 TMPDIR Used during import. It might also be used if your
7168 platform's version of mktemp(3) is unusual, or
7169 you have changed the source to use tmpnam(3).
7171 Last modified: _6/13/1997_
7173 4. OK, I've been told that CVS is set up, my module is named "ralph" and I
7174 have to start editing. What do I type?
7176 cd <where you have some space to work>
7182 Last modified: _6/13/1997_
7184 5. I have been using RCS for a while. Can I convert to CVS without losing
7185 my revision history? How about converting from SCCS?
7187 If you are asking such questions, you are not a mere user of CVS, but
7188 one of its Administrators! You should take a look at Section 4A,
7189 "Installing CVS" and Section 4B, "Setting up and Managing the
7192 Last modified: _6/13/1997_
7194 Category: /User_Tasks_/Less_Common_User_Tas/
7196 " + Less Common User Tasks"
7198 1. Can I create non-CVS sub-directories in my working directory?
7200 Yes. Unless the directory exists in the Repository, "update" will skip
7201 over them and print a '?' the way it does for files you forgot to add.
7202 You can avoid seeing the '?' by adding the name of the foreign
7203 directory to the ./.cvsignore file, just ask you can do with files.
7205 If you explicitly mention a foreign directory on the "update" command
7206 line, it will traverse the directory and waste a bit of time, but if
7207 any directory or sub-directory lacks the ./CVS administrative
7208 directory, CVS will print an error and abort.
7210 Last modified: _6/13/1997_
7212 2. How do I add new sub-directories to the Repository?
7214 The "add" command will work on directories. You type:
7221 Directory /Repos/<dir> added to the repository
7223 and will create both a matching directory in the Repository and a
7224 ./CVS administrative directory within the local <dir> directory.
7226 Last modified: _6/13/1997_
7228 3. How do I remove a file I don't need?
7230 (See the questions in Section 4B on removing files from the
7238 CVS registers the file for removal. To complete the removal, you must
7243 CVS moves the file to the Attic associated with your working
7244 directory. Each directory in the Repository stores its deleted files
7245 in an Attic sub-directory. A normal "checkout" doesn't look in the
7246 Attic, but if you specify a tag, a date or a revision, the "checkout"
7247 (or "update") command will retrieve files from the Attic with that
7248 tag, date or revision.
7250 Last modified: _6/13/1997_
7252 4. How do I rename a file?
7254 CVS does not offer a way to rename a file in a way that CVS can track
7255 later. See Section 4B for more information.
7257 Here is the best (to some, the only acceptable) way to get the effect
7258 of renaming, while preserving the change log:
7260 Copy the RCS (",v") file directly in the Repository.
7262 cp $CVSROOT/<odir>/<ofile>,v $CVSROOT/<ndir>/<nfile>,v
7264 By duplicating the file, you will preserve the change history and the
7265 ability to retrieve earlier revisions of the old file via the "-r
7266 <tag/rev>" or "-D <date>" options to "checkout" and "update".
7268 Remove the old file using CVS.
7270 cd <working-dir>/<odir> rm <ofile>
7274 This will move the <ofile> to the Attic associated with <odir>.
7276 Retrieve <nfile> and remove all the Tags from it.
7278 By stripping off all the old Tags, "checkout -r" and "update -r" won't
7279 retrieve revisions Tagged before the renaming.
7281 cd <working-dir>/<ndir>
7283 cvs log <nfile> # Save the list of Tags
7284 cvs tag -d <tag1> <nfile>
7285 cvs tag -d <tag2> <nfile>
7288 This technique can be used to rename files within one directory or
7289 across different directories. You can apply this idea to directories
7290 too, as long as you apply the above to each file and don't delete the
7293 Of course, you have to change your build system (e.g. Makefile) in
7294 your <working-dir> to know about the name change.
7296 Warning: Stripping the old tags from the copied file will allow "-r
7297 <tag>" to do the right thing, but you will still have problems with
7298 "-D <date>" because there is no place to store the "deletion time".
7299 See 5B.3 for more details.
7301 Last modified: _6/13/1997_
7303 5. How do I make sure that all the files and directories in my working
7304 directory are really in the Repository?
7306 A "cvs update", or "cvs -n update" (which won't modify your working
7307 directory) will display foreign elements, which have no counterpart in
7308 the Repository, preceded by a '?'. To register foreign directories,
7309 you can use "cvs add". To register foreign files, you can use "cvs
7310 add" followed by "cvs commit".
7312 You could also checkout your module, or the Repository directory
7313 associated with your working directory, a second time into another
7314 work area and compare it to your working directory using the (non-CVS)
7317 By default many patterns of files are ignored. If you create a file
7318 named "core" or a file ending in ".o", it is usually ignored. If you
7319 really want to see all the files that aren't in the Repository, you
7320 can use a special "ignore" pattern to say "ignore no files". Try
7321 executing: (You may have to quote or backwhack (i.e. precede by '\')
7322 the '!' in your shell.)
7326 The above command will display not only the normal modified, update
7327 and conflict indicators ('M', 'U', and 'C' respectively) on files
7328 within the Repository, but it will also display each file not in the
7329 Repository preceded by a '?' character.
7331 The '-n' option will not allow "update" to alter your working
7334 Last modified: _6/13/1997_
7336 6. How do I create a branch?
7338 Type this in your working directory:
7340 cvs tag -b <branch_tag>
7342 and you will create a branch. No files have real branches in them yet,
7343 but if you move onto the branch by typing:
7345 cvs update -r <branch_tag>
7347 and commit a file in the normal way:
7351 then a branch will be created in the underlying <file>,v file and the
7352 new revision of <file> will appear only on that branch.
7354 See Section 4C, on Branching.
7356 Last modified: _6/13/1997_
7358 7. How do I modify the modules file? How about the other files in the
7359 CVSROOT administrative area?
7361 A module named "modules" has been provided in the default modules
7362 file, so you can type:
7364 cvs checkout modules
7367 Another module named CVSROOT has been provided in the default modules
7368 file, covering all the administrative files. Type:
7370 cvs checkout CVSROOT
7373 Then you can edit your files, followed by:
7377 If you start with the provided template for the "modules" file, the
7378 CVSROOT and the "modules" module will have the "mkmodules" program as
7379 a "commit helper". After a file is committed to such a module,
7380 "mkmodules" will convert a number of standard files (See 4B.2) in the
7381 CVSROOT directory inside the Repository into a form that is usable by
7384 Last modified: _6/13/1997_
7386 8. How do I split a file into pieces, retaining revision histories?
7388 If you and a coworker find yourselves repeatedly committing the same
7389 file, but never for changes in the same area of the file, you might
7390 want to split the file into two or more pieces. If you are both
7391 changing the same section of code, splitting the file is of no use.
7392 You should talk to each other instead.
7394 If you decide to split the file, here's a suggestion. In many ways, it
7395 is similar to multiple "renamings" as described in 2C.4 above.
7397 Say you want to split , which already in the Repository, into three
7400 Copy the RCS (",v") files directly in the Repository, creating the
7401 new files, then bring readable copies of the new files into the
7402 working directory via "update".
7404 cp $CVSROOT//,v $CVSROOT//,v cp $CVSROOT//,v $CVSROOT//,v
7407 Then remove all the from the new files, either using:
7409 cvs log # Save the list of
7414 (eivind@freebsd.org) or using the following little script to
7415 autmatically remove the tags directly from the repository files:
7420 TAGS=`rlog $file | awk '/^symbolic names:/,/^keyword subst/' | awk 'BEG
7421 IN {FS=":"} /^\t/ {print $1}'`
7422 echo The tags in $file are
7424 echo Is it OK to remove these?
7426 if [ "$confirm" = "y" -o "$confirm" = "yes" ]
7430 echo Removing $file:$tag
7436 Edit each file until it has the data you want in it. This is a
7437 hand-editing job, not something CVS can handle. Then commit all the
7440 [From experience, I'd suggest making sure that only one copy of each
7441 line of code exists among the three files, except for "include"
7442 statements, which must be duplicated. And make sure the code
7448 As in the "rename" case, by duplicating the files, you'll preserve the
7449 change history and the ability to retrieve earlier revisions.
7451 Of course, you have to alter your build system (e.g. Makefiles) to
7452 take the new names and the change in contents into account.
7454 Last modified: _3/11/1998_
7456 Category: /What_is_CVS_/
7460 Category: /What_is_CVS_/How_does_CVS_differ_/
7462 " + How does CVS differ from other, similar software?"
7464 1. How does CVS differ from RCS?
7466 CVS uses RCS to do much of its work and absolutely all the work of
7467 changing the underlying RCS files in the Repository.
7469 RCS comprises a set of programs designed to keep track of changes to
7470 individual files. Of course, it also allows you to refer to multiple
7471 files on the command line, but they are handled by iterating over
7472 individual files. There is no pretense of coordinated interaction
7473 among groups of files.
7475 CVS's main intent is to provide a set of grouping functions that allow
7476 you to treat a collection of RCS files as a single object. Of course,
7477 CVS also has to do a lot of iteration, but it tries its best to hide
7478 that it is doing so. In addition, CVS has some truly group-oriented
7479 facets, such as the modules file and the CVS administrative files that
7480 refer to a whole directory or module.
7482 One group aspect that can be a bit confusing is that a CVS branch is
7483 not the same as an RCS branch. To support a CVS branch, CVS uses
7484 "tags" (what RCS calls "symbols") and some local state, in addition to
7487 Other features offered by CVS that are not supported directly by RCS
7490 Automatic determination of the state of a file, (e.g. modified,
7491 up-to-date with the Repository, already tagged with the same string,
7492 etc.) which helps in limiting the amount of displayed text you have to
7493 wade through to figure out what changed and what to do next.
7495 A copy-modify-merge scheme that avoids locking the files and allows
7496 simultaneous development on a single file.
7498 Serialization of commits. CVS requires you to merge all changes
7499 committed (via "update") since you checked out your working copy of
7500 the file. Although it is still possible to commit a file filled with
7501 old data, it is less likely than when using raw RCS.
7503 Relatively easy merging of releases from external Vendors.
7505 Last modified: _6/13/1997_
7507 2. How does CVS differ from SCCS?
7509 SCCS is much closer to RCS than to CVS, so some of the previous entry
7512 You might want to take a look at Walter Tichy's papers on RCS, which
7513 are referred to in the RCS man pages.
7517 Last modified: _6/13/1997_
7519 3. How does CVS differ from ClearCase?
7521 ClearCase is a distributed client-server version control system.
7522 ClearCase is a variant DSEE tools, formerly available on Apollo
7523 platforms. The ClearCase tool set includes a few X-based interface
7524 tools, a command-line interface, and C programmer API. It is currently
7525 available on Sun, HP, SGI and OSF/1 platforms.
7527 ClearCase uses a special Unix filesystem type, called "mvfs" for
7528 "multi-version file system". Conceptually, mvfs adds another dimension
7529 to a regular Unix filesystem. The new axis is used to store the
7530 different versions of files and to provide a tree-hierarchical view of
7531 a collection of objects that might be scattered across any number of
7532 separate hosts on your local network.
7534 Each user acquires a "view" into the file database by creating a
7535 special mvfs mount point on their machine. Each view has a
7536 "configuration spec" containing a set of selection rules that specify
7537 the particular version of each file to make visible in that view. You
7538 can think of a "view" as a work area in CVS, except that the files
7539 don't really exist on your local disk until you modify them. This
7540 technique conserves disk space because it doesn't keep private copies
7543 Another advantage is that a view is "transparent" in the sense that
7544 all of the files in a "view" appear to be regular Unix files to other
7545 tools and Unix system calls. An extended naming convention allows
7546 access to particular versions of a file directly:
7547 "test.cc@@/main/bugfix/3" identifies the third version of test.c on
7550 ClearCase supports both the copy-modify-merge model of CVS (by using
7551 what are called "unreserved checkouts" and the checkin/checkout
7552 development model with file locking. Directories are
7553 version-controlled objects as well as files. A graphical merge tool is
7554 provided. Like RCS, ClearCase supports branches, symbolic tags, and
7555 delta compression. ASCII as well as binary files are supported, and
7556 converters from RCS, SCCS, DSEE formats are also included.
7558 A make-compatible build facility is provided that can identify common
7559 object code and share it among developers. A build auditing feature
7560 automatically records file dependencies by tracking every file that is
7561 opened when producing a derived object, thus making explicit
7562 dependency lists unnecessary. Pre- and post-event triggers are
7563 available for most ClearCase operations to invoke user programs or
7564 shell scripts. User-defined attributes can be assigned to any version
7565 or object. Hyper-links between version controlled objects can record
7568 For more information, contact:
7570 Atria Software, Inc. 24 Prime Park Way Natick, MA 01760 info@atria.com
7572 (508) 650-1193 (phone) (508) 650-1196 (fax)
7574 Originally contributed by Steve Turner
7575 Edited by the author of this FAQ.
7577 Last modified: _6/13/1997_
7579 4. How does CVS differ from TeamWare/SparcWorks?
7581 TeamWare is a configuration management tool from Sun Microsystems, a
7582 part of SparcWorks. It uses the same copy and merge model as CVS. The
7583 central abstraction is a workspace, which corresponds to either a CVS
7584 branch or a checked out module. TeamWare allows you to manipulate
7585 workspaces directly, including moving and merging code between
7586 workspaces. You can put your workspace on tape and continue to work
7587 with it at home, just like you can with CVS. TeamWare is built upon
7588 and compatible with SCCS.
7590 TeamWare provides both a command line interface and a graphical
7591 interface. The CodeManager tool will display the project as a tree of
7592 workspaces, and allows you to manipulate them with drag and drop. The
7593 other tools are VersionTool that displays and manipulates a dag with a
7594 version history of a single file, CheckPoint that will create symbolic
7595 tags, MakeTool, a make compatible tool with a GUI, and FileMerge which
7596 will interactively merge files when needed (like emerge for emacs). If
7597 you have a sun, you can try /usr/old/mergetool for an old SunView
7598 version of FileMerge.
7600 Email: sunprosig@sun.com
7602 Originally extracted from TeamWare
7603 Marketing literature by Per Abrahamsen.
7604 Edited by the author of this FAQ.
7606 For more information, contact:
7608 SunExpress, Inc. P.O. Box 4426 Bridgeton, MO 63044-9863 (800)873-7869
7610 Last modified: _6/13/1997_
7612 5. How does CVS differ from Aegis?
7614 Aegis appears to be a policy-setting tool that allows you to use other
7615 sub-programs (make, RCS, etc.) to implement pieces of the imposed
7618 The initial document seems to say that most Unix tools are inadequate
7619 for use under Aegis.
7621 It is not really similar to CVS and requires a different mindset.
7623 [[Need more info here.]]
7625 Last modified: _6/13/1997_
7627 6. How does CVS differ from Shapetools?
7629 Shapetools includes a build mechanism (called Shape, not surprisingly)
7630 that is aware of the version mechanism, and some dependency tracking.
7631 It is based on a file system extension called Attributed File System,
7632 which allows arbitrary-sized "attributes" to be associated with a
7633 file. Files are version controlled in a manner similar to RCS.
7634 Configurations are managed through the Shapefile, an extension of the
7635 Makefile syntax and functionality. Shape includes version selection
7636 rules to allow sophisticated selection of component versions in a
7639 Shapetools' concurrency control is pessimistic, in contrast to that of
7640 CVS. Also, there's very limited support for branching and merging. It
7641 has a built-in policy for transitioning a system from initial
7642 development to production.
7644 Contributed by Don Dwiggins
7646 Last modified: _6/13/1997_
7648 7. How does CVS differ from TeamNet?
7650 TeamNet is a configuration management tool from TeamOne.
7652 For more information, contact:
7654 TeamOne 710 Lakeway Drive, Ste 100 Sunnyvale, CA 94086 (800) 442-6650
7656 Contributed by Steve Turner
7658 Last modified: _6/13/1997_
7660 8. How does CVS differ from ProFrame?
7662 ProFrame is a new system integration framework from IBM. ProFrame is
7663 compliant with the CFI (CAD Framework Initiative) industry standards,
7664 including the Scheme extension language.
7666 ProFrame consists of three major components: (1) the Process Manager
7667 that automates your local design methodology (2) the Design Data
7668 Manager handles configuration management, and (3) Inter-tool
7669 Communication to provide a communication path among tools running on
7670 heterogeneous servers.
7672 The Design Data Manager(2) is probably the appropriate component to
7673 compare to CVS. The Design Data Manager provides version control with
7674 checkin/checkout capability, configuration management, and data
7675 dependency tracking. A graphical data selection interface is provided.
7676 Using this interface, you may create and manipulate objects and
7677 hierarchy structures, view the revision history for an object, and
7678 view and assign attributes to a design object.
7680 The ProFrame server currently runs only on RS6000, but clients may be
7681 a wide variety of Unix platforms. Contact IBM for the latest platform
7684 For more information, contact:
7686 IBM EDA Marketing and Sales P.O. Box 950, M/S P121 Poughkeepsie, NY
7687 12602 (800) 332-0066
7689 Contributed by Steve Turner
7690 [extracted from the ProFrame 1.1.0 datasheet]
7692 Last modified: _6/13/1997_
7694 9. How does CVS differ from CaseWare/CM?
7696 CaseWare/CM is a software configuration management product from
7697 CaseWare, Inc. CaseWare/CM may be customized to support a wide variety
7698 of methodologies, including various phases of the software lifecycle,
7699 and different access rights for users.
7701 A GUI is provided to view version histories and configurations. A
7702 merge tools is also included. CaseWare supports type-specific
7703 lifecycles, which allows different types of files to move through
7704 different lifecycles. Also provided is a build facility to support
7705 automatic dependency analysis, parallel, distributed, and remote
7706 builds, and variant releases.
7708 CaseWare/CM has been integrated with other CASE tools, including
7709 FrameMaker, ALSYS Ada, CodeCenter/Object Center, HP SoftBench, and
7710 Software Through Pictures. CaseWare also offers CaseWare/PT, a problem
7711 tracking system to integrate change requests with configuration
7714 Multiple vendors and operating systems are supported.
7716 For more information, contact:
7718 CaseWare, Inc. 108 Pacifica, 2nd Floor Irvine, CA 92718-3332 (714)
7719 453-2200 (phone) (714) 453-2276 (fax)
7721 Contributed by Steve Turner
7722 [extracted from the CaseWare/CM data sheet]
7724 Last modified: _6/13/1997_
7726 10. How does CVS differ from SABLIME?
7728 Produced by AT&T. Sablime uses SCCS as the underlying source code
7729 control system. It uses some other control system (called sbcs I
7730 think) for managing binary files. It uses lock, edit, comit, unlock
7731 mechanism. It has a motif based GUI and curses based GUI (that works
7732 only with ksh, not tcsh, or bash) to do more common tasks. It has even
7733 a command line interface.
7735 Changing source happens as a result of MR. A testing person or a
7736 developer assigns an MR (modification request) to a group of people.
7737 They are allowed to take out files under that MR and change them and
7738 check them back in. You can set up dependencies between and MR and do
7739 release management to say "I want the sources to include these MRs"
7740 etc. It is a reasonably good maintanance system. It is bit heavy
7741 weight though, and the interface is not too polished and does not work
7742 on windows (though that may have changed). rama@savera.com
7744 Last modified: _7/30/1998_
7746 11. How does CVS differ from PVCS?
7748 PVCS works on single files like RCS and SCCS, CVS works on complete
7749 subsystems. PVCS has a make utility (called a configuration builder),
7750 CVS does not. PVCS has a GUI interface for Unix, DOS, OS/2, and MS
7757 Contributed by Per Abrahamsen
7758 [Extracted from Intersolv Marketing literature.]
7760 Last modified: _6/13/1997_
7762 12. How does CVS differ from CMVC?
7764 CMVC is an IBM Configuration Management and Version Control system.
7765 (Though I'm not certain that's the right acronym expansion.) It runs
7766 on Suns, HPs, RS6000s, OS/2 and Windows.
7768 Other than revision control, it apparently has features to manage
7769 releases, bug tracking and the connection between alterations and
7770 reported bugs and feature requests. It is a client/server system,
7771 based on a choice of commercial Relational Database systems, and it
7772 provides a Motif or command line interface.
7774 Unlike CVS, it uses a strict locking protocol to serialize source code
7777 Last modified: _6/13/1997_
7779 Category: /What_is_CVS_/What_do_you_mean_by_/
7781 " + What do you mean by . . .? (Definitions)"
7783 1. What are "The Repository", "$CVSROOT" and "CVSROOT"?
7785 The Repository is a directory tree containing the CVS administrative
7786 files and all the RCS files that constitute "imported" or "committed"
7787 work. The Repository is kept in a shared area, separate from the
7788 working areas of all developers.
7790 Users of CVS must set their "CVSROOT" environment variable to the
7791 absolute pathname of the head of the Repository. Most command line
7792 interpreters replace an instance of "$CVSROOT" with the value of the
7793 "CVSROOT" environment variable. By analogy, in this document
7794 "$CVSROOT" is used as shorthand for "the absolute pathname of the
7795 directory at the head of the Repository".
7797 One of the things found in $CVSROOT is a directory named CVSROOT. It
7798 contains all the "state", the administrative files, that CVS needs
7799 during execution. The "modules", "history", "commitinfo", "loginfo"
7800 and other files can be found there. See 4B.2 for more information
7801 about CVSROOT files.
7803 Last modified: _6/13/1997_
7805 2. What is an RCS file?
7807 An RCS file is a text file containing the source text and the revision
7808 history for all committed revisions of a source file. It is stored
7809 separately from the working files, in a directory hierarchy, called
7812 RCS is the "Revision Control System" that CVS uses to manage
7813 individual files. RCS file names normally end in ",v", but that can be
7814 altered (via the RCS -x option) to conform to file naming standards on
7815 platforms with unusual filename limitations.
7817 Last modified: _6/13/1997_
7819 3. What is a working file?
7821 A working file is a disk file containing a checked-out copy of a
7822 source file that earlier had been placed under CVS. If the working
7823 file has been edited, the changes since the last committed revision
7824 are invisible to other users of CVS.
7826 Last modified: _6/13/1997_
7828 4. What is a working directory (or working area)?
7830 A working directory is the place where you work and the place from
7831 which you "commit" files.
7833 The "checkout" command creates a tree of working directories, filling
7834 them with working files. Each working directory contains a
7835 sub-directory named ./CVS containing three administrative files, which
7836 are created by "checkout" and are always present:
7839 contains information about working files.
7842 contains the location of the directory within the
7843 Repository that was used to create the working directory.
7846 contains the value of $CVSROOT at the time you created
7847 the working directory.
7849 Other files may also appear in ./CVS depending on the state of your
7853 contains the "sticky tag" associated with the whole
7854 directory. See 3A.2 for its main purpose.
7855 [Created by "checkout" or "update" when using "-r <tag>".]
7856 [Deleted by "checkout" or "update" when using '-A'.]
7858 ./CVS/Entries.Static
7859 contains a fixed list of working files. If this file
7860 exists, an "update" doesn't automatically bring newly
7861 added files out of the Repository.
7862 [Created and maintained by hand.]
7865 contains a program to run whenever anything in the
7866 working directory is committed.
7867 [Created by checkout if "-i <prog>" appears in the
7868 modules file for the checked-out module.]
7871 contains a program to run whenever anything in the
7872 working directory is updated.
7873 [Created by checkout if "-u <prog>" appears in the
7874 modules file for the checked-out module.]
7876 ./CVS/<file>,p ./CVS/<file>,t
7877 contain (possibly zero-length) state information about an
7878 "add" that has not been committed.
7880 [Deleted by "commit" or "remove".]
7882 Last modified: _6/13/1997_
7884 5. What is "checking out"?
7886 "Checking out" is the act of using the "checkout" command to copy a
7887 particular revision from a set of RCS files into your working area.
7888 You normally execute "checkout" only once per working directory (or
7889 tree of working directories), maintaining them thereafter with the
7892 See section 3C on the "checkout" command.
7894 Last modified: _6/13/1997_
7896 6. What is a revision?
7898 A "revision" is a version of a file that was "committed" ("checked
7899 in", in RCS terms) some time in the past. CVS (and RCS) can retrieve
7900 any file that was committed by specifying its revision number or its
7901 "tag" ("symbolic name", in RCS terms).
7903 In CVS, a "tag" is more useful than a revision number. It usually
7904 marks a milestone in development represented by different revision
7905 numbers in different files, all available as one "tagged" collection.
7907 Sometimes the word "revision" is used as shorthand for "the file you
7908 get if you retrieve (via "checkout" or "update") the given revision
7909 from the Repository."
7911 Last modified: _6/13/1997_
7915 A "Tag" is a symbolic name, a synonym or alias for a particular
7916 revision number in a file. The CVS "tag" command places the same "Tag"
7917 on all files in a working directory, allowing you to retrieve those
7918 files by name in the future.
7920 The CVS "Tag" is implemented by applying RCS "symbols" to each
7921 individual file. The Tags on a file (or collection of files) may be
7922 displayed using the "log" command.
7924 Last modified: _6/13/1997_
7926 8. What are "HEAD" and "BASE"?
7928 HEAD and BASE are built-in tags that don't show up in the "log" or
7929 "status" listings. They are interpreted directly by CVS.
7931 "HEAD" refers to the latest revision on the current branch in the
7932 Repository. The current branch is either the main line of development,
7933 or a branch in development created by placing a branch tag on a set of
7934 files and checking out that branch.
7936 "BASE" refers to the revision on the current branch you last checked
7937 out, updated, or committed. If you have not modified your working
7938 file, "BASE" is the committed revision matching it.
7940 Most of the time BASE and HEAD refer to the same revision. They can
7941 become different in two ways:
7943 Someone else changed HEAD by committing a new revision of your file
7944 to the Repository. You can pull BASE up to equal HEAD by executing
7947 You moved BASE backward by executing "checkout" or "update" with the
7948 option "-r <rev/tag>" or "-D <date>". CVS records a sticky tag and
7949 moves your files to the specified earlier revision. You can clear the
7950 sticky tag and pull BASE up to equal HEAD again by executing "update
7953 Last modified: _6/13/1997_
7955 9. What is a Branch?
7957 In general, a branch is any mechanism that allows one or more
7958 developers to modify a file without affecting anyone other than those
7959 working on the same branch.
7961 There are four kinds of "branch" CVS can manage:
7965 A single vendor branch is supported. The "import" command takes a
7966 sequence of releases from a source code vendor (called a "vendor" even
7967 if no money is involved), placing them on a special "Vendor" branch.
7968 The Vendor branch is considered part of the "Main line" of
7969 development, though it must be merged into locally modified files on
7970 the RCS Main branch before the "import" is complete.
7972 See Section 3H ("import").
7974 Your Working directory.
7976 A checked-out working directory, can be treated like a private branch.
7977 No one but you can touch your files. You have complete control over
7978 when you include work committed by others. However, you can't commit
7979 or tag intermediate versions of your work.
7981 A Development branch.
7983 A group of developers can share changes among the group, without
7984 affecting the Main line of development, by creating a branch. Only
7985 those who have checked-out the branch see the changes committed to
7986 that branch. This kind of branch is usually temporary, collapsing
7987 (i.e. merge and forget) into the Main line when the project requiring
7988 the branch is completed.
7990 You can also create a private branch of this type, allowing an
7991 individual to commit (and tag) intermediate revisions without changing
7992 the Main line. It should be managed exactly like a Development Branch
7993 -- collapsed into the Main line (or its parent branch, if that is not
7994 the Main Branch) and forgotten when the work is done.
7998 At release time, a branch should be created marking what was released.
7999 Later, small changes (sometimes called "patches") can be made to the
8000 release without including everything else on the Main line of
8001 development. You avoid forcing the customer to accept new, possibly
8002 untested, features added since the release. This is also the way to
8003 correct bugs found during testing in an environment where other
8004 developers have continued to commit to the Main line while you are
8005 testing and packaging the release.
8007 Although the internal format of this type of branch (branch tag and
8008 RCS branches) is the same as in a development branch, its purpose and
8009 the way it is managed are different. The major difference is that a
8010 Release branch is normally Permanent. Once you let a release out the
8011 door to customers, or to the next stage of whatever process you are
8012 using, you should retain forever the branch marking that release.
8014 Since the branch is permanent, you cannot incorporate the branch fixes
8015 into the Main line by "collapsing" (merging and forgetting) the
8016 release branch. For large changes to many files on the release branch,
8017 you will have to perform a branch merge using "update -j <rev> -j
8020 The most common way to merge small changes back into Main line
8021 development is to make the change in both places simultaneously. This
8022 is faster than trying to perform a selective merge.
8024 See 1D.12 (merges) and Section 4C, on Branching for more info.
8026 Last modified: _6/13/1997_
8028 10. What is "the trunk"?
8030 Another name for the RCS Main Branch. The RCS Main Branch is related,
8031 but not equivalent, to both the CVS Main branch and what developers
8032 consider to be the Main line of development. See 3H.3 and Section 4C
8035 Last modified: _6/13/1997_
8037 11. What is a module?
8039 In essence, a module is a name you hand to the "checkout" command to
8040 retrieve one or more files to work on. It was originally intended to
8041 be a simple, unique name in the "modules" file attached to a directory
8042 or a subset of files within a directory.
8044 The module idea is now a somewhat slippery concept that can be defined
8045 in two different ways:
8046 * A module is an argument to "checkout". There are three types:
8047 1. An entry in the modules file. A "module" name as described in
8049 2. A relative path to a directory or file in the Repository.
8050 3. A mixed-mode string of "modulename/relative-path". Everything
8051 up to the first slash ('/') is looked up as a module. The
8052 relative path is appended to the directory associated with
8053 the module name and the resulting path is checked out as in
8055 * A module is a unique (within the file) character string in the
8056 first column of the modules file. There are five types:
8057 1. A name for a directory within the Repository that allows you
8058 to ignore the parent directories above it.
8061 2. A name for a subset of the files within such a directory.
8063 ls unix/bin Makefile ls.c
8064 The 2nd through Nth strings in the above can be files,
8065 directories or module substitutions. No relative paths.
8066 A module substitution occurs when you use a '&module-name'
8067 reference. The module-name referred to is logically
8068 substituted for the '&module-name' string.
8069 3. A relative pathname to a directory within the Repository
8070 which, when checked out, creates an image of part of the
8071 Repository structure in your current directory.
8073 gnu/emacs -o /bin/emacs.helper gnu/emacs
8074 The files checked out are exactly the same as the files
8075 "checkout" would retrieve if the path weren't even in the
8076 modules file. The only reason to put this kind of relative
8077 pathname into the modules file is to hook one of the helper
8079 4. A relative pathname to a single file within the Repository
8080 which, when checked out, creates something you probably don't
8081 want: It creates a directory by the name of the file and puts
8084 gnu/emacs/Makefile -o /bin/emacs.helper gnu/emacs Makefile
8085 The file checked out is the same as what you would get if you
8086 handed the relative pathname to the "checkout" command. But
8087 it puts it in a strange place. The only reason to do this is
8088 to hook a helper function onto a specific file name.
8089 5. An alias consisting of a list of any of the above, including
8090 other aliases, plus exceptions.
8092 my_work -a emacs !emacs/tests gnu/bison unix/bin/ls.c
8093 The exception "!emacs/test" above is functionally equivalent
8094 to specifying "!emacs/tests" on the "checkout" command line.
8096 Another way to look at it is that the modules file is simply another
8097 way to "name" files. The hierarchical directory structure provides
8098 another. You should use whatever turns out to be simplest for your
8101 See 4G.2 for some specific ideas about how to use the modules file.
8103 Last modified: _11/12/1997_
8105 12. What does "merge" mean?
8107 A merge is a way of combining changes made in two independent copies
8108 of a common starting file. Checking out an RCS revision produces a
8109 file, so for the purposes of a merge "file" and "revision" are
8110 equivalent. So, we can say there are always three "files" involved in
8113 The original, starting, "base" or "branch point" file.
8115 A copy of the base file modified in one way.
8117 Another copy of the base file modified in a different way.
8119 Humans aren't very good at handling three things at once, so the
8120 terminology dealing with merges can become strained. One way to think
8121 about it is that all merges are performed by inserting the difference
8122 between a base revision and a later revision (committed by someone
8123 else) into your working file. Both the "later" revision and your
8124 working file are presumed to have started life as a copy of the "base"
8127 In CVS, there are three main types of "merge":
8129 The "update" command automatically merges revisions committed by
8130 others into your working file. In this case, the three files involved
8133 Base: The revision you originally checked out. Later: A revision
8134 committed onto the current branch after you checked out the Base
8135 revision. Working: Your working file. The one lying in the working
8136 directory containing changes you have made.
8138 The "update -j <branch_tag> {optional files}" command merges changes
8139 made on the given branch into your working files, which is presumed to
8140 be on the Main line of development.
8144 The "update -j <rev> -j <rev> {optional files}" command merges the
8145 difference between two specified revisions into files in your working
8146 directory. The two revisions <rev> are usually on the same branch and,
8147 when updating multiple files, they are most useful when they are Tag
8148 names rather than numeric revisions.
8152 Last modified: _6/13/1997_
8154 Category: /What_is_CVS_/What_is_CVS_Whats_it/
8156 " + What is CVS? What's it for? Why CVS?"
8158 1. What does CVS stand for? Can you describe it in one sentence?
8160 "CVS" is an acronym for the "Concurrent Versions System".
8162 CVS is a "Source Control" or "Revision Control" tool designed to keep
8163 track of source changes made by groups of developers working on the
8164 same files, allowing them to stay in sync with each other as each
8167 Last modified: _6/13/1997_
8169 2. What is CVS for? What does it do for me?
8171 CVS is used to keep track of collections of files in a shared
8172 directory called "The Repository". Each collection of files can be
8173 given a "module" name, which is used to "checkout" that collection.
8175 After checkout, files can be modified (using your favorite editor),
8176 "committed" back into the Repository and compared against earlier
8177 revisions. Collections of files can be "tagged" with a symbolic name
8178 for later retrieval.
8180 You can add new files, remove files you no longer want, ask for
8181 information about sets of files in three different ways, produce patch
8182 "diffs" from a base revision and merge the committed changes of other
8183 developers into your working files.
8185 Last modified: _6/13/1997_
8187 3. How does CVS work?
8189 CVS saves its version-control information in RCS files stored in a
8190 directory hierarchy, called the Repository, which is separate from the
8191 user's working directory.
8193 Files in the Repository are stored in a format dictated by the RCS
8194 commands CVS uses to do much of its real work. RCS files are standard
8195 byte-stream files with an internal format described by keywords stored
8196 in the files themselves.
8198 To begin work, you execute a "checkout" command, handing it a module
8199 name or directory path (relative to the $CVSROOT variable) you want to
8200 work on. CVS copies the latest revision of each file in the specified
8201 module or directory out of the Repository and into a directory tree
8202 created in your current directory. You may specify a particular branch
8203 to work on by symbolic name if you don't want to work on the default
8204 (main or trunk) branch.
8206 You may then modify files in the new directory tree, build them into
8207 output files and test the results. When you want to make your changes
8208 available to other developers, you "commit" them back into the
8211 Other developers can check out the same files at the same time. To
8212 merge the committed work of others into your working files you use the
8213 "update" command. When your merged files build and test correctly, you
8214 may commit the merged result. This method is referred to as
8215 "copy-modify-merge", which does not require locks on the source files.
8217 At any time, usually at some milestone, you can "tag" the committed
8218 files, producing a symbolic name that can be handed to a future
8219 "checkout" command. A special form of "tag" produces a branch in
8220 development, as usually happens at "release" time.
8222 When you no longer plan to modify or refer to your local copy of the
8223 files, they can be removed.
8225 Last modified: _6/13/1997_
8227 4. What is CVS useful for?
8229 CVS is intended to handle source control for files in three major
8232 Multiple developers working on the same files.
8234 The major advantage of using CVS over the simpler tools like RCS or
8235 SCCS is that it allows multiple developers to work on the same sources
8238 The shared Repository provides a rendezvous for committed sources that
8239 allows developers a fair amount of flexibility in how often to publish
8240 (via the "commit" command) changes or include work committed by others
8241 (via the "update" command).
8243 Tracking a stream of releases from a source vendor.
8245 If you are making changes to sources distributed by someone else, the
8246 CVS feature, called the Vendor Branch, allows you to combine local
8247 modifications with repeated vendor releases.
8249 I have found this most useful when dealing with sources from three
8250 major classes of source vendor:
8252 Large companies who send you tapes full of the latest release (e.g.
8253 Unix OS vendors, database companies).
8255 Public Domain software which *always* requires work.
8257 Pseudo-Public sources which may require work. (e.g. GNU programs, X,
8260 Branching development.
8262 Aside from the "Vendor Branch", there are three kinds of "branches in
8263 development" that CVS can support:
8265 Your working directory can be treated as a private branch.
8267 A Development branch can be shared by one or more developers.
8269 At release time, a branch is usually created for bug fixes.
8271 (See 1D.9 and Section 4C for more info on branches.)
8273 CVS's branch support is a bit primitive, but it was designed to allow
8274 you to create branches, work on them for while and merge them back
8275 into the main line of development. You should also be able to merge
8276 work performed on the main branch into the branch you are working on.
8277 Arbitrary sharing and merging between branches is not currently
8280 Last modified: _6/13/1997_
8282 5. What is CVS *not* useful for?
8284 CVS is not a build system.
8286 Though the structure of your Repository and modules file interact with
8287 your build system (e.g. a tree of Makefiles), they are essentially
8290 CVS does not dictate how you build anything. It merely stores files
8291 for retrieval in a tree structure you devise.
8293 CVS does not dictate how to use disk space in the checked out working
8294 directories. If you require your Makefiles or build procedures to know
8295 the relative positions of everything else, you wind up requiring the
8296 entire Repository to be checked out. That's simply bad planning.
8298 If you modularize your work, and construct a build system that will
8299 share files (via links, mounts, VPATH in Makefiles, etc.), you can
8300 arrange your disk usage however you like.
8302 But you have to remember that *any* such system is a lot of work to
8303 construct and maintain. CVS does not address the issues involved. You
8304 must use your brain and a collection of other tools to provide a build
8305 scheme to match your plans.
8307 Of course, you should use CVS to maintain the tools created to support
8308 such a build system (scripts, Makefiles, etc).
8310 CVS is not a substitute for management.
8312 You and your project leaders are expected to plan what you are doing.
8313 Everyone involved must be aware of schedules, merge points, branch
8314 names, release dates and the range of procedures needed to build
8315 products. (If you produce it and someone else uses it, it is a
8316 product.) CVS can't cover for a failure to manage your project.
8318 CVS is an instrument for making sources dance to your tune. But you
8319 are the piper and the composer. No instrument plays itself or writes
8322 CVS is not a substitute for developer communication.
8324 When faced with conflicts within a single file, most developers manage
8325 to resolve them without too much effort. But a more general definition
8326 of "conflict" includes problems too difficult to solve without
8327 communication between developers.
8329 CVS cannot determine when simultaneous changes within a single file,
8330 or across a whole collection of files, will logically conflict with
8331 one another. Its concept of a "conflict" is purely textual, arising
8332 when two changes to the same base file are near enough to spook the
8333 merge command into dropping conflict markers into the merged file.
8335 CVS is not capable of figuring out distributed conflicts in program
8336 logic. For example, if you change the arguments to function X defined
8337 in file A and, at the same time, edit file B, adding new calls to
8338 function X using the old arguments. You are outside the realm of CVS's
8341 Acquire the habit of reading specs and talking to your peers.
8343 CVS is not a configuration management system.
8345 CVS is a source control system. The phrase "configuration management"
8346 is a marketing term, not an industry-recognized set of functions.
8348 A true "configuration management system" would contain elements of the
8352 * Dependency tracking.
8353 * Build systems (i.e. What to build and how to find
8354 things during a build. What is shared? What is local?)
8356 * Automated Testing procedures.
8357 * Release Engineering documentation and procedures.
8358 * Tape Construction.
8359 * Customer Installation.
8360 * A way for users to run different versions of the same
8361 software on the same host at the same time.
8363 CVS provides only the first.
8365 Last modified: _6/13/1997_
8367 Category: /What_is_CVS_/Where_do_I_find_CVS_/
8369 " + Where do I find CVS? Where can I find Help?"
8371 1. How do I get more information about CVS?
8373 The first thing I would do is to read the Info file that comes with
8374 the CVS sources under "doc". You can format and read the cvs.texinfo
8375 file in two ways: 1. Use TeX to format it and a "dvips" command to
8376 print it and 2. Install the cvs.info files that are created by the
8377 Makefile and read them online using the Emacs "info-mode" or a
8378 stand-alone "info" reader.
8380 Then I'd run "cvsinit" to set up a Repository and read the man page
8381 while trying out the commands.
8383 Type "cvs -H" for general help or "cvs -H command" for
8384 command-specific help.
8386 For background, you can read the original CVS paper (in the source
8387 tree, under "doc"). It describes the purpose of CVS and some of how it
8388 was designed. Note that the emphasis of the document (especially on
8389 multiple vendors providing the same sources) is somewhat out of date.
8391 For more detailed information about "internals", read the man pages
8392 for RCS. If you are a programmer, you can also read the source code to
8395 Other information and tutorials may be available in the "doc"
8396 directory of the FTP archive described below.
8398 For current information, and a fair amount of detail, join the
8399 info-cvs mailing list described below.
8401 Last modified: _6/13/1997_
8403 2. Is there an archive of CVS material?
8405 An anonymous FTP area has been set up. It contains many of the CVS
8406 files you might want, including extra documentation, patches and a
8407 copy of the latest release.
8416 The README has more (and more up-to-date) information. The Index
8417 contains a terse list of what is in the archive.
8419 A WWW home page is also available at http://www.delos.com/cvs.
8421 This Didn't Exist 6/23/1998
8423 Last modified: _6/24/1998_
8425 3. How do I get files out of the archive if I don't have FTP?
8427 Use one of the FTP<->Email servers. These are the ones I've been told
8430 FTPMAIL service is available from the same host as the FTP server
8431 described above. Send mail to "ftpmail@delos.com" containing "help" in
8432 the body of the message. For example, on most Unix systems, you can
8435 echo help | Mail ftpmail@delos.com
8437 The FTPMAIL server will respond with a document describing how to use
8438 the server. If the "Mail" command doesn't exist on your system, try
8439 "mailx", "/usr/ucb/mail" or "/bin/mail".
8441 If you are on BITNET, use Princeton's BITFTP server. Type
8443 echo 'send help' | Mail bitftp@pucc.princeton.edu
8445 (It is likely that only BITNET addresses can use this one.)
8447 Other possibilities I've heard of from the net: (Try the one closest
8450 ftpmail@decwrl.dec.com ftpmail@sunsite.unc.edu ftpmail@cs.arizona.edu
8451 ftpmail@cs.uow.edu.au ftpmail@doc.ic.ac.uk
8453 Last modified: _6/13/1997_
8455 4. How do I get a copy of the latest version of CVS?
8457 The latest released version of CVS and all the programs it depends on
8458 should be available through anonymous FTP on any FSF archive. The main
8459 FSF archive is at "prep.ai.mit.edu". There are mirrors of the FSF
8460 archive on UUNET and other large Internet sites.
8462 Program(s) Suggested revision
8463 ----------- -----------------------
8465 RCS 5.7 (latest version available today)
8466 GNU diff 2.7 (or later) [contained in diffutils-2.7]
8467 GDBM 1.5 (or later) [optional]
8469 The GNU version of diff is suggested by both the RCS and CVS
8470 configuration instructions because it works better than the standard
8473 It is a good idea not to accept the versions of CVS, RCS or diff you
8474 find lying on your system unless you have checked out their
8475 provenance. Using inconsistent collections of tools can cause you more
8476 trouble than you can probably afford.
8478 The FTP archive mentioned above should contain the latest official
8479 release of CVS, some official and unofficial patches and possibly
8480 complete patched versions of CVS in use somewhere.
8482 Last modified: _6/13/1997_
8484 5. Is there a mailing list devoted to CVS? How do I find it?
8486 An Internet mailing list named "info-cvs" grew out of the private
8487 mailing list used by the CVS 1.3 alpha testers in early 1992.
8488 Throughout 1994, the list received an average of 100 messages per
8491 You can add yourself to the mailing list by sending an Email message
8494 info-cvs-request@prep.ai.mit.edu
8496 (Don't forget the "-request" or you'll send a message to the whole
8497 list, some of whom are capable of remote execution.)
8499 Mail to the whole list should be sent to:
8501 info-cvs@prep.ai.mit.edu
8503 An archive of the mailing list is maintained in the FTP archive
8506 Last modified: _6/13/1997_
8508 6. What happened to the CVS Usenet newsgroup I heard about?
8511 A Usenet newsgroup named "gnu.cvs.info" was announced in April
8512 1993, with an expected creation date of August, 1993. However,
8513 nothing came of this.
8515 If you want to discuss CVS on usenet, the correct group is
8516 comp.software.config-mgmt (which also covers other configuration
8517 management systems). Someday it might be possible to create a
8518 comp.software.config-mgmt.cvs, but only if there is sufficient
8519 CVS traffic on comp.software.config-mgmt.
8523 Last modified: _9/6/1997_
8524 _________________________________________________________________
8526 [Add an answer to this category]
8529 _________________________________________________________________
8531 _Search the FAQ-O-Matic:_ ____________________ Search
8532 [matching all words]
8533 Or look for questions modified in the last: [7.] Days
8534 _________________________________________________________________
8536 The FAQ-O-Matic lives at http://gille.loria.fr:7000/cgi-bin/faqomatic.
8537 The code was written by Jon Howell, and the content by folks from all
8539 _________________________________________________________________
projects / FreeBSD / FreeBSD.git / blob