1 -------------------------------------------------------------------------------
3 CVS is Copyright (C) 1986-2006 The Free Software Foundation, Inc.
5 CVS is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published by
7 the Free Software Foundation; either version 1, or (at your option)
10 More details are available in the COPYING file but, in simplified
11 terms, this means that any distributed modifications you make to
12 this software must also be released under the GNU General Public
15 CVS is distributed in the hope that it will be useful,
16 but WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 GNU General Public License for more details.
20 -------------------------------------------------------------------------------
22 This file contains a CVS FAQ. Until 1995 it was maintained by David
23 Grubbs. It was out of date and not being maintained, but it had a
24 certain following and in 1997 Pascal Molli decided to start
25 maintaining it with the FAQ-O-Matic package which allows any
26 contributor with a web browser to help maintain it. The following
27 text is (mostly automatically) extracted from the FAQ-O-Matic. The
28 odds are good that the file that you are currently reading is out of
29 date with respect to the online FAQ-O-Matic, which is part of Pascal
30 Molli's CVS web site at http://www.loria.fr/~molli/cvs-index.html
31 (currently under "Documentation"). The online version is also
32 somewhat better in terms of things like tables of contents (at least
33 until someone can write some code to extract data from a FAQ-O-Matic
34 and insert things like tables of contents).
36 The answers which are dated "6/13/1997" below are really from the 1995
37 FAQ, for the most part. Many of them are out of date. The current FAQ may
38 be found at <http://ximbiot.com/cvs/wiki/index.php?title=CVS_FAQ>. If you have
39 some time, you are encouraged to export that FAQ as text and import it here.
40 If you don't have such time, take the answers in this file with at least a few
43 Since August, 2005, many of the existing CVS resources have been centralized on
44 <http://cvs.nongnu.org> & <http://ximbiot.com>.
46 Category: /, all questions
54 This is FAQ-O-Matic, a quick-and-dirty Perl hack (aren't they all?) by
57 It seems like most FAQ maintainers make a valiant initial effort, then get
58 a life and don't have time to keep their FAQs up to date. Also, I often
59 find out a solution to a problem, and feel like I could write a single
60 FAQ answer on it in a few minutes, but where to post it?
62 Thus the FAQ-O-Matic was born. FAQ-O-Matic is a couple sleazy Perl scripts
63 that allow people to submit FAQ answers to this database, so it can stay
64 current, with just a tiny bit of work on any one person's part.
66 Yes, a bad guy could come along and wipe out all the FAQ entries. Please don't.
67 But to give the good guys some measure of comfort, each submission is stored
68 in an RCS file, so if someone does tamper, we can recover the database.
70 Guidelines for submissions:
72 1. Please _try to be fairly unbiased in matters of opinion._ Mailing lists are
73 the place to start flame wars (just kidding :v), but definitely not here.
75 2. Please _use HTML only conservatively_ in your entries. Links are appropriate
77 but put the URL in the plaintext also so it's useable on printed versions of
78 the FAQ. Inline images pointing off this site are inappropriate, as is much
79 fancy formatting. This is meant to be bandwidth-light and dumb-browser-friendly
82 3. If you feel there's a place for a _new category, or a reorganization of
83 existing questions_, don't hesitate to mail me (molli@loria.fr).
84 Category changes need to be done from my end.
86 4. Please _leave an email address_ at the bottom of your submission so that oth
90 5. _If you only have a question_, not an answer, you should probably post
91 it to a mailing list, not here. If there are frequently asked questions to whic
93 the answer is not forthcoming on mailing lists (or perhaps there's no
94 useful answer yet other than "no one knows"), then it's appropriate to
95 post here, in hopes that someone will see it and know the answer.
97 6. Please refrain from crude or inconsiderate language. Please don't use
98 this as a forum for advertising. However, mention of worthy commercial
99 products is certainly appropriate (even if you sell said product). Just
102 Last modified: _6/13/1997_
104 2. Adding a new category ?
106 just send me a mail at
109 Last modified: _6/13/1997_
111 Category: /Advanced_Topics_/
115 Category: /Advanced_Topics_/Branching_and_Mergin/
117 " + Branching and Merging"
121 Unfortunately, the word "branch" is an overloaded technical
122 term. It is used in too many different ways in three
123 categories. It might help to understand some of the issues by
124 going through the categories:
126 How Humans use the word "branch":
128 Most development starts with everyone working on the same
129 software, making changes and heading toward a single goal. This
130 is called something like "Main Line Development". Note that
131 though many people do main line development on CVS's "Main
132 Branch", that is a choice, not a requirement.
134 After a release or when one or more developers want to go off
135 and work on some project for a while, the Software Engineers
136 assigned to deal with large software issues generate a "Branch
137 in Development" to support the release or project. (Keep in
138 mind that a programmer is no more a Software Engineer than a
139 carpenter is a Civil Engineer.)
141 Essentially, the word "branch" implies a way to allow
142 simultaneous development on the same files by multiple people.
144 The above terms are human-oriented. They refer to actions that
145 people would like to take. They do *not* imply any particular
146 implementation or set of procedures. Branches in development
147 can be supported in many different ways.
149 How CVS uses the word "branch":
151 CVS uses the word "branch" in a number of ways. The two most
154 - The vendor branch holds releases from (normally) an outside
155 software vendor. It is implemented using a specific RCS branch
158 - The "Main Branch", which normally holds your "Main Line
159 Development", but is defined as the collection of revisions you
160 get when you "checkout" something fresh, or when you use the
161 '-A' option to "update".
163 Important Note: The CVS "Main Branch" is *not* the same as the
164 RCS concept with the same name. If you are using Vendor
165 Branches, files you have never changed are on three branches at
168 - The RCS 1.1.1 branch.
169 - The CVS Vendor branch.
170 - The CVS "Main Branch".
172 The concepts overlap, but they are not equivalent.
174 In referring to CVS, "branch" can be used in four other ways:
176 - A CVS working directory satisfies the definition of "branch"
177 for a single developer -- you are on a private "virtual branch"
178 that does not appear in any of the RCS files or the CVS control
181 - The CVS "default branch" is the Repository source for the
182 collection of files in your working directory. It is *not* the
183 same as the RCS "default branch". Normally the CVS default
184 branch is the same as the CVS Main branch. If you use the "-r
185 <branch_tag>" option to the "checkout" command, you will record
186 a "sticky" tag that changes your default branch to the one you
189 - A "magic" branch can be a branch that hasn't happened yet. It
190 is implemented by a special tag you can check out that is not
191 attached to a real RCS branch. When you commit a file to a
192 magic branch, the branch becomes real (i.e. a physical RCS
195 - And, of course, CVS uses "branch" to indicate a
196 human-oriented "branch in development".
198 How RCS uses the word "branch":
200 - The RCS "Main Branch" (Synonym: "The Trunk") contains a
201 series of two-part revision numbers separated by a single '.'
202 (e.g. 1.2). It is treated specially and is the initial default
203 branch. (The default default?)
205 - The RCS "Default" branch starts out attached to the RCS "Main
206 Branch". For RCS purposes, it can be changed to point to any
207 branch. Within CVS, you *must*not* alter the RCS default
208 branch. It is used to support the CVS idea of a "Main Branch"
209 and it must either point to the RCS Main Branch, or the Vendor
210 Branch (1.1.1) if you haven't made any changes to the file
211 since you executed "import".
213 Last modified: _6/13/1997_
215 2. Why (or when) would I want to create a branch?
217 Remember that you can think of your working directory as a "branch for
218 one". You can consider yourself to be on a branch all the time because
219 you can work without interfering with others until your project (big
222 The four major situations when you should create a branch:
224 When you expect to take a long time or make a large set of changes
225 that the merging process will be difficult. Both "long" and "large"
226 are defined in your own environment.
228 When you want to be able to "commit" and "tag" your work repeatedly
229 without affecting others.
231 If you ever think you need Source Control for your own work, but don't
232 want your changes to affect others, create a private branch. (Put your
233 username in the branch tag, to make it obvious that it is private.)
235 When you need to share code among a group of developers, but not the
236 whole development organization working on the files.
238 Rather than trying to share a working directory, you can move onto a
239 branch and share your work with others by "committing" your work onto
240 the branch. Developers not working on the branch won't see your work
241 unless they switch to your branch or explicitly merge your branch into
244 When you need to make minor changes to a released system.
246 Normally a "release" is labeled by a branch tag, allowing later work
247 on the released files. If the release is labeled by a non-branch tag,
248 it is easy to add a branch tag to a previously tagged module with the
249 "rtag" command. If the release is not tagged, you made a mistake.
250 Recovery requires identifying all revisions involved in the release
251 and adding a tag to them.
253 Last modified: _6/13/1997_
255 3. How do I create and checkout a branch?
259 Attach a non-branch tag to all the revisions you want to branch
260 from. (i.e. the branch point revisions)
262 When you decide you really need a branch, attach a branch tag to the
263 same revisions marked by the non-branch tag.
265 "Checkout" or "update" your working directory onto the branch.
267 Suggested procedure when using modules:
269 cvs rtag <branch_point_tag> module
271 cvs rtag -b -r <branch_point_tag> <branch_tag> <module>
273 cvs checkout -r <branch_tag> module
275 Suggested procedure when using your working directory, which
276 contains the revisions of your working files you want to branch from:
278 cvs tag <branch_point_tag>
280 cvs rtag -b -r <branch_point_tag> <branch_tag> <module>
282 cvs update -r <branch_tag>
284 In each procedure above, Step #1 applies a non-branch tag to all the
285 branch point revisions in the module/directory. Though this is not
286 strictly necessary, if you don't add a non-branch tag to the revisions
287 you branch from, you won't be able to refer to the branch point in the
290 Between steps 1 & 2 you may commit changes. The result would be same
291 because "rtag -r <oldtag> <newtag>" applies <newtag> to the same
292 revision that <oldtag> is attached to. You can use this technique to
293 avoid attaching *any* branch tags until you need them.
295 Step B.2 has two corollaries:
297 If you plan to create the branch tag before committing anything in
298 your working directory, you can use "cvs tag -b <branch_tag>" instead
299 of the "rtag" command.
301 The <module> can be a relative path to a directory from which your
302 working directory was checked out.
304 If you have trouble figuring out what <module> to use (or pathname to
305 use in its place), you can aim it at whatever parent directories you
306 believe will cover all your work.
308 If you are sure the <branch_tag> is not being used anywhere else, you
309 can even aim it at the whole Repository ($CVSROOT), if you have to. It
310 might take some extra time, but assuming that your <tag> is a unique
311 string and you don't use the '-f' option to "rtag -r", "rtag" will
312 only add a <tag> to files in which it actually *finds* the earlier
315 In each procedure above, Step #3 may occur any time after step 2.
316 Unless you explicitly remove them with "tag -d", a <tag> is permanent.
318 The <branch_tag> is an unusual creature. It labels a branch in a way
319 that allows you to "checkout" the branch, to "commit" files to the end
320 of the branch and to refer to the end of the branch. It does not label
321 the base of the branch (the branch point).
323 There are two obvious ways to choose the <branch_point_tag> and
324 <branch_tag> names. But keep in mind that the <branch_tag> is typed by
325 any developer who wants to work on the branch -- you should make it
326 mean something to them.
328 Style #1 presumes that the simple version string refers to a set of
329 designed, documented or promised features, not to a specific set of
330 files. In this case, you tag the branch with the generic Version
331 string and assume that whenever you refer to "Version", you want the
332 "latest" set of files associated with that Version, including all
333 patches. (You can substitute whatever you like for "bp_", as long as
334 your <branch_point_tag> is some modification of the <branch_tag>.)
336 <branch_point_tag> Matching <branch_tag>
339 bp_Release2-3-5 Release2-3-5
340 bp_Production4_5 Release4_5
342 Style #2 presumes that the simple version string refers to the
343 specific set of files used to construct the first release of
344 "version". In this case, you tag the branch-point revisions with the
345 generic Version string and assume that whenever you refer to this
346 Version, you want the original set of released revisions. To get the
347 latest patched revisions of the release, you refer to the branch tag
348 "latest_<branch_point_tag>". (You can substitute what ever you like
349 for "latest_", as long as your <branch_tag> is some modification of
350 the <branch_point_tag>.)
352 <branch_point_tag> Matching <branch_tag>
355 Release2-3-5 latest_Release2-3-5
356 Release4_5 latest_Production4_5
358 In both styles you can find out what you had to change since the
359 original release of this Version by typing:
361 cvs diff -r <branch_point_tag> -r <branch_tag>
363 For Style 1, this is:
365 cvs diff -r bp_<branch_tag> -r <branch_tag>
367 For Style 2, this is:
369 cvs diff -r <branch_point_tag> -r latest_<branch_point_tag>
371 Notes on "being on a branch":
373 - "update -r <tag>" tells CVS to attach a "sticky tag" to working
374 directory (in ./CVS/Tag) and the checked-out files (on each line of
377 - A "sticky" <tag> (including a <branch_tag>) causes most CVS commands
378 to act as if "-r <tag>" were on the command line.
380 - A "sticky" <branch_tag> indicates that the working directory (and
381 working files) are "on the branch".
383 Last modified: _6/13/1997_
385 4. Once created, how do I manage a branch?
387 The most important thing you should know about managing a branch is
388 that the creation of a branch is not a lightweight act. When you
389 create a branch, you must also create a set of procedures to keep
392 Specifically, you must:
394 - Remember that the branch exists. (This is non-trivial if you create
397 - Plan when to merge it back into the main line of development.
399 - Schedule the order that multiple branch merges are to be done.
401 - If you ever intend to merge branches into each other, instead of
402 limiting merges of branch work back into the "main line", you must
403 keep careful track of which parts of which branches have merged into
404 which other branches.
406 The simplest way to deal with branches is to limit their number,
407 "collapse" them back into the main line as quickly as is reasonable
408 and forget them. If a group wants to continue working, tell them to
409 create another branch off the fully merged main line.
411 Remember that CVS is just a tool. Over time, it will probably handle
412 branching better, requiring less careful attendance. But no matter how
413 good it becomes, the whole idea of "branching" is a complicated
414 management problem. Don't take it lightly.
416 Last modified: _6/13/1997_
418 5. Are there any extra issues in managing multiple branches?
420 If you plan to split from the "main line" and merge back after a time,
421 the only problem will be scheduling the order of branch merges. As
422 each branch is merged, the main line must be rebuilt and tested.
423 Merging multiple branches (i.e. "lines of development") before
424 building and testing creates more problems than you are ready for.
426 If you plan to collapse some branches into others, then move the
427 combined branches back into the main line, you have to be careful with
428 the revisions and tags you hand to your "update -j" command, but it
429 shouldn't be much trouble.
431 If you plan to allow every branch to incrementally take the work done
432 on other branches, you are creating an almost insurmountable
433 bookkeeping problem. Every developer will say "Hey, I can handle
434 taking just this little bit," but for the system as a whole it is
435 disaster. Try it once and see. If you are forced into this situation,
436 you will need to keep track of the beginning and end points of every
437 merge ever done. Good Luck.
439 Last modified: _6/13/1997_
441 6. How do I merge a whole branch back into the trunk?
443 If you don't have a working directory, you can checkout and merge in
446 cvs checkout -j <branch_tag> <module>
449 If you already have a working directory:
451 cd <working_directory>
452 cvs update <== Optional, to bring it up to date.
453 cvs update -j <branch_tag>
455 CVS will print lines beginning with
457 'U' for files that you hadn't changed, but the branch did.
459 'M' for files that you changed and the branch didn't
460 *and* for files that you both changed that were merged
461 without overlaps. (This overload is unfortunate.)
463 'C' for files that you both changed in a way that conflicts
466 You need to go edit all the 'C' files and clean up the conflicts. Then
467 you must commit them.
469 Last modified: _6/13/1997_
471 7. How do I merge changes from the trunk into my branch or between
474 The idea is similar to the above, but since CVS doesn't treat the main
475 branch like other branches, you'll have to be more careful. There are
476 5 different ways to look at the problem.
478 The way to merge *all* changes made on the trunk into a working
479 branch is to move to the branch you want via "checkout -r" or "update
482 cvs update -r <branch_tag> {optional files}
484 Then merge the changes from the trunk into your working branch using
485 the pseudo-tag named "HEAD":
487 cvs up -j HEAD {optional files}
489 You will get everything from the branch point of the branch named
490 <branch_tag> up to the HEAD of the main branch. This is still kind of
491 strange. If the file is on a branch, HEAD should be the latest thing
492 on the branch, not the HEAD of MAIN. But that's not the way CVS
495 If you run "cvs up -j HEAD" again after adding more revisions to the
496 trunk, you may get overlaps for the text you have already merged. It
497 depends on your version of your RCS "merge" command (actually the "co
498 -j" option, which depends on the version of "diff3" you configured RCS
501 You can merge the difference between any two <tags> using two "-j"
502 options on "update" or "checkout".
504 Identify the two tags on the branch you want to merge from.
506 cvs update -j <tag1> -j <tag2> {optional files}
508 This step assumes you were careful about tagging milestones. You can
509 use this technique for any two <tags> on the same branch, even the
510 trunk. It is also possible to use tags on different branches, but
511 you'll have to ponder the meaning of the difference between those two
514 In place of one of the <tags>, you can use a <branch_tag> to refer to
515 the latest revision on that branch. See 4C.11 and 4C.3 for info on
518 Merges can also be performed by handing RCS revisions to the '-j'
519 options, but since revision numbers aren't the same in all files,
520 merging by number is normally limited to one file. Sets of files with
521 the exact same trees of branches and revision numbers would work too,
522 but that's a rare situation.
524 To "take" revisions from other branches instead of merging them, see
527 A way to gain the effect of merging the main to the branch is to
528 merge the branch into the main using the normal
530 cvs update -A {optional files}
531 cvs update -j <branch_tag> {optional files}
533 cvs tag -F -b <same_branch_tag> {optional files}
539 This also works, but is probably not officially supported:
541 cvs update -j N {optional files}
543 where N is a number. This will merge all the changes from the branch
544 point up to the highest revision on the main branch starting with N.
545 For example, if your highest trunk revision is 1.52, you can use this
546 to grab revisions from the trunk:
548 cvs update -j 1 {optional files}
550 Another example: Say you have a branch point at rev 1.2 for a branch
551 named "BR1" and trunk revisions 1.3, 1.4, 2.1, 2.2, 2.3, 3.1, 3.2.
554 cvs update -j 1 {optional files}
556 will merge the changes from 1.2 to 1.4
558 cvs update -j 2 {optional files}
560 will merge the changes from 1.2 to 2.3
562 cvs update -j 3 {optional files}
564 will merge the changes from 1.2 to 3.2, which in this example, is
565 equivalent to the use of "-j HEAD" in part A above.
567 The intuitive (at least to me):
569 cvs up -j MAIN (or TRUNK) {optional files}
571 doesn't work. If the trunk (i.e. "main branch") had an implicit branch
572 named "MAIN", you could use:
574 cvs up -j MAIN:10/26 -j MAIN:now {optional files}
576 and refer to date-stamped revisions on the trunk using the
577 <branch_tag>:<date> support that works on other branches.
579 You might also think you could place an explicit tag on branch 1 (or
580 higher) (e.g. MAINHACK:1) and use it in place of the implicit "MAIN",
581 but I haven't found the right combination.
583 [[If you find working techniques, I'll add them here.]]
585 Last modified: _6/13/1997_
587 8. How do I merge onto the Main Branch a file that exists only on a branch
588 other than the Main Branch? (i.e. it is in the Attic)
590 For how such a file can exist, see 3A.2 and 3A.3.
592 For how to avoid creating such a file, see 3A.5.
594 Though you might think that the "update -j" command could perform the
595 "merge" of a file from the side branch to the Main Branch, it isn't
596 (yet) smart enough. Unfortunately, there is no single CVS command to
597 do this -- it takes three steps:
599 To move something onto the Main Branch from the Attic, you have to
600 physically move the file from the Attic to the main Repository
601 directory associated with your working directory.
603 It is exactly like resurrecting a removed file. See 3L.4
605 I use something like this: (csh-like syntax)
607 set repos = `cat ./CVS/Repository` mv $repos/Attic/filename,v
610 (If you use relative paths in your Repository files, that first line
611 becomes: set repos = $CVSROOT/`cat ./CVS/Repository`)
613 Now that the file is physically in the right place within the
614 Repository, "update -A" will make it appear in your working directory
615 on the Main Branch. Do that now.
617 You now have a choice. The act of physically moving the file has
618 fused together the <branch_tag> branch and the Main Branch for this
619 file. You can continue that way, making changes along the RCS Main
620 Branch which CVS will (for this type of file only) treat as both the
621 Main Branch and the <branch_tag> branch.
623 The other choice, which I would suggest, is to re-tag the file with
624 <branch_tag>, restoring a normal-looking magic branch tag to the file:
626 cvs tag -F -b <branch_tag> <file>
628 After you have done the above, you can run "update -A" or "update -r
629 <branch_tag>" to resume whatever you were doing before you started
632 Caveat: The final result is a file whose revision tree doesn't look
633 like it was ever on any branch but the Main Branch until the above
634 "tag -F -b" command was executed. CVS and RCS have no way of saving
635 the history of the actions you have just performed.
637 Last modified: _6/13/1997_
639 9. How do I know what branch I'm (working) on?
644 and look at the "Sticky Tag" field for each file. If:
646 The *same* tag is on *every* file in your working tree, *and*
648 That tag matches the contents of the ./CVS/Tag file, *and*
650 That tag is a branch tag,
652 then you know what branch you are working on. You can get sticky Tag
653 information directly from the ./CVS/Entries file instead of "cvs
656 If all the sticky Tags don't agree, then your directory is temporarily
657 inconsistent. This is a feature allowing you to make changes (or
658 perform merges) to individual files on multiple branches without
659 checking out the whole directory.
661 The sticky Tag on each file in the ./CVS/Entries file (as displayed by
662 the "status" command) indicates what branch the working file is on.
663 New files are added to the Tag stored in ./CVS/Tag.
665 To force your entire working directory onto the same branch, type:
667 cvs update -r <branch_tag>
669 Last modified: _6/13/1997_
671 10. Do I really have to know the name of the branch I'm working on?
673 If a developer can't be relied on to know what branch of development
674 to work on, then either the developer's manager isn't planning
675 branches properly or the developer has serious problems.
677 I have found that one of the hardest concepts to get across to
678 developers (and some managers) is that "a branch in development" (as
679 opposed to the use of RCS branches to support some other scheme) is a
680 heavyweight act. Every time you create a real branch in development,
681 you must spawn a set of managerial procedures and a schedule by which
682 you plan to merge each branch into each other branch. Unless you plan
683 to keep it simple and collapse (by merging and forgetting) branches
684 quickly, they are not to be created lightly.
686 In other words, if you don't regularly attend group meetings in which
687 the branch to be worked on is a major topic of discussion, then the
688 group is not managing branches properly.
690 We created a couple major branches a few months ago and even the
691 customer service people refer to the "XYZ branch" as a shorthand for
692 "continuing development on the XYZ project".
694 Last modified: _6/13/1997_
696 11. How do I refer to the revision where I branched so I can see what
697 changed since the Branch Point on another branch?
699 Given the current <branch_tag> format, there is no direct way to refer
700 to the branch point, which is more useful in many ways than referring
701 to the branch, which always refers to the latest revision on the
704 When CVS adds a branch tag, it attaches an RCS symbol to a
705 non-existent revision number containing the revision number of the
706 branch point as a prefix. (See Section 3O, on the "tag" command.) RCS
707 can't use the CVS magic branch tag and many of the CVS commands can't
710 To be certain of your ability to refer to a branch point, you must
711 create a "branch point" tag at the same time as the Branch tag. See
714 Last modified: _6/13/1997_
716 12. Why didn't the command "cvs admin -bBRANCH1 *" create a branch?
718 Because your command creates an RCS branch, not a CVS branch. See the
719 above discussion on branches. RCS branches are used to support CVS
720 branches, but they are not the same. You can't act as if you have
721 direct control over the RCS files.
723 The "admin" command was placed there as a convenience to allow you to
724 execute raw "rcs" commands on the Repository, taking advantage of
725 CVS's ability to find the files in the Repository.
727 But you have to remember that you are using RCS commands on a CVS
728 Repository, which is not generally safe unless you know exactly what
731 For one thing, CVS insists on control of the default branch. It is set
732 either to the Main branch or the Vendor branch depending on whether
733 you have changed the Vendor's code. If you change the default branch,
734 you are monkeying with the internals and you will get unexpected
737 To set your "default CVS branch" to BRANCH1, you must use "checkout"
738 or "update" with the "-r BRANCH1" option. Then you have changed CVS's
739 idea of your "default branch", which has little to do with RCS's
742 Last modified: _6/13/1997_
744 13. Is it possible to set the "default CVS branch" for everyone?
746 No. It doesn't work that way.
748 When using CVS, all administrative information (such as what branch
749 you checked out) is stored in CVS sub-directories, local to the user.
750 There is no global state, other than the description and logging files
751 in the $CVSROOT/CVSROOT directory.
753 You tell "checkout" or "update" what branch you want to check out via
754 the "-r <tag>" option. The default is CVS's "Main Branch".
756 I don't see a problem in *designing* a new way to indicate what branch
757 you get by default, instead of the main one, but that's not how it
760 Last modified: _6/13/1997_
762 14. How do I perform a large merge?
764 Large merges require a bit more planning to be able to track what has
765 happened in the inevitable cases where something goes wrong. No tool
766 can force a "merge" to make perfect sense.
768 Though you can handle the details in many different ways, the two ends
769 of the spectrum of merge techniques are: gonzo and paranoid.
771 The gonzo method assumes that you know everything about your sources
772 so that recovery from failures is "just a matter of typing." You
773 created the branch this way:
775 cvs checkout <module>
777 cvs tag -b <branch_tag>
778 cvs update -r <branch_tag>
780 cvs commit <<== Onto branch
782 Now you want to merge your branch back into the Main branch, you are
783 certain you can make it work, or at least detect all the failures, so
784 you dive in and hack away: (For simplicity, we will assume you are
785 collapsing (i.e. merging and forgetting) a side-branch into the Main
786 branch from your single working directory.)
789 cvs update -j <branch_tag>
790 >>> Edit the 'C' files and remove the overlaps.
791 >>> Edit some more to make it all compile and work.
794 Looks simple. For more details on the output from the "update -j"
795 command, see 3P.2 and 4C.6.
797 Note: You could also checkout a whole new working directory and
798 perform the merge at the same time by replacing the two
799 update commands with these two commands:
801 cvs checkout -j <branch_tag> <module>
804 The paranoid way is more difficult, but it can catch all sorts of
805 problems. You created the branch this way:
807 cvs checkout <module>
809 cvs tag <branch_point_tag>
810 cvs tag -b <branch_tag>
811 cvs update -r <branch_tag>
813 cvs commit <<== Onto branch
815 The extra tag command places a non-branch tag on the Branch Point, an
816 act that makes it easier to do "diffs" later. Now we decide to perform
819 cvs tag <latest_on_branch_tag>
821 *1* cvs diff -r <branch_point_tag> -r <latest_on_branch_tag>
822 >>> *1* shows all the changes on the branch.
823 *2* cvs diff -r <branch_point_tag> -r HEAD
824 >>> *2* shows the changes on the trunk since branching.
825 cvs tag <premerge_tag>
826 cvs update -j <branch_tag>
827 >>> Edit the 'C' files and remove the overlaps.
829 >>> Verify that *3* matches *1*, except for line numbers.
831 cvs tag <just_merge_changes_tag>
832 >>> Edit some more to make it all compile and work.
834 cvs tag <after_merge_cleanup_tag>
836 The reason *3* and *1* match so closely is that they are the
837 differences between two pairs of starting points and ending points
838 after the same data was inserted. If they are significantly different,
839 you will want to figure out why.
841 NOTE: You will have to tell everyone to stay the hell out of the
842 Repository while you do this. If they commit something while you are
843 in the middle of a merge, your job will be much more difficult. If
844 they "update" at the wrong time, their work will be randomized until
845 you finish. It's better to call a halt.
847 See 3H.13 for some more information about dealing with merges after
848 import. The last part of the procedure is applicable to any large
851 Last modified: _6/13/1997_
853 15. Is a Vendor merge any different from a branch merge?
855 No. In most ways, a Vendor branch is exactly the same as any other
856 branch. In a Vendor merge, the data is append to the branch by the
857 "import" command, rather than by hand-editing, but the merge process
860 See the "import" command in section 3H.
862 Last modified: _6/13/1997_
864 16. How do I go back to a previous version of the code on a branch?
869 You can avoid digging into RCS revision numbers (executing "update
870 -r (rev)" on each file) by trying one of these:
872 Use non-branch tags as you normally would. Non-branch tags
873 attach to specific revisions, so a "tag (tag)" command would
874 mark the revisions you have in your working directory, which
875 are on your branch. If you need to retrieve them, use "update
878 Doing this overrides the sticky (branch-tag) attached to your
879 working directory with a non-branch tag, which means you won't
880 be able to commit until you again move forward to the end of
881 the branch with "update -r (branch-tag)".
883 Use the "update -r (branch-tag):(date)" trick.
885 This is almost like using the '-D' option, but it looks for
886 revisions extant on (date) only along the given branch.
888 As in #1, you can't commit to this kind of working area,
889 because it has a sticky date referring to revisions in the
892 [comment from the audience: You are dreaming..
893 this does not work.. try it, you get
894 No such tag: "MYTAG:May 1"
895 or similar. I wish it did because I need it. julian@whistle.com]
898 You can branch a branch.
900 If you add a branch tag to file in a working directory that was
901 checked out on a branch, you will branch the branch. This
902 works just fine, though you'll have to play some games to merge
903 everything back together again. You'll also create 6-part
904 revision numbers. (They'll be 8-part revision numbers if you
905 branch a branch that started out with some unmodified files on
906 the Vendor branch. Think about it. How does revision
907 1.2.4.2.4.2.2.1 grab you?)
910 (fixed formatting, kingdon@cyclic.com)
912 Last modified: _9/8/1997_
914 17. Once I've found the files I want, how do I start changing them? I keep
915 getting warnings about sticky tags.
917 What you probably did was type "cvs update -r <tag>" where <tag> is a
918 non-branch tag. "update" created a sticky tag for a specific revision,
919 not a branch. To start working right there, you have to create a
922 You have two choices.
924 You can do it in place and keep working:
926 cvs tag -b <branch_tag> <<== To tag the current files.
927 cvs update -r <branch_tab> <<== To move onto the branch.
929 You can do it "externally" and create a new working directory:
931 cvs rtag -b -r <tag> <branch_tag> <module>
932 cvs checkout -r <branch_tag> <module>
934 <module> can be a relative path within the Repository.
936 <tag> in the above is the non-branch tag you placed earlier
937 that caused the error in your question. Be warned that
938 if <tag> is not set on all the files (or all the right
939 revisions) you won't get exactly what you wanted.
941 Last modified: _6/13/1997_
943 18. Why do I get the latest files on the branch when I tried to "update -r
946 If "update -r <tag>" always retrieves the latest files on a branch,
947 then <tag> is really a <branch_tag>. A branch tag is supposed to be
948 used to grab a branch to work on. Since you can't modify a file in the
949 middle of a branch, checking out a <branch_tag> will give you the
950 latest revision on the branch.
952 If you want to "checkout" a specific collection of revisions, you must
953 use a "non-branch" tag. See the first part of 4C.16.
955 Last modified: _6/13/1997_
957 19. How can I avoid a merge? I just want to move the latest revision on my
958 working branch directly onto the trunk.
960 There is no direct way to do this using CVS, though the technique is
961 not difficult using shell commands. Here's one way:
963 Move your working directory to the Main Branch.
967 Use "update -p" to grab the latest revision on the branch and write
968 it over your working files. Make sure you don't have an modified files
969 -- you will lose them. The following is in "csh" syntax. Change the
970 wildcard to grab the files you want
972 foreach i (Makefile *.cc *.hh)
973 cvs update -p -r <branch_tag> $i > $i
976 Commit all the working files onto the Main Branch.
978 cvs commit -m 'Moved branch <branch_tag> onto MAIN'
980 You should experiment with the above before blasting everything.
982 Last modified: _6/13/1997_
984 20. How to I avoid merge collisions in the RCS $\Log$ data?
986 In short, you can't. The RCS $\Log$ keyword is handled differently
987 from all other RCS keywords.
989 On the info-cvs mailing list, there is a periodic discussion that goes
992 Question: How do I deal with $\Log$? Answer1: You can't do much with
993 it. Here's how it works. . . Answer2: I've found a limited way to use
994 it. . . Answer3: Get rid of it. $\Log$ is an abomination.
996 I tend to lean toward answer #3. There are only two sets of people who
997 would ever have access to logs stored within sources files, developers
998 and source customers.
1002 Log entries within sources files are notoriously incomplete, rushed,
1003 poorly phrased and in many cases incorrect, making them useless for
1004 debugging or file maintenance. I remember a maxim from "Software
1005 Tools" (I believe): "Read the code, not the comments." No managerial
1006 order or plan for programmer discipline will affect this in the real
1009 Log entries are usually in an unreadable mixture of styles. Many log
1010 entries are just plain meaningless. Some are foolish. Some are even
1011 insulting. Examples:
1013 "Corrected spelling of misspelling." "Bug fix." "Reversed stupid
1014 change in previous revisions." "If Joe could do his job, this would
1015 already have worked."
1017 Log entries are not managed well by the tools. Any merge can cause
1018 conflicts in the $\Log$ data. Branch merges produce incomplete logs.
1019 They can be edited into chaos and they are not regenerated. They waste
1020 space duplicating information available to the developer with a single
1023 Even if correct when originally entered, as changes are made to the
1024 file, log entries become false over time. Humans are not good at
1025 reading down through a list and remembering only the last change
1026 affecting something. Over time *most* of the log is wrong.
1028 Even if still correct, the log data is almost useless to developers
1029 without the code diffs. If you can get code diffs, you can display the
1032 For source customers the problem is even worse. The last thing you
1033 want to show customers is a hodge-podge of tiny comments about large
1034 changes followed by a series of emergency fixes before delivery. If
1035 you distribute sources, then you should provide documentation, or
1036 changelogs reviewed by people who won't let comments like "Fixed for
1037 stupid customer." out the door.
1039 Conclusion: Though some people would prefer to see in this FAQ
1040 techniques for making the $\Log$ entries the best they can be, I
1041 believe them to be a lost cause. My suggestion is to hunt down, root
1042 out and destroy all occurrences of $\Log$ and the unusable data
1043 attached to it wherever you may find it.
1045 Last modified: _6/13/1997_
1047 21. Why should I trust automatic merges?
1049 Some developers have the feeling that three-way merging doesn't work.
1050 They fear and distrust the way the "update" command automatically
1051 merges committed changes from the Repository into the working file.
1053 Experience has shown that most merges are utterly painless and most of
1054 the rest are easily resolved. The few conflicts that cause headaches
1055 are nearly all due to poor communication between developers, a problem
1056 no source control system can obviate.
1058 Some developers were troubled in the past by flaky Unix software. I
1059 can't say that everything is perfect, but the tools CVS depends on
1060 (RCS and diff, mainly) are fairly solid nowadays. They work.
1062 Since it does seem to work for most of us, the algorithm is unlikely
1063 to change soon. Why not test it on a couple trouble spots and if it
1064 works for you, use it for a while? Then you can make an informed
1067 Last modified: _6/13/1997_
1069 22. How does CVS decide if it can safely perform a merge?
1071 CVS can merge any text file, possibly discovering a conflict and
1072 leaving overlaps for you to edit. Editing the conflict markers out of
1073 the file is a moment's work, but resolving the conflict could take an
1074 arbitrary amount of time. CVS works to determine if it *should* merge,
1077 See 2B.6 for how the merge proceeds.
1079 Last modified: _6/13/1997_
1081 23. After resolving merge conflicts in a file, what if I want to keep my
1082 previous version, and not take any of the branch changes?
1084 If you want to retain your previous version, a version on the MAIN
1085 branch greater than 1.1 (one you committed there), just throw the
1086 merged file away and "cvs update" the file.
1088 You don't need to commit something to remember it. The tags you place
1089 before and after the merge should give all the handles you need to
1090 find various versions. You don't have to create a new version of the
1093 If you want to retain the previous Vendor revision, you can grab a
1094 copy of it using "cvs update -p" and commit it or use the technique
1095 described in 3B.3 to revert back to the Vendor branch.
1097 Last modified: _6/13/1997_
1099 Category: /Advanced_Topics_/Engineering/
1103 1. Where can I find out about Software Engineering?
1105 A couple different people suggested this book:
1107 Software Configuration Management: Coordination for Team Productivity;
1108 Wayne A. Babich; Addison Wesley; 1986; ISBN 0-201-10161-0
1110 A number of others suggested Appendix B of the book "Decline and Fall
1111 of the American Programmer" by Ed Yourdon, called "The Programmer's
1112 Bookshelf". It list 87 books you are expected to have read. Since they
1113 publish many of the books, Prentice-Hall distributes this list as
1114 "Prentice Hall Professional Technical reference PTR-125-AA3.
1116 One interesting item from the Yourdon book: The total number of
1117 professional computer books sold is less than the number of
1118 programmers currently in the United States. It wasn't clear from the
1119 book whether this meant "per year" or not, but it is still
1122 Last modified: _6/13/1997_
1124 2. How do I flexibly arrange the modules file to describe my sources?
1126 An equivalent question might be, "How do I structure my sources?" This
1127 can be a difficult question especially in the areas that are more
1128 political than technical.
1130 Generally you want to think about which pieces of your system need to
1131 be checked out together, built as one system or tagged as a consistent
1132 whole. You should certainly create module names that correspond to
1133 complete, buildable collections that you would tag and release as one
1134 "product". It is also convenient to create module names for small
1135 sections of the Repository containing files that will all be worked on
1136 at the same time by the same person or group.
1138 Once you have defined the structure of your work, you can usually see
1139 how to lay it out in a Repository. After that the modules file is
1140 easy. You set up module names and aliases to match what you need to
1141 check out by name. If you like relative directories, it is possible,
1142 but not recommended, to work completely without a modules file. See
1143 1D.11 and 2C.7 for some info about the modules file.
1145 Here are a few types of modules. You should experiment to see what
1146 kind of structure each of these produces. They all have different
1149 Connected projects in one group with two separate helper
1150 directories. The helper directories can contain build tools, header
1151 files, libraries, or whatever you like.
1153 These are all aliases that checkout relative pathnames. The equivalent
1154 results could be produced by placing the selected relative pathnames
1155 on the "cvs checkout" command line.
1160 pr12 -a P1 P2 HELPERS
1161 pr13 -a P1 P3 HELPERS
1162 pr23 -a P2 P3 HELPERS
1167 HELPERS -a group1/helper1 group1/helper2 MAKEFILE
1168 MAKEFILE -a group1/Makefile
1170 Actual Repository directory structure: (from $CVSROOT down)
1172 group1/ Makefile The top level Makefile. helper1/ helper2/ Helper
1173 files and dirs proj1/ Files and dirs proj2/ Files and dirs proj3/
1176 "checkout group1" produces a duplicate of the above. "checkout projX"
1177 produces all but "projY" and "projZ". "checkout projXY" produces all
1180 Here is the exact same set of module names describing the same
1181 Repository layout using module names (and aliases containing module
1182 names) instead of merely aliases for relative pathnames.
1184 There is one difference in the result. The name of the top level
1185 directory in the checked out working tree will match the "module" name
1186 (e.g. pr1) instead of always being "group1" as it was in the first
1189 pr1 group1 proj1 &HELPERS
1190 pr2 group1 proj2 &HELPERS
1191 pr3 group1 proj3 &HELPERS
1192 pr12 group1 proj1 proj2 &HELPERS
1193 pr13 group1 proj1 proj3 &HELPERS
1194 pr23 group1 proj2 proj3 &HELPERS
1196 HELPERS -a helper1 helper2 group1-Makefile
1197 helper1 group1/helper1
1198 helper2 group1/helper2
1199 group1-Makefile -d . group1 Makefile
1201 The above line (with the -d in it) says that when the module named
1202 "group1-Makefile" is checked out, the file named Makefile file will be
1203 found in a directory named $CVSROOT/group1 and will be checked out
1204 into a directory named '.', which obviously already exists.
1206 The & references say to interpret those pathnames relative to the
1207 directory where the whole module is stored. For the "pr1" module, that
1208 directory is "group1", so the &HELPERS reference winds up placing
1209 Makefile in '.' relative to "group1".
1211 A short one containing the basic "module" actions:
1213 m1 head/path file1 dir2 file3 dir4 file5
1215 When checked out, a directory named "m1" appears in your current
1216 directory. Elements named file1, dir2, file3, dir4, and file5 appear
1217 in it. They were originally taken as relative paths from
1220 Here's another way to construct a working directory out of pieces of
1223 projX projX Makefile &projX_inc &projX_src &projX_doc
1225 # The first line selects a single file within projX, plus
1226 # the contents of three other modules. Those three other
1227 # modules rename their directories.
1229 projX_inc -d include projX/inc projX_src -d source projX/src projX_doc
1230 -d documentation projX/doc
1232 A Unix tree. This is similar to what CVS was developed for and the
1233 way I have used it for years.
1240 usr-bin unix/usr.bin
1242 # Subdirs of top level dirs. (tiny subset)
1247 # Programs without subdirs. (tiny subset)
1248 cat unix/bin Makefile cat.c
1249 uniq unix/usr.bin Makefile uniq.c
1254 public localsrc/public
1258 cvs localsrc/gnu/cvs
1259 emacs localsrc/gnu/emacs
1260 rcs localsrc/gnu/rcs
1261 btoa localsrc/public/btoa
1262 tcsh localsrc/public/tcsh
1264 # X11 related items.
1265 tvtwm localsrc/X11/contrib/tvtwm
1267 "unix" was checked out and built from the top down, using a set of
1268 Makefiles that knew about the whole structure. "localsrc" was kept
1269 checked out in /usr/local/src.
1271 At any time I could run "checkout ls" or "checkout cat" and get a
1272 simple directory with only that tool in it, plus a subset Makefile
1273 that knew how to build that tool against the installed (or alternate,
1274 via environment variables) headers and libraries.
1276 I found it very handy to be able to run "ls" and see the three tools I
1277 was porting that week.
1279 Last modified: _6/13/1997_
1281 3. Can I have multiple source repositories, one for each project?
1283 Yes, you can have as many Repositories as you like. But each
1284 Repository must be managed separately, creating additional work.
1286 Question 4A.1 provides a short description of setting up a single
1287 Repository. A few additional considerations:
1289 It is a good idea to start by creating a single Repository and split
1290 it up (or create additional Repositories) only if you believe it is
1291 really necessary. I would only create a new Repository if the data is
1292 completely disconnected from the rest of the main Repository.
1294 If there is a lot of overlap among the developers working on the
1295 collections of files you want to place in different Repositories, or
1296 if there is any connection between those collections, I would go out
1297 of my way to create a single Repository. It is much easier to manage.
1299 Disk space should not be a factor since you can build up a
1300 Repository using symbolic links and/or remote mounts.
1302 Each Repository is completely distinct. You can't check out modules
1303 from different Repositories at the same time. A better way of looking
1304 at it is that if you *can* check out two modules or directories with a
1305 single "checkout" command (without contortions or explicit absolute
1306 pathnames), then they are in the same Repository.
1308 To "checkout" modules from multiple Repositories, you must use the
1309 "cvs -d" option on all CVS commands or alter your $CVSROOT variable
1310 when you change focus to another Repository. If you work with multiple
1311 Repositories, it is a good idea to configure CVS to use absolute
1312 pathnames in the ./CVS/Repository file, since most commands (other
1313 than "checkout") will use that file rather than $CVSROOT.
1315 If you configure CVS to use relative pathnames in your
1316 ./CVS/Repository files, you must always be careful to set your
1317 $CVSROOT properly or you will get unexpected results.
1319 If you have two modules or directories by the same name at the same
1320 relative path inside two different Repositories, you are asking for
1321 disaster. You could unexpectedly update a directory with completely
1322 unrelated files. This is not a fanciful example -- a Repository is
1323 occasionally duplicated for release purposes in which case *all* the
1324 paths in the two Repositories are the same.
1326 Last modified: _6/13/1997_
1328 4. Who should administer the Repository and manage the modules file?
1330 This is a "management style" question. In large or traditional groups,
1331 the CVS procedures are warped to conform to local conventions. In
1332 small groups, in groups with strong personalities or on new projects
1333 the choice of source control procedures can help create some of the
1334 working environment. Here is a taxonomy of environments I have worked
1335 in or helped set up:
1339 A small number of competent developers working on a medium size
1340 project. We all got along and we all respected each other (at least
1341 technically). Anyone edited anything.
1343 Modules and Repository admin was mostly left to me. I never found a
1344 problem in minor changes made by anyone else.
1348 A large number of experienced developers sprinkled with wackos. Many
1349 of the developers didn't want to deal with any kind of source control.
1350 They wanted a full-service source control system that caused them zero
1353 I learned "big stick" diplomacy here. There was a small number of
1354 "designated" (by me) people who were allowed to do *anything* other
1355 than "update" and "commit". Even "checkouts" were controlled. This is
1356 where I found "history" and "release" the most useful.
1360 A small number of developers who wanted me to "help", but who didn't
1361 want to deal with anything other than their favorite algorithms.
1363 I didn't have the time to baby-sit this group, so I designated one of
1364 them to be my official contact and made him do it all. He felt sullied
1365 by the requirement to pay attention to anything other than his pet
1366 coding projects, but enjoyed the "status" of being the only one who
1367 could touch the control files without my kicking the chair out from
1372 A huge number of developers of covering the whole spectrum of
1373 competence and experience split into 20 groups, none of which
1374 cooperated with the others, working on 57 different projects, most of
1375 which didn't inter-operate.
1377 Managing it in any coherent way was not my responsibility (and beyond
1378 my tolerance for chaos). Too many people. So I privately designated a
1379 person in each group to be the contact and kept watch on the
1380 Repository activity. When something went wrong, I notified the contact
1381 for the group and told him what was happening and *he* kept his troops
1382 in line. They were tougher with their own group that I would have
1385 Eventually only a few people were willing to touch the control files,
1386 since they were flamed from all directions if they screwed up.
1390 In a medium group of really *serious*, and seriously overworked,
1391 people, someone else was designated the "master". I convinced the
1392 master I knew what I was doing and went on my way.
1394 No one else in the world was allowed to touch anything.
1398 In a large amorphous group of beginners, experts and clowns, over whom
1399 no one had official control, I was forced to employ a group of
1400 relative beginners (who became experts rather quickly) to police the
1401 world. The ultimate in locking the barn after the horse was stolen, we
1402 kept Chaos from destroying us only by use of superior firepower.
1404 My choice, if allowed, is to let anyone touch anything. I keep backups
1405 of important items and let people know individually whether I want
1406 them to touch things or not. If someone on my "no touch" list touches
1407 and succeeds, they are allowed more slack. If they screw up after
1408 being warned, their screwup becomes public. After a few months, I
1409 usually have no trouble keeping the world running smoothly, at least
1410 from my (and CVS's) perspective.
1412 Last modified: _6/13/1997_
1414 5. Isn't disk space a big factor? CVS copies files out of the Repository,
1415 duplicating everything.
1417 Everyone knows that disk space is getting cheaper. How do we reconcile
1418 this with the equally well-known problem that *all* disk is *always*
1421 In my opinion, the main reason disk space will never be an unlimited
1422 resource is that it is the major variable in organizational time/space
1423 tradeoffs. It isn't a problem of waste or an aspect of Murphy's law,
1424 as some claim it is, but rather a direct consequence of good
1425 management. Disk space is, and will always be, a limited resource.
1427 First, the cost of *deploying* that disk is not dropping as fast as
1428 the cost of the storage medium. The cost of machines to hold the disks
1429 and the networks to connect them are dropping more slowly than disk
1430 media. And the cost of the human time necessary to manage the
1431 machines, networks, disks, and the developers using them, is not
1432 dropping at all. The cost of human time continues to rise.
1434 If management decides that expensive human time can be saved by using
1435 all that new disk space to keep the last three releases online, then
1436 that's what it will be used for. If each release takes up a Gigabyte
1437 and you support 30 platforms, a simple time-saving suggestion has just
1438 grabbed 100 Gigabytes of disk space. And we've ignored the potential
1439 disk storage needed to support "better Customer Service", another
1442 Even at 30 cents per Megabyte (next year's price), you've just used up
1443 $30,000 of disk space. And that doesn't count the computers, tape
1444 drives and humans necessary to maintain and deploy all of it. Spending
1445 money to save time has its own overhead, too.
1447 Binaries are getting bigger. Graphics and data collection devices can
1448 eat up any amount of disk. There are more tools available, more
1449 libraries, more raw data than you can ever store. My home computer has
1450 a Gigabyte of disk on it. It could easily handle 30.
1452 The "economy" of disk storage media will never remove the need to
1455 So, here's an un-reviewed suggestion originally from Graydon Dodson
1456 <grdodson@lexmark.com>, which I've altered and edited heavily.
1458 - Keep a directory where the whole tree is checked out. (It might be
1459 built and tested once in a while to make sure it is worth linking to,
1460 but that doesn't affect the source control aspect of this procedure).
1461 Let's call it /master/build.
1463 - Write a tool that creates a tree of directories (like the X11
1464 "lndir" command) filled with links to the checked out files in the
1467 This tool should also provide real copies of, not symlinks to, all the
1468 files within the CVS administrative directories.
1470 - You could also provide a way for the tool to take a list of whole
1471 directories that you will never change, for which it would create a
1472 single symlink to the directory and not a subtree of symlinks to
1473 files. Or you could rm -r pieces of the resulting working directory
1474 yourself and replace it with links.
1476 - If you want to edit a file, you have to grab a real copy and keep it
1477 until your revision shows up in the /master/build tree. I'd create a
1478 script to do this: cvsgrab <file>
1483 echo "file $f is not a symlink"
1487 set rev = `grep "^/$f/" CVS/Entries | awk -F/ '{print $3}'`
1488 cvs update -p -r $rev $f > $f
1490 You can't do a plain "cvs update" since that would grab newer
1491 revisions from the Repository, not the revision you wanted to start
1492 with. After the file is no longer a symlink, you can work normally.
1493 You'll have to run "update" before "commit" anyway if there are newer
1496 - Presumably there would also be a tool to traverse the link tree and
1497 revert it to links if there are no modified files and/or if all the
1498 real files match the revision of the /master/build tree.
1500 - To avoid confusing CVS when the /master/build revisions are updated
1501 but your CVS/Entries files is not, CVS would have to change to handle
1502 symlinks. It currently causes problems with this scenario:
1504 ./<file> is a symlink.
1506 ./CVS/Entries says you are revision 1.2.
1508 The corresponding CVS/Entries file in /master/build says the latest
1511 cvs update <file> shows a 'C' conflict flag.
1513 Last modified: _6/13/1997_
1515 Category: /Advanced_Topics_/Installing_CVS/
1519 1. What do I have to do before I install CVS?
1521 You must decide where to set up a Repository.
1523 Though you can construct a Repository tree structure using links and
1524 mount points, there must be a single copy of each real file across
1525 your entire organization. You may not "rdist" files and expect to edit
1528 CVS does not support a truly distributed Repository. You can have
1529 multiple Repositories, but each one must be mounted (not copied or
1530 "rdist"ed) from a single place onto all machines where it will be
1533 Initially, a Repository takes about same amount of disk space as the
1534 sources you want to put into it, plus a bit of overhead for the RCS
1537 See Section 4B. For multiple Repositories, see 4G.3
1539 You need a directory in everyone's $PATH variable where you can
1540 install all the executables. /usr/local/bin is a common place.
1542 You need some helper tools besides CVS such as "RCS" and a good set
1543 of "diff" and "diff3" programs. See 1B.4 for suggestions.
1545 Read the README, INSTALL and ChangeLog files to see what you are
1548 Though you can probably muddle along without it, you should appoint
1549 one or more "Repository Administrators" who will be responsible for
1550 maintaining the Repository structure, administrative files and the
1551 "modules" interface.
1553 Someone at your site should probably be on the info-cvs mailing list.
1556 Last modified: _6/13/1997_
1558 2. How do I configure the CVS programs?
1560 You should certainly start by reading the README file, the INSTALL
1561 files and possibly the ChangeLogs in each directory, the Makefile.in
1562 files and the "cvsinit.sh" program.
1564 Execute the ./configure command.
1568 After running "make" you might try running the "sanity.sh" script:
1569 ./src/sanity.sh `pwd`/src/cvs
1571 It writes into /tmp/cvs-sanity by default.
1573 Finish reading the INSTALL file and test out the system.
1575 Last modified: _6/13/1997_
1577 3. What do I have to install?
1579 Install the "cvs" executable and "mkmodules" from the CVS sources.
1580 The man page is useful too. If you plan to report bugs, you should
1581 also install "cvsbug".
1583 Set your $CVSROOT environment variable and create the Repository
1584 (which you planned out in 4A.1) with the "cvsinit" command at the top
1587 You'll need to edit the Repository control files created by
1590 Install any helper programs mentioned in the modules file.
1592 Last modified: _6/13/1997_
1594 4. How do I work around the merge problems in GNU diff version 2.1 or
1597 See 1B.4 If you use recent versions of RCS and "diff", you won't run
1598 into the above. If you do, see 5B.8
1600 Last modified: _6/13/1997_
1602 Category: /Advanced_Topics_/Internal_errors/
1604 " + Internal errors"
1606 1. Explain: "ci error: unexpected EOF in diff output"
1608 RCS versions earlier than 5.5 print the above error when a file does
1609 not end in a newline character. It can be caused by:
1611 - Editing with Emacs and not using "require-final-newline".
1612 - Committing a binary file.
1613 - Filesystem failures (NFS!) that put nulls in your file.
1615 The solution is to upgrade to RCS 5.5 or later. (Of course, this won't
1616 fix filesystem failures. It will merely allow RCS (and therefore CVS)
1617 to handle the file without error.)
1619 Last modified: _6/13/1997_
1621 2. Explain: "RCS file /Repository/module/file.c,v is in use"
1623 This is an RCS error that occurs when its internal lock file has been
1624 left around by an RCS command interrupted by some sort of system
1625 crash, disk failure or SIGKILL signal.
1627 Go into the Repository and look for files with names similar to
1628 "file.c,v", usually starting with ',', '_' or '#'. Make sure they are
1629 really crash remnants and do not belong to transactions in progress --
1630 a recent last-modified timestamp is a good indicator of a live
1631 transaction. Delete them if they are old.
1633 Last modified: _6/13/1997_
1635 3. Explain: "co error, line 2: Missing access list"
1637 This is an error message from RCS Version 3 when it tries to read a
1638 file created by a later version of RCS.
1640 HP decided to "standardize" on an ancient version of RCS some time
1641 ago. You can't use it for CVS. See 4H.6.
1643 Since the error comes from having a later version of RCS than HP
1644 supports, you probably did install the later version but must have
1645 recently changed your $PATH or installed the HP package that has RCS
1648 You should either reconfigure CVS to use absolute pathnames to the
1649 proper versions of the RCS programs that CVS uses, or change your PATH
1650 to look there first. If you haven't installed the latest version of
1651 RCS, you should upgrade. See 1B.4
1653 Last modified: _6/13/1997_
1655 4. Explain: "error: RCS file name `xyz .c' contains white space"
1657 RCS 5.6 doesn't allow white space in filenames. Apparently this
1658 restriction will be removed in RCS 5.7, but CVS may still require that
1659 filenames have no white space in them.
1661 Last modified: _6/13/1997_
1663 5. Explain: cvs checkout: warning: <X> is not (any longer) pertinent
1665 This message occurs in three instances:
1667 When there is an entry in the ./CVS/Entries for file <X> and there
1668 is no RCS file in the Repository to back it up.
1670 If the working file exists, and hasn't changed (determined from the
1671 timestamp) it is removed.
1673 When you try to check out a piece of the Repository with:
1675 cvs checkout some/place/in/repository/tree
1677 and at least the first element of the path (i.e. "some" in the above)
1678 exists, but some part of the rest of it does not.
1680 The checkout command checks the modules file first for the whole path,
1681 then for a prefix of the path as a module name. If it doesn't find
1682 *any* portion of your path in the modules file, it says:
1684 cvs checkout: cannot find module `<module/path>' - ignored
1686 If it finds some set of prefix directories, it prints the message you
1689 In practice this is usually a spelling error.
1691 If the Repository files you are trying to check out or update are
1692 not readable by you, the same problems can occur. Check the
1693 permissions on the files involved.
1695 Last modified: _6/13/1997_
1697 6. Why did a Repository file change from <file>,v to ,<file>,?
1699 This is an RCS problem, since the ,<file>, syntax for file names is
1700 used by RCS and not CVS.
1702 RCS constructs a new <file>,v in a temporary file named ,<file>,
1703 (which doubles as a lock file) then renames it to <file>,v when it is
1704 done. The only way this is reliable is if your system's version of
1705 rename(2) is an atomic, as required by POSIX.
1707 If your system has a non-atomic (and therefore non-POSIX) rename(2)
1708 system call, RCS runs uses an internal version of this algorithm to
1709 approximate the atomic rename:
1711 rm <file>,v; ln ,<file>, <file>,v; rm ,<file>,
1713 If the system crashes, or you lose your NFS connection between the
1714 first "rm", but before the "ln", you can be left only with the
1715 ,<file>, file. If the crash or network failure occurs between the "ln"
1716 and the final "rm", you could be left with a pair of linked names.
1719 - If only the ,<file>, exists, rename it to <file>,v.
1721 - If both ,<file>, and <file>,v exist and are linked, remove the
1724 - If both ,<file>, and <file>,v exist and are separate files, look at
1725 the dates, "diff" them and make your best guess. This sounds like the
1726 remnants of two separate events.
1728 Last modified: _6/13/1997_
1730 Category: /Advanced_Topics_/Other_Systems/
1734 1. I use a NeXT. Is there anything I need to know?
1736 NeXTSTEP 3.0's Interface Builder uses "nib" directories, rather than
1737 the files used in previous revisions. It removes files it doesn't
1738 recognize, making it impossible to place such a directory under CVS --
1739 the CVS admin directory will be removed.
1741 Some time ago, <Bob_Vadnais@pdh.com> posted a palette named CVSPalette
1742 that claimed to resolve this problem. It was intended to preserve the
1743 CVS administrative directories within nib documents (directories) that
1744 Interface Builder usually removes.
1746 CVSPalette is no longer in its announced place:
1748 ftp.cs.orst.edu:/pub/next/submissions
1750 though I did find two other interesting files on ftp.cs.orst.edu:
1752 /software/NeXT/sources/tools/cvs-next-2_1_1.tar.Z
1754 which is a port of CVS 1.3 (along with RCS and diff) and:
1756 /software/NeXT/sources/programming/cvs.postamble-2.4.gz
1758 which appears to be a set of wrappers for CVS commands that claim to
1759 allow you to use CVS effectively (and without need for the "command
1760 line") on a NeXT machine.
1762 [[Anyone know the truth about CVS and NeXT?]]
1764 Last modified: _6/13/1997_
1766 2. I use OS/2 and/or DOS and/or Windows. Is there anything I need to know?
1768 When using a local repository, be sure to specify the local access
1769 method or CVS will interpret the drive letter as a remote host name
1770 due to the : following it:
1772 WRONG: CVSROOT=C:\SRC\CVSROOT
1774 RIGHT: CVSROOT=:local:C:\SRC\CVSROOT
1776 (larry.jones@sdrc.com)
1778 You can share RCS files between Unix and DOS while avoiding the MS-DOS
1779 file name limits by setting your RCSINIT environment variable to
1780 '-x/,v'. New RCS files will be created without the standard ",v"
1781 suffix, though files ending in ",v" will still be found if there is no
1782 matching file in the same directory without the ",v".
1784 Erik van Linstee offers an OS/2 and a DOS port of CVS 1.3 in:
1786 ftp.informatik.tu-muenchen.de:/pub/comp/os/os2/gnu/devtools or
1787 ftp.rrzn.uni-hannover.de:/pub/os2-local
1789 The files are named:
1793 Where the ? stands for the patch level (currently 8) and the b is for
1794 the binaries, the s for the sources.
1796 There are three binaries. An OS/2 only one (32-bit), a DOS only one
1797 (16-bit) and an EMX one that runs on both (32-bit).
1799 There are many differences between the Unix and the DOS versions of
1800 CVS. Read the material that comes with the DOS version before using
1805 Last modified: _9/22/1997_
1807 3. I use SCO Unix. Is there anything I need to know?
1809 On SCO/UNIX 3.2 V2.0 POSIX signals don't work. Unfortunately the
1810 configure program detects POSIXness and configures in the use of POSIX
1811 signals. Workaround : Edit out the check for POSIXness in the
1812 configure script. [[You could also remove all occurrences of
1813 "-DPOSIX=1" from the Makefiles after configure is run. -dgg-]]
1815 SCO/UNIX doesn't understand #!/<some shell> syntax. This breaks the
1816 use of log.pl as it gets invoked by /bin/sh instead of
1817 !#/usr/local/bin/perl. WorkAround : edit log.pl and change it into a
1818 shell script which invokes perl with log.perl (renamed from log.pl) as
1820 Contributed by Joe Drumgoole
1822 Last modified: _6/13/1997_
1824 4. I use AIX. Is there anything I need to know?
1826 The only report on AIX claims to have no trouble using it in concert
1827 with SunOS and IRIX platforms.
1829 Last modified: _6/13/1997_
1831 5. I use IRIX. Is there anything I need to know?
1833 If you see "uid" numbers where you would expect user names, try adding
1834 -lsun to the link line. Without it CVS is unable to retrieve "passwd"
1837 Last modified: _6/13/1997_
1839 6. I use an HP system. Is there anything I need to know?
1841 HP distributes RCS version 3 (a circa 1983 release!) with HP-UX. CVS
1842 does not work with RCS version 3; it requires RCS version 4 or later.
1843 Your best bet is to find the latest version of RCS and install it
1846 HP-UX 8.07 has a serious bug with the mmap system call and NFS files;
1847 the bug can crash the operating system. Make sure that you configure
1848 RCS to avoid mmap by setting has_mmap to 0 in RCS's conf.h. This bug
1849 is fixed in HP-UX 9.
1851 Contributed by Paul Eggert
1853 If using the setgid() trick described in 4D.13, you will have to
1854 create an entry in the /etc/privgroup file to give the group assigned
1855 to the cvs executable setgid permission (see setprivgrp(1m)).
1856 Additionally, if you are restricting "read" access to the Repository
1857 by limiting access to the executable (this requires yet another
1858 group), then you will require that /etc/logingroup exists and is
1859 configured correctly (usually it's just alink to /etc/group).
1861 Contributed by Dale Woolridge
1863 Last modified: _6/13/1997_
1865 7. I use AFS. Is there anything I need to know?
1867 There is a problem with the way CVS performs its locking when the
1868 files are within AFS. When your current PTS id != your uid, the locks
1869 are not deleted. The stat() system call returns the PTS id of the
1870 owner. If that id != your uid, CVS assumes you did not lock it, and
1871 leaves the lock files alone. The next time you try to use it, it
1872 complains that someone has the repository locked.
1874 Contributed by Michael Ganzberger
1876 [[This was against CVS 1.3. Is it still in CVS 1.4?]]
1878 Last modified: _6/13/1997_
1880 8. I use A/UX. Is there anything I need to know?
1884 Last modified: _6/13/1997_
1886 Category: /Advanced_Topics_/Related_Software/
1888 " + Related Software"
1890 1. How do I use CVS under Emacs? Is there an Emacs cvs-mode?
1892 The pcl-cvs package distributed with CVS is an emacs package that
1893 helps with the update/commit process. When you are ready to update,
1894 you use the 'cvs-update' command within emacs. This executes "update"
1895 and fills a cvs-mode buffer with a line for each file that changed.
1896 The most helpful features are: descriptive words for what happened
1897 (i.e. Merged or Conflict rather than 'U' or 'C'), single keys bound to
1898 diffs and commits, and the ability to mark arbitrary groups of files,
1899 possibly from different directories, for commit as a whole.
1901 All the developers in my group that use emacs find pcl-cvs a much
1902 friendlier and more helpful way to update/commit than raw cvs. One vi
1903 user even converted to emacs just to use pcl-cvs.
1905 Contributed by Jeffrey M Loomis
1907 Last modified: _6/13/1997_
1909 2. What is GIC (Graphical Interface to CVS)?
1914 GIC provides a graphical user interface to the Concurrent Version
1915 System (CVS), a powerful revision control system. GIC is
1916 implemented in the Tcl/Tk programming language and is intended to
1917 augment the sometimes cumbersome CVS command line interface.
1919 Note that according to the official GIC page at
1920 http://www.cpsc.ucalgary.ca/redirect/grouplab/projects/gic/
1921 GIC is no longer being maintained and tkCVS is recommended
1924 For more on tkCVS, see
1925 <http://ximbiot.com/cvs/cvshome/dev/addontkcvs.html>.
1929 Last modified: _9/6/1997_
1933 CAVEMAN is a front end to CVS written in PERL providing a collection
1934 of features desired by the site where it was developed.
1936 - The ability to spread a "project" over multiple Repositories.
1937 - Optional automatic tagging after each commit.
1938 - Additional locking of files.
1939 - Extra before and after program hooks.
1940 - A layer of event logging.
1941 - All sorts of error messages.
1942 - Many changes to the semantics of commands.
1944 It is available via anonymous ftp on ftp.llnl.gov [128.115.54.18] in
1945 gnu/caveman_vX.Y.Z.tar.gz (The numbers X, Y, & Z vary.)
1947 contact Kathleen Dyer kdyer@llnl.gov
1951 [[Does someone want to elaborate?]]
1953 Last modified: _6/13/1997_
1955 Category: /Advanced_Topics_/Setting_up_and_Manag/
1957 " + Setting up and Managing the Repository"
1959 1. What do I do first? How do I create a Repository?
1961 First, install all the programs. (See Section 4A.)
1963 Then create a Repository by executing "cvs -d init". (This works with
1966 Now you can configure your repository by checking out CVSROOT: "cvs -d
1967 checkout CVSROOT". Change into the created directory CVSROOT. Edit the
1968 files you want to edit, and afterwards, commit the changes by typing
1971 You will certainly want to add modules of your own. Edit the "modules"
1972 file and add lines to describe the items you want to "checkout" by
1973 module name. Here's a short list that could be used for storing a
1974 small number of GNU and PD sources:
1979 emacs local/gnu/emacs
1983 pdprog1 local/public/pdprog1
1984 pdprog2 local/public/pdprog2
1991 Last modified: _4/21/1998_
1993 2. What are those files in $CVSROOT/CVSROOT?
1995 There are eight Repository control (or "database") files of interest
1996 in the CVSROOT directory:
1998 modules contains the "modules" database. See 1D.11, 2C.7, 4B.6 and
1999 4B.7 for more details.
2001 commitinfo contains two columns: 1. a regular expression to match
2002 against pathnames within the Repository and
2004 a <command> to execute for matching pathnames.
2006 When you execute "commit", CVS passes the Repository pathname for each
2007 directory (and the files to commit within that directory) to
2008 <command>. If <command> exits with a non-zero status, the commit is
2011 A <command> associated with a pathname of "DEFAULT" is executed if
2012 nothing else matches. Every <command> associated with a pathname of
2013 "ALL" is executed separately.
2015 rcsinfo contains the same first column as commitinfo, but the second
2016 column is a template file for specifying the log entry you are
2017 required to enter for each commit.
2019 "DEFAULT" and "ALL" work the same as in the commitinfo file.
2021 editinfo contains the same two columns as commitinfo, but the
2022 <command> in the second column is intended to do some consistency
2023 checking on the commit log.
2025 "DEFAULT" works as in commitinfo.
2027 loginfo contains the same two columns as commitinfo, but the
2028 <command> is expected to read a log message from its standard input.
2029 The <command> can do anything it wants with the log information, but
2030 normally it is appended to a log file or sent to mailing lists.
2032 "DEFAULT" & "ALL" work the same as in commitinfo.
2034 cvsignore contains "ignore" patterns that are added to the built-in
2035 ignore list. See 2D.10.
2037 checkoutlist contains a list of other files kept under RCS in
2038 $CVSROOT/CVSROOT that should be checked out by mkmodules to provide a
2041 history contains a stream of text records, one for each event that
2042 the "history" command is interested in. Though the contents of the
2043 history file can be read, it is intended to be read and displayed by
2044 the "history" command. This file is the only one in the above list
2045 that is not under RCS.
2047 Last modified: _6/13/1997_
2049 3. Is there any other state stored in the Repository besides in the
2050 $CVSROOT/CVSROOT directory?
2052 Only in the RCS files. The Repository holds exactly two things: the
2053 tree of RCS files (each usually ending in ",v") and the CVSROOT
2054 directory described above.
2056 Last modified: _6/13/1997_
2058 4. How do I put sources into the Repository?
2060 There are three main ways to put files in the Repository:
2062 Use the "import" command described in Section 3H.
2064 This method is the fastest way to put trees of new code into the
2065 Repository and the *only* way to handle source releases from a 3rd
2066 party software vendor.
2068 Use "add" followed by "commit".
2070 This is how to add new files and directories to the Repository, a few
2071 at a time. Directories don't need to be committed.
2073 You can move RCS files directly into the Repository.
2075 You should create a directory hierarchy to hold them, but you can just
2076 move arbitrary ",v" files into the Repository. The only "state" in the
2077 Repository other than within ",v" files is in the required CVSROOT
2078 directory at the top of the Repository.
2080 Last modified: _6/13/1997_
2082 5. What file permissions should I use on (and in) the Repository?
2084 If you are using pserver (password-authenticated access), see below.
2086 If you run a completely open environment (which usually means that you
2087 don't have, or don't want to waste, the time to deal with it):
2089 - Set all directory permissions to 777.
2091 - Have everyone set their umasks to 0.
2093 (BTW, I don't suggest this. I am merely reporting it.)
2095 If you are a normal Unix shop and want to use groups effectively:
2097 - Set all the directory permissions in the Repository to 775.
2099 If you are using a system that handles both System V and BSD
2100 filesystems, you might have to set the permissions to 2775.)
2102 If you are using one of the many recent versions of Unix that don't
2103 allow you to use the full octal mode, then you'll have to type: chmod
2104 u=rwx,g=rwx,o=rx,g+s dir>
2106 - Change all the groups on the directories to match the groups you
2107 want to write to various directories.
2109 - Make sure every user is in the appropriate groups.
2111 - Have everyone set their umask to 002, including root.
2113 If you don't want non-group members to even read the files, do the
2116 - Repository directory permissions to 770. (or 2770)
2120 If you work in an environment where people can't be trusted to set
2121 their "umask" to something reasonable, you might want to set the umask
2124 mv /usr/local/bin/cvs /usr/local/bin/cvs.real
2125 cat > /usr/local/bin/cvs
2127 umask 2 # Or whatever your site standard is.
2128 exec /usr/local/bin/cvs.real ${1+"$@"}
2131 Pserver (Password-Authenticated Access) <blome@de.ibm.com>
2133 The above suggestions are not valid when you use the pserver facility.
2134 Be sure to read and understand the manual section about this (should
2135 be 4.6.something). Above all: do /not/ make the repository and CVSROOT
2136 group writeable. In CVSROOT, make `history´ group or world writeable
2139 I suggest creating one unix group per project group. In the
2140 repository, you would then create one directory for each group, group
2141 writeable. New projects must then be created in these group
2142 directories. If you don't want to say <group>/<project> on
2143 checkout, create a <project> module and point it there.
2145 Last modified: _9/24/1998_
2147 6. How do I structure my Repository?
2149 The Repository holds your software. It can be all interrelated or it
2150 can be a bunch of separately managed directories.
2152 How you break a whole system down into its component parts, while
2153 defining interfaces between them, is one aspect of "Software
2154 Engineering", a discipline that requires the study of dozens of
2155 strange and wonderful areas of the computer and management worlds.
2157 CVS provides a way to keep track of changes to individual files, a way
2158 to "tag" collections of files, and a way to "name" collections of
2159 files and directories. That's all. Everything else is in the way you
2162 In other words, you should structure your Repository to match your
2163 needs, usually tied in with the other tools you use to build, install
2164 and distribute your work. Common needs include the ability to:
2166 - mount (or automount) directories from many places in your
2168 - check out just what you need and no more.
2169 - check out multiple sections in a fixed relation to each other.
2170 - check out large sections to match the assumptions built into your
2171 build system. (Makefiles?)
2173 In my opinion, you should start small and keep everything in one tree,
2174 placing each major sub-system into a separate directory. Later, when
2175 you know what you are doing, you can make it more sophisticated.
2177 Last modified: _6/13/1997_
2179 7. Why would anyone use "modules"? They are too restrictive. I want to be
2180 able to select just the files I want to edit.
2182 Any form of structure is restrictive. If you believe that total chaos
2183 is a viable working paradigm, or if you believe you can keep track of
2184 the interrelations between all portions of your Repository in your
2185 head, then you can do what you please.
2187 If you believe that systems of files require management and structure,
2188 then the "modules" idea is very useful. It is a way to impose a naming
2189 scheme on a tree of files, a naming scheme that can be simpler than a
2190 large list of relative pathnames.
2192 The "modules" file represents a published interface to the Repository
2193 set up by your Repository Administrator. If s/he did a creditable job,
2194 the modules offered will be internally consistent and will smoothly
2195 interact with the rest of your environment.
2197 Last modified: _6/13/1997_
2199 8. How do I rename a file or directory? What are the consequences?
2201 In CVS there is no single "rename" command.
2203 See 2C.4 for the suggested way to rename a file or directory.
2205 The rest of this section covers some of the consequences of renaming.
2207 A "renaming database" has been proposed that would keep track of name
2208 changes so that "update -r <tag>" would continue to work across the
2209 renaming. But as it stands, you have to pick one of the following
2212 Use the technique described in 2C.4. (For each file, duplicate the
2213 file in the Repository, "remove" the old version so it winds up in the
2214 Attic and strip all Tags off the new version.)
2216 - "update -r <tag>" produces the correct files.
2218 - The duplicated revision history can be slightly misleading.
2220 - A plain (i.e. without the "-r <tag>") "checkout" or "update -d" will
2221 create directories "renamed" this way, but you can delete it and a
2222 plain "update" won't bring it back.
2224 Move the files and directories in the Repository to the new names.
2226 - You save the revision history under a different file name.
2228 - You save a little space.
2230 - "update -r <tag>" produces the wrong files or directories.
2232 This is not a good general solution, but if you plan never to look
2233 back (someone may be gaining on you!), it is sometimes a useful
2236 If you are clever with Makefiles, you might be able to rework them to
2237 handle either the new or old names, depending on which ones exist at
2238 the time. Then you can move an old <tag> onto the new, more
2239 sophisticated, revision of the Makefile. (Yes, this changes the
2240 "released" file if <tag> indicates a release. But it is an option.)
2242 - Important Note: If you rename a directory, you must rename the
2243 corresponding directory in every checked-out working directory. At the
2244 same time, you must edit the pathname stored in the ./CVS/Repository
2245 file within each of the moved directories.
2247 The easiest way to move a lot of directories around is to tell
2248 everyone to remove their working directories and check them out again
2251 - The file exists in the working directory and in the ./CVS/Entries
2252 file, but not in the Repository. For the old file, "update" prints:
2254 cvs update: xyz.c is no longer in the repository
2256 and deletes the file. If the file was modified, "update" prints:
2258 cvs update: conflict: xyz.c is modified but no longer in the
2261 and leaves the file alone. In the new directory, you see:
2265 as you would if someone else executed "add" and "commit".
2267 For each file, copy the working file to a new name in the working
2268 directory and use the "cvs remove" to get rid of the old old file and
2269 "cvs add" to add the new one. Since there is no way for CVS to remove
2270 a directory, this only works for files.
2272 - This is what most people think of first. Without a "rename" command,
2273 the remove/add technique seems obvious.
2275 - You lose the connection of your new working file to its past
2278 Last modified: _6/13/1997_
2280 9. What are "Attic" directories?
2282 When you use the "remove" command on a file, CVS doesn't delete the
2283 file, it only registers your desire to delete it.
2285 When you "commit" a removed file, CVS moves the Repository's matching
2286 RCS file into a sub-directory named "Attic" within the Repository.
2288 Attic files are examined when the '-r' or '-D' option is used on
2289 "checkout" or "update". If the specified revision, tag or date matches
2290 one on a file in the Attic, that file is checked out with the others.
2292 You can think of the Attic as a sort of dead branch, which is only
2293 looked at when you refer to a <tag> or <date>.
2295 Last modified: _6/13/1997_
2297 10. Is it OK to remove anything from the Repository?
2299 In general, removing anything from the Repository is a bad idea. The
2300 information in a deleted object is lost forever. There are many ways
2301 to skip over files, directories and revisions without deleting them.
2303 Here are some of the consequences of removing the following things
2304 stored in the Repository:
2306 CVSROOT files (Repository control files)
2308 The Repository will work without any of them, but you should
2309 understand what you are losing by deleting them. See 4B.2.
2313 The only way to remove revisions is to use the "admin -o" command (or
2314 the equivalent RCS command "rcs -o").
2316 They are lost forever. Any tags formerly attached to deleted revisions
2317 are now pointing into the Phantom Zone. You'll need to contact Jor-el
2322 You should not remove a file unless you truly never want to see it
2323 again. If you want to be able to check out an old revision of this
2324 file, use "cvs remove" instead.
2328 Tags take up little space and you can't recover from deleting them. If
2329 you depend on tags for releases you will lose vital information.
2333 There is no Attic for directories, so the only way to remove them is
2334 to use "rm -r". They are gone forever.
2336 If you delete (or move) a directory, all checked-out versions of that
2337 directory will cause CVS to halt. You'll have to visit each
2338 checked-out directory and remove the matching working directory by
2343 The "remove" command sends files to the Attic. To really delete them,
2344 you have to go into the Attic and use "rm".
2346 If a file in the Attic has a Tag on it that you might ever want to
2347 check out again, you probably don't want to delete it.
2349 Lock files (named: "#cvs.[wr]fl.<pid>")
2351 These are lock files. If you are getting "lock" errors and the dates
2352 on the lock files indicate that they are old, you can delete them.
2354 Deleting lock files still in use by a CVS process might produce
2357 Last modified: _6/13/1997_
2359 11. Can I convert to CVS from RCS without losing my revision history?
2361 Yes, you can simply move (or copy) your RCS files into a directory
2362 within the Repository, check out that directory and start working.
2364 Last modified: _6/13/1997_
2366 12. Can I move RCS files with branches in them into the Repository?
2368 Yes, but they may not work if you created branches in a way that
2369 conflicts with CVS's assumptions:
2371 You can't use .0. branches. (They are reserved for "Magic" branch
2374 If you use branch 1.1.1, you can't use the Vendor branch.
2376 You can use other RCS branches under CVS. There is no need to create
2377 "magic" branch tags because the physical branch already exists.
2379 Last modified: _6/13/1997_
2381 13. Can I use raw RCS commands on the Repository?
2383 You can use raw rcs commands directly on the Repository if you take a
2384 little care. The Repository itself contains no "CVS state" (as opposed
2385 to RCS revision histories) outside the CVSROOT directory.
2387 But using raw RCS commands to change branches, tags or other things
2388 that CVS depends on may render the files unusable.
2390 See 4D.7 on RCS/CVS sharing of the Repository and Section 3B on the
2393 Last modified: _6/13/1997_
2395 14. How do I convert from SCCS to RCS?
2397 You'll have to execute something like "sccs2rcs" (in the CVS contrib
2398 directory) on every file. Then you can move the resulting RCS files
2399 into the Repository as described above.
2401 Last modified: _6/13/1997_
2403 15. How do I limit access to the Repository?
2405 There are all sorts of ways to restrict access to Repository files,
2406 none of which are hooked directly into CVS.
2408 Techniques for limiting access include:
2410 Training, management and good backups.
2412 The best form of Repository control is a combination of:
2414 - A reliable backup scheme (verify it!)
2415 - Enough training to ensure your developers are competent and
2416 knowledgeable about all areas of your sources.
2417 - Effective management of the boundaries and grey areas.
2419 In many cases, technical solutions to "security" problems are
2420 inadequate. You should first try to avoid them.
2422 Personal Opinion: In an environment where "unknowns" are allowed to
2423 touch important sources the "owner" of the CVS Repository must be a
2424 large, loud, vigorous lout with a well-balanced truncheon and the
2425 right to use it. Don't underestimate the effectiveness of letting
2426 everyone know they will be strapped into the stocks on the Town Common
2427 and pelted with vegetables if they break something they don't
2428 understand without first asking the experts.
2430 Set Unix groups and permissions. See 4B.5. You can set different
2431 owners, groups and permissions for each sub-directory within the
2432 Repository if that helps.
2434 Catch invocations of "commit" by defining pre-commit programs in the
2435 "commitinfo" file. This is fairly powerful, since it can block commits
2436 based on anything you can program. Take a look at the programs in the
2437 "contrib" directory of the CVS source tree.
2439 Use multiple Repositories, each with its own protection scheme. If
2440 you use NFS (or AFS) you can even use "export" restrictions to various
2441 groups of machines to keep (for example) the Engineering Repository
2442 off the Customer Service machines.
2444 Try the "setgid" trick described in 4D.13.
2446 Try to use the RCS access control lists, though I don't think CVS
2447 will handle them cleanly.
2449 Edit the source code to CVS to add your own access control.
2451 Last modified: _6/13/1997_
2453 16. What are the Repository Administrator's responsibilities?
2455 Generally, the Administrator should set "policy", create the
2456 Repository and monitor its size and control files.
2458 Some specific responsibilities include:
2460 Examining the Repository once in a while to clean up:
2462 Trash files left by misguided developers who mistake the Repository
2463 for a working directory.
2465 Non-RCS files. Other than the files CVS needs in the
2466 $CVSROOT/CVSROOT directory, every file in the Repository should be an
2469 Lock files (both CVS '#*' and RCS ',*' files) left around after
2472 Wrong permissions, groups and ownerships.
2474 Locked files. (RCS locks, that is.)
2476 Attic files that should never have been under CVS at all. Don't
2477 blindly delete files from Attic directories -- they were mostly put
2478 there (via the "cvs remove") for a reason. Files that should be
2479 deleted are binary files (e.g. '*.o', 'core', executables) that were
2480 mistakenly inserted by "import -I !".
2482 Maintaining the modules file.
2484 Storing site-specific ignore patterns in the
2485 $CVSROOT/CVSROOT/cvsignore file.
2487 Storing the names of non-standard CVSROOT files (See 4B.2) in the
2488 $CVSROOT/CVSROOT/checkoutlist
2490 Maintaining the other Repository control files: commitinfo, loginfo,
2491 rcsinfo and editinfo.
2493 Pruning the history file every once in a while. (Try the
2494 "cln_hist.pl" script in the "contrib" directory.)
2496 Staying aware of developments on the info-cvs mailing list and what
2497 is available in the FTP and WWW archives.
2499 Running "ps ax" once in a while and kill off any "update" programs
2500 not running as "root". It is too easy to leave the "cvs" off the front
2501 of the "cvs update" command.
2503 Executing monitor programs to check the internal consistency of the
2504 Repository files. Ideas:
2506 Files that have a default RCS branch that is not 1.1.1 (From an
2507 abuse of "admin -b".)
2509 Files that have only Revisions 1.1 and 1.1.1.1, with a default
2510 branch of "MAIN". (From an abuse of "admin -o".)
2512 Existing branch tags and various branch consistency checks.
2514 Last modified: _6/13/1997_
2516 17. How do I move the whole Repository?
2518 Copy or move the tree. (On Unix systems, a set of piped "tar" commands
2519 works great. If the Repository does not contain any symlinks, which it
2520 normally doesn't, you can also use "cp -r".)
2522 If you can avoid changing $CVSROOT (i.e. the "logical" pathname of the
2523 Repository) by replacing the old location with a symbolic link to the
2524 new location, you don't have to do anything else.
2526 (You could also mount the new location on top of the old location if
2527 you are using NFS or some other filesystem that allows it.)
2529 If you must change $CVSROOT, you must also tell everyone to change the
2530 CVSROOT environment variable in all running shells and in any personal
2531 configuration files ('.' files on Unix) where it is set.
2533 The Repository itself contains no references to its own name, except
2534 possibly in some of the files in the CVSROOT directory. If your
2535 modules (or loginfo, commitinfo, etc.) file mentions helper programs
2536 directly in the Repository, you'll have to change the pathnames to
2537 point to the new Repository location.
2539 The main changes you'll have to make are to all the CVS administrative
2540 files (./CVS/Repository and ./CVS/Root) in every working directory
2541 ever checked out from the previous location of the Repository you just
2544 You have three choices:
2546 If all ./CVS/Repository files in all working directories contain
2547 relative pathnames, you don't have to do anything else.
2549 Have everyone "release" or delete their working directories (after
2550 committing, or just saving, their work) and check them all out again
2551 from the new Repository after the move.
2553 Use "find . ( -name Repository -o -name Root )" and a PERL or shell
2554 script to run through all the ./CVS/Repository and ./CVS/Root files
2555 and edit the values in the files.
2557 Last modified: _6/13/1997_
2559 18. How do I change permissions on a file in the Repository by using a CVS
2560 command? (i.e. without using "chmod 777 $CVSROOT/dir/file")
2562 When you first "import" or "add"/"commit" a file, the read and execute
2563 bits on the Repository file are inherited from the original source
2564 file, while the write bits on the Repository file are are turned off.
2565 This is a standard RCS action.
2567 After that, there is no way to alter the permissions on a file in the
2568 Repository using CVS (or RCS) commands. You have to change the
2569 permissions on both your working file and on the Repository file from
2570 which it was retrieved.
2572 Whenever you "checkout" the file or retrieve a new revision via
2573 "update" (or after a "commit"), your working file is set to match the
2574 permissions of the Repository file, minus any "umask" bits you have
2577 Last modified: _6/13/1997_
2579 Category: /Advanced_Topics_/Tricks_of_the_Trade/
2581 " + Tricks of the Trade"
2583 1. How can you even check in binary files, let alone allow CVS to do its
2584 auto-merge trick on them?
2587 First of all, if you want to use binary files, you should get RCS 5.7
2588 and CVS 1.9 or later (earlier versions had some support, but there have been
2589 bug fixes). Secondly, follow the instructions for installing RCS very
2590 carefully (it is easy to get it installed so it works for everything
2591 except binary files).
2593 Then, specify 'cvs add -kb' instead of just 'cvs add' to add a binary
2594 file. If you want to set an existing file to binary, run 'cvs admin
2595 -kb' (and then check in a new copy of the file). Note that old
2596 versions of CVS used -ko instead of -kb for binary files, so if you
2597 see a reference to -ko in the context of binary files, you should
2600 Of course when 'cvs update' finds that a merge is needed, it can't
2601 do this for binary files the same way as for text files. With the
2602 latest versions (e.g. CVS 1.9.14), it should be able to give you both
2603 versions and let you merge manually. Another approach is to
2604 run 'cvs admin -l' to lock files, as described in
2605 "How can I lock files while I'm working on them the way RCS does?"
2606 elsewhere in this FAQ. See also
2607 "Is there any way to import binary files?" and
2608 "How do I "add" a binary file?" elsewhere in this FAQ.
2612 Last modified: _9/6/1997_
2614 2. Can I edit the RCS (",v") files in the Repository?
2616 Yes, but be very careful. The RCS files are not free-form files, they
2617 have a structure that is easily broken by hand-editing. The only time
2618 I would suggest doing this is to recover from emergency failures that
2619 are difficult to deal with using CVS commands, including the "admin"
2620 command, which can talk directly to RCS.
2622 Though no one actively encourages the editing of RCS files, many
2623 people have succumbed to the urge to do so when pressed for time. The
2624 reasons given, usually with evident contrition, include:
2626 - Editing mistakes in, or adding text to, log entries. (If you have
2627 RCS 5.6 or later, you should use `cvs admin -m'.)
2628 - Renaming or moving symbolic names. (You should `cvs admin -N'
2630 - Unlocking a file by changing the "locker" from someone else to
2631 yourself. (It's safer to use `cvs admin -u -l'.)
2632 - Making global changes to past history. Example: Eradicating former
2633 employees names from old documents and Author entries. (And someone
2634 thought the "history" command was evidence of Big Brother! I never
2635 realized how much help a wide-open revision control system could have
2636 provided to The Ministry of Truth.)
2638 Last modified: _6/13/1997_
2640 3. Can I edit the ./CVS/{Entries,Repository,Tag} files?
2642 Yes, but with CVS 1.3 and later, there is almost no reason to edit any
2643 of the CVS administrative files.
2645 If you move pieces of your Repository around it can be faster to edit
2646 all the ./CVS/Repository files rather than checking out a large tree.
2647 But that is nearly the only reason to do so.
2649 Last modified: _6/13/1997_
2651 4. Someone executed "admin -o" and removed revisions to which tags/symbols
2652 were attached. How do I fix them?
2654 It depends on what you mean by "fix". I can think of three ways to fix
2659 Assuming you really wanted to get rid of the revision and its
2660 associated tags, you can remove them with the "admin" command. The
2661 "tag -d" command will only remove tags attached to existing revisions.
2662 You can remove a tag, even if it is attached to a non-existent
2663 revision, by typing:
2665 cvs admin -N<tag> <file>
2667 Retrieve the outdated revision.
2669 You should first look in your backup system for recent versions of the
2670 file. If you can't use them, you can carefully extract each revision
2671 that followed the earliest outdated revision using RCS (or "cvs
2672 admin") commands and reconstruct the file with all the right
2673 revisions, branches and tags. This is a lot of work.
2675 You *can't* insert a revision into the current RCS file.
2677 Move the Tags to another revision in each file.
2679 If you want to move the tags to another valid revision, you have two
2680 choices, both of which require that you find all the revision numbers
2681 of the files you want to "tag" and execute the following command
2682 sequences on each <file>.
2684 Use "update" to grab the revision you want, then execute a normal
2685 "tag" command to Tag that revision:
2687 cvs update -r <rev> <file>
2688 cvs tag <tag> <file>
2690 Use "admin" to set the tag to a specific revision:
2692 cvs admin -N<tag>:<rev> <file>
2694 Last modified: _6/13/1997_
2696 5. How do I move or rename a magic branch tag?
2698 (To rename a non-branch <tag> see 3O.9.)
2700 Before reading this, read 3M.3 and 3M.4 and understand exactly how tag
2701 and rtag use '-r' and why it won't do the right job here.
2703 First, I have to explain exactly what a magic branch tag is.
2705 A magic <branch_tag> is an artificial tag attached to a non-existent
2706 revision on a non-existent branch number zero. It looks like this:
2710 <X> is the "branch point revision", a normal revision with an
2711 odd number of '.'s in it. (e.g. 1.5, 1.3.1.6, etc)
2713 Y is an even number (e.g. 2, 4, 6, etc.) All CVS branches,
2714 other than the Vendor branch, are even numbered.
2716 TAG1 is considered by CVS to be attached to revision <X>. The first
2717 "update -r TAG1 <file>" after applying TAG1 will produce a copy of
2718 revision <X> with a sticky tag of TAG1. The first "commit" to that
2719 file will cause CVS to construct an RCS branch named <X>.Y and check
2720 in revision <X>.Y.1 on the new branch.
2722 Note: TAG1 is *not* considered to be attached to <X> by RCS, which
2723 explains why you can't refer directly to the branch point revision for
2726 Moving a magic <branch_tag> is the act of reapplying the same tag to
2727 different revisions in the file:
2731 TAG1:<X>.0.Z or TAG1:<A>.0.B
2733 You can move a magic branch tag to the revisions of your choice by
2734 using "update" to find the revisions you want to tag and reapplying
2735 the tag to all the files with the '-F' option to force it to move the
2736 existing <branch_tag>.
2738 cvs update -r <tag/rev> (or '-A' for the Main Branch)
2739 cvs tag -F -b <branch_tag>
2741 If the earlier location of TAG1 refers to a physical branch within any
2742 RCS file, moving it will make the existing branch in the file seem to
2743 disappear from CVS's view. This is not a good idea unless you really
2744 want to forget the existence of those RCS branches.
2746 If the "update" above retrieves the original branch point revision
2747 (<X>), the "tag" command above will create the tag:
2751 Where Z is 2 greater than the highest magic branch already on revision
2752 <X>. The TAG1 branch will still have the same branch point (i.e.
2753 revision <X>), but the first commit to the new TAG1 branch will create
2754 a different RCS branch number (<X>.Z instead of <X>.Y).
2756 Renaming a magic <branch_tag> is the act of changing
2762 There is no harm in changing a tag name as long as you forget that
2763 TAG1 ever existed and you clean up any working directories with sticky
2764 TAG1 tags on them by using "update -A", "update -r <other_tag>" or by
2765 removing the working directories.
2767 On the other hand, actually changing the tag is not easy.
2769 See 3M.3 for why the seemingly obvious solution won't work:
2771 cvs tag -b -r <old_branch_tag> <new_branch_tag>
2773 The only direct way to rename a magic tag is to use the "admin"
2774 command on each file: (You might want to use '-n'. Read "man rcs" and
2775 look at the '-n' and '-N' options.)
2777 cvs admin -N<new_branch_tag>:<old_branch_tag> .
2778 cvs tag -d <old_branch_tag>
2780 But you have to be careful because "admin" is different from other CVS
2783 "admin" can be used recursively, but only by specifying directory
2784 names in its argument list (e.g. '.'),
2786 Where "rtag -r <old_branch_tag>" would interpret <old_branch_tag> as
2787 a magic CVS branch tag, "admin" is a direct interface to RCS which
2788 sees a magic branch tag as a simple (though non-existent) RCS revision
2791 This is good for us in this particular case, but different from normal
2794 "admin" also skips the Attic and produces different kinds of errors
2795 than CVS usually does. (Because they are coming directly from RCS.)
2797 The other way to rename a magic <branch_tag> is to edit the Repository
2798 files with a script of some kind. I've done it in the past, but I'll
2799 leave it as an exercise for the reader.
2801 Last modified: _6/13/1997_
2803 6. Can I use RCS locally to record my changes without making them globally
2804 visible by committing them?
2806 You can, but it will probably confuse CVS to have ",v" files in your
2807 working directory. And you will lose all your log entries when you
2810 Your best bet is to create your own CVS branch and work there. You can
2811 commit as many revisions as you want, then merge it back into the main
2812 line (or parent branch) when you are finished.
2814 Last modified: _6/13/1997_
2816 7. How can I allow access to the Repository by both CVS and RCS?
2818 The first step is to try not to. If some people are using CVS, there
2819 is no reason for everyone not to. It is not hard to learn the basics
2820 and CVS makes certain operations *easier* than a series of RCS
2821 commands. Personal preference in what software tools can be applied to
2822 a shared Repository has to take second place to system integration
2823 needs. If you disagree, try writing some Lisp code for inclusion in
2824 your Unix kernel and see what kind of reception you get.
2826 If you really must allow routine RCS access to the CVS Repository, you
2827 can link an RCS sub-directory into a piece of the Repository:
2829 ln -s /Repository/some/directory/I/want RCS
2831 and RCS will work just fine.
2833 Those who are using RCS will have to keep the following in mind:
2835 If a file was originally added to the Repository by "import" and has
2836 not been changed using CVS, the *RCS* default branch will remain
2837 attached to the Vendor branch, causing revisions checked-in by "ci" to
2838 wind up on the Vendor branch, instead of the main branch. Only CVS
2839 moves the RCS default branch on first commit.
2841 The way around this is to checkin (using "ci") all the files first and
2842 move them into the Repository. That way they won't have Vendor
2843 branches. Then RCS will work OK.
2845 It is possible to use "rcs" and "ci" to make the files unusable by
2846 CVS. The same is true of the CVS "admin" command.
2848 Normal RCS practice locks a file on checkout with "co -l". In such
2849 an environment, RCS users should plan to keep survival gear and food
2850 for at least 30 days near their desks. When faced with bizarre and
2851 unexpected permission errors, howling mobs of slavering CVS users will
2852 run the RCS users out of town with pitchforks and machetes.
2854 See 3C.8 for a way to avoid machetes aroused by lock collisions.
2856 Though files checked in by RCS users will correctly cause
2857 "up-to-date" failures during CVS "commits" and they will be
2858 auto-merged into CVS working directories during "update", the opposite
2861 RCS users will get no warning and will not be required to merge older
2862 work into their code. They can easily checkin an old file on top of a
2863 new revision added by CVS, discarding work committed earlier by CVS
2866 See the howling mob scenario described above.
2868 RCS is great. I have used it for years. But I wouldn't mix it this
2869 way. In a two-camp society, you are asking for real trouble, both in
2870 technical hassles to clean up and in political hassles to soothe.
2871 Branch merges will also be a major problem.
2873 Last modified: _6/13/1997_
2875 8. I "updated" a file my friend, "bubba", committed yesterday. Why doesn't
2876 the file now have a modified date of yesterday?
2878 CVS restores dates from the RCS files only on first "checkout". After
2879 that, it is more important to maintain a timestamp relative to the
2880 other files in the working directory.
2882 Example: You committed a source file at 5PM. Bubba updated his copy of
2883 the file, grabbing your changes, then changed and committed a new
2884 revision of the file at 6PM. At 7PM, you compile your file. Then you
2885 execute "update". If CVS sets the date to the one in the RCS file, the
2886 file would be given a timestamp of 6PM and your Makefile wouldn't
2887 rebuild anything that depended on it. Bad news.
2889 Note that the same logic applies to retrieving a revision out of the
2890 Repository to replace a deleted file. If CVS changes your file in an
2891 existing working directory, whether it was because a new revision was
2892 committed by someone else or because you deleted your working file,
2893 the timestamp on the retrieved working file *must* be set to the
2896 When you first retrieve a file, there is no reason to expect any
2897 particular timestamp on the file within your working area. But later,
2898 when dependency checking is performed during a build, it is more
2899 important for the timestamps on the local files to be consistent with
2900 each other than than it is for working files to match the timestamps
2901 on the files in the Repository. See 4D.17 for some more about
2904 Last modified: _6/13/1997_
2906 9. Why do timestamps sometimes get set to the date of the revision,
2907 sometimes not? The inconsistency causes unnecessary recompiles.
2909 The "checkout" command normally sets the timestamp of a working file
2910 to match the timestamp stored on the revision in the Repository's RCS
2913 The "commit" command retains the timestamp of the file, if the act of
2914 checking it in didn't change it (by expanding keywords).
2916 The "update" command sets the time to the revision time the first time
2917 it sees the file. After that, it sets the time of the file to the
2918 current time. See 4D.8 for a reason why.
2920 Here's a two-line PERL program to set timestamps on files based on
2921 other timestamps. I've found this program useful. When you are certain
2922 you don't want a source file to be recompiled, you can set its
2923 timestamp to the stamp on the object file.
2925 #!/usr/local/bin/perl
2927 # Set timestamp of args 2nd-Last to that of the first arg.
2929 ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,$atime,$mtime,$ctime)
2931 utime($atime,$mtime,@ARGV);
2933 Last modified: _6/13/1997_
2935 10. While in the middle of a large "commit", how do I run other commands,
2936 like "diff" or "stat" without seeing lock errors?
2941 The '-n' option to the main cvs command turns off lock checking, a
2942 reasonable act for read-only commands given the promise offered by
2943 '-n' not to alter anything. The "diff", "log" and "stat" commands
2944 provide the same information (for files that are not being committed)
2945 when used with and without the '-n' option.
2947 Warning: Ignoring locks can produce inconsistent information across a
2948 collection of files if you are looking at the revisions affected by an
2949 active commit. Be careful when creating "patches" from the output of
2950 "cvs -n diff". If you are looking only at your working files, tagged
2951 revisions, and BASE revisions (revisions whose numbers are read from
2952 your ./CVS/Entries files), you should get consistent results. Of
2953 course, if you catch a single file in the middle of RCS activity, you
2954 might get some strange errors.
2956 Note that the suggested command is "cvs -n <command>". The visually
2957 similar command "cvs <command> -n" has no relation to the suggested
2958 usage and has an entirely different meaning for each command.
2960 "cvs -n update" also works in the middle of a commit, providing
2961 slightly different information from a plain "cvs update". But, of
2962 course, it also avoids modifying anything.
2964 You could also use the RCS functions, "rlog" and "rcsdiff" to display
2965 some of the information by referring directly to the Repository files.
2967 You need RCS version 5 or later for the commands described above to
2970 Last modified: _6/13/1997_
2972 11. Where did the ./CVS/Entries.Static file come from? What is it for?
2974 Each CVS working directory contains a ./CVS/Entries file listing the
2975 files managed by CVS in that working directory. Normally, if the
2976 "update" command finds a file in the Repository that is not in the
2977 ./CVS/Entries file, "update" copies the appropriate revision of the
2978 "new" file out of the Repository and adds the filename to the Entries
2979 file. This happens for files:
2981 Added to the Repository from another working directory.
2983 Dragged out of the Attic when switching branches with "update -A" or
2986 Whose names were deleted from the ./CVS/Entries file.
2988 If the ./CVS/Entries.Static file exists, CVS will only bring out
2989 revisions of files that are contained in either ./CVS/Entries or
2990 ./CVS/Entries.Static. If a Repository file is found in *neither* file,
2993 The ./CVS/Entries.Static file is created when you check out an
2994 individual file or a module that creates working directories that
2995 don't contain all files in the corresponding Repository directory. In
2996 those cases, without an ./CVS/Entries.Static file, a simple "update"
2997 would bring more files out of the Repository than the original
3000 The ./CVS/Entries.Static file can be removed by hand. It is
3001 automatically removed if you run "update -d" to create new directories
3002 (even if no new directories are created). (Internally, since
3003 "checkout" turns on the '-d' flag and calls the "update" routine, a
3004 "checkout" of a module or directory that writes into an existing
3005 directory will also remove the ./CVS/Entries.Static file.)
3007 Last modified: _6/13/1997_
3009 12. Why did I get the wrong Repository in the loginfo message?
3013 Use multiple Repositories.
3015 Configured CVS to use absolute pathnames in the ./CVS/Repository
3018 Configured CVS not to use the ./CVS/Root file.
3020 Typed the "commit" command in one Repository with your $CVSROOT
3021 pointing at another.
3023 "commit" and all other CVS commands will heed an absolute pathname in
3024 the ./CVS/Repository file (or in the "-d CVSrootdir" override), but
3025 the log function doesn't take arguments -- it just looks at $CVSROOT.
3027 If you avoid even one of the four steps above, you won't see this
3028 problem. If you configure ./CVS/Root, you won't be allowed to execute
3029 the program causing the error.
3031 Last modified: _6/13/1997_
3033 13. How do I run CVS setuid so I can only allow access through the CVS
3036 Setuid to root is not a great idea. Any program that modifies files
3037 and is used by a widely distributed group of users is not a good
3038 candidate for a setuid program. (The worst suggestion I've ever heard
3039 was to make *Emacs* setuid to root.)
3041 Root access on Unix is too powerful. Also, it might not work in some
3042 (secure?) environments.
3044 Running it setuid to some user other than root might work, if you add
3045 this line to main.c near the beginning:
3049 Otherwise it uses *your* access rights, rather than the effective
3052 Also, you have to invent a fake user whose name will show up in
3053 various places. But many sites, especially those who might want a
3054 setuid CVS for "security", want personal accountability -- no generic
3055 accounts. I don't know whether accountability outweighs file security.
3057 And finally, unless you take action to limit the "admin" command, you
3058 are leaving yourself unprotected anyway.
3060 Last modified: _6/13/1997_
3062 14. How about using groups and setgid() then?
3064 Here is a way to run CVS setgid in some environments:
3066 Stick this near the front of the main() in main.c:
3070 This will allow "access" to work on systems where it only works on the
3073 Create a group named "cvsg". (This example uses "cvsg". You can name
3076 Put *no* users in the "cvsg" group. You can put Repository
3077 administrators in this group if you want to.
3079 Set the cvs executable to setgid (not setuid):
3081 cd /usr/local/bin; chown root.cvsg cvs; chmod 2755 cvs
3083 Make sure every file in the Repository is in group "cvsg":
3085 chown -R root.cvsg $CVSROOT
3087 Change all directory permissions to 770. This allows all access to
3088 the files by the "cvsg" group (which has no members!) and no access at
3091 find $CVSROOT -type d -exec chmod 2770 {} \;
3093 On some systems you might have to type:
3095 find $CVSROOT -type d -exec chmod u=rwx,g=rwx,o=,g+s {} \;
3097 This should allow only the cvs program (or other "setgid to group
3098 cvsg") programs to write into the area, but no one else. Yes the user
3099 winds up owning the file, but s/he can't find it again later since
3100 s/he can't traverse the tree. (If you enable the world execute bit
3101 (mode 2771) on directories, users can traverse the tree and the user
3102 who last wrote the file can still write to it.)
3104 If you want to allow read access, check out an entire tree somewhere.
3105 You have to do this anyway to build it.
3107 Note: If you are using a stupid file system that can't inherit file
3108 groups from the parent directory (even with the "setgid" (Octal 2000)
3109 bit set), you might have to modify CVS (or RCS) to reset the group
3110 every time you create a new file. I have not tested this.
3112 The setgid() method shares with the setuid() method the problem of
3113 keeping "admin" from breaking things.
3115 Last modified: _6/13/1997_
3117 15. How do I use the "commitinfo" file?
3121 The "commitinfo" file allows you to execute "sanity check" functions
3122 before allowing a commit. If any function called from within the
3123 commitinfo file exits with a non-zero status, the commit is denied.
3125 To fill out a "commitinfo" file, ask yourself (and those sharing your
3126 Repository) these questions:
3128 - Is there anything you want to check or change before someone is
3129 allowed to commit a file? If not, forget commitinfo.
3131 If you want to serialize binary files, you might consider something
3132 like the rcslock.pl program in the contrib directory of the CVS
3135 - Do you want to execute the same exact thing before committing to
3136 every file in the Repository? (This is useful if you want to program
3137 the restrictions yourself.) If so, set up a single line in the
3140 DEFAULT /absolute/path/to/program
3142 CVS executes the program once for each directory that "commit"
3143 traverses, passing as arguments the directory and the files to be
3144 committed within that directory.
3146 Write your program accordingly. Some examples exist in the contrib
3149 - Do you want a different kind of sanity check performed for different
3150 directories? If so, you'll have to decide what to do for all
3151 directories and enter lines like this:
3153 regexp1 /absolute/path/to/program-for-regexp1
3154 regexp2 /absolute/path/to/program-for-regexp2
3155 DEFAULT /absolute/path/to/program-for-all-else
3157 - Is there anything you want to happen before *all* commits, in
3158 addition to other pattern matches? If so, include a line like this:
3160 ALL /absolute/path/to/program
3162 It is executed independently of all the above. And it's repeatable --
3163 you can have as many ALL lines as you like.
3165 Last modified: _6/13/1997_
3167 16. How do I use the "loginfo" files?
3169 See 4B.2 and the "commitinfo" question above.
3171 The "loginfo" file has the same format as the "commitinfo" file, but
3172 its function is different. Where the "commitinfo" information is used
3173 before a commit, the "loginfo" file is used after a commit.
3175 All the commands in the "loginfo" file should read data from standard
3176 input, then either append it to a file or send a message to a mailing
3177 list. If you want to make it simple, you can put shell (the shell used
3178 by "popen(3)") command lines directly in the "loginfo" (or
3179 "commitinfo") file. These seem to work:
3181 ^special /usr/ucb/Mail -s %s special-mailing-list ^other /usr/ucb/Mail
3182 -s %s other-mailing-list DEFAULT (echo '===='; echo %s; cat) >
3183 /path/name/to/log/file
3185 Last modified: _6/13/1997_
3187 17. How can I keep people with restrictive umask values from blocking
3188 access to the Repository?
3190 If a user creates a new file with restricted permissions (e.g. 0600),
3191 and commits it, the Repository will have a file in it that is
3192 unreadable by everyone. The 0600 example would be unreadable by
3193 *anyone* but root and the user who created it.
3195 There are 3 solutions to this:
3197 Let it happen. This is a valid way to protect things. If everyone is
3198 working alone, a umask of 077 is OK. If everyone is working only in
3199 small groups, a umask of 007 is OK.
3201 Train your users not to create such things if you expect to share
3204 See 4B.5 for a small script that will reset the umask.
3206 I personally don't like the idea of a program automatically
3207 *loosening* security. It would be better for you all to talk about the
3208 issue and decide how to work together.
3210 Last modified: _6/13/1997_
3212 Category: /Commands_/
3216 Category: /Commands_/add_ad_new/
3218 " + "add", "ad", "new""
3220 1. What is "add" for?
3222 To add a new directory to the Repository or to register the desire to
3223 add a new file to the Repository.
3225 The directory is created immediately, while the desire to add the file
3226 is recorded in the local ./CVS administrative directory. To really add
3227 the file to the Repository, you must then "commit" it.
3229 Last modified: _6/13/1997_
3231 2. How do I add a new file to the branch I'm working on?
3233 The user actions for adding a file to any branch, including the Main
3234 Branch, are exactly the same.
3236 You are in a directory checked out (or updated) with the '-A' option
3237 (to place you on the Main Branch) or the "-r <branch_tag>" option (to
3238 place you on a branch tagged with <branch_tag>). To add <file> to the
3239 branch you are on, you type:
3244 If no ./CVS/Tag file exists (the '-A' option deletes it), the file
3245 will be added to the Main Branch. If a ./CVS/Tag file exists (the "-r
3246 <branch_tag>" option creates it), the file will be added to the branch
3247 named (i.e. tagged with) <branch_tag>.
3249 Unless you took steps to first add the file to the Main Branch, your
3250 new file ends up in the Attic.
3252 Last modified: _6/13/1997_
3254 3. Why did my new file end up in the Attic?
3256 The file is thrown into the Attic to keep it from being visible when
3257 you check out the Main Branch, since it was never committed to the
3260 Last modified: _6/13/1997_
3262 4. Now that it's in the Attic, how do I connect it to the Main branch?
3264 That can be considered a kind of "merge". See 4C.8
3266 Last modified: _6/13/1997_
3268 5. How do I avoid the hassle of reconnecting an Attic-only file to the Main
3271 You create it on the Main Branch first, then branch it.
3273 If you haven't yet added the file or if you decided to delete the new
3274 Attic file and start over, then do the following: (If you added the
3275 file (or worse, the 157 files) to the Attic and don't want to start
3276 over, try the procedure in 4C.8.)
3278 Temporarily remove the sticky branch information. Either:
3280 Move the whole directory back to the Main Branch. [This might not be
3281 a good idea if you have modified files, since it will require a merge
3288 Move the ./CVS/Tag file out of the way.
3290 mv ./CVS/Tag HOLD_Tag
3292 Add and branch the file "normally":
3296 cvs tag -b <branch_tag> <file>
3298 [<branch_tag> is the same Branch Tag as you used on all the other
3299 files. Look at ./CVS/Entries or the output from "cvs stat" for sticky
3302 Clean up the temporary step.
3304 If you moved the ./CVS/Tag file, put it back. Then move the new file
3305 onto the branch where you are working.
3307 mv HOLD_Tag ./CVS/Tag
3308 cvs update -r <branch_tag> <file>
3310 If you ran "update -A" rather than moving the ./CVS/Tag file, move
3311 the whole directory (including the new file) back onto the branch
3312 where you were working:
3314 cvs update -r <branch_tag>
3316 Last modified: _6/13/1997_
3318 6. How do I cancel an "add"?
3320 If you want to remove the file entirely and cancel the "add" at the
3323 cvs remove -f <file>
3325 If you want to cancel the "add", but leave the file as it was before
3326 you typed "cvs add", then you have to fake it:
3328 mv <file> <file>.hold
3330 mv <file>.hold <file>
3332 Last modified: _6/13/1997_
3334 7. What are the ./CVS/file,p and ./CVS/file,t files for?
3336 The ./CVS/file,p and ./CVS/file,t files are created by the "add"
3337 command to hold command line options and message text between the time
3338 of the "add" command and the expected "commit".
3340 The ./CVS/file,p file is always null, since its function was absorbed
3341 by the "options" field in the ./CVS/Entries file. If you put something
3342 in this file it will be used as arguments to the RCS "ci" command that
3343 commit uses to check the file in, but CVS itself doesn't put anything
3346 The ./CVS/file,t file is null unless you specify an initial message in
3347 an "add -m 'message'" command. The text is handed to "rcs -i
3348 -t./CVS/file,t" to create the initial RCS file container.
3350 Both files must exist to commit a newly added file. If the
3351 ./CVS/file,p file doesn't exist, CVS prints an error and aborts the
3352 commit. If the ./CVS/file,t file doesn't exist, RCS prints an error
3353 and CVS gets confused, but does no harm.
3355 To recover from missing ,p and ,t files, just create two zero-length
3356 files and rerun the "commit".
3358 Last modified: _6/13/1997_
3360 8. How do I "add" a binary file?
3362 If you configured CVS to use the GNU version of "diff" and "diff3",
3363 you only need to turn off RCS keyword expansion.
3365 First you turn off RCS keyword expansion for the initial checkin by
3366 using "add -ko". It works like "update -ko" in creating a "sticky"
3367 option only for the copy of the file in the current working directory.
3371 Commit the file normally. The sticky -ko option will be used.
3375 Then mark the RCS file in the Repository so that keyword expansion is
3376 turned off for all checked out versions of the file.
3378 cvs admin -ko <file>
3380 Since "admin -ko" records the keyword substitution value in the
3381 Repository's RCS file, you no longer need the sticky option. You can
3382 turn it off with the "update -A" command, but if you were on a branch,
3383 you'll have to follow it "update -r <branch_tag>" to put yourself back
3386 Managing that binary file is another problem. See 4D.1.
3388 Last modified: _6/13/1997_
3390 Category: /Commands_/admin_adm_rcs/
3392 " + "admin", "adm", "rcs""
3394 1. What is "admin" for?
3396 To provide direct access to the underlying "rcs" command (which is not
3397 documented in this FAQ) bypassing all safeguards and CVS assumptions.
3399 Last modified: _6/13/1997_
3401 2. Wow! Isn't that dangerous?
3405 Though you can't hurt the internal structure of an RCS file using its
3406 own "rcs" command, you *can* change the underlying RCS files using
3407 "admin" in ways that CVS can't handle.
3409 If you feel the need to use "admin", create some test files with the
3410 RCS "ci" command and experiment on them with "rcs" before blasting any
3413 Last modified: _6/13/1997_
3415 3. What would I normally use "admin" for?
3417 Normally, you wouldn't use admin at all. In unusual circumstances,
3418 experts can use it to set up or restore the internal RCS state that
3421 You can use "admin -o" (for "outdate") to remove revisions you don't
3422 care about. This has its own problems, such as leaving dangling Tags
3423 and confusing the "update" command.
3425 There is some feeling among manipulators of binary files that "admin
3426 -l" should be used to serialize access. See 3C.8.
3428 An interesting use for "admin" came up while maintaining CVS itself. I
3429 import versions of CVS onto the Vendor branch of my copy of CVS, make
3430 changes to some files and ship the diffs (created by "cvs diff -c -r
3431 TO_BRIAN") off to Brian Berliner. After creating the diff, I retag
3432 ("cvs tag -F TO_BRIAN") the working directory, which is then ready to
3433 produce the next patch.
3435 I'll use "add.c" as an example (only because the name is short).
3437 When the next release came out, I discovered that the released "add.c"
3438 (version 1.1.1.3 on the Vendor branch) was exactly the same as my
3439 modified file (version 1.3). I didn't care about the changelog on
3440 versions 1.2 and 1.3 (or the evidence of having done the work), so I
3441 decided to revert the file to the state where it looked like I had not
3442 touched the file -- where I was just using the latest on the vendor
3443 branch after a sequence of imports.
3445 To do that, I removed all the revisions on the main branch, except for
3446 the original 1.1 from which the Vendor branch sprouts:
3448 cvs admin -o1.2: add.c
3450 Then I set the RCS "default branch" back to the Vendor branch, the way
3451 import would have created it:
3453 cvs admin -b1.1.1 add.c
3455 And I moved the "TO_BRIAN" Tag to the latest revision on the Vendor
3456 branch, since that is the base from which further patches would be
3457 created (if I made any):
3459 cvs admin -NTO_BRIAN:1.1.1.3 add.c
3461 Instead of 1.1.1.3, I could have used one of the "Release Tags" last
3462 applied by "import" (3rd through Nth arguments).
3464 Suggestion: Practice on non-essential files.
3466 Last modified: _6/13/1997_
3468 4. What should I avoid when using "admin"?
3470 If you know exactly what you are doing, hack away. But under normal
3473 Never use "admin" to alter branches (using the '-b' option), which CVS
3474 takes very seriously. If you change the default branch, CVS will not
3475 work as expected. If you create new branches without using the "tag
3476 -b" command, you may not be able to treat them as CVS branches.
3478 See 3C.8 for a short discussion of how to use "admin -l" for
3479 serializing access to binary files.
3481 The "admin -o <file>" allows you to delete revisions, usually a bad
3482 idea. You should commit a correction rather than back out a revision.
3483 Outdating a revision is prone to all sorts of problems:
3485 Discarding data is always a bad idea. Unless something in the
3486 revision you just committed is a threat to your job or your life,
3487 (like naming a function "<boss's name>_is_a_dweeb", or including the
3488 combination to the local Mafioso's safe in a C comment), just leave it
3489 there. No one cares about simple mistakes -- just commit a corrected
3492 The time travel paradoxes you can cause by changing history are not
3493 worth the trouble. Even if CVS can't interfere with your parents'
3494 introduction, it *can* log commits in at least two ways (history and
3495 loginfo). The reports now lie -- the revision referred to in the logs
3498 If you used "import" to place <file> into CVS, outdating all the
3499 revisions on the Main branch back to and including revision 1.2 (or
3500 worse, 1.1), will produce an invalid CVS file.
3502 If the <file>,v file only contains revision 1.1 (and the connected
3503 branch revision 1.1.1.1), then the default branch must be set to the
3504 Vendor branch as it was when you first imported the file. Outdating
3505 back through 1.2 doesn't restore the branch setting. Despite the above
3506 admonition against it, "admin -b" is the only way to recover:
3508 cvs admin -b1.1.1 <file>
3510 Although you can't outdate a physical (RCS) branch point without
3511 removing the whole branch, you *can* outdate a revision referred to by
3512 a magic branch tag. If you do so, you will invalidate the branch.
3514 If you "outdate" a tagged revision, you will invalidate all uses of
3515 the <tag>, not just the one on <file>. A tag is supposed to be
3516 attached to a consistent set of files, usually a set built as a unit.
3517 By discarding one of the files in the set, you have destroyed the
3518 utility of the <tag>. And it leaves a dangling tag, which points to
3521 And even worse, if you commit a revision already tagged, you will
3522 alter what the <tag> pointed to without using the "tag" command. For
3523 example, if revision 1.3 has <tag> attached to it and you "outdate"
3524 the 1.3 revision, <tag> will point to a nonexistent revision. Although
3525 this is annoying, it is nowhere near as much trouble as the problem
3526 that will occur when you commit to this file again, recreating
3527 revision 1.3. The old tag will point to the new revision, a file that
3528 was not in existence when the <tag> was applied. And the discrepancy
3529 is nearly undetectable.
3531 If you don't understand the above, you should not use the admin
3534 Last modified: _6/13/1997_
3536 5. How do I restrict the "admin" command? The -i flag in the modules file
3537 can restrict commits. What's the equivalent for "admin"?
3539 At this writing, to disable the "admin" command, you will have to
3540 change the program source code, recompile and reinstall.
3542 Last modified: _6/13/1997_
3544 6. I backed out a revision with "admin -o" and committed a replacement. Why
3545 doesn't "update" retrieve the new revision?
3547 CVS is confused because the revision in the ./CVS/Entries file matches
3548 the latest revision in the Repository *and* the timestamp in the
3549 ./CVS/Entries file matches your working file. CVS believes that your
3550 file is "up-to-date" and doesn't need to be updated.
3552 You can cause CVS to notice the change by "touch"ing the file.
3553 Unfortunately what CVS will tell you is that you have a "Modified"
3554 file. If you then "commit" the file, you will bypass the normal CVS
3555 check for "up-to-date" and will probably commit the revision that was
3556 originally removed by "admin -o".
3558 Changing a file without changing the revision number confuses CVS no
3559 matter whether you did it by replacing the revision (using "admin -o"
3560 and "commit" or raw RCS commands) or by applying an editor directly to
3561 a Repository (",v") file. Don't do it unless you are absolutely
3562 certain no one has the latest revision of the file checked out.
3564 The best solution to this is to institute a program of deterrent
3565 flogging of abusers of "admin -o".
3567 The "admin" command has other problems." See 3B.4 above.
3569 Last modified: _6/13/1997_
3571 Category: /Commands_/checkout_co_get/
3573 " + "checkout", "co", "get""
3575 1. What is "checkout" for?
3577 To acquire a copy of a module (or set of files) to work on.
3579 All work on files controlled by CVS starts with a "checkout".
3581 Last modified: _6/13/1997_
3583 2. What is the "module" that "checkout" takes on the command line?
3585 It is a name for a directory or a collection of files in the
3586 Repository. It provides a compact name space and the ability to
3587 execute before and after helper functions based on definitions in the
3592 Last modified: _6/13/1997_
3594 3. Isn't a CVS "checkout" just a bunch of RCS checkouts?
3596 Like much of CVS, a similar RCS concept is used to support a CVS
3597 function. But a CVS checkout is *not* the same as an RCS checkout.
3599 Differences include:
3601 CVS does not lock the files. Others may access them at the same
3604 CVS works best when you provide a name for a collection of files (a
3605 module or a directory) rather than an explicit list of files to work
3608 CVS remembers what revisions you checked out and what branch you are
3609 on, simplifying later commands.
3611 Last modified: _6/13/1997_
3613 4. What's the difference between "update" and "checkout"?
3615 The "checkout" and "update" commands are nearly equivalent in how they
3616 treat individual files. They differ in the following ways:
3618 The "checkout" command always creates a directory, moves into it,
3619 then becomes equivalent to "update -d".
3621 The "update" command does not create directories unless you add the
3624 "Update" is intended to be executed within a working directory
3625 created by "checkout". It doesn't take a module or directory argument,
3626 but figures out what Repository files to look at by reading the files
3627 in the ./CVS administrative directory.
3629 The two commands generate completely different types of records in
3632 Last modified: _6/13/1997_
3634 5. Why can't I check out a file from within my working directory?
3636 Though you *can* check out a file, you normally check out a module or
3637 directory. And you normally do it only once at the beginning of a
3640 After the initial "checkout", you can use the "update" command to
3641 retrieve any file you want within the checked-out directory. There is
3642 no need for further "checkout" commands.
3644 If you want to retrieve another module or directory to work on, you
3645 must provide two pathnames: where to find it in the Repository and
3646 where to put it on disk. The "modules" file and your current directory
3647 supply two pieces of naming information. While inside a checked-out
3648 working directory, the CVS administrative information provides most of
3651 You should be careful not to confuse CVS with RCS and use "checkout"
3652 in the RCS sense. An RCS "checkout" (which is performed by the RCS
3653 "co" command) is closer to a "cvs update" than to a "cvs checkout".
3655 Last modified: _6/13/1997_
3657 6. How do I avoid dealing with those long relative pathnames?
3659 This question has also been phrased:
3661 How do I avoid all those layers of directories on checkout? or Why do
3662 I have to go to the top of my working directory and checkout some long
3663 pathname to get a file or two?
3665 This type of question occurs only among groups of people who decide
3666 not to use "modules". The answer is to use "modules".
3668 When you hand the "checkout" command a relative pathname rather than a
3669 module name, all directories in the path are created, maintaining the
3670 same directory hierarchy as in the Repository. The same kind of
3671 environment results if you specify a "module" that is really an alias
3672 expanding into a list of relative pathnames rather than a list of
3675 If you use "module" names, "checkout" creates a single directory by
3676 the name of the module in your current directory. This "module"
3677 directory becomes your working directory.
3679 The "module" concept combines the ability to "name" a collection of
3680 files with the ability to structure the Repository so that consistent
3681 sets of files are checked out together. It is the responsibility of
3682 the Repository Administrators to set up a modules file that describes
3683 the software within the Repository.
3685 Last modified: _6/13/1997_
3687 7. Can I move a checked-out directory? Does CVS remember where it was
3692 The ./CVS/Repository file in each working directory contains a
3693 pathname pointing to the matching directory within the Repository. The
3694 pathname is either absolute or relative to $CVSROOT, depending on how
3697 When you move a checked-out directory, the CVS administrative files
3698 will move along with it. As long as you don't move the Repository
3699 itself, or alter your $CVSROOT variable, the moved directory will
3700 continue to be usable.
3702 CVS remembers where you checked out the directory in the "history"
3703 file, which can be edited, or even ignored if you don't use the
3704 "working directory" information displayed by the "history" command.
3706 Last modified: _6/13/1997_
3708 8. How can I lock files while I'm working on them the way RCS does?
3710 Until the day arrives of the all-powerful merge tool, there are still
3711 files that must be accessed serially. For those instances, here's a
3714 Install a pre-commit program in the "commitinfo" file to check for
3715 RCS locks. The program "rcslock.pl" performs this function. It can be
3716 found in the contrib directory of the CVS source distribution.
3718 When you want to make a change to a file you know can't be merged,
3719 first use "cvs admin -l" to lock the file. If you can't acquire the
3720 lock, use the standard "locked out" protocol: go talk to the person
3723 Make sure the pre-commit program prints a message and exits with a
3724 non-zero status if someone besides the user running "commit" has the
3725 file locked. This non-zero exist status will cause the "commit" to
3728 Make sure the pre-commit program exits with a zero status if the
3729 file is either unlocked or locked by the user running "commit". The
3730 "cvs commit" command that kicked off the pre-commit program will take
3731 a zero exist status as an OK and checkin the file, which has the
3732 side-effect of unlocking it.
3734 ===> The following is opinion and context. Don't read it if you are
3735 looking for a quick fix.
3737 The topic of locking CVS files resurfaces on the network every so
3738 often, producing the same results each time:
3742 CVS was designed to avoid locks, using a copy-modify-merge model.
3743 Locking is not necessary and you should take the time to learn the CVS
3744 model which many people find workable. So why not get with the program
3745 and learn how to think the CVS way?
3749 The users determine how a tool is to be used, not the designers. We,
3750 the users, have always used locking, our bosses demand locking,
3751 locking is good, locking is God. I don't want to hear any more
3752 lectures on the CVS model. Make locking work.
3754 Any organization making active changes to a source base will
3755 eventually face the need to do parallel development. Parallel
3756 development implies merges. (If you plan to keep separate copies of
3757 everything and never merge, good luck. Tell me who you work for so I
3758 can buy stock in your disk suppliers this year and sell your stock
3761 Merges will never go away. CVS chose to make "merges" stand front and
3762 center as an important, common occurrence in development. It is one
3763 way of looking at things.
3765 For free-format text, the merge paradigm gives you a considerable
3766 amount of freedom. It does take a bit of management, but any project
3767 should be ready to deal with it.
3769 On the other hand, there are many files that can't be merged using
3770 text merge techniques. Straight text merge programs like "diff3" are
3771 guaranteed to fail on executables (with relative branch statements),
3772 files with self-referential counts stored in the file (such as TAGS
3773 files), or files with relative motion statements in them (such as
3774 Frame MIF files, many postscript files). They aren't all binary files.
3776 For these types of files, and many others, there are only two
3779 Complex merge tools that are intimately aware of the contents of the
3780 files to be merged. (ClearCase, and probably others, allow you to
3781 define your own "files types" with associated "merge tools".)
3783 Serialization of access to the file. The only technical solution to
3784 the problem of serialization is "locking".
3786 Since you can call a program that offers:
3788 "Which one do you want? A/B?"
3790 a "merge tool", more and more merge tools will appear which can be
3791 hooked into a merge-intensive program like CVS. Think of a bitmap
3792 "merge" tool that displays the bitmaps on the screen and offers a
3793 "paint" interface to allow you to cut and paste, overlay, invert or
3794 fuse the two images such that the result is a "merged" file.
3796 My conclusion is that the need for locking is temporary, awaiting
3797 better technology. For large development groups, locking is not an
3798 alternative to merging for text files.
3800 Last modified: _6/13/1997_
3802 9. What is "checkout -s"? How is it different from "checkout -c"?
3804 The '-c' and '-s' options to "checkout" both cause the modules file to
3805 appear on standard output, but formatted differently.
3807 "checkout -c" lists the modules file alphabetized by the module name.
3808 It also prints all data (including options like '-a' and "-o <prog>")
3809 specified in the modules file.
3811 "checkout -s" lists the modules file sorted by "status" field, then by
3812 module name. The status field was intended to allow you to mark
3813 modules with strings of your choice to get a quick sorted report based
3814 on the data you chose to put in the status fields. I have used it for
3815 priority ("Showstopper", etc as tied into a bug database), for porting
3816 status ("Ported", "Compiled", etc. when porting a large collection of
3817 modules), for "assignee" (the person responsible for maintenance), and
3818 for "test suite" (which automatic test procedure to run for a
3821 Last modified: _6/13/1997_
3823 Category: /Commands_/commit_ci_com/
3825 " + "commit", "ci", "com""
3827 1. What is "commit" for?
3829 To store new revisions in the Repository, making them visible to other
3832 Last modified: _6/13/1997_
3834 2. If I edit ten files, do I have to type "commit" ten times?
3836 No. The "commit" command will take multiple filenames, directory names
3837 and relative pathnames on the command line and commit them all with
3838 the same log message. If a file is unchanged, even if it is explicitly
3839 listed on the command line, CVS will skip it.
3841 Like all CVS commands, "commit" will work on the whole directory by
3842 default. Just type "cvs commit" to tell CVS to commit all modified
3843 files (i.e. the files that "update" would display preceded by 'M') in
3844 the current directory and in all sub-directories.
3846 Last modified: _6/13/1997_
3848 3. Explain: cvs commit: Up-to-date check failed for `<file>'
3850 You may not "commit" a file if your BASE revision (i.e. the revision
3851 you last checked out, committed or retrieved via "update") doesn't
3852 match the HEAD revision (i.e the latest revision on your branch,
3853 usually the Main Branch).
3855 In other words, someone committed a revision since you last executed
3856 "checkout", "update" or "commit". You must now execute "update" to
3857 merge the other person's changes into your working file before
3858 "commit" will work. You are thus protected (somewhat) from a common
3859 form of race condition in source control systems, where a checkin of a
3860 minor alteration of a second copy of the same base file obliterates
3861 the changes made in the first.
3863 Normally, the "update" command's auto-merge should be followed by
3864 another round of building and testing before the "commit".
3866 Last modified: _6/13/1997_
3868 4. What happens if two people try to "commit" conflicting changes?
3870 Conflicts can occur only when two developers check out the same
3871 revision of the same file and make changes. The first developer to
3872 commit the file has no chance of seeing the conflict. Only the second
3873 developer runs into it, usually when faced with the "Up-to-date" error
3874 explained in the previous question.
3876 There are two types of conflicts:
3878 When two developers make changes to the same section of code, the
3879 auto-merge caused by "update" will print a 'C' on your terminal and
3880 leave "overlap" markers in the file.
3882 You are expected to examine and clean them up before committing the
3883 file. (That may be obvious to *some* of you, but . . .)
3885 A more difficult problem arises when two developers change different
3886 sections of code, but make calls to, or somehow depend on, the old
3887 version of each other's code.
3889 The auto-merge does the "right" thing, if you view the file as a
3890 series of text lines. But as a program, the two developers have
3891 created a problem for themselves.
3893 This is no different from making cross-referential changes in
3894 *separate* files. CVS can't help you. In a perfect world, you would
3895 each refer to the specification and resolve it independently. In the
3896 real world you have to talk/argue, read code, test and debug until the
3897 combined changes work again.
3899 Welcome to the world of parallel development.
3901 Last modified: _6/13/1997_
3903 5. I committed something and I don't like it. How do I remove it?
3905 Though you *can* use the "admin -o" (synonym: "rcs -o") command to
3906 delete revisions, unless the file you committed is so embarrassing
3907 that the need to eradicate it overrides the need to be careful, you
3908 should just grab an old version of the file ("update -p -r
3909 <previous-rev>" might help here) and commit it on top of the offending
3912 See Section 3B on "admin".
3914 Last modified: _6/13/1997_
3916 6. Explain: cvs commit: sticky tag `V3' for file `X' is not a branch
3918 The message implies two things:
3920 You created your working directory by using "checkout -r V3", or you
3921 recently executed "update -r V3".
3923 The tag named V3 is not a branch tag.
3925 CVS records (i.e. makes "sticky") any "-r <tag/rev>" argument handed
3926 to the "checkout" or "update" commands. The <tag/rev> is recorded as
3927 the CVS working branch, which is the branch to which "commit" will add
3930 Branch tags are created when you use the -b switch on the "tag" or
3931 "rtag" commands. Branch tags are magic tags that don't create a
3932 physical branch, but merely mark the revision to branch from when the
3933 branch is needed. The first commit to a magic branch creates a
3934 physical branch in the RCS files.
3936 You can commit onto the end of the Main Trunk, if you have no sticky
3937 tag at all, or onto the end of a branch, if you have a sticky branch
3938 tag. But you can't commit a file that has a sticky tag not pointing to
3939 a branch. CVS assumes a sticky Tag or Revision that does not refer to
3940 a branch is attached to the middle of a series of revisions. You can't
3941 squeeze a new revision between two others. Sticky dates also block
3942 commits since they never refer to a branch.
3946 If you don't want a branch and were just looking at an old revision,
3947 then you can move back to the Main Branch by typing:
3949 cvs update -A {files or dirs, default is '.'}
3951 or you can move to the branch named <branch_tag> by:
3953 cvs update -r <branch_tag> {files or dirs, default is '.'}
3957 If you really wanted to be on a branch and made an earlier mistake by
3958 tagging your branch point with a non-branch tag, you can recover by
3959 adding a new branch tag to the old non-branch tag:
3961 cvs rtag -b -r <oldtag> <newtag> <module>
3963 (It was not a big mistake. Branch-point tags can be useful. But the
3964 <newtag> must have a different name.)
3966 If you don't know the <module> name or don't use "modules", you can
3967 also use "tag" this way:
3969 cvs update -r <oldtag>
3970 cvs tag -b <newtag> .
3972 Then, to put your working directory onto the branch, you type:
3974 cvs update -r <newtag>
3976 You can't delete <oldtag> before adding <newtag>, and I would not
3977 advise deleting the <oldtag> at all, because it is useful in referring
3978 to the branch point. If you must, you can delete the non-branch tag
3981 cvs rtag -d <oldtag> <module>
3983 cvs tag -d <oldtag> .
3987 If you made the same mistake as in Scenario2 (of placing a non-branch
3988 tag where you wanted a branch tag), but really want <oldtag> to be the
3989 name of your branch, you can execute a slightly different series of
3990 commands to rename it and move your working directory onto the branch.
3992 Warning: This is not a way to rename a branch tag. It is a way to turn
3993 a non-branch tag into a branch tag with the same name.
3995 cvs rtag -r <oldtag> <branch_point_tag> <module>
3996 cvs rtag -d <oldtag> <module>
3997 cvs rtag -b -r <branch_point_tag> <oldtag> <module>
3999 Then, if you really must, delete the <branch_point_tag>:
4001 cvs rtag -d <branch_point_tag> <module>
4003 Note: The unwieldy mixture of "tag" and "rtag" is mostly because you
4004 can't specify a revision (-r <tag>) to the "tag" command.
4006 See 4C.3 for more info on creating a branch.
4008 Last modified: _6/13/1997_
4010 7. Why does "commit -r <tag/rev>" put newly added files in the Attic?
4012 If you specify "-r <rev>" (where <rev> is a dotted numeric number like
4013 2.4), it correctly sets the initial revision to <rev>, but it also
4014 attaches the numeric <rev> as a sticky tag and throws the file into
4015 the Attic. This is a bug. The obvious solution is to move the file out
4016 of the Attic into the associated Repository directory and "update -A"
4017 the file. There are no Tags to clean up.
4019 If you specify "-r <tag>" to commit a newly added file, the <tag> is
4020 treated like a <branch_tag>, which becomes a symbolic RCS label
4021 pointing to the string '1', which can be considered to be the "Main
4022 branch number" when the main branch is still at revision 1.N. The file
4023 is also thrown into the Attic. See 4C.8 for a way to recover from
4026 In fact, a plain "commit" without the "-r" will throw a newly added
4027 file into the Attic if you added it to a directory checked out on a
4028 branch. See 3A.[2-5].
4030 See Section 4C, on Branching, for many more details.
4032 Last modified: _6/13/1997_
4034 8. Why would a "commit" of a newly added file not produce rev 1.1?
4036 When committing a newly added file CVS looks for the highest main
4037 branch major number in all files in the ./CVS/Entries file. Normally
4038 it is '1', but if you have a file of revision 3.27 in your directory,
4039 CVS will find the '3' and create revision 3.1 for the first rev of
4040 <file>. Normally, the first revision is 1.1.
4042 Last modified: _6/13/1997_
4044 Category: /Commands_/diff_di_dif/
4046 " + "diff", "di", "dif""
4048 1. What is "diff" for?
4050 To display the difference between a working file and its BASE
4051 revision (the revision last checked out, updated or committed):
4055 To display the difference between a working file and a committed
4056 revision of the same file:
4058 cvs diff -r <tag/rev> <file>
4060 To display the difference between two committed revisions of the
4063 cvs diff -r <tag1/rev1> -r <tag2/rev2> <file>
4065 You can specify any number of <file> arguments. Without any <file>
4066 arguments, it compares the whole directory.
4068 In the examples above, "-D <date>" may be substituted wherever "-r
4069 <tag/rev>" appears. The revision a <date> refers to is the revision
4070 that existed on that date.
4072 Last modified: _6/13/1997_
4074 2. Why did "diff" display nothing when I know there are later committed
4075 revisions in the Repository?
4077 By default, "diff" displays the difference between your working file
4078 and the BASE revision. If you haven't made any changes to the file
4079 since your last "checkout", "update" or "commit" there is no
4080 difference to display.
4082 To display the difference between your working file and the latest
4083 revision committed to your current branch, type:
4085 cvs diff -r HEAD <file>
4087 Last modified: _6/13/1997_
4089 3. How do I display what changed in the Repository since I last executed
4090 "checkout", "update" or "commit"?
4092 A special tag (interpreted by CVS -- it does not appear in the Tag
4093 list) named "BASE" always refers to the revision you last checked out,
4094 updated or committed. Another special tag named "HEAD" always refers
4095 to the latest revision on your working branch.
4097 To compare BASE and HEAD, you type:
4099 cvs diff -r BASE -r HEAD <file>
4101 Last modified: _6/13/1997_
4103 4. How do I display the difference between my working file and what I
4104 checked in last Thursday?
4106 cvs diff -D "last Thursday" <file>
4108 where "last Thursday" is a date string. To be more precise, the
4109 argument to the '-D' option is a timestamp. Many formats are accepted.
4110 See the man page under "-D date_spec" for details.
4112 Last modified: _6/13/1997_
4114 5. Why can't I pass long options, like --unified, to "diff"?
4116 CVS only handles single character '-X' arguments, not the FSF long
4117 options. CVS also passes through only arguments it knows about,
4118 because a few arguments are captured and interpreted by CVS.
4120 If you didn't configure RCS and CVS to use the GNU version of diff,
4121 long options wouldn't work even if future versions of CVS acquire the
4122 ability to pass them through.
4124 Most of the long options have equivalent single-character options,
4125 which do work. The "--unified" option is equivalent to '-u' in
4126 revisions of GNU diff since 1.15.
4128 Last modified: _6/13/1997_
4130 Category: /Commands_/export_exp_ex/
4132 " + "export", "exp", "ex""
4134 1. What is "export" for?
4136 "export" checks out a copy of a module in a form intended for export
4137 outside the CVS environment. The "export" command produces the same
4138 directory and file structure as the "checkout" command, but it doesn't
4139 create "CVS" sub-directories and it removes all the RCS keywords from
4142 Last modified: _6/13/1997_
4144 2. Why does it remove the RCS keywords so I can't use the "ident" command
4145 on the source files?
4147 It removes the RCS keywords, so that if the recipient of the exported
4148 sources checks them into another set of RCS files (with or without
4149 CVS), and then makes modifications through RCS or CVS commands, the
4150 revision numbers that they had when you exported them will be
4151 preserved. (That ident no longer works is just an unfortunate side
4154 The theory is that you are exporting the sources to someone else who
4155 will make independent changes, and at some point you or they will want
4156 to know what revisions from your Repository they started with
4157 (probably to merge changes, or to try to decide whether to merge
4160 A better way to handle this situation would be to give them their own
4161 branch of your Repository. They would need to remember to checkin the
4162 exported sources with RCS IDs intact (ci -k) so that their changes
4163 would get revision numbers from the branch, rather than starting at
4164 1.1 again. Perhaps a future version of CVS will provide a way to
4165 export sources this way.
4167 Contributed by Dan Franklin
4169 Last modified: _6/13/1997_
4171 3. Can I override the '-kv' flag CVS passes to RCS?
4173 Not as of CVS version 1.4.
4175 Last modified: _6/13/1997_
4177 4. Why doesn't "export" have a '-k' flag like "import" does?
4179 Export is intended for a specific purpose -- to remove all trace of
4180 revision control on the way *out* of CVS.
4182 Last modified: _6/13/1997_
4184 5. Why does "export -D" check out every file in the Attic?
4186 See 5B.3 for an explanation of the same problem with "update".
4188 Last modified: _6/13/1997_
4190 Category: /Commands_/history_hi_his/
4192 " + "history", "hi", "his""
4194 1. What is "history" for?
4196 To provide information difficult or impossible to extract out of the
4197 RCS files, such as a "tag" history or a summary of module activities.
4199 Last modified: _6/13/1997_
4201 2. Of what use is it?
4203 I have found it useful in a number of ways, including:
4205 Providing a list of files changed since
4208 - Yesterday, last Thursday, or a specific date.
4209 - Someone changed a specific file.
4211 Providing a list of special events:
4213 - Files added or removed since one of the above events.
4214 - Merge failures since one of the above events. (Where did the
4216 - Has anyone (and who) grabbed the revision of this file I committed
4217 last week, or are they still working blind?
4219 Telling me how often a file/directory/module has been changed.
4221 Dumping a summary of work done on a particular module, including who
4222 last worked on it and what changed.
4224 Displaying the checked-out modules and where they are being worked
4227 To tell me what users "joe" and "malcolm" have done this week.
4229 Last modified: _6/13/1997_
4231 3. What is this, Big Brother?
4235 Ignorance is Strength.
4237 Normally manager types and those with the power to play Big Brother
4238 don't care about this information. The Software Engineer responsible
4239 for integration usually wants to know who is working on what and what
4240 changed. Use your imagination.
4242 Last modified: _6/13/1997_
4244 4. I deleted my working directory and "history" still says I have it
4245 checked out. How do I fix it?
4247 You can use "release -f" to forcibly add a "release" record to the
4248 history file for a working directory associated with a "module". If
4249 your version of "release" doesn't have the '-f' option, or you checked
4250 out the directory using a relative path, you have to edit the
4251 $CVSROOT/CVSROOT/history file.
4253 You can remove the last 'O' line in the history file referring to the
4254 module in question or add an 'F' record.
4256 Last modified: _6/13/1997_
4258 5. So I *can* edit the History file?
4260 Yes, but if you are using history at all, you should take a little
4261 care not to lose information. I normally use Emacs on the file, since
4262 it can detect that a file has changed out from under it. You could
4263 also copy and zero out the history file, edit the copy and append any
4264 new records to the edited copy before replacing it.
4266 Last modified: _6/13/1997_
4268 6. Why does the history file grow so quickly?
4270 It stores 'U' records, which come in handy sometimes when you are
4271 tracking whether people have updated each other's code before testing.
4272 There should (and probably will sometime) be a way to choose what
4273 kinds of events go into the history file.
4275 The contributed "cln_hist.pl" script will remove all the 'U' records,
4276 plus matching pairs of 'O' and 'F' records during your normal clean up
4277 of the history file.
4279 Last modified: _6/13/1997_
4281 7. What is the difference between "cvs history -r <tag/rev>" and "cvs
4284 The '-t' option looks for a Tag record stored by "rtag" in the history
4285 file and limits the search to dates after the last <tag> of the given
4288 The '-r' option was intended to search all files looking for the <tag>
4289 in the RCS files. It takes forever and needs to be rewritten.
4291 Last modified: _6/13/1997_
4293 8. Why does "cvs history -c -t <tag>" fail to print anything?
4295 You have been using "tag" instead of "rtag". The "tag" command
4296 currently doesn't store a history record. This is another remnant of
4297 CVS's earlier firm belief in "modules". But it also has a basis in how
4298 "rtag" and "tag" were originally used.
4300 "rtag" was intended for large-scale tagging of large chunks of the
4301 Repository, an event work recording. "tag" was intended for adding and
4302 updating tags on a few files or directories, though it could also be
4303 used to tag the entire checked-out working tree when there is no
4304 module defined to match the tree or when the working tree is the only
4305 place where the right collection of revisions to tag can be found.
4307 Last modified: _6/13/1997_
4309 9. "cvs history -a -o" only printed one line for each checked-out module.
4310 Shouldn't it print all the directories where the modules are checked out?
4314 Command Question it is supposed to answer.
4315 ---------------- ------------------------------------------
4316 cvs history -o What modules do I have checked out?
4317 cvs history -a -o <same for all users>
4319 cvs history -o -w What working directories have I created
4320 and what modules are in them?
4321 cvs history -a -o -w <same for every user>
4323 The -o option chooses the "checked out modules" report, which is the
4324 default history report.
4326 Last modified: _6/13/1997_
4328 10. I can't figure out "history", can you give me concrete examples?
4330 Default output selects records only for the user who executes the
4331 "history" command. To see records for other users, add one or more "-u
4332 user" options or the '-a' option to select *all* users.
4334 To list (for the selected users): Type "cvs history" and:
4336 * Checked out modules: -o (the default)
4337 * Files added since creation: -x A
4338 * Modified files since creation: -c
4339 * Modified files since last Friday: -c -D 'last Friday'
4340 * Modified files since TAG was added: -c -t <tag>
4341 * Modified files since TAG on files: -c -r <tag>
4342 * Last modifier of file/Repository X? -c -l -[fp] X
4343 * Modified files since string "str": -c -b str
4344 * Tag history: (Actually "rtag".) -T
4345 * History of file/Repository/module X: -[fpn] X
4346 * Module report on "module": -m module
4348 Last modified: _6/13/1997_
4350 11. Can we merge history files when we merge Repositories?
4352 Assuming that the two Repositories have different sets of pathnames,
4353 it should be possible to merge two history files by sorting them
4354 together by the timestamp fields.
4356 You should be able to run:
4358 sort -k 1.2 ${dir1}/history ${dir2}/history > history
4360 If you "diff" a standard history file before and after such a sort,
4361 you might see other differences caused by garbage (split lines, nulls,
4362 etc) in the file. If your Repository is mounted through NFS onto
4363 multiple machines you will also see a few differences caused by
4364 different clocks on different machines. (Especially if you don't use
4365 NTP to keep the clocks in sync.)
4367 Last modified: _6/13/1997_
4369 Category: /Commands_/import_im_imp/
4371 " + "import", "im", "imp""
4373 1. What is "import" for?
4375 The "import" command is a fast way to insert a whole tree of files
4378 The first "import" to a particular file within the Repository creates
4379 an RCS file with a single revision on the "Vendor branch." Subsequent
4380 "import"s of the same file within the Repository append a new revision
4381 onto the Vendor branch. It does not, as some seem to believe, create a
4382 new branch for each "import". All "imports" are appended to the single
4385 If the file hasn't changed, no new revision is created -- the new
4386 "Release-Tag" is added to the previous revision.
4388 After the import is finished, files you have not changed locally are
4389 considered to have changed in the "Main line of development". Files
4390 you *have* changed locally must have the new Vendor code merged into
4391 them before they are visible on the "Main line".
4395 Last modified: _6/13/1997_
4397 2. How am I supposed to use "import"?
4399 Create a source directory containing only the files you want to
4400 import. Make sure you clean up any cruft left over from previous
4401 builds or editing. You want to make sure that the directory contains
4402 only what you want to call "source" from which everything else is
4405 If this is not the first import from this "Vendor", you should also
4406 compare the output of "find . ! -name CVS -print | sort" executed both
4407 at the head of a checked out working directory and at the head of the
4408 sources to be imported. If you find any deleted or renamed files, you
4409 have to deal with them by hand. (See 4B.8 on renaming.)
4411 "cd" into your source directory and type:
4413 cvs import -m "Message" <repos> <Vendor-Tag> <Release-Tag>
4415 where <repos> is the relative directory pathname within the Repository
4416 that corresponds to the sources you are importing.
4418 You might also consider using the "-I !" option to avoid ignoring
4419 anything. It is easier to remove bogus files from the Repository than
4420 to create a sparse tree of the ignored files and rerun "import".
4422 For example, if the FSF, CVS, Make and I are still active in the year
4423 2015, I'll import version 89.53 of GNU make this way:
4425 cvs import -m "GNUmake V89.53" gnu/make GNU GNUMAKE_89_53
4427 See 3H.13 for more details.
4429 Last modified: _6/13/1997_
4431 3. Why does import put files on a branch? Why can't I work on the main
4432 trunk instead of a Vendor branch?
4434 This was a Design choice. The Vendor branch is the way "import" deals
4435 with a Vendor release. It is a solution to the Engineering problem of
4436 how to merge multiple external releases of Vendor-supplied sources
4437 into your ongoing work. The Vendor releases are kept on a separate,
4438 special, "Vendor" branch and your work is kept on the RCS trunk. New
4439 Vendor releases are imported onto the Vendor branch and then merged
4440 into your work, if there is any, on the trunk.
4442 This way, you can use CVS to find out not only about your work, but
4443 you can also find out what the Vendor changed by diffing between two
4444 of the Release Tags you handed to "import".
4446 CVS was designed to work this way. If you use CVS in some other way,
4447 you should think carefully about what you are doing.
4449 Note that the CVS "Main Branch" and the RCS Main Trunk are not the
4450 same. Placing files on the Vendor Branch doesn't keep you from
4451 creating a development branch to work on.
4453 See Section 4C, on Branching.
4455 If you are not working with 3rd party (i.e. Vendor) sources, you can
4456 skip the "import" and avoid the Vendor branch entirely. It works just
4457 as well to move pre-existing RCS files into Repository directories.
4459 You can create a whole Repository tree by copying a directory
4460 hierarchy of normal source files directly into the Repository and
4461 applying CVS to it. Here's an idea you should *test* before using:
4463 cd <your source tree>
4465 set module = xyzzy <<== Your choice of directory name
4466 mkdir $CVSROOT/$module
4468 (cd $source; tar cf - .) | tar xvpBf -
4469 find . -type f -exec ci -t-Original. {} \;
4471 The RCS "ci" command, without -u or -l options, will turn your source
4472 file into an RCS (",v") and delete the original source.
4474 Last modified: _6/13/1997_
4476 4. Is there any way to import binary files?
4478 If you configured CVS to use the GNU version of "diff" and "diff3",
4479 then you can import any kind of file.
4481 Binary files with RCS keywords in them are a problem, since you don't
4482 want them to expand.
4484 If the tree you are about to "import" is entirely filled with binary
4485 files, you can use the '-ko' option on "import". Otherwise, I would
4486 run the import normally, then fix the binary files as described below
4489 See 4D.1 on Binary files.
4491 Last modified: _6/13/1997_
4493 5. Why does "import" corrupt some binary files?
4495 The RCS "co" command, when it is invoked by a CVS "checkout" or
4496 "update" (or after a "commit") command, searches for and expands a
4497 list of keywords within the file. They are documented in the RCS "co"
4498 man page. Strings such as "$\Id$" (or "$\Id:"), or "$\Revision$" (or
4499 "$\Revision:") are altered to the include the indicated information.
4501 [[Note: The keywords should appear in the text without the '\'
4502 character I have inserted to *avoid* expansion here. The only real RCS
4503 keywords in this document are at the top of the file, where I store
4504 the Revision and Date.]]
4506 If RCS keyword strings show up in a binary file, they will be altered
4507 unless you set the '-ko' option on the RCS files to tell RCS to keep
4508 the original keyword values and not to expand new ones. After
4509 "import", you can set the '-ko' option this way:
4511 cvs admin -ko <file>
4515 After an import that didn't use '-ko' (because the whole tree wasn't
4516 of binary files) you should fix up the binary files as described above
4517 before checking out any new copies of the files and before updating
4518 any working directories you checked out earlier.
4520 See 4D.1 on Binary files.
4522 Last modified: _6/13/1997_
4524 6. How do I retain the original $\Revision$ strings in the sources?
4526 If you want to leave old RCS keywords as they are, you can use the
4527 '-ko' tricks described above.
4529 Last modified: _6/13/1997_
4531 7. I imported some files for the Yarg compiler that compiles files with a
4532 suffix of ".yarg" and whose comment prefix is "YARG> ". When I check them
4533 out, they will no longer compile because they have this junk in them. Why?
4535 YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>
4537 # Revision 1.3 1998/03/03 00:16:16 bubba
4538 # What is 2+2 anyway?
4540 # Revision 1.2 1998/03/03 00:15:15 bubba
4541 # Added scorekeeping.
4543 YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>
4545 Well bubba, "Yarg" hasn't hit the big time yet. Neither RCS nor CVS
4546 know about your suffix or your comment prefix. So you have two
4549 Check out the Yarg-less module, and tell all the files about your
4550 comment prefix. Visit each directory and type:
4552 cvs admin -c"YARG> " *.yarg
4554 If *all* files in the whole directory tree are Yarg files, you can use
4557 cvs admin -c"YARG> " .
4559 Then save any changes you made, remove all the "*.yarg" files and grab
4560 new copies from the Repository:
4562 rm *.yarg (or: find . -name '*.yarg' -exec rm {} ';') (or: find .
4563 -name '*.yarg' -print | xargs rm) (or: find . -name '*.yarg' -print0 |
4564 xargs -0 rm if you have spaces in filenames and the GNU find/xargs.)
4567 It might be faster to remove the whole directory and check it out
4570 Change the import.c file in the CVS sources and add the .yarg
4571 suffix, along with the "YARG> " comment prefix to the "comtable"
4574 If you ever plan to add new files with $\Log in them, you should also
4575 go into the RCS sources and make the same change in the table
4576 contained in the "rcsfnms.c" file.
4578 Then delete the imported files from the Repository and re-"import" the
4581 Last modified: _6/13/1997_
4583 8. How do I make "import" save the timestamps on the original files?
4585 Use "import -d" to save the current timestamps on the files as the RCS
4588 See 4D.8 for another aspect of file timestamps.
4590 Last modified: _6/13/1997_
4592 9. Why can't I "import" 3 releases on different branches?
4594 I'll bet you typed something like this:
4597 cvs import -b 1.1.2 VENDOR2 Version2
4599 cvs import -b 1.1.3 VENDOR3 Version3
4601 cvs import -b 1.1.4 VENDOR4 Version4
4603 This is wrong, or at least it won't help you much. You have created
4604 three separate Vendor branches, which is probably not what you wanted.
4606 Earlier versions of CVS, as described in Brian Berliner's Usenix
4607 paper, tried to support multiple Vendor branches on the theory that
4608 you might receive source for the *same* program from multiple vendors.
4609 It turns out that this is very rare, whereas the need to branch in
4610 *your* development, for releases and for project branches, is much
4613 So the model now is to use a single vendor branch to contain a series
4614 of releases from the same vendor. Your work moves along on the Main
4615 Trunk, or on a CVS branch to support a real "branch in development".
4617 To set this up, you should type this instead of the above:
4620 cvs import VENDOR Version2
4622 cvs import VENDOR Version3
4624 cvs import VENDOR Version4
4626 Last modified: _6/13/1997_
4628 10. What do I do if the Vendor adds or deletes files between releases?
4630 Added files show up with no extra effort. To handle "removed" files,
4631 you should always compare the tree structure of the new release
4632 against the one you have in your Repository. If the Vendor has removed
4633 files since the previous release, go into a working directory
4634 containing your current version of the sources and "cvs remove"
4635 (followed by "cvs commit" to make it really take effect) each file
4636 that is no longer in the latest release.
4638 Using this scheme will allow you to "checkout" any version of the
4639 vendor's code, with the correct revisions and files, by using
4640 "checkout -r Version[234]".
4642 Renames are harder to find, since you have to compare file contents to
4643 determine that one has occurred. If you notice one, see 4B.8 on
4646 Last modified: _6/13/1997_
4648 11. What about if the Vendor changes the names of files or directories, or
4649 rearranges the whole structure between releases?
4651 Currently CVS can't handle this cleanly. It requires "renaming" a
4652 bunch of files or directories.
4654 See 4B.8 on "renaming" for more details.
4656 What I generally do is to close the Repository for a while and make
4657 changes in both the Repository and in a copy of the vendor release
4658 until the structure matches, then execute the import.
4660 If you ever have to check out and build an old version, you may have
4661 to use the new, or completely different Makefiles.
4663 Last modified: _6/13/1997_
4665 12. I thought "import" was for Vendor releases, why would I use it for code
4666 of my own? Do I have to use import?
4668 For code you produce yourself, "import" is a convenience for fast
4669 insertion of whole trees. It is not necessary. You can just as easily
4670 create ",v" files using the RCS "ci" command and move them directly
4671 into the Repository.
4673 Other than the CVSROOT directory, the Repository consists entirely of
4674 directories of ",v" files. The Repository contains no other state
4677 See Section 4B, on Setting up and Managing the Repository.
4679 Last modified: _6/13/1997_
4681 13. How do I import a large Vendor release?
4683 When the sum of the changes made by the Vendor and the changes made by
4684 local developers is small, "import" is not a big problem. But when you
4685 are managing a large Repository, any care taken up front will save you
4688 First read the following, then, before executing "import", see the
4689 questions in Section 4C dealing with branch merges and Vendor branch
4692 If this is not the first import of this code, before starting, rtag
4693 the whole directory you will be changing.
4695 The first step is to make sure the structure of the new files
4696 matches the structure of the current Repository.
4698 Run "find . -print | sort" on both trees and "diff" the output.
4700 Alter the "source" tree until the "diff" (of the list of filenames,
4701 not of the whole trees) shows that the directory structures are
4704 The "comm" command, if you have it, can help figure out what has been
4705 added or deleted between releases.
4707 If they deleted any files, you can handle them cleanly with "cvs
4708 remove". The command "comm -23 files.old files.new" will show you a
4709 list of files that need to be removed.
4711 You should examine the list first to see if any have been renamed
4712 rather than simply deleted.
4714 If they renamed any files, see 4B.8 on renaming files.
4716 Remember to *SAVE* the output from the import command.
4718 When you have dealt with removed and renamed files, then you can
4722 cvs import -I ! -m "Message" <repos> <VendorTag> <ReleaseTag>
4726 "-I !" is an optional argument that keeps "import" from ignoring
4727 files. The comparison of the "find" commands above will probably avoid
4728 the need for this, but it is easier to remove files from the
4729 Repository than to run a subset "import" to catch just the ignored
4730 files. [You might have to quote or backwhack the '!'.]
4732 Message is the log message to be stored in the RCS files.
4734 <repos> is a relative path to a directory within the
4735 Repository. The directory <new source> must be at
4736 the same relative level within the new sources as
4737 the <repos> you give is within the Repository. (I
4738 realize this is not obvious. Experiment first.)
4740 <VendorTag> is a Tag used to identify the Vendor who sent you
4741 the files you are importing. All "imports" into
4742 the same <repos> *must* use the same VendorTag.
4743 You can find it later by using the "log" command.
4745 <ReleaseTag> is a Tag used to identify the particular release of the
4746 software you are importing. It must be unique and should be mnemonic
4747 -- at least include the revision number in it. (Note: you can't use
4748 '.' characters in a Tag. Substitute '_' or '-'.)
4750 There will be six categories of files to deal with. (Actually there
4751 are eight, but you have already dealt with "removed" and "renamed"
4754 If this is the first "import" into a given <repos> directory, only the
4755 first three of these ('I', 'L' and 'N') can occur.
4759 CVS prints: I filename
4761 You'll need to examine it to see if it *should* have been ignored. If
4762 you use "-I !", nothing will be ignored.
4766 CVS prints: L linkname
4768 Links are "ignored", but you'll probably want to create a "checkout
4769 helper" function to regenerate them.
4773 CVS prints: N filename
4775 CVS creates a new file in the Repository. You don't have to do
4776 anything to the file, but you might have to change Makefiles to refer
4777 to it if this is really a new file.
4779 A file unchanged by the Vendor since its last release.
4781 CVS prints: U filename
4783 CVS will notice this and simply add the new ReleaseTag to the latest
4784 rev on the Vendor branch.
4786 No work will be needed by you, whether you have changed the file or
4787 not. No one will notice anything.
4789 A file changed by the Vendor, but not by you.
4791 CVS prints: U filename
4793 CVS should add the file onto the vendor branch and attach the Release
4796 When you next execute "update" in any working directory you'll get the
4799 A file changed by both the Vendor and by you.
4801 CVS prints: C filename
4803 These are the trouble files. For each of these files (or in groups --
4804 I usually do one directory at a time), you must execute:
4806 cvs update -j <PreviousReleaseTag> -j <ReleaseTag>
4808 cvs update -j <VendorTag:yesterday> -j <VendorTag>
4810 It will print either 'M' (if no overlaps) or 'C', if overlaps. If a
4811 'C' shows up, you'll need to edit the file by hand.
4813 Then, for every file, you'll need to execute "cvs commit".
4815 See the part of Section 4C dealing with branch merges.
4817 If you are truly performing a large import, you will most likely
4818 need help. Managing those people is another problem area.
4820 Since the merge of the Vendor branch is just like any other merge, you
4821 should read section 4C for more info about performing and cleaning up
4824 The larger the import, and the larger the group of people involved,
4825 the more often you should use "tag" and "rtag" to record even trivial
4826 milestones. See 4C.14, especially the "paranoid" section.
4828 Before starting the import, you should install and test a "commitinfo"
4829 procedure to record all commits in a file or via Email to a mail
4830 archive. Along with the tags you placed on the Repository before the
4831 import, this archive will help to track what was changed, if problems
4834 There are four stages to the recovery:
4836 Parcel out the work -- Effective Emacs Engineering.
4838 As input to the assignment process, you might want to examine the tree
4839 and record the last person who changed the file. You can also
4840 research, if you don't already know, who is expert in each area of the
4843 Examine the import log (you saved the output, right?), estimate how
4844 much work is involved in each area and assign groups of files to
4845 individual developers. Unless some directory is immense, it is easier
4846 to manage if you assign whole directories to one person.
4848 Keep a list. Suggest a completion date/time. Tell them to "commit" the
4849 file when they are finished with the merge. If you tagged the
4850 Repository before starting the import, you should have no trouble
4851 figuring out what happened.
4853 If you can, find out (or tell them) which working directory to use.
4854 You should verify that the working directory they use is on the Main
4855 Branch ("update -A") and without modified files.
4857 If you trust your crew, have them notify you by Email. Have them send
4858 you the output from "cvs update" in their working directory. You might
4859 have to poll some people until you are certain they have finished, or
4860 have given up. (This is not an invention. I've heard a false, "Yeah,
4861 sure. I finished yesterday," more times that you'd believe.)
4863 When all reports are in, go on to the Source Verification stage.
4865 Source Verification -- CVS and other Tools.
4867 If you didn't dictate which ones to use, find all working directories
4868 and run "cvs -n update" in all of them. The history command and the
4869 "commitinfo" log you set up might help to find checked out working
4872 Sticky conflict flags will help, but they can't recover from
4873 sloppiness or incompetence. You might want to check everything out
4874 into a tree and grep for the parts of the merge conflict markers CVS
4875 doesn't look for. CVS looks for the string '^>>>>>>> '. The merge
4876 operation also puts '^<<<<<<< ' and '^======= ' markers in the file
4877 that careless developers might leave there.
4879 If you find problems simply by looking at the source files and working
4880 directories, start the flogging now. Resolving the textual conflicts
4881 is the easy part. Weed the turkeys out before reaching the next part
4882 of the cleanup -- the resolution of logical conflicts.
4884 Then apply a set of post-commit tags.
4886 Logical Verification -- Diff and powerful eyeballs.
4888 No source control system can solve the problem of resolving
4889 distributed conflicts in program logic. If you change the argument
4890 template for function A (defined in file A.c) and add new calls to
4891 function A from within function B (defined in file B.c) using the old
4892 argument format, you are outside the realm of CVS's competence.
4894 Assign someone to understand what the Vendor changed by running "cvs
4895 diff -c -r <PreviousReleaseTag> <ReleaseTag>", where the tags were
4896 those handed to the last two invocations of "import".
4898 Then have the same person compare that output (logically or you can
4899 actually diff the diffs) to the output of the similar "cvs diff -c -r
4900 <pre-import-tag> <post-commit-tag>". The two sets of differences
4901 should be almost identical. They should both show only the work *you*
4904 Product Verification -- Build and Test.
4906 Don't let your help off the hook until you verify that the merge
4907 actually produced something that can compile and pass tests. Compiling
4908 should really be part of the logical verification phase, but you
4909 should test the output of the build system before declaring victory
4910 and releasing the troops.
4912 After it is all built, apply another set of tags to mark the end of
4913 the "import process". You can delete the intermediate tags you added
4914 during source and logic testing, but keep the "pre-import" and
4915 "post-import" tags forever.
4917 Of course, experience can tell you when to skip a step. But I'd start
4918 out by considering each one as necessary unless you can prove
4921 Last modified: _6/13/1997_
4923 14. Explain: ERROR: cannot create link to <file>: Permission denied
4925 This error appears when you try to execute a second (or later)
4926 "import" into the same module from a directory to which you don't have
4929 The "link error" is caused by a feature purposely added to speed up
4932 Though the error message is somewhat strange, it indicates that
4933 "import" is supposed to be executed only in writable directories.
4935 Last modified: _6/13/1997_
4937 15. Where does the -m <message> go when the file doesn't change?
4939 The <message> handed to import is used as an RCS log message, but only
4940 if the imported file changed since the last version on the Vendor
4941 branch. If the imported file hasn't changed, then no new revision is
4942 created. The <ReleaseTag> is still applied, but to the previous
4943 revision. So the Tags are still correct, but the message is lost.
4945 Maybe it should be appended to the previous log message. But currently
4948 Last modified: _6/13/1997_
4950 16. How do I "import" just the files ignored by a previous "import"?
4952 A real answer follows, but first, an editorial:
4954 I am now convinced that you should always use the "-I !" option.
4955 Removing a few extraneous files from the Repository is a lot easier
4956 than the recovery step described below.
4958 Let's assume your original import procedure was: (We assume there is
4959 enough disk space in /tmp.)
4961 cd <head-of-vendor-tree>
4962 cvs import -m 'xyz 1.3' gnu/xyz GNU GNUXYZ_1_3 | tee /tmp/IMP
4964 To import just the files ignored by "import", I would do this:
4966 Create a list of the ignored files to import:
4968 cd <head-of-vendor-tree> awk '/^I / {print $2}' /tmp/IMP | sed
4969 's|^gnu/xyz/||' > /tmp/IG [Edit the IG file to contain just the files
4972 Then create a sparse directory by handing your list to the GNU
4973 version of "tar", installed in many places as "gtar":
4975 mkdir /tmp/FIXUP gtar -T /tmp/IG -c -f - . | (cd /tmp/FIXUP; gtar xvBf
4978 Then rerun the import. Use the exact same command, but execute it in
4979 the sparse directory tree you just created. And this time, tell it not
4983 cvs import -I ! -m 'xyz 1.3' gnu/xyz GNU GNUXYZ_1_3
4985 Last modified: _6/13/1997_
4987 17. Why did "import" ignore all the symlinks?
4989 This is another design choice.
4991 Like the Unix "tar" command, "import" could sprout an option to follow
4992 symbolic links, but I don't think CVS will ever follow symbolic links
4995 Two possible future enhancements have been seriously discussed:
4997 Treat symbolic links as data in its parent directory (the way
4998 ClearCase does) in some sort of per-directory control file.
5000 Treat symbolic links as version-controlled elements themselves,
5001 whose data is the value of readlink(2).
5003 For now, they are simply ignored.
5005 If you want to save and reconstruct symlinks, you might want to define
5006 a "checkout" or "update" program in the modules file which could
5007 consult a file kept under CVS in your working directory and make sure
5008 the specified links are in place.
5010 Last modified: _6/13/1997_
5012 Category: /Commands_/log_lo_rlog/
5014 " + "log", "lo", "rlog""
5016 1. What is "log" for?
5018 To provide an interface to the RCS "rlog" command, which displays
5019 information about the underlying RCS files, including the revision
5020 history and Tag (RCS calls it a "symbol") list.
5022 Last modified: _6/13/1997_
5024 2. How do I extract the log entries between two revisions?
5026 If both <rev1> and <rev2> are on the same branch, you can get what you
5027 are looking for with: (If they aren't on the same branch you'll either
5028 get an error or a display of the whole change log.)
5030 cvs log -r<rev1>:<rev2> <file>
5032 If you want all the revisions on the branch from <rev1> to the end of
5033 the branch <rev1> is on, you can use:
5035 cvs log -r<rev1>: <file>
5037 (If <rev1> is a numeric RCS symbol attached to a branch revision with
5038 an even number of '.'s in it, you get the whole branch.)
5040 If you want all the revisions on the branch from the beginning of the
5041 branch <rev2> is on up to revision <rev2>, you can use:
5043 cvs log -r:<rev2> <file>
5045 Note: Depending on whether <rev1> and <rev2> are:
5047 - numeric or symbolic
5048 - in the file or not
5049 - on the same branch or not
5051 the RCS "rlog" (and therefore the "cvs log") command will
5052 display some combination of:
5055 - (intuitively correct) partial log listings
5056 - a display of the entire change log.
5058 Last modified: _6/13/1997_
5060 3. How do I extract the log entries on a whole branch?
5062 cvs log -r<rev> <file>
5064 where <rev> must be a branch revision (one with an even number of
5065 dots) or a *non-branch* tag on a branch revision. Non-branch tags on a
5066 branch revision are not normally attached by CVS, to add one you will
5067 have to explicitly tag a physical branch number within each file.
5068 Since these branch numbers are almost never the same in different
5069 files, this command is not all that useful.
5071 The intuitive command (at least from the CVS perspective):
5073 cvs log -r<branch_tag> <file>
5077 Last modified: _6/13/1997_
5079 4. How do I generate ChangeLogs from RCS logs?
5081 A program called rcs2log is distributed as part of GNU Emacs 19. A
5082 (possibly older) version of this program appears in the contrib
5083 directory of the cvs source tree.
5085 Last modified: _6/13/1997_
5087 5. Why does "log" tell me a file was committed exactly 5 hours later
5091 I can tell by this question that you were working in a time zone that
5092 is 5 hours behind GMT (e.g. the U.S. East Coast in winter).
5094 RCS file dates are stored in GMT to allow users in different time
5095 zones to agree on the meaning of a timestamp. At first glance this
5096 doesn't seem necessary, but many companies use distributed file
5097 systems, such as NFS or AFS, across multiple timezones.
5099 Some standard form must be used. GMT, as the "grid origin", is an
5100 obvious candidate. The only other reasonable choice is to put the
5101 timezone information in all the time stamps, but that changes the RCS
5102 file format incompatibly, a step which has been avoided in the last
5105 Last modified: _6/13/1997_
5107 Category: /Commands_/patch_pa_rdiff/
5109 " + "patch", "pa", "rdiff""
5111 1. What is "patch" for?
5113 To produce a "diff" between tagged releases to be handed to the
5114 "patch" command at other sites. This is the standard way that source
5115 patches are distributed on the network.
5117 Last modified: _6/13/1997_
5119 2. Why does "patch" include files from the Attic when I use '-D'?
5121 See the explanation of the same problem with "update -D" contained in
5124 Last modified: _6/13/1997_
5126 3. How do I make "patch" produce a patch for one or two files? It seems to
5127 work only with modules.
5129 Patch is intended for producing patches of whole modules between
5130 releases to be distributed to remote sites. Instead of "patch", you
5131 can use the "diff" command with the '-c' context option:
5133 cvs diff -c -r <rev/tag> -r <rev/tag> <file1> . . .
5135 The patch command will be able to merge such a "diff" into the remote
5138 If you configured CVS to use a version of "diff" that supports the
5139 '-u' option, you can produce a more compact "patch" in "unidiff"
5140 format. The latest revisions of the patch command can parse and apply
5141 patches in "unidiff" format.
5143 Last modified: _6/13/1997_
5145 Category: /Commands_/release_re_rel/
5147 " + "release", "re", "rel""
5149 1. What is "release" for?
5151 To register that a module is no longer in use. It is intended to
5152 reverse the effects of a "checkout" by adding a record to the history
5153 file to balance the checkout record and by optionally allowing you to
5154 delete the checked-out directory associated with the module name.
5156 Last modified: _6/13/1997_
5158 2. Why can't I reverse a "cvs checkout path/name/subdir" with a "cvs
5159 release path/name/subdir" without an "unknown module name"?
5161 A simplistic implementation. (I can say this -- I wrote it.)
5163 The "release" function was written for CVS 1.2 under the assumption
5164 that the "module name" is a first class, unavoidable interface to the
5165 Repository, allowing no way to retrieve anything other than by module
5166 name. Though it is easier to program that way, many users of CVS
5167 believe the modules support to be too primitive to allow such a
5170 Since "release" was written, other parts of CVS broke that assumption.
5171 It needs to be revised.
5173 Last modified: _6/13/1997_
5175 3. Why can't I "release" portions of a checked out directory? I should be
5176 able to "release" any file or sub-directory within my working directory.
5178 This isn't really a limitation in "release", per se. CVS doesn't try
5179 to keep track of which files in which directories are "checked out"
5180 and which are just lying there. You can delete directories and
5181 "update" will not bring them back unless you add a special "-d"
5184 In other words, CVS doesn't keep track of how you adjust the partition
5185 between files you consider part of your working set and files that
5186 were checked out because they are part of the same module or
5187 directory. And neither does "release".
5189 In future CVS releases, "release" might become sophisticated enough to
5190 handle both the reversal of a "checkout" and the deletion of random
5191 portions of the working directory, but it isn't that way now.
5193 Last modified: _6/13/1997_
5195 4. I removed the tree that I was about to start working on. How do I tell
5196 cvs that I want to release it if I don't have it anymore?
5200 Last modified: _6/13/1997_
5202 5. Why doesn't "release -d module" reverse a "checkout module"?
5204 It does, if you are using "module" in a way that "release" expects: a
5205 non-alias string in the left column of the "modules" database.
5207 If "module" is really an alias, or if you are using a relative path in
5208 the place of "module", or if you renamed the directory with the -d
5209 option in the modules file or on the "checkout" command line, then the
5210 current version of "release" won't work.
5212 Future versions of "release" will probably fix most of these.
5214 Last modified: _6/13/1997_
5216 6. Why can't I release a module renamed with "cvs checkout -d"?
5218 The current version of "release" doesn't know how to track the
5219 renaming option ('-d') of the "checkout" command. It will probably be
5220 fixed in the future.
5222 Last modified: _6/13/1997_
5224 Category: /Commands_/remove_rm_delete/
5226 " + "remove", "rm", "delete""
5228 1. What is "remove" for?
5230 To remove a file from the working branch. It removes a file from the
5231 main branch by placing it in an "Attic" directory.
5233 Last modified: _6/13/1997_
5235 2. Why doesn't "remove" work on directories when it appears to try?
5237 Oversight. It should be able to delete an empty directory, but you
5238 still don't have a way to remember when it was there and when it
5239 disappeared to allow the "-D " option to work.
5241 You'll have to remove the working directory and the matching directory
5244 Note that you want to do a _cvs remove dir_ in the working directory,
5245 do a cvs commit, and then do a _rmdir dir_ in the Repository.
5246 (msusrtsp.mark at eds dot com)
5248 Last modified: _12/18/1997_
5250 3. I don't like removing files. Is there another way to ignore them?
5252 There's no reason to be hasty in using the "remove" command.
5254 If there is a way to ignore files in your build procedures, I'd just
5255 do that. Later, when you decide that the files are really ancient, you
5256 can execute a "remove" command to clean up.
5258 The CVS "ignore" concept can't ignore files already in CVS.
5260 Last modified: _6/13/1997_
5262 4. I just removed a file. How do I resurrect it?
5264 If you executed "remove", but haven't typed "commit" (you can tell
5265 this by the 'R' notation that "update" prints next to the file), you
5266 can execute "add" to reverse the "remove".
5268 If you followed the "remove" with a "commit", you'll have to move it
5269 back out of the Attic by hand:
5271 I use something like this: (csh-like syntax)
5273 set repos = `cat ./CVS/Repository`
5274 mv $repos/Attic/filename,v $repos/filename,v
5276 (If you use relative paths in your Repository files, that first line
5277 becomes: set repos = $CVSROOT/`cat ./CVS/Repository`)
5279 While a file is in the Attic, you can't "add" another file by the same
5280 name. To add such a file you either have to move it by hand as in the
5281 above, or delete it from the Attic.
5283 The main reason for the Attic is to retain files with tags in them. If
5284 you execute: "update -r <oldtag>", files with <oldtag> attached to
5285 some revision will be taken from the normal Repository area and from
5286 the Attic. That's why you can't "add" a file with the same name.
5287 "remove" only moves a file off the main branch, it doesn't obliterate
5290 Last modified: _6/13/1997_
5292 5. Why doesn't "remove" delete the file? Instead, it prints an error
5293 message and tells me to remove the file by hand.
5295 Design choice. Unix software written within last decade, usually
5296 requires an extra verification step, such as answering a question or
5297 adding a flag on the command line. CVS currently requires that you
5298 delete the file first unless you specify the '-f' (force) option,
5299 which deletes the file before performing "cvs remove".
5301 Last modified: _6/13/1997_
5303 Category: /Commands_/rtag_rt_rfreeze/
5305 " + "rtag", "rt", "rfreeze""
5307 1. What is "rtag" for?
5309 To add a symbolic label (a "tag") to the last committed revisions of a
5310 module directly in the Repository.
5312 Last modified: _6/13/1997_
5314 2. Why use "rtag"? It assumes no one is changing the Repository.
5316 Though the "tag" command is more useful in marking the revisions you
5317 have in a particular working directory, "rtag" is much handier for
5318 whole-Repository actions, which occur at major release boundaries.
5320 Last modified: _6/13/1997_
5322 3. What revision does "rtag -r <tag1> <tag2>" actually put the tag on?
5324 In short, the '-r' option is another way to select the revision to
5325 tag. The revision is selected the same way for all commands that
5326 accept a "-r <tag/rev>" option.
5328 Depending on whether <tag1> is a <branch_tag>, or a non-branch <tag>
5329 and on whether you use the '-b' option to "rtag", you get four
5332 rtag -r <tag1> <tag2>
5334 Adds the non-branch tag <tag2> to the same revision that the
5335 non-branch tag <tag1> is attached to.
5340 <file> --> Symbols: TT1:1.4
5341 After --> Symbols: TT1:1.4,TT2:1.4
5343 rtag -r <branch_tag1> <tag2>
5345 Adds the non-branch tag <tag2> to the HEAD of (the highest revision
5346 number on) the branch labelled with tag <branch_tag1>.
5349 <branch_tag1> --> BR1
5351 <file> --> Symbols: BR1:1.2.0.2 (1.2.2.5 is HEAD)
5352 After --> Symbols: BR1:1.2.0.2,TT2:1.2.2.5
5354 If the branch tagged by <branch_tag1> has not been created, then the
5355 tag shows up on the branch point revision:
5358 <branch_tag1> --> BR1
5360 <file> --> Symbols: BR1:1.2.0.2 (No 1.2.X exists.)
5361 After --> Symbols: BR1:1.2.0.2,TT2:1.2
5363 rtag -b -r <tag1> <branch_tag2>
5365 Adds the magic branch tag <branch_tag2> to the revision that the
5366 non-branch tag <tag1> is attached to, preparing it to be a branch
5371 <branch_tag2> --> BR2
5372 <file> --> Symbol: TT1:1.4
5373 After --> Symbol: TT1:1.4, BR2:1.4.0.2
5375 rtag -b -r <branch_tag1> <branch_tag2>
5377 Adds the magic branch tag <branch_tag2> to the revision at the HEAD of
5378 (the highest revision number on) the branch labelled with
5379 <branch_tag1>, preparing it to be a branch point.
5382 <branch_tag1> --> BR1
5383 <branch_tag2> --> BR2
5384 <file> --> Symbol: BR1:1.2.0.2 (1.2.2.5 is HEAD)
5385 After --> Symbol: BR1:1.2.0.2,BR2:1.2.2.5.0.2
5387 If the branch tagged by <branch_tag1> has not been created, then the
5388 tag shows up as a second branch off the same branch point revision:
5391 <branch_tag1> --> BR1
5393 <file> --> Symbols: BR1:1.2.0.2 (No 1.2.X exists.)
5394 After --> Symbols: BR1:1.2.0.2,TT2:1.2.0.4
5396 In all four cases above, if <tag2> already exists on the file, you get
5397 an error unless you specify the '-F' option.
5399 In all four cases, if <tag1> does not exist on the file, <tag2> is not
5400 added unless you specify the '-f' option.
5402 Last modified: _6/13/1997_
5404 4. What happens if the tags are the same in "rtag -r <tag> <tag>"?
5406 Again, there are four cases depending on whether <tag> is a branch
5407 tag, or a non-branch tag and on whether you use the '-b' option to
5412 Is a no-op. It does nothing even with '-F' specified.
5414 If you add the '-f' option ("rtag -f -r <tag> <tag>"), then <tag> is
5415 attached to the latest revision on the Main Branch if the file does
5416 *not* already have <tag> on some revision.
5418 If the <tag> is already on the file, using "rtag -f" is still a no-op.
5420 rtag -r <branch_tag> <branch_tag>
5422 Produces an error, since the <branch_tag> is already on some revision
5425 But, "rtag -F -r <branch_tag> <branch_tag>" turns the magic branch tag
5426 into a non-branch tag.
5428 Symbols: BR1:1.4.0.2 becomes Symbols: BR1:1.4
5430 rtag -b -r <tag> <tag>
5432 Produces an error, since the <tag> is already on the file.
5434 But, "rtag -F -b -r <tag> <tag>" turns the non-branch tag into a magic
5437 Symbols: BR1:1.4 becomes Symbols: BR1:1.4.0.2
5439 rtag -b -r <branch_tag> <branch_tag>
5441 Produces an error, since the <branch_tag> is already on the file.
5443 But, "rtag -F -b -r <branch_tag> <branch_tag>" increments the branch
5444 number. It essentially removes the branch and creates a new one by the
5447 Symbols: BR1:1.2.0.4 becomes Symbols: BR1:1.2.0.6
5449 Last modified: _6/13/1997_
5451 5. Why doesn't "rtag -b -r <branch_tag1> <branch_tag2>" rename or duplicate
5454 None of the "tag" or "rtag" options rename anything. They only apply
5455 (or, with the '-F' option, move) tags to specific revisions in the
5458 See 3M.[3-4] above for details of how it works.
5460 To rename a non-branch tag, see 3O.9. To rename a magic branch tag,
5463 Last modified: _6/13/1997_
5465 Category: /Commands_/status_st_stat/
5467 " + "status", "st", "stat""
5469 1. What is "status" for?
5471 To display the status of files, including the revision and branch you
5472 are working on and the existence of "sticky" information.
5474 Last modified: _6/13/1997_
5476 2. Why does "status" limit the File: at the top to 17 characters?
5478 Designed that way to line up with other data. You can find the whole
5479 filename in the line beginning with "RCS version:", which is not
5482 Last modified: _6/13/1997_
5484 3. Why does it print "Sticky" lines when the values are "(none)"?
5486 Oversight. It should probably elide lines without information.
5488 Last modified: _6/13/1997_
5490 4. Shouldn't the status "Needs Checkout" be "Needs Update"?
5494 [[Did this show up in CVS 1.4?]]
5496 Last modified: _6/13/1997_
5498 Category: /Commands_/tag_ta_freeze/
5500 " + "tag", "ta", "freeze""
5502 1. What is "tag" for?
5504 To add a symbolic label (a "tag") to the RCS files last checked out,
5505 updated or committed in a working directory.
5507 Last modified: _6/13/1997_
5509 2. What is the difference between "tag" and "rtag"?
5511 The end result of both commands is that a <tag>, or symbolic name, is
5512 attached to a single revision in each of a collection of files.
5514 The differences lie in:
5516 The collection of files they work on.
5518 "rtag" works on the collection of files referred to by a "module" name
5519 as defined in the "modules" file, or a relative path within the
5522 "tag" works on files and directories specified on the command line
5523 within the user's working directory. (Default is '.')
5525 Both commands recursively follow directory hierarchies within the
5526 named files and directories.
5528 The revisions they choose to tag.
5530 "rtag" places a tag on the latest committed revision of each file on
5531 the branch specified by the '-r' option. By default it tags the Main
5534 "tag" places a tag on the BASE (i.e. last checked out, updated or
5535 committed) revision of each file found in the working directory. (The
5536 BASE revision of a file is the one stored in the ./CVS/Entries file.)
5538 A different set of command line options.
5540 For example, "rtag" takes a "-r <oldtag>" option to retag an existing
5541 tag. The "tag" command does not.
5545 Currently "rtag" records the <tag> and the module in the "history"
5546 file, while "tag" does not.
5548 Last modified: _6/13/1997_
5550 3. Why does "tag -b" not put a tag on the Branch Point revision? How do I
5551 refer to the Branch Point?
5553 This is probably an oversight, or a disbelief in the need for it. If
5554 everything works perfectly, the "update -j" command will do the merge
5555 you need and you don't need to check up on it by playing with the
5556 branch point revision.
5558 The '-b' option attaches a magic branch tag to allow CVS later to
5559 figure out the branch point. The actual revision that <tag> is
5560 attached to does not exist. References to the branch tag are
5561 equivalent to references to the latest revision on the branch.
5563 There is no way to refer to the branch point without adding a
5564 non-branch tag. You might want to add non-branch tags as a habit and
5565 add branch tags later, possibly immediate after adding the non-branch
5566 tag. See 4C.3 on Creating a Branch.
5568 Last modified: _6/13/1997_
5570 4. So "{r}tag" labels a bunch of files. What do you use a Tag for?
5572 You use it to "checkout" the labeled collection of files as a single
5573 object, referring to it by name.
5575 Anywhere a revision number can be used a Tag can be used. In fact tags
5576 are more useful because they draw a line through a collection of
5577 files, marking a development milestone.
5579 The way to think about a Tag is as a curve drawn through a matrix of
5580 filename vs. revision number. Consider this:
5582 Say we have 5 files (in some arbitrary modules, some may be in 2 or
5583 more modules by name, some may be in 2 or more modules because of the
5584 Repository tree structure) with the following revisions:
5586 file1 file2 file3 file4 file5
5588 1.1 1.1 1.1 1.1 /--1.1* <-*- <tag>
5589 1.2*- 1.2 1.2 -1.2*-
5590 1.3 \- 1.3*- 1.3 / 1.3
5595 At some time in the past, the '*' versions were tagged. Think of the
5596 <tag> as a handle attached to the curve drawn through the tagged
5597 revisions. When you pull on the handle, you get all the tagged
5598 revisions. Another way to look at it is that you draw a straight line
5599 through the set of revisions you care about and shuffle the other
5600 revisions accordingly. Like this:
5602 file1 file2 file3 file4 file5
5608 1.2*----1.3*----1.5*----1.2*----1.1 (--- <-- Look here
5613 I find that using these visual aids, it is much easier to understand
5614 what a <tag> is and what it is useful for.
5616 Last modified: _6/13/1997_
5618 5. How do I get "tag" and "rtag" to send mail the way "commit" does?
5620 The "commit" command is supported by two files ("commitinfo" and
5621 "loginfo") not used by other commands. To do logging the same way for
5622 "tag" and "rtag" would require another file like loginfo, which
5623 currently doesn't exist.
5625 The "rtag" command requires a "module" entry, which can specify a
5626 "tag" program using the "-t programname" option on the module line.
5628 There is no equivalent support for "tag".
5630 Last modified: _6/13/1997_
5632 6. Why can't "tag" handle the '-r' option that "rtag" takes?
5634 Oversight. The answer is probably "Fixed in a Future Release."
5636 Last modified: _6/13/1997_
5638 7. After a "tag <tag>" in my working directory, why doesn't "checkout -r
5639 <tag>" somewhere else produce copies of my current files?
5641 The only reason this would fail, other than misspelling the <tag>
5642 string, is that you didn't "commit" your work before "tagging" it.
5643 Only committed revisions may be tagged. Modified files are not marked
5646 Last modified: _6/13/1997_
5648 8. Why doesn't "tag" write a history record the way "rtag" does?
5650 The "rtag" command was originally intended to place major "release"
5651 tags onto modules. The "tag" functionality was developed to *move* the
5652 more significant tag when slight changes to individual files sneaked
5653 in after the release tag was stamped onto the Repository.
5655 The significant event was the "rtag", which was recorded in the
5656 "history" file for the "history -T" option to work.
5658 It turns out that "tag" is generally more useful than "rtag", so the
5659 model has changed. Future revisions of CVS will probably store both
5660 kinds of tags in the history file.
5662 Last modified: _6/13/1997_
5664 9. How do I rename a <tag>?
5666 For a procedure to rename a branch tag, See section 4D.5 The following
5667 covers only non-branch tags.
5669 First, pick a <newtag> that is not in use. You could reuse (i.e. move)
5670 an existing tag to the new revisions using the '-F' option, but that
5671 will confuse matters when both tags are not already on a file. (It
5672 will probably confuse "rtag -f" too.)
5674 Use "rtag" to place <newtag> only on revisions attached to <oldtag> in
5675 the whole Repository, then delete the old one.
5677 cvs rtag -r <oldtag> <newtag> world
5678 cvs rtag -d <oldtag> world.
5680 You can also checkout or update your working directory to the <oldtag>
5681 and "tag" rather than "rtag" the result. But that will take longer and
5682 it has the chance of producing conflicts.
5684 cvs update -r <oldtag>
5687 cvs update -A (or cvs update -r <previous_tag>)
5689 Last modified: _6/13/1997_
5691 Category: /Commands_/update_up_upd/
5693 " + "update", "up", "upd""
5695 1. What is "update" for?
5697 The "update" command is by far the most important command and is
5698 probably also the most used command.
5700 It has five purposes: (And many options.)
5702 To display the status of your working files.
5704 Though a plain "update" also displays the status, it does so after
5705 possibly altering your working directory. To see the status of your
5706 working files without changing anything, type:
5708 cvs -n update {optional list of files}
5710 To merge changes made by others to the branch you are working on
5711 into your working files.
5713 Each working directory is attached to a branch, usually the Main
5714 branch. To merge changes made on your working branch since your last
5715 checkout, update or commit, type:
5717 cvs update {optional list of files}
5719 To merge changes made on another branch into the branch you are
5720 working on (your "working branch").
5722 If you want to grab a whole branch, from the branch point, which is
5723 assumed to be on the Main Branch, to the end of the branch, you type:
5725 cvs update -j <branch_tag> {optional files}
5727 If you want to grab the changes made between two tags or revisions,
5730 cvs update -j <tag1> -j <tag2> {optional files}
5732 (If you are working with a single file, the Tags could also be
5733 revisions numbers. Unless you take great care to match revision
5734 numbers across different files (a waste of time given the way Tags
5735 work), using revision numbers in place of the Tags for multiple files
5736 would be meaningless.)
5738 To move your working directory to another branch.
5740 A working directory is presumed to be attached to (or working on) a
5741 particular branch, usually the Main branch. To alter what CVS believes
5742 to be your working branch, you "move" to that branch.
5744 To move to a tagged branch, type:
5746 cvs update -r <branch_tag> {optional files}
5748 To move to the Main Branch, type:
5750 cvs update -A {optional files}
5752 If you have modified files in your working directory, this is not a
5753 clean move. CVS will attempt to merge the changes necessary to make it
5754 look like you made the same changes to the new branch as you made in
5755 the old one. But if you do this twice without resolving the merge
5756 conflicts each time, you can lose work.
5758 To retrieve old revisions of files.
5760 This option is similar to 4 above but you are not restricted to using
5761 a <branch_tag>. You may specify any revision or <tag> with '-r' and
5762 get the specified revision or the tagged revision:
5764 cvs update -r <tag/rev> {optional files}
5766 Or you may specify any date with '-D':
5768 cvs update -D <date> {optional files}
5770 The '-p' option sends the revisions to standard output (normally your
5771 terminal) rather than setting the "sticky" tag and changing the files.
5773 Last modified: _6/13/1997_
5775 2. What do 'U', 'M' and 'C' mean when I type "update"? Are they different
5776 for "cvs -n update"?
5778 "cvs update" merges changes made to the Repository, since your last
5779 "checkout", "update" or "commit", into your working files. You can
5780 think of it as changing your BASE revision.
5782 "cvs update" prints lines beginning with:
5784 'U' after replacing your unmodified file with a different
5785 revision from the Repository.
5787 'M' for two different reasons:
5789 for files you have modified that have not changed in the Repository.
5791 after a merge, if it detected no conflicts.
5793 'C' after a merge, if it detected conflicts. See 2D.7 and 3P.6 for
5794 more info on conflict resolution and "sticky conflicts."
5796 "cvs -n update" shows what it *would* do, rather than doing it. Or,
5797 another way of looking at it, "cvs -n update" displays the
5798 relationship between your current BASE revisions (identified in your
5799 ./CVS/Entries file) and the HEAD revisions (the latest revisions in
5802 "cvs -n update" prints lines beginning with:
5804 'U' for files you have not modified that have changed in the
5807 'M' for files you have modified that have not changed in the
5810 'C' for files you have modified that have also been changed in the
5813 See 4C.6 for what the letters mean when merging in from another
5814 branch. The output is almost the same for a normal update if you
5815 consider the Repository as the branch and your working directory as
5818 Last modified: _6/13/1997_
5820 3. What's the difference between "update" and "checkout"?
5824 Last modified: _6/13/1997_
5826 4. Why don't I get new files when I execute "update"?
5828 There are six reasons for nothing to happen during an "update":
5830 Nothing on your branch changed in the Repository.
5832 If no one has committed anything to the branch you are working on
5833 (normally the Main branch) since the last time you executed
5834 "checkout", "update" or "commit", nothing will happen.
5836 It's like shouting "xyzzy" or "plugh" in the wrong room.
5838 You have a "sticky" non-branch <tag> or <date> attached to the
5839 working files you are trying to "update".
5841 At some time in the past you checked out or updated your directory
5842 with the "-r <tag>" or "-D <date>" option. Until you do it again with
5843 a different tag or date, or go back to the Main Branch with "update
5844 -A", you will never again see any updates.
5846 The ./CVS/Entries.Static file exists and you are expecting a new
5849 If your ./CVS administrative directory contains a file named
5850 Entries.Static, no files will be checked out that aren't already in
5851 the Entries or Entries.Static file.
5853 You forgot to use the '-d' option and are looking for new
5856 If you execute "update" without the '-d' option, it will not create
5857 new directories that have been added to the Repository.
5859 You typed "update" instead of "cvs update".
5861 On most Unix systems, your disk caches are now furiously being flushed
5862 by multiple update daemons, destroying performance and proving to
5863 management that you need more CPU power. :-)
5865 On HP systems you might be asked what package you want to install from
5866 the "update server".
5868 Someone removed (using "admin -o") your BASE revision (the revision
5869 CVS thought you had in your working directory), then committed a
5870 "replacement". CVS is now confused because the revision in the
5871 Repository matches your BASE revision when the files themselves don't
5874 Last modified: _6/13/1997_
5876 5. Why does "update" say 'M' both for plain modified files and for
5877 successful (i.e. conflict-free) merges? Aren't they different?
5879 A design choice. Yes, they are different internally, but that
5880 shouldn't matter. Your files are in the same condition after the
5881 "update" as they were before -- a "diff" will display only your
5882 modifications. And you are expected to continue onward with parts two
5883 and three of the normal development cycle: "emacs" (a synonym for
5884 "edit" in most of the civilized world) and "commit".
5886 Last modified: _6/13/1997_
5888 6. What's a "sticky conflict"? How does it know a conflict occurred?
5890 When a "cvs update" (or an "update -j") creates a conflict, it prints
5891 a 'C' and stores the timestamp of the file after the merge in a
5892 special field in the ./CVS/Entries file.
5894 This conflict indication implies that the merge command altered your
5895 working file to contain conflict markers surrounding the overlapping
5896 code segments. For example, say that
5898 - Two developers acquire revision 1.2 of <file> via "checkout" or
5901 - Developer A changes line 1 from "9999" to "5555", then commits the
5902 file, creating revision 1.3.
5904 - Developer B changes line 1 from "9999" to "7777", then tries to
5905 commit the file, but is blocked because the file is not up to date.
5906 Developer B then runs "update" and sees the conflict marker 'C'. The
5907 beginning of the file would look like this:
5909 <<<<<<< <file> The working <file> in question.
5910 7777 Change made to the working <file>.
5912 5555 Change made in the first commit (1.3)
5913 >>>>>>> 1.3 The revision created by the first commit.
5915 The conflict is "sticky", which means that until the conflict is
5916 cleared, the "update" command will continue to display the file's
5917 status as 'C' and the "status" command will show the file's status as
5918 "Unresolved Conflict".
5920 Until the conflict is cleared, "commit" is blocked for this file.
5922 The sticky conflict indicator can be cleared by:
5924 Resolving the conflict by editing the file. Two things must happen
5925 before the conflict is considered resolved:
5927 The timestamp of the file must change. *and* The file must contain no
5928 conflict markers. (The string searched for in the file is the regexp:
5931 After clearing the sticky conflict indicator, you may then commit the
5934 Removing the file and running "update". This throws away the local
5935 changes and accepts the latest committed file on this branch. No
5938 Forcing the commit to happen by using "commit -f". This is probably
5939 a mistake since there are few lines of real text that begin with
5942 Last modified: _6/13/1997_
5944 7. Is there a feature to tell me what I have changed, added and removed
5945 without changing anything?
5947 The command "cvs -n update" will do exactly that.
5949 Last modified: _6/13/1997_
5951 8. Why were all my files deleted when I executed "update"?
5953 You probably executed "update -r <tag>" some time ago, then removed
5954 <tag> from the Repository files. "update -r <tag>" will delete a file
5955 that doesn't contain <tag>.
5957 A way to fix this is to "cd" into your working directory and type:
5961 If you don't want the latest revisions on the Main (or Vendor) Branch,
5962 then decide what Tag (normal or branch) you want and type:
5964 cvs update -r <the_tag_you_want>
5966 Another way to make a file disappear is to execute "update -D <date>"
5967 where <date> is before the date stamped onto the first revision in the
5970 Last modified: _6/13/1997_
5972 Category: /Past__Future_/
5976 Category: /Past__Future_/Bugs_and_Patches/
5978 " + Bugs and Patches"
5980 1. Why can't CVS handle deletion of directories?
5982 An oversight, probably. [[Fixed in a future release?]]
5984 Last modified: _6/13/1997_
5986 2. Why can't CVS handle the moving of sources from one place in the
5988 directory hierarchy to another?
5990 A "renaming database" has been proposed to track the history of
5991 pathname changes in the Repository. A general solution is a difficult
5994 Last modified: _6/13/1997_
5996 3. When I typed "cvs update -D <date>", why did it check out all
5998 sorts of ancient files from the Attic? Shouldn't it just create the
5999 set of files and revisions that existed at that date?
6001 This seems to be a bug, but is really the lack of any obvious place to
6002 store the date when a file is "removed".
6004 There are four ranges of dates that CVS has to deal with when trying
6005 to determine what revision was available on <date>:
6007 Dates before the earliest revision in the file.
6009 Dates between any two revisions in the file.
6011 Dates between the latest revision in the file and the date when the
6012 file was moved to the Attic by "commit".
6014 Dates after moving the file to the Attic.
6016 Since the date when a file is moved to the Attic is not stored
6017 anywhere, CVS can't tell the difference between #3 and #4. To avoid
6018 not producing a file that should exist in case #3, it produces
6019 extraneous files in case #4.
6021 For the above reason, if you have removed files in the Attic, it is
6022 better to use "-r <tag>, or even "-r HEAD" than to use a date spec.
6024 If you must use "-D <date>", then you should either archive and delete
6025 Attic files (losing some past history) or construct your Makefiles to
6026 work with an explicit list of files and let the old source files stay
6027 in the working directory. The contents of the revision-controlled
6028 Makefile can then be considered to contain deletion "information".
6030 Last modified: _6/13/1997_
6032 4. When I typed "cvs update -D <date>" in my branch, why did it screw up
6035 Currently, the internal routine ("version_ts") that looks up info
6036 about a file, overrides both the tag and date if *either* the tag or
6037 date is specified on the command line. If only the date is specified,
6038 it should not override a branch tag, but it does.
6040 In CVS 1.3, the documented "-D <branch_tag>:<date>" syntax only works
6041 with the Main Branch and the Vendor Branch.
6043 [[Is this fixed in CVS 1.4? This is one item I didn't check.]]
6045 Last modified: _6/13/1997_
6047 5. When I executed "checkout" into an existing directory I got "No such
6048 file or directory" errors. Why?
6050 Though the man page says that "checkout" turns into an "update -d" in
6051 directories that already exist, it is referring to directories that
6052 already exist *and* were created by CVS.
6054 When you try to run "checkout" on top of an existing directory
6055 structure, some of which wasn't created by CVS, it will handle
6056 directories and non-CVS files within directories already under CVS,
6057 but it will display the above error on non-CVS files within non-CVS
6060 Last modified: _6/13/1997_
6062 6. Why does "update" send all output to the terminal after 26 files have
6065 CVS uses the "tmpnam()" function to generate temporary file names. The
6066 ANSI standard for the "tmpnam()" function says:
6068 "The tmpnam function generates a different string each time it is
6069 called, up to TMP_MAX times. If it is called more than TMP_MAX times,
6070 the behavior is implementation defined."
6072 Later it says that the value of "TMP_MAX shall be at least 25."
6074 On some platforms, the above specification is taken literally by
6075 turning "at least 25" into "exactly 26" and by doing something foolish
6076 (i.e. "implementation defined") after that. Some systems return the
6077 same name repeatedly, which causes one form of trouble. Others return
6078 NULL or garbage, which causes a different form of trouble.
6080 The broken systems appear to be cycling a single character through the
6081 alphabet. SunOS cycles 3 characters through the alphabet, so it won't
6082 cause trouble until 26 cubed or 17576 calls to "tmpnam()".
6084 Since CVS doesn't depend on the exact format of the tmp files, the
6085 workaround is to provide a "tmpnam()" that doesn't have a limit on the
6086 number of calls to it.
6088 Last modified: _6/13/1997_
6090 7. Why does the merge occasionally resurrect lines of code?
6092 The diff3 program provided by GNU diff version 1.15 has a bug that
6093 occasionally causes text to come back from the dead.
6095 This is an old problem which you can avoid by upgrading to the latest
6096 GNU "diffutils" package. If you were using GNU diff version 1.15 and
6097 plan to upgrade to the latest GNU diff program, see the next question.
6099 Last modified: _6/13/1997_
6101 8. Why does the merge fail when my "rcsmerge" program is configured to use
6102 GNU diff version 2.1 or later?
6104 A change in the overlap format was introduced in GNU diff3 between
6105 versions 2.0 and 2.1 that causes RCS versions before 5.6.0.1 to fail
6108 To get consistent rcsmerge behavior, you have four choices:
6110 Go back to using GNU diff 1.15 or 2.0 with RCS versions 5.5 or 5.6.
6111 If you want to use GNU diff 2.1 or later, you'll have to pick one of
6112 the other three choices in this list.
6114 Grab RCS version 5.6.0.1 from an FSF archive and set the DIFF3_A
6115 macro to '1' as it tells you to in the Makefile:
6119 Patch the RCS 5.6 source. Change line 84 in "merger.c" from:
6121 DIFF3, "-am", "-L", label[0], "-L", label[1], to DIFF3, "-amE", "-L",
6122 label[0], "-L", "", "-L", label[1],
6124 Wait both for RCS version 5.7 to be released and for a new version
6125 of CVS that can deal with it.
6127 Last modified: _6/13/1997_
6129 Category: /Past__Future_/Contributors/
6135 Brian Berliner <berliner@sun.com> converted a collection of scripts
6136 written by Dick Grune <dick@cs.vu.nl> into a C program, then added all
6137 sorts of features. He continues to maintain CVS.
6139 Jeff Polk <polk@bsdi.com> wrote much of the code added between
6140 revisions 1.2 and 1.3. Many others were involved at some level.
6142 david d zuhn <zoo@armadillo.com> fixed a number of bugs, added some of
6143 the new features, reworked the whole thing to be more portable, and
6144 provided much of the energy to push CVS 1.4 out the door.
6146 Jim Kingdon implemented CVS 1.5's remote repository access features,
6147 fixed many bugs, and managed the release of version 1.5.
6149 Take a look at the README and the ChangeLog files in the CVS sources
6150 for more contributors.
6152 Last modified: _6/13/1997_
6154 2. You didn't write all of this FAQ, did you?
6156 In the original hunt for questions to answer (performed in Jan/Feb,
6157 1993), I polled hundreds of people and I rephrased all sorts of text
6158 found on the net. Between 2/93 and 10/93, I released about 20
6159 versions, with corrections and additions from the info-cvs mailing
6160 list and private correspondence.
6162 Between 10/93 and 10/94 I extracted frequently asked questions from
6163 the 1200 mail messages to the info-cvs mailing list, turned them into
6164 focused questions and tried to answer them.
6166 93/02/?? ~4000 lines 93/06/?? ~5000 lines 93/10/23 7839 lines 278K
6167 94/10/29 9856 lines 360K 95/05/09 9981 lines 365K
6169 Because there are so many posers of questions, I will list only those
6170 who contribute answers or help significantly with the content and
6171 structure of this document.
6173 If I used someone else's text verbatim, I mentioned it in the given
6174 answer. The people whose email postings have added to this document or
6175 who have added to my understanding are:
6177 Brian Berliner <berliner@sun.com>, CVS maintainer. Paul Eggert
6178 <eggert@twinsun.com>, RCS maintainer.
6180 Gray Watson <gray@antaire.com> Per Cederqvist <ceder@signum.se> Pete
6181 Clark <pclark@is.com>
6183 all of whom have sent me copies of their tutorials and local CVS
6186 Additional contributors, who have sent me ideas, text, corrections and
6187 support include (in alphabetical order):
6189 Per Abrahamsen <amanda@iesd.auc.dk> Donald Amby
6190 <amby@mixcom.mixcom.com> Mark D Baushke <mdb@cisco.com> Jim Blandy
6191 <jimb@cyclic.com> Tom Cunningham <tomc@bouwsma,sps.mot.com> Graydon
6192 Dodson <grdodson@lexmark.com> Joe Drumgoole
6193 <joed@splatter.demon.co.uk> Don Dwiggins <dwig@markv.com> Bryant
6194 Eastham <bryant@ced.utah.edu> Dan Franklin <dan@diamond.bbn.com>
6195 Michael Ganzberger <ganzbergermd@ES.net> Steve Harris
6196 <vsh%etnibsd@uunet.uu.net> Erik van Linstee
6197 <linstee@dutecaj.et.tudelft.nl> Jeffrey M Loomis <jml@world.std.com>
6198 Barry Margolin <barmar@near.net> Mark K. Mellis <mkm@ncd.com> Chris
6199 Moore <Chris.Moore@src.bae.co.uk> Gary Oberbrunner <garyo@avs.com>
6200 Steve Turner <stevet@carrier.sps.mot.com> Dave Wolfe
6201 <dwolfe@pffft.sps.mot.com> Dale Woolridge <dwoolridge@cid.aes.doe.ca>
6203 Please send corrections. If I forgot you, remind me and I'll add your
6206 Last modified: _6/13/1997_
6208 Category: /Past__Future_/Development/
6212 1. Where do I send bug reports?
6214 First make sure it is a bug. Talk to your friends, coworkers and
6215 anyone you know who uses CVS. Search this FAQ for related issues. Then
6216 test it carefully. Try out variations to narrow down the problem. Make
6217 sure it is repeatable. Look for workarounds so you can report them.
6219 If you are still sure it's a bug and you tried to fix it, skip to the
6220 next question. Otherwise, send a message to the info-cvs mailing list
6221 containing one of the following:
6223 If you have a good repeatable case and you think you know what is
6224 going on, then describe the problem in detail. Include a workaround if
6227 If you have no idea what is going on, go ahead and send a question
6228 to the info-cvs mailing list. Include any information you have
6229 describing the symptoms.
6231 Last modified: _6/13/1997_
6233 2. Where do I send fixes and patches?
6235 First make sure the "fix" does something useful. Have someone review
6236 your fix. Spend a bit of one person's time in a detailed analysis of
6237 your vast idea before displaying a half-vast idea to hundreds of
6240 If you tried to fix it and the patch is small, include the patch in
6241 your message. Make sure the patch is based on the latest released
6244 If you tried to fix it and the patch is large, you should think about
6245 why it is so large. Did you add a generally useful feature, or did it
6248 If you still believe it is solid, produce a patch file using the CVS
6249 commands "patch" or "diff -c". [[You *are* keeping CVS under CVS,
6250 right?]] The patch should be based on the latest released version of
6251 CVS. Then use the "cvsbug" program (provided with the CVS sources) to
6252 send it to the CVS maintainers. A self-contained patch that provides a
6253 single useful feature or correction might show up independently in the
6254 patches directory of the FTP archive.
6256 If careful testing reveals an RCS bug rather than a CVS bug, you can
6257 send bug reports to: rcs-bugs@cs.purdue.edu
6259 Last modified: _6/13/1997_
6261 3. Where do I send ideas for future development?
6263 If you have a bright idea, discuss it on the info-cvs mailing list. If
6264 you have the time to implement something you can test, send the diffs
6265 along too as described above.
6267 Last modified: _6/13/1997_
6269 4. What plans are there for new features?
6273 A "rename" or "per-directory" database has been bandied about on
6274 the net for years. Many of the goals of the rename database have
6275 been achieved by the so-called "death support" in recent versions of
6276 CVS (such as 1.9). For more information on what may remain to be
6277 done, see item #189 in the TODO file of a development version of CVS.
6279 CVS version 1.5 supports remote repository access, but Paul
6280 Kunz has produced another version
6281 (rCVS) that also runs remotely. Note that as far as I know there
6282 are no advantages to rCVS over the remote CVS in CVS 1.5 and later,
6283 and the rCVS user community has migrated to remote CVS.
6284 rCVS is *not* a multisite CVS (see item #186 in TODO for more on
6285 multisite). For more on rCVS, see
6287 ftp://ftp.slac.stanford.edu/software/rcvs
6291 Last modified: _9/6/1997_
6293 5. I have some time and I'd like to help. What can I do for you?
6296 You can review this document, correct errors and fill in any of
6297 the incomplete sections.
6299 You can write scripts or CVS add-ons and make them available by
6302 You could work on the regression test suite (src/sanity.sh in the
6303 CVS source distribution).
6305 You can write specs for new features, fix bugs, review the
6306 documentation or . . .
6308 For more information, see the files HACKING and DEVEL-CVS in the
6309 CVS source distribution or
6310 http://www.cyclic.com/cyclic-pages/cvsdev.html
6314 Last modified: _9/6/1997_
6316 Category: /Past__Future_/Professional_Support/
6318 " + Professional Support"
6320 1. Doesn't Cygnus support CVS?
6325 Cygnus is a company that supports free software such as the GCC
6326 compiler. They have never sold support for CVS, however. They
6327 do use CVS internally and have contributed much code to CVS over
6328 the years (for which CVS users should be grateful).
6332 Last modified: _9/6/1997_
6334 2. What is Cyclic Software doing with CVS?
6337 Cyclic Software exists to provide support for CVS. For details such
6338 as prices and what this covers, see http://www.cyclic.com or ask
6343 Last modified: _9/6/1997_
6345 Category: /User_Tasks_/
6349 Category: /User_Tasks_/Common_User_Tasks/
6351 " + Common User Tasks"
6353 1. What is the absolute minimum I have to do to edit a file?
6355 Tell your Repository Administrator to create a module covering the
6356 directory or files you care about. You will be told that your module
6357 name is <module>. Then type:
6359 cvs checkout <module>
6361 emacs <file> # Isn't Emacs a synonym for edit?
6364 If you don't use modules (in my opinion, a mistake), you can check out
6365 a directory by substituting its relative path within the Repository
6366 for <module> in the example above.
6368 To work on a single file, you'll have to change "cd <module>" to "cd
6369 `dirname <module>`".
6371 Last modified: _6/13/1997_
6373 2. If I edit multiple files, must I type "commit" for each one?
6375 No. You can commit a list of files and directories, including relative
6376 paths into multiple directories. You can also commit every modified
6377 file in the current directory or in all directories and subdirectories
6378 from your current directory downward. See 3D.2.
6380 Last modified: _6/13/1997_
6382 3. How do I get rid of the <module> directory that "checkout" created?
6384 Change your directory to be the same as when you executed the
6385 "checkout" command that created <module>.
6387 If you want to get rid of the CVS control information, but leave the
6388 files and directories, type:
6390 cvs release <module>
6392 If you want to obliterate the entire directory, type:
6394 cvs release -d <module>
6396 ("release -d" searches through the output of "cvs -n update" and
6397 refuses to continue if the "update" command finds any modified files
6398 or non-ignored foreign files. Foreign directories too.)
6400 If you don't care about keeping "history", or checking for modified
6401 and foreign files, you can just remove the whole directory. That's "rm
6402 -rf <module>" under Unix.
6404 Last modified: _6/13/1997_
6406 4. How do I find out what has changed since my last update?
6408 There are many ways to answer this.
6410 To find out what you've changed in your current working directory
6411 since your last checkout, update or commit, type:
6415 To find out what other people have added (to your branch) since you
6416 last checked out or updated, type:
6418 cvs diff -r BASE -r HEAD
6420 To look at a revision history containing the comments for all changes,
6421 you can use the "log" command.
6423 You can also use "history" to trace a wide variety of events.
6425 Last modified: _6/13/1997_
6427 5. I just created a new file. How do I add it to the Repository?
6429 The "update" command will mark files CVS doesn't know about in your
6430 working directory with a '?' indicator.
6434 To add <file> to the Repository, type:
6439 See 3A.[2-5] and 4C.8 for branch and merge considerations.
6441 Last modified: _6/13/1997_
6443 6. How do I merge changes made by others into my working directory?
6445 If you are asking about other branches, see Section 4C on "Branching".
6446 You will have to use the "update -j" command.
6448 Retrieving changes made to the Repository on the *same* branch you are
6449 working on is the main purpose of the "update" command. The "update"
6450 command tries to merge work committed to the Repository by others
6451 since you last executed "checkout", "update" or "commit" into your
6454 For a single file, there are six possible results when you type the
6457 If the file is lying in your working directory, but is not under
6458 CVS, it will do nothing but print:
6462 If neither you nor anyone else has committed changes to <file>,
6463 since your last "checkout", "update" or "commit", "update" will print
6464 nothing and do nothing.
6466 If you have made no changes to a working file, but you or others
6467 have committed changes to the Repository since your last "checkout",
6468 "update" or "commit" of this working file, CVS will remove your
6469 working file and replace it with a copy of the latest revision of that
6470 file in the Repository. It will print:
6474 You might want to examine the changes (using the CVS "diff" command)
6475 to see if they mesh with your own in related files.
6477 If you have made changes to a working file, but no one has changed
6478 your BASE revision (the revision you retrieved from the Repository in
6479 your last "checkout", "update" or "commit"), "update" will print:
6483 Nothing changes. You were told that you have a modified file in your
6486 If you have made changes to your working file and you or others have
6487 committed changes to the Repository, but in different sections of the
6488 file, CVS will merge the changes stored in the Repository since your
6489 last "checkout", "update" or "commit" into your working file. "update"
6492 RCS file: /Repository/module/<file> retrieving revision 1.X retrieving
6493 revision 1.Y Merging differences between 1.X and 1.Y into <file> M
6496 If you execute "diff" before and after this step, you should see the
6497 same output, since both the base file and your working file changed in
6498 parallel. This is one of the few times the otherwise nonsensical
6499 phrase "same difference" means something.
6501 If both you and those who committed files (since your last checkout,
6502 update or commit) have made changes to the same section of a file, CVS
6503 will merge the changes into your file as in #5 above, but it will
6504 leave conflict indicators in the file. "update" will print:
6506 RCS file: /Repository/module/<file> retrieving revision 1.X retrieving
6507 revision 1.Y Merging differences between 1.X and 1.Y into <file>
6508 rcsmerge warning: overlaps during merge
6509 cvs update: conflicts found in <file>
6512 This is a "conflict". The file will contain markers surrounding the
6513 overlapping text. The 'C' conflict indicator is sticky -- subsequent
6514 "update" commands will continue to show a 'C' until you edit the file.
6516 You must examine the overlaps with care and resolve the problem by
6517 analyzing how to retain the features of both changes. See 2D.7 and
6518 3P.6 for more details on conflict resolution.
6520 Last modified: _6/13/1997_
6522 7. How do I label a set of revisions so I can retrieve them later?
6524 To "tag" the BASE revisions (the ones you last checked out, updated,
6525 or committed) you should "cd" to the head of the working directory you
6526 want to tag and type:
6530 It recursively walks through your working directory tagging the BASE
6531 revisions of all files.
6533 To "tag" the latest revision on the Main branch in the Repository, you
6534 can use the following from anywhere: (No "cd" is required -- it works
6535 directly on the Repository.)
6537 cvs rtag <tag> <module>
6539 Last modified: _6/13/1997_
6541 8. How do I checkout an old release of a module, directory or file?
6543 Module names and directories are simply ways to name sets of files.
6544 Once the names are determined, there are 6 ways to specify which
6545 revision of a particular file to check out:
6547 By tag or symbolic name, via the "-r <tag>" option.
6549 By date, via the "-D <date>" option.
6551 By branch tag (a type of tag with a magic format), via the "-r
6552 <branch_tag>" option.
6554 By date within a branch, via the "-r <branch_tag>:<date>" option.
6556 By an explicit branch revision number ("-r <rev>"), which refers to
6557 the latest revision on the branch. This isn't really an "old"
6558 revision, from the branch's perspective, but from the user's
6559 perspective the whole branch might have been abandoned in the past.
6561 An explicit revision number: "-r <rev>" Though this works, it is
6562 almost useless for more than one file.
6566 cvs checkout <option-specified-above> <module>
6569 Last modified: _6/13/1997_
6571 9. What do I have to remember to do periodically?
6573 You should execute "cvs -n update" fairly often to keep track of what
6574 you and others have changed. It won't change anything -- it will just
6577 Unless you are purposely delaying the inclusion of others' work, you
6578 should execute "update" once in a while and resolve the conflicts. It
6579 is not good to get too far out of sync with the rest of the developers
6580 working on your branch.
6582 It is assumed that your system administrators have arranged for editor
6583 backup and Unix temp files (#* and .#*) to be deleted after a few
6584 weeks. But you might want to look around for anything else that is
6585 ignored or hidden. Try "cvs -n update -I !" to see all the ignored
6588 If you are the Repository Administrator, see 4B.16 on Administrator
6591 Last modified: _6/13/1997_
6593 Category: /User_Tasks_/General_Questions/
6595 " + General Questions"
6597 1. How do I see what CVS is trying to do?
6599 The '-t' option on the main "cvs" command will display every external
6600 command (mostly RCS commands and file deletions) it executes. When
6601 combined with the '-n' option, which prevents the execution of any
6602 command that might modify a file, you can see what it will do before
6603 you let it fly. The '-t' option will *not* display every internal
6604 action, only calls to external programs.
6606 To see a harmless example, try typing:
6610 Some systems offer a "trace" or "truss" command that will display all
6611 system calls as they happen. This is a *very* low-level interface that
6612 does not normally follow the execution of external commands, but it
6615 The most complete answer is to read the source, compile it with the
6616 '-g' option and step through it under a debugger.
6618 Last modified: _6/13/1997_
6620 2. If I work with multiple modules, should I check them all out and commit
6621 them occasionally? Is it OK to leave modules checked out?
6623 The simple answers are "Yes."
6625 There is no reason to remove working directories, other than to save
6626 disk space. As long as you have committed the files you choose to make
6627 public, your working directory is just like any other directory.
6629 CVS doesn't care whether you leave modules checked out or not. The
6630 advantage of leaving them checked out is that you can quickly visit
6631 them to make and commit changes.
6633 Last modified: _6/13/1997_
6635 3. What is a "sticky" tag? What makes it sticky? How do I loosen it?
6637 When you execute "update -r <tag>", CVS remembers the <tag>. It has
6638 become "sticky" in the sense that until you change it or remove it,
6639 the tag is remembered and used in references to the file as if you had
6640 typed "-r <tag>" on the command line.
6642 It is most useful for a <branch_tag>, which is a sticky tag indicating
6643 what branch you are working on.
6645 A revision number ("-r <rev-number>") or date ("-D <date>") can also
6646 become sticky when they are specified on the command line.
6648 A sticky tag, revision or date remains until you specify another tag,
6649 revision or date the same way. The "update -A" command moves back to
6650 the Main branch, which has the side-effect of clearing all sticky
6651 items on the updated files.
6653 The "checkout" command creates sticky tags, revisions and dates the
6654 same way "update" does.
6656 Also, the '-k' option records a "sticky" keyword option that is used
6657 in further "updates until "update -A" is specified.
6659 Last modified: _6/13/1997_
6661 4. How do I get an old revision without updating the "sticky tag"?
6663 Use the '-p' option to "pipe" data to standard output. The command
6664 "update -p -r <tag/rev>" sends the selected revision to your standard
6665 output (usually the terminal, unless redirected). The '-p' affects no
6666 disk files, leaving a "sticky tag" unaltered and avoiding all other
6667 side-effects of a normal "update".
6669 If you want to save the result, you can redirect "stdout" to a file
6670 using your shell's redirection capability. In most shells the
6671 following command works:
6673 cvs update -p -r <tag/rev> filename > diskfile
6675 Last modified: _6/13/1997_
6677 5. What operations disregard sticky tags?
6679 The functions that routinely disregard sticky tags are:
6681 Those that work directly on the Repository or its administrative
6684 admin rtag log status remove history
6686 Those that take Tags or revisions as arguments and ignore everything
6687 else: (They also never *set* a sticky tag.)
6691 The "release" command itself ignores sticky tags, but it calls "cvs
6692 -n update" (which *does* pay attention to a sticky tag) to figure out
6693 what inconsistencies exist in the working directory. If no
6694 discrepancies exist between the files you originally checked out
6695 (possibly marked by a sticky tag) and what is there now, "release -d"
6696 will delete them all.
6698 The "tag" command works on the revision lying in the working
6699 directory however it got there. That the revision lying there might
6700 happen to have a sticky tag attached to it is not the "tag" command's
6703 The main function that *does* read and write sticky tags is the
6704 "update" command. You can avoid referring to or changing the sticky
6705 tag by using the '-p' option, which sends files to your terminal,
6706 touching nothing else.
6708 The "checkout" command sets sticky tags when checking out a new module
6709 and it acts like "update" when checking out a module into an existing
6712 The "diff" and "commit" commands use the sticky tags, unless
6713 overridden on the command line. They do not set sticky tags. Note that
6714 you can only "commit" to a file checked out with a sticky tag, if the
6715 tag identifies a branch.
6717 There are really two types of sticky tags, one attached to individual
6718 files (in the ./CVS/Entries file) and one attached to each directory
6719 (in the ./CVS/Tag file). They can differ.
6721 The "add" command registers the desire to add a new file. If the
6722 "directory tag" (./CVS/Tag) file exists at the time of the "add", the
6723 value stored in ./CVS/Tag becomes the "sticky tag" on the new file.
6724 The file doesn't exist in the Repository until you "commit" it, but
6725 the ./CVS/Entries file holds the sticky tag name from the time of the
6728 Last modified: _6/13/1997_
6730 6. Is there a way to avoid reverting my Emacs buffer after committing a
6731 file? Is there a "cvs-mode" for Emacs?
6735 Last modified: _6/13/1997_
6737 7. How does conflict resolution work? What *really* happens if two of us
6738 change the same file?
6740 While editing files, there is no conflict. You are working on separate
6741 copies of the file stored in the virtual "branch" represented by your
6742 working directories. After one of you commits a file, the other may
6743 not commit the same file until "update" has merged the earlier
6744 committed changes into the later working file.
6746 For example, say you both check out rev 1.2 of <file> and make change
6747 to your working files. Your coworker commits revision 1.3. When you
6748 try to commit your file, CVS says:
6750 cvs commit: Up-to-date check failed for `<file>'
6752 You must merge your coworker's changes into your working file by
6757 which will produce the output described in 2B.6.
6759 If a conflict occurs, the filename will be shown with a status of 'C'.
6760 After you resolve any overlaps caused by the merging process, you may
6761 then commit the file. See 3P.6 for info on "sticky conflicts".
6763 Even if you get a simple 'M', you should examine the differences
6764 before committing the file. A smooth, error-free text merge is still
6765 no indication that the file is in proper shape. Compile and test it at
6768 The answer to two obvious questions is "Yes".
6770 Yes, the first one who commits avoids the merge. Later developers have
6771 to merge the earlier changes into their working files before
6772 committing the merged result. Depending on how difficult the merge is
6773 and how important the contending projects are, the order of commits
6774 and updates might have to be carefully staged.
6776 And yes, between the time you execute "update" and "commit" (while you
6777 are fixing conflicts and testing the results) someone else may commit
6778 another revision of <file>. You will have to execute "update" again to
6779 merge the new work before committing. Most organizations don't have
6780 this problem. If you do, you might consider splitting the file. Or
6783 Last modified: _6/13/1997_
6785 8. How can I tell who has a module checked out?
6787 If you "checkout" module names (not relative pathnames) and you use
6788 the release command, the "history" command will display active
6789 checkouts, who has them and where they were checked out. It is
6790 advisory only; it can be circumvented by using the '-l' option on the
6793 Last modified: _6/13/1997_
6795 9. Where did the .#<file>.1.3 file in my working directory come from?
6797 It was created during an "update" when CVS merged changes from the
6798 Repository into your modified working file.
6800 It serves the same purpose as any "backup" file: saving your bacon
6801 often enough to be worth retaining. It is invaluable in recovering
6802 when things go wrong.
6804 Say Developers A (you) and B check out rev 1.3 of file <file>. You
6805 both make changes -- different changes. B commits first, so <file>,v
6806 in the Repository contains revisions up through 1.4.
6808 At this point, there are 5 (yes, five) versions of the file of
6811 Revision 1.3 (What you originally checked out.)
6813 Revision 1.4 (What you need from developer B.)
6815 Your old working file. (Before the update.)
6817 Your new working file. (After the merge caused by "update".)
6819 Revision 1.5 (Which you will commit shortly.)
6821 In the case where your working file was not modified, #1 and #3 will
6822 be the same, as will #2 and #4. In this degenerate case, there is no
6823 need to create #5. The following assumes that your working file was
6826 If the merge executed by the "update" caused no overlaps, and you
6827 commit the file immediately, #4 and #5 will be the same. But you can
6828 make arbitrary changes before committing, so the difference between #4
6829 and #5 might be more than just the correction of overlaps. In general,
6830 though, you don't need #4 after a commit.
6832 But #3 (which is the one saved as ".#<file>.1.3") holds all of your
6833 work, independent of B's work. It could represent a major effort that
6834 you couldn't afford to lose. If you don't save it somewhere, the merge
6835 makes #3 *disappear* under a potential blizzard of conflicts caused by
6836 overlapping changes.
6838 I have been saved a few times, and others I support have been saved
6839 hundreds of times, by the ability to "diff <original file> <original
6840 file with only my work added>", which can be done in the example above
6841 by the Unix shell command:
6843 cvs update -p -r 1.3 <file> | diff - .#<file>.1.3
6845 The assumption is that the ".#" files will be useful far beyond the
6846 "commit" point, but not forever. You are expected to run the "normal"
6847 Unix cleanup script from "cron", which removes "#*" and ".#*" files
6848 older than a some period chosen by your sysadmin, usually ranging from
6851 A question was raised about the need for #3 after #5 has been
6852 committed, under the assumption that you won't commit files until
6853 everything is exactly as you like them.
6855 This assumes perfect humans, which violates one of the Cardinal rules
6856 of Software Engineering: Never assume any form of discipline on the
6857 part of the users of software. If restrictions are not bound into the
6858 software, then you, the toolsmith, have to arrange a recovery path.
6860 In other words, I've seen every possible variety of screwup you can
6861 imagine in #5. There is no way to make assumptions about what "should"
6862 happen. I've seen #5 filled with zeros because of NFS failures, I've
6863 seen emacs core dumps that leave #5 in an unreasonable state, I've
6864 seen a foolish developer uppercase the whole file (with his "undo"
6865 size set low so he couldn't undo it) and decide that it would be less
6866 work to play with the uppercased file than to blow it away and start
6867 over. I've even seen committed files with conflict markers still in
6868 them, a sure sign of carelessness.
6870 There are all sorts of scenarios where having #3 is incredibly useful.
6871 You can move it back into place and try again.
6873 Last modified: _6/13/1997_
6875 10. What is this "ignore" business? What is it ignoring?
6877 The "update" and "import" commands use collections of Unix wildcards
6878 to skip over files and directories matching any of those patterns.
6880 You may add to the built-in ignore list by adding lines of
6881 whitespace-separated wildcards to the following places: (They are read
6884 In a file named "cvsignore" in $CVSROOT/CVSROOT.
6886 A Repository Administrator uses this to add site-specific files and
6887 patterns to the built-in ignore list.
6889 In a file named ".cvsignore" in your home directory.
6891 For user-specific files. For example, if you use "__" as your default
6892 junk file prefix, you can put "__*" in your .cvsignore file.
6894 People who play around exclusively in directory trees where the
6895 Makefiles are generated by "imake" or "configure" might want to put
6896 "Makefile" in their ignore list, since they are all generated and
6897 usually don't end up in the Repository.
6899 In the CVSIGNORE environment variable.
6901 For session-specific files.
6903 Via the '-I' option on "import" or "update" commands.
6905 For this-command-only files.
6907 In a file named ".cvsignore" within each directory.
6909 The contents of a ".cvsignore" file in each directory is temporarily
6910 added to the ignore list. This way you can ignore files that are
6911 peculiar to that directory, such as executables and other generated
6912 files without known wildcard patterns.
6914 In any of the places listed above, a single '!' character nulls out
6915 the ignore list. A Repository administrator can use this to override,
6916 rather than enhance, the built-in ignore list. A user can choose to
6917 override the system-wide ignore list. For example, if you place "! *.o
6918 *.a" in your .cvsignore file, only *.o *.a files, plus any files a
6919 local-directory .cvsignore file, are ignored.
6921 A variant of the ignore-file scheme is used internally during
6922 checkout. "Module names" found in the modules file (or on the
6923 "checkout" command line) that begin with a '!' are ignored during
6924 checkout. This is useful to permanently ignore (if the '!' path is in
6925 the modules file) or temporarily ignore (if the '!' path is on the
6926 command line) a sub-directory within a Repository hierarchy. For
6929 cvs checkout !gnu/emacs/tests gnu/emacs
6931 would checkout the module (or relative path within $CVSROOT) named
6932 "gnu/emacs", but ignore the "tests" directory within it.
6934 Last modified: _6/13/1997_
6936 11. Is there a way to set user-specific configuration options?
6938 User-specific configuration is available through use of a ".cvsrc"
6939 file in your home directory.
6941 CVS searches the first column of your ~/.cvsrc file for the cvs
6942 command name you invoked. If the command is found, the rest of the
6943 line is treated like a set of command line options, stuffed into the
6944 command line before the arguments you actually typed.
6946 For example, if you always want to see context diffs and you never
6947 want to have to delete a file before you run "cvs remove", then you
6948 should create a .cvsrc file containing the following:
6953 which will add the given options to every invocation of the given
6956 [[The rest of this will be removed someday, when CVS changes.]]
6958 I would like to stop here with a comment that the command name to use
6959 is the full, canonical one. But the command that the cvsrc support
6960 uses is the string you typed on the command line, not the proper
6961 command. So to get the full effect of the above example, you should
6962 also add all the alternate command names:
6969 There are two other limitations that will probably be fixed when CVS
6970 sprouts long option names:
6972 It only affects options made available on the command line.
6974 There is a limited number of short options. With long option names,
6975 there is no problem. You can have as many long options as you like,
6976 affecting anything that looks malleable.
6978 The existing command line options do not come in on/off pairs, so
6979 there is no easy way to override your ~/.cvsrc configuration for a
6980 single invocation of a command.
6982 Choosing a good set of long option pairs would fix this.
6984 Last modified: _6/13/1997_
6986 12. Is it safe to interrupt CVS using Control-C?
6988 It depends on what you mean by "safe". ("Ah," said Arthur, "this is
6989 obviously some strange usage of the word *safe* that I wasn't
6990 previously aware of." -- Hitchhiker's Guide to the Galaxy)
6992 You won't hurt the underlying RCS files and if you are executing a
6993 command that only *reads* data, you will have no cleanup to do.
6995 But you may have to hit Control-C repeatedly to stop it. CVS uses the
6996 Unix "system" routine which blocks signals in the CVS parent process.
6997 A single Control-C during "system" will only halt the child process,
6998 usually some form of RCS command.
7000 If you don't hit another Control-C while the CVS process has control,
7001 it is likely to continue onto the next task assuming that the earlier
7002 one did its job. It is not enough to hit two Control-C's. You might
7003 simply kill two child processes and not interrupt CVS at all.
7004 Depending on the speed of your processor, your terminal and your
7005 fingers, you might have to hit dozens of Control-C's to stop the damn
7008 Executing a CVS command, such as "commit" or "tag" that writes to the
7009 files is a different matter.
7011 Since CVS is not a full-fledged database, with what database people
7012 call "commit points", merely stopping the process will not back out
7013 the "transaction" and place you back in the starting blocks. CVS has
7014 no concept of an "atomic" transaction or of "backtracking", which
7015 means that a command can be half-executed.
7017 Hitting Control-C will usually leave lock files that you have to go
7018 clean up in the Repository.
7022 If you interrupt a multi-file "commit" in the middle of
7023 an RCS checkin, RCS will leave the file either fully
7024 checked-in or in its original state. But CVS might have
7025 been half-way through the list of files to commit. The
7026 directory or module will be inconsistent.
7028 To recover, you must remove the lock files, then decide
7029 whether you want to back out or finish the job.
7031 To back out, you'll have to apply the "admin -o"
7032 command, very carefully, to remove the newly committed
7033 revisions. This is usually a bad idea, but is
7034 occasionally necessary.
7036 To finish, you can simply retype the same commit command.
7037 CVS will figure out what files are still modified and
7038 commit them. It helps that RCS doesn't leave a file in an
7043 If you interrupt a multi-file "tag" command, you have a
7044 problem similar, but not equivalent, to interrupting a
7045 "commit". The RCS file will still be consistent, but
7046 unlike "commit", which only *adds* to the RCS file, "tag"
7047 can *move* a tag and it doesn't keep a history of what
7048 revision a tag used to be attached to.
7050 Normally, you have little choice but to re-execute the
7051 command and allow it to tag everything consistently.
7053 You might be able to recover by carefully re-applying the
7054 tags via the "cvs admin -N" command, but you'll still have
7055 to dig up from outside sources the information you use to
7056 determine what tag was on what revision in what file.
7057 the Repository, or by using the equivalent: "cvs admin".
7059 Halting a new "checkout" should cause no harm. If you don't want it,
7060 "release" (or rm -rf) it. If you do want it, re-execute the command. A
7061 repeated "checkout" from above a directory acts like a repeated
7062 "update -d" within it.
7064 Halting "update" half-way will give you an unpredictable collection of
7065 files and revisions. To continue, you can rerun the update and it
7066 should move you forward into in a known state. To back out, you'll
7067 have to examine the output from the first "update" command, take a
7068 look at each file that was modified and reconstruct the previous state
7069 by editing the ./CVS/Entries file and by using "cvs admin". Good Luck.
7071 Last modified: _6/13/1997_
7073 13. How do I turn off the "admin" command?
7075 In the current revision, you'd have to edit the source code.
7077 Last modified: _6/13/1997_
7079 14. How do I turn off the ability to disable history via "cvs -l"?
7081 In the current revision, you'd have to edit the source code.
7083 Last modified: _6/13/1997_
7085 15. How do I keep certain people from accessing certain directories?
7087 If you don't try to run CVS set[ug]id, you can use Unix groups and
7088 permissions to limit access to the Repository.
7090 If you only want to limit "commit" commands, you can write a program
7091 to put in the "commitinfo" file. In the "contrib" directory, there are
7092 a few scripts that might help you out.
7094 Last modified: _6/13/1997_
7096 Category: /User_Tasks_/Getting_Started/
7098 " + Getting Started"
7100 1. What is the first thing I have to know?
7102 Your organization has most likely assigned one or more persons to
7103 understand, baby-sit and administer the CVS programs and the data
7104 Repository. I call these persons Repository Administrators. They
7105 should have set up a Repository and "imported" files into it.
7107 If you don't believe anyone has this responsibility, or you are just
7108 testing CVS, then *you* are the Repository Administrator.
7110 If you are a normal user of CVS ask your Repository Administrator what
7111 module you should check out.
7115 If you *are* the Repository Administrator, you will want to read
7116 everything you can get your hands on, including this FAQ. Source
7117 control issues can be difficult, especially when you get to branches
7118 and release planning. Expect to feel stupid for a few days/weeks.
7120 No tool in the universe avoids the need for intelligent organization.
7121 In other words, there are all sorts of related issues you will
7122 probably have to learn. Don't expect to dive in without any
7123 preparation, stuff your 300 Megabytes of sources into CVS and expect
7124 to start working. If you don't prepare first, you will probably spend
7125 a few sleepless nights.
7127 Last modified: _6/13/1997_
7131 Wherever you have disk space. That's one of the advantages of CVS: you
7132 use the "checkout" command to copy files from the Repository to your
7133 working directory, which can be anywhere you have the space.
7135 Your local group might have conventions for where to work. Ask your
7138 Last modified: _6/13/1997_
7140 3. What does CVS use from my environment?
7142 You must set two environment variables. Some shells share these
7143 variables with local shell variables using a different syntax. You'll
7144 have to learn how your shell handles them.
7146 Variable Value (or action)
7147 --------- ---------------------
7148 CVSROOT Absolute pathname of the head of your Repository.
7150 PATH Normally set to a list of ':'-separated directory
7151 pathnames searched to find executables. You must
7152 make sure "cvs" is in one of the directories.
7154 If your CVS was built with the RCSBIN directory set
7155 to null (""), and you don't set the RCSBIN
7156 variable mentioned below, then the RCS commands
7157 also must be somewhere in your PATH.
7159 Optional variables: (Used if set, but ignored otherwise.)
7161 Variable Value (or action)
7162 --------- ---------------------
7163 CVSEDITOR The name of your favorite fast-start editor
7164 program. You'll be kicked into your editor to
7165 supply revision comments if you don't specify them
7166 via -m "Log message" on the command line.
7168 EDITOR Used if CVSEDITOR doesn't exist. If EDITOR
7169 doesn't exist, CVS uses a configured constant,
7172 CVSREAD Sets files to read-only on "checkout".
7174 RCSBIN Changes where CVS finds the RCS commands.
7176 CVSIGNORE Adds to the ignore list. See Section 2D.
7178 Other variables used by CVS that are normally set upon login:
7180 Variable Value (or action)
7181 --------- ---------------------
7182 LOGNAME Used to find the real user name.
7184 USER Used to find the real user name if no LOGNAME.
7186 HOME Used to determine your home directory, if set.
7187 Otherwise LOGNAME/USER/getuid() are used to find
7188 your home directory from the passwd file.
7190 TMPDIR Used during import. It might also be used if your
7191 platform's version of mktemp(3) is unusual, or
7192 you have changed the source to use tmpnam(3).
7194 Last modified: _6/13/1997_
7196 4. OK, I've been told that CVS is set up, my module is named "ralph" and I
7197 have to start editing. What do I type?
7199 cd <where you have some space to work>
7205 Last modified: _6/13/1997_
7207 5. I have been using RCS for a while. Can I convert to CVS without losing
7208 my revision history? How about converting from SCCS?
7210 If you are asking such questions, you are not a mere user of CVS, but
7211 one of its Administrators! You should take a look at Section 4A,
7212 "Installing CVS" and Section 4B, "Setting up and Managing the
7215 Last modified: _6/13/1997_
7217 Category: /User_Tasks_/Less_Common_User_Tas/
7219 " + Less Common User Tasks"
7221 1. Can I create non-CVS sub-directories in my working directory?
7223 Yes. Unless the directory exists in the Repository, "update" will skip
7224 over them and print a '?' the way it does for files you forgot to add.
7225 You can avoid seeing the '?' by adding the name of the foreign
7226 directory to the ./.cvsignore file, just ask you can do with files.
7228 If you explicitly mention a foreign directory on the "update" command
7229 line, it will traverse the directory and waste a bit of time, but if
7230 any directory or sub-directory lacks the ./CVS administrative
7231 directory, CVS will print an error and abort.
7233 Last modified: _6/13/1997_
7235 2. How do I add new sub-directories to the Repository?
7237 The "add" command will work on directories. You type:
7244 Directory /Repos/<dir> added to the repository
7246 and will create both a matching directory in the Repository and a
7247 ./CVS administrative directory within the local <dir> directory.
7249 Last modified: _6/13/1997_
7251 3. How do I remove a file I don't need?
7253 (See the questions in Section 4B on removing files from the
7261 CVS registers the file for removal. To complete the removal, you must
7266 CVS moves the file to the Attic associated with your working
7267 directory. Each directory in the Repository stores its deleted files
7268 in an Attic sub-directory. A normal "checkout" doesn't look in the
7269 Attic, but if you specify a tag, a date or a revision, the "checkout"
7270 (or "update") command will retrieve files from the Attic with that
7271 tag, date or revision.
7273 Last modified: _6/13/1997_
7275 4. How do I rename a file?
7277 CVS does not offer a way to rename a file in a way that CVS can track
7278 later. See Section 4B for more information.
7280 Here is the best (to some, the only acceptable) way to get the effect
7281 of renaming, while preserving the change log:
7283 Copy the RCS (",v") file directly in the Repository.
7285 cp $CVSROOT/<odir>/<ofile>,v $CVSROOT/<ndir>/<nfile>,v
7287 By duplicating the file, you will preserve the change history and the
7288 ability to retrieve earlier revisions of the old file via the "-r
7289 <tag/rev>" or "-D <date>" options to "checkout" and "update".
7291 Remove the old file using CVS.
7293 cd <working-dir>/<odir> rm <ofile>
7297 This will move the <ofile> to the Attic associated with <odir>.
7299 Retrieve <nfile> and remove all the Tags from it.
7301 By stripping off all the old Tags, "checkout -r" and "update -r" won't
7302 retrieve revisions Tagged before the renaming.
7304 cd <working-dir>/<ndir>
7306 cvs log <nfile> # Save the list of Tags
7307 cvs tag -d <tag1> <nfile>
7308 cvs tag -d <tag2> <nfile>
7311 This technique can be used to rename files within one directory or
7312 across different directories. You can apply this idea to directories
7313 too, as long as you apply the above to each file and don't delete the
7316 Of course, you have to change your build system (e.g. Makefile) in
7317 your <working-dir> to know about the name change.
7319 Warning: Stripping the old tags from the copied file will allow "-r
7320 <tag>" to do the right thing, but you will still have problems with
7321 "-D <date>" because there is no place to store the "deletion time".
7322 See 5B.3 for more details.
7324 Last modified: _6/13/1997_
7326 5. How do I make sure that all the files and directories in my working
7327 directory are really in the Repository?
7329 A "cvs update", or "cvs -n update" (which won't modify your working
7330 directory) will display foreign elements, which have no counterpart in
7331 the Repository, preceded by a '?'. To register foreign directories,
7332 you can use "cvs add". To register foreign files, you can use "cvs
7333 add" followed by "cvs commit".
7335 You could also checkout your module, or the Repository directory
7336 associated with your working directory, a second time into another
7337 work area and compare it to your working directory using the (non-CVS)
7340 By default many patterns of files are ignored. If you create a file
7341 named "core" or a file ending in ".o", it is usually ignored. If you
7342 really want to see all the files that aren't in the Repository, you
7343 can use a special "ignore" pattern to say "ignore no files". Try
7344 executing: (You may have to quote or backwhack (i.e. precede by '\')
7345 the '!' in your shell.)
7349 The above command will display not only the normal modified, update
7350 and conflict indicators ('M', 'U', and 'C' respectively) on files
7351 within the Repository, but it will also display each file not in the
7352 Repository preceded by a '?' character.
7354 The '-n' option will not allow "update" to alter your working
7357 Last modified: _6/13/1997_
7359 6. How do I create a branch?
7361 Type this in your working directory:
7363 cvs tag -b <branch_tag>
7365 and you will create a branch. No files have real branches in them yet,
7366 but if you move onto the branch by typing:
7368 cvs update -r <branch_tag>
7370 and commit a file in the normal way:
7374 then a branch will be created in the underlying <file>,v file and the
7375 new revision of <file> will appear only on that branch.
7377 See Section 4C, on Branching.
7379 Last modified: _6/13/1997_
7381 7. How do I modify the modules file? How about the other files in the
7382 CVSROOT administrative area?
7384 A module named "modules" has been provided in the default modules
7385 file, so you can type:
7387 cvs checkout modules
7390 Another module named CVSROOT has been provided in the default modules
7391 file, covering all the administrative files. Type:
7393 cvs checkout CVSROOT
7396 Then you can edit your files, followed by:
7400 If you start with the provided template for the "modules" file, the
7401 CVSROOT and the "modules" module will have the "mkmodules" program as
7402 a "commit helper". After a file is committed to such a module,
7403 "mkmodules" will convert a number of standard files (See 4B.2) in the
7404 CVSROOT directory inside the Repository into a form that is usable by
7407 Last modified: _6/13/1997_
7409 8. How do I split a file into pieces, retaining revision histories?
7411 If you and a coworker find yourselves repeatedly committing the same
7412 file, but never for changes in the same area of the file, you might
7413 want to split the file into two or more pieces. If you are both
7414 changing the same section of code, splitting the file is of no use.
7415 You should talk to each other instead.
7417 If you decide to split the file, here's a suggestion. In many ways, it
7418 is similar to multiple "renamings" as described in 2C.4 above.
7420 Say you want to split , which already in the Repository, into three
7423 Copy the RCS (",v") files directly in the Repository, creating the
7424 new files, then bring readable copies of the new files into the
7425 working directory via "update".
7427 cp $CVSROOT//,v $CVSROOT//,v cp $CVSROOT//,v $CVSROOT//,v
7430 Then remove all the from the new files, either using:
7432 cvs log # Save the list of
7437 (eivind@freebsd.org) or using the following little script to
7438 autmatically remove the tags directly from the repository files:
7443 TAGS=`rlog $file | awk '/^symbolic names:/,/^keyword subst/' | awk 'BEG
7444 IN {FS=":"} /^\t/ {print $1}'`
7445 echo The tags in $file are
7447 echo Is it OK to remove these?
7449 if [ "$confirm" = "y" -o "$confirm" = "yes" ]
7453 echo Removing $file:$tag
7459 Edit each file until it has the data you want in it. This is a
7460 hand-editing job, not something CVS can handle. Then commit all the
7463 [From experience, I'd suggest making sure that only one copy of each
7464 line of code exists among the three files, except for "include"
7465 statements, which must be duplicated. And make sure the code
7471 As in the "rename" case, by duplicating the files, you'll preserve the
7472 change history and the ability to retrieve earlier revisions.
7474 Of course, you have to alter your build system (e.g. Makefiles) to
7475 take the new names and the change in contents into account.
7477 Last modified: _3/11/1998_
7479 Category: /What_is_CVS_/
7483 Category: /What_is_CVS_/How_does_CVS_differ_/
7485 " + How does CVS differ from other, similar software?"
7487 1. How does CVS differ from RCS?
7489 CVS uses RCS to do much of its work and absolutely all the work of
7490 changing the underlying RCS files in the Repository.
7492 RCS comprises a set of programs designed to keep track of changes to
7493 individual files. Of course, it also allows you to refer to multiple
7494 files on the command line, but they are handled by iterating over
7495 individual files. There is no pretense of coordinated interaction
7496 among groups of files.
7498 CVS's main intent is to provide a set of grouping functions that allow
7499 you to treat a collection of RCS files as a single object. Of course,
7500 CVS also has to do a lot of iteration, but it tries its best to hide
7501 that it is doing so. In addition, CVS has some truly group-oriented
7502 facets, such as the modules file and the CVS administrative files that
7503 refer to a whole directory or module.
7505 One group aspect that can be a bit confusing is that a CVS branch is
7506 not the same as an RCS branch. To support a CVS branch, CVS uses
7507 "tags" (what RCS calls "symbols") and some local state, in addition to
7510 Other features offered by CVS that are not supported directly by RCS
7513 Automatic determination of the state of a file, (e.g. modified,
7514 up-to-date with the Repository, already tagged with the same string,
7515 etc.) which helps in limiting the amount of displayed text you have to
7516 wade through to figure out what changed and what to do next.
7518 A copy-modify-merge scheme that avoids locking the files and allows
7519 simultaneous development on a single file.
7521 Serialization of commits. CVS requires you to merge all changes
7522 committed (via "update") since you checked out your working copy of
7523 the file. Although it is still possible to commit a file filled with
7524 old data, it is less likely than when using raw RCS.
7526 Relatively easy merging of releases from external Vendors.
7528 Last modified: _6/13/1997_
7530 2. How does CVS differ from SCCS?
7532 SCCS is much closer to RCS than to CVS, so some of the previous entry
7535 You might want to take a look at Walter Tichy's papers on RCS, which
7536 are referred to in the RCS man pages.
7540 Last modified: _6/13/1997_
7542 3. How does CVS differ from ClearCase?
7544 ClearCase is a distributed client-server version control system.
7545 ClearCase is a variant DSEE tools, formerly available on Apollo
7546 platforms. The ClearCase tool set includes a few X-based interface
7547 tools, a command-line interface, and C programmer API. It is currently
7548 available on Sun, HP, SGI and OSF/1 platforms.
7550 ClearCase uses a special Unix filesystem type, called "mvfs" for
7551 "multi-version file system". Conceptually, mvfs adds another dimension
7552 to a regular Unix filesystem. The new axis is used to store the
7553 different versions of files and to provide a tree-hierarchical view of
7554 a collection of objects that might be scattered across any number of
7555 separate hosts on your local network.
7557 Each user acquires a "view" into the file database by creating a
7558 special mvfs mount point on their machine. Each view has a
7559 "configuration spec" containing a set of selection rules that specify
7560 the particular version of each file to make visible in that view. You
7561 can think of a "view" as a work area in CVS, except that the files
7562 don't really exist on your local disk until you modify them. This
7563 technique conserves disk space because it doesn't keep private copies
7566 Another advantage is that a view is "transparent" in the sense that
7567 all of the files in a "view" appear to be regular Unix files to other
7568 tools and Unix system calls. An extended naming convention allows
7569 access to particular versions of a file directly:
7570 "test.cc@@/main/bugfix/3" identifies the third version of test.c on
7573 ClearCase supports both the copy-modify-merge model of CVS (by using
7574 what are called "unreserved checkouts" and the checkin/checkout
7575 development model with file locking. Directories are
7576 version-controlled objects as well as files. A graphical merge tool is
7577 provided. Like RCS, ClearCase supports branches, symbolic tags, and
7578 delta compression. ASCII as well as binary files are supported, and
7579 converters from RCS, SCCS, DSEE formats are also included.
7581 A make-compatible build facility is provided that can identify common
7582 object code and share it among developers. A build auditing feature
7583 automatically records file dependencies by tracking every file that is
7584 opened when producing a derived object, thus making explicit
7585 dependency lists unnecessary. Pre- and post-event triggers are
7586 available for most ClearCase operations to invoke user programs or
7587 shell scripts. User-defined attributes can be assigned to any version
7588 or object. Hyper-links between version controlled objects can record
7591 For more information, contact:
7593 Atria Software, Inc. 24 Prime Park Way Natick, MA 01760 info@atria.com
7595 (508) 650-1193 (phone) (508) 650-1196 (fax)
7597 Originally contributed by Steve Turner
7598 Edited by the author of this FAQ.
7600 Last modified: _6/13/1997_
7602 4. How does CVS differ from TeamWare/SparcWorks?
7604 TeamWare is a configuration management tool from Sun Microsystems, a
7605 part of SparcWorks. It uses the same copy and merge model as CVS. The
7606 central abstraction is a workspace, which corresponds to either a CVS
7607 branch or a checked out module. TeamWare allows you to manipulate
7608 workspaces directly, including moving and merging code between
7609 workspaces. You can put your workspace on tape and continue to work
7610 with it at home, just like you can with CVS. TeamWare is built upon
7611 and compatible with SCCS.
7613 TeamWare provides both a command line interface and a graphical
7614 interface. The CodeManager tool will display the project as a tree of
7615 workspaces, and allows you to manipulate them with drag and drop. The
7616 other tools are VersionTool that displays and manipulates a dag with a
7617 version history of a single file, CheckPoint that will create symbolic
7618 tags, MakeTool, a make compatible tool with a GUI, and FileMerge which
7619 will interactively merge files when needed (like emerge for emacs). If
7620 you have a sun, you can try /usr/old/mergetool for an old SunView
7621 version of FileMerge.
7623 Email: sunprosig@sun.com
7625 Originally extracted from TeamWare
7626 Marketing literature by Per Abrahamsen.
7627 Edited by the author of this FAQ.
7629 For more information, contact:
7631 SunExpress, Inc. P.O. Box 4426 Bridgeton, MO 63044-9863 (800)873-7869
7633 Last modified: _6/13/1997_
7635 5. How does CVS differ from Aegis?
7637 Aegis appears to be a policy-setting tool that allows you to use other
7638 sub-programs (make, RCS, etc.) to implement pieces of the imposed
7641 The initial document seems to say that most Unix tools are inadequate
7642 for use under Aegis.
7644 It is not really similar to CVS and requires a different mindset.
7646 [[Need more info here.]]
7648 Last modified: _6/13/1997_
7650 6. How does CVS differ from Shapetools?
7652 Shapetools includes a build mechanism (called Shape, not surprisingly)
7653 that is aware of the version mechanism, and some dependency tracking.
7654 It is based on a file system extension called Attributed File System,
7655 which allows arbitrary-sized "attributes" to be associated with a
7656 file. Files are version controlled in a manner similar to RCS.
7657 Configurations are managed through the Shapefile, an extension of the
7658 Makefile syntax and functionality. Shape includes version selection
7659 rules to allow sophisticated selection of component versions in a
7662 Shapetools' concurrency control is pessimistic, in contrast to that of
7663 CVS. Also, there's very limited support for branching and merging. It
7664 has a built-in policy for transitioning a system from initial
7665 development to production.
7667 Contributed by Don Dwiggins
7669 Last modified: _6/13/1997_
7671 7. How does CVS differ from TeamNet?
7673 TeamNet is a configuration management tool from TeamOne.
7675 For more information, contact:
7677 TeamOne 710 Lakeway Drive, Ste 100 Sunnyvale, CA 94086 (800) 442-6650
7679 Contributed by Steve Turner
7681 Last modified: _6/13/1997_
7683 8. How does CVS differ from ProFrame?
7685 ProFrame is a new system integration framework from IBM. ProFrame is
7686 compliant with the CFI (CAD Framework Initiative) industry standards,
7687 including the Scheme extension language.
7689 ProFrame consists of three major components: (1) the Process Manager
7690 that automates your local design methodology (2) the Design Data
7691 Manager handles configuration management, and (3) Inter-tool
7692 Communication to provide a communication path among tools running on
7693 heterogeneous servers.
7695 The Design Data Manager(2) is probably the appropriate component to
7696 compare to CVS. The Design Data Manager provides version control with
7697 checkin/checkout capability, configuration management, and data
7698 dependency tracking. A graphical data selection interface is provided.
7699 Using this interface, you may create and manipulate objects and
7700 hierarchy structures, view the revision history for an object, and
7701 view and assign attributes to a design object.
7703 The ProFrame server currently runs only on RS6000, but clients may be
7704 a wide variety of Unix platforms. Contact IBM for the latest platform
7707 For more information, contact:
7709 IBM EDA Marketing and Sales P.O. Box 950, M/S P121 Poughkeepsie, NY
7710 12602 (800) 332-0066
7712 Contributed by Steve Turner
7713 [extracted from the ProFrame 1.1.0 datasheet]
7715 Last modified: _6/13/1997_
7717 9. How does CVS differ from CaseWare/CM?
7719 CaseWare/CM is a software configuration management product from
7720 CaseWare, Inc. CaseWare/CM may be customized to support a wide variety
7721 of methodologies, including various phases of the software lifecycle,
7722 and different access rights for users.
7724 A GUI is provided to view version histories and configurations. A
7725 merge tools is also included. CaseWare supports type-specific
7726 lifecycles, which allows different types of files to move through
7727 different lifecycles. Also provided is a build facility to support
7728 automatic dependency analysis, parallel, distributed, and remote
7729 builds, and variant releases.
7731 CaseWare/CM has been integrated with other CASE tools, including
7732 FrameMaker, ALSYS Ada, CodeCenter/Object Center, HP SoftBench, and
7733 Software Through Pictures. CaseWare also offers CaseWare/PT, a problem
7734 tracking system to integrate change requests with configuration
7737 Multiple vendors and operating systems are supported.
7739 For more information, contact:
7741 CaseWare, Inc. 108 Pacifica, 2nd Floor Irvine, CA 92718-3332 (714)
7742 453-2200 (phone) (714) 453-2276 (fax)
7744 Contributed by Steve Turner
7745 [extracted from the CaseWare/CM data sheet]
7747 Last modified: _6/13/1997_
7749 10. How does CVS differ from SABLIME?
7751 Produced by AT&T. Sablime uses SCCS as the underlying source code
7752 control system. It uses some other control system (called sbcs I
7753 think) for managing binary files. It uses lock, edit, comit, unlock
7754 mechanism. It has a motif based GUI and curses based GUI (that works
7755 only with ksh, not tcsh, or bash) to do more common tasks. It has even
7756 a command line interface.
7758 Changing source happens as a result of MR. A testing person or a
7759 developer assigns an MR (modification request) to a group of people.
7760 They are allowed to take out files under that MR and change them and
7761 check them back in. You can set up dependencies between and MR and do
7762 release management to say "I want the sources to include these MRs"
7763 etc. It is a reasonably good maintanance system. It is bit heavy
7764 weight though, and the interface is not too polished and does not work
7765 on windows (though that may have changed). rama@savera.com
7767 Last modified: _7/30/1998_
7769 11. How does CVS differ from PVCS?
7771 PVCS works on single files like RCS and SCCS, CVS works on complete
7772 subsystems. PVCS has a make utility (called a configuration builder),
7773 CVS does not. PVCS has a GUI interface for Unix, DOS, OS/2, and MS
7780 Contributed by Per Abrahamsen
7781 [Extracted from Intersolv Marketing literature.]
7783 Last modified: _6/13/1997_
7785 12. How does CVS differ from CMVC?
7787 CMVC is an IBM Configuration Management and Version Control system.
7788 (Though I'm not certain that's the right acronym expansion.) It runs
7789 on Suns, HPs, RS6000s, OS/2 and Windows.
7791 Other than revision control, it apparently has features to manage
7792 releases, bug tracking and the connection between alterations and
7793 reported bugs and feature requests. It is a client/server system,
7794 based on a choice of commercial Relational Database systems, and it
7795 provides a Motif or command line interface.
7797 Unlike CVS, it uses a strict locking protocol to serialize source code
7800 Last modified: _6/13/1997_
7802 Category: /What_is_CVS_/What_do_you_mean_by_/
7804 " + What do you mean by . . .? (Definitions)"
7806 1. What are "The Repository", "$CVSROOT" and "CVSROOT"?
7808 The Repository is a directory tree containing the CVS administrative
7809 files and all the RCS files that constitute "imported" or "committed"
7810 work. The Repository is kept in a shared area, separate from the
7811 working areas of all developers.
7813 Users of CVS must set their "CVSROOT" environment variable to the
7814 absolute pathname of the head of the Repository. Most command line
7815 interpreters replace an instance of "$CVSROOT" with the value of the
7816 "CVSROOT" environment variable. By analogy, in this document
7817 "$CVSROOT" is used as shorthand for "the absolute pathname of the
7818 directory at the head of the Repository".
7820 One of the things found in $CVSROOT is a directory named CVSROOT. It
7821 contains all the "state", the administrative files, that CVS needs
7822 during execution. The "modules", "history", "commitinfo", "loginfo"
7823 and other files can be found there. See 4B.2 for more information
7824 about CVSROOT files.
7826 Last modified: _6/13/1997_
7828 2. What is an RCS file?
7830 An RCS file is a text file containing the source text and the revision
7831 history for all committed revisions of a source file. It is stored
7832 separately from the working files, in a directory hierarchy, called
7835 RCS is the "Revision Control System" that CVS uses to manage
7836 individual files. RCS file names normally end in ",v", but that can be
7837 altered (via the RCS -x option) to conform to file naming standards on
7838 platforms with unusual filename limitations.
7840 Last modified: _6/13/1997_
7842 3. What is a working file?
7844 A working file is a disk file containing a checked-out copy of a
7845 source file that earlier had been placed under CVS. If the working
7846 file has been edited, the changes since the last committed revision
7847 are invisible to other users of CVS.
7849 Last modified: _6/13/1997_
7851 4. What is a working directory (or working area)?
7853 A working directory is the place where you work and the place from
7854 which you "commit" files.
7856 The "checkout" command creates a tree of working directories, filling
7857 them with working files. Each working directory contains a
7858 sub-directory named ./CVS containing three administrative files, which
7859 are created by "checkout" and are always present:
7862 contains information about working files.
7865 contains the location of the directory within the
7866 Repository that was used to create the working directory.
7869 contains the value of $CVSROOT at the time you created
7870 the working directory.
7872 Other files may also appear in ./CVS depending on the state of your
7876 contains the "sticky tag" associated with the whole
7877 directory. See 3A.2 for its main purpose.
7878 [Created by "checkout" or "update" when using "-r <tag>".]
7879 [Deleted by "checkout" or "update" when using '-A'.]
7881 ./CVS/Entries.Static
7882 contains a fixed list of working files. If this file
7883 exists, an "update" doesn't automatically bring newly
7884 added files out of the Repository.
7885 [Created and maintained by hand.]
7888 contains a program to run whenever anything in the
7889 working directory is committed.
7890 [Created by checkout if "-i <prog>" appears in the
7891 modules file for the checked-out module.]
7894 contains a program to run whenever anything in the
7895 working directory is updated.
7896 [Created by checkout if "-u <prog>" appears in the
7897 modules file for the checked-out module.]
7899 ./CVS/<file>,p ./CVS/<file>,t
7900 contain (possibly zero-length) state information about an
7901 "add" that has not been committed.
7903 [Deleted by "commit" or "remove".]
7905 Last modified: _6/13/1997_
7907 5. What is "checking out"?
7909 "Checking out" is the act of using the "checkout" command to copy a
7910 particular revision from a set of RCS files into your working area.
7911 You normally execute "checkout" only once per working directory (or
7912 tree of working directories), maintaining them thereafter with the
7915 See section 3C on the "checkout" command.
7917 Last modified: _6/13/1997_
7919 6. What is a revision?
7921 A "revision" is a version of a file that was "committed" ("checked
7922 in", in RCS terms) some time in the past. CVS (and RCS) can retrieve
7923 any file that was committed by specifying its revision number or its
7924 "tag" ("symbolic name", in RCS terms).
7926 In CVS, a "tag" is more useful than a revision number. It usually
7927 marks a milestone in development represented by different revision
7928 numbers in different files, all available as one "tagged" collection.
7930 Sometimes the word "revision" is used as shorthand for "the file you
7931 get if you retrieve (via "checkout" or "update") the given revision
7932 from the Repository."
7934 Last modified: _6/13/1997_
7938 A "Tag" is a symbolic name, a synonym or alias for a particular
7939 revision number in a file. The CVS "tag" command places the same "Tag"
7940 on all files in a working directory, allowing you to retrieve those
7941 files by name in the future.
7943 The CVS "Tag" is implemented by applying RCS "symbols" to each
7944 individual file. The Tags on a file (or collection of files) may be
7945 displayed using the "log" command.
7947 Last modified: _6/13/1997_
7949 8. What are "HEAD" and "BASE"?
7951 HEAD and BASE are built-in tags that don't show up in the "log" or
7952 "status" listings. They are interpreted directly by CVS.
7954 "HEAD" refers to the latest revision on the current branch in the
7955 Repository. The current branch is either the main line of development,
7956 or a branch in development created by placing a branch tag on a set of
7957 files and checking out that branch.
7959 "BASE" refers to the revision on the current branch you last checked
7960 out, updated, or committed. If you have not modified your working
7961 file, "BASE" is the committed revision matching it.
7963 Most of the time BASE and HEAD refer to the same revision. They can
7964 become different in two ways:
7966 Someone else changed HEAD by committing a new revision of your file
7967 to the Repository. You can pull BASE up to equal HEAD by executing
7970 You moved BASE backward by executing "checkout" or "update" with the
7971 option "-r <rev/tag>" or "-D <date>". CVS records a sticky tag and
7972 moves your files to the specified earlier revision. You can clear the
7973 sticky tag and pull BASE up to equal HEAD again by executing "update
7976 Last modified: _6/13/1997_
7978 9. What is a Branch?
7980 In general, a branch is any mechanism that allows one or more
7981 developers to modify a file without affecting anyone other than those
7982 working on the same branch.
7984 There are four kinds of "branch" CVS can manage:
7988 A single vendor branch is supported. The "import" command takes a
7989 sequence of releases from a source code vendor (called a "vendor" even
7990 if no money is involved), placing them on a special "Vendor" branch.
7991 The Vendor branch is considered part of the "Main line" of
7992 development, though it must be merged into locally modified files on
7993 the RCS Main branch before the "import" is complete.
7995 See Section 3H ("import").
7997 Your Working directory.
7999 A checked-out working directory, can be treated like a private branch.
8000 No one but you can touch your files. You have complete control over
8001 when you include work committed by others. However, you can't commit
8002 or tag intermediate versions of your work.
8004 A Development branch.
8006 A group of developers can share changes among the group, without
8007 affecting the Main line of development, by creating a branch. Only
8008 those who have checked-out the branch see the changes committed to
8009 that branch. This kind of branch is usually temporary, collapsing
8010 (i.e. merge and forget) into the Main line when the project requiring
8011 the branch is completed.
8013 You can also create a private branch of this type, allowing an
8014 individual to commit (and tag) intermediate revisions without changing
8015 the Main line. It should be managed exactly like a Development Branch
8016 -- collapsed into the Main line (or its parent branch, if that is not
8017 the Main Branch) and forgotten when the work is done.
8021 At release time, a branch should be created marking what was released.
8022 Later, small changes (sometimes called "patches") can be made to the
8023 release without including everything else on the Main line of
8024 development. You avoid forcing the customer to accept new, possibly
8025 untested, features added since the release. This is also the way to
8026 correct bugs found during testing in an environment where other
8027 developers have continued to commit to the Main line while you are
8028 testing and packaging the release.
8030 Although the internal format of this type of branch (branch tag and
8031 RCS branches) is the same as in a development branch, its purpose and
8032 the way it is managed are different. The major difference is that a
8033 Release branch is normally Permanent. Once you let a release out the
8034 door to customers, or to the next stage of whatever process you are
8035 using, you should retain forever the branch marking that release.
8037 Since the branch is permanent, you cannot incorporate the branch fixes
8038 into the Main line by "collapsing" (merging and forgetting) the
8039 release branch. For large changes to many files on the release branch,
8040 you will have to perform a branch merge using "update -j <rev> -j
8043 The most common way to merge small changes back into Main line
8044 development is to make the change in both places simultaneously. This
8045 is faster than trying to perform a selective merge.
8047 See 1D.12 (merges) and Section 4C, on Branching for more info.
8049 Last modified: _6/13/1997_
8051 10. What is "the trunk"?
8053 Another name for the RCS Main Branch. The RCS Main Branch is related,
8054 but not equivalent, to both the CVS Main branch and what developers
8055 consider to be the Main line of development. See 3H.3 and Section 4C
8058 Last modified: _6/13/1997_
8060 11. What is a module?
8062 In essence, a module is a name you hand to the "checkout" command to
8063 retrieve one or more files to work on. It was originally intended to
8064 be a simple, unique name in the "modules" file attached to a directory
8065 or a subset of files within a directory.
8067 The module idea is now a somewhat slippery concept that can be defined
8068 in two different ways:
8069 * A module is an argument to "checkout". There are three types:
8070 1. An entry in the modules file. A "module" name as described in
8072 2. A relative path to a directory or file in the Repository.
8073 3. A mixed-mode string of "modulename/relative-path". Everything
8074 up to the first slash ('/') is looked up as a module. The
8075 relative path is appended to the directory associated with
8076 the module name and the resulting path is checked out as in
8078 * A module is a unique (within the file) character string in the
8079 first column of the modules file. There are five types:
8080 1. A name for a directory within the Repository that allows you
8081 to ignore the parent directories above it.
8084 2. A name for a subset of the files within such a directory.
8086 ls unix/bin Makefile ls.c
8087 The 2nd through Nth strings in the above can be files,
8088 directories or module substitutions. No relative paths.
8089 A module substitution occurs when you use a '&module-name'
8090 reference. The module-name referred to is logically
8091 substituted for the '&module-name' string.
8092 3. A relative pathname to a directory within the Repository
8093 which, when checked out, creates an image of part of the
8094 Repository structure in your current directory.
8096 gnu/emacs -o /bin/emacs.helper gnu/emacs
8097 The files checked out are exactly the same as the files
8098 "checkout" would retrieve if the path weren't even in the
8099 modules file. The only reason to put this kind of relative
8100 pathname into the modules file is to hook one of the helper
8102 4. A relative pathname to a single file within the Repository
8103 which, when checked out, creates something you probably don't
8104 want: It creates a directory by the name of the file and puts
8107 gnu/emacs/Makefile -o /bin/emacs.helper gnu/emacs Makefile
8108 The file checked out is the same as what you would get if you
8109 handed the relative pathname to the "checkout" command. But
8110 it puts it in a strange place. The only reason to do this is
8111 to hook a helper function onto a specific file name.
8112 5. An alias consisting of a list of any of the above, including
8113 other aliases, plus exceptions.
8115 my_work -a emacs !emacs/tests gnu/bison unix/bin/ls.c
8116 The exception "!emacs/test" above is functionally equivalent
8117 to specifying "!emacs/tests" on the "checkout" command line.
8119 Another way to look at it is that the modules file is simply another
8120 way to "name" files. The hierarchical directory structure provides
8121 another. You should use whatever turns out to be simplest for your
8124 See 4G.2 for some specific ideas about how to use the modules file.
8126 Last modified: _11/12/1997_
8128 12. What does "merge" mean?
8130 A merge is a way of combining changes made in two independent copies
8131 of a common starting file. Checking out an RCS revision produces a
8132 file, so for the purposes of a merge "file" and "revision" are
8133 equivalent. So, we can say there are always three "files" involved in
8136 The original, starting, "base" or "branch point" file.
8138 A copy of the base file modified in one way.
8140 Another copy of the base file modified in a different way.
8142 Humans aren't very good at handling three things at once, so the
8143 terminology dealing with merges can become strained. One way to think
8144 about it is that all merges are performed by inserting the difference
8145 between a base revision and a later revision (committed by someone
8146 else) into your working file. Both the "later" revision and your
8147 working file are presumed to have started life as a copy of the "base"
8150 In CVS, there are three main types of "merge":
8152 The "update" command automatically merges revisions committed by
8153 others into your working file. In this case, the three files involved
8156 Base: The revision you originally checked out. Later: A revision
8157 committed onto the current branch after you checked out the Base
8158 revision. Working: Your working file. The one lying in the working
8159 directory containing changes you have made.
8161 The "update -j <branch_tag> {optional files}" command merges changes
8162 made on the given branch into your working files, which is presumed to
8163 be on the Main line of development.
8167 The "update -j <rev> -j <rev> {optional files}" command merges the
8168 difference between two specified revisions into files in your working
8169 directory. The two revisions <rev> are usually on the same branch and,
8170 when updating multiple files, they are most useful when they are Tag
8171 names rather than numeric revisions.
8175 Last modified: _6/13/1997_
8177 Category: /What_is_CVS_/What_is_CVS_Whats_it/
8179 " + What is CVS? What's it for? Why CVS?"
8181 1. What does CVS stand for? Can you describe it in one sentence?
8183 "CVS" is an acronym for the "Concurrent Versions System".
8185 CVS is a "Source Control" or "Revision Control" tool designed to keep
8186 track of source changes made by groups of developers working on the
8187 same files, allowing them to stay in sync with each other as each
8190 Last modified: _6/13/1997_
8192 2. What is CVS for? What does it do for me?
8194 CVS is used to keep track of collections of files in a shared
8195 directory called "The Repository". Each collection of files can be
8196 given a "module" name, which is used to "checkout" that collection.
8198 After checkout, files can be modified (using your favorite editor),
8199 "committed" back into the Repository and compared against earlier
8200 revisions. Collections of files can be "tagged" with a symbolic name
8201 for later retrieval.
8203 You can add new files, remove files you no longer want, ask for
8204 information about sets of files in three different ways, produce patch
8205 "diffs" from a base revision and merge the committed changes of other
8206 developers into your working files.
8208 Last modified: _6/13/1997_
8210 3. How does CVS work?
8212 CVS saves its version-control information in RCS files stored in a
8213 directory hierarchy, called the Repository, which is separate from the
8214 user's working directory.
8216 Files in the Repository are stored in a format dictated by the RCS
8217 commands CVS uses to do much of its real work. RCS files are standard
8218 byte-stream files with an internal format described by keywords stored
8219 in the files themselves.
8221 To begin work, you execute a "checkout" command, handing it a module
8222 name or directory path (relative to the $CVSROOT variable) you want to
8223 work on. CVS copies the latest revision of each file in the specified
8224 module or directory out of the Repository and into a directory tree
8225 created in your current directory. You may specify a particular branch
8226 to work on by symbolic name if you don't want to work on the default
8227 (main or trunk) branch.
8229 You may then modify files in the new directory tree, build them into
8230 output files and test the results. When you want to make your changes
8231 available to other developers, you "commit" them back into the
8234 Other developers can check out the same files at the same time. To
8235 merge the committed work of others into your working files you use the
8236 "update" command. When your merged files build and test correctly, you
8237 may commit the merged result. This method is referred to as
8238 "copy-modify-merge", which does not require locks on the source files.
8240 At any time, usually at some milestone, you can "tag" the committed
8241 files, producing a symbolic name that can be handed to a future
8242 "checkout" command. A special form of "tag" produces a branch in
8243 development, as usually happens at "release" time.
8245 When you no longer plan to modify or refer to your local copy of the
8246 files, they can be removed.
8248 Last modified: _6/13/1997_
8250 4. What is CVS useful for?
8252 CVS is intended to handle source control for files in three major
8255 Multiple developers working on the same files.
8257 The major advantage of using CVS over the simpler tools like RCS or
8258 SCCS is that it allows multiple developers to work on the same sources
8261 The shared Repository provides a rendezvous for committed sources that
8262 allows developers a fair amount of flexibility in how often to publish
8263 (via the "commit" command) changes or include work committed by others
8264 (via the "update" command).
8266 Tracking a stream of releases from a source vendor.
8268 If you are making changes to sources distributed by someone else, the
8269 CVS feature, called the Vendor Branch, allows you to combine local
8270 modifications with repeated vendor releases.
8272 I have found this most useful when dealing with sources from three
8273 major classes of source vendor:
8275 Large companies who send you tapes full of the latest release (e.g.
8276 Unix OS vendors, database companies).
8278 Public Domain software which *always* requires work.
8280 Pseudo-Public sources which may require work. (e.g. GNU programs, X,
8283 Branching development.
8285 Aside from the "Vendor Branch", there are three kinds of "branches in
8286 development" that CVS can support:
8288 Your working directory can be treated as a private branch.
8290 A Development branch can be shared by one or more developers.
8292 At release time, a branch is usually created for bug fixes.
8294 (See 1D.9 and Section 4C for more info on branches.)
8296 CVS's branch support is a bit primitive, but it was designed to allow
8297 you to create branches, work on them for while and merge them back
8298 into the main line of development. You should also be able to merge
8299 work performed on the main branch into the branch you are working on.
8300 Arbitrary sharing and merging between branches is not currently
8303 Last modified: _6/13/1997_
8305 5. What is CVS *not* useful for?
8307 CVS is not a build system.
8309 Though the structure of your Repository and modules file interact with
8310 your build system (e.g. a tree of Makefiles), they are essentially
8313 CVS does not dictate how you build anything. It merely stores files
8314 for retrieval in a tree structure you devise.
8316 CVS does not dictate how to use disk space in the checked out working
8317 directories. If you require your Makefiles or build procedures to know
8318 the relative positions of everything else, you wind up requiring the
8319 entire Repository to be checked out. That's simply bad planning.
8321 If you modularize your work, and construct a build system that will
8322 share files (via links, mounts, VPATH in Makefiles, etc.), you can
8323 arrange your disk usage however you like.
8325 But you have to remember that *any* such system is a lot of work to
8326 construct and maintain. CVS does not address the issues involved. You
8327 must use your brain and a collection of other tools to provide a build
8328 scheme to match your plans.
8330 Of course, you should use CVS to maintain the tools created to support
8331 such a build system (scripts, Makefiles, etc).
8333 CVS is not a substitute for management.
8335 You and your project leaders are expected to plan what you are doing.
8336 Everyone involved must be aware of schedules, merge points, branch
8337 names, release dates and the range of procedures needed to build
8338 products. (If you produce it and someone else uses it, it is a
8339 product.) CVS can't cover for a failure to manage your project.
8341 CVS is an instrument for making sources dance to your tune. But you
8342 are the piper and the composer. No instrument plays itself or writes
8345 CVS is not a substitute for developer communication.
8347 When faced with conflicts within a single file, most developers manage
8348 to resolve them without too much effort. But a more general definition
8349 of "conflict" includes problems too difficult to solve without
8350 communication between developers.
8352 CVS cannot determine when simultaneous changes within a single file,
8353 or across a whole collection of files, will logically conflict with
8354 one another. Its concept of a "conflict" is purely textual, arising
8355 when two changes to the same base file are near enough to spook the
8356 merge command into dropping conflict markers into the merged file.
8358 CVS is not capable of figuring out distributed conflicts in program
8359 logic. For example, if you change the arguments to function X defined
8360 in file A and, at the same time, edit file B, adding new calls to
8361 function X using the old arguments. You are outside the realm of CVS's
8364 Acquire the habit of reading specs and talking to your peers.
8366 CVS is not a configuration management system.
8368 CVS is a source control system. The phrase "configuration management"
8369 is a marketing term, not an industry-recognized set of functions.
8371 A true "configuration management system" would contain elements of the
8375 * Dependency tracking.
8376 * Build systems (i.e. What to build and how to find
8377 things during a build. What is shared? What is local?)
8379 * Automated Testing procedures.
8380 * Release Engineering documentation and procedures.
8381 * Tape Construction.
8382 * Customer Installation.
8383 * A way for users to run different versions of the same
8384 software on the same host at the same time.
8386 CVS provides only the first.
8388 Last modified: _6/13/1997_
8390 Category: /What_is_CVS_/Where_do_I_find_CVS_/
8392 " + Where do I find CVS? Where can I find Help?"
8394 1. How do I get more information about CVS?
8396 The first thing I would do is to read the Info file that comes with
8397 the CVS sources under "doc". You can format and read the cvs.texinfo
8398 file in two ways: 1. Use TeX to format it and a "dvips" command to
8399 print it and 2. Install the cvs.info files that are created by the
8400 Makefile and read them online using the Emacs "info-mode" or a
8401 stand-alone "info" reader.
8403 Then I'd run "cvsinit" to set up a Repository and read the man page
8404 while trying out the commands.
8406 Type "cvs -H" for general help or "cvs -H command" for
8407 command-specific help.
8409 For background, you can read the original CVS paper (in the source
8410 tree, under "doc"). It describes the purpose of CVS and some of how it
8411 was designed. Note that the emphasis of the document (especially on
8412 multiple vendors providing the same sources) is somewhat out of date.
8414 For more detailed information about "internals", read the man pages
8415 for RCS. If you are a programmer, you can also read the source code to
8418 Other information and tutorials may be available in the "doc"
8419 directory of the FTP archive described below.
8421 For current information, and a fair amount of detail, join the
8422 info-cvs mailing list described below.
8424 Last modified: _6/13/1997_
8426 2. Is there an archive of CVS material?
8428 An anonymous FTP area has been set up. It contains many of the CVS
8429 files you might want, including extra documentation, patches and a
8430 copy of the latest release.
8439 The README has more (and more up-to-date) information. The Index
8440 contains a terse list of what is in the archive.
8442 A WWW home page is also available at http://www.delos.com/cvs.
8444 This Didn't Exist 6/23/1998
8446 Last modified: _6/24/1998_
8448 3. How do I get files out of the archive if I don't have FTP?
8450 Use one of the FTP<->Email servers. These are the ones I've been told
8453 FTPMAIL service is available from the same host as the FTP server
8454 described above. Send mail to "ftpmail@delos.com" containing "help" in
8455 the body of the message. For example, on most Unix systems, you can
8458 echo help | Mail ftpmail@delos.com
8460 The FTPMAIL server will respond with a document describing how to use
8461 the server. If the "Mail" command doesn't exist on your system, try
8462 "mailx", "/usr/ucb/mail" or "/bin/mail".
8464 If you are on BITNET, use Princeton's BITFTP server. Type
8466 echo 'send help' | Mail bitftp@pucc.princeton.edu
8468 (It is likely that only BITNET addresses can use this one.)
8470 Other possibilities I've heard of from the net: (Try the one closest
8473 ftpmail@decwrl.dec.com ftpmail@sunsite.unc.edu ftpmail@cs.arizona.edu
8474 ftpmail@cs.uow.edu.au ftpmail@doc.ic.ac.uk
8476 Last modified: _6/13/1997_
8478 4. How do I get a copy of the latest version of CVS?
8480 The latest released version of CVS and all the programs it depends on
8481 should be available through anonymous FTP on any FSF archive. The main
8482 FSF archive is at "prep.ai.mit.edu". There are mirrors of the FSF
8483 archive on UUNET and other large Internet sites.
8485 Program(s) Suggested revision
8486 ----------- -----------------------
8488 RCS 5.7 (latest version available today)
8489 GNU diff 2.7 (or later) [contained in diffutils-2.7]
8490 GDBM 1.5 (or later) [optional]
8492 The GNU version of diff is suggested by both the RCS and CVS
8493 configuration instructions because it works better than the standard
8496 It is a good idea not to accept the versions of CVS, RCS or diff you
8497 find lying on your system unless you have checked out their
8498 provenance. Using inconsistent collections of tools can cause you more
8499 trouble than you can probably afford.
8501 The FTP archive mentioned above should contain the latest official
8502 release of CVS, some official and unofficial patches and possibly
8503 complete patched versions of CVS in use somewhere.
8505 Last modified: _6/13/1997_
8507 5. Is there a mailing list devoted to CVS? How do I find it?
8509 An Internet mailing list named "info-cvs" grew out of the private
8510 mailing list used by the CVS 1.3 alpha testers in early 1992.
8511 Throughout 1994, the list received an average of 100 messages per
8514 You can add yourself to the mailing list by sending an Email message
8517 info-cvs-request@prep.ai.mit.edu
8519 (Don't forget the "-request" or you'll send a message to the whole
8520 list, some of whom are capable of remote execution.)
8522 Mail to the whole list should be sent to:
8524 info-cvs@prep.ai.mit.edu
8526 An archive of the mailing list is maintained in the FTP archive
8529 Last modified: _6/13/1997_
8531 6. What happened to the CVS Usenet newsgroup I heard about?
8534 A Usenet newsgroup named "gnu.cvs.info" was announced in April
8535 1993, with an expected creation date of August, 1993. However,
8536 nothing came of this.
8538 If you want to discuss CVS on usenet, the correct group is
8539 comp.software.config-mgmt (which also covers other configuration
8540 management systems). Someday it might be possible to create a
8541 comp.software.config-mgmt.cvs, but only if there is sufficient
8542 CVS traffic on comp.software.config-mgmt.
8546 Last modified: _9/6/1997_
8547 _________________________________________________________________
8549 [Add an answer to this category]
8552 _________________________________________________________________
8554 _Search the FAQ-O-Matic:_ ____________________ Search
8555 [matching all words]
8556 Or look for questions modified in the last: [7.] Days
8557 _________________________________________________________________
8559 The FAQ-O-Matic lives at http://gille.loria.fr:7000/cgi-bin/faqomatic.
8560 The code was written by Jon Howell, and the content by folks from all
8562 _________________________________________________________________