Revert "adjust the testsuite to the new behaviour", it was wrong
[alioth/cvs.git] / FAQ
1 -------------------------------------------------------------------------------
2
3    CVS is Copyright (C) 1989-2005 The Free Software Foundation, Inc.
4
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)
8    any later version.
9
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
13    License.
14
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.
19
20 -------------------------------------------------------------------------------
21
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.
29
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
35 grains of salt.
36
37 Since August, 2005, many of the existing CVS resources have been centralized on
38 <http://cvs.nongnu.org> & <http://ximbiot.com>.
39
40   Category: /, all questions
41   
42   Category: /
43   
44           " [INLINE] "
45           
46     1. About FAQ-O-Matic 
47     
48 This is FAQ-O-Matic, a quick-and-dirty Perl hack (aren't they all?) by
49 Jon Howell.
50
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?
55
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.
59
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.
63
64 Guidelines for submissions:
65
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.
68
69 2. Please _use HTML only conservatively_ in your entries. Links are appropriate
70 ,
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
74 .
75
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.
78
79 4. Please _leave an email address_ at the bottom of your submission so that oth
80 ers
81 can drop you a note.
82
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
85 h
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.
89
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
93 don't overdo it. :v)
94
95           Last modified: _6/13/1997_
96           
97     2. Adding a new category ? 
98     
99 try to get bug-cvs@nongnu.org to help you.
100
101
102           Last modified: _12/09/2004_
103           
104   Category: /Advanced_Topics_/
105   
106           " Advanced Topics "
107           
108   Category: /Advanced_Topics_/Branching_and_Mergin/
109   
110           " + Branching and Merging"
111           
112     1. What is a branch? 
113     
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:
118           
119      How Humans use the word "branch":
120           
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.
126           
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.)
133           
134           Essentially, the word "branch" implies a way to allow
135           simultaneous development on the same files by multiple people.
136           
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.
141           
142      How CVS uses the word "branch":
143           
144           CVS uses the word "branch" in a number of ways. The two most
145           important are:
146           
147           - The vendor branch holds releases from (normally) an outside
148           software vendor. It is implemented using a specific RCS branch
149           (i.e. 1.1.1).
150           
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".
155           
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
159           the same time:
160           
161           - The RCS 1.1.1 branch.
162           - The CVS Vendor branch.
163           - The CVS "Main Branch".
164           
165           The concepts overlap, but they are not equivalent.
166           
167           In referring to CVS, "branch" can be used in four other ways:
168           
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
172           files.
173           
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
180           checked out.
181           
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
186           branch).
187           
188           - And, of course, CVS uses "branch" to indicate a
189           human-oriented "branch in development".
190           
191      How RCS uses the word "branch":
192           
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?)
197           
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".
205           
206    Last modified: _6/13/1997_
207    
208     2. Why (or when) would I want to create a branch? 
209     
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
213    or small) is done.
214    
215    The four major situations when you should create a branch:
216    
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.
220    
221      When you want to be able to "commit" and "tag" your work repeatedly
222    without affecting others.
223    
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.)
227    
228      When you need to share code among a group of developers, but not the
229    whole development organization working on the files.
230    
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
235    theirs.
236    
237      When you need to make minor changes to a released system.
238    
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.
245    
246    Last modified: _6/13/1997_
247    
248     3. How do I create and checkout a branch? 
249     
250    Suggested technique:
251    
252      Attach a non-branch tag to all the revisions you want to branch
253    from. (i.e. the branch point revisions)
254    
255      When you decide you really need a branch, attach a branch tag to the
256    same revisions marked by the non-branch tag.
257    
258      "Checkout" or "update" your working directory onto the branch.
259    
260      Suggested procedure when using modules:
261    
262      cvs rtag <branch_point_tag> module
263    
264      cvs rtag -b -r <branch_point_tag> <branch_tag> <module>
265    
266      cvs checkout -r <branch_tag> module
267    
268      Suggested procedure when using your working directory, which
269    contains the revisions of your working files you want to branch from:
270    
271      cvs tag <branch_point_tag>
272    
273      cvs rtag -b -r <branch_point_tag> <branch_tag> <module>
274    
275      cvs update -r <branch_tag>
276    
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
281    future.
282    
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.
287    
288    Step B.2 has two corollaries:
289    
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.
293    
294      The <module> can be a relative path to a directory from which your
295    working directory was checked out.
296    
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.
300    
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
306    <tag>.
307    
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.
310    
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).
315    
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.
320    
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>.)
328    
329                 <branch_point_tag>      Matching <branch_tag>
330
331                 bp_V1_3                 V1_3
332                 bp_Release2-3-5         Release2-3-5
333                 bp_Production4_5        Release4_5
334
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>.)
344    
345                 <branch_point_tag>      Matching <branch_tag>
346
347                 V1_3                    latest_V1_3
348                 Release2-3-5            latest_Release2-3-5
349                 Release4_5              latest_Production4_5
350
351    In both styles you can find out what you had to change since the
352    original release of this Version by typing:
353    
354             cvs diff -r <branch_point_tag> -r <branch_tag>
355
356    For Style 1, this is:
357    
358             cvs diff -r bp_<branch_tag> -r <branch_tag>
359
360    For Style 2, this is:
361    
362             cvs diff -r <branch_point_tag> -r latest_<branch_point_tag>
363
364    Notes on "being on a branch":
365    
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
368    ./CVS/Entries).
369    
370    - A "sticky" <tag> (including a <branch_tag>) causes most CVS commands
371    to act as if "-r <tag>" were on the command line.
372    
373    - A "sticky" <branch_tag> indicates that the working directory (and
374    working files) are "on the branch".
375    
376    Last modified: _6/13/1997_
377    
378     4. Once created, how do I manage a branch? 
379     
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
383    track of it.
384    
385    Specifically, you must:
386    
387    - Remember that the branch exists. (This is non-trivial if you create
388    a lot of them.)
389    
390    - Plan when to merge it back into the main line of development.
391    
392    - Schedule the order that multiple branch merges are to be done.
393    
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.
398    
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.
403    
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.
408    
409    Last modified: _6/13/1997_
410    
411     5. Are there any extra issues in managing multiple branches? 
412     
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.
418    
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.
423    
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.
431    
432    Last modified: _6/13/1997_
433    
434     6. How do I merge a whole branch back into the trunk? 
435     
436    If you don't have a working directory, you can checkout and merge in
437    one command:
438    
439                 cvs checkout -j <branch_tag> <module>
440                 cd <module>
441
442    If you already have a working directory:
443    
444                 cd <working_directory>
445                 cvs update      <== Optional, to bring it up to date.
446                 cvs update -j <branch_tag>
447
448    CVS will print lines beginning with
449    
450    'U' for files that you hadn't changed, but the branch did.
451    
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.)
455
456    'C' for files that you both changed in a way that conflicts
457                 with each other.
458
459    You need to go edit all the 'C' files and clean up the conflicts. Then
460    you must commit them.
461    
462    Last modified: _6/13/1997_
463    
464     7. How do I merge changes from the trunk into my branch or between
465     branches? 
466     
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.
470    
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
473    -r":
474    
475                 cvs update -r <branch_tag> {optional files}
476
477    Then merge the changes from the trunk into your working branch using
478    the pseudo-tag named "HEAD":
479    
480                 cvs up -j HEAD {optional files}
481
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
486    (currently) works.
487    
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
492    to use).
493    
494      You can merge the difference between any two <tags> using two "-j"
495    options on "update" or "checkout".
496    
497    Identify the two tags on the branch you want to merge from.
498    
499                 cvs update -j <tag1> -j <tag2> {optional files}
500
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
505    tags.
506    
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
509    branch points.
510    
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.
516    
517      To "take" revisions from other branches instead of merging them, see
518    4C.19 for an idea.
519    
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
522    
523                 cvs update -A {optional files}
524                 cvs update -j <branch_tag> {optional files}
525                 cvs commit
526                 cvs tag -F  -b <same_branch_tag> {optional files}
527
528    See part B of 4D.5
529    
530      Other oddities.
531    
532    This also works, but is probably not officially supported:
533    
534                    cvs update -j N {optional files}
535
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:
540    
541                    cvs update -j 1 {optional files}
542
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.
545    Then:
546    
547                    cvs update -j 1 {optional files}
548
549    will merge the changes from 1.2 to 1.4
550    
551                    cvs update -j 2 {optional files}
552
553    will merge the changes from 1.2 to 2.3
554    
555                    cvs update -j 3 {optional files}
556
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.
559    
560    The intuitive (at least to me):
561    
562                    cvs up -j MAIN (or TRUNK) {optional files}
563
564    doesn't work. If the trunk (i.e. "main branch") had an implicit branch
565    named "MAIN", you could use:
566    
567                    cvs up -j MAIN:10/26 -j MAIN:now {optional files}
568
569    and refer to date-stamped revisions on the trunk using the
570    <branch_tag>:<date> support that works on other branches.
571    
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.
575    
576    [[If you find working techniques, I'll add them here.]]
577    
578    Last modified: _6/13/1997_
579    
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) 
582     
583    For how such a file can exist, see 3A.2 and 3A.3.
584    
585    For how to avoid creating such a file, see 3A.5.
586    
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:
591    
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.
595    
596    It is exactly like resurrecting a removed file. See 3L.4
597    
598    I use something like this: (csh-like syntax)
599    
600    set repos = `cat ./CVS/Repository` mv $repos/Attic/filename,v
601    $repos/filename,v
602    
603    (If you use relative paths in your Repository files, that first line
604    becomes: set repos = $CVSROOT/`cat ./CVS/Repository`)
605    
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.
609    
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.
615    
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:
618    
619                 cvs tag -F -b <branch_tag> <file>
620
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
623    this procedure.
624    
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.
629    
630    Last modified: _6/13/1997_
631    
632     9. How do I know what branch I'm (working) on? 
633     
634    Type:
635                 cvs status
636
637    and look at the "Sticky Tag" field for each file. If:
638    
639      The *same* tag is on *every* file in your working tree, *and*
640    
641      That tag matches the contents of the ./CVS/Tag file, *and*
642    
643      That tag is a branch tag,
644    
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
647    status".
648    
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.
653    
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.
657    
658    To force your entire working directory onto the same branch, type:
659    
660                 cvs update -r <branch_tag>
661
662    Last modified: _6/13/1997_
663    
664     10. Do I really have to know the name of the branch I'm working on? 
665     
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.
669    
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.
678    
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.
682    
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".
686    
687    Last modified: _6/13/1997_
688    
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? 
691     
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
695    branch.
696    
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
701    refer to it.
702    
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
705    4C.3.
706    
707    Last modified: _6/13/1997_
708    
709     12. Why didn't the command "cvs admin -bBRANCH1 *" create a branch? 
710     
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.
715    
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.
719    
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
722    CVS depends on.
723    
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
728    results.
729    
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
733    default branch.
734    
735    Last modified: _6/13/1997_
736    
737     13. Is it possible to set the "default CVS branch" for everyone? 
738     
739    No. It doesn't work that way.
740    
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.
745    
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".
748    
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
751    currently works.
752    
753    Last modified: _6/13/1997_
754    
755     14. How do I perform a large merge? 
756     
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.
760    
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.
763    
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:
767    
768                 cvs checkout <module>
769                 cd <module>
770                 cvs tag -b <branch_tag>
771                 cvs update -r <branch_tag>
772                 >>> Edit away.
773                 cvs commit              <<== Onto branch
774
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.)
780    
781                 cvs update -A
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.
785                 cvs commit
786
787    Looks simple. For more details on the output from the "update -j"
788    command, see 3P.2 and 4C.6.
789    
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:
793
794                         cvs checkout -j <branch_tag> <module>
795                         cd <module>
796
797      The paranoid way is more difficult, but it can catch all sorts of
798    problems. You created the branch this way:
799    
800                 cvs checkout <module>
801                 cd <module>
802                 cvs tag <branch_point_tag>
803                 cvs tag -b <branch_tag>
804                 cvs update -r <branch_tag>
805                 >>> Edit away.
806                 cvs commit              <<== Onto branch
807
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
810    the merge:
811    
812                 cvs tag <latest_on_branch_tag>
813                 cvs update -A
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.
821            *3*  cvs diff
822                 >>> Verify that *3* matches *1*, except for line numbers.
823                 cvs commit
824                 cvs tag <just_merge_changes_tag>
825                 >>> Edit some more to make it all compile and work.
826                 cvs commit
827                 cvs tag <after_merge_cleanup_tag>
828
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.
833    
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.
839    
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
842    merge.
843    
844    Last modified: _6/13/1997_
845    
846     15. Is a Vendor merge any different from a branch merge? 
847     
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
851    is the same.
852    
853    See the "import" command in section 3H.
854    
855    Last modified: _6/13/1997_
856    
857     16. How do I go back to a previous version of the code on a branch? 
858     
859
860
861
862         You can avoid digging into RCS revision numbers (executing "update
863         -r (rev)" on each file) by trying one of these:
864
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
869            -r (non-branch-tag)"
870
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)".
875
876 Use the "update -r (branch-tag):(date)" trick.
877
878            This is almost like using the '-D' option, but it looks for
879            revisions extant on (date) only along the given branch.
880
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
883            middle of a branch.
884
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]
889
890
891 You can branch a branch.
892
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?)
901
902
903 (fixed formatting, kingdon@cyclic.com)
904
905    Last modified: _9/8/1997_
906    
907     17. Once I've found the files I want, how do I start changing them? I keep
908     getting warnings about sticky tags. 
909     
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
913    branch to work on.
914    
915    You have two choices.
916    
917      You can do it in place and keep working:
918    
919            cvs tag -b <branch_tag>      <<== To tag the current files.
920            cvs update -r <branch_tab>   <<== To move onto the branch.
921
922      You can do it "externally" and create a new working directory:
923    
924            cvs rtag -b -r <tag> <branch_tag> <module>
925            cvs checkout -r <branch_tag> <module>
926
927    <module> can be a relative path within the Repository.
928    
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.
933
934    Last modified: _6/13/1997_
935    
936     18. Why do I get the latest files on the branch when I tried to "update -r
937     <tag>"? 
938     
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.
944    
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.
947    
948    Last modified: _6/13/1997_
949    
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. 
952     
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:
955    
956      Move your working directory to the Main Branch.
957    
958                 cvs update -A
959
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
964    
965    foreach i (Makefile *.cc *.hh)
966                     cvs update -p -r <branch_tag> $i > $i
967                 end
968
969      Commit all the working files onto the Main Branch.
970    
971                 cvs commit -m 'Moved branch <branch_tag> onto MAIN'
972
973    You should experiment with the above before blasting everything.
974    
975    Last modified: _6/13/1997_
976    
977     20. How to I avoid merge collisions in the RCS $\Log$ data? 
978     
979    In short, you can't. The RCS $\Log$ keyword is handled differently
980    from all other RCS keywords.
981    
982    On the info-cvs mailing list, there is a periodic discussion that goes
983    something like this:
984    
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.
988    
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.
992    
993    For developers:
994    
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
1000    world.
1001    
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:
1005    
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."
1009    
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
1014    command.
1015    
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.
1020    
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
1023    log.
1024    
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.
1031    
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.
1037    
1038    Last modified: _6/13/1997_
1039    
1040     21. Why should I trust automatic merges? 
1041     
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.
1045    
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.
1050    
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.
1054    
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
1058    decision.
1059    
1060    Last modified: _6/13/1997_
1061    
1062     22. How does CVS decide if it can safely perform a merge? 
1063     
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,
1068    not if it *can*.
1069    
1070    See 2B.6 for how the merge proceeds.
1071    
1072    Last modified: _6/13/1997_
1073    
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? 
1076     
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.
1080    
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
1084    file.
1085    
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.
1089    
1090    Last modified: _6/13/1997_
1091    
1092   Category: /Advanced_Topics_/Engineering/
1093   
1094    " + Engineering"
1095    
1096     1. Where can I find out about Software Engineering? 
1097     
1098    A couple different people suggested this book:
1099    
1100    Software Configuration Management: Coordination for Team Productivity;
1101    Wayne A. Babich; Addison Wesley; 1986; ISBN 0-201-10161-0
1102    
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.
1108    
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
1113    frightening.
1114    
1115    Last modified: _6/13/1997_
1116    
1117     2. How do I flexibly arrange the modules file to describe my sources? 
1118     
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.
1122    
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.
1130    
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.
1137    
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
1140    uses.
1141    
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.
1145    
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.
1149    
1150            pr1  -a P1 HELPERS
1151            pr2  -a P2 HELPERS
1152            pr3  -a P3 HELPERS
1153            pr12 -a P1 P2 HELPERS
1154            pr13 -a P1 P3 HELPERS
1155            pr23 -a P2 P3 HELPERS
1156
1157            P1           -a group1/proj1
1158            P2           -a group1/proj2
1159            P3           -a group1/proj3
1160            HELPERS      -a group1/helper1 group1/helper2 MAKEFILE
1161            MAKEFILE     -a group1/Makefile
1162
1163    Actual Repository directory structure: (from $CVSROOT down)
1164    
1165    group1/ Makefile The top level Makefile. helper1/ helper2/ Helper
1166    files and dirs proj1/ Files and dirs proj2/ Files and dirs proj3/
1167    Files and dirs
1168    
1169    "checkout group1" produces a duplicate of the above. "checkout projX"
1170    produces all but "projY" and "projZ". "checkout projXY" produces all
1171    but "projZ".
1172    
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.
1176    
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
1180    example above.
1181    
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
1188
1189            HELPERS      -a helper1 helper2 group1-Makefile
1190            helper1      group1/helper1
1191            helper2      group1/helper2
1192            group1-Makefile -d . group1 Makefile
1193
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.
1198    
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".
1203    
1204      A short one containing the basic "module" actions:
1205    
1206            m1           head/path file1 dir2 file3 dir4 file5
1207
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
1211    $CVSROOT/head/path.
1212    
1213      Here's another way to construct a working directory out of pieces of
1214    the Repository:
1215    
1216                 projX   projX Makefile &projX_inc &projX_src &projX_doc
1217
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.
1221
1222    projX_inc -d include projX/inc projX_src -d source projX/src projX_doc
1223    -d documentation projX/doc
1224    
1225      A Unix tree. This is similar to what CVS was developed for and the
1226    way I have used it for years.
1227    
1228                 # Top level
1229                 unix            unix
1230                 u_bin           unix/bin
1231                 u_etc           unix/etc
1232                 u_man           unix/man
1233                 usr-bin         unix/usr.bin
1234
1235                 # Subdirs of top level dirs.  (tiny subset)
1236                 ls              unix/bin/ls
1237                 fsck            unix/etc/fsck
1238                 man8            unix/man/man8
1239
1240                 # Programs without subdirs. (tiny subset)
1241                 cat             unix/bin Makefile cat.c
1242                 uniq            unix/usr.bin Makefile uniq.c
1243
1244                 # /usr/local/src
1245                 localsrc        localsrc
1246                 gnu             localsrc/gnu
1247                 public          localsrc/public
1248                 X11             localsrc/X11
1249
1250                 # GNU and PD tools
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
1256
1257                 # X11 related items.
1258                 tvtwm           localsrc/X11/contrib/tvtwm
1259
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.
1263    
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.
1268    
1269    I found it very handy to be able to run "ls" and see the three tools I
1270    was porting that week.
1271    
1272    Last modified: _6/13/1997_
1273    
1274     3. Can I have multiple source repositories, one for each project? 
1275     
1276    Yes, you can have as many Repositories as you like. But each
1277    Repository must be managed separately, creating additional work.
1278    
1279    Question 4A.1 provides a short description of setting up a single
1280    Repository. A few additional considerations:
1281    
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.
1286    
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.
1291    
1292      Disk space should not be a factor since you can build up a
1293    Repository using symbolic links and/or remote mounts.
1294    
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.
1300    
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.
1307    
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.
1311    
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.
1318    
1319    Last modified: _6/13/1997_
1320    
1321     4. Who should administer the Repository and manage the modules file? 
1322     
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:
1329    
1330    Situation 1.
1331    
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.
1335    
1336    Modules and Repository admin was mostly left to me. I never found a
1337    problem in minor changes made by anyone else.
1338    
1339    Situation 2.
1340    
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
1344    thought.
1345    
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.
1350    
1351    Situation 3.
1352    
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.
1355    
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
1361    under him.
1362    
1363    Situation 4.
1364    
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.
1369    
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
1376    been.
1377    
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.
1380    
1381    Situation 5.
1382    
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.
1386    
1387    No one else in the world was allowed to touch anything.
1388    
1389    Situation 6.
1390    
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.
1396    
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.
1404    
1405    Last modified: _6/13/1997_
1406    
1407     5. Isn't disk space a big factor? CVS copies files out of the Repository,
1408     duplicating everything. 
1409     
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*
1412    filled up?
1413    
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.
1419    
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.
1426    
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
1433    management refrain.
1434    
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.
1439    
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.
1444    
1445    The "economy" of disk storage media will never remove the need to
1446    manage disk space.
1447    
1448    So, here's an un-reviewed suggestion originally from Graydon Dodson
1449    <grdodson@lexmark.com>, which I've altered and edited heavily.
1450    
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.
1455    
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
1458    /master/build tree.
1459    
1460    This tool should also provide real copies of, not symlinks to, all the
1461    files within the CVS administrative directories.
1462    
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.
1468    
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>
1472    
1473                 #!/bin/csh -f
1474                 set f = $1
1475                 if (! -l $f) then
1476                    echo "file $f is not a symlink"
1477                    exit 1
1478                 endif
1479                 rm $f
1480                 set rev = `grep "^/$f/" CVS/Entries | awk -F/ '{print $3}'`
1481                 cvs update -p -r $rev $f > $f
1482
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
1487    revisions.
1488    
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.
1492    
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:
1496    
1497      ./<file> is a symlink.
1498    
1499      ./CVS/Entries says you are revision 1.2.
1500    
1501      The corresponding CVS/Entries file in /master/build says the latest
1502    revision is 1.3.
1503    
1504      cvs update <file> shows a 'C' conflict flag.
1505    
1506    Last modified: _6/13/1997_
1507    
1508   Category: /Advanced_Topics_/Installing_CVS/
1509   
1510    " + Installing CVS"
1511    
1512     1. What do I have to do before I install CVS? 
1513     
1514      You must decide where to set up a Repository.
1515    
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
1519    both copies.
1520    
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
1524    used.
1525    
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
1528    files.
1529    
1530    See Section 4B. For multiple Repositories, see 4G.3
1531    
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.
1534    
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.
1537    
1538      Read the README, INSTALL-CVS and ChangeLog files to see what you are
1539    getting into.
1540    
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.
1545    
1546    Someone at your site should probably be on the info-cvs mailing list.
1547    See 1B.5.
1548    
1549    Last modified: _6/13/1997_
1550    
1551     2. How do I configure the CVS programs? 
1552     
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.
1556    
1557      Execute the ./configure command.
1558    
1559      Type "make".
1560    
1561      After running "make" you might try running the "sanity.sh" script:
1562    ./src/sanity.sh `pwd`/src/cvs
1563    
1564    It writes into /tmp/cvs-sanity by default.
1565    
1566      Finish reading the INSTALL-CVS file and test out the system.
1567    
1568    Last modified: _6/13/1997_
1569    
1570     3. What do I have to install? 
1571     
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".
1575    
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
1578    of the CVS sources.
1579    
1580      You'll need to edit the Repository control files created by
1581    "cvsinit".
1582    
1583      Install any helper programs mentioned in the modules file.
1584    
1585    Last modified: _6/13/1997_
1586    
1587     4. How do I work around the merge problems in GNU diff version 2.1 or
1588     later? 
1589     
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
1592    
1593    Last modified: _6/13/1997_
1594    
1595   Category: /Advanced_Topics_/Internal_errors/
1596   
1597    " + Internal errors"
1598    
1599     1. Explain: "ci error: unexpected EOF in diff output" 
1600     
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:
1603    
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.
1607    
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.)
1611    
1612    Last modified: _6/13/1997_
1613    
1614     2. Explain: "RCS file /Repository/module/file.c,v is in use" 
1615     
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.
1619    
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.
1625    
1626    Last modified: _6/13/1997_
1627    
1628     3. Explain: "co error, line 2: Missing access list" 
1629     
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.
1632    
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.
1635    
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
1639    in it.
1640    
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
1645    
1646    Last modified: _6/13/1997_
1647    
1648     4. Explain: "error: RCS file name `xyz .c' contains white space" 
1649     
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.
1653    
1654    Last modified: _6/13/1997_
1655    
1656     5. Explain: cvs checkout: warning: <X> is not (any longer) pertinent 
1657     
1658    This message occurs in three instances:
1659    
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.
1662    
1663    If the working file exists, and hasn't changed (determined from the
1664    timestamp) it is removed.
1665    
1666      When you try to check out a piece of the Repository with:
1667    
1668    cvs checkout some/place/in/repository/tree
1669    
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.
1672    
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:
1676    
1677                 cvs checkout: cannot find module `<module/path>' - ignored
1678
1679    If it finds some set of prefix directories, it prints the message you
1680    see.
1681    
1682    In practice this is usually a spelling error.
1683    
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.
1687    
1688    Last modified: _6/13/1997_
1689    
1690     6. Why did a Repository file change from <file>,v to ,<file>,? 
1691     
1692    This is an RCS problem, since the ,<file>, syntax for file names is
1693    used by RCS and not CVS.
1694    
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.
1699    
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:
1703    
1704    rm <file>,v; ln ,<file>, <file>,v; rm ,<file>,
1705    
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.
1710    
1711    Recovery:
1712    - If only the ,<file>, exists, rename it to <file>,v.
1713    
1714    - If both ,<file>, and <file>,v exist and are linked, remove the
1715    ,<file>, file.
1716    
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.
1720    
1721    Last modified: _6/13/1997_
1722    
1723   Category: /Advanced_Topics_/Other_Systems/
1724   
1725    " + Other Systems"
1726    
1727     1. I use a NeXT. Is there anything I need to know? 
1728     
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.
1733    
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.
1738    
1739    CVSPalette is no longer in its announced place:
1740    
1741                 ftp.cs.orst.edu:/pub/next/submissions
1742
1743    though I did find two other interesting files on ftp.cs.orst.edu:
1744    
1745                 /software/NeXT/sources/tools/cvs-next-2_1_1.tar.Z
1746
1747    which is a port of CVS 1.3 (along with RCS and diff) and:
1748    
1749                 /software/NeXT/sources/programming/cvs.postamble-2.4.gz
1750
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.
1754    
1755    [[Anyone know the truth about CVS and NeXT?]]
1756    
1757    Last modified: _6/13/1997_
1758    
1759     2. I use OS/2 and/or DOS and/or Windows. Is there anything I need to know? 
1760     
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:
1764    
1765         WRONG:  CVSROOT=C:\SRC\CVSROOT
1766
1767         RIGHT:  CVSROOT=:local:C:\SRC\CVSROOT
1768
1769    (larry.jones@sdrc.com)
1770    
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".
1776    
1777    Erik van Linstee offers an OS/2 and a DOS port of CVS 1.3 in:
1778    
1779    ftp.informatik.tu-muenchen.de:/pub/comp/os/os2/gnu/devtools or
1780    ftp.rrzn.uni-hannover.de:/pub/os2-local
1781    
1782    The files are named:
1783    
1784                 cvs13p?[bs].zip
1785
1786    Where the ? stands for the patch level (currently 8) and the b is for
1787    the binaries, the s for the sources.
1788    
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).
1791    
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
1794    it.
1795    
1796    [[Updates?]].
1797
1798    Last modified: _9/22/1997_
1799    
1800     3. I use SCO Unix. Is there anything I need to know? 
1801     
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-]]
1807    
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
1812    input.
1813                                 Contributed by Joe Drumgoole
1814
1815    Last modified: _6/13/1997_
1816    
1817     4. I use AIX. Is there anything I need to know? 
1818     
1819    The only report on AIX claims to have no trouble using it in concert
1820    with SunOS and IRIX platforms.
1821    
1822    Last modified: _6/13/1997_
1823    
1824     5. I use IRIX. Is there anything I need to know? 
1825     
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"
1828    data through NIS.
1829    
1830    Last modified: _6/13/1997_
1831    
1832     6. I use an HP system. Is there anything I need to know? 
1833     
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
1837    somewhere.
1838    
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.
1843    
1844                                 Contributed by Paul Eggert
1845
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).
1853    
1854                                 Contributed by Dale Woolridge
1855
1856    Last modified: _6/13/1997_
1857    
1858     7. I use AFS. Is there anything I need to know? 
1859     
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.
1866    
1867                                 Contributed by Michael Ganzberger
1868
1869    [[This was against CVS 1.3. Is it still in CVS 1.4?]]
1870    
1871    Last modified: _6/13/1997_
1872    
1873     8. I use A/UX. Is there anything I need to know? 
1874     
1875    [[??]]
1876    
1877    Last modified: _6/13/1997_
1878    
1879   Category: /Advanced_Topics_/Related_Software/
1880   
1881    " + Related Software"
1882    
1883     1. How do I use CVS under Emacs? Is there an Emacs cvs-mode? 
1884     
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.
1893    
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.
1897    
1898                                 Contributed by Jeffrey M Loomis
1899
1900    Last modified: _6/13/1997_
1901    
1902     2. What is GIC (Graphical Interface to CVS)? 
1903     
1904
1905
1906
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.
1911         
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
1915         instead.
1916
1917         For more on tkCVS, see
1918         <http://ximbiot.com/cvs/cvshome/dev/addontkcvs.html>.
1919
1920         kingdon@cyclic.com
1921
1922    Last modified: _9/6/1997_
1923    
1924     3. What is CAVEMAN? 
1925     
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.
1928    
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.
1936    
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.)
1939    
1940    contact Kathleen Dyer kdyer@llnl.gov
1941                                 (510)423-6803
1942                                 (510)423-5112 FAX
1943
1944    [[Does someone want to elaborate?]]
1945    
1946    Last modified: _6/13/1997_
1947    
1948   Category: /Advanced_Topics_/Setting_up_and_Manag/
1949   
1950    " + Setting up and Managing the Repository"
1951    
1952     1. What do I do first? How do I create a Repository? 
1953     
1954    First, install all the programs. (See Section 4A.)
1955    
1956    Then create a Repository by executing "cvs -d init". (This works with
1957    CVS 1.9.)
1958    
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
1962    "cvs commit".
1963    
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:
1968    
1969                 local   local
1970
1971                 gnu     local/gnu
1972                 emacs   local/gnu/emacs
1973                 cvs     local/gnu/cvs
1974
1975                 public  local/public
1976                 pdprog1 local/public/pdprog1
1977                 pdprog2 local/public/pdprog2
1978
1979                 test    test
1980                 junk    test/junk
1981
1982    Andreas Kostyrka
1983    
1984    Last modified: _4/21/1998_
1985    
1986     2. What are those files in $CVSROOT/CVSROOT? 
1987     
1988    There are eight Repository control (or "database") files of interest
1989    in the CVSROOT directory:
1990    
1991      modules contains the "modules" database. See 1D.11, 2C.7, 4B.6 and
1992    4B.7 for more details.
1993    
1994      commitinfo contains two columns: 1. a regular expression to match
1995    against pathnames within the Repository and
1996    
1997      a <command> to execute for matching pathnames.
1998    
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
2002    blocked.
2003    
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.
2007    
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.
2011    
2012    "DEFAULT" and "ALL" work the same as in the commitinfo file.
2013    
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.
2017    
2018    "DEFAULT" works as in commitinfo.
2019    
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.
2024    
2025    "DEFAULT" & "ALL" work the same as in commitinfo.
2026    
2027      cvsignore contains "ignore" patterns that are added to the built-in
2028    ignore list. See 2D.10.
2029    
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
2032    readable copy.
2033    
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.
2039    
2040    Last modified: _6/13/1997_
2041    
2042     3. Is there any other state stored in the Repository besides in the
2043     $CVSROOT/CVSROOT directory? 
2044     
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.
2048    
2049    Last modified: _6/13/1997_
2050    
2051     4. How do I put sources into the Repository? 
2052     
2053    There are three main ways to put files in the Repository:
2054    
2055      Use the "import" command described in Section 3H.
2056    
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.
2060    
2061      Use "add" followed by "commit".
2062    
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.
2065    
2066      You can move RCS files directly into the Repository.
2067    
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.
2072    
2073    Last modified: _6/13/1997_
2074    
2075     5. What file permissions should I use on (and in) the Repository? 
2076     
2077    If you are using pserver (password-authenticated access), see below.
2078    
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):
2081    
2082    - Set all directory permissions to 777.
2083    
2084    - Have everyone set their umasks to 0.
2085    
2086    (BTW, I don't suggest this. I am merely reporting it.)
2087    
2088    If you are a normal Unix shop and want to use groups effectively:
2089    
2090    - Set all the directory permissions in the Repository to 775.
2091    
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.)
2094    
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&gt;
2098    
2099    - Change all the groups on the directories to match the groups you
2100    want to write to various directories.
2101    
2102    - Make sure every user is in the appropriate groups.
2103    
2104    - Have everyone set their umask to 002, including root.
2105    
2106    If you don't want non-group members to even read the files, do the
2107    above, but change:
2108    
2109    - Repository directory permissions to 770. (or 2770)
2110    
2111    - umasks to 007.
2112    
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
2115    for them:
2116    
2117                 mv /usr/local/bin/cvs /usr/local/bin/cvs.real
2118                 cat > /usr/local/bin/cvs
2119                 #!/bin/sh
2120                 umask 2         # Or whatever your site standard is.
2121                 exec /usr/local/bin/cvs.real ${1+"$@"}
2122                 ^D
2123
2124    Pserver (Password-Authenticated Access) &lt;blome@de.ibm.com&gt;
2125    
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
2130    instead.
2131    
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 &lt;group&gt;/&lt;project&gt; on
2136    checkout, create a &lt;project&gt; module and point it there.
2137    
2138    Last modified: _9/24/1998_
2139    
2140     6. How do I structure my Repository? 
2141     
2142    The Repository holds your software. It can be all interrelated or it
2143    can be a bunch of separately managed directories.
2144    
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.
2149    
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
2153    apply it.
2154    
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:
2158    
2159    - mount (or automount) directories from many places in your
2160    organization.
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?)
2165    
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.
2169    
2170    Last modified: _6/13/1997_
2171    
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. 
2174     
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.
2179    
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.
2184    
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.
2189    
2190    Last modified: _6/13/1997_
2191    
2192     8. How do I rename a file or directory? What are the consequences? 
2193     
2194    In CVS there is no single "rename" command.
2195    
2196    See 2C.4 for the suggested way to rename a file or directory.
2197    
2198    The rest of this section covers some of the consequences of renaming.
2199    
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
2203    options:
2204    
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.)
2208    
2209    - "update -r <tag>" produces the correct files.
2210    
2211    - The duplicated revision history can be slightly misleading.
2212    
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.
2216    
2217      Move the files and directories in the Repository to the new names.
2218    
2219    - You save the revision history under a different file name.
2220    
2221    - You save a little space.
2222    
2223    - "update -r <tag>" produces the wrong files or directories.
2224    
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
2227    notion.
2228    
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.)
2234    
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.
2239    
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
2242    from scratch.
2243    
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:
2246    
2247    cvs update: xyz.c is no longer in the repository
2248    
2249    and deletes the file. If the file was modified, "update" prints:
2250    
2251    cvs update: conflict: xyz.c is modified but no longer in the
2252    repository C xyz.c
2253    
2254    and leaves the file alone. In the new directory, you see:
2255    
2256    U xyz.c
2257    
2258    as you would if someone else executed "add" and "commit".
2259    
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.
2264    
2265    - This is what most people think of first. Without a "rename" command,
2266    the remove/add technique seems obvious.
2267    
2268    - You lose the connection of your new working file to its past
2269    revision history.
2270    
2271    Last modified: _6/13/1997_
2272    
2273     9. What are "Attic" directories? 
2274     
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.
2277    
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.
2280    
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.
2284    
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>.
2287    
2288    Last modified: _6/13/1997_
2289    
2290     10. Is it OK to remove anything from the Repository? 
2291     
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.
2295    
2296    Here are some of the consequences of removing the following things
2297    stored in the Repository:
2298    
2299      CVSROOT files (Repository control files)
2300    
2301    The Repository will work without any of them, but you should
2302    understand what you are losing by deleting them. See 4B.2.
2303    
2304      Revisions
2305    
2306    The only way to remove revisions is to use the "admin -o" command (or
2307    the equivalent RCS command "rcs -o").
2308    
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
2311    to get them back.
2312    
2313      Files
2314    
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.
2318    
2319      Tags
2320    
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.
2323    
2324      Directories
2325    
2326    There is no Attic for directories, so the only way to remove them is
2327    to use "rm -r". They are gone forever.
2328    
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
2332    hand.
2333    
2334      Attic files
2335    
2336    The "remove" command sends files to the Attic. To really delete them,
2337    you have to go into the Attic and use "rm".
2338    
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.
2341    
2342      Lock files (named: "#cvs.[wr]fl.<pid>")
2343    
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.
2346    
2347    Deleting lock files still in use by a CVS process might produce
2348    unusual errors.
2349    
2350    Last modified: _6/13/1997_
2351    
2352     11. Can I convert to CVS from RCS without losing my revision history? 
2353     
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.
2356    
2357    Last modified: _6/13/1997_
2358    
2359     12. Can I move RCS files with branches in them into the Repository? 
2360     
2361    Yes, but they may not work if you created branches in a way that
2362    conflicts with CVS's assumptions:
2363    
2364      You can't use .0. branches. (They are reserved for "Magic" branch
2365    tags.)
2366    
2367      If you use branch 1.1.1, you can't use the Vendor branch.
2368    
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.
2371    
2372    Last modified: _6/13/1997_
2373    
2374     13. Can I use raw RCS commands on the Repository? 
2375     
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.
2379    
2380    But using raw RCS commands to change branches, tags or other things
2381    that CVS depends on may render the files unusable.
2382    
2383    See 4D.7 on RCS/CVS sharing of the Repository and Section 3B on the
2384    "admin" command.
2385    
2386    Last modified: _6/13/1997_
2387    
2388     14. How do I convert from SCCS to RCS? 
2389     
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.
2393    
2394    Last modified: _6/13/1997_
2395    
2396     15. How do I limit access to the Repository? 
2397     
2398    There are all sorts of ways to restrict access to Repository files,
2399    none of which are hooked directly into CVS.
2400    
2401    Techniques for limiting access include:
2402    
2403      Training, management and good backups.
2404    
2405    The best form of Repository control is a combination of:
2406    
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.
2411    
2412    In many cases, technical solutions to "security" problems are
2413    inadequate. You should first try to avoid them.
2414    
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.
2422    
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.
2426    
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.
2431    
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.
2436    
2437      Try the "setgid" trick described in 4D.13.
2438    
2439      Try to use the RCS access control lists, though I don't think CVS
2440    will handle them cleanly.
2441    
2442      Edit the source code to CVS to add your own access control.
2443    
2444    Last modified: _6/13/1997_
2445    
2446     16. What are the Repository Administrator's responsibilities? 
2447     
2448    Generally, the Administrator should set "policy", create the
2449    Repository and monitor its size and control files.
2450    
2451    Some specific responsibilities include:
2452    
2453      Examining the Repository once in a while to clean up:
2454    
2455      Trash files left by misguided developers who mistake the Repository
2456    for a working directory.
2457    
2458      Non-RCS files. Other than the files CVS needs in the
2459    $CVSROOT/CVSROOT directory, every file in the Repository should be an
2460    RCS file.
2461    
2462      Lock files (both CVS '#*' and RCS ',*' files) left around after
2463    crashes.
2464    
2465      Wrong permissions, groups and ownerships.
2466    
2467      Locked files. (RCS locks, that is.)
2468    
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 !".
2474    
2475      Maintaining the modules file.
2476    
2477      Storing site-specific ignore patterns in the
2478    $CVSROOT/CVSROOT/cvsignore file.
2479    
2480      Storing the names of non-standard CVSROOT files (See 4B.2) in the
2481    $CVSROOT/CVSROOT/checkoutlist
2482    
2483      Maintaining the other Repository control files: commitinfo, loginfo,
2484    rcsinfo and editinfo.
2485    
2486      Pruning the history file every once in a while. (Try the
2487    "cln_hist.pl" script in the "contrib" directory.)
2488    
2489      Staying aware of developments on the info-cvs mailing list and what
2490    is available in the FTP and WWW archives.
2491    
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.
2495    
2496      Executing monitor programs to check the internal consistency of the
2497    Repository files. Ideas:
2498    
2499      Files that have a default RCS branch that is not 1.1.1 (From an
2500    abuse of "admin -b".)
2501    
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".)
2504    
2505      Existing branch tags and various branch consistency checks.
2506    
2507    Last modified: _6/13/1997_
2508    
2509     17. How do I move the whole Repository? 
2510     
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".)
2514    
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.
2518    
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.)
2521    
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.
2525    
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.
2531    
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
2535    moved.
2536    
2537    You have three choices:
2538    
2539      If all ./CVS/Repository files in all working directories contain
2540    relative pathnames, you don't have to do anything else.
2541    
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.
2545    
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.
2549    
2550    Last modified: _6/13/1997_
2551    
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") 
2554     
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.
2559    
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.
2564    
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
2568    set.
2569    
2570    Last modified: _6/13/1997_
2571    
2572   Category: /Advanced_Topics_/Tricks_of_the_Trade/
2573   
2574    " + Tricks of the Trade"
2575    
2576     1. How can you even check in binary files, let alone allow CVS to do its
2577     auto-merge trick on them? 
2578     
2579
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).
2585
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
2591 think -kb instead.
2592
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.
2602
2603 kingdon@cyclic.com
2604
2605    Last modified: _9/6/1997_
2606    
2607     2. Can I edit the RCS (",v") files in the Repository? 
2608     
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.
2614    
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:
2618    
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'
2622    instead.)
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.)
2630    
2631    Last modified: _6/13/1997_
2632    
2633     3. Can I edit the ./CVS/{Entries,Repository,Tag} files? 
2634     
2635    Yes, but with CVS 1.3 and later, there is almost no reason to edit any
2636    of the CVS administrative files.
2637    
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.
2641    
2642    Last modified: _6/13/1997_
2643    
2644     4. Someone executed "admin -o" and removed revisions to which tags/symbols
2645     were attached. How do I fix them? 
2646     
2647    It depends on what you mean by "fix". I can think of three ways to fix
2648    your predicament:
2649    
2650      Remove the tags.
2651    
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:
2657    
2658                 cvs admin -N<tag> <file>
2659
2660      Retrieve the outdated revision.
2661    
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.
2667    
2668    You *can't* insert a revision into the current RCS file.
2669    
2670      Move the Tags to another revision in each file.
2671    
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>.
2676    
2677      Use "update" to grab the revision you want, then execute a normal
2678    "tag" command to Tag that revision:
2679    
2680                         cvs update -r <rev> <file>
2681                         cvs tag <tag> <file>
2682
2683      Use "admin" to set the tag to a specific revision:
2684    
2685                         cvs admin -N<tag>:<rev> <file>
2686
2687    Last modified: _6/13/1997_
2688    
2689     5. How do I move or rename a magic branch tag? 
2690     
2691    (To rename a non-branch <tag> see 3O.9.)
2692    
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.
2695    
2696      First, I have to explain exactly what a magic branch tag is.
2697    
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:
2700    
2701                 TAG1:<X>.0.Y
2702
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)
2705
2706              Y  is an even number (e.g. 2, 4, 6, etc.)  All CVS branches,
2707                 other than the Vendor branch, are even numbered.
2708
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.
2714    
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
2717    some CVS commands.
2718    
2719      Moving a magic <branch_tag> is the act of reapplying the same tag to
2720    different revisions in the file:
2721    
2722                 TAG1:<X>.0.Y
2723            to
2724                 TAG1:<X>.0.Z    or      TAG1:<A>.0.B
2725
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>.
2730    
2731                 cvs update -r <tag/rev>  (or '-A' for the Main Branch)
2732                 cvs tag -F -b <branch_tag>
2733
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.
2738    
2739    If the "update" above retrieves the original branch point revision
2740    (<X>), the "tag" command above will create the tag:
2741    
2742                 TAG1:<X>.0.Z
2743
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).
2748    
2749      Renaming a magic <branch_tag> is the act of changing
2750    
2751                 TAG1:<X>.0.Y
2752            to
2753                 TAG2:<X>.0.Y
2754
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.
2759    
2760    On the other hand, actually changing the tag is not easy.
2761    
2762    See 3M.3 for why the seemingly obvious solution won't work:
2763    
2764                 cvs tag -b -r <old_branch_tag> <new_branch_tag>
2765
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.)
2769    
2770                 cvs admin -N<new_branch_tag>:<old_branch_tag> .
2771                 cvs tag -d <old_branch_tag>
2772
2773    But you have to be careful because "admin" is different from other CVS
2774    commands:
2775    
2776      "admin" can be used recursively, but only by specifying directory
2777    names in its argument list (e.g. '.'),
2778    
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
2782    number.
2783    
2784    This is good for us in this particular case, but different from normal
2785    CVS.
2786    
2787      "admin" also skips the Attic and produces different kinds of errors
2788    than CVS usually does. (Because they are coming directly from RCS.)
2789    
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.
2793    
2794    Last modified: _6/13/1997_
2795    
2796     6. Can I use RCS locally to record my changes without making them globally
2797     visible by committing them? 
2798     
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
2801    finally commit it.
2802    
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.
2806    
2807    Last modified: _6/13/1997_
2808    
2809     7. How can I allow access to the Repository by both CVS and RCS? 
2810     
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.
2818    
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:
2821    
2822                 ln -s /Repository/some/directory/I/want RCS
2823
2824    and RCS will work just fine.
2825    
2826    Those who are using RCS will have to keep the following in mind:
2827    
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.
2833    
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.
2837    
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.
2840    
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.
2846    
2847    See 3C.8 for a way to avoid machetes aroused by lock collisions.
2848    
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
2852    won't happen.
2853    
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
2857    users.
2858    
2859    See the howling mob scenario described above.
2860    
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.
2865    
2866    Last modified: _6/13/1997_
2867    
2868     8. I "updated" a file my friend, "bubba", committed yesterday. Why doesn't
2869     the file now have a modified date of yesterday? 
2870     
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.
2874    
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.
2881    
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
2887    current time.
2888    
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
2895    timestamps.
2896    
2897    Last modified: _6/13/1997_
2898    
2899     9. Why do timestamps sometimes get set to the date of the revision,
2900     sometimes not? The inconsistency causes unnecessary recompiles. 
2901     
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
2904    file.
2905    
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).
2908    
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.
2912    
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.
2917    
2918         #!/usr/local/bin/perl
2919         #
2920         # Set timestamp of args 2nd-Last to that of the first arg.
2921         #
2922         ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,$atime,$mtime,$ctime)
2923                 = stat(shift);
2924         utime($atime,$mtime,@ARGV);
2925
2926    Last modified: _6/13/1997_
2927    
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? 
2930     
2931    Type:
2932                 cvs -n <command>
2933
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.
2939    
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.
2948    
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.
2952    
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.
2956    
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.
2959    
2960    You need RCS version 5 or later for the commands described above to
2961    work reliably.
2962    
2963    Last modified: _6/13/1997_
2964    
2965     11. Where did the ./CVS/Entries.Static file come from? What is it for? 
2966     
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:
2973    
2974      Added to the Repository from another working directory.
2975    
2976      Dragged out of the Attic when switching branches with "update -A" or
2977    "update -r".
2978    
2979      Whose names were deleted from the ./CVS/Entries file.
2980    
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,
2984    it is ignored.
2985    
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
2991    "checkout" wanted.
2992    
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.)
2999    
3000    Last modified: _6/13/1997_
3001    
3002     12. Why did I get the wrong Repository in the loginfo message? 
3003     
3004    You probably:
3005    
3006      Use multiple Repositories.
3007    
3008      Configured CVS to use absolute pathnames in the ./CVS/Repository
3009    file.
3010    
3011      Configured CVS not to use the ./CVS/Root file.
3012    
3013      Typed the "commit" command in one Repository with your $CVSROOT
3014    pointing at another.
3015    
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.
3019    
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.
3023    
3024    Last modified: _6/13/1997_
3025    
3026     13. How do I run CVS setuid so I can only allow access through the CVS
3027     program itself? 
3028     
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.)
3033    
3034    Root access on Unix is too powerful. Also, it might not work in some
3035    (secure?) environments.
3036    
3037    Running it setuid to some user other than root might work, if you add
3038    this line to main.c near the beginning:
3039    
3040                 setuid(geteuid());
3041
3042    Otherwise it uses *your* access rights, rather than the effective
3043    uid's.
3044    
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.
3049    
3050    And finally, unless you take action to limit the "admin" command, you
3051    are leaving yourself unprotected anyway.
3052    
3053    Last modified: _6/13/1997_
3054    
3055     14. How about using groups and setgid() then? 
3056     
3057    Here is a way to run CVS setgid in some environments:
3058    
3059      Stick this near the front of the main() in main.c:
3060    
3061    setgid(getegid());
3062    
3063    This will allow "access" to work on systems where it only works on the
3064    real gid.
3065    
3066      Create a group named "cvsg". (This example uses "cvsg". You can name
3067    it as you wish.)
3068    
3069      Put *no* users in the "cvsg" group. You can put Repository
3070    administrators in this group if you want to.
3071    
3072      Set the cvs executable to setgid (not setuid):
3073    
3074    cd /usr/local/bin; chown root.cvsg cvs; chmod 2755 cvs
3075    
3076      Make sure every file in the Repository is in group "cvsg":
3077    
3078    chown -R root.cvsg $CVSROOT
3079    
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
3082    all to anyone else.
3083    
3084    find $CVSROOT -type d -exec chmod 2770 {} \;
3085    
3086    On some systems you might have to type:
3087    
3088    find $CVSROOT -type d -exec chmod u=rwx,g=rwx,o=,g+s {} \;
3089    
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.)
3096    
3097    If you want to allow read access, check out an entire tree somewhere.
3098    You have to do this anyway to build it.
3099    
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.
3104    
3105    The setgid() method shares with the setuid() method the problem of
3106    keeping "admin" from breaking things.
3107    
3108    Last modified: _6/13/1997_
3109    
3110     15. How do I use the "commitinfo" file? 
3111     
3112    Go read 4B.2 first.
3113    
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.
3117    
3118    To fill out a "commitinfo" file, ask yourself (and those sharing your
3119    Repository) these questions:
3120    
3121    - Is there anything you want to check or change before someone is
3122    allowed to commit a file? If not, forget commitinfo.
3123    
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
3126    sources.
3127    
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
3131    commitinfo:
3132    
3133                 DEFAULT         /absolute/path/to/program
3134
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.
3138    
3139    Write your program accordingly. Some examples exist in the contrib
3140    directory.
3141    
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:
3145    
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
3149
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:
3152    
3153                 ALL             /absolute/path/to/program
3154
3155    It is executed independently of all the above. And it's repeatable --
3156    you can have as many ALL lines as you like.
3157    
3158    Last modified: _6/13/1997_
3159    
3160     16. How do I use the "loginfo" files? 
3161     
3162    See 4B.2 and the "commitinfo" question above.
3163    
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.
3167    
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:
3173    
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
3177    
3178    Last modified: _6/13/1997_
3179    
3180     17. How can I keep people with restrictive umask values from blocking
3181     access to the Repository? 
3182     
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.
3187    
3188    There are 3 solutions to this:
3189    
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.
3193    
3194      Train your users not to create such things if you expect to share
3195    them.
3196    
3197      See 4B.5 for a small script that will reset the umask.
3198    
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.
3202    
3203    Last modified: _6/13/1997_
3204    
3205   Category: /Commands_/
3206   
3207    " Commands "
3208    
3209   Category: /Commands_/add_ad_new/
3210   
3211    " + "add", "ad", "new""
3212    
3213     1. What is "add" for? 
3214     
3215    To add a new directory to the Repository or to register the desire to
3216    add a new file to the Repository.
3217    
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.
3221    
3222    Last modified: _6/13/1997_
3223    
3224     2. How do I add a new file to the branch I'm working on? 
3225     
3226    The user actions for adding a file to any branch, including the Main
3227    Branch, are exactly the same.
3228    
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:
3233    
3234                 cvs add <file>
3235                 cvs commit <file>
3236
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>.
3241    
3242    Unless you took steps to first add the file to the Main Branch, your
3243    new file ends up in the Attic.
3244    
3245    Last modified: _6/13/1997_
3246    
3247     3. Why did my new file end up in the Attic? 
3248     
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
3251    Main Branch.
3252    
3253    Last modified: _6/13/1997_
3254    
3255     4. Now that it's in the Attic, how do I connect it to the Main branch? 
3256     
3257    That can be considered a kind of "merge". See 4C.8
3258    
3259    Last modified: _6/13/1997_
3260    
3261     5. How do I avoid the hassle of reconnecting an Attic-only file to the Main
3262     Branch? 
3263     
3264    You create it on the Main Branch first, then branch it.
3265    
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.)
3270    
3271      Temporarily remove the sticky branch information. Either:
3272    
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
3275    in each direction.]
3276    
3277                 cvs update -A
3278
3279                         *or*
3280
3281      Move the ./CVS/Tag file out of the way.
3282    
3283                 mv ./CVS/Tag HOLD_Tag
3284
3285      Add and branch the file "normally":
3286    
3287                 cvs add <file>
3288                 cvs commit <file>
3289                 cvs tag -b <branch_tag> <file>
3290
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
3293    tags.]