1 -------------------------------------------------------------------------------
3 CVS is Copyright (C) 1989-2005 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.
28 In 2004, Dr. Pascal Molli's FAQ-O-Matic was decommissioned.
30 The answers which are dated "6/13/1997" below are really from the 1995
31 FAQ, for the most part. Many of them are out of date. The current FAQ may
32 be found at <http://ximbiot.com/cvs/wiki/index.php?title=CVS_FAQ>. If you have
33 some time, you are encouraged to export that FAQ as text and import it here.
34 If you don't have such time, take the answers in this file with at least a few
37 Since August, 2005, many of the existing CVS resources have been centralized on
38 <http://cvs.nongnu.org> & <http://ximbiot.com>.
40 Category: /, all questions
48 This is FAQ-O-Matic, a quick-and-dirty Perl hack (aren't they all?) by
51 It seems like most FAQ maintainers make a valiant initial effort, then get
52 a life and don't have time to keep their FAQs up to date. Also, I often
53 find out a solution to a problem, and feel like I could write a single
54 FAQ answer on it in a few minutes, but where to post it?
56 Thus the FAQ-O-Matic was born. FAQ-O-Matic is a couple sleazy Perl scripts
57 that allow people to submit FAQ answers to this database, so it can stay
58 current, with just a tiny bit of work on any one person's part.
60 Yes, a bad guy could come along and wipe out all the FAQ entries. Please don't.
61 But to give the good guys some measure of comfort, each submission is stored
62 in an RCS file, so if someone does tamper, we can recover the database.
64 Guidelines for submissions:
66 1. Please _try to be fairly unbiased in matters of opinion._ Mailing lists are
67 the place to start flame wars (just kidding :v), but definitely not here.
69 2. Please _use HTML only conservatively_ in your entries. Links are appropriate
71 but put the URL in the plaintext also so it's useable on printed versions of
72 the FAQ. Inline images pointing off this site are inappropriate, as is much
73 fancy formatting. This is meant to be bandwidth-light and dumb-browser-friendly
76 3. If you feel there's a place for a _new category, or a reorganization of
77 existing questions_, send e-mail to bug-cvs@nongnu.org.
79 4. Please _leave an email address_ at the bottom of your submission so that oth
83 5. _If you only have a question_, not an answer, you should probably post
84 it to a mailing list, not here. If there are frequently asked questions to whic
86 the answer is not forthcoming on mailing lists (or perhaps there's no
87 useful answer yet other than "no one knows"), then it's appropriate to
88 post here, in hopes that someone will see it and know the answer.
90 6. Please refrain from crude or inconsiderate language. Please don't use
91 this as a forum for advertising. However, mention of worthy commercial
92 products is certainly appropriate (even if you sell said product). Just
95 Last modified: _6/13/1997_
97 2. Adding a new category ?
99 try to get bug-cvs@nongnu.org to help you.
102 Last modified: _12/09/2004_
104 Category: /Advanced_Topics_/
108 Category: /Advanced_Topics_/Branching_and_Mergin/
110 " + Branching and Merging"
114 Unfortunately, the word "branch" is an overloaded technical
115 term. It is used in too many different ways in three
116 categories. It might help to understand some of the issues by
117 going through the categories:
119 How Humans use the word "branch":
121 Most development starts with everyone working on the same
122 software, making changes and heading toward a single goal. This
123 is called something like "Main Line Development". Note that
124 though many people do main line development on CVS's "Main
125 Branch", that is a choice, not a requirement.
127 After a release or when one or more developers want to go off
128 and work on some project for a while, the Software Engineers
129 assigned to deal with large software issues generate a "Branch
130 in Development" to support the release or project. (Keep in
131 mind that a programmer is no more a Software Engineer than a
132 carpenter is a Civil Engineer.)
134 Essentially, the word "branch" implies a way to allow
135 simultaneous development on the same files by multiple people.
137 The above terms are human-oriented. They refer to actions that
138 people would like to take. They do *not* imply any particular
139 implementation or set of procedures. Branches in development
140 can be supported in many different ways.
142 How CVS uses the word "branch":
144 CVS uses the word "branch" in a number of ways. The two most
147 - The vendor branch holds releases from (normally) an outside
148 software vendor. It is implemented using a specific RCS branch
151 - The "Main Branch", which normally holds your "Main Line
152 Development", but is defined as the collection of revisions you
153 get when you "checkout" something fresh, or when you use the
154 '-A' option to "update".
156 Important Note: The CVS "Main Branch" is *not* the same as the
157 RCS concept with the same name. If you are using Vendor
158 Branches, files you have never changed are on three branches at
161 - The RCS 1.1.1 branch.
162 - The CVS Vendor branch.
163 - The CVS "Main Branch".
165 The concepts overlap, but they are not equivalent.
167 In referring to CVS, "branch" can be used in four other ways:
169 - A CVS working directory satisfies the definition of "branch"
170 for a single developer -- you are on a private "virtual branch"
171 that does not appear in any of the RCS files or the CVS control
174 - The CVS "default branch" is the Repository source for the
175 collection of files in your working directory. It is *not* the
176 same as the RCS "default branch". Normally the CVS default
177 branch is the same as the CVS Main branch. If you use the "-r
178 <branch_tag>" option to the "checkout" command, you will record
179 a "sticky" tag that changes your default branch to the one you
182 - A "magic" branch can be a branch that hasn't happened yet. It
183 is implemented by a special tag you can check out that is not
184 attached to a real RCS branch. When you commit a file to a
185 magic branch, the branch becomes real (i.e. a physical RCS
188 - And, of course, CVS uses "branch" to indicate a
189 human-oriented "branch in development".
191 How RCS uses the word "branch":
193 - The RCS "Main Branch" (Synonym: "The Trunk") contains a
194 series of two-part revision numbers separated by a single '.'
195 (e.g. 1.2). It is treated specially and is the initial default
196 branch. (The default default?)
198 - The RCS "Default" branch starts out attached to the RCS "Main
199 Branch". For RCS purposes, it can be changed to point to any
200 branch. Within CVS, you *must*not* alter the RCS default
201 branch. It is used to support the CVS idea of a "Main Branch"
202 and it must either point to the RCS Main Branch, or the Vendor
203 Branch (1.1.1) if you haven't made any changes to the file
204 since you executed "import".
206 Last modified: _6/13/1997_
208 2. Why (or when) would I want to create a branch?
210 Remember that you can think of your working directory as a "branch for
211 one". You can consider yourself to be on a branch all the time because
212 you can work without interfering with others until your project (big
215 The four major situations when you should create a branch:
217 When you expect to take a long time or make a large set of changes
218 that the merging process will be difficult. Both "long" and "large"
219 are defined in your own environment.
221 When you want to be able to "commit" and "tag" your work repeatedly
222 without affecting others.
224 If you ever think you need Source Control for your own work, but don't
225 want your changes to affect others, create a private branch. (Put your
226 username in the branch tag, to make it obvious that it is private.)
228 When you need to share code among a group of developers, but not the
229 whole development organization working on the files.
231 Rather than trying to share a working directory, you can move onto a
232 branch and share your work with others by "committing" your work onto
233 the branch. Developers not working on the branch won't see your work
234 unless they switch to your branch or explicitly merge your branch into
237 When you need to make minor changes to a released system.
239 Normally a "release" is labeled by a branch tag, allowing later work
240 on the released files. If the release is labeled by a non-branch tag,
241 it is easy to add a branch tag to a previously tagged module with the
242 "rtag" command. If the release is not tagged, you made a mistake.
243 Recovery requires identifying all revisions involved in the release
244 and adding a tag to them.
246 Last modified: _6/13/1997_
248 3. How do I create and checkout a branch?
252 Attach a non-branch tag to all the revisions you want to branch
253 from. (i.e. the branch point revisions)
255 When you decide you really need a branch, attach a branch tag to the
256 same revisions marked by the non-branch tag.
258 "Checkout" or "update" your working directory onto the branch.
260 Suggested procedure when using modules:
262 cvs rtag <branch_point_tag> module
264 cvs rtag -b -r <branch_point_tag> <branch_tag> <module>
266 cvs checkout -r <branch_tag> module
268 Suggested procedure when using your working directory, which
269 contains the revisions of your working files you want to branch from:
271 cvs tag <branch_point_tag>
273 cvs rtag -b -r <branch_point_tag> <branch_tag> <module>
275 cvs update -r <branch_tag>
277 In each procedure above, Step #1 applies a non-branch tag to all the
278 branch point revisions in the module/directory. Though this is not
279 strictly necessary, if you don't add a non-branch tag to the revisions
280 you branch from, you won't be able to refer to the branch point in the
283 Between steps 1 & 2 you may commit changes. The result would be same
284 because "rtag -r <oldtag> <newtag>" applies <newtag> to the same
285 revision that <oldtag> is attached to. You can use this technique to
286 avoid attaching *any* branch tags until you need them.
288 Step B.2 has two corollaries:
290 If you plan to create the branch tag before committing anything in
291 your working directory, you can use "cvs tag -b <branch_tag>" instead
292 of the "rtag" command.
294 The <module> can be a relative path to a directory from which your
295 working directory was checked out.
297 If you have trouble figuring out what <module> to use (or pathname to
298 use in its place), you can aim it at whatever parent directories you
299 believe will cover all your work.
301 If you are sure the <branch_tag> is not being used anywhere else, you
302 can even aim it at the whole Repository ($CVSROOT), if you have to. It
303 might take some extra time, but assuming that your <tag> is a unique
304 string and you don't use the '-f' option to "rtag -r", "rtag" will
305 only add a <tag> to files in which it actually *finds* the earlier
308 In each procedure above, Step #3 may occur any time after step 2.
309 Unless you explicitly remove them with "tag -d", a <tag> is permanent.
311 The <branch_tag> is an unusual creature. It labels a branch in a way
312 that allows you to "checkout" the branch, to "commit" files to the end
313 of the branch and to refer to the end of the branch. It does not label
314 the base of the branch (the branch point).
316 There are two obvious ways to choose the <branch_point_tag> and
317 <branch_tag> names. But keep in mind that the <branch_tag> is typed by
318 any developer who wants to work on the branch -- you should make it
319 mean something to them.
321 Style #1 presumes that the simple version string refers to a set of
322 designed, documented or promised features, not to a specific set of
323 files. In this case, you tag the branch with the generic Version
324 string and assume that whenever you refer to "Version", you want the
325 "latest" set of files associated with that Version, including all
326 patches. (You can substitute whatever you like for "bp_", as long as
327 your <branch_point_tag> is some modification of the <branch_tag>.)
329 <branch_point_tag> Matching <branch_tag>
332 bp_Release2-3-5 Release2-3-5
333 bp_Production4_5 Release4_5
335 Style #2 presumes that the simple version string refers to the
336 specific set of files used to construct the first release of
337 "version". In this case, you tag the branch-point revisions with the
338 generic Version string and assume that whenever you refer to this
339 Version, you want the original set of released revisions. To get the
340 latest patched revisions of the release, you refer to the branch tag
341 "latest_<branch_point_tag>". (You can substitute what ever you like
342 for "latest_", as long as your <branch_tag> is some modification of
343 the <branch_point_tag>.)
345 <branch_point_tag> Matching <branch_tag>
348 Release2-3-5 latest_Release2-3-5
349 Release4_5 latest_Production4_5
351 In both styles you can find out what you had to change since the
352 original release of this Version by typing:
354 cvs diff -r <branch_point_tag> -r <branch_tag>
356 For Style 1, this is:
358 cvs diff -r bp_<branch_tag> -r <branch_tag>
360 For Style 2, this is:
362 cvs diff -r <branch_point_tag> -r latest_<branch_point_tag>
364 Notes on "being on a branch":
366 - "update -r <tag>" tells CVS to attach a "sticky tag" to working
367 directory (in ./CVS/Tag) and the checked-out files (on each line of
370 - A "sticky" <tag> (including a <branch_tag>) causes most CVS commands
371 to act as if "-r <tag>" were on the command line.
373 - A "sticky" <branch_tag> indicates that the working directory (and
374 working files) are "on the branch".
376 Last modified: _6/13/1997_
378 4. Once created, how do I manage a branch?
380 The most important thing you should know about managing a branch is
381 that the creation of a branch is not a lightweight act. When you
382 create a branch, you must also create a set of procedures to keep
385 Specifically, you must:
387 - Remember that the branch exists. (This is non-trivial if you create
390 - Plan when to merge it back into the main line of development.
392 - Schedule the order that multiple branch merges are to be done.
394 - If you ever intend to merge branches into each other, instead of
395 limiting merges of branch work back into the "main line", you must
396 keep careful track of which parts of which branches have merged into
397 which other branches.
399 The simplest way to deal with branches is to limit their number,
400 "collapse" them back into the main line as quickly as is reasonable
401 and forget them. If a group wants to continue working, tell them to
402 create another branch off the fully merged main line.
404 Remember that CVS is just a tool. Over time, it will probably handle
405 branching better, requiring less careful attendance. But no matter how
406 good it becomes, the whole idea of "branching" is a complicated
407 management problem. Don't take it lightly.
409 Last modified: _6/13/1997_
411 5. Are there any extra issues in managing multiple branches?
413 If you plan to split from the "main line" and merge back after a time,
414 the only problem will be scheduling the order of branch merges. As
415 each branch is merged, the main line must be rebuilt and tested.
416 Merging multiple branches (i.e. "lines of development") before
417 building and testing creates more problems than you are ready for.
419 If you plan to collapse some branches into others, then move the
420 combined branches back into the main line, you have to be careful with
421 the revisions and tags you hand to your "update -j" command, but it
422 shouldn't be much trouble.
424 If you plan to allow every branch to incrementally take the work done
425 on other branches, you are creating an almost insurmountable
426 bookkeeping problem. Every developer will say "Hey, I can handle
427 taking just this little bit," but for the system as a whole it is
428 disaster. Try it once and see. If you are forced into this situation,
429 you will need to keep track of the beginning and end points of every
430 merge ever done. Good Luck.
432 Last modified: _6/13/1997_
434 6. How do I merge a whole branch back into the trunk?
436 If you don't have a working directory, you can checkout and merge in
439 cvs checkout -j <branch_tag> <module>
442 If you already have a working directory:
444 cd <working_directory>
445 cvs update <== Optional, to bring it up to date.
446 cvs update -j <branch_tag>
448 CVS will print lines beginning with
450 'U' for files that you hadn't changed, but the branch did.
452 'M' for files that you changed and the branch didn't
453 *and* for files that you both changed that were merged
454 without overlaps. (This overload is unfortunate.)
456 'C' for files that you both changed in a way that conflicts
459 You need to go edit all the 'C' files and clean up the conflicts. Then
460 you must commit them.
462 Last modified: _6/13/1997_
464 7. How do I merge changes from the trunk into my branch or between
467 The idea is similar to the above, but since CVS doesn't treat the main
468 branch like other branches, you'll have to be more careful. There are
469 5 different ways to look at the problem.
471 The way to merge *all* changes made on the trunk into a working
472 branch is to move to the branch you want via "checkout -r" or "update
475 cvs update -r <branch_tag> {optional files}
477 Then merge the changes from the trunk into your working branch using
478 the pseudo-tag named "HEAD":
480 cvs up -j HEAD {optional files}
482 You will get everything from the branch point of the branch named
483 <branch_tag> up to the HEAD of the main branch. This is still kind of
484 strange. If the file is on a branch, HEAD should be the latest thing
485 on the branch, not the HEAD of MAIN. But that's not the way CVS
488 If you run "cvs up -j HEAD" again after adding more revisions to the
489 trunk, you may get overlaps for the text you have already merged. It
490 depends on your version of your RCS "merge" command (actually the "co
491 -j" option, which depends on the version of "diff3" you configured RCS
494 You can merge the difference between any two <tags> using two "-j"
495 options on "update" or "checkout".
497 Identify the two tags on the branch you want to merge from.
499 cvs update -j <tag1> -j <tag2> {optional files}
501 This step assumes you were careful about tagging milestones. You can
502 use this technique for any two <tags> on the same branch, even the
503 trunk. It is also possible to use tags on different branches, but
504 you'll have to ponder the meaning of the difference between those two
507 In place of one of the <tags>, you can use a <branch_tag> to refer to
508 the latest revision on that branch. See 4C.11 and 4C.3 for info on
511 Merges can also be performed by handing RCS revisions to the '-j'
512 options, but since revision numbers aren't the same in all files,
513 merging by number is normally limited to one file. Sets of files with
514 the exact same trees of branches and revision numbers would work too,
515 but that's a rare situation.
517 To "take" revisions from other branches instead of merging them, see
520 A way to gain the effect of merging the main to the branch is to
521 merge the branch into the main using the normal
523 cvs update -A {optional files}
524 cvs update -j <branch_tag> {optional files}
526 cvs tag -F -b <same_branch_tag> {optional files}
532 This also works, but is probably not officially supported:
534 cvs update -j N {optional files}
536 where N is a number. This will merge all the changes from the branch
537 point up to the highest revision on the main branch starting with N.
538 For example, if your highest trunk revision is 1.52, you can use this
539 to grab revisions from the trunk:
541 cvs update -j 1 {optional files}
543 Another example: Say you have a branch point at rev 1.2 for a branch
544 named "BR1" and trunk revisions 1.3, 1.4, 2.1, 2.2, 2.3, 3.1, 3.2.
547 cvs update -j 1 {optional files}
549 will merge the changes from 1.2 to 1.4
551 cvs update -j 2 {optional files}
553 will merge the changes from 1.2 to 2.3
555 cvs update -j 3 {optional files}
557 will merge the changes from 1.2 to 3.2, which in this example, is
558 equivalent to the use of "-j HEAD" in part A above.
560 The intuitive (at least to me):
562 cvs up -j MAIN (or TRUNK) {optional files}
564 doesn't work. If the trunk (i.e. "main branch") had an implicit branch
565 named "MAIN", you could use:
567 cvs up -j MAIN:10/26 -j MAIN:now {optional files}
569 and refer to date-stamped revisions on the trunk using the
570 <branch_tag>:<date> support that works on other branches.
572 You might also think you could place an explicit tag on branch 1 (or
573 higher) (e.g. MAINHACK:1) and use it in place of the implicit "MAIN",
574 but I haven't found the right combination.
576 [[If you find working techniques, I'll add them here.]]
578 Last modified: _6/13/1997_
580 8. How do I merge onto the Main Branch a file that exists only on a branch
581 other than the Main Branch? (i.e. it is in the Attic)
583 For how such a file can exist, see 3A.2 and 3A.3.
585 For how to avoid creating such a file, see 3A.5.
587 Though you might think that the "update -j" command could perform the
588 "merge" of a file from the side branch to the Main Branch, it isn't
589 (yet) smart enough. Unfortunately, there is no single CVS command to
590 do this -- it takes three steps:
592 To move something onto the Main Branch from the Attic, you have to
593 physically move the file from the Attic to the main Repository
594 directory associated with your working directory.
596 It is exactly like resurrecting a removed file. See 3L.4
598 I use something like this: (csh-like syntax)
600 set repos = `cat ./CVS/Repository` mv $repos/Attic/filename,v
603 (If you use relative paths in your Repository files, that first line
604 becomes: set repos = $CVSROOT/`cat ./CVS/Repository`)
606 Now that the file is physically in the right place within the
607 Repository, "update -A" will make it appear in your working directory
608 on the Main Branch. Do that now.
610 You now have a choice. The act of physically moving the file has
611 fused together the <branch_tag> branch and the Main Branch for this
612 file. You can continue that way, making changes along the RCS Main
613 Branch which CVS will (for this type of file only) treat as both the
614 Main Branch and the <branch_tag> branch.
616 The other choice, which I would suggest, is to re-tag the file with
617 <branch_tag>, restoring a normal-looking magic branch tag to the file:
619 cvs tag -F -b <branch_tag> <file>
621 After you have done the above, you can run "update -A" or "update -r
622 <branch_tag>" to resume whatever you were doing before you started
625 Caveat: The final result is a file whose revision tree doesn't look
626 like it was ever on any branch but the Main Branch until the above
627 "tag -F -b" command was executed. CVS and RCS have no way of saving
628 the history of the actions you have just performed.
630 Last modified: _6/13/1997_
632 9. How do I know what branch I'm (working) on?
637 and look at the "Sticky Tag" field for each file. If:
639 The *same* tag is on *every* file in your working tree, *and*
641 That tag matches the contents of the ./CVS/Tag file, *and*
643 That tag is a branch tag,
645 then you know what branch you are working on. You can get sticky Tag
646 information directly from the ./CVS/Entries file instead of "cvs
649 If all the sticky Tags don't agree, then your directory is temporarily
650 inconsistent. This is a feature allowing you to make changes (or
651 perform merges) to individual files on multiple branches without
652 checking out the whole directory.
654 The sticky Tag on each file in the ./CVS/Entries file (as displayed by
655 the "status" command) indicates what branch the working file is on.
656 New files are added to the Tag stored in ./CVS/Tag.
658 To force your entire working directory onto the same branch, type:
660 cvs update -r <branch_tag>
662 Last modified: _6/13/1997_
664 10. Do I really have to know the name of the branch I'm working on?
666 If a developer can't be relied on to know what branch of development
667 to work on, then either the developer's manager isn't planning
668 branches properly or the developer has serious problems.
670 I have found that one of the hardest concepts to get across to
671 developers (and some managers) is that "a branch in development" (as
672 opposed to the use of RCS branches to support some other scheme) is a
673 heavyweight act. Every time you create a real branch in development,
674 you must spawn a set of managerial procedures and a schedule by which
675 you plan to merge each branch into each other branch. Unless you plan
676 to keep it simple and collapse (by merging and forgetting) branches
677 quickly, they are not to be created lightly.
679 In other words, if you don't regularly attend group meetings in which
680 the branch to be worked on is a major topic of discussion, then the
681 group is not managing branches properly.
683 We created a couple major branches a few months ago and even the
684 customer service people refer to the "XYZ branch" as a shorthand for
685 "continuing development on the XYZ project".
687 Last modified: _6/13/1997_
689 11. How do I refer to the revision where I branched so I can see what
690 changed since the Branch Point on another branch?
692 Given the current <branch_tag> format, there is no direct way to refer
693 to the branch point, which is more useful in many ways than referring
694 to the branch, which always refers to the latest revision on the
697 When CVS adds a branch tag, it attaches an RCS symbol to a
698 non-existent revision number containing the revision number of the
699 branch point as a prefix. (See Section 3O, on the "tag" command.) RCS
700 can't use the CVS magic branch tag and many of the CVS commands can't
703 To be certain of your ability to refer to a branch point, you must
704 create a "branch point" tag at the same time as the Branch tag. See
707 Last modified: _6/13/1997_
709 12. Why didn't the command "cvs admin -bBRANCH1 *" create a branch?
711 Because your command creates an RCS branch, not a CVS branch. See the
712 above discussion on branches. RCS branches are used to support CVS
713 branches, but they are not the same. You can't act as if you have
714 direct control over the RCS files.
716 The "admin" command was placed there as a convenience to allow you to
717 execute raw "rcs" commands on the Repository, taking advantage of
718 CVS's ability to find the files in the Repository.
720 But you have to remember that you are using RCS commands on a CVS
721 Repository, which is not generally safe unless you know exactly what
724 For one thing, CVS insists on control of the default branch. It is set
725 either to the Main branch or the Vendor branch depending on whether
726 you have changed the Vendor's code. If you change the default branch,
727 you are monkeying with the internals and you will get unexpected
730 To set your "default CVS branch" to BRANCH1, you must use "checkout"
731 or "update" with the "-r BRANCH1" option. Then you have changed CVS's
732 idea of your "default branch", which has little to do with RCS's
735 Last modified: _6/13/1997_
737 13. Is it possible to set the "default CVS branch" for everyone?
739 No. It doesn't work that way.
741 When using CVS, all administrative information (such as what branch
742 you checked out) is stored in CVS sub-directories, local to the user.
743 There is no global state, other than the description and logging files
744 in the $CVSROOT/CVSROOT directory.
746 You tell "checkout" or "update" what branch you want to check out via
747 the "-r <tag>" option. The default is CVS's "Main Branch".
749 I don't see a problem in *designing* a new way to indicate what branch
750 you get by default, instead of the main one, but that's not how it
753 Last modified: _6/13/1997_
755 14. How do I perform a large merge?
757 Large merges require a bit more planning to be able to track what has
758 happened in the inevitable cases where something goes wrong. No tool
759 can force a "merge" to make perfect sense.
761 Though you can handle the details in many different ways, the two ends
762 of the spectrum of merge techniques are: gonzo and paranoid.
764 The gonzo method assumes that you know everything about your sources
765 so that recovery from failures is "just a matter of typing." You
766 created the branch this way:
768 cvs checkout <module>
770 cvs tag -b <branch_tag>
771 cvs update -r <branch_tag>
773 cvs commit <<== Onto branch
775 Now you want to merge your branch back into the Main branch, you are
776 certain you can make it work, or at least detect all the failures, so
777 you dive in and hack away: (For simplicity, we will assume you are
778 collapsing (i.e. merging and forgetting) a side-branch into the Main
779 branch from your single working directory.)
782 cvs update -j <branch_tag>
783 >>> Edit the 'C' files and remove the overlaps.
784 >>> Edit some more to make it all compile and work.
787 Looks simple. For more details on the output from the "update -j"
788 command, see 3P.2 and 4C.6.
790 Note: You could also checkout a whole new working directory and
791 perform the merge at the same time by replacing the two
792 update commands with these two commands:
794 cvs checkout -j <branch_tag> <module>
797 The paranoid way is more difficult, but it can catch all sorts of
798 problems. You created the branch this way:
800 cvs checkout <module>
802 cvs tag <branch_point_tag>
803 cvs tag -b <branch_tag>
804 cvs update -r <branch_tag>
806 cvs commit <<== Onto branch
808 The extra tag command places a non-branch tag on the Branch Point, an
809 act that makes it easier to do "diffs" later. Now we decide to perform
812 cvs tag <latest_on_branch_tag>
814 *1* cvs diff -r <branch_point_tag> -r <latest_on_branch_tag>
815 >>> *1* shows all the changes on the branch.
816 *2* cvs diff -r <branch_point_tag> -r HEAD
817 >>> *2* shows the changes on the trunk since branching.
818 cvs tag <premerge_tag>
819 cvs update -j <branch_tag>
820 >>> Edit the 'C' files and remove the overlaps.
822 >>> Verify that *3* matches *1*, except for line numbers.
824 cvs tag <just_merge_changes_tag>
825 >>> Edit some more to make it all compile and work.
827 cvs tag <after_merge_cleanup_tag>
829 The reason *3* and *1* match so closely is that they are the
830 differences between two pairs of starting points and ending points
831 after the same data was inserted. If they are significantly different,
832 you will want to figure out why.
834 NOTE: You will have to tell everyone to stay the hell out of the
835 Repository while you do this. If they commit something while you are
836 in the middle of a merge, your job will be much more difficult. If
837 they "update" at the wrong time, their work will be randomized until
838 you finish. It's better to call a halt.
840 See 3H.13 for some more information about dealing with merges after
841 import. The last part of the procedure is applicable to any large
844 Last modified: _6/13/1997_
846 15. Is a Vendor merge any different from a branch merge?
848 No. In most ways, a Vendor branch is exactly the same as any other
849 branch. In a Vendor merge, the data is append to the branch by the
850 "import" command, rather than by hand-editing, but the merge process
853 See the "import" command in section 3H.
855 Last modified: _6/13/1997_
857 16. How do I go back to a previous version of the code on a branch?
862 You can avoid digging into RCS revision numbers (executing "update
863 -r (rev)" on each file) by trying one of these:
865 Use non-branch tags as you normally would. Non-branch tags
866 attach to specific revisions, so a "tag (tag)" command would
867 mark the revisions you have in your working directory, which
868 are on your branch. If you need to retrieve them, use "update
871 Doing this overrides the sticky (branch-tag) attached to your
872 working directory with a non-branch tag, which means you won't
873 be able to commit until you again move forward to the end of
874 the branch with "update -r (branch-tag)".
876 Use the "update -r (branch-tag):(date)" trick.
878 This is almost like using the '-D' option, but it looks for
879 revisions extant on (date) only along the given branch.
881 As in #1, you can't commit to this kind of working area,
882 because it has a sticky date referring to revisions in the
885 [comment from the audience: You are dreaming..
886 this does not work.. try it, you get
887 No such tag: "MYTAG:May 1"
888 or similar. I wish it did because I need it. julian@whistle.com]
891 You can branch a branch.
893 If you add a branch tag to file in a working directory that was
894 checked out on a branch, you will branch the branch. This
895 works just fine, though you'll have to play some games to merge
896 everything back together again. You'll also create 6-part
897 revision numbers. (They'll be 8-part revision numbers if you
898 branch a branch that started out with some unmodified files on
899 the Vendor branch. Think about it. How does revision
900 1.2.4.2.4.2.2.1 grab you?)
903 (fixed formatting, kingdon@cyclic.com)
905 Last modified: _9/8/1997_
907 17. Once I've found the files I want, how do I start changing them? I keep
908 getting warnings about sticky tags.
910 What you probably did was type "cvs update -r <tag>" where <tag> is a
911 non-branch tag. "update" created a sticky tag for a specific revision,
912 not a branch. To start working right there, you have to create a
915 You have two choices.
917 You can do it in place and keep working:
919 cvs tag -b <branch_tag> <<== To tag the current files.
920 cvs update -r <branch_tab> <<== To move onto the branch.
922 You can do it "externally" and create a new working directory:
924 cvs rtag -b -r <tag> <branch_tag> <module>
925 cvs checkout -r <branch_tag> <module>
927 <module> can be a relative path within the Repository.
929 <tag> in the above is the non-branch tag you placed earlier
930 that caused the error in your question. Be warned that
931 if <tag> is not set on all the files (or all the right
932 revisions) you won't get exactly what you wanted.
934 Last modified: _6/13/1997_
936 18. Why do I get the latest files on the branch when I tried to "update -r
939 If "update -r <tag>" always retrieves the latest files on a branch,
940 then <tag> is really a <branch_tag>. A branch tag is supposed to be
941 used to grab a branch to work on. Since you can't modify a file in the
942 middle of a branch, checking out a <branch_tag> will give you the
943 latest revision on the branch.
945 If you want to "checkout" a specific collection of revisions, you must
946 use a "non-branch" tag. See the first part of 4C.16.
948 Last modified: _6/13/1997_
950 19. How can I avoid a merge? I just want to move the latest revision on my
951 working branch directly onto the trunk.
953 There is no direct way to do this using CVS, though the technique is
954 not difficult using shell commands. Here's one way:
956 Move your working directory to the Main Branch.
960 Use "update -p" to grab the latest revision on the branch and write
961 it over your working files. Make sure you don't have an modified files
962 -- you will lose them. The following is in "csh" syntax. Change the
963 wildcard to grab the files you want
965 foreach i (Makefile *.cc *.hh)
966 cvs update -p -r <branch_tag> $i > $i
969 Commit all the working files onto the Main Branch.
971 cvs commit -m 'Moved branch <branch_tag> onto MAIN'
973 You should experiment with the above before blasting everything.
975 Last modified: _6/13/1997_
977 20. How to I avoid merge collisions in the RCS $\Log$ data?
979 In short, you can't. The RCS $\Log$ keyword is handled differently
980 from all other RCS keywords.
982 On the info-cvs mailing list, there is a periodic discussion that goes
985 Question: How do I deal with $\Log$? Answer1: You can't do much with
986 it. Here's how it works. . . Answer2: I've found a limited way to use
987 it. . . Answer3: Get rid of it. $\Log$ is an abomination.
989 I tend to lean toward answer #3. There are only two sets of people who
990 would ever have access to logs stored within sources files, developers
991 and source customers.
995 Log entries within sources files are notoriously incomplete, rushed,
996 poorly phrased and in many cases incorrect, making them useless for
997 debugging or file maintenance. I remember a maxim from "Software
998 Tools" (I believe): "Read the code, not the comments." No managerial
999 order or plan for programmer discipline will affect this in the real
1002 Log entries are usually in an unreadable mixture of styles. Many log
1003 entries are just plain meaningless. Some are foolish. Some are even
1004 insulting. Examples:
1006 "Corrected spelling of misspelling." "Bug fix." "Reversed stupid
1007 change in previous revisions." "If Joe could do his job, this would
1008 already have worked."
1010 Log entries are not managed well by the tools. Any merge can cause
1011 conflicts in the $\Log$ data. Branch merges produce incomplete logs.
1012 They can be edited into chaos and they are not regenerated. They waste
1013 space duplicating information available to the developer with a single
1016 Even if correct when originally entered, as changes are made to the
1017 file, log entries become false over time. Humans are not good at
1018 reading down through a list and remembering only the last change
1019 affecting something. Over time *most* of the log is wrong.
1021 Even if still correct, the log data is almost useless to developers
1022 without the code diffs. If you can get code diffs, you can display the
1025 For source customers the problem is even worse. The last thing you
1026 want to show customers is a hodge-podge of tiny comments about large
1027 changes followed by a series of emergency fixes before delivery. If
1028 you distribute sources, then you should provide documentation, or
1029 changelogs reviewed by people who won't let comments like "Fixed for
1030 stupid customer." out the door.
1032 Conclusion: Though some people would prefer to see in this FAQ
1033 techniques for making the $\Log$ entries the best they can be, I
1034 believe them to be a lost cause. My suggestion is to hunt down, root
1035 out and destroy all occurrences of $\Log$ and the unusable data
1036 attached to it wherever you may find it.
1038 Last modified: _6/13/1997_
1040 21. Why should I trust automatic merges?
1042 Some developers have the feeling that three-way merging doesn't work.
1043 They fear and distrust the way the "update" command automatically
1044 merges committed changes from the Repository into the working file.
1046 Experience has shown that most merges are utterly painless and most of
1047 the rest are easily resolved. The few conflicts that cause headaches
1048 are nearly all due to poor communication between developers, a problem
1049 no source control system can obviate.
1051 Some developers were troubled in the past by flaky Unix software. I
1052 can't say that everything is perfect, but the tools CVS depends on
1053 (RCS and diff, mainly) are fairly solid nowadays. They work.
1055 Since it does seem to work for most of us, the algorithm is unlikely
1056 to change soon. Why not test it on a couple trouble spots and if it
1057 works for you, use it for a while? Then you can make an informed
1060 Last modified: _6/13/1997_
1062 22. How does CVS decide if it can safely perform a merge?
1064 CVS can merge any text file, possibly discovering a conflict and
1065 leaving overlaps for you to edit. Editing the conflict markers out of
1066 the file is a moment's work, but resolving the conflict could take an
1067 arbitrary amount of time. CVS works to determine if it *should* merge,
1070 See 2B.6 for how the merge proceeds.
1072 Last modified: _6/13/1997_
1074 23. After resolving merge conflicts in a file, what if I want to keep my
1075 previous version, and not take any of the branch changes?
1077 If you want to retain your previous version, a version on the MAIN
1078 branch greater than 1.1 (one you committed there), just throw the
1079 merged file away and "cvs update" the file.
1081 You don't need to commit something to remember it. The tags you place
1082 before and after the merge should give all the handles you need to
1083 find various versions. You don't have to create a new version of the
1086 If you want to retain the previous Vendor revision, you can grab a
1087 copy of it using "cvs update -p" and commit it or use the technique
1088 described in 3B.3 to revert back to the Vendor branch.
1090 Last modified: _6/13/1997_
1092 Category: /Advanced_Topics_/Engineering/
1096 1. Where can I find out about Software Engineering?
1098 A couple different people suggested this book:
1100 Software Configuration Management: Coordination for Team Productivity;
1101 Wayne A. Babich; Addison Wesley; 1986; ISBN 0-201-10161-0
1103 A number of others suggested Appendix B of the book "Decline and Fall
1104 of the American Programmer" by Ed Yourdon, called "The Programmer's
1105 Bookshelf". It list 87 books you are expected to have read. Since they
1106 publish many of the books, Prentice-Hall distributes this list as
1107 "Prentice Hall Professional Technical reference PTR-125-AA3.
1109 One interesting item from the Yourdon book: The total number of
1110 professional computer books sold is less than the number of
1111 programmers currently in the United States. It wasn't clear from the
1112 book whether this meant "per year" or not, but it is still
1115 Last modified: _6/13/1997_
1117 2. How do I flexibly arrange the modules file to describe my sources?
1119 An equivalent question might be, "How do I structure my sources?" This
1120 can be a difficult question especially in the areas that are more
1121 political than technical.
1123 Generally you want to think about which pieces of your system need to
1124 be checked out together, built as one system or tagged as a consistent
1125 whole. You should certainly create module names that correspond to
1126 complete, buildable collections that you would tag and release as one
1127 "product". It is also convenient to create module names for small
1128 sections of the Repository containing files that will all be worked on
1129 at the same time by the same person or group.
1131 Once you have defined the structure of your work, you can usually see
1132 how to lay it out in a Repository. After that the modules file is
1133 easy. You set up module names and aliases to match what you need to
1134 check out by name. If you like relative directories, it is possible,
1135 but not recommended, to work completely without a modules file. See
1136 1D.11 and 2C.7 for some info about the modules file.
1138 Here are a few types of modules. You should experiment to see what
1139 kind of structure each of these produces. They all have different
1142 Connected projects in one group with two separate helper
1143 directories. The helper directories can contain build tools, header
1144 files, libraries, or whatever you like.
1146 These are all aliases that checkout relative pathnames. The equivalent
1147 results could be produced by placing the selected relative pathnames
1148 on the "cvs checkout" command line.
1153 pr12 -a P1 P2 HELPERS
1154 pr13 -a P1 P3 HELPERS
1155 pr23 -a P2 P3 HELPERS
1160 HELPERS -a group1/helper1 group1/helper2 MAKEFILE
1161 MAKEFILE -a group1/Makefile
1163 Actual Repository directory structure: (from $CVSROOT down)
1165 group1/ Makefile The top level Makefile. helper1/ helper2/ Helper
1166 files and dirs proj1/ Files and dirs proj2/ Files and dirs proj3/
1169 "checkout group1" produces a duplicate of the above. "checkout projX"
1170 produces all but "projY" and "projZ". "checkout projXY" produces all
1173 Here is the exact same set of module names describing the same
1174 Repository layout using module names (and aliases containing module
1175 names) instead of merely aliases for relative pathnames.
1177 There is one difference in the result. The name of the top level
1178 directory in the checked out working tree will match the "module" name
1179 (e.g. pr1) instead of always being "group1" as it was in the first
1182 pr1 group1 proj1 &HELPERS
1183 pr2 group1 proj2 &HELPERS
1184 pr3 group1 proj3 &HELPERS
1185 pr12 group1 proj1 proj2 &HELPERS
1186 pr13 group1 proj1 proj3 &HELPERS
1187 pr23 group1 proj2 proj3 &HELPERS
1189 HELPERS -a helper1 helper2 group1-Makefile
1190 helper1 group1/helper1
1191 helper2 group1/helper2
1192 group1-Makefile -d . group1 Makefile
1194 The above line (with the -d in it) says that when the module named
1195 "group1-Makefile" is checked out, the file named Makefile file will be
1196 found in a directory named $CVSROOT/group1 and will be checked out
1197 into a directory named '.', which obviously already exists.
1199 The & references say to interpret those pathnames relative to the
1200 directory where the whole module is stored. For the "pr1" module, that
1201 directory is "group1", so the &HELPERS reference winds up placing
1202 Makefile in '.' relative to "group1".
1204 A short one containing the basic "module" actions:
1206 m1 head/path file1 dir2 file3 dir4 file5
1208 When checked out, a directory named "m1" appears in your current
1209 directory. Elements named file1, dir2, file3, dir4, and file5 appear
1210 in it. They were originally taken as relative paths from
1213 Here's another way to construct a working directory out of pieces of
1216 projX projX Makefile &projX_inc &projX_src &projX_doc
1218 # The first line selects a single file within projX, plus
1219 # the contents of three other modules. Those three other
1220 # modules rename their directories.
1222 projX_inc -d include projX/inc projX_src -d source projX/src projX_doc
1223 -d documentation projX/doc
1225 A Unix tree. This is similar to what CVS was developed for and the
1226 way I have used it for years.
1233 usr-bin unix/usr.bin
1235 # Subdirs of top level dirs. (tiny subset)
1240 # Programs without subdirs. (tiny subset)
1241 cat unix/bin Makefile cat.c
1242 uniq unix/usr.bin Makefile uniq.c
1247 public localsrc/public
1251 cvs localsrc/gnu/cvs
1252 emacs localsrc/gnu/emacs
1253 rcs localsrc/gnu/rcs
1254 btoa localsrc/public/btoa
1255 tcsh localsrc/public/tcsh
1257 # X11 related items.
1258 tvtwm localsrc/X11/contrib/tvtwm
1260 "unix" was checked out and built from the top down, using a set of
1261 Makefiles that knew about the whole structure. "localsrc" was kept
1262 checked out in /usr/local/src.
1264 At any time I could run "checkout ls" or "checkout cat" and get a
1265 simple directory with only that tool in it, plus a subset Makefile
1266 that knew how to build that tool against the installed (or alternate,
1267 via environment variables) headers and libraries.
1269 I found it very handy to be able to run "ls" and see the three tools I
1270 was porting that week.
1272 Last modified: _6/13/1997_
1274 3. Can I have multiple source repositories, one for each project?
1276 Yes, you can have as many Repositories as you like. But each
1277 Repository must be managed separately, creating additional work.
1279 Question 4A.1 provides a short description of setting up a single
1280 Repository. A few additional considerations:
1282 It is a good idea to start by creating a single Repository and split
1283 it up (or create additional Repositories) only if you believe it is
1284 really necessary. I would only create a new Repository if the data is
1285 completely disconnected from the rest of the main Repository.
1287 If there is a lot of overlap among the developers working on the
1288 collections of files you want to place in different Repositories, or
1289 if there is any connection between those collections, I would go out
1290 of my way to create a single Repository. It is much easier to manage.
1292 Disk space should not be a factor since you can build up a
1293 Repository using symbolic links and/or remote mounts.
1295 Each Repository is completely distinct. You can't check out modules
1296 from different Repositories at the same time. A better way of looking
1297 at it is that if you *can* check out two modules or directories with a
1298 single "checkout" command (without contortions or explicit absolute
1299 pathnames), then they are in the same Repository.
1301 To "checkout" modules from multiple Repositories, you must use the
1302 "cvs -d" option on all CVS commands or alter your $CVSROOT variable
1303 when you change focus to another Repository. If you work with multiple
1304 Repositories, it is a good idea to configure CVS to use absolute
1305 pathnames in the ./CVS/Repository file, since most commands (other
1306 than "checkout") will use that file rather than $CVSROOT.
1308 If you configure CVS to use relative pathnames in your
1309 ./CVS/Repository files, you must always be careful to set your
1310 $CVSROOT properly or you will get unexpected results.
1312 If you have two modules or directories by the same name at the same
1313 relative path inside two different Repositories, you are asking for
1314 disaster. You could unexpectedly update a directory with completely
1315 unrelated files. This is not a fanciful example -- a Repository is
1316 occasionally duplicated for release purposes in which case *all* the
1317 paths in the two Repositories are the same.
1319 Last modified: _6/13/1997_
1321 4. Who should administer the Repository and manage the modules file?
1323 This is a "management style" question. In large or traditional groups,
1324 the CVS procedures are warped to conform to local conventions. In
1325 small groups, in groups with strong personalities or on new projects
1326 the choice of source control procedures can help create some of the
1327 working environment. Here is a taxonomy of environments I have worked
1328 in or helped set up:
1332 A small number of competent developers working on a medium size
1333 project. We all got along and we all respected each other (at least
1334 technically). Anyone edited anything.
1336 Modules and Repository admin was mostly left to me. I never found a
1337 problem in minor changes made by anyone else.
1341 A large number of experienced developers sprinkled with wackos. Many
1342 of the developers didn't want to deal with any kind of source control.
1343 They wanted a full-service source control system that caused them zero
1346 I learned "big stick" diplomacy here. There was a small number of
1347 "designated" (by me) people who were allowed to do *anything* other
1348 than "update" and "commit". Even "checkouts" were controlled. This is
1349 where I found "history" and "release" the most useful.
1353 A small number of developers who wanted me to "help", but who didn't
1354 want to deal with anything other than their favorite algorithms.
1356 I didn't have the time to baby-sit this group, so I designated one of
1357 them to be my official contact and made him do it all. He felt sullied
1358 by the requirement to pay attention to anything other than his pet
1359 coding projects, but enjoyed the "status" of being the only one who
1360 could touch the control files without my kicking the chair out from
1365 A huge number of developers of covering the whole spectrum of
1366 competence and experience split into 20 groups, none of which
1367 cooperated with the others, working on 57 different projects, most of
1368 which didn't inter-operate.
1370 Managing it in any coherent way was not my responsibility (and beyond
1371 my tolerance for chaos). Too many people. So I privately designated a
1372 person in each group to be the contact and kept watch on the
1373 Repository activity. When something went wrong, I notified the contact
1374 for the group and told him what was happening and *he* kept his troops
1375 in line. They were tougher with their own group that I would have
1378 Eventually only a few people were willing to touch the control files,
1379 since they were flamed from all directions if they screwed up.
1383 In a medium group of really *serious*, and seriously overworked,
1384 people, someone else was designated the "master". I convinced the
1385 master I knew what I was doing and went on my way.
1387 No one else in the world was allowed to touch anything.
1391 In a large amorphous group of beginners, experts and clowns, over whom
1392 no one had official control, I was forced to employ a group of
1393 relative beginners (who became experts rather quickly) to police the
1394 world. The ultimate in locking the barn after the horse was stolen, we
1395 kept Chaos from destroying us only by use of superior firepower.
1397 My choice, if allowed, is to let anyone touch anything. I keep backups
1398 of important items and let people know individually whether I want
1399 them to touch things or not. If someone on my "no touch" list touches
1400 and succeeds, they are allowed more slack. If they screw up after
1401 being warned, their screwup becomes public. After a few months, I
1402 usually have no trouble keeping the world running smoothly, at least
1403 from my (and CVS's) perspective.
1405 Last modified: _6/13/1997_
1407 5. Isn't disk space a big factor? CVS copies files out of the Repository,
1408 duplicating everything.
1410 Everyone knows that disk space is getting cheaper. How do we reconcile
1411 this with the equally well-known problem that *all* disk is *always*
1414 In my opinion, the main reason disk space will never be an unlimited
1415 resource is that it is the major variable in organizational time/space
1416 tradeoffs. It isn't a problem of waste or an aspect of Murphy's law,
1417 as some claim it is, but rather a direct consequence of good
1418 management. Disk space is, and will always be, a limited resource.
1420 First, the cost of *deploying* that disk is not dropping as fast as
1421 the cost of the storage medium. The cost of machines to hold the disks
1422 and the networks to connect them are dropping more slowly than disk
1423 media. And the cost of the human time necessary to manage the
1424 machines, networks, disks, and the developers using them, is not
1425 dropping at all. The cost of human time continues to rise.
1427 If management decides that expensive human time can be saved by using
1428 all that new disk space to keep the last three releases online, then
1429 that's what it will be used for. If each release takes up a Gigabyte
1430 and you support 30 platforms, a simple time-saving suggestion has just
1431 grabbed 100 Gigabytes of disk space. And we've ignored the potential
1432 disk storage needed to support "better Customer Service", another
1435 Even at 30 cents per Megabyte (next year's price), you've just used up
1436 $30,000 of disk space. And that doesn't count the computers, tape
1437 drives and humans necessary to maintain and deploy all of it. Spending
1438 money to save time has its own overhead, too.
1440 Binaries are getting bigger. Graphics and data collection devices can
1441 eat up any amount of disk. There are more tools available, more
1442 libraries, more raw data than you can ever store. My home computer has
1443 a Gigabyte of disk on it. It could easily handle 30.
1445 The "economy" of disk storage media will never remove the need to
1448 So, here's an un-reviewed suggestion originally from Graydon Dodson
1449 <grdodson@lexmark.com>, which I've altered and edited heavily.
1451 - Keep a directory where the whole tree is checked out. (It might be
1452 built and tested once in a while to make sure it is worth linking to,
1453 but that doesn't affect the source control aspect of this procedure).
1454 Let's call it /master/build.
1456 - Write a tool that creates a tree of directories (like the X11
1457 "lndir" command) filled with links to the checked out files in the
1460 This tool should also provide real copies of, not symlinks to, all the
1461 files within the CVS administrative directories.
1463 - You could also provide a way for the tool to take a list of whole
1464 directories that you will never change, for which it would create a
1465 single symlink to the directory and not a subtree of symlinks to
1466 files. Or you could rm -r pieces of the resulting working directory
1467 yourself and replace it with links.
1469 - If you want to edit a file, you have to grab a real copy and keep it
1470 until your revision shows up in the /master/build tree. I'd create a
1471 script to do this: cvsgrab <file>
1476 echo "file $f is not a symlink"
1480 set rev = `grep "^/$f/" CVS/Entries | awk -F/ '{print $3}'`
1481 cvs update -p -r $rev $f > $f
1483 You can't do a plain "cvs update" since that would grab newer
1484 revisions from the Repository, not the revision you wanted to start
1485 with. After the file is no longer a symlink, you can work normally.
1486 You'll have to run "update" before "commit" anyway if there are newer
1489 - Presumably there would also be a tool to traverse the link tree and
1490 revert it to links if there are no modified files and/or if all the
1491 real files match the revision of the /master/build tree.
1493 - To avoid confusing CVS when the /master/build revisions are updated
1494 but your CVS/Entries files is not, CVS would have to change to handle
1495 symlinks. It currently causes problems with this scenario:
1497 ./<file> is a symlink.
1499 ./CVS/Entries says you are revision 1.2.
1501 The corresponding CVS/Entries file in /master/build says the latest
1504 cvs update <file> shows a 'C' conflict flag.
1506 Last modified: _6/13/1997_
1508 Category: /Advanced_Topics_/Installing_CVS/
1512 1. What do I have to do before I install CVS?
1514 You must decide where to set up a Repository.
1516 Though you can construct a Repository tree structure using links and
1517 mount points, there must be a single copy of each real file across
1518 your entire organization. You may not "rdist" files and expect to edit
1521 CVS does not support a truly distributed Repository. You can have
1522 multiple Repositories, but each one must be mounted (not copied or
1523 "rdist"ed) from a single place onto all machines where it will be
1526 Initially, a Repository takes about same amount of disk space as the
1527 sources you want to put into it, plus a bit of overhead for the RCS
1530 See Section 4B. For multiple Repositories, see 4G.3
1532 You need a directory in everyone's $PATH variable where you can
1533 install all the executables. /usr/local/bin is a common place.
1535 You need some helper tools besides CVS such as "RCS" and a good set
1536 of "diff" and "diff3" programs. See 1B.4 for suggestions.
1538 Read the README, INSTALL-CVS and ChangeLog files to see what you are
1541 Though you can probably muddle along without it, you should appoint
1542 one or more "Repository Administrators" who will be responsible for
1543 maintaining the Repository structure, administrative files and the
1544 "modules" interface.
1546 Someone at your site should probably be on the info-cvs mailing list.
1549 Last modified: _6/13/1997_
1551 2. How do I configure the CVS programs?
1553 You should certainly start by reading the README file, the INSTALL-CVS
1554 files and possibly the ChangeLogs in each directory, the Makefile.in
1555 files and the "cvsinit.sh" program.
1557 Execute the ./configure command.
1561 After running "make" you might try running the "sanity.sh" script:
1562 ./src/sanity.sh `pwd`/src/cvs
1564 It writes into /tmp/cvs-sanity by default.
1566 Finish reading the INSTALL-CVS file and test out the system.
1568 Last modified: _6/13/1997_
1570 3. What do I have to install?
1572 Install the "cvs" executable and "mkmodules" from the CVS sources.
1573 The man page is useful too. If you plan to report bugs, you should
1574 also install "cvsbug".
1576 Set your $CVSROOT environment variable and create the Repository
1577 (which you planned out in 4A.1) with the "cvsinit" command at the top
1580 You'll need to edit the Repository control files created by
1583 Install any helper programs mentioned in the modules file.
1585 Last modified: _6/13/1997_
1587 4. How do I work around the merge problems in GNU diff version 2.1 or
1590 See 1B.4 If you use recent versions of RCS and "diff", you won't run
1591 into the above. If you do, see 5B.8
1593 Last modified: _6/13/1997_
1595 Category: /Advanced_Topics_/Internal_errors/
1597 " + Internal errors"
1599 1. Explain: "ci error: unexpected EOF in diff output"
1601 RCS versions earlier than 5.5 print the above error when a file does
1602 not end in a newline character. It can be caused by:
1604 - Editing with Emacs and not using "require-final-newline".
1605 - Committing a binary file.
1606 - Filesystem failures (NFS!) that put nulls in your file.
1608 The solution is to upgrade to RCS 5.5 or later. (Of course, this won't
1609 fix filesystem failures. It will merely allow RCS (and therefore CVS)
1610 to handle the file without error.)
1612 Last modified: _6/13/1997_
1614 2. Explain: "RCS file /Repository/module/file.c,v is in use"
1616 This is an RCS error that occurs when its internal lock file has been
1617 left around by an RCS command interrupted by some sort of system
1618 crash, disk failure or SIGKILL signal.
1620 Go into the Repository and look for files with names similar to
1621 "file.c,v", usually starting with ',', '_' or '#'. Make sure they are
1622 really crash remnants and do not belong to transactions in progress --
1623 a recent last-modified timestamp is a good indicator of a live
1624 transaction. Delete them if they are old.
1626 Last modified: _6/13/1997_
1628 3. Explain: "co error, line 2: Missing access list"
1630 This is an error message from RCS Version 3 when it tries to read a
1631 file created by a later version of RCS.
1633 HP decided to "standardize" on an ancient version of RCS some time
1634 ago. You can't use it for CVS. See 4H.6.
1636 Since the error comes from having a later version of RCS than HP
1637 supports, you probably did install the later version but must have
1638 recently changed your $PATH or installed the HP package that has RCS
1641 You should either reconfigure CVS to use absolute pathnames to the
1642 proper versions of the RCS programs that CVS uses, or change your PATH
1643 to look there first. If you haven't installed the latest version of
1644 RCS, you should upgrade. See 1B.4
1646 Last modified: _6/13/1997_
1648 4. Explain: "error: RCS file name `xyz .c' contains white space"
1650 RCS 5.6 doesn't allow white space in filenames. Apparently this
1651 restriction will be removed in RCS 5.7, but CVS may still require that
1652 filenames have no white space in them.
1654 Last modified: _6/13/1997_
1656 5. Explain: cvs checkout: warning: <X> is not (any longer) pertinent
1658 This message occurs in three instances:
1660 When there is an entry in the ./CVS/Entries for file <X> and there
1661 is no RCS file in the Repository to back it up.
1663 If the working file exists, and hasn't changed (determined from the
1664 timestamp) it is removed.
1666 When you try to check out a piece of the Repository with:
1668 cvs checkout some/place/in/repository/tree
1670 and at least the first element of the path (i.e. "some" in the above)
1671 exists, but some part of the rest of it does not.
1673 The checkout command checks the modules file first for the whole path,
1674 then for a prefix of the path as a module name. If it doesn't find
1675 *any* portion of your path in the modules file, it says:
1677 cvs checkout: cannot find module `<module/path>' - ignored
1679 If it finds some set of prefix directories, it prints the message you
1682 In practice this is usually a spelling error.
1684 If the Repository files you are trying to check out or update are
1685 not readable by you, the same problems can occur. Check the
1686 permissions on the files involved.
1688 Last modified: _6/13/1997_
1690 6. Why did a Repository file change from <file>,v to ,<file>,?
1692 This is an RCS problem, since the ,<file>, syntax for file names is
1693 used by RCS and not CVS.
1695 RCS constructs a new <file>,v in a temporary file named ,<file>,
1696 (which doubles as a lock file) then renames it to <file>,v when it is
1697 done. The only way this is reliable is if your system's version of
1698 rename(2) is an atomic, as required by POSIX.
1700 If your system has a non-atomic (and therefore non-POSIX) rename(2)
1701 system call, RCS runs uses an internal version of this algorithm to
1702 approximate the atomic rename:
1704 rm <file>,v; ln ,<file>, <file>,v; rm ,<file>,
1706 If the system crashes, or you lose your NFS connection between the
1707 first "rm", but before the "ln", you can be left only with the
1708 ,<file>, file. If the crash or network failure occurs between the "ln"
1709 and the final "rm", you could be left with a pair of linked names.
1712 - If only the ,<file>, exists, rename it to <file>,v.
1714 - If both ,<file>, and <file>,v exist and are linked, remove the
1717 - If both ,<file>, and <file>,v exist and are separate files, look at
1718 the dates, "diff" them and make your best guess. This sounds like the
1719 remnants of two separate events.
1721 Last modified: _6/13/1997_
1723 Category: /Advanced_Topics_/Other_Systems/
1727 1. I use a NeXT. Is there anything I need to know?
1729 NeXTSTEP 3.0's Interface Builder uses "nib" directories, rather than
1730 the files used in previous revisions. It removes files it doesn't
1731 recognize, making it impossible to place such a directory under CVS --
1732 the CVS admin directory will be removed.
1734 Some time ago, <Bob_Vadnais@pdh.com> posted a palette named CVSPalette
1735 that claimed to resolve this problem. It was intended to preserve the
1736 CVS administrative directories within nib documents (directories) that
1737 Interface Builder usually removes.
1739 CVSPalette is no longer in its announced place:
1741 ftp.cs.orst.edu:/pub/next/submissions
1743 though I did find two other interesting files on ftp.cs.orst.edu:
1745 /software/NeXT/sources/tools/cvs-next-2_1_1.tar.Z
1747 which is a port of CVS 1.3 (along with RCS and diff) and:
1749 /software/NeXT/sources/programming/cvs.postamble-2.4.gz
1751 which appears to be a set of wrappers for CVS commands that claim to
1752 allow you to use CVS effectively (and without need for the "command
1753 line") on a NeXT machine.
1755 [[Anyone know the truth about CVS and NeXT?]]
1757 Last modified: _6/13/1997_
1759 2. I use OS/2 and/or DOS and/or Windows. Is there anything I need to know?
1761 When using a local repository, be sure to specify the local access
1762 method or CVS will interpret the drive letter as a remote host name
1763 due to the : following it:
1765 WRONG: CVSROOT=C:\SRC\CVSROOT
1767 RIGHT: CVSROOT=:local:C:\SRC\CVSROOT
1769 (larry.jones@sdrc.com)
1771 You can share RCS files between Unix and DOS while avoiding the MS-DOS
1772 file name limits by setting your RCSINIT environment variable to
1773 '-x/,v'. New RCS files will be created without the standard ",v"
1774 suffix, though files ending in ",v" will still be found if there is no
1775 matching file in the same directory without the ",v".
1777 Erik van Linstee offers an OS/2 and a DOS port of CVS 1.3 in:
1779 ftp.informatik.tu-muenchen.de:/pub/comp/os/os2/gnu/devtools or
1780 ftp.rrzn.uni-hannover.de:/pub/os2-local
1782 The files are named:
1786 Where the ? stands for the patch level (currently 8) and the b is for
1787 the binaries, the s for the sources.
1789 There are three binaries. An OS/2 only one (32-bit), a DOS only one
1790 (16-bit) and an EMX one that runs on both (32-bit).
1792 There are many differences between the Unix and the DOS versions of
1793 CVS. Read the material that comes with the DOS version before using
1798 Last modified: _9/22/1997_
1800 3. I use SCO Unix. Is there anything I need to know?
1802 On SCO/UNIX 3.2 V2.0 POSIX signals don't work. Unfortunately the
1803 configure program detects POSIXness and configures in the use of POSIX
1804 signals. Workaround : Edit out the check for POSIXness in the
1805 configure script. [[You could also remove all occurrences of
1806 "-DPOSIX=1" from the Makefiles after configure is run. -dgg-]]
1808 SCO/UNIX doesn't understand #!/<some shell> syntax. This breaks the
1809 use of log.pl as it gets invoked by /bin/sh instead of
1810 !#/usr/local/bin/perl. WorkAround : edit log.pl and change it into a
1811 shell script which invokes perl with log.perl (renamed from log.pl) as
1813 Contributed by Joe Drumgoole
1815 Last modified: _6/13/1997_
1817 4. I use AIX. Is there anything I need to know?
1819 The only report on AIX claims to have no trouble using it in concert
1820 with SunOS and IRIX platforms.
1822 Last modified: _6/13/1997_
1824 5. I use IRIX. Is there anything I need to know?
1826 If you see "uid" numbers where you would expect user names, try adding
1827 -lsun to the link line. Without it CVS is unable to retrieve "passwd"
1830 Last modified: _6/13/1997_
1832 6. I use an HP system. Is there anything I need to know?
1834 HP distributes RCS version 3 (a circa 1983 release!) with HP-UX. CVS
1835 does not work with RCS version 3; it requires RCS version 4 or later.
1836 Your best bet is to find the latest version of RCS and install it
1839 HP-UX 8.07 has a serious bug with the mmap system call and NFS files;
1840 the bug can crash the operating system. Make sure that you configure
1841 RCS to avoid mmap by setting has_mmap to 0 in RCS's conf.h. This bug
1842 is fixed in HP-UX 9.
1844 Contributed by Paul Eggert
1846 If using the setgid() trick described in 4D.13, you will have to
1847 create an entry in the /etc/privgroup file to give the group assigned
1848 to the cvs executable setgid permission (see setprivgrp(1m)).
1849 Additionally, if you are restricting "read" access to the Repository
1850 by limiting access to the executable (this requires yet another
1851 group), then you will require that /etc/logingroup exists and is
1852 configured correctly (usually it's just alink to /etc/group).
1854 Contributed by Dale Woolridge
1856 Last modified: _6/13/1997_
1858 7. I use AFS. Is there anything I need to know?
1860 There is a problem with the way CVS performs its locking when the
1861 files are within AFS. When your current PTS id != your uid, the locks
1862 are not deleted. The stat() system call returns the PTS id of the
1863 owner. If that id != your uid, CVS assumes you did not lock it, and
1864 leaves the lock files alone. The next time you try to use it, it
1865 complains that someone has the repository locked.
1867 Contributed by Michael Ganzberger
1869 [[This was against CVS 1.3. Is it still in CVS 1.4?]]
1871 Last modified: _6/13/1997_
1873 8. I use A/UX. Is there anything I need to know?
1877 Last modified: _6/13/1997_
1879 Category: /Advanced_Topics_/Related_Software/
1881 " + Related Software"
1883 1. How do I use CVS under Emacs? Is there an Emacs cvs-mode?
1885 The pcl-cvs package distributed with CVS is an emacs package that
1886 helps with the update/commit process. When you are ready to update,
1887 you use the 'cvs-update' command within emacs. This executes "update"
1888 and fills a cvs-mode buffer with a line for each file that changed.
1889 The most helpful features are: descriptive words for what happened
1890 (i.e. Merged or Conflict rather than 'U' or 'C'), single keys bound to
1891 diffs and commits, and the ability to mark arbitrary groups of files,
1892 possibly from different directories, for commit as a whole.
1894 All the developers in my group that use emacs find pcl-cvs a much
1895 friendlier and more helpful way to update/commit than raw cvs. One vi
1896 user even converted to emacs just to use pcl-cvs.
1898 Contributed by Jeffrey M Loomis
1900 Last modified: _6/13/1997_
1902 2. What is GIC (Graphical Interface to CVS)?
1907 GIC provides a graphical user interface to the Concurrent Version
1908 System (CVS), a powerful revision control system. GIC is
1909 implemented in the Tcl/Tk programming language and is intended to
1910 augment the sometimes cumbersome CVS command line interface.
1912 Note that according to the official GIC page at
1913 http://www.cpsc.ucalgary.ca/redirect/grouplab/projects/gic/
1914 GIC is no longer being maintained and tkCVS is recommended
1917 For more on tkCVS, see
1918 <http://ximbiot.com/cvs/cvshome/dev/addontkcvs.html>.
1922 Last modified: _9/6/1997_
1926 CAVEMAN is a front end to CVS written in PERL providing a collection
1927 of features desired by the site where it was developed.
1929 - The ability to spread a "project" over multiple Repositories.
1930 - Optional automatic tagging after each commit.
1931 - Additional locking of files.
1932 - Extra before and after program hooks.
1933 - A layer of event logging.
1934 - All sorts of error messages.
1935 - Many changes to the semantics of commands.
1937 It is available via anonymous ftp on ftp.llnl.gov [128.115.54.18] in
1938 gnu/caveman_vX.Y.Z.tar.gz (The numbers X, Y, & Z vary.)
1940 contact Kathleen Dyer kdyer@llnl.gov
1944 [[Does someone want to elaborate?]]
1946 Last modified: _6/13/1997_
1948 Category: /Advanced_Topics_/Setting_up_and_Manag/
1950 " + Setting up and Managing the Repository"
1952 1. What do I do first? How do I create a Repository?
1954 First, install all the programs. (See Section 4A.)
1956 Then create a Repository by executing "cvs -d init". (This works with
1959 Now you can configure your repository by checking out CVSROOT: "cvs -d
1960 checkout CVSROOT". Change into the created directory CVSROOT. Edit the
1961 files you want to edit, and afterwards, commit the changes by typing
1964 You will certainly want to add modules of your own. Edit the "modules"
1965 file and add lines to describe the items you want to "checkout" by
1966 module name. Here's a short list that could be used for storing a
1967 small number of GNU and PD sources:
1972 emacs local/gnu/emacs
1976 pdprog1 local/public/pdprog1
1977 pdprog2 local/public/pdprog2
1984 Last modified: _4/21/1998_
1986 2. What are those files in $CVSROOT/CVSROOT?
1988 There are eight Repository control (or "database") files of interest
1989 in the CVSROOT directory:
1991 modules contains the "modules" database. See 1D.11, 2C.7, 4B.6 and
1992 4B.7 for more details.
1994 commitinfo contains two columns: 1. a regular expression to match
1995 against pathnames within the Repository and
1997 a <command> to execute for matching pathnames.
1999 When you execute "commit", CVS passes the Repository pathname for each
2000 directory (and the files to commit within that directory) to
2001 <command>. If <command> exits with a non-zero status, the commit is
2004 A <command> associated with a pathname of "DEFAULT" is executed if
2005 nothing else matches. Every <command> associated with a pathname of
2006 "ALL" is executed separately.
2008 rcsinfo contains the same first column as commitinfo, but the second
2009 column is a template file for specifying the log entry you are
2010 required to enter for each commit.
2012 "DEFAULT" and "ALL" work the same as in the commitinfo file.
2014 editinfo contains the same two columns as commitinfo, but the
2015 <command> in the second column is intended to do some consistency
2016 checking on the commit log.
2018 "DEFAULT" works as in commitinfo.
2020 loginfo contains the same two columns as commitinfo, but the
2021 <command> is expected to read a log message from its standard input.
2022 The <command> can do anything it wants with the log information, but
2023 normally it is appended to a log file or sent to mailing lists.
2025 "DEFAULT" & "ALL" work the same as in commitinfo.
2027 cvsignore contains "ignore" patterns that are added to the built-in
2028 ignore list. See 2D.10.
2030 checkoutlist contains a list of other files kept under RCS in
2031 $CVSROOT/CVSROOT that should be checked out by mkmodules to provide a
2034 history contains a stream of text records, one for each event that
2035 the "history" command is interested in. Though the contents of the
2036 history file can be read, it is intended to be read and displayed by
2037 the "history" command. This file is the only one in the above list
2038 that is not under RCS.
2040 Last modified: _6/13/1997_
2042 3. Is there any other state stored in the Repository besides in the
2043 $CVSROOT/CVSROOT directory?
2045 Only in the RCS files. The Repository holds exactly two things: the
2046 tree of RCS files (each usually ending in ",v") and the CVSROOT
2047 directory described above.
2049 Last modified: _6/13/1997_
2051 4. How do I put sources into the Repository?
2053 There are three main ways to put files in the Repository:
2055 Use the "import" command described in Section 3H.
2057 This method is the fastest way to put trees of new code into the
2058 Repository and the *only* way to handle source releases from a 3rd
2059 party software vendor.
2061 Use "add" followed by "commit".
2063 This is how to add new files and directories to the Repository, a few
2064 at a time. Directories don't need to be committed.
2066 You can move RCS files directly into the Repository.
2068 You should create a directory hierarchy to hold them, but you can just
2069 move arbitrary ",v" files into the Repository. The only "state" in the
2070 Repository other than within ",v" files is in the required CVSROOT
2071 directory at the top of the Repository.
2073 Last modified: _6/13/1997_
2075 5. What file permissions should I use on (and in) the Repository?
2077 If you are using pserver (password-authenticated access), see below.
2079 If you run a completely open environment (which usually means that you
2080 don't have, or don't want to waste, the time to deal with it):
2082 - Set all directory permissions to 777.
2084 - Have everyone set their umasks to 0.
2086 (BTW, I don't suggest this. I am merely reporting it.)
2088 If you are a normal Unix shop and want to use groups effectively:
2090 - Set all the directory permissions in the Repository to 775.
2092 If you are using a system that handles both System V and BSD
2093 filesystems, you might have to set the permissions to 2775.)
2095 If you are using one of the many recent versions of Unix that don't
2096 allow you to use the full octal mode, then you'll have to type: chmod
2097 u=rwx,g=rwx,o=rx,g+s dir>
2099 - Change all the groups on the directories to match the groups you
2100 want to write to various directories.
2102 - Make sure every user is in the appropriate groups.
2104 - Have everyone set their umask to 002, including root.
2106 If you don't want non-group members to even read the files, do the
2109 - Repository directory permissions to 770. (or 2770)
2113 If you work in an environment where people can't be trusted to set
2114 their "umask" to something reasonable, you might want to set the umask
2117 mv /usr/local/bin/cvs /usr/local/bin/cvs.real
2118 cat > /usr/local/bin/cvs
2120 umask 2 # Or whatever your site standard is.
2121 exec /usr/local/bin/cvs.real ${1+"$@"}
2124 Pserver (Password-Authenticated Access) <blome@de.ibm.com>
2126 The above suggestions are not valid when you use the pserver facility.
2127 Be sure to read and understand the manual section about this (should
2128 be 4.6.something). Above all: do /not/ make the repository and CVSROOT
2129 group writeable. In CVSROOT, make `history´ group or world writeable
2132 I suggest creating one unix group per project group. In the
2133 repository, you would then create one directory for each group, group
2134 writeable. New projects must then be created in these group
2135 directories. If you don't want to say <group>/<project> on
2136 checkout, create a <project> module and point it there.
2138 Last modified: _9/24/1998_
2140 6. How do I structure my Repository?
2142 The Repository holds your software. It can be all interrelated or it
2143 can be a bunch of separately managed directories.
2145 How you break a whole system down into its component parts, while
2146 defining interfaces between them, is one aspect of "Software
2147 Engineering", a discipline that requires the study of dozens of
2148 strange and wonderful areas of the computer and management worlds.
2150 CVS provides a way to keep track of changes to individual files, a way
2151 to "tag" collections of files, and a way to "name" collections of
2152 files and directories. That's all. Everything else is in the way you
2155 In other words, you should structure your Repository to match your
2156 needs, usually tied in with the other tools you use to build, install
2157 and distribute your work. Common needs include the ability to:
2159 - mount (or automount) directories from many places in your
2161 - check out just what you need and no more.
2162 - check out multiple sections in a fixed relation to each other.
2163 - check out large sections to match the assumptions built into your
2164 build system. (Makefiles?)
2166 In my opinion, you should start small and keep everything in one tree,
2167 placing each major sub-system into a separate directory. Later, when
2168 you know what you are doing, you can make it more sophisticated.
2170 Last modified: _6/13/1997_
2172 7. Why would anyone use "modules"? They are too restrictive. I want to be
2173 able to select just the files I want to edit.
2175 Any form of structure is restrictive. If you believe that total chaos
2176 is a viable working paradigm, or if you believe you can keep track of
2177 the interrelations between all portions of your Repository in your
2178 head, then you can do what you please.
2180 If you believe that systems of files require management and structure,
2181 then the "modules" idea is very useful. It is a way to impose a naming
2182 scheme on a tree of files, a naming scheme that can be simpler than a
2183 large list of relative pathnames.
2185 The "modules" file represents a published interface to the Repository
2186 set up by your Repository Administrator. If s/he did a creditable job,
2187 the modules offered will be internally consistent and will smoothly
2188 interact with the rest of your environment.
2190 Last modified: _6/13/1997_
2192 8. How do I rename a file or directory? What are the consequences?
2194 In CVS there is no single "rename" command.
2196 See 2C.4 for the suggested way to rename a file or directory.
2198 The rest of this section covers some of the consequences of renaming.
2200 A "renaming database" has been proposed that would keep track of name
2201 changes so that "update -r <tag>" would continue to work across the
2202 renaming. But as it stands, you have to pick one of the following
2205 Use the technique described in 2C.4. (For each file, duplicate the
2206 file in the Repository, "remove" the old version so it winds up in the
2207 Attic and strip all Tags off the new version.)
2209 - "update -r <tag>" produces the correct files.
2211 - The duplicated revision history can be slightly misleading.
2213 - A plain (i.e. without the "-r <tag>") "checkout" or "update -d" will
2214 create directories "renamed" this way, but you can delete it and a
2215 plain "update" won't bring it back.
2217 Move the files and directories in the Repository to the new names.
2219 - You save the revision history under a different file name.
2221 - You save a little space.
2223 - "update -r <tag>" produces the wrong files or directories.
2225 This is not a good general solution, but if you plan never to look
2226 back (someone may be gaining on you!), it is sometimes a useful
2229 If you are clever with Makefiles, you might be able to rework them to
2230 handle either the new or old names, depending on which ones exist at
2231 the time. Then you can move an old <tag> onto the new, more
2232 sophisticated, revision of the Makefile. (Yes, this changes the
2233 "released" file if <tag> indicates a release. But it is an option.)
2235 - Important Note: If you rename a directory, you must rename the
2236 corresponding directory in every checked-out working directory. At the
2237 same time, you must edit the pathname stored in the ./CVS/Repository
2238 file within each of the moved directories.
2240 The easiest way to move a lot of directories around is to tell
2241 everyone to remove their working directories and check them out again
2244 - The file exists in the working directory and in the ./CVS/Entries
2245 file, but not in the Repository. For the old file, "update" prints:
2247 cvs update: xyz.c is no longer in the repository
2249 and deletes the file. If the file was modified, "update" prints:
2251 cvs update: conflict: xyz.c is modified but no longer in the
2254 and leaves the file alone. In the new directory, you see:
2258 as you would if someone else executed "add" and "commit".
2260 For each file, copy the working file to a new name in the working
2261 directory and use the "cvs remove" to get rid of the old old file and
2262 "cvs add" to add the new one. Since there is no way for CVS to remove
2263 a directory, this only works for files.
2265 - This is what most people think of first. Without a "rename" command,
2266 the remove/add technique seems obvious.
2268 - You lose the connection of your new working file to its past
2271 Last modified: _6/13/1997_
2273 9. What are "Attic" directories?
2275 When you use the "remove" command on a file, CVS doesn't delete the
2276 file, it only registers your desire to delete it.
2278 When you "commit" a removed file, CVS moves the Repository's matching
2279 RCS file into a sub-directory named "Attic" within the Repository.
2281 Attic files are examined when the '-r' or '-D' option is used on
2282 "checkout" or "update". If the specified revision, tag or date matches
2283 one on a file in the Attic, that file is checked out with the others.
2285 You can think of the Attic as a sort of dead branch, which is only
2286 looked at when you refer to a <tag> or <date>.
2288 Last modified: _6/13/1997_
2290 10. Is it OK to remove anything from the Repository?
2292 In general, removing anything from the Repository is a bad idea. The
2293 information in a deleted object is lost forever. There are many ways
2294 to skip over files, directories and revisions without deleting them.
2296 Here are some of the consequences of removing the following things
2297 stored in the Repository:
2299 CVSROOT files (Repository control files)
2301 The Repository will work without any of them, but you should
2302 understand what you are losing by deleting them. See 4B.2.
2306 The only way to remove revisions is to use the "admin -o" command (or
2307 the equivalent RCS command "rcs -o").
2309 They are lost forever. Any tags formerly attached to deleted revisions
2310 are now pointing into the Phantom Zone. You'll need to contact Jor-el
2315 You should not remove a file unless you truly never want to see it
2316 again. If you want to be able to check out an old revision of this
2317 file, use "cvs remove" instead.
2321 Tags take up little space and you can't recover from deleting them. If
2322 you depend on tags for releases you will lose vital information.
2326 There is no Attic for directories, so the only way to remove them is
2327 to use "rm -r". They are gone forever.
2329 If you delete (or move) a directory, all checked-out versions of that
2330 directory will cause CVS to halt. You'll have to visit each
2331 checked-out directory and remove the matching working directory by
2336 The "remove" command sends files to the Attic. To really delete them,
2337 you have to go into the Attic and use "rm".
2339 If a file in the Attic has a Tag on it that you might ever want to
2340 check out again, you probably don't want to delete it.
2342 Lock files (named: "#cvs.[wr]fl.<pid>")
2344 These are lock files. If you are getting "lock" errors and the dates
2345 on the lock files indicate that they are old, you can delete them.
2347 Deleting lock files still in use by a CVS process might produce
2350 Last modified: _6/13/1997_
2352 11. Can I convert to CVS from RCS without losing my revision history?
2354 Yes, you can simply move (or copy) your RCS files into a directory
2355 within the Repository, check out that directory and start working.
2357 Last modified: _6/13/1997_
2359 12. Can I move RCS files with branches in them into the Repository?
2361 Yes, but they may not work if you created branches in a way that
2362 conflicts with CVS's assumptions:
2364 You can't use .0. branches. (They are reserved for "Magic" branch
2367 If you use branch 1.1.1, you can't use the Vendor branch.
2369 You can use other RCS branches under CVS. There is no need to create
2370 "magic" branch tags because the physical branch already exists.
2372 Last modified: _6/13/1997_
2374 13. Can I use raw RCS commands on the Repository?
2376 You can use raw rcs commands directly on the Repository if you take a
2377 little care. The Repository itself contains no "CVS state" (as opposed
2378 to RCS revision histories) outside the CVSROOT directory.
2380 But using raw RCS commands to change branches, tags or other things
2381 that CVS depends on may render the files unusable.
2383 See 4D.7 on RCS/CVS sharing of the Repository and Section 3B on the
2386 Last modified: _6/13/1997_
2388 14. How do I convert from SCCS to RCS?
2390 You'll have to execute something like "sccs2rcs" (in the CVS contrib
2391 directory) on every file. Then you can move the resulting RCS files
2392 into the Repository as described above.
2394 Last modified: _6/13/1997_
2396 15. How do I limit access to the Repository?
2398 There are all sorts of ways to restrict access to Repository files,
2399 none of which are hooked directly into CVS.
2401 Techniques for limiting access include:
2403 Training, management and good backups.
2405 The best form of Repository control is a combination of:
2407 - A reliable backup scheme (verify it!)
2408 - Enough training to ensure your developers are competent and
2409 knowledgeable about all areas of your sources.
2410 - Effective management of the boundaries and grey areas.
2412 In many cases, technical solutions to "security" problems are
2413 inadequate. You should first try to avoid them.
2415 Personal Opinion: In an environment where "unknowns" are allowed to
2416 touch important sources the "owner" of the CVS Repository must be a
2417 large, loud, vigorous lout with a well-balanced truncheon and the
2418 right to use it. Don't underestimate the effectiveness of letting
2419 everyone know they will be strapped into the stocks on the Town Common
2420 and pelted with vegetables if they break something they don't
2421 understand without first asking the experts.
2423 Set Unix groups and permissions. See 4B.5. You can set different
2424 owners, groups and permissions for each sub-directory within the
2425 Repository if that helps.
2427 Catch invocations of "commit" by defining pre-commit programs in the
2428 "commitinfo" file. This is fairly powerful, since it can block commits
2429 based on anything you can program. Take a look at the programs in the
2430 "contrib" directory of the CVS source tree.
2432 Use multiple Repositories, each with its own protection scheme. If
2433 you use NFS (or AFS) you can even use "export" restrictions to various
2434 groups of machines to keep (for example) the Engineering Repository
2435 off the Customer Service machines.
2437 Try the "setgid" trick described in 4D.13.
2439 Try to use the RCS access control lists, though I don't think CVS
2440 will handle them cleanly.
2442 Edit the source code to CVS to add your own access control.
2444 Last modified: _6/13/1997_
2446 16. What are the Repository Administrator's responsibilities?
2448 Generally, the Administrator should set "policy", create the
2449 Repository and monitor its size and control files.
2451 Some specific responsibilities include:
2453 Examining the Repository once in a while to clean up:
2455 Trash files left by misguided developers who mistake the Repository
2456 for a working directory.
2458 Non-RCS files. Other than the files CVS needs in the
2459 $CVSROOT/CVSROOT directory, every file in the Repository should be an
2462 Lock files (both CVS '#*' and RCS ',*' files) left around after
2465 Wrong permissions, groups and ownerships.
2467 Locked files. (RCS locks, that is.)
2469 Attic files that should never have been under CVS at all. Don't
2470 blindly delete files from Attic directories -- they were mostly put
2471 there (via the "cvs remove") for a reason. Files that should be
2472 deleted are binary files (e.g. '*.o', 'core', executables) that were
2473 mistakenly inserted by "import -I !".
2475 Maintaining the modules file.
2477 Storing site-specific ignore patterns in the
2478 $CVSROOT/CVSROOT/cvsignore file.
2480 Storing the names of non-standard CVSROOT files (See 4B.2) in the
2481 $CVSROOT/CVSROOT/checkoutlist
2483 Maintaining the other Repository control files: commitinfo, loginfo,
2484 rcsinfo and editinfo.
2486 Pruning the history file every once in a while. (Try the
2487 "cln_hist.pl" script in the "contrib" directory.)
2489 Staying aware of developments on the info-cvs mailing list and what
2490 is available in the FTP and WWW archives.
2492 Running "ps ax" once in a while and kill off any "update" programs
2493 not running as "root". It is too easy to leave the "cvs" off the front
2494 of the "cvs update" command.
2496 Executing monitor programs to check the internal consistency of the
2497 Repository files. Ideas:
2499 Files that have a default RCS branch that is not 1.1.1 (From an
2500 abuse of "admin -b".)
2502 Files that have only Revisions 1.1 and 1.1.1.1, with a default
2503 branch of "MAIN". (From an abuse of "admin -o".)
2505 Existing branch tags and various branch consistency checks.
2507 Last modified: _6/13/1997_
2509 17. How do I move the whole Repository?
2511 Copy or move the tree. (On Unix systems, a set of piped "tar" commands
2512 works great. If the Repository does not contain any symlinks, which it
2513 normally doesn't, you can also use "cp -r".)
2515 If you can avoid changing $CVSROOT (i.e. the "logical" pathname of the
2516 Repository) by replacing the old location with a symbolic link to the
2517 new location, you don't have to do anything else.
2519 (You could also mount the new location on top of the old location if
2520 you are using NFS or some other filesystem that allows it.)
2522 If you must change $CVSROOT, you must also tell everyone to change the
2523 CVSROOT environment variable in all running shells and in any personal
2524 configuration files ('.' files on Unix) where it is set.
2526 The Repository itself contains no references to its own name, except
2527 possibly in some of the files in the CVSROOT directory. If your
2528 modules (or loginfo, commitinfo, etc.) file mentions helper programs
2529 directly in the Repository, you'll have to change the pathnames to
2530 point to the new Repository location.
2532 The main changes you'll have to make are to all the CVS administrative
2533 files (./CVS/Repository and ./CVS/Root) in every working directory
2534 ever checked out from the previous location of the Repository you just
2537 You have three choices:
2539 If all ./CVS/Repository files in all working directories contain
2540 relative pathnames, you don't have to do anything else.
2542 Have everyone "release" or delete their working directories (after
2543 committing, or just saving, their work) and check them all out again
2544 from the new Repository after the move.
2546 Use "find . ( -name Repository -o -name Root )" and a PERL or shell
2547 script to run through all the ./CVS/Repository and ./CVS/Root files
2548 and edit the values in the files.
2550 Last modified: _6/13/1997_
2552 18. How do I change permissions on a file in the Repository by using a CVS
2553 command? (i.e. without using "chmod 777 $CVSROOT/dir/file")
2555 When you first "import" or "add"/"commit" a file, the read and execute
2556 bits on the Repository file are inherited from the original source
2557 file, while the write bits on the Repository file are are turned off.
2558 This is a standard RCS action.
2560 After that, there is no way to alter the permissions on a file in the
2561 Repository using CVS (or RCS) commands. You have to change the
2562 permissions on both your working file and on the Repository file from
2563 which it was retrieved.
2565 Whenever you "checkout" the file or retrieve a new revision via
2566 "update" (or after a "commit"), your working file is set to match the
2567 permissions of the Repository file, minus any "umask" bits you have
2570 Last modified: _6/13/1997_
2572 Category: /Advanced_Topics_/Tricks_of_the_Trade/
2574 " + Tricks of the Trade"
2576 1. How can you even check in binary files, let alone allow CVS to do its
2577 auto-merge trick on them?
2580 First of all, if you want to use binary files, you should get RCS 5.7
2581 and CVS 1.9 or later (earlier versions had some support, but there have been
2582 bug fixes). Secondly, follow the instructions for installing RCS very
2583 carefully (it is easy to get it installed so it works for everything
2584 except binary files).
2586 Then, specify 'cvs add -kb' instead of just 'cvs add' to add a binary
2587 file. If you want to set an existing file to binary, run 'cvs admin
2588 -kb' (and then check in a new copy of the file). Note that old
2589 versions of CVS used -ko instead of -kb for binary files, so if you
2590 see a reference to -ko in the context of binary files, you should
2593 Of course when 'cvs update' finds that a merge is needed, it can't
2594 do this for binary files the same way as for text files. With the
2595 latest versions (e.g. CVS 1.9.14), it should be able to give you both
2596 versions and let you merge manually. Another approach is to
2597 run 'cvs admin -l' to lock files, as described in
2598 "How can I lock files while I'm working on them the way RCS does?"
2599 elsewhere in this FAQ. See also
2600 "Is there any way to import binary files?" and
2601 "How do I "add" a binary file?" elsewhere in this FAQ.
2605 Last modified: _9/6/1997_
2607 2. Can I edit the RCS (",v") files in the Repository?
2609 Yes, but be very careful. The RCS files are not free-form files, they
2610 have a structure that is easily broken by hand-editing. The only time
2611 I would suggest doing this is to recover from emergency failures that
2612 are difficult to deal with using CVS commands, including the "admin"
2613 command, which can talk directly to RCS.
2615 Though no one actively encourages the editing of RCS files, many
2616 people have succumbed to the urge to do so when pressed for time. The
2617 reasons given, usually with evident contrition, include:
2619 - Editing mistakes in, or adding text to, log entries. (If you have
2620 RCS 5.6 or later, you should use `cvs admin -m'.)
2621 - Renaming or moving symbolic names. (You should `cvs admin -N'
2623 - Unlocking a file by changing the "locker" from someone else to
2624 yourself. (It's safer to use `cvs admin -u -l'.)
2625 - Making global changes to past history. Example: Eradicating former
2626 employees names from old documents and Author entries. (And someone
2627 thought the "history" command was evidence of Big Brother! I never
2628 realized how much help a wide-open revision control system could have
2629 provided to The Ministry of Truth.)
2631 Last modified: _6/13/1997_
2633 3. Can I edit the ./CVS/{Entries,Repository,Tag} files?
2635 Yes, but with CVS 1.3 and later, there is almost no reason to edit any
2636 of the CVS administrative files.
2638 If you move pieces of your Repository around it can be faster to edit
2639 all the ./CVS/Repository files rather than checking out a large tree.
2640 But that is nearly the only reason to do so.
2642 Last modified: _6/13/1997_
2644 4. Someone executed "admin -o" and removed revisions to which tags/symbols
2645 were attached. How do I fix them?
2647 It depends on what you mean by "fix". I can think of three ways to fix
2652 Assuming you really wanted to get rid of the revision and its
2653 associated tags, you can remove them with the "admin" command. The
2654 "tag -d" command will only remove tags attached to existing revisions.
2655 You can remove a tag, even if it is attached to a non-existent
2656 revision, by typing:
2658 cvs admin -N<tag> <file>
2660 Retrieve the outdated revision.
2662 You should first look in your backup system for recent versions of the
2663 file. If you can't use them, you can carefully extract each revision
2664 that followed the earliest outdated revision using RCS (or "cvs
2665 admin") commands and reconstruct the file with all the right
2666 revisions, branches and tags. This is a lot of work.
2668 You *can't* insert a revision into the current RCS file.
2670 Move the Tags to another revision in each file.
2672 If you want to move the tags to another valid revision, you have two
2673 choices, both of which require that you find all the revision numbers
2674 of the files you want to "tag" and execute the following command
2675 sequences on each <file>.
2677 Use "update" to grab the revision you want, then execute a normal
2678 "tag" command to Tag that revision:
2680 cvs update -r <rev> <file>
2681 cvs tag <tag> <file>
2683 Use "admin" to set the tag to a specific revision:
2685 cvs admin -N<tag>:<rev> <file>
2687 Last modified: _6/13/1997_
2689 5. How do I move or rename a magic branch tag?
2691 (To rename a non-branch <tag> see 3O.9.)
2693 Before reading this, read 3M.3 and 3M.4 and understand exactly how tag
2694 and rtag use '-r' and why it won't do the right job here.
2696 First, I have to explain exactly what a magic branch tag is.
2698 A magic <branch_tag> is an artificial tag attached to a non-existent
2699 revision on a non-existent branch number zero. It looks like this:
2703 <X> is the "branch point revision", a normal revision with an
2704 odd number of '.'s in it. (e.g. 1.5, 1.3.1.6, etc)
2706 Y is an even number (e.g. 2, 4, 6, etc.) All CVS branches,
2707 other than the Vendor branch, are even numbered.
2709 TAG1 is considered by CVS to be attached to revision <X>. The first
2710 "update -r TAG1 <file>" after applying TAG1 will produce a copy of
2711 revision <X> with a sticky tag of TAG1. The first "commit" to that
2712 file will cause CVS to construct an RCS branch named <X>.Y and check
2713 in revision <X>.Y.1 on the new branch.
2715 Note: TAG1 is *not* considered to be attached to <X> by RCS, which
2716 explains why you can't refer directly to the branch point revision for
2719 Moving a magic <branch_tag> is the act of reapplying the same tag to
2720 different revisions in the file:
2724 TAG1:<X>.0.Z or TAG1:<A>.0.B
2726 You can move a magic branch tag to the revisions of your choice by
2727 using "update" to find the revisions you want to tag and reapplying
2728 the tag to all the files with the '-F' option to force it to move the
2729 existing <branch_tag>.
2731 cvs update -r <tag/rev> (or '-A' for the Main Branch)
2732 cvs tag -F -b <branch_tag>
2734 If the earlier location of TAG1 refers to a physical branch within any
2735 RCS file, moving it will make the existing branch in the file seem to
2736 disappear from CVS's view. This is not a good idea unless you really
2737 want to forget the existence of those RCS branches.
2739 If the "update" above retrieves the original branch point revision
2740 (<X>), the "tag" command above will create the tag:
2744 Where Z is 2 greater than the highest magic branch already on revision
2745 <X>. The TAG1 branch will still have the same branch point (i.e.
2746 revision <X>), but the first commit to the new TAG1 branch will create
2747 a different RCS branch number (<X>.Z instead of <X>.Y).
2749 Renaming a magic <branch_tag> is the act of changing
2755 There is no harm in changing a tag name as long as you forget that
2756 TAG1 ever existed and you clean up any working directories with sticky
2757 TAG1 tags on them by using "update -A", "update -r <other_tag>" or by
2758 removing the working directories.
2760 On the other hand, actually changing the tag is not easy.
2762 See 3M.3 for why the seemingly obvious solution won't work:
2764 cvs tag -b -r <old_branch_tag> <new_branch_tag>
2766 The only direct way to rename a magic tag is to use the "admin"
2767 command on each file: (You might want to use '-n'. Read "man rcs" and
2768 look at the '-n' and '-N' options.)
2770 cvs admin -N<new_branch_tag>:<old_branch_tag> .
2771 cvs tag -d <old_branch_tag>
2773 But you have to be careful because "admin" is different from other CVS
2776 "admin" can be used recursively, but only by specifying directory
2777 names in its argument list (e.g. '.'),
2779 Where "rtag -r <old_branch_tag>" would interpret <old_branch_tag> as
2780 a magic CVS branch tag, "admin" is a direct interface to RCS which
2781 sees a magic branch tag as a simple (though non-existent) RCS revision
2784 This is good for us in this particular case, but different from normal
2787 "admin" also skips the Attic and produces different kinds of errors
2788 than CVS usually does. (Because they are coming directly from RCS.)
2790 The other way to rename a magic <branch_tag> is to edit the Repository
2791 files with a script of some kind. I've done it in the past, but I'll
2792 leave it as an exercise for the reader.
2794 Last modified: _6/13/1997_
2796 6. Can I use RCS locally to record my changes without making them globally
2797 visible by committing them?
2799 You can, but it will probably confuse CVS to have ",v" files in your
2800 working directory. And you will lose all your log entries when you
2803 Your best bet is to create your own CVS branch and work there. You can
2804 commit as many revisions as you want, then merge it back into the main
2805 line (or parent branch) when you are finished.
2807 Last modified: _6/13/1997_
2809 7. How can I allow access to the Repository by both CVS and RCS?
2811 The first step is to try not to. If some people are using CVS, there
2812 is no reason for everyone not to. It is not hard to learn the basics
2813 and CVS makes certain operations *easier* than a series of RCS
2814 commands. Personal preference in what software tools can be applied to
2815 a shared Repository has to take second place to system integration
2816 needs. If you disagree, try writing some Lisp code for inclusion in
2817 your Unix kernel and see what kind of reception you get.
2819 If you really must allow routine RCS access to the CVS Repository, you
2820 can link an RCS sub-directory into a piece of the Repository:
2822 ln -s /Repository/some/directory/I/want RCS
2824 and RCS will work just fine.
2826 Those who are using RCS will have to keep the following in mind:
2828 If a file was originally added to the Repository by "import" and has
2829 not been changed using CVS, the *RCS* default branch will remain
2830 attached to the Vendor branch, causing revisions checked-in by "ci" to
2831 wind up on the Vendor branch, instead of the main branch. Only CVS
2832 moves the RCS default branch on first commit.
2834 The way around this is to checkin (using "ci") all the files first and
2835 move them into the Repository. That way they won't have Vendor
2836 branches. Then RCS will work OK.
2838 It is possible to use "rcs" and "ci" to make the files unusable by
2839 CVS. The same is true of the CVS "admin" command.
2841 Normal RCS practice locks a file on checkout with "co -l". In such
2842 an environment, RCS users should plan to keep survival gear and food
2843 for at least 30 days near their desks. When faced with bizarre and
2844 unexpected permission errors, howling mobs of slavering CVS users will
2845 run the RCS users out of town with pitchforks and machetes.
2847 See 3C.8 for a way to avoid machetes aroused by lock collisions.
2849 Though files checked in by RCS users will correctly cause
2850 "up-to-date" failures during CVS "commits" and they will be
2851 auto-merged into CVS working directories during "update", the opposite
2854 RCS users will get no warning and will not be required to merge older
2855 work into their code. They can easily checkin an old file on top of a
2856 new revision added by CVS, discarding work committed earlier by CVS
2859 See the howling mob scenario described above.
2861 RCS is great. I have used it for years. But I wouldn't mix it this
2862 way. In a two-camp society, you are asking for real trouble, both in
2863 technical hassles to clean up and in political hassles to soothe.
2864 Branch merges will also be a major problem.
2866 Last modified: _6/13/1997_
2868 8. I "updated" a file my friend, "bubba", committed yesterday. Why doesn't
2869 the file now have a modified date of yesterday?
2871 CVS restores dates from the RCS files only on first "checkout". After
2872 that, it is more important to maintain a timestamp relative to the
2873 other files in the working directory.
2875 Example: You committed a source file at 5PM. Bubba updated his copy of
2876 the file, grabbing your changes, then changed and committed a new
2877 revision of the file at 6PM. At 7PM, you compile your file. Then you
2878 execute "update". If CVS sets the date to the one in the RCS file, the
2879 file would be given a timestamp of 6PM and your Makefile wouldn't
2880 rebuild anything that depended on it. Bad news.
2882 Note that the same logic applies to retrieving a revision out of the
2883 Repository to replace a deleted file. If CVS changes your file in an
2884 existing working directory, whether it was because a new revision was
2885 committed by someone else or because you deleted your working file,
2886 the timestamp on the retrieved working file *must* be set to the
2889 When you first retrieve a file, there is no reason to expect any
2890 particular timestamp on the file within your working area. But later,
2891 when dependency checking is performed during a build, it is more
2892 important for the timestamps on the local files to be consistent with
2893 each other than than it is for working files to match the timestamps
2894 on the files in the Repository. See 4D.17 for some more about
2897 Last modified: _6/13/1997_
2899 9. Why do timestamps sometimes get set to the date of the revision,
2900 sometimes not? The inconsistency causes unnecessary recompiles.
2902 The "checkout" command normally sets the timestamp of a working file
2903 to match the timestamp stored on the revision in the Repository's RCS
2906 The "commit" command retains the timestamp of the file, if the act of
2907 checking it in didn't change it (by expanding keywords).
2909 The "update" command sets the time to the revision time the first time
2910 it sees the file. After that, it sets the time of the file to the
2911 current time. See 4D.8 for a reason why.
2913 Here's a two-line PERL program to set timestamps on files based on
2914 other timestamps. I've found this program useful. When you are certain
2915 you don't want a source file to be recompiled, you can set its
2916 timestamp to the stamp on the object file.
2918 #!/usr/local/bin/perl
2920 # Set timestamp of args 2nd-Last to that of the first arg.
2922 ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,$atime,$mtime,$ctime)
2924 utime($atime,$mtime,@ARGV);
2926 Last modified: _6/13/1997_
2928 10. While in the middle of a large "commit", how do I run other commands,
2929 like "diff" or "stat" without seeing lock errors?
2934 The '-n' option to the main cvs command turns off lock checking, a
2935 reasonable act for read-only commands given the promise offered by
2936 '-n' not to alter anything. The "diff", "log" and "stat" commands
2937 provide the same information (for files that are not being committed)
2938 when used with and without the '-n' option.
2940 Warning: Ignoring locks can produce inconsistent information across a
2941 collection of files if you are looking at the revisions affected by an
2942 active commit. Be careful when creating "patches" from the output of
2943 "cvs -n diff". If you are looking only at your working files, tagged
2944 revisions, and BASE revisions (revisions whose numbers are read from
2945 your ./CVS/Entries files), you should get consistent results. Of
2946 course, if you catch a single file in the middle of RCS activity, you
2947 might get some strange errors.
2949 Note that the suggested command is "cvs -n <command>". The visually
2950 similar command "cvs <command> -n" has no relation to the suggested
2951 usage and has an entirely different meaning for each command.
2953 "cvs -n update" also works in the middle of a commit, providing
2954 slightly different information from a plain "cvs update". But, of
2955 course, it also avoids modifying anything.
2957 You could also use the RCS functions, "rlog" and "rcsdiff" to display
2958 some of the information by referring directly to the Repository files.
2960 You need RCS version 5 or later for the commands described above to
2963 Last modified: _6/13/1997_
2965 11. Where did the ./CVS/Entries.Static file come from? What is it for?
2967 Each CVS working directory contains a ./CVS/Entries file listing the
2968 files managed by CVS in that working directory. Normally, if the
2969 "update" command finds a file in the Repository that is not in the
2970 ./CVS/Entries file, "update" copies the appropriate revision of the
2971 "new" file out of the Repository and adds the filename to the Entries
2972 file. This happens for files:
2974 Added to the Repository from another working directory.
2976 Dragged out of the Attic when switching branches with "update -A" or
2979 Whose names were deleted from the ./CVS/Entries file.
2981 If the ./CVS/Entries.Static file exists, CVS will only bring out
2982 revisions of files that are contained in either ./CVS/Entries or
2983 ./CVS/Entries.Static. If a Repository file is found in *neither* file,
2986 The ./CVS/Entries.Static file is created when you check out an
2987 individual file or a module that creates working directories that
2988 don't contain all files in the corresponding Repository directory. In
2989 those cases, without an ./CVS/Entries.Static file, a simple "update"
2990 would bring more files out of the Repository than the original
2993 The ./CVS/Entries.Static file can be removed by hand. It is
2994 automatically removed if you run "update -d" to create new directories
2995 (even if no new directories are created). (Internally, since
2996 "checkout" turns on the '-d' flag and calls the "update" routine, a
2997 "checkout" of a module or directory that writes into an existing
2998 directory will also remove the ./CVS/Entries.Static file.)
3000 Last modified: _6/13/1997_
3002 12. Why did I get the wrong Repository in the loginfo message?
3006 Use multiple Repositories.
3008 Configured CVS to use absolute pathnames in the ./CVS/Repository
3011 Configured CVS not to use the ./CVS/Root file.
3013 Typed the "commit" command in one Repository with your $CVSROOT
3014 pointing at another.
3016 "commit" and all other CVS commands will heed an absolute pathname in
3017 the ./CVS/Repository file (or in the "-d CVSrootdir" override), but
3018 the log function doesn't take arguments -- it just looks at $CVSROOT.
3020 If you avoid even one of the four steps above, you won't see this
3021 problem. If you configure ./CVS/Root, you won't be allowed to execute
3022 the program causing the error.
3024 Last modified: _6/13/1997_
3026 13. How do I run CVS setuid so I can only allow access through the CVS
3029 Setuid to root is not a great idea. Any program that modifies files
3030 and is used by a widely distributed group of users is not a good
3031 candidate for a setuid program. (The worst suggestion I've ever heard
3032 was to make *Emacs* setuid to root.)
3034 Root access on Unix is too powerful. Also, it might not work in some
3035 (secure?) environments.
3037 Running it setuid to some user other than root might work, if you add
3038 this line to main.c near the beginning:
3042 Otherwise it uses *your* access rights, rather than the effective
3045 Also, you have to invent a fake user whose name will show up in
3046 various places. But many sites, especially those who might want a
3047 setuid CVS for "security", want personal accountability -- no generic
3048 accounts. I don't know whether accountability outweighs file security.
3050 And finally, unless you take action to limit the "admin" command, you
3051 are leaving yourself unprotected anyway.
3053 Last modified: _6/13/1997_
3055 14. How about using groups and setgid() then?
3057 Here is a way to run CVS setgid in some environments:
3059 Stick this near the front of the main() in main.c:
3063 This will allow "access" to work on systems where it only works on the
3066 Create a group named "cvsg". (This example uses "cvsg". You can name
3069 Put *no* users in the "cvsg" group. You can put Repository
3070 administrators in this group if you want to.
3072 Set the cvs executable to setgid (not setuid):
3074 cd /usr/local/bin; chown root.cvsg cvs; chmod 2755 cvs
3076 Make sure every file in the Repository is in group "cvsg":
3078 chown -R root.cvsg $CVSROOT
3080 Change all directory permissions to 770. This allows all access to
3081 the files by the "cvsg" group (which has no members!) and no access at
3084 find $CVSROOT -type d -exec chmod 2770 {} \;
3086 On some systems you might have to type:
3088 find $CVSROOT -type d -exec chmod u=rwx,g=rwx,o=,g+s {} \;
3090 This should allow only the cvs program (or other "setgid to group
3091 cvsg") programs to write into the area, but no one else. Yes the user
3092 winds up owning the file, but s/he can't find it again later since
3093 s/he can't traverse the tree. (If you enable the world execute bit
3094 (mode 2771) on directories, users can traverse the tree and the user
3095 who last wrote the file can still write to it.)
3097 If you want to allow read access, check out an entire tree somewhere.
3098 You have to do this anyway to build it.
3100 Note: If you are using a stupid file system that can't inherit file
3101 groups from the parent directory (even with the "setgid" (Octal 2000)
3102 bit set), you might have to modify CVS (or RCS) to reset the group
3103 every time you create a new file. I have not tested this.
3105 The setgid() method shares with the setuid() method the problem of
3106 keeping "admin" from breaking things.
3108 Last modified: _6/13/1997_
3110 15. How do I use the "commitinfo" file?
3114 The "commitinfo" file allows you to execute "sanity check" functions
3115 before allowing a commit. If any function called from within the
3116 commitinfo file exits with a non-zero status, the commit is denied.
3118 To fill out a "commitinfo" file, ask yourself (and those sharing your
3119 Repository) these questions:
3121 - Is there anything you want to check or change before someone is
3122 allowed to commit a file? If not, forget commitinfo.
3124 If you want to serialize binary files, you might consider something
3125 like the rcslock.pl program in the contrib directory of the CVS
3128 - Do you want to execute the same exact thing before committing to
3129 every file in the Repository? (This is useful if you want to program
3130 the restrictions yourself.) If so, set up a single line in the
3133 DEFAULT /absolute/path/to/program
3135 CVS executes the program once for each directory that "commit"
3136 traverses, passing as arguments the directory and the files to be
3137 committed within that directory.
3139 Write your program accordingly. Some examples exist in the contrib
3142 - Do you want a different kind of sanity check performed for different
3143 directories? If so, you'll have to decide what to do for all
3144 directories and enter lines like this:
3146 regexp1 /absolute/path/to/program-for-regexp1
3147 regexp2 /absolute/path/to/program-for-regexp2
3148 DEFAULT /absolute/path/to/program-for-all-else
3150 - Is there anything you want to happen before *all* commits, in
3151 addition to other pattern matches? If so, include a line like this:
3153 ALL /absolute/path/to/program
3155 It is executed independently of all the above. And it's repeatable --
3156 you can have as many ALL lines as you like.
3158 Last modified: _6/13/1997_
3160 16. How do I use the "loginfo" files?
3162 See 4B.2 and the "commitinfo" question above.
3164 The "loginfo" file has the same format as the "commitinfo" file, but
3165 its function is different. Where the "commitinfo" information is used
3166 before a commit, the "loginfo" file is used after a commit.
3168 All the commands in the "loginfo" file should read data from standard
3169 input, then either append it to a file or send a message to a mailing
3170 list. If you want to make it simple, you can put shell (the shell used
3171 by "popen(3)") command lines directly in the "loginfo" (or
3172 "commitinfo") file. These seem to work:
3174 ^special /usr/ucb/Mail -s %s special-mailing-list ^other /usr/ucb/Mail
3175 -s %s other-mailing-list DEFAULT (echo '===='; echo %s; cat) >
3176 /path/name/to/log/file
3178 Last modified: _6/13/1997_
3180 17. How can I keep people with restrictive umask values from blocking
3181 access to the Repository?
3183 If a user creates a new file with restricted permissions (e.g. 0600),
3184 and commits it, the Repository will have a file in it that is
3185 unreadable by everyone. The 0600 example would be unreadable by
3186 *anyone* but root and the user who created it.
3188 There are 3 solutions to this:
3190 Let it happen. This is a valid way to protect things. If everyone is
3191 working alone, a umask of 077 is OK. If everyone is working only in
3192 small groups, a umask of 007 is OK.
3194 Train your users not to create such things if you expect to share
3197 See 4B.5 for a small script that will reset the umask.
3199 I personally don't like the idea of a program automatically
3200 *loosening* security. It would be better for you all to talk about the
3201 issue and decide how to work together.
3203 Last modified: _6/13/1997_
3205 Category: /Commands_/
3209 Category: /Commands_/add_ad_new/
3211 " + "add", "ad", "new""
3213 1. What is "add" for?
3215 To add a new directory to the Repository or to register the desire to
3216 add a new file to the Repository.
3218 The directory is created immediately, while the desire to add the file
3219 is recorded in the local ./CVS administrative directory. To really add
3220 the file to the Repository, you must then "commit" it.
3222 Last modified: _6/13/1997_
3224 2. How do I add a new file to the branch I'm working on?
3226 The user actions for adding a file to any branch, including the Main
3227 Branch, are exactly the same.
3229 You are in a directory checked out (or updated) with the '-A' option
3230 (to place you on the Main Branch) or the "-r <branch_tag>" option (to
3231 place you on a branch tagged with <branch_tag>). To add <file> to the
3232 branch you are on, you type:
3237 If no ./CVS/Tag file exists (the '-A' option deletes it), the file
3238 will be added to the Main Branch. If a ./CVS/Tag file exists (the "-r
3239 <branch_tag>" option creates it), the file will be added to the branch
3240 named (i.e. tagged with) <branch_tag>.
3242 Unless you took steps to first add the file to the Main Branch, your
3243 new file ends up in the Attic.
3245 Last modified: _6/13/1997_
3247 3. Why did my new file end up in the Attic?
3249 The file is thrown into the Attic to keep it from being visible when
3250 you check out the Main Branch, since it was never committed to the
3253 Last modified: _6/13/1997_
3255 4. Now that it's in the Attic, how do I connect it to the Main branch?
3257 That can be considered a kind of "merge". See 4C.8
3259 Last modified: _6/13/1997_
3261 5. How do I avoid the hassle of reconnecting an Attic-only file to the Main
3264 You create it on the Main Branch first, then branch it.
3266 If you haven't yet added the file or if you decided to delete the new
3267 Attic file and start over, then do the following: (If you added the
3268 file (or worse, the 157 files) to the Attic and don't want to start
3269 over, try the procedure in 4C.8.)
3271 Temporarily remove the sticky branch information. Either:
3273 Move the whole directory back to the Main Branch. [This might not be
3274 a good idea if you have modified files, since it will require a merge
3281 Move the ./CVS/Tag file out of the way.
3283 mv ./CVS/Tag HOLD_Tag
3285 Add and branch the file "normally":
3289 cvs tag -b <branch_tag> <file>
3291 [<branch_tag> is the same Branch Tag as you used on all the other
3292 files. Look at ./CVS/Entries or the output from "cvs stat" for sticky
projects / alioth / cvs.git / blob