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
1900 instead. For more on tkCVS, see http://www.cyclic.com/tkcvs/
1904 Last modified: _9/6/1997_
1908 CAVEMAN is a front end to CVS written in PERL providing a collection
1909 of features desired by the site where it was developed.
1911 - The ability to spread a "project" over multiple Repositories.
1912 - Optional automatic tagging after each commit.
1913 - Additional locking of files.
1914 - Extra before and after program hooks.
1915 - A layer of event logging.
1916 - All sorts of error messages.
1917 - Many changes to the semantics of commands.
1919 It is available via anonymous ftp on ftp.llnl.gov [128.115.54.18] in
1920 gnu/caveman_vX.Y.Z.tar.gz (The numbers X, Y, & Z vary.)
1922 contact Kathleen Dyer kdyer@llnl.gov
1926 [[Does someone want to elaborate?]]
1928 Last modified: _6/13/1997_
1930 Category: /Advanced_Topics_/Setting_up_and_Manag/
1932 " + Setting up and Managing the Repository"
1934 1. What do I do first? How do I create a Repository?
1936 First, install all the programs. (See Section 4A.)
1938 Then create a Repository by executing "cvs -d init". (This works with
1941 Now you can configure your repository by checking out CVSROOT: "cvs -d
1942 checkout CVSROOT". Change into the created directory CVSROOT. Edit the
1943 files you want to edit, and afterwards, commit the changes by typing
1946 You will certainly want to add modules of your own. Edit the "modules"
1947 file and add lines to describe the items you want to "checkout" by
1948 module name. Here's a short list that could be used for storing a
1949 small number of GNU and PD sources:
1954 emacs local/gnu/emacs
1958 pdprog1 local/public/pdprog1
1959 pdprog2 local/public/pdprog2
1966 Last modified: _4/21/1998_
1968 2. What are those files in $CVSROOT/CVSROOT?
1970 There are eight Repository control (or "database") files of interest
1971 in the CVSROOT directory:
1973 modules contains the "modules" database. See 1D.11, 2C.7, 4B.6 and
1974 4B.7 for more details.
1976 commitinfo contains two columns: 1. a regular expression to match
1977 against pathnames within the Repository and
1979 a <command> to execute for matching pathnames.
1981 When you execute "commit", CVS passes the Repository pathname for each
1982 directory (and the files to commit within that directory) to
1983 <command>. If <command> exits with a non-zero status, the commit is
1986 A <command> associated with a pathname of "DEFAULT" is executed if
1987 nothing else matches. Every <command> associated with a pathname of
1988 "ALL" is executed separately.
1990 rcsinfo contains the same first column as commitinfo, but the second
1991 column is a template file for specifying the log entry you are
1992 required to enter for each commit.
1994 "DEFAULT" and "ALL" work the same as in the commitinfo file.
1996 editinfo contains the same two columns as commitinfo, but the
1997 <command> in the second column is intended to do some consistency
1998 checking on the commit log.
2000 "DEFAULT" works as in commitinfo.
2002 loginfo contains the same two columns as commitinfo, but the
2003 <command> is expected to read a log message from its standard input.
2004 The <command> can do anything it wants with the log information, but
2005 normally it is appended to a log file or sent to mailing lists.
2007 "DEFAULT" & "ALL" work the same as in commitinfo.
2009 cvsignore contains "ignore" patterns that are added to the built-in
2010 ignore list. See 2D.10.
2012 checkoutlist contains a list of other files kept under RCS in
2013 $CVSROOT/CVSROOT that should be checked out by mkmodules to provide a
2016 history contains a stream of text records, one for each event that
2017 the "history" command is interested in. Though the contents of the
2018 history file can be read, it is intended to be read and displayed by
2019 the "history" command. This file is the only one in the above list
2020 that is not under RCS.
2022 Last modified: _6/13/1997_
2024 3. Is there any other state stored in the Repository besides in the
2025 $CVSROOT/CVSROOT directory?
2027 Only in the RCS files. The Repository holds exactly two things: the
2028 tree of RCS files (each usually ending in ",v") and the CVSROOT
2029 directory described above.
2031 Last modified: _6/13/1997_
2033 4. How do I put sources into the Repository?
2035 There are three main ways to put files in the Repository:
2037 Use the "import" command described in Section 3H.
2039 This method is the fastest way to put trees of new code into the
2040 Repository and the *only* way to handle source releases from a 3rd
2041 party software vendor.
2043 Use "add" followed by "commit".
2045 This is how to add new files and directories to the Repository, a few
2046 at a time. Directories don't need to be committed.
2048 You can move RCS files directly into the Repository.
2050 You should create a directory hierarchy to hold them, but you can just
2051 move arbitrary ",v" files into the Repository. The only "state" in the
2052 Repository other than within ",v" files is in the required CVSROOT
2053 directory at the top of the Repository.
2055 Last modified: _6/13/1997_
2057 5. What file permissions should I use on (and in) the Repository?
2059 If you are using pserver (password-authenticated access), see below.
2061 If you run a completely open environment (which usually means that you
2062 don't have, or don't want to waste, the time to deal with it):
2064 - Set all directory permissions to 777.
2066 - Have everyone set their umasks to 0.
2068 (BTW, I don't suggest this. I am merely reporting it.)
2070 If you are a normal Unix shop and want to use groups effectively:
2072 - Set all the directory permissions in the Repository to 775.
2074 If you are using a system that handles both System V and BSD
2075 filesystems, you might have to set the permissions to 2775.)
2077 If you are using one of the many recent versions of Unix that don't
2078 allow you to use the full octal mode, then you'll have to type: chmod
2079 u=rwx,g=rwx,o=rx,g+s dir>
2081 - Change all the groups on the directories to match the groups you
2082 want to write to various directories.
2084 - Make sure every user is in the appropriate groups.
2086 - Have everyone set their umask to 002, including root.
2088 If you don't want non-group members to even read the files, do the
2091 - Repository directory permissions to 770. (or 2770)
2095 If you work in an environment where people can't be trusted to set
2096 their "umask" to something reasonable, you might want to set the umask
2099 mv /usr/local/bin/cvs /usr/local/bin/cvs.real
2100 cat > /usr/local/bin/cvs
2102 umask 2 # Or whatever your site standard is.
2103 exec /usr/local/bin/cvs.real ${1+"$@"}
2106 Pserver (Password-Authenticated Access) <blome@de.ibm.com>
2108 The above suggestions are not valid when you use the pserver facility.
2109 Be sure to read and understand the manual section about this (should
2110 be 4.6.something). Above all: do /not/ make the repository and CVSROOT
2111 group writeable. In CVSROOT, make `history´ group or world writeable
2114 I suggest creating one unix group per project group. In the
2115 repository, you would then create one directory for each group, group
2116 writeable. New projects must then be created in these group
2117 directories. If you don't want to say <group>/<project> on
2118 checkout, create a <project> module and point it there.
2120 Last modified: _9/24/1998_
2122 6. How do I structure my Repository?
2124 The Repository holds your software. It can be all interrelated or it
2125 can be a bunch of separately managed directories.
2127 How you break a whole system down into its component parts, while
2128 defining interfaces between them, is one aspect of "Software
2129 Engineering", a discipline that requires the study of dozens of
2130 strange and wonderful areas of the computer and management worlds.
2132 CVS provides a way to keep track of changes to individual files, a way
2133 to "tag" collections of files, and a way to "name" collections of
2134 files and directories. That's all. Everything else is in the way you
2137 In other words, you should structure your Repository to match your
2138 needs, usually tied in with the other tools you use to build, install
2139 and distribute your work. Common needs include the ability to:
2141 - mount (or automount) directories from many places in your
2143 - check out just what you need and no more.
2144 - check out multiple sections in a fixed relation to each other.
2145 - check out large sections to match the assumptions built into your
2146 build system. (Makefiles?)
2148 In my opinion, you should start small and keep everything in one tree,
2149 placing each major sub-system into a separate directory. Later, when
2150 you know what you are doing, you can make it more sophisticated.
2152 Last modified: _6/13/1997_
2154 7. Why would anyone use "modules"? They are too restrictive. I want to be
2155 able to select just the files I want to edit.
2157 Any form of structure is restrictive. If you believe that total chaos
2158 is a viable working paradigm, or if you believe you can keep track of
2159 the interrelations between all portions of your Repository in your
2160 head, then you can do what you please.
2162 If you believe that systems of files require management and structure,
2163 then the "modules" idea is very useful. It is a way to impose a naming
2164 scheme on a tree of files, a naming scheme that can be simpler than a
2165 large list of relative pathnames.
2167 The "modules" file represents a published interface to the Repository
2168 set up by your Repository Administrator. If s/he did a creditable job,
2169 the modules offered will be internally consistent and will smoothly
2170 interact with the rest of your environment.
2172 Last modified: _6/13/1997_
2174 8. How do I rename a file or directory? What are the consequences?
2176 In CVS there is no single "rename" command.
2178 See 2C.4 for the suggested way to rename a file or directory.
2180 The rest of this section covers some of the consequences of renaming.
2182 A "renaming database" has been proposed that would keep track of name
2183 changes so that "update -r <tag>" would continue to work across the
2184 renaming. But as it stands, you have to pick one of the following
2187 Use the technique described in 2C.4. (For each file, duplicate the
2188 file in the Repository, "remove" the old version so it winds up in the
2189 Attic and strip all Tags off the new version.)
2191 - "update -r <tag>" produces the correct files.
2193 - The duplicated revision history can be slightly misleading.
2195 - A plain (i.e. without the "-r <tag>") "checkout" or "update -d" will
2196 create directories "renamed" this way, but you can delete it and a
2197 plain "update" won't bring it back.
2199 Move the files and directories in the Repository to the new names.
2201 - You save the revision history under a different file name.
2203 - You save a little space.
2205 - "update -r <tag>" produces the wrong files or directories.
2207 This is not a good general solution, but if you plan never to look
2208 back (someone may be gaining on you!), it is sometimes a useful
2211 If you are clever with Makefiles, you might be able to rework them to
2212 handle either the new or old names, depending on which ones exist at
2213 the time. Then you can move an old <tag> onto the new, more
2214 sophisticated, revision of the Makefile. (Yes, this changes the
2215 "released" file if <tag> indicates a release. But it is an option.)
2217 - Important Note: If you rename a directory, you must rename the
2218 corresponding directory in every checked-out working directory. At the
2219 same time, you must edit the pathname stored in the ./CVS/Repository
2220 file within each of the moved directories.
2222 The easiest way to move a lot of directories around is to tell
2223 everyone to remove their working directories and check them out again
2226 - The file exists in the working directory and in the ./CVS/Entries
2227 file, but not in the Repository. For the old file, "update" prints:
2229 cvs update: xyz.c is no longer in the repository
2231 and deletes the file. If the file was modified, "update" prints:
2233 cvs update: conflict: xyz.c is modified but no longer in the
2236 and leaves the file alone. In the new directory, you see:
2240 as you would if someone else executed "add" and "commit".
2242 For each file, copy the working file to a new name in the working
2243 directory and use the "cvs remove" to get rid of the old old file and
2244 "cvs add" to add the new one. Since there is no way for CVS to remove
2245 a directory, this only works for files.
2247 - This is what most people think of first. Without a "rename" command,
2248 the remove/add technique seems obvious.
2250 - You lose the connection of your new working file to its past
2253 Last modified: _6/13/1997_
2255 9. What are "Attic" directories?
2257 When you use the "remove" command on a file, CVS doesn't delete the
2258 file, it only registers your desire to delete it.
2260 When you "commit" a removed file, CVS moves the Repository's matching
2261 RCS file into a sub-directory named "Attic" within the Repository.
2263 Attic files are examined when the '-r' or '-D' option is used on
2264 "checkout" or "update". If the specified revision, tag or date matches
2265 one on a file in the Attic, that file is checked out with the others.
2267 You can think of the Attic as a sort of dead branch, which is only
2268 looked at when you refer to a <tag> or <date>.
2270 Last modified: _6/13/1997_
2272 10. Is it OK to remove anything from the Repository?
2274 In general, removing anything from the Repository is a bad idea. The
2275 information in a deleted object is lost forever. There are many ways
2276 to skip over files, directories and revisions without deleting them.
2278 Here are some of the consequences of removing the following things
2279 stored in the Repository:
2281 CVSROOT files (Repository control files)
2283 The Repository will work without any of them, but you should
2284 understand what you are losing by deleting them. See 4B.2.
2288 The only way to remove revisions is to use the "admin -o" command (or
2289 the equivalent RCS command "rcs -o").
2291 They are lost forever. Any tags formerly attached to deleted revisions
2292 are now pointing into the Phantom Zone. You'll need to contact Jor-el
2297 You should not remove a file unless you truly never want to see it
2298 again. If you want to be able to check out an old revision of this
2299 file, use "cvs remove" instead.
2303 Tags take up little space and you can't recover from deleting them. If
2304 you depend on tags for releases you will lose vital information.
2308 There is no Attic for directories, so the only way to remove them is
2309 to use "rm -r". They are gone forever.
2311 If you delete (or move) a directory, all checked-out versions of that
2312 directory will cause CVS to halt. You'll have to visit each
2313 checked-out directory and remove the matching working directory by
2318 The "remove" command sends files to the Attic. To really delete them,
2319 you have to go into the Attic and use "rm".
2321 If a file in the Attic has a Tag on it that you might ever want to
2322 check out again, you probably don't want to delete it.
2324 Lock files (named: "#cvs.[wr]fl.<pid>")
2326 These are lock files. If you are getting "lock" errors and the dates
2327 on the lock files indicate that they are old, you can delete them.
2329 Deleting lock files still in use by a CVS process might produce
2332 Last modified: _6/13/1997_
2334 11. Can I convert to CVS from RCS without losing my revision history?
2336 Yes, you can simply move (or copy) your RCS files into a directory
2337 within the Repository, check out that directory and start working.
2339 Last modified: _6/13/1997_
2341 12. Can I move RCS files with branches in them into the Repository?
2343 Yes, but they may not work if you created branches in a way that
2344 conflicts with CVS's assumptions:
2346 You can't use .0. branches. (They are reserved for "Magic" branch
2349 If you use branch 1.1.1, you can't use the Vendor branch.
2351 You can use other RCS branches under CVS. There is no need to create
2352 "magic" branch tags because the physical branch already exists.
2354 Last modified: _6/13/1997_
2356 13. Can I use raw RCS commands on the Repository?
2358 You can use raw rcs commands directly on the Repository if you take a
2359 little care. The Repository itself contains no "CVS state" (as opposed
2360 to RCS revision histories) outside the CVSROOT directory.
2362 But using raw RCS commands to change branches, tags or other things
2363 that CVS depends on may render the files unusable.
2365 See 4D.7 on RCS/CVS sharing of the Repository and Section 3B on the
2368 Last modified: _6/13/1997_
2370 14. How do I convert from SCCS to RCS?
2372 You'll have to execute something like "sccs2rcs" (in the CVS contrib
2373 directory) on every file. Then you can move the resulting RCS files
2374 into the Repository as described above.
2376 Last modified: _6/13/1997_
2378 15. How do I limit access to the Repository?
2380 There are all sorts of ways to restrict access to Repository files,
2381 none of which are hooked directly into CVS.
2383 Techniques for limiting access include:
2385 Training, management and good backups.
2387 The best form of Repository control is a combination of:
2389 - A reliable backup scheme (verify it!)
2390 - Enough training to ensure your developers are competent and
2391 knowledgeable about all areas of your sources.
2392 - Effective management of the boundaries and grey areas.
2394 In many cases, technical solutions to "security" problems are
2395 inadequate. You should first try to avoid them.
2397 Personal Opinion: In an environment where "unknowns" are allowed to
2398 touch important sources the "owner" of the CVS Repository must be a
2399 large, loud, vigorous lout with a well-balanced truncheon and the
2400 right to use it. Don't underestimate the effectiveness of letting
2401 everyone know they will be strapped into the stocks on the Town Common
2402 and pelted with vegetables if they break something they don't
2403 understand without first asking the experts.
2405 Set Unix groups and permissions. See 4B.5. You can set different
2406 owners, groups and permissions for each sub-directory within the
2407 Repository if that helps.
2409 Catch invocations of "commit" by defining pre-commit programs in the
2410 "commitinfo" file. This is fairly powerful, since it can block commits
2411 based on anything you can program. Take a look at the programs in the
2412 "contrib" directory of the CVS source tree.
2414 Use multiple Repositories, each with its own protection scheme. If
2415 you use NFS (or AFS) you can even use "export" restrictions to various
2416 groups of machines to keep (for example) the Engineering Repository
2417 off the Customer Service machines.
2419 Try the "setgid" trick described in 4D.13.
2421 Try to use the RCS access control lists, though I don't think CVS
2422 will handle them cleanly.
2424 Edit the source code to CVS to add your own access control.
2426 Last modified: _6/13/1997_
2428 16. What are the Repository Administrator's responsibilities?
2430 Generally, the Administrator should set "policy", create the
2431 Repository and monitor its size and control files.
2433 Some specific responsibilities include:
2435 Examining the Repository once in a while to clean up:
2437 Trash files left by misguided developers who mistake the Repository
2438 for a working directory.
2440 Non-RCS files. Other than the files CVS needs in the
2441 $CVSROOT/CVSROOT directory, every file in the Repository should be an
2444 Lock files (both CVS '#*' and RCS ',*' files) left around after
2447 Wrong permissions, groups and ownerships.
2449 Locked files. (RCS locks, that is.)
2451 Attic files that should never have been under CVS at all. Don't
2452 blindly delete files from Attic directories -- they were mostly put
2453 there (via the "cvs remove") for a reason. Files that should be
2454 deleted are binary files (e.g. '*.o', 'core', executables) that were
2455 mistakenly inserted by "import -I !".
2457 Maintaining the modules file.
2459 Storing site-specific ignore patterns in the
2460 $CVSROOT/CVSROOT/cvsignore file.
2462 Storing the names of non-standard CVSROOT files (See 4B.2) in the
2463 $CVSROOT/CVSROOT/checkoutlist
2465 Maintaining the other Repository control files: commitinfo, loginfo,
2466 rcsinfo and editinfo.
2468 Pruning the history file every once in a while. (Try the
2469 "cln_hist.pl" script in the "contrib" directory.)
2471 Staying aware of developments on the info-cvs mailing list and what
2472 is available in the FTP and WWW archives.
2474 Running "ps ax" once in a while and kill off any "update" programs
2475 not running as "root". It is too easy to leave the "cvs" off the front
2476 of the "cvs update" command.
2478 Executing monitor programs to check the internal consistency of the
2479 Repository files. Ideas:
2481 Files that have a default RCS branch that is not 1.1.1 (From an
2482 abuse of "admin -b".)
2484 Files that have only Revisions 1.1 and 1.1.1.1, with a default
2485 branch of "MAIN". (From an abuse of "admin -o".)
2487 Existing branch tags and various branch consistency checks.
2489 Last modified: _6/13/1997_
2491 17. How do I move the whole Repository?
2493 Copy or move the tree. (On Unix systems, a set of piped "tar" commands
2494 works great. If the Repository does not contain any symlinks, which it
2495 normally doesn't, you can also use "cp -r".)
2497 If you can avoid changing $CVSROOT (i.e. the "logical" pathname of the
2498 Repository) by replacing the old location with a symbolic link to the
2499 new location, you don't have to do anything else.
2501 (You could also mount the new location on top of the old location if
2502 you are using NFS or some other filesystem that allows it.)
2504 If you must change $CVSROOT, you must also tell everyone to change the
2505 CVSROOT environment variable in all running shells and in any personal
2506 configuration files ('.' files on Unix) where it is set.
2508 The Repository itself contains no references to its own name, except
2509 possibly in some of the files in the CVSROOT directory. If your
2510 modules (or loginfo, commitinfo, etc.) file mentions helper programs
2511 directly in the Repository, you'll have to change the pathnames to
2512 point to the new Repository location.
2514 The main changes you'll have to make are to all the CVS administrative
2515 files (./CVS/Repository and ./CVS/Root) in every working directory
2516 ever checked out from the previous location of the Repository you just
2519 You have three choices:
2521 If all ./CVS/Repository files in all working directories contain
2522 relative pathnames, you don't have to do anything else.
2524 Have everyone "release" or delete their working directories (after
2525 committing, or just saving, their work) and check them all out again
2526 from the new Repository after the move.
2528 Use "find . ( -name Repository -o -name Root )" and a PERL or shell
2529 script to run through all the ./CVS/Repository and ./CVS/Root files
2530 and edit the values in the files.
2532 Last modified: _6/13/1997_
2534 18. How do I change permissions on a file in the Repository by using a CVS
2535 command? (i.e. without using "chmod 777 $CVSROOT/dir/file")
2537 When you first "import" or "add"/"commit" a file, the read and execute
2538 bits on the Repository file are inherited from the original source
2539 file, while the write bits on the Repository file are are turned off.
2540 This is a standard RCS action.
2542 After that, there is no way to alter the permissions on a file in the
2543 Repository using CVS (or RCS) commands. You have to change the
2544 permissions on both your working file and on the Repository file from
2545 which it was retrieved.
2547 Whenever you "checkout" the file or retrieve a new revision via
2548 "update" (or after a "commit"), your working file is set to match the
2549 permissions of the Repository file, minus any "umask" bits you have
2552 Last modified: _6/13/1997_
2554 Category: /Advanced_Topics_/Tricks_of_the_Trade/
2556 " + Tricks of the Trade"
2558 1. How can you even check in binary files, let alone allow CVS to do its
2559 auto-merge trick on them?
2562 First of all, if you want to use binary files, you should get RCS 5.7
2563 and CVS 1.9 or later (earlier versions had some support, but there have been
2564 bug fixes). Secondly, follow the instructions for installing RCS very
2565 carefully (it is easy to get it installed so it works for everything
2566 except binary files).
2568 Then, specify 'cvs add -kb' instead of just 'cvs add' to add a binary
2569 file. If you want to set an existing file to binary, run 'cvs admin
2570 -kb' (and then check in a new copy of the file). Note that old
2571 versions of CVS used -ko instead of -kb for binary files, so if you
2572 see a reference to -ko in the context of binary files, you should
2575 Of course when 'cvs update' finds that a merge is needed, it can't
2576 do this for binary files the same way as for text files. With the
2577 latest versions (e.g. CVS 1.9.14), it should be able to give you both
2578 versions and let you merge manually. Another approach is to
2579 run 'cvs admin -l' to lock files, as described in
2580 "How can I lock files while I'm working on them the way RCS does?"
2581 elsewhere in this FAQ. See also
2582 "Is there any way to import binary files?" and
2583 "How do I "add" a binary file?" elsewhere in this FAQ.
2587 Last modified: _9/6/1997_
2589 2. Can I edit the RCS (",v") files in the Repository?
2591 Yes, but be very careful. The RCS files are not free-form files, they
2592 have a structure that is easily broken by hand-editing. The only time
2593 I would suggest doing this is to recover from emergency failures that
2594 are difficult to deal with using CVS commands, including the "admin"
2595 command, which can talk directly to RCS.
2597 Though no one actively encourages the editing of RCS files, many
2598 people have succumbed to the urge to do so when pressed for time. The
2599 reasons given, usually with evident contrition, include:
2601 - Editing mistakes in, or adding text to, log entries. (If you have
2602 RCS 5.6 or later, you should use `cvs admin -m'.)
2603 - Renaming or moving symbolic names. (You should `cvs admin -N'
2605 - Unlocking a file by changing the "locker" from someone else to
2606 yourself. (It's safer to use `cvs admin -u -l'.)
2607 - Making global changes to past history. Example: Eradicating former
2608 employees names from old documents and Author entries. (And someone
2609 thought the "history" command was evidence of Big Brother! I never
2610 realized how much help a wide-open revision control system could have
2611 provided to The Ministry of Truth.)
2613 Last modified: _6/13/1997_
2615 3. Can I edit the ./CVS/{Entries,Repository,Tag} files?
2617 Yes, but with CVS 1.3 and later, there is almost no reason to edit any
2618 of the CVS administrative files.
2620 If you move pieces of your Repository around it can be faster to edit
2621 all the ./CVS/Repository files rather than checking out a large tree.
2622 But that is nearly the only reason to do so.
2624 Last modified: _6/13/1997_
2626 4. Someone executed "admin -o" and removed revisions to which tags/symbols
2627 were attached. How do I fix them?
2629 It depends on what you mean by "fix". I can think of three ways to fix
2634 Assuming you really wanted to get rid of the revision and its
2635 associated tags, you can remove them with the "admin" command. The
2636 "tag -d" command will only remove tags attached to existing revisions.
2637 You can remove a tag, even if it is attached to a non-existent
2638 revision, by typing:
2640 cvs admin -N<tag> <file>
2642 Retrieve the outdated revision.
2644 You should first look in your backup system for recent versions of the
2645 file. If you can't use them, you can carefully extract each revision
2646 that followed the earliest outdated revision using RCS (or "cvs
2647 admin") commands and reconstruct the file with all the right
2648 revisions, branches and tags. This is a lot of work.
2650 You *can't* insert a revision into the current RCS file.
2652 Move the Tags to another revision in each file.
2654 If you want to move the tags to another valid revision, you have two
2655 choices, both of which require that you find all the revision numbers
2656 of the files you want to "tag" and execute the following command
2657 sequences on each <file>.
2659 Use "update" to grab the revision you want, then execute a normal
2660 "tag" command to Tag that revision:
2662 cvs update -r <rev> <file>
2663 cvs tag <tag> <file>
2665 Use "admin" to set the tag to a specific revision:
2667 cvs admin -N<tag>:<rev> <file>
2669 Last modified: _6/13/1997_
2671 5. How do I move or rename a magic branch tag?
2673 (To rename a non-branch <tag> see 3O.9.)
2675 Before reading this, read 3M.3 and 3M.4 and understand exactly how tag
2676 and rtag use '-r' and why it won't do the right job here.
2678 First, I have to explain exactly what a magic branch tag is.
2680 A magic <branch_tag> is an artificial tag attached to a non-existent
2681 revision on a non-existent branch number zero. It looks like this:
2685 <X> is the "branch point revision", a normal revision with an
2686 odd number of '.'s in it. (e.g. 1.5, 1.3.1.6, etc)
2688 Y is an even number (e.g. 2, 4, 6, etc.) All CVS branches,
2689 other than the Vendor branch, are even numbered.
2691 TAG1 is considered by CVS to be attached to revision <X>. The first
2692 "update -r TAG1 <file>" after applying TAG1 will produce a copy of
2693 revision <X> with a sticky tag of TAG1. The first "commit" to that
2694 file will cause CVS to construct an RCS branch named <X>.Y and check
2695 in revision <X>.Y.1 on the new branch.
2697 Note: TAG1 is *not* considered to be attached to <X> by RCS, which
2698 explains why you can't refer directly to the branch point revision for
2701 Moving a magic <branch_tag> is the act of reapplying the same tag to
2702 different revisions in the file:
2706 TAG1:<X>.0.Z or TAG1:<A>.0.B
2708 You can move a magic branch tag to the revisions of your choice by
2709 using "update" to find the revisions you want to tag and reapplying
2710 the tag to all the files with the '-F' option to force it to move the
2711 existing <branch_tag>.
2713 cvs update -r <tag/rev> (or '-A' for the Main Branch)
2714 cvs tag -F -b <branch_tag>
2716 If the earlier location of TAG1 refers to a physical branch within any
2717 RCS file, moving it will make the existing branch in the file seem to
2718 disappear from CVS's view. This is not a good idea unless you really
2719 want to forget the existence of those RCS branches.
2721 If the "update" above retrieves the original branch point revision
2722 (<X>), the "tag" command above will create the tag:
2726 Where Z is 2 greater than the highest magic branch already on revision
2727 <X>. The TAG1 branch will still have the same branch point (i.e.
2728 revision <X>), but the first commit to the new TAG1 branch will create
2729 a different RCS branch number (<X>.Z instead of <X>.Y).
2731 Renaming a magic <branch_tag> is the act of changing
2737 There is no harm in changing a tag name as long as you forget that
2738 TAG1 ever existed and you clean up any working directories with sticky
2739 TAG1 tags on them by using "update -A", "update -r <other_tag>" or by
2740 removing the working directories.
2742 On the other hand, actually changing the tag is not easy.
2744 See 3M.3 for why the seemingly obvious solution won't work:
2746 cvs tag -b -r <old_branch_tag> <new_branch_tag>
2748 The only direct way to rename a magic tag is to use the "admin"
2749 command on each file: (You might want to use '-n'. Read "man rcs" and
2750 look at the '-n' and '-N' options.)
2752 cvs admin -N<new_branch_tag>:<old_branch_tag> .
2753 cvs tag -d <old_branch_tag>
2755 But you have to be careful because "admin" is different from other CVS
2758 "admin" can be used recursively, but only by specifying directory
2759 names in its argument list (e.g. '.'),
2761 Where "rtag -r <old_branch_tag>" would interpret <old_branch_tag> as
2762 a magic CVS branch tag, "admin" is a direct interface to RCS which
2763 sees a magic branch tag as a simple (though non-existent) RCS revision
2766 This is good for us in this particular case, but different from normal
2769 "admin" also skips the Attic and produces different kinds of errors
2770 than CVS usually does. (Because they are coming directly from RCS.)
2772 The other way to rename a magic <branch_tag> is to edit the Repository
2773 files with a script of some kind. I've done it in the past, but I'll
2774 leave it as an exercise for the reader.
2776 Last modified: _6/13/1997_
2778 6. Can I use RCS locally to record my changes without making them globally
2779 visible by committing them?
2781 You can, but it will probably confuse CVS to have ",v" files in your
2782 working directory. And you will lose all your log entries when you
2785 Your best bet is to create your own CVS branch and work there. You can
2786 commit as many revisions as you want, then merge it back into the main
2787 line (or parent branch) when you are finished.
2789 Last modified: _6/13/1997_
2791 7. How can I allow access to the Repository by both CVS and RCS?
2793 The first step is to try not to. If some people are using CVS, there
2794 is no reason for everyone not to. It is not hard to learn the basics
2795 and CVS makes certain operations *easier* than a series of RCS
2796 commands. Personal preference in what software tools can be applied to
2797 a shared Repository has to take second place to system integration
2798 needs. If you disagree, try writing some Lisp code for inclusion in
2799 your Unix kernel and see what kind of reception you get.
2801 If you really must allow routine RCS access to the CVS Repository, you
2802 can link an RCS sub-directory into a piece of the Repository:
2804 ln -s /Repository/some/directory/I/want RCS
2806 and RCS will work just fine.
2808 Those who are using RCS will have to keep the following in mind:
2810 If a file was originally added to the Repository by "import" and has
2811 not been changed using CVS, the *RCS* default branch will remain
2812 attached to the Vendor branch, causing revisions checked-in by "ci" to
2813 wind up on the Vendor branch, instead of the main branch. Only CVS
2814 moves the RCS default branch on first commit.
2816 The way around this is to checkin (using "ci") all the files first and
2817 move them into the Repository. That way they won't have Vendor
2818 branches. Then RCS will work OK.
2820 It is possible to use "rcs" and "ci" to make the files unusable by
2821 CVS. The same is true of the CVS "admin" command.
2823 Normal RCS practice locks a file on checkout with "co -l". In such
2824 an environment, RCS users should plan to keep survival gear and food
2825 for at least 30 days near their desks. When faced with bizarre and
2826 unexpected permission errors, howling mobs of slavering CVS users will
2827 run the RCS users out of town with pitchforks and machetes.
2829 See 3C.8 for a way to avoid machetes aroused by lock collisions.
2831 Though files checked in by RCS users will correctly cause
2832 "up-to-date" failures during CVS "commits" and they will be
2833 auto-merged into CVS working directories during "update", the opposite
2836 RCS users will get no warning and will not be required to merge older
2837 work into their code. They can easily checkin an old file on top of a
2838 new revision added by CVS, discarding work committed earlier by CVS
2841 See the howling mob scenario described above.
2843 RCS is great. I have used it for years. But I wouldn't mix it this
2844 way. In a two-camp society, you are asking for real trouble, both in
2845 technical hassles to clean up and in political hassles to soothe.
2846 Branch merges will also be a major problem.
2848 Last modified: _6/13/1997_
2850 8. I "updated" a file my friend, "bubba", committed yesterday. Why doesn't
2851 the file now have a modified date of yesterday?
2853 CVS restores dates from the RCS files only on first "checkout". After
2854 that, it is more important to maintain a timestamp relative to the
2855 other files in the working directory.
2857 Example: You committed a source file at 5PM. Bubba updated his copy of
2858 the file, grabbing your changes, then changed and committed a new
2859 revision of the file at 6PM. At 7PM, you compile your file. Then you
2860 execute "update". If CVS sets the date to the one in the RCS file, the
2861 file would be given a timestamp of 6PM and your Makefile wouldn't
2862 rebuild anything that depended on it. Bad news.
2864 Note that the same logic applies to retrieving a revision out of the
2865 Repository to replace a deleted file. If CVS changes your file in an
2866 existing working directory, whether it was because a new revision was
2867 committed by someone else or because you deleted your working file,
2868 the timestamp on the retrieved working file *must* be set to the
2871 When you first retrieve a file, there is no reason to expect any
2872 particular timestamp on the file within your working area. But later,
2873 when dependency checking is performed during a build, it is more
2874 important for the timestamps on the local files to be consistent with
2875 each other than than it is for working files to match the timestamps
2876 on the files in the Repository. See 4D.17 for some more about
2879 Last modified: _6/13/1997_
2881 9. Why do timestamps sometimes get set to the date of the revision,
2882 sometimes not? The inconsistency causes unnecessary recompiles.
2884 The "checkout" command normally sets the timestamp of a working file
2885 to match the timestamp stored on the revision in the Repository's RCS
2888 The "commit" command retains the timestamp of the file, if the act of
2889 checking it in didn't change it (by expanding keywords).
2891 The "update" command sets the time to the revision time the first time
2892 it sees the file. After that, it sets the time of the file to the
2893 current time. See 4D.8 for a reason why.
2895 Here's a two-line PERL program to set timestamps on files based on
2896 other timestamps. I've found this program useful. When you are certain
2897 you don't want a source file to be recompiled, you can set its
2898 timestamp to the stamp on the object file.
2900 #!/usr/local/bin/perl
2902 # Set timestamp of args 2nd-Last to that of the first arg.
2904 ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,$atime,$mtime,$ctime)
2906 utime($atime,$mtime,@ARGV);
2908 Last modified: _6/13/1997_
2910 10. While in the middle of a large "commit", how do I run other commands,
2911 like "diff" or "stat" without seeing lock errors?
2916 The '-n' option to the main cvs command turns off lock checking, a
2917 reasonable act for read-only commands given the promise offered by
2918 '-n' not to alter anything. The "diff", "log" and "stat" commands
2919 provide the same information (for files that are not being committed)
2920 when used with and without the '-n' option.
2922 Warning: Ignoring locks can produce inconsistent information across a
2923 collection of files if you are looking at the revisions affected by an
2924 active commit. Be careful when creating "patches" from the output of
2925 "cvs -n diff". If you are looking only at your working files, tagged
2926 revisions, and BASE revisions (revisions whose numbers are read from
2927 your ./CVS/Entries files), you should get consistent results. Of
2928 course, if you catch a single file in the middle of RCS activity, you
2929 might get some strange errors.
2931 Note that the suggested command is "cvs -n <command>". The visually
2932 similar command "cvs <command> -n" has no relation to the suggested
2933 usage and has an entirely different meaning for each command.
2935 "cvs -n update" also works in the middle of a commit, providing
2936 slightly different information from a plain "cvs update". But, of
2937 course, it also avoids modifying anything.
2939 You could also use the RCS functions, "rlog" and "rcsdiff" to display
2940 some of the information by referring directly to the Repository files.
2942 You need RCS version 5 or later for the commands described above to
2945 Last modified: _6/13/1997_
2947 11. Where did the ./CVS/Entries.Static file come from? What is it for?
2949 Each CVS working directory contains a ./CVS/Entries file listing the
2950 files managed by CVS in that working directory. Normally, if the
2951 "update" command finds a file in the Repository that is not in the
2952 ./CVS/Entries file, "update" copies the appropriate revision of the
2953 "new" file out of the Repository and adds the filename to the Entries
2954 file. This happens for files:
2956 Added to the Repository from another working directory.
2958 Dragged out of the Attic when switching branches with "update -A" or
2961 Whose names were deleted from the ./CVS/Entries file.
2963 If the ./CVS/Entries.Static file exists, CVS will only bring out
2964 revisions of files that are contained in either ./CVS/Entries or
2965 ./CVS/Entries.Static. If a Repository file is found in *neither* file,
2968 The ./CVS/Entries.Static file is created when you check out an
2969 individual file or a module that creates working directories that
2970 don't contain all files in the corresponding Repository directory. In
2971 those cases, without an ./CVS/Entries.Static file, a simple "update"
2972 would bring more files out of the Repository than the original
2975 The ./CVS/Entries.Static file can be removed by hand. It is
2976 automatically removed if you run "update -d" to create new directories
2977 (even if no new directories are created). (Internally, since
2978 "checkout" turns on the '-d' flag and calls the "update" routine, a
2979 "checkout" of a module or directory that writes into an existing
2980 directory will also remove the ./CVS/Entries.Static file.)
2982 Last modified: _6/13/1997_
2984 12. Why did I get the wrong Repository in the loginfo message?
2988 Use multiple Repositories.
2990 Configured CVS to use absolute pathnames in the ./CVS/Repository
2993 Configured CVS not to use the ./CVS/Root file.
2995 Typed the "commit" command in one Repository with your $CVSROOT
2996 pointing at another.
2998 "commit" and all other CVS commands will heed an absolute pathname in
2999 the ./CVS/Repository file (or in the "-d CVSrootdir" override), but
3000 the log function doesn't take arguments -- it just looks at $CVSROOT.
3002 If you avoid even one of the four steps above, you won't see this
3003 problem. If you configure ./CVS/Root, you won't be allowed to execute
3004 the program causing the error.
3006 Last modified: _6/13/1997_
3008 13. How do I run CVS setuid so I can only allow access through the CVS
3011 Setuid to root is not a great idea. Any program that modifies files
3012 and is used by a widely distributed group of users is not a good
3013 candidate for a setuid program. (The worst suggestion I've ever heard
3014 was to make *Emacs* setuid to root.)
3016 Root access on Unix is too powerful. Also, it might not work in some
3017 (secure?) environments.
3019 Running it setuid to some user other than root might work, if you add
3020 this line to main.c near the beginning:
3024 Otherwise it uses *your* access rights, rather than the effective
3027 Also, you have to invent a fake user whose name will show up in
3028 various places. But many sites, especially those who might want a
3029 setuid CVS for "security", want personal accountability -- no generic
3030 accounts. I don't know whether accountability outweighs file security.
3032 And finally, unless you take action to limit the "admin" command, you
3033 are leaving yourself unprotected anyway.
3035 Last modified: _6/13/1997_
3037 14. How about using groups and setgid() then?
3039 Here is a way to run CVS setgid in some environments:
3041 Stick this near the front of the main() in main.c:
3045 This will allow "access" to work on systems where it only works on the
3048 Create a group named "cvsg". (This example uses "cvsg". You can name
3051 Put *no* users in the "cvsg" group. You can put Repository
3052 administrators in this group if you want to.
3054 Set the cvs executable to setgid (not setuid):
3056 cd /usr/local/bin; chown root.cvsg cvs; chmod 2755 cvs
3058 Make sure every file in the Repository is in group "cvsg":
3060 chown -R root.cvsg $CVSROOT
3062 Change all directory permissions to 770. This allows all access to
3063 the files by the "cvsg" group (which has no members!) and no access at
3066 find $CVSROOT -type d -exec chmod 2770 {} \;
3068 On some systems you might have to type:
3070 find $CVSROOT -type d -exec chmod u=rwx,g=rwx,o=,g+s {} \;
3072 This should allow only the cvs program (or other "setgid to group
3073 cvsg") programs to write into the area, but no one else. Yes the user
3074 winds up owning the file, but s/he can't find it again later since
3075 s/he can't traverse the tree. (If you enable the world execute bit
3076 (mode 2771) on directories, users can traverse the tree and the user
3077 who last wrote the file can still write to it.)
3079 If you want to allow read access, check out an entire tree somewhere.
3080 You have to do this anyway to build it.
3082 Note: If you are using a stupid file system that can't inherit file
3083 groups from the parent directory (even with the "setgid" (Octal 2000)
3084 bit set), you might have to modify CVS (or RCS) to reset the group
3085 every time you create a new file. I have not tested this.
3087 The setgid() method shares with the setuid() method the problem of
3088 keeping "admin" from breaking things.
3090 Last modified: _6/13/1997_
3092 15. How do I use the "commitinfo" file?
3096 The "commitinfo" file allows you to execute "sanity check" functions
3097 before allowing a commit. If any function called from within the
3098 commitinfo file exits with a non-zero status, the commit is denied.
3100 To fill out a "commitinfo" file, ask yourself (and those sharing your
3101 Repository) these questions:
3103 - Is there anything you want to check or change before someone is
3104 allowed to commit a file? If not, forget commitinfo.
3106 If you want to serialize binary files, you might consider something
3107 like the rcslock.pl program in the contrib directory of the CVS
3110 - Do you want to execute the same exact thing before committing to
3111 every file in the Repository? (This is useful if you want to program
3112 the restrictions yourself.) If so, set up a single line in the
3115 DEFAULT /absolute/path/to/program
3117 CVS executes the program once for each directory that "commit"
3118 traverses, passing as arguments the directory and the files to be
3119 committed within that directory.
3121 Write your program accordingly. Some examples exist in the contrib
3124 - Do you want a different kind of sanity check performed for different
3125 directories? If so, you'll have to decide what to do for all
3126 directories and enter lines like this:
3128 regexp1 /absolute/path/to/program-for-regexp1
3129 regexp2 /absolute/path/to/program-for-regexp2
3130 DEFAULT /absolute/path/to/program-for-all-else
3132 - Is there anything you want to happen before *all* commits, in
3133 addition to other pattern matches? If so, include a line like this:
3135 ALL /absolute/path/to/program
3137 It is executed independently of all the above. And it's repeatable --
3138 you can have as many ALL lines as you like.
3140 Last modified: _6/13/1997_
3142 16. How do I use the "loginfo" files?
3144 See 4B.2 and the "commitinfo" question above.
3146 The "loginfo" file has the same format as the "commitinfo" file, but
3147 its function is different. Where the "commitinfo" information is used
3148 before a commit, the "loginfo" file is used after a commit.
3150 All the commands in the "loginfo" file should read data from standard
3151 input, then either append it to a file or send a message to a mailing
3152 list. If you want to make it simple, you can put shell (the shell used
3153 by "popen(3)") command lines directly in the "loginfo" (or
3154 "commitinfo") file. These seem to work:
3156 ^special /usr/ucb/Mail -s %s special-mailing-list ^other /usr/ucb/Mail
3157 -s %s other-mailing-list DEFAULT (echo '===='; echo %s; cat) >
3158 /path/name/to/log/file
3160 Last modified: _6/13/1997_
3162 17. How can I keep people with restrictive umask values from blocking
3163 access to the Repository?
3165 If a user creates a new file with restricted permissions (e.g. 0600),
3166 and commits it, the Repository will have a file in it that is
3167 unreadable by everyone. The 0600 example would be unreadable by
3168 *anyone* but root and the user who created it.
3170 There are 3 solutions to this:
3172 Let it happen. This is a valid way to protect things. If everyone is
3173 working alone, a umask of 077 is OK. If everyone is working only in
3174 small groups, a umask of 007 is OK.
3176 Train your users not to create such things if you expect to share
3179 See 4B.5 for a small script that will reset the umask.
3181 I personally don't like the idea of a program automatically
3182 *loosening* security. It would be better for you all to talk about the
3183 issue and decide how to work together.
3185 Last modified: _6/13/1997_
3187 Category: /Commands_/
3191 Category: /Commands_/add_ad_new/
3193 " + "add", "ad", "new""
3195 1. What is "add" for?
3197 To add a new directory to the Repository or to register the desire to
3198 add a new file to the Repository.
3200 The directory is created immediately, while the desire to add the file
3201 is recorded in the local ./CVS administrative directory. To really add
3202 the file to the Repository, you must then "commit" it.
3204 Last modified: _6/13/1997_
3206 2. How do I add a new file to the branch I'm working on?
3208 The user actions for adding a file to any branch, including the Main
3209 Branch, are exactly the same.
3211 You are in a directory checked out (or updated) with the '-A' option
3212 (to place you on the Main Branch) or the "-r <branch_tag>" option (to
3213 place you on a branch tagged with <branch_tag>). To add <file> to the
3214 branch you are on, you type:
3219 If no ./CVS/Tag file exists (the '-A' option deletes it), the file
3220 will be added to the Main Branch. If a ./CVS/Tag file exists (the "-r
3221 <branch_tag>" option creates it), the file will be added to the branch
3222 named (i.e. tagged with) <branch_tag>.
3224 Unless you took steps to first add the file to the Main Branch, your
3225 new file ends up in the Attic.
3227 Last modified: _6/13/1997_
3229 3. Why did my new file end up in the Attic?
3231 The file is thrown into the Attic to keep it from being visible when
3232 you check out the Main Branch, since it was never committed to the
3235 Last modified: _6/13/1997_
3237 4. Now that it's in the Attic, how do I connect it to the Main branch?
3239 That can be considered a kind of "merge". See 4C.8
3241 Last modified: _6/13/1997_
3243 5. How do I avoid the hassle of reconnecting an Attic-only file to the Main
3246 You create it on the Main Branch first, then branch it.
3248 If you haven't yet added the file or if you decided to delete the new
3249 Attic file and start over, then do the following: (If you added the
3250 file (or worse, the 157 files) to the Attic and don't want to start
3251 over, try the procedure in 4C.8.)
3253 Temporarily remove the sticky branch information. Either:
3255 Move the whole directory back to the Main Branch. [This might not be
3256 a good idea if you have modified files, since it will require a merge
3263 Move the ./CVS/Tag file out of the way.
3265 mv ./CVS/Tag HOLD_Tag
3267 Add and branch the file "normally":
3271 cvs tag -b <branch_tag> <file>
3273 [<branch_tag> is the same Branch Tag as you used on all the other
3274 files. Look at ./CVS/Entries or the output from "cvs stat" for sticky
3277 Clean up the temporary step.
3279 If you moved the ./CVS/Tag file, put it back. Then move the new file
3280 onto the branch where you are working.
3282 mv HOLD_Tag ./CVS/Tag
3283 cvs update -r <branch_tag> <file>
3285 If you ran "update -A" rather than moving the ./CVS/Tag file, move
3286 the whole directory (including the new file) back onto the branch
3287 where you were working:
3289 cvs update -r <branch_tag>
3291 Last modified: _6/13/1997_
3293 6. How do I cancel an "add"?
3295 If you want to remove the file entirely and cancel the "add" at the
3298 cvs remove -f <file>
3300 If you want to cancel the "add", but leave the file as it was before
3301 you typed "cvs add", then you have to fake it:
3303 mv <file> <file>.hold
3305 mv <file>.hold <file>
3307 Last modified: _6/13/1997_
3309 7. What are the ./CVS/file,p and ./CVS/file,t files for?
3311 The ./CVS/file,p and ./CVS/file,t files are created by the "add"
3312 command to hold command line options and message text between the time
3313 of the "add" command and the expected "commit".
3315 The ./CVS/file,p file is always null, since its function was absorbed
3316 by the "options" field in the ./CVS/Entries file. If you put something
3317 in this file it will be used as arguments to the RCS "ci" command that
3318 commit uses to check the file in, but CVS itself doesn't put anything
3321 The ./CVS/file,t file is null unless you specify an initial message in
3322 an "add -m 'message'" command. The text is handed to "rcs -i
3323 -t./CVS/file,t" to create the initial RCS file container.
3325 Both files must exist to commit a newly added file. If the
3326 ./CVS/file,p file doesn't exist, CVS prints an error and aborts the
3327 commit. If the ./CVS/file,t file doesn't exist, RCS prints an error
3328 and CVS gets confused, but does no harm.
3330 To recover from missing ,p and ,t files, just create two zero-length
3331 files and rerun the "commit".
3333 Last modified: _6/13/1997_
3335 8. How do I "add" a binary file?
3337 If you configured CVS to use the GNU version of "diff" and "diff3",
3338 you only need to turn off RCS keyword expansion.
3340 First you turn off RCS keyword expansion for the initial checkin by
3341 using "add -ko". It works like "update -ko" in creating a "sticky"
3342 option only for the copy of the file in the current working directory.
3346 Commit the file normally. The sticky -ko option will be used.
3350 Then mark the RCS file in the Repository so that keyword expansion is
3351 turned off for all checked out versions of the file.
3353 cvs admin -ko <file>
3355 Since "admin -ko" records the keyword substitution value in the
3356 Repository's RCS file, you no longer need the sticky option. You can
3357 turn it off with the "update -A" command, but if you were on a branch,
3358 you'll have to follow it "update -r <branch_tag>" to put yourself back
3361 Managing that binary file is another problem. See 4D.1.
3363 Last modified: _6/13/1997_
3365 Category: /Commands_/admin_adm_rcs/
3367 " + "admin", "adm", "rcs""
3369 1. What is "admin" for?
3371 To provide direct access to the underlying "rcs" command (which is not
3372 documented in this FAQ) bypassing all safeguards and CVS assumptions.
3374 Last modified: _6/13/1997_
3376 2. Wow! Isn't that dangerous?
3380 Though you can't hurt the internal structure of an RCS file using its
3381 own "rcs" command, you *can* change the underlying RCS files using
3382 "admin" in ways that CVS can't handle.
3384 If you feel the need to use "admin", create some test files with the
3385 RCS "ci" command and experiment on them with "rcs" before blasting any
3388 Last modified: _6/13/1997_
3390 3. What would I normally use "admin" for?
3392 Normally, you wouldn't use admin at all. In unusual circumstances,
3393 experts can use it to set up or restore the internal RCS state that
3396 You can use "admin -o" (for "outdate") to remove revisions you don't
3397 care about. This has its own problems, such as leaving dangling Tags
3398 and confusing the "update" command.
3400 There is some feeling among manipulators of binary files that "admin
3401 -l" should be used to serialize access. See 3C.8.
3403 An interesting use for "admin" came up while maintaining CVS itself. I
3404 import versions of CVS onto the Vendor branch of my copy of CVS, make
3405 changes to some files and ship the diffs (created by "cvs diff -c -r
3406 TO_BRIAN") off to Brian Berliner. After creating the diff, I retag
3407 ("cvs tag -F TO_BRIAN") the working directory, which is then ready to
3408 produce the next patch.
3410 I'll use "add.c" as an example (only because the name is short).
3412 When the next release came out, I discovered that the released "add.c"
3413 (version 1.1.1.3 on the Vendor branch) was exactly the same as my
3414 modified file (version 1.3). I didn't care about the changelog on
3415 versions 1.2 and 1.3 (or the evidence of having done the work), so I
3416 decided to revert the file to the state where it looked like I had not
3417 touched the file -- where I was just using the latest on the vendor
3418 branch after a sequence of imports.
3420 To do that, I removed all the revisions on the main branch, except for
3421 the original 1.1 from which the Vendor branch sprouts:
3423 cvs admin -o1.2: add.c
3425 Then I set the RCS "default branch" back to the Vendor branch, the way
3426 import would have created it:
3428 cvs admin -b1.1.1 add.c
3430 And I moved the "TO_BRIAN" Tag to the latest revision on the Vendor
3431 branch, since that is the base from which further patches would be
3432 created (if I made any):
3434 cvs admin -NTO_BRIAN:1.1.1.3 add.c
3436 Instead of 1.1.1.3, I could have used one of the "Release Tags" last
3437 applied by "import" (3rd through Nth arguments).
3439 Suggestion: Practice on non-essential files.
3441 Last modified: _6/13/1997_
3443 4. What should I avoid when using "admin"?
3445 If you know exactly what you are doing, hack away. But under normal
3448 Never use "admin" to alter branches (using the '-b' option), which CVS
3449 takes very seriously. If you change the default branch, CVS will not
3450 work as expected. If you create new branches without using the "tag
3451 -b" command, you may not be able to treat them as CVS branches.
3453 See 3C.8 for a short discussion of how to use "admin -l" for
3454 serializing access to binary files.
3456 The "admin -o <file>" allows you to delete revisions, usually a bad
3457 idea. You should commit a correction rather than back out a revision.
3458 Outdating a revision is prone to all sorts of problems:
3460 Discarding data is always a bad idea. Unless something in the
3461 revision you just committed is a threat to your job or your life,
3462 (like naming a function "<boss's name>_is_a_dweeb", or including the
3463 combination to the local Mafioso's safe in a C comment), just leave it
3464 there. No one cares about simple mistakes -- just commit a corrected
3467 The time travel paradoxes you can cause by changing history are not
3468 worth the trouble. Even if CVS can't interfere with your parents'
3469 introduction, it *can* log commits in at least two ways (history and
3470 loginfo). The reports now lie -- the revision referred to in the logs
3473 If you used "import" to place <file> into CVS, outdating all the
3474 revisions on the Main branch back to and including revision 1.2 (or
3475 worse, 1.1), will produce an invalid CVS file.
3477 If the <file>,v file only contains revision 1.1 (and the connected
3478 branch revision 1.1.1.1), then the default branch must be set to the
3479 Vendor branch as it was when you first imported the file. Outdating
3480 back through 1.2 doesn't restore the branch setting. Despite the above
3481 admonition against it, "admin -b" is the only way to recover:
3483 cvs admin -b1.1.1 <file>
3485 Although you can't outdate a physical (RCS) branch point without
3486 removing the whole branch, you *can* outdate a revision referred to by
3487 a magic branch tag. If you do so, you will invalidate the branch.
3489 If you "outdate" a tagged revision, you will invalidate all uses of
3490 the <tag>, not just the one on <file>. A tag is supposed to be
3491 attached to a consistent set of files, usually a set built as a unit.
3492 By discarding one of the files in the set, you have destroyed the
3493 utility of the <tag>. And it leaves a dangling tag, which points to
3496 And even worse, if you commit a revision already tagged, you will
3497 alter what the <tag> pointed to without using the "tag" command. For
3498 example, if revision 1.3 has <tag> attached to it and you "outdate"
3499 the 1.3 revision, <tag> will point to a nonexistent revision. Although
3500 this is annoying, it is nowhere near as much trouble as the problem
3501 that will occur when you commit to this file again, recreating
3502 revision 1.3. The old tag will point to the new revision, a file that
3503 was not in existence when the <tag> was applied. And the discrepancy
3504 is nearly undetectable.
3506 If you don't understand the above, you should not use the admin
3509 Last modified: _6/13/1997_
3511 5. How do I restrict the "admin" command? The -i flag in the modules file
3512 can restrict commits. What's the equivalent for "admin"?
3514 At this writing, to disable the "admin" command, you will have to
3515 change the program source code, recompile and reinstall.
3517 Last modified: _6/13/1997_
3519 6. I backed out a revision with "admin -o" and committed a replacement. Why
3520 doesn't "update" retrieve the new revision?
3522 CVS is confused because the revision in the ./CVS/Entries file matches
3523 the latest revision in the Repository *and* the timestamp in the
3524 ./CVS/Entries file matches your working file. CVS believes that your
3525 file is "up-to-date" and doesn't need to be updated.
3527 You can cause CVS to notice the change by "touch"ing the file.
3528 Unfortunately what CVS will tell you is that you have a "Modified"
3529 file. If you then "commit" the file, you will bypass the normal CVS
3530 check for "up-to-date" and will probably commit the revision that was
3531 originally removed by "admin -o".
3533 Changing a file without changing the revision number confuses CVS no
3534 matter whether you did it by replacing the revision (using "admin -o"
3535 and "commit" or raw RCS commands) or by applying an editor directly to
3536 a Repository (",v") file. Don't do it unless you are absolutely
3537 certain no one has the latest revision of the file checked out.
3539 The best solution to this is to institute a program of deterrent
3540 flogging of abusers of "admin -o".
3542 The "admin" command has other problems." See 3B.4 above.
3544 Last modified: _6/13/1997_
3546 Category: /Commands_/checkout_co_get/
3548 " + "checkout", "co", "get""
3550 1. What is "checkout" for?
3552 To acquire a copy of a module (or set of files) to work on.
3554 All work on files controlled by CVS starts with a "checkout".
3556 Last modified: _6/13/1997_
3558 2. What is the "module" that "checkout" takes on the command line?
3560 It is a name for a directory or a collection of files in the
3561 Repository. It provides a compact name space and the ability to
3562 execute before and after helper functions based on definitions in the
3567 Last modified: _6/13/1997_
3569 3. Isn't a CVS "checkout" just a bunch of RCS checkouts?
3571 Like much of CVS, a similar RCS concept is used to support a CVS
3572 function. But a CVS checkout is *not* the same as an RCS checkout.
3574 Differences include:
3576 CVS does not lock the files. Others may access them at the same
3579 CVS works best when you provide a name for a collection of files (a
3580 module or a directory) rather than an explicit list of files to work
3583 CVS remembers what revisions you checked out and what branch you are
3584 on, simplifying later commands.
3586 Last modified: _6/13/1997_
3588 4. What's the difference between "update" and "checkout"?
3590 The "checkout" and "update" commands are nearly equivalent in how they
3591 treat individual files. They differ in the following ways:
3593 The "checkout" command always creates a directory, moves into it,
3594 then becomes equivalent to "update -d".
3596 The "update" command does not create directories unless you add the
3599 "Update" is intended to be executed within a working directory
3600 created by "checkout". It doesn't take a module or directory argument,
3601 but figures out what Repository files to look at by reading the files
3602 in the ./CVS administrative directory.
3604 The two commands generate completely different types of records in
3607 Last modified: _6/13/1997_
3609 5. Why can't I check out a file from within my working directory?
3611 Though you *can* check out a file, you normally check out a module or
3612 directory. And you normally do it only once at the beginning of a
3615 After the initial "checkout", you can use the "update" command to
3616 retrieve any file you want within the checked-out directory. There is
3617 no need for further "checkout" commands.
3619 If you want to retrieve another module or directory to work on, you
3620 must provide two pathnames: where to find it in the Repository and
3621 where to put it on disk. The "modules" file and your current directory
3622 supply two pieces of naming information. While inside a checked-out
3623 working directory, the CVS administrative information provides most of
3626 You should be careful not to confuse CVS with RCS and use "checkout"
3627 in the RCS sense. An RCS "checkout" (which is performed by the RCS
3628 "co" command) is closer to a "cvs update" than to a "cvs checkout".
3630 Last modified: _6/13/1997_
3632 6. How do I avoid dealing with those long relative pathnames?
3634 This question has also been phrased:
3636 How do I avoid all those layers of directories on checkout? or Why do
3637 I have to go to the top of my working directory and checkout some long
3638 pathname to get a file or two?
3640 This type of question occurs only among groups of people who decide
3641 not to use "modules". The answer is to use "modules".
3643 When you hand the "checkout" command a relative pathname rather than a
3644 module name, all directories in the path are created, maintaining the
3645 same directory hierarchy as in the Repository. The same kind of
3646 environment results if you specify a "module" that is really an alias
3647 expanding into a list of relative pathnames rather than a list of
3650 If you use "module" names, "checkout" creates a single directory by
3651 the name of the module in your current directory. This "module"
3652 directory becomes your working directory.
3654 The "module" concept combines the ability to "name" a collection of
3655 files with the ability to structure the Repository so that consistent
3656 sets of files are checked out together. It is the responsibility of
3657 the Repository Administrators to set up a modules file that describes
3658 the software within the Repository.
3660 Last modified: _6/13/1997_
3662 7. Can I move a checked-out directory? Does CVS remember where it was
3667 The ./CVS/Repository file in each working directory contains a
3668 pathname pointing to the matching directory within the Repository. The
3669 pathname is either absolute or relative to $CVSROOT, depending on how
3672 When you move a checked-out directory, the CVS administrative files
3673 will move along with it. As long as you don't move the Repository
3674 itself, or alter your $CVSROOT variable, the moved directory will
3675 continue to be usable.
3677 CVS remembers where you checked out the directory in the "history"
3678 file, which can be edited, or even ignored if you don't use the
3679 "working directory" information displayed by the "history" command.
3681 Last modified: _6/13/1997_
3683 8. How can I lock files while I'm working on them the way RCS does?
3685 Until the day arrives of the all-powerful merge tool, there are still
3686 files that must be accessed serially. For those instances, here's a
3689 Install a pre-commit program in the "commitinfo" file to check for
3690 RCS locks. The program "rcslock.pl" performs this function. It can be
3691 found in the contrib directory of the CVS source distribution.
3693 When you want to make a change to a file you know can't be merged,
3694 first use "cvs admin -l" to lock the file. If you can't acquire the
3695 lock, use the standard "locked out" protocol: go talk to the person
3698 Make sure the pre-commit program prints a message and exits with a
3699 non-zero status if someone besides the user running "commit" has the
3700 file locked. This non-zero exist status will cause the "commit" to
3703 Make sure the pre-commit program exits with a zero status if the
3704 file is either unlocked or locked by the user running "commit". The
3705 "cvs commit" command that kicked off the pre-commit program will take
3706 a zero exist status as an OK and checkin the file, which has the
3707 side-effect of unlocking it.
3709 ===> The following is opinion and context. Don't read it if you are
3710 looking for a quick fix.
3712 The topic of locking CVS files resurfaces on the network every so
3713 often, producing the same results each time:
3717 CVS was designed to avoid locks, using a copy-modify-merge model.
3718 Locking is not necessary and you should take the time to learn the CVS
3719 model which many people find workable. So why not get with the program
3720 and learn how to think the CVS way?
3724 The users determine how a tool is to be used, not the designers. We,
3725 the users, have always used locking, our bosses demand locking,
3726 locking is good, locking is God. I don't want to hear any more
3727 lectures on the CVS model. Make locking work.
3729 Any organization making active changes to a source base will
3730 eventually face the need to do parallel development. Parallel
3731 development implies merges. (If you plan to keep separate copies of
3732 everything and never merge, good luck. Tell me who you work for so I
3733 can buy stock in your disk suppliers this year and sell your stock
3736 Merges will never go away. CVS chose to make "merges" stand front and
3737 center as an important, common occurrence in development. It is one
3738 way of looking at things.
3740 For free-format text, the merge paradigm gives you a considerable
3741 amount of freedom. It does take a bit of management, but any project
3742 should be ready to deal with it.
3744 On the other hand, there are many files that can't be merged using
3745 text merge techniques. Straight text merge programs like "diff3" are
3746 guaranteed to fail on executables (with relative branch statements),
3747 files with self-referential counts stored in the file (such as TAGS
3748 files), or files with relative motion statements in them (such as
3749 Frame MIF files, many postscript files). They aren't all binary files.
3751 For these types of files, and many others, there are only two
3754 Complex merge tools that are intimately aware of the contents of the
3755 files to be merged. (ClearCase, and probably others, allow you to
3756 define your own "files types" with associated "merge tools".)
3758 Serialization of access to the file. The only technical solution to
3759 the problem of serialization is "locking".
3761 Since you can call a program that offers:
3763 "Which one do you want? A/B?"
3765 a "merge tool", more and more merge tools will appear which can be
3766 hooked into a merge-intensive program like CVS. Think of a bitmap
3767 "merge" tool that displays the bitmaps on the screen and offers a
3768 "paint" interface to allow you to cut and paste, overlay, invert or
3769 fuse the two images such that the result is a "merged" file.
3771 My conclusion is that the need for locking is temporary, awaiting
3772 better technology. For large development groups, locking is not an
3773 alternative to merging for text files.
3775 Last modified: _6/13/1997_
3777 9. What is "checkout -s"? How is it different from "checkout -c"?
3779 The '-c' and '-s' options to "checkout" both cause the modules file to
3780 appear on standard output, but formatted differently.
3782 "checkout -c" lists the modules file alphabetized by the module name.
3783 It also prints all data (including options like '-a' and "-o <prog>")
3784 specified in the modules file.
3786 "checkout -s" lists the modules file sorted by "status" field, then by
3787 module name. The status field was intended to allow you to mark
3788 modules with strings of your choice to get a quick sorted report based
3789 on the data you chose to put in the status fields. I have used it for
3790 priority ("Showstopper", etc as tied into a bug database), for porting
3791 status ("Ported", "Compiled", etc. when porting a large collection of
3792 modules), for "assignee" (the person responsible for maintenance), and
3793 for "test suite" (which automatic test procedure to run for a
3796 Last modified: _6/13/1997_
3798 Category: /Commands_/commit_ci_com/
3800 " + "commit", "ci", "com""
3802 1. What is "commit" for?
3804 To store new revisions in the Repository, making them visible to other
3807 Last modified: _6/13/1997_
3809 2. If I edit ten files, do I have to type "commit" ten times?
3811 No. The "commit" command will take multiple filenames, directory names
3812 and relative pathnames on the command line and commit them all with
3813 the same log message. If a file is unchanged, even if it is explicitly
3814 listed on the command line, CVS will skip it.
3816 Like all CVS commands, "commit" will work on the whole directory by
3817 default. Just type "cvs commit" to tell CVS to commit all modified
3818 files (i.e. the files that "update" would display preceded by 'M') in
3819 the current directory and in all sub-directories.
3821 Last modified: _6/13/1997_
3823 3. Explain: cvs commit: Up-to-date check failed for `<file>'
3825 You may not "commit" a file if your BASE revision (i.e. the revision
3826 you last checked out, committed or retrieved via "update") doesn't
3827 match the HEAD revision (i.e the latest revision on your branch,
3828 usually the Main Branch).
3830 In other words, someone committed a revision since you last executed
3831 "checkout", "update" or "commit". You must now execute "update" to
3832 merge the other person's changes into your working file before
3833 "commit" will work. You are thus protected (somewhat) from a common
3834 form of race condition in source control systems, where a checkin of a
3835 minor alteration of a second copy of the same base file obliterates
3836 the changes made in the first.
3838 Normally, the "update" command's auto-merge should be followed by
3839 another round of building and testing before the "commit".
3841 Last modified: _6/13/1997_
3843 4. What happens if two people try to "commit" conflicting changes?
3845 Conflicts can occur only when two developers check out the same
3846 revision of the same file and make changes. The first developer to
3847 commit the file has no chance of seeing the conflict. Only the second
3848 developer runs into it, usually when faced with the "Up-to-date" error
3849 explained in the previous question.
3851 There are two types of conflicts:
3853 When two developers make changes to the same section of code, the
3854 auto-merge caused by "update" will print a 'C' on your terminal and
3855 leave "overlap" markers in the file.
3857 You are expected to examine and clean them up before committing the
3858 file. (That may be obvious to *some* of you, but . . .)
3860 A more difficult problem arises when two developers change different
3861 sections of code, but make calls to, or somehow depend on, the old
3862 version of each other's code.
3864 The auto-merge does the "right" thing, if you view the file as a
3865 series of text lines. But as a program, the two developers have
3866 created a problem for themselves.
3868 This is no different from making cross-referential changes in
3869 *separate* files. CVS can't help you. In a perfect world, you would
3870 each refer to the specification and resolve it independently. In the
3871 real world you have to talk/argue, read code, test and debug until the
3872 combined changes work again.
3874 Welcome to the world of parallel development.
3876 Last modified: _6/13/1997_
3878 5. I committed something and I don't like it. How do I remove it?
3880 Though you *can* use the "admin -o" (synonym: "rcs -o") command to
3881 delete revisions, unless the file you committed is so embarrassing
3882 that the need to eradicate it overrides the need to be careful, you
3883 should just grab an old version of the file ("update -p -r
3884 <previous-rev>" might help here) and commit it on top of the offending
3887 See Section 3B on "admin".
3889 Last modified: _6/13/1997_
3891 6. Explain: cvs commit: sticky tag `V3' for file `X' is not a branch
3893 The message implies two things:
3895 You created your working directory by using "checkout -r V3", or you
3896 recently executed "update -r V3".
3898 The tag named V3 is not a branch tag.
3900 CVS records (i.e. makes "sticky") any "-r <tag/rev>" argument handed
3901 to the "checkout" or "update" commands. The <tag/rev> is recorded as
3902 the CVS working branch, which is the branch to which "commit" will add
3905 Branch tags are created when you use the -b switch on the "tag" or
3906 "rtag" commands. Branch tags are magic tags that don't create a
3907 physical branch, but merely mark the revision to branch from when the
3908 branch is needed. The first commit to a magic branch creates a
3909 physical branch in the RCS files.
3911 You can commit onto the end of the Main Trunk, if you have no sticky
3912 tag at all, or onto the end of a branch, if you have a sticky branch
3913 tag. But you can't commit a file that has a sticky tag not pointing to
3914 a branch. CVS assumes a sticky Tag or Revision that does not refer to
3915 a branch is attached to the middle of a series of revisions. You can't
3916 squeeze a new revision between two others. Sticky dates also block
3917 commits since they never refer to a branch.
3921 If you don't want a branch and were just looking at an old revision,
3922 then you can move back to the Main Branch by typing:
3924 cvs update -A {files or dirs, default is '.'}
3926 or you can move to the branch named <branch_tag> by:
3928 cvs update -r <branch_tag> {files or dirs, default is '.'}
3932 If you really wanted to be on a branch and made an earlier mistake by
3933 tagging your branch point with a non-branch tag, you can recover by
3934 adding a new branch tag to the old non-branch tag:
3936 cvs rtag -b -r <oldtag> <newtag> <module>
3938 (It was not a big mistake. Branch-point tags can be useful. But the
3939 <newtag> must have a different name.)
3941 If you don't know the <module> name or don't use "modules", you can
3942 also use "tag" this way:
3944 cvs update -r <oldtag>
3945 cvs tag -b <newtag> .
3947 Then, to put your working directory onto the branch, you type:
3949 cvs update -r <newtag>
3951 You can't delete <oldtag> before adding <newtag>, and I would not
3952 advise deleting the <oldtag> at all, because it is useful in referring
3953 to the branch point. If you must, you can delete the non-branch tag
3956 cvs rtag -d <oldtag> <module>
3958 cvs tag -d <oldtag> .
3962 If you made the same mistake as in Scenario2 (of placing a non-branch
3963 tag where you wanted a branch tag), but really want <oldtag> to be the
3964 name of your branch, you can execute a slightly different series of
3965 commands to rename it and move your working directory onto the branch.
3967 Warning: This is not a way to rename a branch tag. It is a way to turn
3968 a non-branch tag into a branch tag with the same name.
3970 cvs rtag -r <oldtag> <branch_point_tag> <module>
3971 cvs rtag -d <oldtag> <module>
3972 cvs rtag -b -r <branch_point_tag> <oldtag> <module>
3974 Then, if you really must, delete the <branch_point_tag>:
3976 cvs rtag -d <branch_point_tag> <module>
3978 Note: The unwieldy mixture of "tag" and "rtag" is mostly because you
3979 can't specify a revision (-r <tag>) to the "tag" command.
3981 See 4C.3 for more info on creating a branch.
3983 Last modified: _6/13/1997_
3985 7. Why does "commit -r <tag/rev>" put newly added files in the Attic?
3987 If you specify "-r <rev>" (where <rev> is a dotted numeric number like
3988 2.4), it correctly sets the initial revision to <rev>, but it also
3989 attaches the numeric <rev> as a sticky tag and throws the file into
3990 the Attic. This is a bug. The obvious solution is to move the file out
3991 of the Attic into the associated Repository directory and "update -A"
3992 the file. There are no Tags to clean up.
3994 If you specify "-r <tag>" to commit a newly added file, the <tag> is
3995 treated like a <branch_tag>, which becomes a symbolic RCS label
3996 pointing to the string '1', which can be considered to be the "Main
3997 branch number" when the main branch is still at revision 1.N. The file
3998 is also thrown into the Attic. See 4C.8 for a way to recover from
4001 In fact, a plain "commit" without the "-r" will throw a newly added
4002 file into the Attic if you added it to a directory checked out on a
4003 branch. See 3A.[2-5].
4005 See Section 4C, on Branching, for many more details.
4007 Last modified: _6/13/1997_
4009 8. Why would a "commit" of a newly added file not produce rev 1.1?
4011 When committing a newly added file CVS looks for the highest main
4012 branch major number in all files in the ./CVS/Entries file. Normally
4013 it is '1', but if you have a file of revision 3.27 in your directory,
4014 CVS will find the '3' and create revision 3.1 for the first rev of
4015 <file>. Normally, the first revision is 1.1.
4017 Last modified: _6/13/1997_
4019 Category: /Commands_/diff_di_dif/
4021 " + "diff", "di", "dif""
4023 1. What is "diff" for?
4025 To display the difference between a working file and its BASE
4026 revision (the revision last checked out, updated or committed):
4030 To display the difference between a working file and a committed
4031 revision of the same file:
4033 cvs diff -r <tag/rev> <file>
4035 To display the difference between two committed revisions of the
4038 cvs diff -r <tag1/rev1> -r <tag2/rev2> <file>
4040 You can specify any number of <file> arguments. Without any <file>
4041 arguments, it compares the whole directory.
4043 In the examples above, "-D <date>" may be substituted wherever "-r
4044 <tag/rev>" appears. The revision a <date> refers to is the revision
4045 that existed on that date.
4047 Last modified: _6/13/1997_
4049 2. Why did "diff" display nothing when I know there are later committed
4050 revisions in the Repository?
4052 By default, "diff" displays the difference between your working file
4053 and the BASE revision. If you haven't made any changes to the file
4054 since your last "checkout", "update" or "commit" there is no
4055 difference to display.
4057 To display the difference between your working file and the latest
4058 revision committed to your current branch, type:
4060 cvs diff -r HEAD <file>
4062 Last modified: _6/13/1997_
4064 3. How do I display what changed in the Repository since I last executed
4065 "checkout", "update" or "commit"?
4067 A special tag (interpreted by CVS -- it does not appear in the Tag
4068 list) named "BASE" always refers to the revision you last checked out,
4069 updated or committed. Another special tag named "HEAD" always refers
4070 to the latest revision on your working branch.
4072 To compare BASE and HEAD, you type:
4074 cvs diff -r BASE -r HEAD <file>
4076 Last modified: _6/13/1997_
4078 4. How do I display the difference between my working file and what I
4079 checked in last Thursday?
4081 cvs diff -D "last Thursday" <file>
4083 where "last Thursday" is a date string. To be more precise, the
4084 argument to the '-D' option is a timestamp. Many formats are accepted.
4085 See the man page under "-D date_spec" for details.
4087 Last modified: _6/13/1997_
4089 5. Why can't I pass long options, like --unified, to "diff"?
4091 CVS only handles single character '-X' arguments, not the FSF long
4092 options. CVS also passes through only arguments it knows about,
4093 because a few arguments are captured and interpreted by CVS.
4095 If you didn't configure RCS and CVS to use the GNU version of diff,
4096 long options wouldn't work even if future versions of CVS acquire the
4097 ability to pass them through.
4099 Most of the long options have equivalent single-character options,
4100 which do work. The "--unified" option is equivalent to '-u' in
4101 revisions of GNU diff since 1.15.
4103 Last modified: _6/13/1997_
4105 Category: /Commands_/export_exp_ex/
4107 " + "export", "exp", "ex""
4109 1. What is "export" for?
4111 "export" checks out a copy of a module in a form intended for export
4112 outside the CVS environment. The "export" command produces the same
4113 directory and file structure as the "checkout" command, but it doesn't
4114 create "CVS" sub-directories and it removes all the RCS keywords from
4117 Last modified: _6/13/1997_
4119 2. Why does it remove the RCS keywords so I can't use the "ident" command
4120 on the source files?
4122 It removes the RCS keywords, so that if the recipient of the exported
4123 sources checks them into another set of RCS files (with or without
4124 CVS), and then makes modifications through RCS or CVS commands, the
4125 revision numbers that they had when you exported them will be
4126 preserved. (That ident no longer works is just an unfortunate side
4129 The theory is that you are exporting the sources to someone else who
4130 will make independent changes, and at some point you or they will want
4131 to know what revisions from your Repository they started with
4132 (probably to merge changes, or to try to decide whether to merge
4135 A better way to handle this situation would be to give them their own
4136 branch of your Repository. They would need to remember to checkin the
4137 exported sources with RCS IDs intact (ci -k) so that their changes
4138 would get revision numbers from the branch, rather than starting at
4139 1.1 again. Perhaps a future version of CVS will provide a way to
4140 export sources this way.
4142 Contributed by Dan Franklin
4144 Last modified: _6/13/1997_
4146 3. Can I override the '-kv' flag CVS passes to RCS?
4148 Not as of CVS version 1.4.
4150 Last modified: _6/13/1997_
4152 4. Why doesn't "export" have a '-k' flag like "import" does?
4154 Export is intended for a specific purpose -- to remove all trace of
4155 revision control on the way *out* of CVS.
4157 Last modified: _6/13/1997_
4159 5. Why does "export -D" check out every file in the Attic?
4161 See 5B.3 for an explanation of the same problem with "update".
4163 Last modified: _6/13/1997_
4165 Category: /Commands_/history_hi_his/
4167 " + "history", "hi", "his""
4169 1. What is "history" for?
4171 To provide information difficult or impossible to extract out of the
4172 RCS files, such as a "tag" history or a summary of module activities.
4174 Last modified: _6/13/1997_
4176 2. Of what use is it?
4178 I have found it useful in a number of ways, including:
4180 Providing a list of files changed since
4183 - Yesterday, last Thursday, or a specific date.
4184 - Someone changed a specific file.
4186 Providing a list of special events:
4188 - Files added or removed since one of the above events.
4189 - Merge failures since one of the above events. (Where did the
4191 - Has anyone (and who) grabbed the revision of this file I committed
4192 last week, or are they still working blind?
4194 Telling me how often a file/directory/module has been changed.
4196 Dumping a summary of work done on a particular module, including who
4197 last worked on it and what changed.
4199 Displaying the checked-out modules and where they are being worked
4202 To tell me what users "joe" and "malcolm" have done this week.
4204 Last modified: _6/13/1997_
4206 3. What is this, Big Brother?
4210 Ignorance is Strength.
4212 Normally manager types and those with the power to play Big Brother
4213 don't care about this information. The Software Engineer responsible
4214 for integration usually wants to know who is working on what and what
4215 changed. Use your imagination.
4217 Last modified: _6/13/1997_
4219 4. I deleted my working directory and "history" still says I have it
4220 checked out. How do I fix it?
4222 You can use "release -f" to forcibly add a "release" record to the
4223 history file for a working directory associated with a "module". If
4224 your version of "release" doesn't have the '-f' option, or you checked
4225 out the directory using a relative path, you have to edit the
4226 $CVSROOT/CVSROOT/history file.
4228 You can remove the last 'O' line in the history file referring to the
4229 module in question or add an 'F' record.
4231 Last modified: _6/13/1997_
4233 5. So I *can* edit the History file?
4235 Yes, but if you are using history at all, you should take a little
4236 care not to lose information. I normally use Emacs on the file, since
4237 it can detect that a file has changed out from under it. You could
4238 also copy and zero out the history file, edit the copy and append any
4239 new records to the edited copy before replacing it.
4241 Last modified: _6/13/1997_
4243 6. Why does the history file grow so quickly?
4245 It stores 'U' records, which come in handy sometimes when you are
4246 tracking whether people have updated each other's code before testing.
4247 There should (and probably will sometime) be a way to choose what
4248 kinds of events go into the history file.
4250 The contributed "cln_hist.pl" script will remove all the 'U' records,
4251 plus matching pairs of 'O' and 'F' records during your normal clean up
4252 of the history file.
4254 Last modified: _6/13/1997_
4256 7. What is the difference between "cvs history -r <tag/rev>" and "cvs
4259 The '-t' option looks for a Tag record stored by "rtag" in the history
4260 file and limits the search to dates after the last <tag> of the given
4263 The '-r' option was intended to search all files looking for the <tag>
4264 in the RCS files. It takes forever and needs to be rewritten.
4266 Last modified: _6/13/1997_
4268 8. Why does "cvs history -c -t <tag>" fail to print anything?
4270 You have been using "tag" instead of "rtag". The "tag" command
4271 currently doesn't store a history record. This is another remnant of
4272 CVS's earlier firm belief in "modules". But it also has a basis in how
4273 "rtag" and "tag" were originally used.
4275 "rtag" was intended for large-scale tagging of large chunks of the
4276 Repository, an event work recording. "tag" was intended for adding and
4277 updating tags on a few files or directories, though it could also be
4278 used to tag the entire checked-out working tree when there is no
4279 module defined to match the tree or when the working tree is the only
4280 place where the right collection of revisions to tag can be found.
4282 Last modified: _6/13/1997_
4284 9. "cvs history -a -o" only printed one line for each checked-out module.
4285 Shouldn't it print all the directories where the modules are checked out?
4289 Command Question it is supposed to answer.
4290 ---------------- ------------------------------------------
4291 cvs history -o What modules do I have checked out?
4292 cvs history -a -o <same for all users>
4294 cvs history -o -w What working directories have I created
4295 and what modules are in them?
4296 cvs history -a -o -w <same for every user>
4298 The -o option chooses the "checked out modules" report, which is the
4299 default history report.
4301 Last modified: _6/13/1997_
4303 10. I can't figure out "history", can you give me concrete examples?
4305 Default output selects records only for the user who executes the
4306 "history" command. To see records for other users, add one or more "-u
4307 user" options or the '-a' option to select *all* users.
4309 To list (for the selected users): Type "cvs history" and:
4311 * Checked out modules: -o (the default)
4312 * Files added since creation: -x A
4313 * Modified files since creation: -c
4314 * Modified files since last Friday: -c -D 'last Friday'
4315 * Modified files since TAG was added: -c -t <tag>
4316 * Modified files since TAG on files: -c -r <tag>
4317 * Last modifier of file/Repository X? -c -l -[fp] X
4318 * Modified files since string "str": -c -b str
4319 * Tag history: (Actually "rtag".) -T
4320 * History of file/Repository/module X: -[fpn] X
4321 * Module report on "module": -m module
4323 Last modified: _6/13/1997_
4325 11. Can we merge history files when we merge Repositories?
4327 Assuming that the two Repositories have different sets of pathnames,
4328 it should be possible to merge two history files by sorting them
4329 together by the timestamp fields.
4331 You should be able to run:
4333 sort +0.1 ${dir1}/history ${dir2}/history > history
4335 If you "diff" a standard history file before and after such a sort,
4336 you might see other differences caused by garbage (split lines, nulls,
4337 etc) in the file. If your Repository is mounted through NFS onto
4338 multiple machines you will also see a few differences caused by
4339 different clocks on different machines. (Especially if you don't use
4340 NTP to keep the clocks in sync.)
4342 Last modified: _6/13/1997_
4344 Category: /Commands_/import_im_imp/
4346 " + "import", "im", "imp""
4348 1. What is "import" for?
4350 The "import" command is a fast way to insert a whole tree of files
4353 The first "import" to a particular file within the Repository creates
4354 an RCS file with a single revision on the "Vendor branch." Subsequent
4355 "import"s of the same file within the Repository append a new revision
4356 onto the Vendor branch. It does not, as some seem to believe, create a
4357 new branch for each "import". All "imports" are appended to the single
4360 If the file hasn't changed, no new revision is created -- the new
4361 "Release-Tag" is added to the previous revision.
4363 After the import is finished, files you have not changed locally are
4364 considered to have changed in the "Main line of development". Files
4365 you *have* changed locally must have the new Vendor code merged into
4366 them before they are visible on the "Main line".
4370 Last modified: _6/13/1997_
4372 2. How am I supposed to use "import"?
4374 Create a source directory containing only the files you want to
4375 import. Make sure you clean up any cruft left over from previous
4376 builds or editing. You want to make sure that the directory contains
4377 only what you want to call "source" from which everything else is
4380 If this is not the first import from this "Vendor", you should also
4381 compare the output of "find . ! -name CVS -print | sort" executed both
4382 at the head of a checked out working directory and at the head of the
4383 sources to be imported. If you find any deleted or renamed files, you
4384 have to deal with them by hand. (See 4B.8 on renaming.)
4386 "cd" into your source directory and type:
4388 cvs import -m "Message" <repos> <Vendor-Tag> <Release-Tag>
4390 where <repos> is the relative directory pathname within the Repository
4391 that corresponds to the sources you are importing.
4393 You might also consider using the "-I !" option to avoid ignoring
4394 anything. It is easier to remove bogus files from the Repository than
4395 to create a sparse tree of the ignored files and rerun "import".
4397 For example, if the FSF, CVS, Make and I are still active in the year
4398 2015, I'll import version 89.53 of GNU make this way:
4400 cvs import -m "GNUmake V89.53" gnu/make GNU GNUMAKE_89_53
4402 See 3H.13 for more details.
4404 Last modified: _6/13/1997_
4406 3. Why does import put files on a branch? Why can't I work on the main
4407 trunk instead of a Vendor branch?
4409 This was a Design choice. The Vendor branch is the way "import" deals
4410 with a Vendor release. It is a solution to the Engineering problem of
4411 how to merge multiple external releases of Vendor-supplied sources
4412 into your ongoing work. The Vendor releases are kept on a separate,
4413 special, "Vendor" branch and your work is kept on the RCS trunk. New
4414 Vendor releases are imported onto the Vendor branch and then merged
4415 into your work, if there is any, on the trunk.
4417 This way, you can use CVS to find out not only about your work, but
4418 you can also find out what the Vendor changed by diffing between two
4419 of the Release Tags you handed to "import".
4421 CVS was designed to work this way. If you use CVS in some other way,
4422 you should think carefully about what you are doing.
4424 Note that the CVS "Main Branch" and the RCS Main Trunk are not the
4425 same. Placing files on the Vendor Branch doesn't keep you from
4426 creating a development branch to work on.
4428 See Section 4C, on Branching.
4430 If you are not working with 3rd party (i.e. Vendor) sources, you can
4431 skip the "import" and avoid the Vendor branch entirely. It works just
4432 as well to move pre-existing RCS files into Repository directories.
4434 You can create a whole Repository tree by copying a directory
4435 hierarchy of normal source files directly into the Repository and
4436 applying CVS to it. Here's an idea you should *test* before using:
4438 cd <your source tree>
4440 set module = xyzzy <<== Your choice of directory name
4441 mkdir $CVSROOT/$module
4443 (cd $source; tar cf - .) | tar xvpBf -
4444 find . -type f -exec ci -t-Original. {} \;
4446 The RCS "ci" command, without -u or -l options, will turn your source
4447 file into an RCS (",v") and delete the original source.
4449 Last modified: _6/13/1997_
4451 4. Is there any way to import binary files?
4453 If you configured CVS to use the GNU version of "diff" and "diff3",
4454 then you can import any kind of file.
4456 Binary files with RCS keywords in them are a problem, since you don't
4457 want them to expand.
4459 If the tree you are about to "import" is entirely filled with binary
4460 files, you can use the '-ko' option on "import". Otherwise, I would
4461 run the import normally, then fix the binary files as described below
4464 See 4D.1 on Binary files.
4466 Last modified: _6/13/1997_
4468 5. Why does "import" corrupt some binary files?
4470 The RCS "co" command, when it is invoked by a CVS "checkout" or
4471 "update" (or after a "commit") command, searches for and expands a
4472 list of keywords within the file. They are documented in the RCS "co"
4473 man page. Strings such as "$\Id$" (or "$\Id:"), or "$\Revision$" (or
4474 "$\Revision:") are altered to the include the indicated information.
4476 [[Note: The keywords should appear in the text without the '\'
4477 character I have inserted to *avoid* expansion here. The only real RCS
4478 keywords in this document are at the top of the file, where I store
4479 the Revision and Date.]]
4481 If RCS keyword strings show up in a binary file, they will be altered
4482 unless you set the '-ko' option on the RCS files to tell RCS to keep
4483 the original keyword values and not to expand new ones. After
4484 "import", you can set the '-ko' option this way:
4486 cvs admin -ko <file>
4490 After an import that didn't use '-ko' (because the whole tree wasn't
4491 of binary files) you should fix up the binary files as described above
4492 before checking out any new copies of the files and before updating
4493 any working directories you checked out earlier.
4495 See 4D.1 on Binary files.
4497 Last modified: _6/13/1997_
4499 6. How do I retain the original $\Revision$ strings in the sources?
4501 If you want to leave old RCS keywords as they are, you can use the
4502 '-ko' tricks described above.
4504 Last modified: _6/13/1997_
4506 7. I imported some files for the Yarg compiler that compiles files with a
4507 suffix of ".yarg" and whose comment prefix is "YARG> ". When I check them
4508 out, they will no longer compile because they have this junk in them. Why?
4510 YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>
4512 # Revision 1.3 1998/03/03 00:16:16 bubba
4513 # What is 2+2 anyway?
4515 # Revision 1.2 1998/03/03 00:15:15 bubba
4516 # Added scorekeeping.
4518 YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>
4520 Well bubba, "Yarg" hasn't hit the big time yet. Neither RCS nor CVS
4521 know about your suffix or your comment prefix. So you have two
4524 Check out the Yarg-less module, and tell all the files about your
4525 comment prefix. Visit each directory and type:
4527 cvs admin -c"YARG> " *.yarg
4529 If *all* files in the whole directory tree are Yarg files, you can use
4532 cvs admin -c"YARG> " .
4534 Then save any changes you made, remove all the "*.yarg" files and grab
4535 new copies from the Repository:
4537 rm *.yarg (or: find . -name '*.yarg' -exec rm {} ';') (or: find .
4538 -name '*.yarg' -print | xargs rm) (or: find . -name '*.yarg' -print0 |
4539 xargs -0 rm if you have spaces in filenames and the GNU find/xargs.)
4542 It might be faster to remove the whole directory and check it out
4545 Change the import.c file in the CVS sources and add the .yarg
4546 suffix, along with the "YARG> " comment prefix to the "comtable"
4549 If you ever plan to add new files with $\Log in them, you should also
4550 go into the RCS sources and make the same change in the table
4551 contained in the "rcsfnms.c" file.
4553 Then delete the imported files from the Repository and re-"import" the
4556 Last modified: _6/13/1997_
4558 8. How do I make "import" save the timestamps on the original files?
4560 Use "import -d" to save the current timestamps on the files as the RCS
4563 See 4D.8 for another aspect of file timestamps.
4565 Last modified: _6/13/1997_
4567 9. Why can't I "import" 3 releases on different branches?
4569 I'll bet you typed something like this:
4572 cvs import -b 1.1.2 VENDOR2 Version2
4574 cvs import -b 1.1.3 VENDOR3 Version3
4576 cvs import -b 1.1.4 VENDOR4 Version4
4578 This is wrong, or at least it won't help you much. You have created
4579 three separate Vendor branches, which is probably not what you wanted.
4581 Earlier versions of CVS, as described in Brian Berliner's Usenix
4582 paper, tried to support multiple Vendor branches on the theory that
4583 you might receive source for the *same* program from multiple vendors.
4584 It turns out that this is very rare, whereas the need to branch in
4585 *your* development, for releases and for project branches, is much
4588 So the model now is to use a single vendor branch to contain a series
4589 of releases from the same vendor. Your work moves along on the Main
4590 Trunk, or on a CVS branch to support a real "branch in development".
4592 To set this up, you should type this instead of the above:
4595 cvs import VENDOR Version2
4597 cvs import VENDOR Version3
4599 cvs import VENDOR Version4
4601 Last modified: _6/13/1997_
4603 10. What do I do if the Vendor adds or deletes files between releases?
4605 Added files show up with no extra effort. To handle "removed" files,
4606 you should always compare the tree structure of the new release
4607 against the one you have in your Repository. If the Vendor has removed
4608 files since the previous release, go into a working directory
4609 containing your current version of the sources and "cvs remove"
4610 (followed by "cvs commit" to make it really take effect) each file
4611 that is no longer in the latest release.
4613 Using this scheme will allow you to "checkout" any version of the
4614 vendor's code, with the correct revisions and files, by using
4615 "checkout -r Version[234]".
4617 Renames are harder to find, since you have to compare file contents to
4618 determine that one has occurred. If you notice one, see 4B.8 on
4621 Last modified: _6/13/1997_
4623 11. What about if the Vendor changes the names of files or directories, or
4624 rearranges the whole structure between releases?
4626 Currently CVS can't handle this cleanly. It requires "renaming" a
4627 bunch of files or directories.
4629 See 4B.8 on "renaming" for more details.
4631 What I generally do is to close the Repository for a while and make
4632 changes in both the Repository and in a copy of the vendor release
4633 until the structure matches, then execute the import.
4635 If you ever have to check out and build an old version, you may have
4636 to use the new, or completely different Makefiles.
4638 Last modified: _6/13/1997_
4640 12. I thought "import" was for Vendor releases, why would I use it for code
4641 of my own? Do I have to use import?
4643 For code you produce yourself, "import" is a convenience for fast
4644 insertion of whole trees. It is not necessary. You can just as easily
4645 create ",v" files using the RCS "ci" command and move them directly
4646 into the Repository.
4648 Other than the CVSROOT directory, the Repository consists entirely of
4649 directories of ",v" files. The Repository contains no other state
4652 See Section 4B, on Setting up and Managing the Repository.
4654 Last modified: _6/13/1997_
4656 13. How do I import a large Vendor release?
4658 When the sum of the changes made by the Vendor and the changes made by
4659 local developers is small, "import" is not a big problem. But when you
4660 are managing a large Repository, any care taken up front will save you
4663 First read the following, then, before executing "import", see the
4664 questions in Section 4C dealing with branch merges and Vendor branch
4667 If this is not the first import of this code, before starting, rtag
4668 the whole directory you will be changing.
4670 The first step is to make sure the structure of the new files
4671 matches the structure of the current Repository.
4673 Run "find . -print | sort" on both trees and "diff" the output.
4675 Alter the "source" tree until the "diff" (of the list of filenames,
4676 not of the whole trees) shows that the directory structures are
4679 The "comm" command, if you have it, can help figure out what has been
4680 added or deleted between releases.
4682 If they deleted any files, you can handle them cleanly with "cvs
4683 remove". The command "comm -23 files.old files.new" will show you a
4684 list of files that need to be removed.
4686 You should examine the list first to see if any have been renamed
4687 rather than simply deleted.
4689 If they renamed any files, see 4B.8 on renaming files.
4691 Remember to *SAVE* the output from the import command.
4693 When you have dealt with removed and renamed files, then you can
4697 cvs import -I ! -m "Message" <repos> <VendorTag> <ReleaseTag>
4701 "-I !" is an optional argument that keeps "import" from ignoring
4702 files. The comparison of the "find" commands above will probably avoid
4703 the need for this, but it is easier to remove files from the
4704 Repository than to run a subset "import" to catch just the ignored
4705 files. [You might have to quote or backwhack the '!'.]
4707 Message is the log message to be stored in the RCS files.
4709 <repos> is a relative path to a directory within the
4710 Repository. The directory <new source> must be at
4711 the same relative level within the new sources as
4712 the <repos> you give is within the Repository. (I
4713 realize this is not obvious. Experiment first.)
4715 <VendorTag> is a Tag used to identify the Vendor who sent you
4716 the files you are importing. All "imports" into
4717 the same <repos> *must* use the same VendorTag.
4718 You can find it later by using the "log" command.
4720 <ReleaseTag> is a Tag used to identify the particular release of the
4721 software you are importing. It must be unique and should be mnemonic
4722 -- at least include the revision number in it. (Note: you can't use
4723 '.' characters in a Tag. Substitute '_' or '-'.)
4725 There will be six categories of files to deal with. (Actually there
4726 are eight, but you have already dealt with "removed" and "renamed"
4729 If this is the first "import" into a given <repos> directory, only the
4730 first three of these ('I', 'L' and 'N') can occur.
4734 CVS prints: I filename
4736 You'll need to examine it to see if it *should* have been ignored. If
4737 you use "-I !", nothing will be ignored.
4741 CVS prints: L linkname
4743 Links are "ignored", but you'll probably want to create a "checkout
4744 helper" function to regenerate them.
4748 CVS prints: N filename
4750 CVS creates a new file in the Repository. You don't have to do
4751 anything to the file, but you might have to change Makefiles to refer
4752 to it if this is really a new file.
4754 A file unchanged by the Vendor since its last release.
4756 CVS prints: U filename
4758 CVS will notice this and simply add the new ReleaseTag to the latest
4759 rev on the Vendor branch.
4761 No work will be needed by you, whether you have changed the file or
4762 not. No one will notice anything.
4764 A file changed by the Vendor, but not by you.
4766 CVS prints: U filename
4768 CVS should add the file onto the vendor branch and attach the Release
4771 When you next execute "update" in any working directory you'll get the
4774 A file changed by both the Vendor and by you.
4776 CVS prints: C filename
4778 These are the trouble files. For each of these files (or in groups --
4779 I usually do one directory at a time), you must execute:
4781 cvs update -j <PreviousReleaseTag> -j <ReleaseTag>
4783 cvs update -j <VendorTag:yesterday> -j <VendorTag>
4785 It will print either 'M' (if no overlaps) or 'C', if overlaps. If a
4786 'C' shows up, you'll need to edit the file by hand.
4788 Then, for every file, you'll need to execute "cvs commit".
4790 See the part of Section 4C dealing with branch merges.
4792 If you are truly performing a large import, you will most likely
4793 need help. Managing those people is another problem area.
4795 Since the merge of the Vendor branch is just like any other merge, you
4796 should read section 4C for more info about performing and cleaning up
4799 The larger the import, and the larger the group of people involved,
4800 the more often you should use "tag" and "rtag" to record even trivial
4801 milestones. See 4C.14, especially the "paranoid" section.
4803 Before starting the import, you should install and test a "commitinfo"
4804 procedure to record all commits in a file or via Email to a mail
4805 archive. Along with the tags you placed on the Repository before the
4806 import, this archive will help to track what was changed, if problems
4809 There are four stages to the recovery:
4811 Parcel out the work -- Effective Emacs Engineering.
4813 As input to the assignment process, you might want to examine the tree
4814 and record the last person who changed the file. You can also
4815 research, if you don't already know, who is expert in each area of the
4818 Examine the import log (you saved the output, right?), estimate how
4819 much work is involved in each area and assign groups of files to
4820 individual developers. Unless some directory is immense, it is easier
4821 to manage if you assign whole directories to one person.
4823 Keep a list. Suggest a completion date/time. Tell them to "commit" the
4824 file when they are finished with the merge. If you tagged the
4825 Repository before starting the import, you should have no trouble
4826 figuring out what happened.
4828 If you can, find out (or tell them) which working directory to use.
4829 You should verify that the working directory they use is on the Main
4830 Branch ("update -A") and without modified files.
4832 If you trust your crew, have them notify you by Email. Have them send
4833 you the output from "cvs update" in their working directory. You might
4834 have to poll some people until you are certain they have finished, or
4835 have given up. (This is not an invention. I've heard a false, "Yeah,
4836 sure. I finished yesterday," more times that you'd believe.)
4838 When all reports are in, go on to the Source Verification stage.
4840 Source Verification -- CVS and other Tools.
4842 If you didn't dictate which ones to use, find all working directories
4843 and run "cvs -n update" in all of them. The history command and the
4844 "commitinfo" log you set up might help to find checked out working
4847 Sticky conflict flags will help, but they can't recover from
4848 sloppiness or incompetence. You might want to check everything out
4849 into a tree and grep for the parts of the merge conflict markers CVS
4850 doesn't look for. CVS looks for the string '^>>>>>>> '. The merge
4851 operation also puts '^<<<<<<< ' and '^======= ' markers in the file
4852 that careless developers might leave there.
4854 If you find problems simply by looking at the source files and working
4855 directories, start the flogging now. Resolving the textual conflicts
4856 is the easy part. Weed the turkeys out before reaching the next part
4857 of the cleanup -- the resolution of logical conflicts.
4859 Then apply a set of post-commit tags.
4861 Logical Verification -- Diff and powerful eyeballs.
4863 No source control system can solve the problem of resolving
4864 distributed conflicts in program logic. If you change the argument
4865 template for function A (defined in file A.c) and add new calls to
4866 function A from within function B (defined in file B.c) using the old
4867 argument format, you are outside the realm of CVS's competence.
4869 Assign someone to understand what the Vendor changed by running "cvs
4870 diff -c -r <PreviousReleaseTag> <ReleaseTag>", where the tags were
4871 those handed to the last two invocations of "import".
4873 Then have the same person compare that output (logically or you can
4874 actually diff the diffs) to the output of the similar "cvs diff -c -r
4875 <pre-import-tag> <post-commit-tag>". The two sets of differences
4876 should be almost identical. They should both show only the work *you*
4879 Product Verification -- Build and Test.
4881 Don't let your help off the hook until you verify that the merge
4882 actually produced something that can compile and pass tests. Compiling
4883 should really be part of the logical verification phase, but you
4884 should test the output of the build system before declaring victory
4885 and releasing the troops.
4887 After it is all built, apply another set of tags to mark the end of
4888 the "import process". You can delete the intermediate tags you added
4889 during source and logic testing, but keep the "pre-import" and
4890 "post-import" tags forever.
4892 Of course, experience can tell you when to skip a step. But I'd start
4893 out by considering each one as necessary unless you can prove
4896 Last modified: _6/13/1997_
4898 14. Explain: ERROR: cannot create link to <file>: Permission denied
4900 This error appears when you try to execute a second (or later)
4901 "import" into the same module from a directory to which you don't have
4904 The "link error" is caused by a feature purposely added to speed up
4907 Though the error message is somewhat strange, it indicates that
4908 "import" is supposed to be executed only in writable directories.
4910 Last modified: _6/13/1997_
4912 15. Where does the -m <message> go when the file doesn't change?
4914 The <message> handed to import is used as an RCS log message, but only
4915 if the imported file changed since the last version on the Vendor
4916 branch. If the imported file hasn't changed, then no new revision is
4917 created. The <ReleaseTag> is still applied, but to the previous
4918 revision. So the Tags are still correct, but the message is lost.
4920 Maybe it should be appended to the previous log message. But currently
4923 Last modified: _6/13/1997_
4925 16. How do I "import" just the files ignored by a previous "import"?
4927 A real answer follows, but first, an editorial:
4929 I am now convinced that you should always use the "-I !" option.
4930 Removing a few extraneous files from the Repository is a lot easier
4931 than the recovery step described below.
4933 Let's assume your original import procedure was: (We assume there is
4934 enough disk space in /tmp.)
4936 cd <head-of-vendor-tree>
4937 cvs import -m 'xyz 1.3' gnu/xyz GNU GNUXYZ_1_3 | tee /tmp/IMP
4939 To import just the files ignored by "import", I would do this:
4941 Create a list of the ignored files to import:
4943 cd <head-of-vendor-tree> awk '/^I / {print $2}' /tmp/IMP | sed
4944 's|^gnu/xyz/||' > /tmp/IG [Edit the IG file to contain just the files
4947 Then create a sparse directory by handing your list to the GNU
4948 version of "tar", installed in many places as "gtar":
4950 mkdir /tmp/FIXUP gtar -T /tmp/IG -c -f - . | (cd /tmp/FIXUP; gtar xvBf
4953 Then rerun the import. Use the exact same command, but execute it in
4954 the sparse directory tree you just created. And this time, tell it not
4958 cvs import -I ! -m 'xyz 1.3' gnu/xyz GNU GNUXYZ_1_3
4960 Last modified: _6/13/1997_
4962 17. Why did "import" ignore all the symlinks?
4964 This is another design choice.
4966 Like the Unix "tar" command, "import" could sprout an option to follow
4967 symbolic links, but I don't think CVS will ever follow symbolic links
4970 Two possible future enhancements have been seriously discussed:
4972 Treat symbolic links as data in its parent directory (the way
4973 ClearCase does) in some sort of per-directory control file.
4975 Treat symbolic links as version-controlled elements themselves,
4976 whose data is the value of readlink(2).
4978 For now, they are simply ignored.
4980 If you want to save and reconstruct symlinks, you might want to define
4981 a "checkout" or "update" program in the modules file which could
4982 consult a file kept under CVS in your working directory and make sure
4983 the specified links are in place.
4985 Last modified: _6/13/1997_
4987 Category: /Commands_/log_lo_rlog/
4989 " + "log", "lo", "rlog""
4991 1. What is "log" for?
4993 To provide an interface to the RCS "rlog" command, which displays
4994 information about the underlying RCS files, including the revision
4995 history and Tag (RCS calls it a "symbol") list.
4997 Last modified: _6/13/1997_
4999 2. How do I extract the log entries between two revisions?
5001 If both <rev1> and <rev2> are on the same branch, you can get what you
5002 are looking for with: (If they aren't on the same branch you'll either
5003 get an error or a display of the whole change log.)
5005 cvs log -r<rev1>:<rev2> <file>
5007 If you want all the revisions on the branch from <rev1> to the end of
5008 the branch <rev1> is on, you can use:
5010 cvs log -r<rev1>: <file>
5012 (If <rev1> is a numeric RCS symbol attached to a branch revision with
5013 an even number of '.'s in it, you get the whole branch.)
5015 If you want all the revisions on the branch from the beginning of the
5016 branch <rev2> is on up to revision <rev2>, you can use:
5018 cvs log -r:<rev2> <file>
5020 Note: Depending on whether <rev1> and <rev2> are:
5022 - numeric or symbolic
5023 - in the file or not
5024 - on the same branch or not
5026 the RCS "rlog" (and therefore the "cvs log") command will
5027 display some combination of:
5030 - (intuitively correct) partial log listings
5031 - a display of the entire change log.
5033 Last modified: _6/13/1997_
5035 3. How do I extract the log entries on a whole branch?
5037 cvs log -r<rev> <file>
5039 where <rev> must be a branch revision (one with an even number of
5040 dots) or a *non-branch* tag on a branch revision. Non-branch tags on a
5041 branch revision are not normally attached by CVS, to add one you will
5042 have to explicitly tag a physical branch number within each file.
5043 Since these branch numbers are almost never the same in different
5044 files, this command is not all that useful.
5046 The intuitive command (at least from the CVS perspective):
5048 cvs log -r<branch_tag> <file>
5052 Last modified: _6/13/1997_
5054 4. How do I generate ChangeLogs from RCS logs?
5056 A program called rcs2log is distributed as part of GNU Emacs 19. A
5057 (possibly older) version of this program appears in the contrib
5058 directory of the cvs source tree.
5060 Last modified: _6/13/1997_
5062 5. Why does "log" tell me a file was committed exactly 5 hours later
5066 I can tell by this question that you were working in a time zone that
5067 is 5 hours behind GMT (e.g. the U.S. East Coast in winter).
5069 RCS file dates are stored in GMT to allow users in different time
5070 zones to agree on the meaning of a timestamp. At first glance this
5071 doesn't seem necessary, but many companies use distributed file
5072 systems, such as NFS or AFS, across multiple timezones.
5074 Some standard form must be used. GMT, as the "grid origin", is an
5075 obvious candidate. The only other reasonable choice is to put the
5076 timezone information in all the time stamps, but that changes the RCS
5077 file format incompatibly, a step which has been avoided in the last
5080 Last modified: _6/13/1997_
5082 Category: /Commands_/patch_pa_rdiff/
5084 " + "patch", "pa", "rdiff""
5086 1. What is "patch" for?
5088 To produce a "diff" between tagged releases to be handed to the
5089 "patch" command at other sites. This is the standard way that source
5090 patches are distributed on the network.
5092 Last modified: _6/13/1997_
5094 2. Why does "patch" include files from the Attic when I use '-D'?
5096 See the explanation of the same problem with "update -D" contained in
5099 Last modified: _6/13/1997_
5101 3. How do I make "patch" produce a patch for one or two files? It seems to
5102 work only with modules.
5104 Patch is intended for producing patches of whole modules between
5105 releases to be distributed to remote sites. Instead of "patch", you
5106 can use the "diff" command with the '-c' context option:
5108 cvs diff -c -r <rev/tag> -r <rev/tag> <file1> . . .
5110 The patch command will be able to merge such a "diff" into the remote
5113 If you configured CVS to use a version of "diff" that supports the
5114 '-u' option, you can produce a more compact "patch" in "unidiff"
5115 format. The latest revisions of the patch command can parse and apply
5116 patches in "unidiff" format.
5118 Last modified: _6/13/1997_
5120 Category: /Commands_/release_re_rel/
5122 " + "release", "re", "rel""
5124 1. What is "release" for?
5126 To register that a module is no longer in use. It is intended to
5127 reverse the effects of a "checkout" by adding a record to the history
5128 file to balance the checkout record and by optionally allowing you to
5129 delete the checked-out directory associated with the module name.
5131 Last modified: _6/13/1997_
5133 2. Why can't I reverse a "cvs checkout path/name/subdir" with a "cvs
5134 release path/name/subdir" without an "unknown module name"?
5136 A simplistic implementation. (I can say this -- I wrote it.)
5138 The "release" function was written for CVS 1.2 under the assumption
5139 that the "module name" is a first class, unavoidable interface to the
5140 Repository, allowing no way to retrieve anything other than by module
5141 name. Though it is easier to program that way, many users of CVS
5142 believe the modules support to be too primitive to allow such a
5145 Since "release" was written, other parts of CVS broke that assumption.
5146 It needs to be revised.
5148 Last modified: _6/13/1997_
5150 3. Why can't I "release" portions of a checked out directory? I should be
5151 able to "release" any file or sub-directory within my working directory.
5153 This isn't really a limitation in "release", per se. CVS doesn't try
5154 to keep track of which files in which directories are "checked out"
5155 and which are just lying there. You can delete directories and
5156 "update" will not bring them back unless you add a special "-d"
5159 In other words, CVS doesn't keep track of how you adjust the partition
5160 between files you consider part of your working set and files that
5161 were checked out because they are part of the same module or
5162 directory. And neither does "release".
5164 In future CVS releases, "release" might become sophisticated enough to
5165 handle both the reversal of a "checkout" and the deletion of random
5166 portions of the working directory, but it isn't that way now.
5168 Last modified: _6/13/1997_
5170 4. I removed the tree that I was about to start working on. How do I tell
5171 cvs that I want to release it if I don't have it anymore?
5175 Last modified: _6/13/1997_
5177 5. Why doesn't "release -d module" reverse a "checkout module"?
5179 It does, if you are using "module" in a way that "release" expects: a
5180 non-alias string in the left column of the "modules" database.
5182 If "module" is really an alias, or if you are using a relative path in
5183 the place of "module", or if you renamed the directory with the -d
5184 option in the modules file or on the "checkout" command line, then the
5185 current version of "release" won't work.
5187 Future versions of "release" will probably fix most of these.
5189 Last modified: _6/13/1997_
5191 6. Why can't I release a module renamed with "cvs checkout -d"?
5193 The current version of "release" doesn't know how to track the
5194 renaming option ('-d') of the "checkout" command. It will probably be
5195 fixed in the future.
5197 Last modified: _6/13/1997_
5199 Category: /Commands_/remove_rm_delete/
5201 " + "remove", "rm", "delete""
5203 1. What is "remove" for?
5205 To remove a file from the working branch. It removes a file from the
5206 main branch by placing it in an "Attic" directory.
5208 Last modified: _6/13/1997_
5210 2. Why doesn't "remove" work on directories when it appears to try?
5212 Oversight. It should be able to delete an empty directory, but you
5213 still don't have a way to remember when it was there and when it
5214 disappeared to allow the "-D " option to work.
5216 You'll have to remove the working directory and the matching directory
5219 Note that you want to do a _cvs remove dir_ in the working directory,
5220 do a cvs commit, and then do a _rmdir dir_ in the Repository.
5221 (msusrtsp.mark at eds dot com)
5223 Last modified: _12/18/1997_
5225 3. I don't like removing files. Is there another way to ignore them?
5227 There's no reason to be hasty in using the "remove" command.
5229 If there is a way to ignore files in your build procedures, I'd just
5230 do that. Later, when you decide that the files are really ancient, you
5231 can execute a "remove" command to clean up.
5233 The CVS "ignore" concept can't ignore files already in CVS.
5235 Last modified: _6/13/1997_
5237 4. I just removed a file. How do I resurrect it?
5239 If you executed "remove", but haven't typed "commit" (you can tell
5240 this by the 'R' notation that "update" prints next to the file), you
5241 can execute "add" to reverse the "remove".
5243 If you followed the "remove" with a "commit", you'll have to move it
5244 back out of the Attic by hand:
5246 I use something like this: (csh-like syntax)
5248 set repos = `cat ./CVS/Repository`
5249 mv $repos/Attic/filename,v $repos/filename,v
5251 (If you use relative paths in your Repository files, that first line
5252 becomes: set repos = $CVSROOT/`cat ./CVS/Repository`)
5254 While a file is in the Attic, you can't "add" another file by the same
5255 name. To add such a file you either have to move it by hand as in the
5256 above, or delete it from the Attic.
5258 The main reason for the Attic is to retain files with tags in them. If
5259 you execute: "update -r <oldtag>", files with <oldtag> attached to
5260 some revision will be taken from the normal Repository area and from
5261 the Attic. That's why you can't "add" a file with the same name.
5262 "remove" only moves a file off the main branch, it doesn't obliterate
5265 Last modified: _6/13/1997_
5267 5. Why doesn't "remove" delete the file? Instead, it prints an error
5268 message and tells me to remove the file by hand.
5270 Design choice. Unix software written within last decade, usually
5271 requires an extra verification step, such as answering a question or
5272 adding a flag on the command line. CVS currently requires that you
5273 delete the file first unless you specify the '-f' (force) option,
5274 which deletes the file before performing "cvs remove".
5276 Last modified: _6/13/1997_
5278 Category: /Commands_/rtag_rt_rfreeze/
5280 " + "rtag", "rt", "rfreeze""
5282 1. What is "rtag" for?
5284 To add a symbolic label (a "tag") to the last committed revisions of a
5285 module directly in the Repository.
5287 Last modified: _6/13/1997_
5289 2. Why use "rtag"? It assumes no one is changing the Repository.
5291 Though the "tag" command is more useful in marking the revisions you
5292 have in a particular working directory, "rtag" is much handier for
5293 whole-Repository actions, which occur at major release boundaries.
5295 Last modified: _6/13/1997_
5297 3. What revision does "rtag -r <tag1> <tag2>" actually put the tag on?
5299 In short, the '-r' option is another way to select the revision to
5300 tag. The revision is selected the same way for all commands that
5301 accept a "-r <tag/rev>" option.
5303 Depending on whether <tag1> is a <branch_tag>, or a non-branch <tag>
5304 and on whether you use the '-b' option to "rtag", you get four
5307 rtag -r <tag1> <tag2>
5309 Adds the non-branch tag <tag2> to the same revision that the
5310 non-branch tag <tag1> is attached to.
5315 <file> --> Symbols: TT1:1.4
5316 After --> Symbols: TT1:1.4,TT2:1.4
5318 rtag -r <branch_tag1> <tag2>
5320 Adds the non-branch tag <tag2> to the HEAD of (the highest revision
5321 number on) the branch labelled with tag <branch_tag1>.
5324 <branch_tag1> --> BR1
5326 <file> --> Symbols: BR1:1.2.0.2 (1.2.2.5 is HEAD)
5327 After --> Symbols: BR1:1.2.0.2,TT2:1.2.2.5
5329 If the branch tagged by <branch_tag1> has not been created, then the
5330 tag shows up on the branch point revision:
5333 <branch_tag1> --> BR1
5335 <file> --> Symbols: BR1:1.2.0.2 (No 1.2.X exists.)
5336 After --> Symbols: BR1:1.2.0.2,TT2:1.2
5338 rtag -b -r <tag1> <branch_tag2>
5340 Adds the magic branch tag <branch_tag2> to the revision that the
5341 non-branch tag <tag1> is attached to, preparing it to be a branch
5346 <branch_tag2> --> BR2
5347 <file> --> Symbol: TT1:1.4
5348 After --> Symbol: TT1:1.4, BR2:1.4.0.2
5350 rtag -b -r <branch_tag1> <branch_tag2>
5352 Adds the magic branch tag <branch_tag2> to the revision at the HEAD of
5353 (the highest revision number on) the branch labelled with
5354 <branch_tag1>, preparing it to be a branch point.
5357 <branch_tag1> --> BR1
5358 <branch_tag2> --> BR2
5359 <file> --> Symbol: BR1:1.2.0.2 (1.2.2.5 is HEAD)
5360 After --> Symbol: BR1:1.2.0.2,BR2:1.2.2.5.0.2
5362 If the branch tagged by <branch_tag1> has not been created, then the
5363 tag shows up as a second branch off the same branch point revision:
5366 <branch_tag1> --> BR1
5368 <file> --> Symbols: BR1:1.2.0.2 (No 1.2.X exists.)
5369 After --> Symbols: BR1:1.2.0.2,TT2:1.2.0.4
5371 In all four cases above, if <tag2> already exists on the file, you get
5372 an error unless you specify the '-F' option.
5374 In all four cases, if <tag1> does not exist on the file, <tag2> is not
5375 added unless you specify the '-f' option.
5377 Last modified: _6/13/1997_
5379 4. What happens if the tags are the same in "rtag -r <tag> <tag>"?
5381 Again, there are four cases depending on whether <tag> is a branch
5382 tag, or a non-branch tag and on whether you use the '-b' option to
5387 Is a no-op. It does nothing even with '-F' specified.
5389 If you add the '-f' option ("rtag -f -r <tag> <tag>"), then <tag> is
5390 attached to the latest revision on the Main Branch if the file does
5391 *not* already have <tag> on some revision.
5393 If the <tag> is already on the file, using "rtag -f" is still a no-op.
5395 rtag -r <branch_tag> <branch_tag>
5397 Produces an error, since the <branch_tag> is already on some revision
5400 But, "rtag -F -r <branch_tag> <branch_tag>" turns the magic branch tag
5401 into a non-branch tag.
5403 Symbols: BR1:1.4.0.2 becomes Symbols: BR1:1.4
5405 rtag -b -r <tag> <tag>
5407 Produces an error, since the <tag> is already on the file.
5409 But, "rtag -F -b -r <tag> <tag>" turns the non-branch tag into a magic
5412 Symbols: BR1:1.4 becomes Symbols: BR1:1.4.0.2
5414 rtag -b -r <branch_tag> <branch_tag>
5416 Produces an error, since the <branch_tag> is already on the file.
5418 But, "rtag -F -b -r <branch_tag> <branch_tag>" increments the branch
5419 number. It essentially removes the branch and creates a new one by the
5422 Symbols: BR1:1.2.0.4 becomes Symbols: BR1:1.2.0.6
5424 Last modified: _6/13/1997_
5426 5. Why doesn't "rtag -b -r <branch_tag1> <branch_tag2>" rename or duplicate
5429 None of the "tag" or "rtag" options rename anything. They only apply
5430 (or, with the '-F' option, move) tags to specific revisions in the
5433 See 3M.[3-4] above for details of how it works.
5435 To rename a non-branch tag, see 3O.9. To rename a magic branch tag,
5438 Last modified: _6/13/1997_
5440 Category: /Commands_/status_st_stat/
5442 " + "status", "st", "stat""
5444 1. What is "status" for?
5446 To display the status of files, including the revision and branch you
5447 are working on and the existence of "sticky" information.
5449 Last modified: _6/13/1997_
5451 2. Why does "status" limit the File: at the top to 17 characters?
5453 Designed that way to line up with other data. You can find the whole
5454 filename in the line beginning with "RCS version:", which is not
5457 Last modified: _6/13/1997_
5459 3. Why does it print "Sticky" lines when the values are "(none)"?
5461 Oversight. It should probably elide lines without information.
5463 Last modified: _6/13/1997_
5465 4. Shouldn't the status "Needs Checkout" be "Needs Update"?
5469 [[Did this show up in CVS 1.4?]]
5471 Last modified: _6/13/1997_
5473 Category: /Commands_/tag_ta_freeze/
5475 " + "tag", "ta", "freeze""
5477 1. What is "tag" for?
5479 To add a symbolic label (a "tag") to the RCS files last checked out,
5480 updated or committed in a working directory.
5482 Last modified: _6/13/1997_
5484 2. What is the difference between "tag" and "rtag"?
5486 The end result of both commands is that a <tag>, or symbolic name, is
5487 attached to a single revision in each of a collection of files.
5489 The differences lie in:
5491 The collection of files they work on.
5493 "rtag" works on the collection of files referred to by a "module" name
5494 as defined in the "modules" file, or a relative path within the
5497 "tag" works on files and directories specified on the command line
5498 within the user's working directory. (Default is '.')
5500 Both commands recursively follow directory hierarchies within the
5501 named files and directories.
5503 The revisions they choose to tag.
5505 "rtag" places a tag on the latest committed revision of each file on
5506 the branch specified by the '-r' option. By default it tags the Main
5509 "tag" places a tag on the BASE (i.e. last checked out, updated or
5510 committed) revision of each file found in the working directory. (The
5511 BASE revision of a file is the one stored in the ./CVS/Entries file.)
5513 A different set of command line options.
5515 For example, "rtag" takes a "-r <oldtag>" option to retag an existing
5516 tag. The "tag" command does not.
5520 Currently "rtag" records the <tag> and the module in the "history"
5521 file, while "tag" does not.
5523 Last modified: _6/13/1997_
5525 3. Why does "tag -b" not put a tag on the Branch Point revision? How do I
5526 refer to the Branch Point?
5528 This is probably an oversight, or a disbelief in the need for it. If
5529 everything works perfectly, the "update -j" command will do the merge
5530 you need and you don't need to check up on it by playing with the
5531 branch point revision.
5533 The '-b' option attaches a magic branch tag to allow CVS later to
5534 figure out the branch point. The actual revision that <tag> is
5535 attached to does not exist. References to the branch tag are
5536 equivalent to references to the latest revision on the branch.
5538 There is no way to refer to the branch point without adding a
5539 non-branch tag. You might want to add non-branch tags as a habit and
5540 add branch tags later, possibly immediate after adding the non-branch
5541 tag. See 4C.3 on Creating a Branch.
5543 Last modified: _6/13/1997_
5545 4. So "{r}tag" labels a bunch of files. What do you use a Tag for?
5547 You use it to "checkout" the labeled collection of files as a single
5548 object, referring to it by name.
5550 Anywhere a revision number can be used a Tag can be used. In fact tags
5551 are more useful because they draw a line through a collection of
5552 files, marking a development milestone.
5554 The way to think about a Tag is as a curve drawn through a matrix of
5555 filename vs. revision number. Consider this:
5557 Say we have 5 files (in some arbitrary modules, some may be in 2 or
5558 more modules by name, some may be in 2 or more modules because of the
5559 Repository tree structure) with the following revisions:
5561 file1 file2 file3 file4 file5
5563 1.1 1.1 1.1 1.1 /--1.1* <-*- <tag>
5564 1.2*- 1.2 1.2 -1.2*-
5565 1.3 \- 1.3*- 1.3 / 1.3
5570 At some time in the past, the '*' versions were tagged. Think of the
5571 <tag> as a handle attached to the curve drawn through the tagged
5572 revisions. When you pull on the handle, you get all the tagged
5573 revisions. Another way to look at it is that you draw a straight line
5574 through the set of revisions you care about and shuffle the other
5575 revisions accordingly. Like this:
5577 file1 file2 file3 file4 file5
5583 1.2*----1.3*----1.5*----1.2*----1.1 (--- <-- Look here
5588 I find that using these visual aids, it is much easier to understand
5589 what a <tag> is and what it is useful for.
5591 Last modified: _6/13/1997_
5593 5. How do I get "tag" and "rtag" to send mail the way "commit" does?
5595 The "commit" command is supported by two files ("commitinfo" and
5596 "loginfo") not used by other commands. To do logging the same way for
5597 "tag" and "rtag" would require another file like loginfo, which
5598 currently doesn't exist.
5600 The "rtag" command requires a "module" entry, which can specify a
5601 "tag" program using the "-t programname" option on the module line.
5603 There is no equivalent support for "tag".
5605 Last modified: _6/13/1997_
5607 6. Why can't "tag" handle the '-r' option that "rtag" takes?
5609 Oversight. The answer is probably "Fixed in a Future Release."
5611 Last modified: _6/13/1997_
5613 7. After a "tag <tag>" in my working directory, why doesn't "checkout -r
5614 <tag>" somewhere else produce copies of my current files?
5616 The only reason this would fail, other than misspelling the <tag>
5617 string, is that you didn't "commit" your work before "tagging" it.
5618 Only committed revisions may be tagged. Modified files are not marked
5621 Last modified: _6/13/1997_
5623 8. Why doesn't "tag" write a history record the way "rtag" does?
5625 The "rtag" command was originally intended to place major "release"
5626 tags onto modules. The "tag" functionality was developed to *move* the
5627 more significant tag when slight changes to individual files sneaked
5628 in after the release tag was stamped onto the Repository.
5630 The significant event was the "rtag", which was recorded in the
5631 "history" file for the "history -T" option to work.
5633 It turns out that "tag" is generally more useful than "rtag", so the
5634 model has changed. Future revisions of CVS will probably store both
5635 kinds of tags in the history file.
5637 Last modified: _6/13/1997_
5639 9. How do I rename a <tag>?
5641 For a procedure to rename a branch tag, See section 4D.5 The following
5642 covers only non-branch tags.
5644 First, pick a <newtag> that is not in use. You could reuse (i.e. move)
5645 an existing tag to the new revisions using the '-F' option, but that
5646 will confuse matters when both tags are not already on a file. (It
5647 will probably confuse "rtag -f" too.)
5649 Use "rtag" to place <newtag> only on revisions attached to <oldtag> in
5650 the whole Repository, then delete the old one.
5652 cvs rtag -r <oldtag> <newtag> world
5653 cvs rtag -d <oldtag> world.
5655 You can also checkout or update your working directory to the <oldtag>
5656 and "tag" rather than "rtag" the result. But that will take longer and
5657 it has the chance of producing conflicts.
5659 cvs update -r <oldtag>
5662 cvs update -A (or cvs update -r <previous_tag>)
5664 Last modified: _6/13/1997_
5666 Category: /Commands_/update_up_upd/
5668 " + "update", "up", "upd""
5670 1. What is "update" for?
5672 The "update" command is by far the most important command and is
5673 probably also the most used command.
5675 It has five purposes: (And many options.)
5677 To display the status of your working files.
5679 Though a plain "update" also displays the status, it does so after
5680 possibly altering your working directory. To see the status of your
5681 working files without changing anything, type:
5683 cvs -n update {optional list of files}
5685 To merge changes made by others to the branch you are working on
5686 into your working files.
5688 Each working directory is attached to a branch, usually the Main
5689 branch. To merge changes made on your working branch since your last
5690 checkout, update or commit, type:
5692 cvs update {optional list of files}
5694 To merge changes made on another branch into the branch you are
5695 working on (your "working branch").
5697 If you want to grab a whole branch, from the branch point, which is
5698 assumed to be on the Main Branch, to the end of the branch, you type:
5700 cvs update -j <branch_tag> {optional files}
5702 If you want to grab the changes made between two tags or revisions,
5705 cvs update -j <tag1> -j <tag2> {optional files}
5707 (If you are working with a single file, the Tags could also be
5708 revisions numbers. Unless you take great care to match revision
5709 numbers across different files (a waste of time given the way Tags
5710 work), using revision numbers in place of the Tags for multiple files
5711 would be meaningless.)
5713 To move your working directory to another branch.
5715 A working directory is presumed to be attached to (or working on) a
5716 particular branch, usually the Main branch. To alter what CVS believes
5717 to be your working branch, you "move" to that branch.
5719 To move to a tagged branch, type:
5721 cvs update -r <branch_tag> {optional files}
5723 To move to the Main Branch, type:
5725 cvs update -A {optional files}
5727 If you have modified files in your working directory, this is not a
5728 clean move. CVS will attempt to merge the changes necessary to make it
5729 look like you made the same changes to the new branch as you made in
5730 the old one. But if you do this twice without resolving the merge
5731 conflicts each time, you can lose work.
5733 To retrieve old revisions of files.
5735 This option is similar to 4 above but you are not restricted to using
5736 a <branch_tag>. You may specify any revision or <tag> with '-r' and
5737 get the specified revision or the tagged revision:
5739 cvs update -r <tag/rev> {optional files}
5741 Or you may specify any date with '-D':
5743 cvs update -D <date> {optional files}
5745 The '-p' option sends the revisions to standard output (normally your
5746 terminal) rather than setting the "sticky" tag and changing the files.
5748 Last modified: _6/13/1997_
5750 2. What do 'U', 'M' and 'C' mean when I type "update"? Are they different
5751 for "cvs -n update"?
5753 "cvs update" merges changes made to the Repository, since your last
5754 "checkout", "update" or "commit", into your working files. You can
5755 think of it as changing your BASE revision.
5757 "cvs update" prints lines beginning with:
5759 'U' after replacing your unmodified file with a different
5760 revision from the Repository.
5762 'M' for two different reasons:
5764 for files you have modified that have not changed in the Repository.
5766 after a merge, if it detected no conflicts.
5768 'C' after a merge, if it detected conflicts. See 2D.7 and 3P.6 for
5769 more info on conflict resolution and "sticky conflicts."
5771 "cvs -n update" shows what it *would* do, rather than doing it. Or,
5772 another way of looking at it, "cvs -n update" displays the
5773 relationship between your current BASE revisions (identified in your
5774 ./CVS/Entries file) and the HEAD revisions (the latest revisions in
5777 "cvs -n update" prints lines beginning with:
5779 'U' for files you have not modified that have changed in the
5782 'M' for files you have modified that have not changed in the
5785 'C' for files you have modified that have also been changed in the
5788 See 4C.6 for what the letters mean when merging in from another
5789 branch. The output is almost the same for a normal update if you
5790 consider the Repository as the branch and your working directory as
5793 Last modified: _6/13/1997_
5795 3. What's the difference between "update" and "checkout"?
5799 Last modified: _6/13/1997_
5801 4. Why don't I get new files when I execute "update"?
5803 There are six reasons for nothing to happen during an "update":
5805 Nothing on your branch changed in the Repository.
5807 If no one has committed anything to the branch you are working on
5808 (normally the Main branch) since the last time you executed
5809 "checkout", "update" or "commit", nothing will happen.
5811 It's like shouting "xyzzy" or "plugh" in the wrong room.
5813 You have a "sticky" non-branch <tag> or <date> attached to the
5814 working files you are trying to "update".
5816 At some time in the past you checked out or updated your directory
5817 with the "-r <tag>" or "-D <date>" option. Until you do it again with
5818 a different tag or date, or go back to the Main Branch with "update
5819 -A", you will never again see any updates.
5821 The ./CVS/Entries.Static file exists and you are expecting a new
5824 If your ./CVS administrative directory contains a file named
5825 Entries.Static, no files will be checked out that aren't already in
5826 the Entries or Entries.Static file.
5828 You forgot to use the '-d' option and are looking for new
5831 If you execute "update" without the '-d' option, it will not create
5832 new directories that have been added to the Repository.
5834 You typed "update" instead of "cvs update".
5836 On most Unix systems, your disk caches are now furiously being flushed
5837 by multiple update daemons, destroying performance and proving to
5838 management that you need more CPU power. :-)
5840 On HP systems you might be asked what package you want to install from
5841 the "update server".
5843 Someone removed (using "admin -o") your BASE revision (the revision
5844 CVS thought you had in your working directory), then committed a
5845 "replacement". CVS is now confused because the revision in the
5846 Repository matches your BASE revision when the files themselves don't
5849 Last modified: _6/13/1997_
5851 5. Why does "update" say 'M' both for plain modified files and for
5852 successful (i.e. conflict-free) merges? Aren't they different?
5854 A design choice. Yes, they are different internally, but that
5855 shouldn't matter. Your files are in the same condition after the
5856 "update" as they were before -- a "diff" will display only your
5857 modifications. And you are expected to continue onward with parts two
5858 and three of the normal development cycle: "emacs" (a synonym for
5859 "edit" in most of the civilized world) and "commit".
5861 Last modified: _6/13/1997_
5863 6. What's a "sticky conflict"? How does it know a conflict occurred?
5865 When a "cvs update" (or an "update -j") creates a conflict, it prints
5866 a 'C' and stores the timestamp of the file after the merge in a
5867 special field in the ./CVS/Entries file.
5869 This conflict indication implies that the merge command altered your
5870 working file to contain conflict markers surrounding the overlapping
5871 code segments. For example, say that
5873 - Two developers acquire revision 1.2 of <file> via "checkout" or
5876 - Developer A changes line 1 from "9999" to "5555", then commits the
5877 file, creating revision 1.3.
5879 - Developer B changes line 1 from "9999" to "7777", then tries to
5880 commit the file, but is blocked because the file is not up to date.
5881 Developer B then runs "update" and sees the conflict marker 'C'. The
5882 beginning of the file would look like this:
5884 <<<<<<< <file> The working <file> in question.
5885 7777 Change made to the working <file>.
5887 5555 Change made in the first commit (1.3)
5888 >>>>>>> 1.3 The revision created by the first commit.
5890 The conflict is "sticky", which means that until the conflict is
5891 cleared, the "update" command will continue to display the file's
5892 status as 'C' and the "status" command will show the file's status as
5893 "Unresolved Conflict".
5895 Until the conflict is cleared, "commit" is blocked for this file.
5897 The sticky conflict indicator can be cleared by:
5899 Resolving the conflict by editing the file. Two things must happen
5900 before the conflict is considered resolved:
5902 The timestamp of the file must change. *and* The file must contain no
5903 conflict markers. (The string searched for in the file is the regexp:
5906 After clearing the sticky conflict indicator, you may then commit the
5909 Removing the file and running "update". This throws away the local
5910 changes and accepts the latest committed file on this branch. No
5913 Forcing the commit to happen by using "commit -f". This is probably
5914 a mistake since there are few lines of real text that begin with
5917 Last modified: _6/13/1997_
5919 7. Is there a feature to tell me what I have changed, added and removed
5920 without changing anything?
5922 The command "cvs -n update" will do exactly that.
5924 Last modified: _6/13/1997_
5926 8. Why were all my files deleted when I executed "update"?
5928 You probably executed "update -r <tag>" some time ago, then removed
5929 <tag> from the Repository files. "update -r <tag>" will delete a file
5930 that doesn't contain <tag>.
5932 A way to fix this is to "cd" into your working directory and type:
5936 If you don't want the latest revisions on the Main (or Vendor) Branch,
5937 then decide what Tag (normal or branch) you want and type:
5939 cvs update -r <the_tag_you_want>
5941 Another way to make a file disappear is to execute "update -D <date>"
5942 where <date> is before the date stamped onto the first revision in the
5945 Last modified: _6/13/1997_
5947 Category: /Past__Future_/
5951 Category: /Past__Future_/Bugs_and_Patches/
5953 " + Bugs and Patches"
5955 1. Why can't CVS handle deletion of directories?
5957 An oversight, probably. [[Fixed in a future release?]]
5959 Last modified: _6/13/1997_
5961 2. Why can't CVS handle the moving of sources from one place in the
5963 directory hierarchy to another?
5965 A "renaming database" has been proposed to track the history of
5966 pathname changes in the Repository. A general solution is a difficult
5969 Last modified: _6/13/1997_
5971 3. When I typed "cvs update -D <date>", why did it check out all
5973 sorts of ancient files from the Attic? Shouldn't it just create the
5974 set of files and revisions that existed at that date?
5976 This seems to be a bug, but is really the lack of any obvious place to
5977 store the date when a file is "removed".
5979 There are four ranges of dates that CVS has to deal with when trying
5980 to determine what revision was available on <date>:
5982 Dates before the earliest revision in the file.
5984 Dates between any two revisions in the file.
5986 Dates between the latest revision in the file and the date when the
5987 file was moved to the Attic by "commit".
5989 Dates after moving the file to the Attic.
5991 Since the date when a file is moved to the Attic is not stored
5992 anywhere, CVS can't tell the difference between #3 and #4. To avoid
5993 not producing a file that should exist in case #3, it produces
5994 extraneous files in case #4.
5996 For the above reason, if you have removed files in the Attic, it is
5997 better to use "-r <tag>, or even "-r HEAD" than to use a date spec.
5999 If you must use "-D <date>", then you should either archive and delete
6000 Attic files (losing some past history) or construct your Makefiles to
6001 work with an explicit list of files and let the old source files stay
6002 in the working directory. The contents of the revision-controlled
6003 Makefile can then be considered to contain deletion "information".
6005 Last modified: _6/13/1997_
6007 4. When I typed "cvs update -D <date>" in my branch, why did it screw up
6010 Currently, the internal routine ("version_ts") that looks up info
6011 about a file, overrides both the tag and date if *either* the tag or
6012 date is specified on the command line. If only the date is specified,
6013 it should not override a branch tag, but it does.
6015 In CVS 1.3, the documented "-D <branch_tag>:<date>" syntax only works
6016 with the Main Branch and the Vendor Branch.
6018 [[Is this fixed in CVS 1.4? This is one item I didn't check.]]
6020 Last modified: _6/13/1997_
6022 5. When I executed "checkout" into an existing directory I got "No such
6023 file or directory" errors. Why?
6025 Though the man page says that "checkout" turns into an "update -d" in
6026 directories that already exist, it is referring to directories that
6027 already exist *and* were created by CVS.
6029 When you try to run "checkout" on top of an existing directory
6030 structure, some of which wasn't created by CVS, it will handle
6031 directories and non-CVS files within directories already under CVS,
6032 but it will display the above error on non-CVS files within non-CVS
6035 Last modified: _6/13/1997_
6037 6. Why does "update" send all output to the terminal after 26 files have
6040 CVS uses the "tmpnam()" function to generate temporary file names. The
6041 ANSI standard for the "tmpnam()" function says:
6043 "The tmpnam function generates a different string each time it is
6044 called, up to TMP_MAX times. If it is called more than TMP_MAX times,
6045 the behavior is implementation defined."
6047 Later it says that the value of "TMP_MAX shall be at least 25."
6049 On some platforms, the above specification is taken literally by
6050 turning "at least 25" into "exactly 26" and by doing something foolish
6051 (i.e. "implementation defined") after that. Some systems return the
6052 same name repeatedly, which causes one form of trouble. Others return
6053 NULL or garbage, which causes a different form of trouble.
6055 The broken systems appear to be cycling a single character through the
6056 alphabet. SunOS cycles 3 characters through the alphabet, so it won't
6057 cause trouble until 26 cubed or 17576 calls to "tmpnam()".
6059 Since CVS doesn't depend on the exact format of the tmp files, the
6060 workaround is to provide a "tmpnam()" that doesn't have a limit on the
6061 number of calls to it.
6063 Last modified: _6/13/1997_
6065 7. Why does the merge occasionally resurrect lines of code?
6067 The diff3 program provided by GNU diff version 1.15 has a bug that
6068 occasionally causes text to come back from the dead.
6070 This is an old problem which you can avoid by upgrading to the latest
6071 GNU "diffutils" package. If you were using GNU diff version 1.15 and
6072 plan to upgrade to the latest GNU diff program, see the next question.
6074 Last modified: _6/13/1997_
6076 8. Why does the merge fail when my "rcsmerge" program is configured to use
6077 GNU diff version 2.1 or later?
6079 A change in the overlap format was introduced in GNU diff3 between
6080 versions 2.0 and 2.1 that causes RCS versions before 5.6.0.1 to fail
6083 To get consistent rcsmerge behavior, you have four choices:
6085 Go back to using GNU diff 1.15 or 2.0 with RCS versions 5.5 or 5.6.
6086 If you want to use GNU diff 2.1 or later, you'll have to pick one of
6087 the other three choices in this list.
6089 Grab RCS version 5.6.0.1 from an FSF archive and set the DIFF3_A
6090 macro to '1' as it tells you to in the Makefile:
6094 Patch the RCS 5.6 source. Change line 84 in "merger.c" from:
6096 DIFF3, "-am", "-L", label[0], "-L", label[1], to DIFF3, "-amE", "-L",
6097 label[0], "-L", "", "-L", label[1],
6099 Wait both for RCS version 5.7 to be released and for a new version
6100 of CVS that can deal with it.
6102 Last modified: _6/13/1997_
6104 Category: /Past__Future_/Contributors/
6110 Brian Berliner <berliner@sun.com> converted a collection of scripts
6111 written by Dick Grune <dick@cs.vu.nl> into a C program, then added all
6112 sorts of features. He continues to maintain CVS.
6114 Jeff Polk <polk@bsdi.com> wrote much of the code added between
6115 revisions 1.2 and 1.3. Many others were involved at some level.
6117 david d zuhn <zoo@armadillo.com> fixed a number of bugs, added some of
6118 the new features, reworked the whole thing to be more portable, and
6119 provided much of the energy to push CVS 1.4 out the door.
6121 Jim Kingdon implemented CVS 1.5's remote repository access features,
6122 fixed many bugs, and managed the release of version 1.5.
6124 Take a look at the README and the ChangeLog files in the CVS sources
6125 for more contributors.
6127 Last modified: _6/13/1997_
6129 2. You didn't write all of this FAQ, did you?
6131 In the original hunt for questions to answer (performed in Jan/Feb,
6132 1993), I polled hundreds of people and I rephrased all sorts of text
6133 found on the net. Between 2/93 and 10/93, I released about 20
6134 versions, with corrections and additions from the info-cvs mailing
6135 list and private correspondence.
6137 Between 10/93 and 10/94 I extracted frequently asked questions from
6138 the 1200 mail messages to the info-cvs mailing list, turned them into
6139 focused questions and tried to answer them.
6141 93/02/?? ~4000 lines 93/06/?? ~5000 lines 93/10/23 7839 lines 278K
6142 94/10/29 9856 lines 360K 95/05/09 9981 lines 365K
6144 Because there are so many posers of questions, I will list only those
6145 who contribute answers or help significantly with the content and
6146 structure of this document.
6148 If I used someone else's text verbatim, I mentioned it in the given
6149 answer. The people whose email postings have added to this document or
6150 who have added to my understanding are:
6152 Brian Berliner <berliner@sun.com>, CVS maintainer. Paul Eggert
6153 <eggert@twinsun.com>, RCS maintainer.
6155 Gray Watson <gray@antaire.com> Per Cederqvist <ceder@signum.se> Pete
6156 Clark <pclark@is.com>
6158 all of whom have sent me copies of their tutorials and local CVS
6161 Additional contributors, who have sent me ideas, text, corrections and
6162 support include (in alphabetical order):
6164 Per Abrahamsen <amanda@iesd.auc.dk> Donald Amby
6165 <amby@mixcom.mixcom.com> Mark D Baushke <mdb@cisco.com> Jim Blandy
6166 <jimb@cyclic.com> Tom Cunningham <tomc@bouwsma,sps.mot.com> Graydon
6167 Dodson <grdodson@lexmark.com> Joe Drumgoole
6168 <joed@splatter.demon.co.uk> Don Dwiggins <dwig@markv.com> Bryant
6169 Eastham <bryant@ced.utah.edu> Dan Franklin <dan@diamond.bbn.com>
6170 Michael Ganzberger <ganzbergermd@ES.net> Steve Harris
6171 <vsh%etnibsd@uunet.uu.net> Erik van Linstee
6172 <linstee@dutecaj.et.tudelft.nl> Jeffrey M Loomis <jml@world.std.com>
6173 Barry Margolin <barmar@near.net> Mark K. Mellis <mkm@ncd.com> Chris
6174 Moore <Chris.Moore@src.bae.co.uk> Gary Oberbrunner <garyo@avs.com>
6175 Steve Turner <stevet@carrier.sps.mot.com> Dave Wolfe
6176 <dwolfe@pffft.sps.mot.com> Dale Woolridge <dwoolridge@cid.aes.doe.ca>
6178 Please send corrections. If I forgot you, remind me and I'll add your
6181 Last modified: _6/13/1997_
6183 Category: /Past__Future_/Development/
6187 1. Where do I send bug reports?
6189 First make sure it is a bug. Talk to your friends, coworkers and
6190 anyone you know who uses CVS. Search this FAQ for related issues. Then
6191 test it carefully. Try out variations to narrow down the problem. Make
6192 sure it is repeatable. Look for workarounds so you can report them.
6194 If you are still sure it's a bug and you tried to fix it, skip to the
6195 next question. Otherwise, send a message to the info-cvs mailing list
6196 containing one of the following:
6198 If you have a good repeatable case and you think you know what is
6199 going on, then describe the problem in detail. Include a workaround if
6202 If you have no idea what is going on, go ahead and send a question
6203 to the info-cvs mailing list. Include any information you have
6204 describing the symptoms.
6206 Last modified: _6/13/1997_
6208 2. Where do I send fixes and patches?
6210 First make sure the "fix" does something useful. Have someone review
6211 your fix. Spend a bit of one person's time in a detailed analysis of
6212 your vast idea before displaying a half-vast idea to hundreds of
6215 If you tried to fix it and the patch is small, include the patch in
6216 your message. Make sure the patch is based on the latest released
6219 If you tried to fix it and the patch is large, you should think about
6220 why it is so large. Did you add a generally useful feature, or did it
6223 If you still believe it is solid, produce a patch file using the CVS
6224 commands "patch" or "diff -c". [[You *are* keeping CVS under CVS,
6225 right?]] The patch should be based on the latest released version of
6226 CVS. Then use the "cvsbug" program (provided with the CVS sources) to
6227 send it to the CVS maintainers. A self-contained patch that provides a
6228 single useful feature or correction might show up independently in the
6229 patches directory of the FTP archive.
6231 If careful testing reveals an RCS bug rather than a CVS bug, you can
6232 send bug reports to: rcs-bugs@cs.purdue.edu
6234 Last modified: _6/13/1997_
6236 3. Where do I send ideas for future development?
6238 If you have a bright idea, discuss it on the info-cvs mailing list. If
6239 you have the time to implement something you can test, send the diffs
6240 along too as described above.
6242 Last modified: _6/13/1997_
6244 4. What plans are there for new features?
6248 A "rename" or "per-directory" database has been bandied about on
6249 the net for years. Many of the goals of the rename database have
6250 been achieved by the so-called "death support" in recent versions of
6251 CVS (such as 1.9). For more information on what may remain to be
6252 done, see item #189 in the TODO file of a development version of CVS.
6254 CVS version 1.5 supports remote repository access, but Paul
6255 Kunz has produced another version
6256 (rCVS) that also runs remotely. Note that as far as I know there
6257 are no advantages to rCVS over the remote CVS in CVS 1.5 and later,
6258 and the rCVS user community has migrated to remote CVS.
6259 rCVS is *not* a multisite CVS (see item #186 in TODO for more on
6260 multisite). For more on rCVS, see
6262 ftp://ftp.slac.stanford.edu/software/rcvs
6266 Last modified: _9/6/1997_
6268 5. I have some time and I'd like to help. What can I do for you?
6271 You can review this document, correct errors and fill in any of
6272 the incomplete sections.
6274 You can write scripts or CVS add-ons and make them available by
6277 You could work on the regression test suite (src/sanity.sh in the
6278 CVS source distribution).
6280 You can write specs for new features, fix bugs, review the
6281 documentation or . . .
6283 For more information, see the files HACKING and DEVEL-CVS in the
6284 CVS source distribution or
6285 http://www.cyclic.com/cyclic-pages/cvsdev.html
6289 Last modified: _9/6/1997_
6291 Category: /Past__Future_/Professional_Support/
6293 " + Professional Support"
6295 1. Doesn't Cygnus support CVS?
6300 Cygnus is a company that supports free software such as the GCC
6301 compiler. They have never sold support for CVS, however. They
6302 do use CVS internally and have contributed much code to CVS over
6303 the years (for which CVS users should be grateful).
6307 Last modified: _9/6/1997_
6309 2. What is Cyclic Software doing with CVS?
6312 Cyclic Software exists to provide support for CVS. For details such
6313 as prices and what this covers, see http://www.cyclic.com or ask
6318 Last modified: _9/6/1997_
6320 Category: /User_Tasks_/
6324 Category: /User_Tasks_/Common_User_Tasks/
6326 " + Common User Tasks"
6328 1. What is the absolute minimum I have to do to edit a file?
6330 Tell your Repository Administrator to create a module covering the
6331 directory or files you care about. You will be told that your module
6332 name is <module>. Then type:
6334 cvs checkout <module>
6336 emacs <file> # Isn't Emacs a synonym for edit?
6339 If you don't use modules (in my opinion, a mistake), you can check out
6340 a directory by substituting its relative path within the Repository
6341 for <module> in the example above.
6343 To work on a single file, you'll have to change "cd <module>" to "cd
6344 `dirname <module>`".
6346 Last modified: _6/13/1997_
6348 2. If I edit multiple files, must I type "commit" for each one?
6350 No. You can commit a list of files and directories, including relative
6351 paths into multiple directories. You can also commit every modified
6352 file in the current directory or in all directories and subdirectories
6353 from your current directory downward. See 3D.2.
6355 Last modified: _6/13/1997_
6357 3. How do I get rid of the <module> directory that "checkout" created?
6359 Change your directory to be the same as when you executed the
6360 "checkout" command that created <module>.
6362 If you want to get rid of the CVS control information, but leave the
6363 files and directories, type:
6365 cvs release <module>
6367 If you want to obliterate the entire directory, type:
6369 cvs release -d <module>
6371 ("release -d" searches through the output of "cvs -n update" and
6372 refuses to continue if the "update" command finds any modified files
6373 or non-ignored foreign files. Foreign directories too.)
6375 If you don't care about keeping "history", or checking for modified
6376 and foreign files, you can just remove the whole directory. That's "rm
6377 -rf <module>" under Unix.
6379 Last modified: _6/13/1997_
6381 4. How do I find out what has changed since my last update?
6383 There are many ways to answer this.
6385 To find out what you've changed in your current working directory
6386 since your last checkout, update or commit, type:
6390 To find out what other people have added (to your branch) since you
6391 last checked out or updated, type:
6393 cvs diff -r BASE -r HEAD
6395 To look at a revision history containing the comments for all changes,
6396 you can use the "log" command.
6398 You can also use "history" to trace a wide variety of events.
6400 Last modified: _6/13/1997_
6402 5. I just created a new file. How do I add it to the Repository?
6404 The "update" command will mark files CVS doesn't know about in your
6405 working directory with a '?' indicator.
6409 To add <file> to the Repository, type:
6414 See 3A.[2-5] and 4C.8 for branch and merge considerations.
6416 Last modified: _6/13/1997_
6418 6. How do I merge changes made by others into my working directory?
6420 If you are asking about other branches, see Section 4C on "Branching".
6421 You will have to use the "update -j" command.
6423 Retrieving changes made to the Repository on the *same* branch you are
6424 working on is the main purpose of the "update" command. The "update"
6425 command tries to merge work committed to the Repository by others
6426 since you last executed "checkout", "update" or "commit" into your
6429 For a single file, there are six possible results when you type the
6432 If the file is lying in your working directory, but is not under
6433 CVS, it will do nothing but print:
6437 If neither you nor anyone else has committed changes to <file>,
6438 since your last "checkout", "update" or "commit", "update" will print
6439 nothing and do nothing.
6441 If you have made no changes to a working file, but you or others
6442 have committed changes to the Repository since your last "checkout",
6443 "update" or "commit" of this working file, CVS will remove your
6444 working file and replace it with a copy of the latest revision of that
6445 file in the Repository. It will print:
6449 You might want to examine the changes (using the CVS "diff" command)
6450 to see if they mesh with your own in related files.
6452 If you have made changes to a working file, but no one has changed
6453 your BASE revision (the revision you retrieved from the Repository in
6454 your last "checkout", "update" or "commit"), "update" will print:
6458 Nothing changes. You were told that you have a modified file in your
6461 If you have made changes to your working file and you or others have
6462 committed changes to the Repository, but in different sections of the
6463 file, CVS will merge the changes stored in the Repository since your
6464 last "checkout", "update" or "commit" into your working file. "update"
6467 RCS file: /Repository/module/<file> retrieving revision 1.X retrieving
6468 revision 1.Y Merging differences between 1.X and 1.Y into <file> M
6471 If you execute "diff" before and after this step, you should see the
6472 same output, since both the base file and your working file changed in
6473 parallel. This is one of the few times the otherwise nonsensical
6474 phrase "same difference" means something.
6476 If both you and those who committed files (since your last checkout,
6477 update or commit) have made changes to the same section of a file, CVS
6478 will merge the changes into your file as in #5 above, but it will
6479 leave conflict indicators in the file. "update" will print:
6481 RCS file: /Repository/module/<file> retrieving revision 1.X retrieving
6482 revision 1.Y Merging differences between 1.X and 1.Y into <file>
6483 rcsmerge warning: overlaps during merge
6484 cvs update: conflicts found in <file>
6487 This is a "conflict". The file will contain markers surrounding the
6488 overlapping text. The 'C' conflict indicator is sticky -- subsequent
6489 "update" commands will continue to show a 'C' until you edit the file.
6491 You must examine the overlaps with care and resolve the problem by
6492 analyzing how to retain the features of both changes. See 2D.7 and
6493 3P.6 for more details on conflict resolution.
6495 Last modified: _6/13/1997_
6497 7. How do I label a set of revisions so I can retrieve them later?
6499 To "tag" the BASE revisions (the ones you last checked out, updated,
6500 or committed) you should "cd" to the head of the working directory you
6501 want to tag and type:
6505 It recursively walks through your working directory tagging the BASE
6506 revisions of all files.
6508 To "tag" the latest revision on the Main branch in the Repository, you
6509 can use the following from anywhere: (No "cd" is required -- it works
6510 directly on the Repository.)
6512 cvs rtag <tag> <module>
6514 Last modified: _6/13/1997_
6516 8. How do I checkout an old release of a module, directory or file?
6518 Module names and directories are simply ways to name sets of files.
6519 Once the names are determined, there are 6 ways to specify which
6520 revision of a particular file to check out:
6522 By tag or symbolic name, via the "-r <tag>" option.
6524 By date, via the "-D <date>" option.
6526 By branch tag (a type of tag with a magic format), via the "-r
6527 <branch_tag>" option.
6529 By date within a branch, via the "-r <branch_tag>:<date>" option.
6531 By an explicit branch revision number ("-r <rev>"), which refers to
6532 the latest revision on the branch. This isn't really an "old"
6533 revision, from the branch's perspective, but from the user's
6534 perspective the whole branch might have been abandoned in the past.
6536 An explicit revision number: "-r <rev>" Though this works, it is
6537 almost useless for more than one file.
6541 cvs checkout <option-specified-above> <module>
6544 Last modified: _6/13/1997_
6546 9. What do I have to remember to do periodically?
6548 You should execute "cvs -n update" fairly often to keep track of what
6549 you and others have changed. It won't change anything -- it will just
6552 Unless you are purposely delaying the inclusion of others' work, you
6553 should execute "update" once in a while and resolve the conflicts. It
6554 is not good to get too far out of sync with the rest of the developers
6555 working on your branch.
6557 It is assumed that your system administrators have arranged for editor
6558 backup and Unix temp files (#* and .#*) to be deleted after a few
6559 weeks. But you might want to look around for anything else that is
6560 ignored or hidden. Try "cvs -n update -I !" to see all the ignored
6563 If you are the Repository Administrator, see 4B.16 on Administrator
6566 Last modified: _6/13/1997_
6568 Category: /User_Tasks_/General_Questions/
6570 " + General Questions"
6572 1. How do I see what CVS is trying to do?
6574 The '-t' option on the main "cvs" command will display every external
6575 command (mostly RCS commands and file deletions) it executes. When
6576 combined with the '-n' option, which prevents the execution of any
6577 command that might modify a file, you can see what it will do before
6578 you let it fly. The '-t' option will *not* display every internal
6579 action, only calls to external programs.
6581 To see a harmless example, try typing:
6585 Some systems offer a "trace" or "truss" command that will display all
6586 system calls as they happen. This is a *very* low-level interface that
6587 does not normally follow the execution of external commands, but it
6590 The most complete answer is to read the source, compile it with the
6591 '-g' option and step through it under a debugger.
6593 Last modified: _6/13/1997_
6595 2. If I work with multiple modules, should I check them all out and commit
6596 them occasionally? Is it OK to leave modules checked out?
6598 The simple answers are "Yes."
6600 There is no reason to remove working directories, other than to save
6601 disk space. As long as you have committed the files you choose to make
6602 public, your working directory is just like any other directory.
6604 CVS doesn't care whether you leave modules checked out or not. The
6605 advantage of leaving them checked out is that you can quickly visit
6606 them to make and commit changes.
6608 Last modified: _6/13/1997_
6610 3. What is a "sticky" tag? What makes it sticky? How do I loosen it?
6612 When you execute "update -r <tag>", CVS remembers the <tag>. It has
6613 become "sticky" in the sense that until you change it or remove it,
6614 the tag is remembered and used in references to the file as if you had
6615 typed "-r <tag>" on the command line.
6617 It is most useful for a <branch_tag>, which is a sticky tag indicating
6618 what branch you are working on.
6620 A revision number ("-r <rev-number>") or date ("-D <date>") can also
6621 become sticky when they are specified on the command line.
6623 A sticky tag, revision or date remains until you specify another tag,
6624 revision or date the same way. The "update -A" command moves back to
6625 the Main branch, which has the side-effect of clearing all sticky
6626 items on the updated files.
6628 The "checkout" command creates sticky tags, revisions and dates the
6629 same way "update" does.
6631 Also, the '-k' option records a "sticky" keyword option that is used
6632 in further "updates until "update -A" is specified.
6634 Last modified: _6/13/1997_
6636 4. How do I get an old revision without updating the "sticky tag"?
6638 Use the '-p' option to "pipe" data to standard output. The command
6639 "update -p -r <tag/rev>" sends the selected revision to your standard
6640 output (usually the terminal, unless redirected). The '-p' affects no
6641 disk files, leaving a "sticky tag" unaltered and avoiding all other
6642 side-effects of a normal "update".
6644 If you want to save the result, you can redirect "stdout" to a file
6645 using your shell's redirection capability. In most shells the
6646 following command works:
6648 cvs update -p -r <tag/rev> filename > diskfile
6650 Last modified: _6/13/1997_
6652 5. What operations disregard sticky tags?
6654 The functions that routinely disregard sticky tags are:
6656 Those that work directly on the Repository or its administrative
6659 admin rtag log status remove history
6661 Those that take Tags or revisions as arguments and ignore everything
6662 else: (They also never *set* a sticky tag.)
6666 The "release" command itself ignores sticky tags, but it calls "cvs
6667 -n update" (which *does* pay attention to a sticky tag) to figure out
6668 what inconsistencies exist in the working directory. If no
6669 discrepancies exist between the files you originally checked out
6670 (possibly marked by a sticky tag) and what is there now, "release -d"
6671 will delete them all.
6673 The "tag" command works on the revision lying in the working
6674 directory however it got there. That the revision lying there might
6675 happen to have a sticky tag attached to it is not the "tag" command's
6678 The main function that *does* read and write sticky tags is the
6679 "update" command. You can avoid referring to or changing the sticky
6680 tag by using the '-p' option, which sends files to your terminal,
6681 touching nothing else.
6683 The "checkout" command sets sticky tags when checking out a new module
6684 and it acts like "update" when checking out a module into an existing
6687 The "diff" and "commit" commands use the sticky tags, unless
6688 overridden on the command line. They do not set sticky tags. Note that
6689 you can only "commit" to a file checked out with a sticky tag, if the
6690 tag identifies a branch.
6692 There are really two types of sticky tags, one attached to individual
6693 files (in the ./CVS/Entries file) and one attached to each directory
6694 (in the ./CVS/Tag file). They can differ.
6696 The "add" command registers the desire to add a new file. If the
6697 "directory tag" (./CVS/Tag) file exists at the time of the "add", the
6698 value stored in ./CVS/Tag becomes the "sticky tag" on the new file.
6699 The file doesn't exist in the Repository until you "commit" it, but
6700 the ./CVS/Entries file holds the sticky tag name from the time of the
6703 Last modified: _6/13/1997_
6705 6. Is there a way to avoid reverting my Emacs buffer after committing a
6706 file? Is there a "cvs-mode" for Emacs?
6710 Last modified: _6/13/1997_
6712 7. How does conflict resolution work? What *really* happens if two of us
6713 change the same file?
6715 While editing files, there is no conflict. You are working on separate
6716 copies of the file stored in the virtual "branch" represented by your
6717 working directories. After one of you commits a file, the other may
6718 not commit the same file until "update" has merged the earlier
6719 committed changes into the later working file.
6721 For example, say you both check out rev 1.2 of <file> and make change
6722 to your working files. Your coworker commits revision 1.3. When you
6723 try to commit your file, CVS says:
6725 cvs commit: Up-to-date check failed for `<file>'
6727 You must merge your coworker's changes into your working file by
6732 which will produce the output described in 2B.6.
6734 If a conflict occurs, the filename will be shown with a status of 'C'.
6735 After you resolve any overlaps caused by the merging process, you may
6736 then commit the file. See 3P.6 for info on "sticky conflicts".
6738 Even if you get a simple 'M', you should examine the differences
6739 before committing the file. A smooth, error-free text merge is still
6740 no indication that the file is in proper shape. Compile and test it at
6743 The answer to two obvious questions is "Yes".
6745 Yes, the first one who commits avoids the merge. Later developers have
6746 to merge the earlier changes into their working files before
6747 committing the merged result. Depending on how difficult the merge is
6748 and how important the contending projects are, the order of commits
6749 and updates might have to be carefully staged.
6751 And yes, between the time you execute "update" and "commit" (while you
6752 are fixing conflicts and testing the results) someone else may commit
6753 another revision of <file>. You will have to execute "update" again to
6754 merge the new work before committing. Most organizations don't have
6755 this problem. If you do, you might consider splitting the file. Or
6758 Last modified: _6/13/1997_
6760 8. How can I tell who has a module checked out?
6762 If you "checkout" module names (not relative pathnames) and you use
6763 the release command, the "history" command will display active
6764 checkouts, who has them and where they were checked out. It is
6765 advisory only; it can be circumvented by using the '-l' option on the
6768 Last modified: _6/13/1997_
6770 9. Where did the .#<file>.1.3 file in my working directory come from?
6772 It was created during an "update" when CVS merged changes from the
6773 Repository into your modified working file.
6775 It serves the same purpose as any "backup" file: saving your bacon
6776 often enough to be worth retaining. It is invaluable in recovering
6777 when things go wrong.
6779 Say Developers A (you) and B check out rev 1.3 of file <file>. You
6780 both make changes -- different changes. B commits first, so <file>,v
6781 in the Repository contains revisions up through 1.4.
6783 At this point, there are 5 (yes, five) versions of the file of
6786 Revision 1.3 (What you originally checked out.)
6788 Revision 1.4 (What you need from developer B.)
6790 Your old working file. (Before the update.)
6792 Your new working file. (After the merge caused by "update".)
6794 Revision 1.5 (Which you will commit shortly.)
6796 In the case where your working file was not modified, #1 and #3 will
6797 be the same, as will #2 and #4. In this degenerate case, there is no
6798 need to create #5. The following assumes that your working file was
6801 If the merge executed by the "update" caused no overlaps, and you
6802 commit the file immediately, #4 and #5 will be the same. But you can
6803 make arbitrary changes before committing, so the difference between #4
6804 and #5 might be more than just the correction of overlaps. In general,
6805 though, you don't need #4 after a commit.
6807 But #3 (which is the one saved as ".#<file>.1.3") holds all of your
6808 work, independent of B's work. It could represent a major effort that
6809 you couldn't afford to lose. If you don't save it somewhere, the merge
6810 makes #3 *disappear* under a potential blizzard of conflicts caused by
6811 overlapping changes.
6813 I have been saved a few times, and others I support have been saved
6814 hundreds of times, by the ability to "diff <original file> <original
6815 file with only my work added>", which can be done in the example above
6816 by the Unix shell command:
6818 cvs update -p -r 1.3 <file> | diff - .#<file>.1.3
6820 The assumption is that the ".#" files will be useful far beyond the
6821 "commit" point, but not forever. You are expected to run the "normal"
6822 Unix cleanup script from "cron", which removes "#*" and ".#*" files
6823 older than a some period chosen by your sysadmin, usually ranging from
6826 A question was raised about the need for #3 after #5 has been
6827 committed, under the assumption that you won't commit files until
6828 everything is exactly as you like them.
6830 This assumes perfect humans, which violates one of the Cardinal rules
6831 of Software Engineering: Never assume any form of discipline on the
6832 part of the users of software. If restrictions are not bound into the
6833 software, then you, the toolsmith, have to arrange a recovery path.
6835 In other words, I've seen every possible variety of screwup you can
6836 imagine in #5. There is no way to make assumptions about what "should"
6837 happen. I've seen #5 filled with zeros because of NFS failures, I've
6838 seen emacs core dumps that leave #5 in an unreasonable state, I've
6839 seen a foolish developer uppercase the whole file (with his "undo"
6840 size set low so he couldn't undo it) and decide that it would be less
6841 work to play with the uppercased file than to blow it away and start
6842 over. I've even seen committed files with conflict markers still in
6843 them, a sure sign of carelessness.
6845 There are all sorts of scenarios where having #3 is incredibly useful.
6846 You can move it back into place and try again.
6848 Last modified: _6/13/1997_
6850 10. What is this "ignore" business? What is it ignoring?
6852 The "update" and "import" commands use collections of Unix wildcards
6853 to skip over files and directories matching any of those patterns.
6855 You may add to the built-in ignore list by adding lines of
6856 whitespace-separated wildcards to the following places: (They are read
6859 In a file named "cvsignore" in $CVSROOT/CVSROOT.
6861 A Repository Administrator uses this to add site-specific files and
6862 patterns to the built-in ignore list.
6864 In a file named ".cvsignore" in your home directory.
6866 For user-specific files. For example, if you use "__" as your default
6867 junk file prefix, you can put "__*" in your .cvsignore file.
6869 People who play around exclusively in directory trees where the
6870 Makefiles are generated by "imake" or "configure" might want to put
6871 "Makefile" in their ignore list, since they are all generated and
6872 usually don't end up in the Repository.
6874 In the CVSIGNORE environment variable.
6876 For session-specific files.
6878 Via the '-I' option on "import" or "update" commands.
6880 For this-command-only files.
6882 In a file named ".cvsignore" within each directory.
6884 The contents of a ".cvsignore" file in each directory is temporarily
6885 added to the ignore list. This way you can ignore files that are
6886 peculiar to that directory, such as executables and other generated
6887 files without known wildcard patterns.
6889 In any of the places listed above, a single '!' character nulls out
6890 the ignore list. A Repository administrator can use this to override,
6891 rather than enhance, the built-in ignore list. A user can choose to
6892 override the system-wide ignore list. For example, if you place "! *.o
6893 *.a" in your .cvsignore file, only *.o *.a files, plus any files a
6894 local-directory .cvsignore file, are ignored.
6896 A variant of the ignore-file scheme is used internally during
6897 checkout. "Module names" found in the modules file (or on the
6898 "checkout" command line) that begin with a '!' are ignored during
6899 checkout. This is useful to permanently ignore (if the '!' path is in
6900 the modules file) or temporarily ignore (if the '!' path is on the
6901 command line) a sub-directory within a Repository hierarchy. For
6904 cvs checkout !gnu/emacs/tests gnu/emacs
6906 would checkout the module (or relative path within $CVSROOT) named
6907 "gnu/emacs", but ignore the "tests" directory within it.
6909 Last modified: _6/13/1997_
6911 11. Is there a way to set user-specific configuration options?
6913 User-specific configuration is available through use of a ".cvsrc"
6914 file in your home directory.
6916 CVS searches the first column of your ~/.cvsrc file for the cvs
6917 command name you invoked. If the command is found, the rest of the
6918 line is treated like a set of command line options, stuffed into the
6919 command line before the arguments you actually typed.
6921 For example, if you always want to see context diffs and you never
6922 want to have to delete a file before you run "cvs remove", then you
6923 should create a .cvsrc file containing the following:
6928 which will add the given options to every invocation of the given
6931 [[The rest of this will be removed someday, when CVS changes.]]
6933 I would like to stop here with a comment that the command name to use
6934 is the full, canonical one. But the command that the cvsrc support
6935 uses is the string you typed on the command line, not the proper
6936 command. So to get the full effect of the above example, you should
6937 also add all the alternate command names:
6944 There are two other limitations that will probably be fixed when CVS
6945 sprouts long option names:
6947 It only affects options made available on the command line.
6949 There is a limited number of short options. With long option names,
6950 there is no problem. You can have as many long options as you like,
6951 affecting anything that looks malleable.
6953 The existing command line options do not come in on/off pairs, so
6954 there is no easy way to override your ~/.cvsrc configuration for a
6955 single invocation of a command.
6957 Choosing a good set of long option pairs would fix this.
6959 Last modified: _6/13/1997_
6961 12. Is it safe to interrupt CVS using Control-C?
6963 It depends on what you mean by "safe". ("Ah," said Arthur, "this is
6964 obviously some strange usage of the word *safe* that I wasn't
6965 previously aware of." -- Hitchhiker's Guide to the Galaxy)
6967 You won't hurt the underlying RCS files and if you are executing a
6968 command that only *reads* data, you will have no cleanup to do.
6970 But you may have to hit Control-C repeatedly to stop it. CVS uses the
6971 Unix "system" routine which blocks signals in the CVS parent process.
6972 A single Control-C during "system" will only halt the child process,
6973 usually some form of RCS command.
6975 If you don't hit another Control-C while the CVS process has control,
6976 it is likely to continue onto the next task assuming that the earlier
6977 one did its job. It is not enough to hit two Control-C's. You might
6978 simply kill two child processes and not interrupt CVS at all.
6979 Depending on the speed of your processor, your terminal and your
6980 fingers, you might have to hit dozens of Control-C's to stop the damn
6983 Executing a CVS command, such as "commit" or "tag" that writes to the
6984 files is a different matter.
6986 Since CVS is not a full-fledged database, with what database people
6987 call "commit points", merely stopping the process will not back out
6988 the "transaction" and place you back in the starting blocks. CVS has
6989 no concept of an "atomic" transaction or of "backtracking", which
6990 means that a command can be half-executed.
6992 Hitting Control-C will usually leave lock files that you have to go
6993 clean up in the Repository.
6997 If you interrupt a multi-file "commit" in the middle of
6998 an RCS checkin, RCS will leave the file either fully
6999 checked-in or in its original state. But CVS might have
7000 been half-way through the list of files to commit. The
7001 directory or module will be inconsistent.
7003 To recover, you must remove the lock files, then decide
7004 whether you want to back out or finish the job.
7006 To back out, you'll have to apply the "admin -o"
7007 command, very carefully, to remove the newly committed
7008 revisions. This is usually a bad idea, but is
7009 occasionally necessary.
7011 To finish, you can simply retype the same commit command.
7012 CVS will figure out what files are still modified and
7013 commit them. It helps that RCS doesn't leave a file in an
7018 If you interrupt a multi-file "tag" command, you have a
7019 problem similar, but not equivalent, to interrupting a
7020 "commit". The RCS file will still be consistent, but
7021 unlike "commit", which only *adds* to the RCS file, "tag"
7022 can *move* a tag and it doesn't keep a history of what
7023 revision a tag used to be attached to.
7025 Normally, you have little choice but to re-execute the
7026 command and allow it to tag everything consistently.
7028 You might be able to recover by carefully re-applying the
7029 tags via the "cvs admin -N" command, but you'll still have
7030 to dig up from outside sources the information you use to
7031 determine what tag was on what revision in what file.
7032 the Repository, or by using the equivalent: "cvs admin".
7034 Halting a new "checkout" should cause no harm. If you don't want it,
7035 "release" (or rm -rf) it. If you do want it, re-execute the command. A
7036 repeated "checkout" from above a directory acts like a repeated
7037 "update -d" within it.
7039 Halting "update" half-way will give you an unpredictable collection of
7040 files and revisions. To continue, you can rerun the update and it
7041 should move you forward into in a known state. To back out, you'll
7042 have to examine the output from the first "update" command, take a
7043 look at each file that was modified and reconstruct the previous state
7044 by editing the ./CVS/Entries file and by using "cvs admin". Good Luck.
7046 Last modified: _6/13/1997_
7048 13. How do I turn off the "admin" command?
7050 In the current revision, you'd have to edit the source code.
7052 Last modified: _6/13/1997_
7054 14. How do I turn off the ability to disable history via "cvs -l"?
7056 In the current revision, you'd have to edit the source code.
7058 Last modified: _6/13/1997_
7060 15. How do I keep certain people from accessing certain directories?
7062 If you don't try to run CVS set[ug]id, you can use Unix groups and
7063 permissions to limit access to the Repository.
7065 If you only want to limit "commit" commands, you can write a program
7066 to put in the "commitinfo" file. In the "contrib" directory, there are
7067 a few scripts that might help you out.
7069 Last modified: _6/13/1997_
7071 Category: /User_Tasks_/Getting_Started/
7073 " + Getting Started"
7075 1. What is the first thing I have to know?
7077 Your organization has most likely assigned one or more persons to
7078 understand, baby-sit and administer the CVS programs and the data
7079 Repository. I call these persons Repository Administrators. They
7080 should have set up a Repository and "imported" files into it.
7082 If you don't believe anyone has this responsibility, or you are just
7083 testing CVS, then *you* are the Repository Administrator.
7085 If you are a normal user of CVS ask your Repository Administrator what
7086 module you should check out.
7090 If you *are* the Repository Administrator, you will want to read
7091 everything you can get your hands on, including this FAQ. Source
7092 control issues can be difficult, especially when you get to branches
7093 and release planning. Expect to feel stupid for a few days/weeks.
7095 No tool in the universe avoids the need for intelligent organization.
7096 In other words, there are all sorts of related issues you will
7097 probably have to learn. Don't expect to dive in without any
7098 preparation, stuff your 300 Megabytes of sources into CVS and expect
7099 to start working. If you don't prepare first, you will probably spend
7100 a few sleepless nights.
7102 Last modified: _6/13/1997_
7106 Wherever you have disk space. That's one of the advantages of CVS: you
7107 use the "checkout" command to copy files from the Repository to your
7108 working directory, which can be anywhere you have the space.
7110 Your local group might have conventions for where to work. Ask your
7113 Last modified: _6/13/1997_
7115 3. What does CVS use from my environment?
7117 You must set two environment variables. Some shells share these
7118 variables with local shell variables using a different syntax. You'll
7119 have to learn how your shell handles them.
7121 Variable Value (or action)
7122 --------- ---------------------
7123 CVSROOT Absolute pathname of the head of your Repository.
7125 PATH Normally set to a list of ':'-separated directory
7126 pathnames searched to find executables. You must
7127 make sure "cvs" is in one of the directories.
7129 If your CVS was built with the RCSBIN directory set
7130 to null (""), and you don't set the RCSBIN
7131 variable mentioned below, then the RCS commands
7132 also must be somewhere in your PATH.
7134 Optional variables: (Used if set, but ignored otherwise.)
7136 Variable Value (or action)
7137 --------- ---------------------
7138 CVSEDITOR The name of your favorite fast-start editor
7139 program. You'll be kicked into your editor to
7140 supply revision comments if you don't specify them
7141 via -m "Log message" on the command line.
7143 EDITOR Used if CVSEDITOR doesn't exist. If EDITOR
7144 doesn't exist, CVS uses a configured constant,
7147 CVSREAD Sets files to read-only on "checkout".
7149 RCSBIN Changes where CVS finds the RCS commands.
7151 CVSIGNORE Adds to the ignore list. See Section 2D.
7153 Other variables used by CVS that are normally set upon login:
7155 Variable Value (or action)
7156 --------- ---------------------
7157 LOGNAME Used to find the real user name.
7159 USER Used to find the real user name if no LOGNAME.
7161 HOME Used to determine your home directory, if set.
7162 Otherwise LOGNAME/USER/getuid() are used to find
7163 your home directory from the passwd file.
7165 TMPDIR Used during import. It might also be used if your
7166 platform's version of mktemp(3) is unusual, or
7167 you have changed the source to use tmpnam(3).
7169 Last modified: _6/13/1997_
7171 4. OK, I've been told that CVS is set up, my module is named "ralph" and I
7172 have to start editing. What do I type?
7174 cd <where you have some space to work>
7180 Last modified: _6/13/1997_
7182 5. I have been using RCS for a while. Can I convert to CVS without losing
7183 my revision history? How about converting from SCCS?
7185 If you are asking such questions, you are not a mere user of CVS, but
7186 one of its Administrators! You should take a look at Section 4A,
7187 "Installing CVS" and Section 4B, "Setting up and Managing the
7190 Last modified: _6/13/1997_
7192 Category: /User_Tasks_/Less_Common_User_Tas/
7194 " + Less Common User Tasks"
7196 1. Can I create non-CVS sub-directories in my working directory?
7198 Yes. Unless the directory exists in the Repository, "update" will skip
7199 over them and print a '?' the way it does for files you forgot to add.
7200 You can avoid seeing the '?' by adding the name of the foreign
7201 directory to the ./.cvsignore file, just ask you can do with files.
7203 If you explicitly mention a foreign directory on the "update" command
7204 line, it will traverse the directory and waste a bit of time, but if
7205 any directory or sub-directory lacks the ./CVS administrative
7206 directory, CVS will print an error and abort.
7208 Last modified: _6/13/1997_
7210 2. How do I add new sub-directories to the Repository?
7212 The "add" command will work on directories. You type:
7219 Directory /Repos/<dir> added to the repository
7221 and will create both a matching directory in the Repository and a
7222 ./CVS administrative directory within the local <dir> directory.
7224 Last modified: _6/13/1997_
7226 3. How do I remove a file I don't need?
7228 (See the questions in Section 4B on removing files from the
7236 CVS registers the file for removal. To complete the removal, you must
7241 CVS moves the file to the Attic associated with your working
7242 directory. Each directory in the Repository stores its deleted files
7243 in an Attic sub-directory. A normal "checkout" doesn't look in the
7244 Attic, but if you specify a tag, a date or a revision, the "checkout"
7245 (or "update") command will retrieve files from the Attic with that
7246 tag, date or revision.
7248 Last modified: _6/13/1997_
7250 4. How do I rename a file?
7252 CVS does not offer a way to rename a file in a way that CVS can track
7253 later. See Section 4B for more information.
7255 Here is the best (to some, the only acceptable) way to get the effect
7256 of renaming, while preserving the change log:
7258 Copy the RCS (",v") file directly in the Repository.
7260 cp $CVSROOT/<odir>/<ofile>,v $CVSROOT/<ndir>/<nfile>,v
7262 By duplicating the file, you will preserve the change history and the
7263 ability to retrieve earlier revisions of the old file via the "-r
7264 <tag/rev>" or "-D <date>" options to "checkout" and "update".
7266 Remove the old file using CVS.
7268 cd <working-dir>/<odir> rm <ofile>
7272 This will move the <ofile> to the Attic associated with <odir>.
7274 Retrieve <nfile> and remove all the Tags from it.
7276 By stripping off all the old Tags, "checkout -r" and "update -r" won't
7277 retrieve revisions Tagged before the renaming.
7279 cd <working-dir>/<ndir>
7281 cvs log <nfile> # Save the list of Tags
7282 cvs tag -d <tag1> <nfile>
7283 cvs tag -d <tag2> <nfile>
7286 This technique can be used to rename files within one directory or
7287 across different directories. You can apply this idea to directories
7288 too, as long as you apply the above to each file and don't delete the
7291 Of course, you have to change your build system (e.g. Makefile) in
7292 your <working-dir> to know about the name change.
7294 Warning: Stripping the old tags from the copied file will allow "-r
7295 <tag>" to do the right thing, but you will still have problems with
7296 "-D <date>" because there is no place to store the "deletion time".
7297 See 5B.3 for more details.
7299 Last modified: _6/13/1997_
7301 5. How do I make sure that all the files and directories in my working
7302 directory are really in the Repository?
7304 A "cvs update", or "cvs -n update" (which won't modify your working
7305 directory) will display foreign elements, which have no counterpart in
7306 the Repository, preceded by a '?'. To register foreign directories,
7307 you can use "cvs add". To register foreign files, you can use "cvs
7308 add" followed by "cvs commit".
7310 You could also checkout your module, or the Repository directory
7311 associated with your working directory, a second time into another
7312 work area and compare it to your working directory using the (non-CVS)
7315 By default many patterns of files are ignored. If you create a file
7316 named "core" or a file ending in ".o", it is usually ignored. If you
7317 really want to see all the files that aren't in the Repository, you
7318 can use a special "ignore" pattern to say "ignore no files". Try
7319 executing: (You may have to quote or backwhack (i.e. precede by '\')
7320 the '!' in your shell.)
7324 The above command will display not only the normal modified, update
7325 and conflict indicators ('M', 'U', and 'C' respectively) on files
7326 within the Repository, but it will also display each file not in the
7327 Repository preceded by a '?' character.
7329 The '-n' option will not allow "update" to alter your working
7332 Last modified: _6/13/1997_
7334 6. How do I create a branch?
7336 Type this in your working directory:
7338 cvs tag -b <branch_tag>
7340 and you will create a branch. No files have real branches in them yet,
7341 but if you move onto the branch by typing:
7343 cvs update -r <branch_tag>
7345 and commit a file in the normal way:
7349 then a branch will be created in the underlying <file>,v file and the
7350 new revision of <file> will appear only on that branch.
7352 See Section 4C, on Branching.
7354 Last modified: _6/13/1997_
7356 7. How do I modify the modules file? How about the other files in the
7357 CVSROOT administrative area?
7359 A module named "modules" has been provided in the default modules
7360 file, so you can type:
7362 cvs checkout modules
7365 Another module named CVSROOT has been provided in the default modules
7366 file, covering all the administrative files. Type:
7368 cvs checkout CVSROOT
7371 Then you can edit your files, followed by:
7375 If you start with the provided template for the "modules" file, the
7376 CVSROOT and the "modules" module will have the "mkmodules" program as
7377 a "commit helper". After a file is committed to such a module,
7378 "mkmodules" will convert a number of standard files (See 4B.2) in the
7379 CVSROOT directory inside the Repository into a form that is usable by
7382 Last modified: _6/13/1997_
7384 8. How do I split a file into pieces, retaining revision histories?
7386 If you and a coworker find yourselves repeatedly committing the same
7387 file, but never for changes in the same area of the file, you might
7388 want to split the file into two or more pieces. If you are both
7389 changing the same section of code, splitting the file is of no use.
7390 You should talk to each other instead.
7392 If you decide to split the file, here's a suggestion. In many ways, it
7393 is similar to multiple "renamings" as described in 2C.4 above.
7395 Say you want to split , which already in the Repository, into three
7398 Copy the RCS (",v") files directly in the Repository, creating the
7399 new files, then bring readable copies of the new files into the
7400 working directory via "update".
7402 cp $CVSROOT//,v $CVSROOT//,v cp $CVSROOT//,v $CVSROOT//,v
7405 Then remove all the from the new files, either using:
7407 cvs log # Save the list of
7412 (eivind@freebsd.org) or using the following little script to
7413 autmatically remove the tags directly from the repository files:
7418 TAGS=`rlog $file | awk '/^symbolic names:/,/^keyword subst/' | awk 'BEG
7419 IN {FS=":"} /^\t/ {print $1}'`
7420 echo The tags in $file are
7422 echo Is it OK to remove these?
7424 if [ "$confirm" = "y" -o "$confirm" = "yes" ]
7428 echo Removing $file:$tag
7434 Edit each file until it has the data you want in it. This is a
7435 hand-editing job, not something CVS can handle. Then commit all the
7438 [From experience, I'd suggest making sure that only one copy of each
7439 line of code exists among the three files, except for "include"
7440 statements, which must be duplicated. And make sure the code
7446 As in the "rename" case, by duplicating the files, you'll preserve the
7447 change history and the ability to retrieve earlier revisions.
7449 Of course, you have to alter your build system (e.g. Makefiles) to
7450 take the new names and the change in contents into account.
7452 Last modified: _3/11/1998_
7454 Category: /What_is_CVS_/
7458 Category: /What_is_CVS_/How_does_CVS_differ_/
7460 " + How does CVS differ from other, similar software?"
7462 1. How does CVS differ from RCS?
7464 CVS uses RCS to do much of its work and absolutely all the work of
7465 changing the underlying RCS files in the Repository.
7467 RCS comprises a set of programs designed to keep track of changes to
7468 individual files. Of course, it also allows you to refer to multiple
7469 files on the command line, but they are handled by iterating over
7470 individual files. There is no pretense of coordinated interaction
7471 among groups of files.
7473 CVS's main intent is to provide a set of grouping functions that allow
7474 you to treat a collection of RCS files as a single object. Of course,
7475 CVS also has to do a lot of iteration, but it tries its best to hide
7476 that it is doing so. In addition, CVS has some truly group-oriented
7477 facets, such as the modules file and the CVS administrative files that
7478 refer to a whole directory or module.
7480 One group aspect that can be a bit confusing is that a CVS branch is
7481 not the same as an RCS branch. To support a CVS branch, CVS uses
7482 "tags" (what RCS calls "symbols") and some local state, in addition to
7485 Other features offered by CVS that are not supported directly by RCS
7488 Automatic determination of the state of a file, (e.g. modified,
7489 up-to-date with the Repository, already tagged with the same string,
7490 etc.) which helps in limiting the amount of displayed text you have to
7491 wade through to figure out what changed and what to do next.
7493 A copy-modify-merge scheme that avoids locking the files and allows
7494 simultaneous development on a single file.
7496 Serialization of commits. CVS requires you to merge all changes
7497 committed (via "update") since you checked out your working copy of
7498 the file. Although it is still possible to commit a file filled with
7499 old data, it is less likely than when using raw RCS.
7501 Relatively easy merging of releases from external Vendors.
7503 Last modified: _6/13/1997_
7505 2. How does CVS differ from SCCS?
7507 SCCS is much closer to RCS than to CVS, so some of the previous entry
7510 You might want to take a look at Walter Tichy's papers on RCS, which
7511 are referred to in the RCS man pages.
7515 Last modified: _6/13/1997_
7517 3. How does CVS differ from ClearCase?
7519 ClearCase is a distributed client-server version control system.
7520 ClearCase is a variant DSEE tools, formerly available on Apollo
7521 platforms. The ClearCase tool set includes a few X-based interface
7522 tools, a command-line interface, and C programmer API. It is currently
7523 available on Sun, HP, SGI and OSF/1 platforms.
7525 ClearCase uses a special Unix filesystem type, called "mvfs" for
7526 "multi-version file system". Conceptually, mvfs adds another dimension
7527 to a regular Unix filesystem. The new axis is used to store the
7528 different versions of files and to provide a tree-hierarchical view of
7529 a collection of objects that might be scattered across any number of
7530 separate hosts on your local network.
7532 Each user acquires a "view" into the file database by creating a
7533 special mvfs mount point on their machine. Each view has a
7534 "configuration spec" containing a set of selection rules that specify
7535 the particular version of each file to make visible in that view. You
7536 can think of a "view" as a work area in CVS, except that the files
7537 don't really exist on your local disk until you modify them. This
7538 technique conserves disk space because it doesn't keep private copies
7541 Another advantage is that a view is "transparent" in the sense that
7542 all of the files in a "view" appear to be regular Unix files to other
7543 tools and Unix system calls. An extended naming convention allows
7544 access to particular versions of a file directly:
7545 "test.cc@@/main/bugfix/3" identifies the third version of test.c on
7548 ClearCase supports both the copy-modify-merge model of CVS (by using
7549 what are called "unreserved checkouts" and the checkin/checkout
7550 development model with file locking. Directories are
7551 version-controlled objects as well as files. A graphical merge tool is
7552 provided. Like RCS, ClearCase supports branches, symbolic tags, and
7553 delta compression. ASCII as well as binary files are supported, and
7554 converters from RCS, SCCS, DSEE formats are also included.
7556 A make-compatible build facility is provided that can identify common
7557 object code and share it among developers. A build auditing feature
7558 automatically records file dependencies by tracking every file that is
7559 opened when producing a derived object, thus making explicit
7560 dependency lists unnecessary. Pre- and post-event triggers are
7561 available for most ClearCase operations to invoke user programs or
7562 shell scripts. User-defined attributes can be assigned to any version
7563 or object. Hyper-links between version controlled objects can record
7566 For more information, contact:
7568 Atria Software, Inc. 24 Prime Park Way Natick, MA 01760 info@atria.com
7570 (508) 650-1193 (phone) (508) 650-1196 (fax)
7572 Originally contributed by Steve Turner
7573 Edited by the author of this FAQ.
7575 Last modified: _6/13/1997_
7577 4. How does CVS differ from TeamWare/SparcWorks?
7579 TeamWare is a configuration management tool from Sun Microsystems, a
7580 part of SparcWorks. It uses the same copy and merge model as CVS. The
7581 central abstraction is a workspace, which corresponds to either a CVS
7582 branch or a checked out module. TeamWare allows you to manipulate
7583 workspaces directly, including moving and merging code between
7584 workspaces. You can put your workspace on tape and continue to work
7585 with it at home, just like you can with CVS. TeamWare is built upon
7586 and compatible with SCCS.
7588 TeamWare provides both a command line interface and a graphical
7589 interface. The CodeManager tool will display the project as a tree of
7590 workspaces, and allows you to manipulate them with drag and drop. The
7591 other tools are VersionTool that displays and manipulates a dag with a
7592 version history of a single file, CheckPoint that will create symbolic
7593 tags, MakeTool, a make compatible tool with a GUI, and FileMerge which
7594 will interactively merge files when needed (like emerge for emacs). If
7595 you have a sun, you can try /usr/old/mergetool for an old SunView
7596 version of FileMerge.
7598 Email: sunprosig@sun.com
7600 Originally extracted from TeamWare
7601 Marketing literature by Per Abrahamsen.
7602 Edited by the author of this FAQ.
7604 For more information, contact:
7606 SunExpress, Inc. P.O. Box 4426 Bridgeton, MO 63044-9863 (800)873-7869
7608 Last modified: _6/13/1997_
7610 5. How does CVS differ from Aegis?
7612 Aegis appears to be a policy-setting tool that allows you to use other
7613 sub-programs (make, RCS, etc.) to implement pieces of the imposed
7616 The initial document seems to say that most Unix tools are inadequate
7617 for use under Aegis.
7619 It is not really similar to CVS and requires a different mindset.
7621 [[Need more info here.]]
7623 Last modified: _6/13/1997_
7625 6. How does CVS differ from Shapetools?
7627 Shapetools includes a build mechanism (called Shape, not surprisingly)
7628 that is aware of the version mechanism, and some dependency tracking.
7629 It is based on a file system extension called Attributed File System,
7630 which allows arbitrary-sized "attributes" to be associated with a
7631 file. Files are version controlled in a manner similar to RCS.
7632 Configurations are managed through the Shapefile, an extension of the
7633 Makefile syntax and functionality. Shape includes version selection
7634 rules to allow sophisticated selection of component versions in a
7637 Shapetools' concurrency control is pessimistic, in contrast to that of
7638 CVS. Also, there's very limited support for branching and merging. It
7639 has a built-in policy for transitioning a system from initial
7640 development to production.
7642 Contributed by Don Dwiggins
7644 Last modified: _6/13/1997_
7646 7. How does CVS differ from TeamNet?
7648 TeamNet is a configuration management tool from TeamOne.
7650 For more information, contact:
7652 TeamOne 710 Lakeway Drive, Ste 100 Sunnyvale, CA 94086 (800) 442-6650
7654 Contributed by Steve Turner
7656 Last modified: _6/13/1997_
7658 8. How does CVS differ from ProFrame?
7660 ProFrame is a new system integration framework from IBM. ProFrame is
7661 compliant with the CFI (CAD Framework Initiative) industry standards,
7662 including the Scheme extension language.
7664 ProFrame consists of three major components: (1) the Process Manager
7665 that automates your local design methodology (2) the Design Data
7666 Manager handles configuration management, and (3) Inter-tool
7667 Communication to provide a communication path among tools running on
7668 heterogeneous servers.
7670 The Design Data Manager(2) is probably the appropriate component to
7671 compare to CVS. The Design Data Manager provides version control with
7672 checkin/checkout capability, configuration management, and data
7673 dependency tracking. A graphical data selection interface is provided.
7674 Using this interface, you may create and manipulate objects and
7675 hierarchy structures, view the revision history for an object, and
7676 view and assign attributes to a design object.
7678 The ProFrame server currently runs only on RS6000, but clients may be
7679 a wide variety of Unix platforms. Contact IBM for the latest platform
7682 For more information, contact:
7684 IBM EDA Marketing and Sales P.O. Box 950, M/S P121 Poughkeepsie, NY
7685 12602 (800) 332-0066
7687 Contributed by Steve Turner
7688 [extracted from the ProFrame 1.1.0 datasheet]
7690 Last modified: _6/13/1997_
7692 9. How does CVS differ from CaseWare/CM?
7694 CaseWare/CM is a software configuration management product from
7695 CaseWare, Inc. CaseWare/CM may be customized to support a wide variety
7696 of methodologies, including various phases of the software lifecycle,
7697 and different access rights for users.
7699 A GUI is provided to view version histories and configurations. A
7700 merge tools is also included. CaseWare supports type-specific
7701 lifecycles, which allows different types of files to move through
7702 different lifecycles. Also provided is a build facility to support
7703 automatic dependency analysis, parallel, distributed, and remote
7704 builds, and variant releases.
7706 CaseWare/CM has been integrated with other CASE tools, including
7707 FrameMaker, ALSYS Ada, CodeCenter/Object Center, HP SoftBench, and
7708 Software Through Pictures. CaseWare also offers CaseWare/PT, a problem
7709 tracking system to integrate change requests with configuration
7712 Multiple vendors and operating systems are supported.
7714 For more information, contact:
7716 CaseWare, Inc. 108 Pacifica, 2nd Floor Irvine, CA 92718-3332 (714)
7717 453-2200 (phone) (714) 453-2276 (fax)
7719 Contributed by Steve Turner
7720 [extracted from the CaseWare/CM data sheet]
7722 Last modified: _6/13/1997_
7724 10. How does CVS differ from SABLIME?
7726 Produced by AT&T. Sablime uses SCCS as the underlying source code
7727 control system. It uses some other control system (called sbcs I
7728 think) for managing binary files. It uses lock, edit, comit, unlock
7729 mechanism. It has a motif based GUI and curses based GUI (that works
7730 only with ksh, not tcsh, or bash) to do more common tasks. It has even
7731 a command line interface.
7733 Changing source happens as a result of MR. A testing person or a
7734 developer assigns an MR (modification request) to a group of people.
7735 They are allowed to take out files under that MR and change them and
7736 check them back in. You can set up dependencies between and MR and do
7737 release management to say "I want the sources to include these MRs"
7738 etc. It is a reasonably good maintanance system. It is bit heavy
7739 weight though, and the interface is not too polished and does not work
7740 on windows (though that may have changed). rama@savera.com
7742 Last modified: _7/30/1998_
7744 11. How does CVS differ from PVCS?
7746 PVCS works on single files like RCS and SCCS, CVS works on complete
7747 subsystems. PVCS has a make utility (called a configuration builder),
7748 CVS does not. PVCS has a GUI interface for Unix, DOS, OS/2, and MS
7755 Contributed by Per Abrahamsen
7756 [Extracted from Intersolv Marketing literature.]
7758 Last modified: _6/13/1997_
7760 12. How does CVS differ from CMVC?
7762 CMVC is an IBM Configuration Management and Version Control system.
7763 (Though I'm not certain that's the right acronym expansion.) It runs
7764 on Suns, HPs, RS6000s, OS/2 and Windows.
7766 Other than revision control, it apparently has features to manage
7767 releases, bug tracking and the connection between alterations and
7768 reported bugs and feature requests. It is a client/server system,
7769 based on a choice of commercial Relational Database systems, and it
7770 provides a Motif or command line interface.
7772 Unlike CVS, it uses a strict locking protocol to serialize source code
7775 Last modified: _6/13/1997_
7777 Category: /What_is_CVS_/What_do_you_mean_by_/
7779 " + What do you mean by . . .? (Definitions)"
7781 1. What are "The Repository", "$CVSROOT" and "CVSROOT"?
7783 The Repository is a directory tree containing the CVS administrative
7784 files and all the RCS files that constitute "imported" or "committed"
7785 work. The Repository is kept in a shared area, separate from the
7786 working areas of all developers.
7788 Users of CVS must set their "CVSROOT" environment variable to the
7789 absolute pathname of the head of the Repository. Most command line
7790 interpreters replace an instance of "$CVSROOT" with the value of the
7791 "CVSROOT" environment variable. By analogy, in this document
7792 "$CVSROOT" is used as shorthand for "the absolute pathname of the
7793 directory at the head of the Repository".
7795 One of the things found in $CVSROOT is a directory named CVSROOT. It
7796 contains all the "state", the administrative files, that CVS needs
7797 during execution. The "modules", "history", "commitinfo", "loginfo"
7798 and other files can be found there. See 4B.2 for more information
7799 about CVSROOT files.
7801 Last modified: _6/13/1997_
7803 2. What is an RCS file?
7805 An RCS file is a text file containing the source text and the revision
7806 history for all committed revisions of a source file. It is stored
7807 separately from the working files, in a directory hierarchy, called
7810 RCS is the "Revision Control System" that CVS uses to manage
7811 individual files. RCS file names normally end in ",v", but that can be
7812 altered (via the RCS -x option) to conform to file naming standards on
7813 platforms with unusual filename limitations.
7815 Last modified: _6/13/1997_
7817 3. What is a working file?
7819 A working file is a disk file containing a checked-out copy of a
7820 source file that earlier had been placed under CVS. If the working
7821 file has been edited, the changes since the last committed revision
7822 are invisible to other users of CVS.
7824 Last modified: _6/13/1997_
7826 4. What is a working directory (or working area)?
7828 A working directory is the place where you work and the place from
7829 which you "commit" files.
7831 The "checkout" command creates a tree of working directories, filling
7832 them with working files. Each working directory contains a
7833 sub-directory named ./CVS containing three administrative files, which
7834 are created by "checkout" and are always present:
7837 contains information about working files.
7840 contains the location of the directory within the
7841 Repository that was used to create the working directory.
7844 contains the value of $CVSROOT at the time you created
7845 the working directory.
7847 Other files may also appear in ./CVS depending on the state of your
7851 contains the "sticky tag" associated with the whole
7852 directory. See 3A.2 for its main purpose.
7853 [Created by "checkout" or "update" when using "-r <tag>".]
7854 [Deleted by "checkout" or "update" when using '-A'.]
7856 ./CVS/Entries.Static
7857 contains a fixed list of working files. If this file
7858 exists, an "update" doesn't automatically bring newly
7859 added files out of the Repository.
7860 [Created and maintained by hand.]
7863 contains a program to run whenever anything in the
7864 working directory is committed.
7865 [Created by checkout if "-i <prog>" appears in the
7866 modules file for the checked-out module.]
7869 contains a program to run whenever anything in the
7870 working directory is updated.
7871 [Created by checkout if "-u <prog>" appears in the
7872 modules file for the checked-out module.]
7874 ./CVS/<file>,p ./CVS/<file>,t
7875 contain (possibly zero-length) state information about an
7876 "add" that has not been committed.
7878 [Deleted by "commit" or "remove".]
7880 Last modified: _6/13/1997_
7882 5. What is "checking out"?
7884 "Checking out" is the act of using the "checkout" command to copy a
7885 particular revision from a set of RCS files into your working area.
7886 You normally execute "checkout" only once per working directory (or
7887 tree of working directories), maintaining them thereafter with the
7890 See section 3C on the "checkout" command.
7892 Last modified: _6/13/1997_
7894 6. What is a revision?
7896 A "revision" is a version of a file that was "committed" ("checked
7897 in", in RCS terms) some time in the past. CVS (and RCS) can retrieve
7898 any file that was committed by specifying its revision number or its
7899 "tag" ("symbolic name", in RCS terms).
7901 In CVS, a "tag" is more useful than a revision number. It usually
7902 marks a milestone in development represented by different revision
7903 numbers in different files, all available as one "tagged" collection.
7905 Sometimes the word "revision" is used as shorthand for "the file you
7906 get if you retrieve (via "checkout" or "update") the given revision
7907 from the Repository."
7909 Last modified: _6/13/1997_
7913 A "Tag" is a symbolic name, a synonym or alias for a particular
7914 revision number in a file. The CVS "tag" command places the same "Tag"
7915 on all files in a working directory, allowing you to retrieve those
7916 files by name in the future.
7918 The CVS "Tag" is implemented by applying RCS "symbols" to each
7919 individual file. The Tags on a file (or collection of files) may be
7920 displayed using the "log" command.
7922 Last modified: _6/13/1997_
7924 8. What are "HEAD" and "BASE"?
7926 HEAD and BASE are built-in tags that don't show up in the "log" or
7927 "status" listings. They are interpreted directly by CVS.
7929 "HEAD" refers to the latest revision on the current branch in the
7930 Repository. The current branch is either the main line of development,
7931 or a branch in development created by placing a branch tag on a set of
7932 files and checking out that branch.
7934 "BASE" refers to the revision on the current branch you last checked
7935 out, updated, or committed. If you have not modified your working
7936 file, "BASE" is the committed revision matching it.
7938 Most of the time BASE and HEAD refer to the same revision. They can
7939 become different in two ways:
7941 Someone else changed HEAD by committing a new revision of your file
7942 to the Repository. You can pull BASE up to equal HEAD by executing
7945 You moved BASE backward by executing "checkout" or "update" with the
7946 option "-r <rev/tag>" or "-D <date>". CVS records a sticky tag and
7947 moves your files to the specified earlier revision. You can clear the
7948 sticky tag and pull BASE up to equal HEAD again by executing "update
7951 Last modified: _6/13/1997_
7953 9. What is a Branch?
7955 In general, a branch is any mechanism that allows one or more
7956 developers to modify a file without affecting anyone other than those
7957 working on the same branch.
7959 There are four kinds of "branch" CVS can manage:
7963 A single vendor branch is supported. The "import" command takes a
7964 sequence of releases from a source code vendor (called a "vendor" even
7965 if no money is involved), placing them on a special "Vendor" branch.
7966 The Vendor branch is considered part of the "Main line" of
7967 development, though it must be merged into locally modified files on
7968 the RCS Main branch before the "import" is complete.
7970 See Section 3H ("import").
7972 Your Working directory.
7974 A checked-out working directory, can be treated like a private branch.
7975 No one but you can touch your files. You have complete control over
7976 when you include work committed by others. However, you can't commit
7977 or tag intermediate versions of your work.
7979 A Development branch.
7981 A group of developers can share changes among the group, without
7982 affecting the Main line of development, by creating a branch. Only
7983 those who have checked-out the branch see the changes committed to
7984 that branch. This kind of branch is usually temporary, collapsing
7985 (i.e. merge and forget) into the Main line when the project requiring
7986 the branch is completed.
7988 You can also create a private branch of this type, allowing an
7989 individual to commit (and tag) intermediate revisions without changing
7990 the Main line. It should be managed exactly like a Development Branch
7991 -- collapsed into the Main line (or its parent branch, if that is not
7992 the Main Branch) and forgotten when the work is done.
7996 At release time, a branch should be created marking what was released.
7997 Later, small changes (sometimes called "patches") can be made to the
7998 release without including everything else on the Main line of
7999 development. You avoid forcing the customer to accept new, possibly
8000 untested, features added since the release. This is also the way to
8001 correct bugs found during testing in an environment where other
8002 developers have continued to commit to the Main line while you are
8003 testing and packaging the release.
8005 Although the internal format of this type of branch (branch tag and
8006 RCS branches) is the same as in a development branch, its purpose and
8007 the way it is managed are different. The major difference is that a
8008 Release branch is normally Permanent. Once you let a release out the
8009 door to customers, or to the next stage of whatever process you are
8010 using, you should retain forever the branch marking that release.
8012 Since the branch is permanent, you cannot incorporate the branch fixes
8013 into the Main line by "collapsing" (merging and forgetting) the
8014 release branch. For large changes to many files on the release branch,
8015 you will have to perform a branch merge using "update -j <rev> -j
8018 The most common way to merge small changes back into Main line
8019 development is to make the change in both places simultaneously. This
8020 is faster than trying to perform a selective merge.
8022 See 1D.12 (merges) and Section 4C, on Branching for more info.
8024 Last modified: _6/13/1997_
8026 10. What is "the trunk"?
8028 Another name for the RCS Main Branch. The RCS Main Branch is related,
8029 but not equivalent, to both the CVS Main branch and what developers
8030 consider to be the Main line of development. See 3H.3 and Section 4C
8033 Last modified: _6/13/1997_
8035 11. What is a module?
8037 In essence, a module is a name you hand to the "checkout" command to
8038 retrieve one or more files to work on. It was originally intended to
8039 be a simple, unique name in the "modules" file attached to a directory
8040 or a subset of files within a directory.
8042 The module idea is now a somewhat slippery concept that can be defined
8043 in two different ways:
8044 * A module is an argument to "checkout". There are three types:
8045 1. An entry in the modules file. A "module" name as described in
8047 2. A relative path to a directory or file in the Repository.
8048 3. A mixed-mode string of "modulename/relative-path". Everything
8049 up to the first slash ('/') is looked up as a module. The
8050 relative path is appended to the directory associated with
8051 the module name and the resulting path is checked out as in
8053 * A module is a unique (within the file) character string in the
8054 first column of the modules file. There are five types:
8055 1. A name for a directory within the Repository that allows you
8056 to ignore the parent directories above it.
8059 2. A name for a subset of the files within such a directory.
8061 ls unix/bin Makefile ls.c
8062 The 2nd through Nth strings in the above can be files,
8063 directories or module substitutions. No relative paths.
8064 A module substitution occurs when you use a '&module-name'
8065 reference. The module-name referred to is logically
8066 substituted for the '&module-name' string.
8067 3. A relative pathname to a directory within the Repository
8068 which, when checked out, creates an image of part of the
8069 Repository structure in your current directory.
8071 gnu/emacs -o /bin/emacs.helper gnu/emacs
8072 The files checked out are exactly the same as the files
8073 "checkout" would retrieve if the path weren't even in the
8074 modules file. The only reason to put this kind of relative
8075 pathname into the modules file is to hook one of the helper
8077 4. A relative pathname to a single file within the Repository
8078 which, when checked out, creates something you probably don't
8079 want: It creates a directory by the name of the file and puts
8082 gnu/emacs/Makefile -o /bin/emacs.helper gnu/emacs Makefile
8083 The file checked out is the same as what you would get if you
8084 handed the relative pathname to the "checkout" command. But
8085 it puts it in a strange place. The only reason to do this is
8086 to hook a helper function onto a specific file name.
8087 5. An alias consisting of a list of any of the above, including
8088 other aliases, plus exceptions.
8090 my_work -a emacs !emacs/tests gnu/bison unix/bin/ls.c
8091 The exception "!emacs/test" above is functionally equivalent
8092 to specifying "!emacs/tests" on the "checkout" command line.
8094 Another way to look at it is that the modules file is simply another
8095 way to "name" files. The hierarchical directory structure provides
8096 another. You should use whatever turns out to be simplest for your
8099 See 4G.2 for some specific ideas about how to use the modules file.
8101 Last modified: _11/12/1997_
8103 12. What does "merge" mean?
8105 A merge is a way of combining changes made in two independent copies
8106 of a common starting file. Checking out an RCS revision produces a
8107 file, so for the purposes of a merge "file" and "revision" are
8108 equivalent. So, we can say there are always three "files" involved in
8111 The original, starting, "base" or "branch point" file.
8113 A copy of the base file modified in one way.
8115 Another copy of the base file modified in a different way.
8117 Humans aren't very good at handling three things at once, so the
8118 terminology dealing with merges can become strained. One way to think
8119 about it is that all merges are performed by inserting the difference
8120 between a base revision and a later revision (committed by someone
8121 else) into your working file. Both the "later" revision and your
8122 working file are presumed to have started life as a copy of the "base"
8125 In CVS, there are three main types of "merge":
8127 The "update" command automatically merges revisions committed by
8128 others into your working file. In this case, the three files involved
8131 Base: The revision you originally checked out. Later: A revision
8132 committed onto the current branch after you checked out the Base
8133 revision. Working: Your working file. The one lying in the working
8134 directory containing changes you have made.
8136 The "update -j <branch_tag> {optional files}" command merges changes
8137 made on the given branch into your working files, which is presumed to
8138 be on the Main line of development.
8142 The "update -j <rev> -j <rev> {optional files}" command merges the
8143 difference between two specified revisions into files in your working
8144 directory. The two revisions <rev> are usually on the same branch and,
8145 when updating multiple files, they are most useful when they are Tag
8146 names rather than numeric revisions.
8150 Last modified: _6/13/1997_
8152 Category: /What_is_CVS_/What_is_CVS_Whats_it/
8154 " + What is CVS? What's it for? Why CVS?"
8156 1. What does CVS stand for? Can you describe it in one sentence?
8158 "CVS" is an acronym for the "Concurrent Versions System".
8160 CVS is a "Source Control" or "Revision Control" tool designed to keep
8161 track of source changes made by groups of developers working on the
8162 same files, allowing them to stay in sync with each other as each
8165 Last modified: _6/13/1997_
8167 2. What is CVS for? What does it do for me?
8169 CVS is used to keep track of collections of files in a shared
8170 directory called "The Repository". Each collection of files can be
8171 given a "module" name, which is used to "checkout" that collection.
8173 After checkout, files can be modified (using your favorite editor),
8174 "committed" back into the Repository and compared against earlier
8175 revisions. Collections of files can be "tagged" with a symbolic name
8176 for later retrieval.
8178 You can add new files, remove files you no longer want, ask for
8179 information about sets of files in three different ways, produce patch
8180 "diffs" from a base revision and merge the committed changes of other
8181 developers into your working files.
8183 Last modified: _6/13/1997_
8185 3. How does CVS work?
8187 CVS saves its version-control information in RCS files stored in a
8188 directory hierarchy, called the Repository, which is separate from the
8189 user's working directory.
8191 Files in the Repository are stored in a format dictated by the RCS
8192 commands CVS uses to do much of its real work. RCS files are standard
8193 byte-stream files with an internal format described by keywords stored
8194 in the files themselves.
8196 To begin work, you execute a "checkout" command, handing it a module
8197 name or directory path (relative to the $CVSROOT variable) you want to
8198 work on. CVS copies the latest revision of each file in the specified
8199 module or directory out of the Repository and into a directory tree
8200 created in your current directory. You may specify a particular branch
8201 to work on by symbolic name if you don't want to work on the default
8202 (main or trunk) branch.
8204 You may then modify files in the new directory tree, build them into
8205 output files and test the results. When you want to make your changes
8206 available to other developers, you "commit" them back into the
8209 Other developers can check out the same files at the same time. To
8210 merge the committed work of others into your working files you use the
8211 "update" command. When your merged files build and test correctly, you
8212 may commit the merged result. This method is referred to as
8213 "copy-modify-merge", which does not require locks on the source files.
8215 At any time, usually at some milestone, you can "tag" the committed
8216 files, producing a symbolic name that can be handed to a future
8217 "checkout" command. A special form of "tag" produces a branch in
8218 development, as usually happens at "release" time.
8220 When you no longer plan to modify or refer to your local copy of the
8221 files, they can be removed.
8223 Last modified: _6/13/1997_
8225 4. What is CVS useful for?
8227 CVS is intended to handle source control for files in three major
8230 Multiple developers working on the same files.
8232 The major advantage of using CVS over the simpler tools like RCS or
8233 SCCS is that it allows multiple developers to work on the same sources
8236 The shared Repository provides a rendezvous for committed sources that
8237 allows developers a fair amount of flexibility in how often to publish
8238 (via the "commit" command) changes or include work committed by others
8239 (via the "update" command).
8241 Tracking a stream of releases from a source vendor.
8243 If you are making changes to sources distributed by someone else, the
8244 CVS feature, called the Vendor Branch, allows you to combine local
8245 modifications with repeated vendor releases.
8247 I have found this most useful when dealing with sources from three
8248 major classes of source vendor:
8250 Large companies who send you tapes full of the latest release (e.g.
8251 Unix OS vendors, database companies).
8253 Public Domain software which *always* requires work.
8255 Pseudo-Public sources which may require work. (e.g. GNU programs, X,
8258 Branching development.
8260 Aside from the "Vendor Branch", there are three kinds of "branches in
8261 development" that CVS can support:
8263 Your working directory can be treated as a private branch.
8265 A Development branch can be shared by one or more developers.
8267 At release time, a branch is usually created for bug fixes.
8269 (See 1D.9 and Section 4C for more info on branches.)
8271 CVS's branch support is a bit primitive, but it was designed to allow
8272 you to create branches, work on them for while and merge them back
8273 into the main line of development. You should also be able to merge
8274 work performed on the main branch into the branch you are working on.
8275 Arbitrary sharing and merging between branches is not currently
8278 Last modified: _6/13/1997_
8280 5. What is CVS *not* useful for?
8282 CVS is not a build system.
8284 Though the structure of your Repository and modules file interact with
8285 your build system (e.g. a tree of Makefiles), they are essentially
8288 CVS does not dictate how you build anything. It merely stores files
8289 for retrieval in a tree structure you devise.
8291 CVS does not dictate how to use disk space in the checked out working
8292 directories. If you require your Makefiles or build procedures to know
8293 the relative positions of everything else, you wind up requiring the
8294 entire Repository to be checked out. That's simply bad planning.
8296 If you modularize your work, and construct a build system that will
8297 share files (via links, mounts, VPATH in Makefiles, etc.), you can
8298 arrange your disk usage however you like.
8300 But you have to remember that *any* such system is a lot of work to
8301 construct and maintain. CVS does not address the issues involved. You
8302 must use your brain and a collection of other tools to provide a build
8303 scheme to match your plans.
8305 Of course, you should use CVS to maintain the tools created to support
8306 such a build system (scripts, Makefiles, etc).
8308 CVS is not a substitute for management.
8310 You and your project leaders are expected to plan what you are doing.
8311 Everyone involved must be aware of schedules, merge points, branch
8312 names, release dates and the range of procedures needed to build
8313 products. (If you produce it and someone else uses it, it is a
8314 product.) CVS can't cover for a failure to manage your project.
8316 CVS is an instrument for making sources dance to your tune. But you
8317 are the piper and the composer. No instrument plays itself or writes
8320 CVS is not a substitute for developer communication.
8322 When faced with conflicts within a single file, most developers manage
8323 to resolve them without too much effort. But a more general definition
8324 of "conflict" includes problems too difficult to solve without
8325 communication between developers.
8327 CVS cannot determine when simultaneous changes within a single file,
8328 or across a whole collection of files, will logically conflict with
8329 one another. Its concept of a "conflict" is purely textual, arising
8330 when two changes to the same base file are near enough to spook the
8331 merge command into dropping conflict markers into the merged file.
8333 CVS is not capable of figuring out distributed conflicts in program
8334 logic. For example, if you change the arguments to function X defined
8335 in file A and, at the same time, edit file B, adding new calls to
8336 function X using the old arguments. You are outside the realm of CVS's
8339 Acquire the habit of reading specs and talking to your peers.
8341 CVS is not a configuration management system.
8343 CVS is a source control system. The phrase "configuration management"
8344 is a marketing term, not an industry-recognized set of functions.
8346 A true "configuration management system" would contain elements of the
8350 * Dependency tracking.
8351 * Build systems (i.e. What to build and how to find
8352 things during a build. What is shared? What is local?)
8354 * Automated Testing procedures.
8355 * Release Engineering documentation and procedures.
8356 * Tape Construction.
8357 * Customer Installation.
8358 * A way for users to run different versions of the same
8359 software on the same host at the same time.
8361 CVS provides only the first.
8363 Last modified: _6/13/1997_
8365 Category: /What_is_CVS_/Where_do_I_find_CVS_/
8367 " + Where do I find CVS? Where can I find Help?"
8369 1. How do I get more information about CVS?
8371 The first thing I would do is to read the Info file that comes with
8372 the CVS sources under "doc". You can format and read the cvs.texinfo
8373 file in two ways: 1. Use TeX to format it and a "dvips" command to
8374 print it and 2. Install the cvs.info files that are created by the
8375 Makefile and read them online using the Emacs "info-mode" or a
8376 stand-alone "info" reader.
8378 Then I'd run "cvsinit" to set up a Repository and read the man page
8379 while trying out the commands.
8381 Type "cvs -H" for general help or "cvs -H command" for
8382 command-specific help.
8384 For background, you can read the original CVS paper (in the source
8385 tree, under "doc"). It describes the purpose of CVS and some of how it
8386 was designed. Note that the emphasis of the document (especially on
8387 multiple vendors providing the same sources) is somewhat out of date.
8389 For more detailed information about "internals", read the man pages
8390 for RCS. If you are a programmer, you can also read the source code to
8393 Other information and tutorials may be available in the "doc"
8394 directory of the FTP archive described below.
8396 For current information, and a fair amount of detail, join the
8397 info-cvs mailing list described below.
8399 Last modified: _6/13/1997_
8401 2. Is there an archive of CVS material?
8403 An anonymous FTP area has been set up. It contains many of the CVS
8404 files you might want, including extra documentation, patches and a
8405 copy of the latest release.
8414 The README has more (and more up-to-date) information. The Index
8415 contains a terse list of what is in the archive.
8417 A WWW home page is also available at http://www.delos.com/cvs.
8419 This Didn't Exist 6/23/1998
8421 Last modified: _6/24/1998_
8423 3. How do I get files out of the archive if I don't have FTP?
8425 Use one of the FTP<->Email servers. These are the ones I've been told
8428 FTPMAIL service is available from the same host as the FTP server
8429 described above. Send mail to "ftpmail@delos.com" containing "help" in
8430 the body of the message. For example, on most Unix systems, you can
8433 echo help | Mail ftpmail@delos.com
8435 The FTPMAIL server will respond with a document describing how to use
8436 the server. If the "Mail" command doesn't exist on your system, try
8437 "mailx", "/usr/ucb/mail" or "/bin/mail".
8439 If you are on BITNET, use Princeton's BITFTP server. Type
8441 echo 'send help' | Mail bitftp@pucc.princeton.edu
8443 (It is likely that only BITNET addresses can use this one.)
8445 Other possibilities I've heard of from the net: (Try the one closest
8448 ftpmail@decwrl.dec.com ftpmail@sunsite.unc.edu ftpmail@cs.arizona.edu
8449 ftpmail@cs.uow.edu.au ftpmail@doc.ic.ac.uk
8451 Last modified: _6/13/1997_
8453 4. How do I get a copy of the latest version of CVS?
8455 The latest released version of CVS and all the programs it depends on
8456 should be available through anonymous FTP on any FSF archive. The main
8457 FSF archive is at "prep.ai.mit.edu". There are mirrors of the FSF
8458 archive on UUNET and other large Internet sites.
8460 Program(s) Suggested revision
8461 ----------- -----------------------
8463 RCS 5.7 (latest version available today)
8464 GNU diff 2.7 (or later) [contained in diffutils-2.7]
8465 GDBM 1.5 (or later) [optional]
8467 The GNU version of diff is suggested by both the RCS and CVS
8468 configuration instructions because it works better than the standard
8471 It is a good idea not to accept the versions of CVS, RCS or diff you
8472 find lying on your system unless you have checked out their
8473 provenance. Using inconsistent collections of tools can cause you more
8474 trouble than you can probably afford.
8476 The FTP archive mentioned above should contain the latest official
8477 release of CVS, some official and unofficial patches and possibly
8478 complete patched versions of CVS in use somewhere.
8480 Last modified: _6/13/1997_
8482 5. Is there a mailing list devoted to CVS? How do I find it?
8484 An Internet mailing list named "info-cvs" grew out of the private
8485 mailing list used by the CVS 1.3 alpha testers in early 1992.
8486 Throughout 1994, the list received an average of 100 messages per
8489 You can add yourself to the mailing list by sending an Email message
8492 info-cvs-request@prep.ai.mit.edu
8494 (Don't forget the "-request" or you'll send a message to the whole
8495 list, some of whom are capable of remote execution.)
8497 Mail to the whole list should be sent to:
8499 info-cvs@prep.ai.mit.edu
8501 An archive of the mailing list is maintained in the FTP archive
8504 Last modified: _6/13/1997_
8506 6. What happened to the CVS Usenet newsgroup I heard about?
8509 A Usenet newsgroup named "gnu.cvs.info" was announced in April
8510 1993, with an expected creation date of August, 1993. However,
8511 nothing came of this.
8513 If you want to discuss CVS on usenet, the correct group is
8514 comp.software.config-mgmt (which also covers other configuration
8515 management systems). Someday it might be possible to create a
8516 comp.software.config-mgmt.cvs, but only if there is sufficient
8517 CVS traffic on comp.software.config-mgmt.
8521 Last modified: _9/6/1997_
8522 _________________________________________________________________
8524 [Add an answer to this category]
8527 _________________________________________________________________
8529 _Search the FAQ-O-Matic:_ ____________________ Search
8530 [matching all words]
8531 Or look for questions modified in the last: [7.] Days
8532 _________________________________________________________________
8534 The FAQ-O-Matic lives at http://gille.loria.fr:7000/cgi-bin/faqomatic.
8535 The code was written by Jon Howell, and the content by folks from all
8537 _________________________________________________________________
projects / FreeBSD / FreeBSD.git / blob