sync with .orig.tar.gz after removing all CLEANFILES
[alioth/cvs.git] / doc / cvs.texinfo
1 \input texinfo  @c -*-texinfo-*-
2 @comment Documentation for CVS.
3 @setfilename cvs.info
4 @macro copyleftnotice
5 @noindent
6 Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
7                        2001, 2002, 2003, 2004, 2005
8                        Free Software Foundation, Inc.
9
10 @multitable @columnfractions .12 .88
11 @item Portions
12 @item @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005
13                                   Derek R. Price,
14 @item @tab Copyright @copyright{} 2002, 2003, 2004, 2005
15                                   Ximbiot @url{http://ximbiot.com},
16 @item @tab Copyright @copyright{} 1992, 1993, 1999 Signum Support AB,
17 @item @tab and Copyright @copyright{} others.
18 @end multitable
19
20 @ignore
21 Permission is granted to process this file through Tex and print the
22 results, provided the printed document carries copying permission
23 notice identical to this one except for the removal of this paragraph
24 (this paragraph not being relevant to the printed manual).
25
26 @end ignore
27 Permission is granted to make and distribute verbatim copies of
28 this manual provided the copyright notice and this permission notice
29 are preserved on all copies.
30
31 Permission is granted to copy and distribute modified versions of this
32 manual under the conditions for verbatim copying, provided also that the
33 entire resulting derived work is distributed under the terms of a
34 permission notice identical to this one.
35
36 Permission is granted to copy and distribute translations of this manual
37 into another language, under the above conditions for modified versions,
38 except that this permission notice may be stated in a translation
39 approved by the Free Software Foundation.
40 @end macro
41
42 @comment This file is part of the CVS distribution.
43
44 @comment CVS is free software; you can redistribute it and/or modify
45 @comment it under the terms of the GNU General Public License as published by
46 @comment the Free Software Foundation; either version 2, or (at your option)
47 @comment any later version.
48
49 @comment CVS is distributed in the hope that it will be useful,
50 @comment but WITHOUT ANY WARRANTY; without even the implied warranty of
51 @comment MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
52 @comment GNU General Public License for more details.
53
54 @c See ../README for A4 vs. US letter size.
55 @c When we provided A4 postscript, and people tried to
56 @c print it on US letter, the usual complaint was that the
57 @c page numbers would get cut off.
58 @c If one prints US letter on A4, reportedly there is
59 @c some extra space at the top and/or bottom, and the side
60 @c margins are a bit narrow, but no text is lost.
61 @c
62 @c See
63 @c http://www.ft.uni-erlangen.de/~mskuhn/iso-paper.html
64 @c for more on paper sizes.  Insuring that margins are
65 @c big enough to print on either A4 or US letter does
66 @c indeed seem to be the usual approach (RFC2346).
67
68 @c This document seems to get overfull hboxes with some
69 @c frequency (probably because the tendency is to
70 @c sanity-check it with "make info" and run TeX less
71 @c often).  The big ugly boxes just seem to add insult
72 @c to injury, and I'm not aware of them helping to fix
73 @c the overfull hboxes at all.
74 @finalout
75
76 @include version.texi
77 @settitle CVS---Concurrent Versions System v@value{VERSION}
78 @setchapternewpage odd
79
80 @c -- TODO list:
81 @c -- Fix all lines that match "^@c -- "
82 @c -- Also places marked with FIXME should be manual
83 @c problems (as opposed to FIXCVS for CVS problems).
84
85 @c @splitrcskeyword{} is used to avoid keyword expansion.  It is replaced by
86 @c @asis when generating info and dvi, and by <i></i> in the generated html,
87 @c such that keywords are not expanded in the generated html. 
88 @ifnothtml
89 @macro splitrcskeyword {arg}
90 @asis{}\arg\
91 @end macro
92 @end ifnothtml
93
94 @ifhtml
95 @macro splitrcskeyword {arg}
96 @i{}\arg\
97 @end macro
98 @end ifhtml
99
100 @dircategory GNU Packages
101 @direntry
102 * CVS: (cvs).                   Concurrent Versions System
103 @end direntry
104 @dircategory Individual utilities
105 @direntry
106 * cvs: (cvs)CVS commands.       Concurrent Versions System
107 @end direntry
108
109 @comment The titlepage section does not appear in the Info file.
110 @titlepage
111 @sp 4
112 @comment The title is printed in a large font.
113 @center @titlefont{Version Management}
114 @sp
115 @center @titlefont{with}
116 @sp
117 @center @titlefont{CVS}
118 @sp 2
119 @center for @sc{cvs} @value{VERSION}
120 @comment -release-
121 @sp 3
122 @center Per Cederqvist et al
123
124 @comment  The following two commands start the copyright page
125 @comment  for the printed manual.  This will not appear in the Info file.
126 @page
127 @vskip 0pt plus 1filll
128 @copyleftnotice
129 @end titlepage
130
131 @summarycontents
132
133 @contents
134
135 @comment ================================================================
136 @comment                   The real text starts here
137 @comment ================================================================
138
139 @ifnottex
140 @c ---------------------------------------------------------------------
141 @node    Top
142 @top
143
144 This info manual describes how to use and administer
145 @sc{cvs} version @value{VERSION}.
146 @end ifnottex
147
148 @ifinfo
149 @copyleftnotice
150 @end ifinfo
151
152 @c This menu is pretty long.  Not sure how easily that
153 @c can be fixed (no brilliant ideas right away)...
154 @menu
155 * Overview::                    An introduction to CVS
156 * Repository::                  Where all your sources are stored
157 * Starting a new project::      Starting a project with CVS
158 * Revisions::                   Numeric and symbolic names for revisions
159 * Branching and merging::       Diverging/rejoining branches of development
160 * Recursive behavior::          CVS descends directories
161 * Adding and removing::         Adding/removing/renaming files/directories
162 * History browsing::            Viewing the history of files in various ways
163
164 CVS and the Real World.
165 -----------------------
166 * Binary files::                CVS can handle binary files
167 * Multiple developers::         How CVS helps a group of developers
168 * Revision management::         Policy questions for revision management
169 * Keyword substitution::        CVS can include the revision inside the file
170 * Tracking sources::            Tracking third-party sources
171 * Builds::                      Issues related to CVS and builds
172 * Special Files::               Devices, links and other non-regular files
173
174 References.
175 -----------
176 * CVS commands::                CVS commands share some things
177 * Invoking CVS::                Quick reference to CVS commands
178 * Administrative files::        Reference manual for the Administrative files
179 * Environment variables::       All environment variables which affect CVS
180 * Compatibility::               Upgrading CVS versions
181 * Troubleshooting::             Some tips when nothing works
182 * Credits::                     Some of the contributors to this manual
183 * BUGS::                        Dealing with bugs in CVS or this manual
184 * Index::                       Index
185 @end menu
186
187 @c ---------------------------------------------------------------------
188 @node Overview
189 @chapter Overview
190 @cindex Overview
191
192 This chapter is for people who have never used
193 @sc{cvs}, and perhaps have never used version control
194 software before.
195
196 If you are already familiar with @sc{cvs} and are just
197 trying to learn a particular feature or remember a
198 certain command, you can probably skip everything here.
199
200 @menu
201 * What is CVS?::                What you can do with @sc{cvs}
202 * What is CVS not?::            Problems @sc{cvs} doesn't try to solve
203 * A sample session::            A tour of basic @sc{cvs} usage
204 @end menu
205
206 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
207 @node What is CVS?
208 @section What is CVS?
209 @cindex What is CVS?
210 @cindex Introduction to CVS
211 @cindex CVS, introduction to
212
213 @sc{cvs} is a version control system.  Using it, you can
214 record the history of your source files.
215
216 @c -- ///
217 @c -- ///Those who cannot remember the past are condemned to repeat it.
218 @c -- ///               -- George Santayana
219 @c -- //////
220
221 @c -- Insert history  quote here!
222 For example, bugs sometimes creep in when
223 software is modified, and you might not detect the bug
224 until a long time after you make the modification.
225 With @sc{cvs}, you can easily retrieve old versions to see
226 exactly which change caused the bug.  This can
227 sometimes be a big help.
228
229 You could of course save every version of every file
230 you have ever created.  This would
231 however waste an enormous amount of disk space.  @sc{cvs}
232 stores all the versions of a file in a single file in a
233 clever way that only stores the differences between
234 versions.
235
236 @sc{cvs} also helps you if you are part of a group of people working
237 on the same project.  It is all too easy to overwrite
238 each others' changes unless you are extremely careful.
239 Some editors, like @sc{gnu} Emacs, try to make sure that
240 two people never modify the same file at the
241 same time.  Unfortunately, if someone is using another
242 editor, that safeguard will not work.  @sc{cvs} solves this problem
243 by insulating the different developers from each other.  Every
244 developer works in his own directory, and @sc{cvs} merges
245 the work when each developer is done.
246
247 @cindex History of CVS
248 @cindex CVS, history of
249 @cindex Credits (CVS program)
250 @cindex Contributors (CVS program)
251 @sc{cvs} started out as a bunch of shell scripts written by
252 Dick Grune, posted to the newsgroup
253 @code{comp.sources.unix} in the volume 6
254 release of July, 1986.  While no actual code from
255 these shell scripts is present in the current version
256 of @sc{cvs} much of the @sc{cvs} conflict resolution algorithms
257 come from them.
258
259 In April, 1989, Brian Berliner designed and coded @sc{cvs}.
260 Jeff Polk later helped Brian with the design of the @sc{cvs}
261 module and vendor branch support.
262
263 @cindex Source, getting CVS source
264 You can get @sc{cvs} in a variety of ways, including
265 free download from the Internet.  For more information
266 on downloading @sc{cvs} and other @sc{cvs} topics, see:
267
268 @example
269 @url{http://cvs.nongnu.org/}
270 @end example
271
272 @cindex Mailing list
273 @cindex List, mailing list
274 @cindex Newsgroups
275 There is a mailing list, known as @email{info-cvs@@nongnu.org},
276 devoted to @sc{cvs}.  To subscribe or
277 unsubscribe
278 write to
279 @email{info-cvs-request@@nongnu.org}.
280 If you prefer a Usenet group, there is a one-way mirror (posts to the email
281 list are usually sent to the news group, but not visa versa) of
282 @email{info-cvs@@nongnu.org} at @url{news:gnu.cvs.help}.  The right
283 Usenet group for posts is @url{news:comp.software.config-mgmt} which is for
284 @sc{cvs} discussions (along with other configuration
285 management systems).  In the future, it might be
286 possible to create a
287 @code{comp.software.config-mgmt.cvs}, but probably only
288 if there is sufficient @sc{cvs} traffic on
289 @url{news:comp.software.config-mgmt}.
290 @c Other random data is that the tale was very
291 @c skeptical of comp.software.config-mgmt.cvs when the
292 @c subject came up around 1995 or so (for one
293 @c thing, because creating it would be a "reorg" which
294 @c would need to take a more comprehensive look at the
295 @c whole comp.software.config-mgmt.* hierarchy).
296
297 You can also subscribe to the @email{bug-cvs@@nongnu.org} mailing list,
298 described in more detail in @ref{BUGS}.  To subscribe
299 send mail to @email{bug-cvs-request@@nongnu.org}.  There is a two-way
300 Usenet mirror (posts to the Usenet group are usually sent to the email list and
301 visa versa) of @email{bug-cvs@@nongnu.org} named @url{news:gnu.cvs.bug}.
302
303 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
304 @node What is CVS not?
305 @section What is CVS not?
306 @cindex What is CVS not?
307
308 @sc{cvs} can do a lot of things for you, but it does
309 not try to be everything for everyone.
310
311 @table @asis
312 @item @sc{cvs} is not a build system.
313
314 Though the structure of your repository and modules
315 file interact with your build system
316 (e.g. @file{Makefile}s), they are essentially
317 independent.
318
319 @sc{cvs} does not dictate how you build anything.  It
320 merely stores files for retrieval in a tree structure
321 you devise.
322
323 @sc{cvs} does not dictate how to use disk space in the
324 checked out working directories.  If you write your
325 @file{Makefile}s or scripts in every directory so they
326 have to know the relative positions of everything else,
327 you wind up requiring the entire repository to be
328 checked out.
329
330 If you modularize your work, and construct a build
331 system that will share files (via links, mounts,
332 @code{VPATH} in @file{Makefile}s, etc.), you can
333 arrange your disk usage however you like.
334
335 But you have to remember that @emph{any} such system is
336 a lot of work to construct and maintain.  @sc{cvs} does
337 not address the issues involved.
338
339 Of course, you should place the tools created to
340 support such a build system (scripts, @file{Makefile}s,
341 etc) under @sc{cvs}.
342
343 Figuring out what files need to be rebuilt when
344 something changes is, again, something to be handled
345 outside the scope of @sc{cvs}.  One traditional
346 approach is to use @code{make} for building, and use
347 some automated tool for generating the dependencies which
348 @code{make} uses.
349
350 See @ref{Builds}, for more information on doing builds
351 in conjunction with @sc{cvs}.
352
353 @item @sc{cvs} is not a substitute for management.
354
355 Your managers and project leaders are expected to talk
356 to you frequently enough to make certain you are aware
357 of schedules, merge points, branch names and release
358 dates.  If they don't, @sc{cvs} can't help.
359
360 @sc{cvs} is an instrument for making sources dance to
361 your tune.  But you are the piper and the composer.  No
362 instrument plays itself or writes its own music.
363
364 @item @sc{cvs} is not a substitute for developer communication.
365
366 When faced with conflicts within a single file, most
367 developers manage to resolve them without too much
368 effort.  But a more general definition of ``conflict''
369 includes problems too difficult to solve without
370 communication between developers.
371
372 @sc{cvs} cannot determine when simultaneous changes
373 within a single file, or across a whole collection of
374 files, will logically conflict with one another.  Its
375 concept of a @dfn{conflict} is purely textual, arising
376 when two changes to the same base file are near enough
377 to spook the merge (i.e. @code{diff3}) command.
378
379 @sc{cvs} does not claim to help at all in figuring out
380 non-textual or distributed conflicts in program logic.
381
382 For example: Say you change the arguments to function
383 @code{X} defined in file @file{A}.  At the same time,
384 someone edits file @file{B}, adding new calls to
385 function @code{X} using the old arguments.  You are
386 outside the realm of @sc{cvs}'s competence.
387
388 Acquire the habit of reading specs and talking to your
389 peers.
390
391
392 @item @sc{cvs} does not have change control
393
394 Change control refers to a number of things.  First of
395 all it can mean @dfn{bug-tracking}, that is being able
396 to keep a database of reported bugs and the status of
397 each one (is it fixed?  in what release?  has the bug
398 submitter agreed that it is fixed?).  For interfacing
399 @sc{cvs} to an external bug-tracking system, see the
400 @file{rcsinfo} and @file{verifymsg} files
401 (@pxref{Administrative files}).
402
403 Another aspect of change control is keeping track of
404 the fact that changes to several files were in fact
405 changed together as one logical change.  If you check
406 in several files in a single @code{cvs commit}
407 operation, @sc{cvs} then forgets that those files were
408 checked in together, and the fact that they have the
409 same log message is the only thing tying them
410 together.  Keeping a @sc{gnu} style @file{ChangeLog}
411 can help somewhat.
412 @c FIXME: should have an xref to a section which talks
413 @c more about keeping ChangeLog's with CVS, but that
414 @c section hasn't been written yet.
415
416 Another aspect of change control, in some systems, is
417 the ability to keep track of the status of each
418 change.  Some changes have been written by a developer,
419 others have been reviewed by a second developer, and so
420 on.  Generally, the way to do this with @sc{cvs} is to
421 generate a diff (using @code{cvs diff} or @code{diff})
422 and email it to someone who can then apply it using the
423 @code{patch} utility.  This is very flexible, but
424 depends on mechanisms outside @sc{cvs} to make sure
425 nothing falls through the cracks.
426
427 @item @sc{cvs} is not an automated testing program
428
429 It should be possible to enforce mandatory use of a
430 test suite using the @code{commitinfo} file.  I haven't
431 heard a lot about projects trying to do that or whether
432 there are subtle gotchas, however.
433
434 @item @sc{cvs} does not have a built-in process model
435
436 Some systems provide ways to ensure that changes or
437 releases go through various steps, with various
438 approvals as needed.  Generally, one can accomplish
439 this with @sc{cvs} but it might be a little more work.
440 In some cases you'll want to use the @file{commitinfo},
441 @file{loginfo}, @file{rcsinfo}, or @file{verifymsg}
442 files, to require that certain steps be performed
443 before cvs will allow a checkin.  Also consider whether
444 features such as branches and tags can be used to
445 perform tasks such as doing work in a development tree
446 and then merging certain changes over to a stable tree
447 only once they have been proven.
448 @end table
449
450 @c ---------------------------------------------------------------------
451 @node A sample session
452 @section A sample session
453 @cindex Example of a work-session
454 @cindex Getting started
455 @cindex Work-session, example of
456 @cindex tc, Trivial Compiler (example)
457 @cindex Trivial Compiler (example)
458
459 @c I think an example is a pretty good way to start.  But
460 @c somewhere in here, maybe after the sample session,
461 @c we need something which is kind of
462 @c a "roadmap" which is more directed at sketching out
463 @c the functionality of CVS and pointing people to
464 @c various other parts of the manual.  As it stands now
465 @c people who read in order get dumped right into all
466 @c manner of hair regarding remote repositories,
467 @c creating a repository, etc.
468 @c
469 @c The following was in the old Basic concepts node.  I don't
470 @c know how good a job it does at introducing modules,
471 @c or whether they need to be introduced so soon, but
472 @c something of this sort might go into some
473 @c introductory material somewhere.
474 @ignore
475 @cindex Modules (intro)
476 The repository contains directories and files, in an
477 arbitrary tree.  The @dfn{modules} feature can be used
478 to group together a set of directories or files into a
479 single entity (@pxref{modules}).  A typical usage is to
480 define one module per project.
481 @end ignore
482
483 As a way of introducing @sc{cvs}, we'll go through a
484 typical work-session using @sc{cvs}.  The first thing
485 to understand is that @sc{cvs} stores all files in a
486 centralized @dfn{repository} (@pxref{Repository}); this
487 section assumes that a repository is set up.
488 @c I'm not sure that the sentence concerning the
489 @c repository quite tells the user what they need to
490 @c know at this point.  Might need to expand on "centralized"
491 @c slightly (maybe not here, maybe further down in the example?)
492
493 Suppose you are working on a simple compiler.  The source
494 consists of a handful of C files and a @file{Makefile}.
495 The compiler is called @samp{tc} (Trivial Compiler),
496 and the repository is set up so that there is a module
497 called @samp{tc}.
498
499 @menu
500 * Getting the source::          Creating a workspace
501 * Committing your changes::     Making your work available to others
502 * Cleaning up::                 Cleaning up
503 * Viewing differences::         Viewing differences
504 @end menu
505
506 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
507 @node Getting the source
508 @subsection Getting the source
509 @cindex Getting the source
510 @cindex Checking out source
511 @cindex Fetching source
512 @cindex Source, getting from CVS
513 @cindex Checkout, example
514
515 The first thing you must do is to get your own working copy of the
516 source for @samp{tc}.  For this, you use the @code{checkout} command:
517
518 @example
519 $ cvs checkout tc
520 @end example
521
522 @noindent
523 This will create a new directory called @file{tc} and populate it with
524 the source files.
525
526 @example
527 $ cd tc
528 $ ls
529 CVS         Makefile    backend.c   driver.c    frontend.c  parser.c
530 @end example
531
532 The @file{CVS} directory is used internally by
533 @sc{cvs}.  Normally, you should not modify or remove
534 any of the files in it.
535
536 You start your favorite editor, hack away at @file{backend.c}, and a couple
537 of hours later you have added an optimization pass to the compiler.
538 A note to @sc{rcs} and @sc{sccs} users: There is no need to lock the files that
539 you want to edit.  @xref{Multiple developers}, for an explanation.
540
541 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
542 @node Committing your changes
543 @subsection Committing your changes
544 @cindex Committing changes to files
545 @cindex Log message entry
546
547 When you have checked that the compiler is still compilable you decide
548 to make a new version of @file{backend.c}.  This will
549 store your new @file{backend.c} in the repository and
550 make it available to anyone else who is using that same
551 repository.
552
553 @example
554 $ cvs commit backend.c
555 @end example
556
557 @noindent
558 @sc{cvs} starts an editor, to allow you to enter a log
559 message.  You type in ``Added an optimization pass.'',
560 save the temporary file, and exit the editor.
561
562 @cindex CVSEDITOR, environment variable
563 @cindex EDITOR, environment variable
564 The environment variable @code{$CVSEDITOR} determines
565 which editor is started.  If @code{$CVSEDITOR} is not
566 set, then if the environment variable @code{$EDITOR} is
567 set, it will be used. If both @code{$CVSEDITOR} and
568 @code{$EDITOR} are not set then there is a default
569 which will vary with your operating system, for example
570 @code{vi} for unix or @code{notepad} for Windows
571 NT/95.
572
573 @cindex VISUAL, environment variable
574 In addition, @sc{cvs} checks the @code{$VISUAL} environment
575 variable.  Opinions vary on whether this behavior is desirable and
576 whether future releases of @sc{cvs} should check @code{$VISUAL} or
577 ignore it.  You will be OK either way if you make sure that
578 @code{$VISUAL} is either unset or set to the same thing as
579 @code{$EDITOR}.
580
581 @c This probably should go into some new node
582 @c containing detailed info on the editor, rather than
583 @c the intro.  In fact, perhaps some of the stuff with
584 @c CVSEDITOR and -m and so on should too.
585 When @sc{cvs} starts the editor, it includes a list of
586 files which are modified.  For the @sc{cvs} client,
587 this list is based on comparing the modification time
588 of the file against the modification time that the file
589 had when it was last gotten or updated.  Therefore, if
590 a file's modification time has changed but its contents
591 have not, it will show up as modified.  The simplest
592 way to handle this is simply not to worry about it---if
593 you proceed with the commit @sc{cvs} will detect that
594 the contents are not modified and treat it as an
595 unmodified file.  The next @code{update} will clue
596 @sc{cvs} in to the fact that the file is unmodified,
597 and it will reset its stored timestamp so that the file
598 will not show up in future editor sessions.
599 @c FIXCVS: Might be nice if "commit" and other commands
600 @c would reset that timestamp too, but currently commit
601 @c doesn't.
602 @c FIXME: Need to talk more about the process of
603 @c prompting for the log message.  Like show an example
604 @c of what it pops up in the editor, for example.  Also
605 @c a discussion of how to get the "a)bort, c)ontinue,
606 @c e)dit" prompt and what to do with it.  Might also
607 @c work in the suggestion that if you want a diff, you
608 @c should make it before running commit (someone
609 @c suggested that the diff pop up in the editor.  I'm
610 @c not sure that is better than telling people to run
611 @c "cvs diff" first if that is what they want, but if
612 @c we want to tell people that, the manual possibly
613 @c should say it).
614
615 If you want to avoid
616 starting an editor you can specify the log message on
617 the command line using the @samp{-m} flag instead, like
618 this:
619
620 @example
621 $ cvs commit -m "Added an optimization pass" backend.c
622 @end example
623
624 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
625 @node Cleaning up
626 @subsection Cleaning up
627 @cindex Cleaning up
628 @cindex Working copy, removing
629 @cindex Removing your working copy
630 @cindex Releasing your working copy
631
632 Before you turn to other tasks you decide to remove your working copy of
633 tc.  One acceptable way to do that is of course
634
635 @example
636 $ cd ..
637 $ rm -r tc
638 @end example
639
640 @noindent
641 but a better way is to use the @code{release} command (@pxref{release}):
642
643 @example
644 $ cd ..
645 $ cvs release -d tc
646 M driver.c
647 ? tc
648 You have [1] altered files in this repository.
649 Are you sure you want to release (and delete) directory `tc': n
650 ** `release' aborted by user choice.
651 @end example
652
653 The @code{release} command checks that all your modifications have been
654 committed.  If history logging is enabled it also makes a note in the
655 history file.  @xref{history file}.
656
657 When you use the @samp{-d} flag with @code{release}, it
658 also removes your working copy.
659
660 In the example above, the @code{release} command wrote a couple of lines
661 of output.  @samp{? tc} means that the file @file{tc} is unknown to @sc{cvs}.
662 That is nothing to worry about: @file{tc} is the executable compiler,
663 and it should not be stored in the repository.  @xref{cvsignore},
664 for information about how to make that warning go away.
665 @xref{release output}, for a complete explanation of
666 all possible output from @code{release}.
667
668 @samp{M driver.c} is more serious.  It means that the
669 file @file{driver.c} has been modified since it was
670 checked out.
671
672 The @code{release} command always finishes by telling
673 you how many modified files you have in your working
674 copy of the sources, and then asks you for confirmation
675 before deleting any files or making any note in the
676 history file.
677
678 You decide to play it safe and answer @kbd{n @key{RET}}
679 when @code{release} asks for confirmation.
680
681 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
682 @node Viewing differences
683 @subsection Viewing differences
684 @cindex Viewing differences
685 @cindex Diff
686
687 You do not remember modifying @file{driver.c}, so you want to see what
688 has happened to that file.
689
690 @example
691 $ cd tc
692 $ cvs diff driver.c
693 @end example
694
695 This command runs @code{diff} to compare the version of @file{driver.c}
696 that you checked out with your working copy.  When you see the output
697 you remember that you added a command line option that enabled the
698 optimization pass.  You check it in, and release the module.
699 @c FIXME: we haven't yet defined the term "check in".
700
701 @example
702 $ cvs commit -m "Added an optimization pass" driver.c
703 Checking in driver.c;
704 /usr/local/cvsroot/tc/driver.c,v  <--  driver.c
705 new revision: 1.2; previous revision: 1.1
706 done
707 $ cd ..
708 $ cvs release -d tc
709 ? tc
710 You have [0] altered files in this repository.
711 Are you sure you want to release (and delete) directory `tc': y
712 @end example
713
714 @c ---------------------------------------------------------------------
715 @node Repository
716 @chapter The Repository
717 @cindex Repository (intro)
718 @cindex Repository, example
719 @cindex Layout of repository
720 @cindex Typical repository
721 @cindex /usr/local/cvsroot, as example repository
722 @cindex cvsroot
723
724 The @sc{cvs} @dfn{repository} stores a complete copy of
725 all the files and directories which are under version
726 control.
727
728 Normally, you never access any of the files in the
729 repository directly.  Instead, you use @sc{cvs}
730 commands to get your own copy of the files into a
731 @dfn{working directory}, and then
732 work on that copy.  When you've finished a set of
733 changes, you check (or @dfn{commit}) them back into the
734 repository.  The repository then contains the changes
735 which you have made, as well as recording exactly what
736 you changed, when you changed it, and other such
737 information.  Note that the repository is not a
738 subdirectory of the working directory, or vice versa;
739 they should be in separate locations.
740 @c Need some example, e.g. repository
741 @c /usr/local/cvsroot; working directory
742 @c /home/joe/sources.  But this node is too long
743 @c as it is; need a little reorganization...
744
745 @cindex :local:, setting up
746 @sc{cvs} can access a repository by a variety of
747 means.  It might be on the local computer, or it might
748 be on a computer across the room or across the world.
749 To distinguish various ways to access a repository, the
750 repository name can start with an @dfn{access method}.
751 For example, the access method @code{:local:} means to
752 access a repository directory, so the repository
753 @code{:local:/usr/local/cvsroot} means that the
754 repository is in @file{/usr/local/cvsroot} on the
755 computer running @sc{cvs}.  For information on other
756 access methods, see @ref{Remote repositories}.
757
758 @c Can se say this more concisely?  Like by passing
759 @c more of the buck to the Remote repositories node?
760 If the access method is omitted, then if the repository
761 starts with @samp{/}, then @code{:local:} is
762 assumed.  If it does not start with @samp{/} then either
763 @code{:ext:} or @code{:server:} is assumed.  For
764 example, if you have a local repository in
765 @file{/usr/local/cvsroot}, you can use
766 @code{/usr/local/cvsroot} instead of
767 @code{:local:/usr/local/cvsroot}.  But if (under
768 Windows NT, for example) your local repository is
769 @file{c:\src\cvsroot}, then you must specify the access
770 method, as in @code{:local:c:/src/cvsroot}.
771
772 @c This might appear to go in Repository storage, but
773 @c actually it is describing something which is quite
774 @c user-visible, when you do a "cvs co CVSROOT".  This
775 @c isn't necessary the perfect place for that, though.
776 The repository is split in two parts.  @file{$CVSROOT/CVSROOT} contains
777 administrative files for @sc{cvs}.  The other directories contain the actual
778 user-defined modules.
779
780 @menu
781 * Specifying a repository::     Telling CVS where your repository is
782 * Repository storage::          The structure of the repository
783 * Working directory storage::   The structure of working directories
784 * Intro administrative files::  Defining modules
785 * Multiple repositories::       Multiple repositories
786 * Creating a repository::       Creating a repository
787 * Backing up::                  Backing up a repository
788 * Moving a repository::         Moving a repository
789 * Remote repositories::         Accessing repositories on remote machines
790 * Read-only access::            Granting read-only access to the repository
791 * Server temporary directory::  The server creates temporary directories
792 @end menu
793
794 @node Specifying a repository
795 @section Telling CVS where your repository is
796
797 There are several ways to tell @sc{cvs}
798 where to find the repository.  You can name the
799 repository on the command line explicitly, with the
800 @code{-d} (for "directory") option:
801
802 @example
803 cvs -d /usr/local/cvsroot checkout yoyodyne/tc
804 @end example
805
806 @cindex .profile, setting CVSROOT in
807 @cindex .cshrc, setting CVSROOT in
808 @cindex .tcshrc, setting CVSROOT in
809 @cindex .bashrc, setting CVSROOT in
810 @cindex CVSROOT, environment variable
811         Or you can set the @code{$CVSROOT} environment
812 variable to an absolute path to the root of the
813 repository, @file{/usr/local/cvsroot} in this example.
814 To set @code{$CVSROOT}, @code{csh} and @code{tcsh}
815 users should have this line in their @file{.cshrc} or
816 @file{.tcshrc} files:
817
818 @example
819 setenv CVSROOT /usr/local/cvsroot
820 @end example
821
822 @noindent
823 @code{sh} and @code{bash} users should instead have these lines in their
824 @file{.profile} or @file{.bashrc}:
825
826 @example
827 CVSROOT=/usr/local/cvsroot
828 export CVSROOT
829 @end example
830
831 @cindex Root file, in CVS directory
832 @cindex CVS/Root file
833         A repository specified with @code{-d} will
834 override the @code{$CVSROOT} environment variable.
835 Once you've checked a working copy out from the
836 repository, it will remember where its repository is
837 (the information is recorded in the
838 @file{CVS/Root} file in the working copy).
839
840 The @code{-d} option and the @file{CVS/Root} file both
841 override the @code{$CVSROOT} environment variable.  If
842 @code{-d} option differs from @file{CVS/Root}, the
843 former is used.  Of course, for proper operation they
844 should be two ways of referring to the same repository.
845
846 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
847 @node Repository storage
848 @section How data is stored in the repository
849 @cindex Repository, how data is stored
850
851 For most purposes it isn't important @emph{how}
852 @sc{cvs} stores information in the repository.  In
853 fact, the format has changed in the past, and is likely
854 to change in the future.  Since in almost all cases one
855 accesses the repository via @sc{cvs} commands, such
856 changes need not be disruptive.
857
858 However, in some cases it may be necessary to
859 understand how @sc{cvs} stores data in the repository,
860 for example you might need to track down @sc{cvs} locks
861 (@pxref{Concurrency}) or you might need to deal with
862 the file permissions appropriate for the repository.
863
864 @menu
865 * Repository files::            What files are stored in the repository
866 * File permissions::            File permissions
867 * Windows permissions::         Issues specific to Windows
868 * Attic::                       Some files are stored in the Attic
869 * CVS in repository::           Additional information in CVS directory
870 * Locks::                       CVS locks control concurrent accesses
871 * CVSROOT storage::             A few things about CVSROOT are different
872 @end menu
873
874 @node Repository files
875 @subsection Where files are stored within the repository
876
877 @c @cindex Filenames, legal
878 @c @cindex Legal filenames
879 @c Somewhere we need to say something about legitimate
880 @c characters in filenames in working directory and
881 @c repository.  Not "/" (not even on non-unix).  And
882 @c here is a specific set of issues:
883 @c      Files starting with a - are handled inconsistently. They can not
884 @c   be added to a repository with an add command, because it they are
885 @c   interpreted as a switch. They can appear in a repository if they are
886 @c   part of a tree that is imported. They can not be removed from the tree
887 @c   once they are there.
888 @c Note that "--" *is* supported (as a
889 @c consequence of using GNU getopt).  Should document
890 @c this somewhere ("Common options"?).  The other usual technique,
891 @c "./-foo", isn't as effective, at least for "cvs add"
892 @c which doesn't support pathnames containing "/".
893
894 The overall structure of the repository is a directory
895 tree corresponding to the directories in the working
896 directory.  For example, supposing the repository is in
897
898 @example
899 /usr/local/cvsroot
900 @end example
901
902 @noindent
903 here is a possible directory tree (showing only the
904 directories):
905
906 @example
907 @t{/usr}
908  |
909  +--@t{local}
910  |   |
911  |   +--@t{cvsroot}
912  |   |    |
913  |   |    +--@t{CVSROOT}
914           |      (administrative files)
915           |
916           +--@t{gnu}
917           |   |
918           |   +--@t{diff}
919           |   |   (source code to @sc{gnu} diff)
920           |   |
921           |   +--@t{rcs}
922           |   |   (source code to @sc{rcs})
923           |   |
924           |   +--@t{cvs}
925           |       (source code to @sc{cvs})
926           |
927           +--@t{yoyodyne}
928               |
929               +--@t{tc}
930               |    |
931               |    +--@t{man}
932               |    |
933               |    +--@t{testing}
934               |
935               +--(other Yoyodyne software)
936 @end example
937
938 With the directories are @dfn{history files} for each file
939 under version control.  The name of the history file is
940 the name of the corresponding file with @samp{,v}
941 appended to the end.  Here is what the repository for
942 the @file{yoyodyne/tc} directory might look like:
943 @c FIXME: Should also mention CVS (CVSREP)
944 @c FIXME? Should we introduce Attic with an xref to
945 @c Attic?  Not sure whether that is a good idea or not.
946 @example
947   @code{$CVSROOT}
948     |
949     +--@t{yoyodyne}
950     |   |
951     |   +--@t{tc}
952     |   |   |
953             +--@t{Makefile,v}
954             +--@t{backend.c,v}
955             +--@t{driver.c,v}
956             +--@t{frontend.c,v}
957             +--@t{parser.c,v}
958             +--@t{man}
959             |    |
960             |    +--@t{tc.1,v}
961             |
962             +--@t{testing}
963                  |
964                  +--@t{testpgm.t,v}
965                  +--@t{test2.t,v}
966 @end example
967
968 @cindex History files
969 @cindex RCS history files
970 @c The first sentence, about what history files
971 @c contain, is kind of redundant with our intro to what the
972 @c repository does in node Repository....
973 The history files contain, among other things, enough
974 information to recreate any revision of the file, a log
975 of all commit messages and the user-name of the person
976 who committed the revision.  The history files are
977 known as @dfn{RCS files}, because the first program to
978 store files in that format was a version control system
979 known as @sc{rcs}.  For a full
980 description of the file format, see the @code{man} page
981 @cite{rcsfile(5)}, distributed with @sc{rcs}, or the
982 file @file{doc/RCSFILES} in the @sc{cvs} source
983 distribution.  This
984 file format has become very common---many systems other
985 than @sc{cvs} or @sc{rcs} can at least import history
986 files in this format.
987 @c FIXME: Think about including documentation for this
988 @c rather than citing it?  In the long run, getting
989 @c this to be a standard (not sure if we can cope with
990 @c a standards process as formal as IEEE/ANSI/ISO/etc,
991 @c though...) is the way to go, so maybe citing is
992 @c better.
993
994 The @sc{rcs} files used in @sc{cvs} differ in a few
995 ways from the standard format.  The biggest difference
996 is magic branches; for more information see @ref{Magic
997 branch numbers}.  Also in @sc{cvs} the valid tag names
998 are a subset of what @sc{rcs} accepts; for @sc{cvs}'s
999 rules see @ref{Tags}.
1000
1001 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1002 @node File permissions
1003 @subsection File permissions
1004 @c -- Move this to @node Creating a repository or similar
1005 @cindex Security, file permissions in repository
1006 @cindex File permissions, general
1007 @cindex Permissions, general
1008 @c FIXME: we need to somehow reflect "permissions in
1009 @c repository" versus "permissions in working
1010 @c directory" in the index entries.
1011 @cindex Group, UNIX file permissions, in repository
1012 @cindex Read-only files, in repository
1013 All @samp{,v} files are created read-only, and you
1014 should not change the permission of those files.  The
1015 directories inside the repository should be writable by
1016 the persons that have permission to modify the files in
1017 each directory.  This normally means that you must
1018 create a UNIX group (see group(5)) consisting of the
1019 persons that are to edit the files in a project, and
1020 set up the repository so that it is that group that
1021 owns the directory.
1022 (On some systems, you also need to set the set-group-ID-on-execution bit
1023 on the repository directories (see chmod(1)) so that newly-created files
1024 and directories get the group-ID of the parent directory rather than
1025 that of the current process.)
1026
1027 @c See also comment in commitinfo node regarding cases
1028 @c which are really awkward with unix groups.
1029
1030 This means that you can only control access to files on
1031 a per-directory basis.
1032
1033 Note that users must also have write access to check
1034 out files, because @sc{cvs} needs to create lock files
1035 (@pxref{Concurrency}).  You can use LockDir in CVSROOT/config
1036 to put the lock files somewhere other than in the repository
1037 if you want to allow read-only access to some directories
1038 (@pxref{config}).
1039
1040 @c CVS seems to use CVSUMASK in picking permissions for
1041 @c val-tags, but maybe we should say more about this.
1042 @c Like val-tags gets created by someone who doesn't
1043 @c have CVSUMASK set right?
1044 @cindex CVSROOT/val-tags file, and read-only access to projects
1045 @cindex val-tags file, and read-only access to projects
1046 Also note that users must have write access to the
1047 @file{CVSROOT/val-tags} file.  @sc{cvs} uses it to keep
1048 track of what tags are valid tag names (it is sometimes
1049 updated when tags are used, as well as when they are
1050 created).
1051
1052 Each @sc{rcs} file will be owned by the user who last
1053 checked it in.  This has little significance; what
1054 really matters is who owns the directories.
1055
1056 @cindex CVSUMASK, environment variable
1057 @cindex Umask, for repository files
1058 @sc{cvs} tries to set up reasonable file permissions
1059 for new directories that are added inside the tree, but
1060 you must fix the permissions manually when a new
1061 directory should have different permissions than its
1062 parent directory.  If you set the @code{CVSUMASK}
1063 environment variable that will control the file
1064 permissions which @sc{cvs} uses in creating directories
1065 and/or files in the repository.  @code{CVSUMASK} does
1066 not affect the file permissions in the working
1067 directory; such files have the permissions which are
1068 typical for newly created files, except that sometimes
1069 @sc{cvs} creates them read-only (see the sections on
1070 watches, @ref{Setting a watch}; -r, @ref{Global
1071 options}; or @code{CVSREAD}, @ref{Environment variables}).
1072 @c FIXME: Need more discussion of which
1073 @c group should own the file in the repository.
1074 @c Include a somewhat detailed example of the usual
1075 @c case where CVSUMASK is 007, the developers are all
1076 @c in a group, and that group owns stuff in the
1077 @c repository.  Need to talk about group ownership of
1078 @c newly-created directories/files (on some unices,
1079 @c such as SunOS4, setting the setgid bit on the
1080 @c directories will make files inherit the directory's
1081 @c group.  On other unices, your mileage may vary.  I
1082 @c can't remember what POSIX says about this, if
1083 @c anything).
1084
1085 Note that using the client/server @sc{cvs}
1086 (@pxref{Remote repositories}), there is no good way to
1087 set @code{CVSUMASK}; the setting on the client machine
1088 has no effect.  If you are connecting with @code{rsh}, you
1089 can set @code{CVSUMASK} in @file{.bashrc} or @file{.cshrc}, as
1090 described in the documentation for your operating
1091 system.  This behavior might change in future versions
1092 of @sc{cvs}; do not rely on the setting of
1093 @code{CVSUMASK} on the client having no effect.
1094 @c FIXME: need to explain what a umask is or cite
1095 @c someplace which does.
1096 @c
1097 @c There is also a larger (largely separate) issue
1098 @c about the meaning of CVSUMASK in a non-unix context.
1099 @c For example, whether there is
1100 @c an equivalent which fits better into other
1101 @c protection schemes like POSIX.6, VMS, &c.
1102 @c
1103 @c FIXME: Need one place which discusses this
1104 @c read-only files thing.  Why would one use -r or
1105 @c CVSREAD?  Why would one use watches?  How do they
1106 @c interact?
1107 @c
1108 @c FIXME: We need to state
1109 @c whether using CVSUMASK removes the need for manually
1110 @c fixing permissions (in fact, if we are going to mention
1111 @c manually fixing permission, we better document a lot
1112 @c better just what we mean by "fix").
1113
1114 Using pserver, you will generally need stricter
1115 permissions on the @sc{cvsroot} directory and
1116 directories above it in the tree; see @ref{Password
1117 authentication security}.
1118
1119 @cindex Setuid
1120 @cindex Setgid
1121 @cindex Security, setuid
1122 @cindex Installed images (VMS)
1123 Some operating systems have features which allow a
1124 particular program to run with the ability to perform
1125 operations which the caller of the program could not.
1126 For example, the set user ID (setuid) or set group ID
1127 (setgid) features of unix or the installed image
1128 feature of VMS.  @sc{cvs} was not written to use such
1129 features and therefore attempting to install @sc{cvs} in
1130 this fashion will provide protection against only
1131 accidental lapses; anyone who is trying to circumvent
1132 the measure will be able to do so, and depending on how
1133 you have set it up may gain access to more than just
1134 @sc{cvs}.  You may wish to instead consider pserver.  It
1135 shares some of the same attributes, in terms of
1136 possibly providing a false sense of security or opening
1137 security holes wider than the ones you are trying to
1138 fix, so read the documentation on pserver security
1139 carefully if you are considering this option
1140 (@ref{Password authentication security}).
1141
1142 @node Windows permissions
1143 @subsection File Permission issues specific to Windows
1144 @cindex Windows, and permissions
1145 @cindex File permissions, Windows-specific
1146 @cindex Permissions, Windows-specific
1147
1148 Some file permission issues are specific to Windows
1149 operating systems (Windows 95, Windows NT, and
1150 presumably future operating systems in this family.
1151 Some of the following might apply to OS/2 but I'm not
1152 sure).
1153
1154 If you are using local @sc{cvs} and the repository is on a
1155 networked file system which is served by the Samba SMB
1156 server, some people have reported problems with
1157 permissions.  Enabling WRITE=YES in the samba
1158 configuration is said to fix/workaround it.
1159 Disclaimer: I haven't investigated enough to know the
1160 implications of enabling that option, nor do I know
1161 whether there is something which @sc{cvs} could be doing
1162 differently in order to avoid the problem.  If you find
1163 something out, please let us know as described in
1164 @ref{BUGS}.
1165
1166 @node Attic
1167 @subsection The attic
1168 @cindex Attic
1169
1170 You will notice that sometimes @sc{cvs} stores an
1171 @sc{rcs} file in the @code{Attic}.  For example, if the
1172 @sc{cvsroot} is @file{/usr/local/cvsroot} and we are
1173 talking about the file @file{backend.c} in the
1174 directory @file{yoyodyne/tc}, then the file normally
1175 would be in
1176
1177 @example
1178 /usr/local/cvsroot/yoyodyne/tc/backend.c,v
1179 @end example
1180
1181 @noindent
1182 but if it goes in the attic, it would be in
1183
1184 @example
1185 /usr/local/cvsroot/yoyodyne/tc/Attic/backend.c,v
1186 @end example
1187
1188 @noindent
1189 @cindex Dead state
1190 instead.  It should not matter from a user point of
1191 view whether a file is in the attic; @sc{cvs} keeps
1192 track of this and looks in the attic when it needs to.
1193 But in case you want to know, the rule is that the RCS
1194 file is stored in the attic if and only if the head
1195 revision on the trunk has state @code{dead}.  A
1196 @code{dead} state means that file has been removed, or
1197 never added, for that revision.  For example, if you
1198 add a file on a branch, it will have a trunk revision
1199 in @code{dead} state, and a branch revision in a
1200 non-@code{dead} state.
1201 @c Probably should have some more concrete examples
1202 @c here, or somewhere (not sure exactly how we should
1203 @c arrange the discussion of the dead state, versus
1204 @c discussion of the attic).
1205
1206 @node CVS in repository
1207 @subsection The CVS directory in the repository
1208 @cindex CVS directory, in repository
1209
1210 The @file{CVS} directory in each repository directory
1211 contains information such as file attributes (in a file
1212 called @file{CVS/fileattr}.  In the
1213 future additional files may be added to this directory,
1214 so implementations should silently ignore additional
1215 files.
1216
1217 This behavior is implemented only by @sc{cvs} 1.7 and
1218 later; for details see @ref{Watches Compatibility}.
1219
1220 The format of the @file{fileattr} file is a series of entries
1221 of the following form (where @samp{@{} and @samp{@}}
1222 means the text between the braces can be repeated zero
1223 or more times):
1224
1225 @var{ent-type} @var{filename} <tab> @var{attrname} = @var{attrval}
1226   @{; @var{attrname} = @var{attrval}@} <linefeed>
1227
1228 @var{ent-type} is @samp{F} for a file, in which case the entry specifies the
1229 attributes for that file.
1230
1231 @var{ent-type} is @samp{D},
1232 and @var{filename} empty, to specify default attributes
1233 to be used for newly added files.
1234
1235 Other @var{ent-type} are reserved for future expansion.  @sc{cvs} 1.9 and older
1236 will delete them any time it writes file attributes.
1237 @sc{cvs} 1.10 and later will preserve them.
1238
1239 Note that the order of the lines is not significant;
1240 a program writing the fileattr file may
1241 rearrange them at its convenience.
1242
1243 There is currently no way of quoting tabs or line feeds in the
1244 filename, @samp{=} in @var{attrname},
1245 @samp{;} in @var{attrval}, etc.  Note: some implementations also
1246 don't handle a NUL character in any of the fields, but
1247 implementations are encouraged to allow it.
1248
1249 By convention, @var{attrname} starting with @samp{_} is for an attribute given
1250 special meaning by @sc{cvs}; other @var{attrname}s are for user-defined attributes
1251 (or will be, once implementations start supporting user-defined attributes).
1252
1253 Built-in attributes:
1254
1255 @table @code
1256 @item _watched
1257 Present means the file is watched and should be checked out
1258 read-only.
1259
1260 @item _watchers
1261 Users with watches for this file.  Value is
1262 @var{watcher} > @var{type} @{ , @var{watcher} > @var{type} @}
1263 where @var{watcher} is a username, and @var{type}
1264 is zero or more of edit,unedit,commit separated by
1265 @samp{+} (that is, nothing if none; there is no "none" or "all" keyword).
1266
1267 @item _editors
1268 Users editing this file.  Value is
1269 @var{editor} > @var{val} @{ , @var{editor} > @var{val} @}
1270 where @var{editor} is a username, and @var{val} is
1271 @var{time}+@var{hostname}+@var{pathname}, where
1272 @var{time} is when the @code{cvs edit} command (or
1273 equivalent) happened,
1274 and @var{hostname} and @var{pathname} are for the working directory.
1275 @end table
1276
1277 Example:
1278
1279 @c FIXME: sanity.sh should contain a similar test case
1280 @c so we can compare this example from something from
1281 @c Real Life(TM).  See cvsclient.texi (under Notify) for more
1282 @c discussion of the date format of _editors.
1283 @example
1284 Ffile1 _watched=;_watchers=joe>edit,mary>commit
1285 Ffile2 _watched=;_editors=sue>8 Jan 1975+workstn1+/home/sue/cvs
1286 D _watched=
1287 @end example
1288
1289 @noindent
1290 means that the file @file{file1} should be checked out
1291 read-only.  Furthermore, joe is watching for edits and
1292 mary is watching for commits.  The file @file{file2}
1293 should be checked out read-only; sue started editing it
1294 on 8 Jan 1975 in the directory @file{/home/sue/cvs} on
1295 the machine @code{workstn1}.  Future files which are
1296 added should be checked out read-only.  To represent
1297 this example here, we have shown a space after
1298 @samp{D}, @samp{Ffile1}, and @samp{Ffile2}, but in fact
1299 there must be a single tab character there and no spaces.
1300
1301 @node Locks
1302 @subsection CVS locks in the repository
1303
1304 @cindex #cvs.rfl, technical details
1305 @cindex #cvs.pfl, technical details
1306 @cindex #cvs.wfl, technical details
1307 @cindex #cvs.lock, technical details
1308 @cindex Locks, cvs, technical details
1309 For an introduction to @sc{cvs} locks focusing on
1310 user-visible behavior, see @ref{Concurrency}.  The
1311 following section is aimed at people who are writing
1312 tools which want to access a @sc{cvs} repository without
1313 interfering with other tools accessing the same
1314 repository.  If you find yourself confused by concepts
1315 described here, like @dfn{read lock}, @dfn{write lock},
1316 and @dfn{deadlock}, you might consult the literature on
1317 operating systems or databases.
1318
1319 @cindex #cvs.tfl
1320 Any file in the repository with a name starting
1321 with @file{#cvs.rfl.} is a read lock.  Any file in
1322 the repository with a name starting with
1323 @file{#cvs.pfl} is a promotable read lock.  Any file in
1324 the repository with a name starting with
1325 @file{#cvs.wfl} is a write lock.  Old versions of @sc{cvs}
1326 (before @sc{cvs} 1.5) also created files with names starting
1327 with @file{#cvs.tfl}, but they are not discussed here.
1328 The directory @file{#cvs.lock} serves as a master
1329 lock.  That is, one must obtain this lock first before
1330 creating any of the other locks.
1331
1332 To obtain a read lock, first create the @file{#cvs.lock}
1333 directory.  This operation must be atomic (which should
1334 be true for creating a directory under most operating
1335 systems).  If it fails because the directory already
1336 existed, wait for a while and try again.  After
1337 obtaining the @file{#cvs.lock} lock, create a file
1338 whose name is @file{#cvs.rfl.} followed by information
1339 of your choice (for example, hostname and process
1340 identification number).  Then remove the
1341 @file{#cvs.lock} directory to release the master lock.
1342 Then proceed with reading the repository.  When you are
1343 done, remove the @file{#cvs.rfl} file to release the
1344 read lock.
1345
1346 Promotable read locks are a concept you may not find in other literature on
1347 concurrency.  They are used to allow a two (or more) pass process to only lock
1348 a file for read on the first (read) pass(es), then upgrade its read locks to
1349 write locks if necessary for a final pass, still assured that the files have
1350 not changed since they were first read.  @sc{cvs} uses promotable read locks,
1351 for example, to prevent commit and tag verification passes from interfering
1352 with other reading processes.  It can then lock only a single directory at a
1353 time for write during the write pass.
1354
1355 To obtain a promotable read lock, first create the @file{#cvs.lock} directory,
1356 as with a non-promotable read lock.  Then check
1357 that there are no files that start with
1358 @file{#cvs.pfl}.  If there are, remove the master @file{#cvs.lock} directory,
1359 wait awhile (CVS waits 30 seconds between lock attempts), and try again.  If
1360 there are no other promotable locks, go ahead and create a file whose name is
1361 @file{#cvs.pfl} followed by information of your choice (for example, CVS uses
1362 its hostname and the process identification number of the CVS server process
1363 creating the lock).  If versions of @sc{cvs} older than version 1.12.4 access
1364 your repository directly (not via a @sc{cvs} server of version 1.12.4 or
1365 later), then you should also create a read lock since older versions of CVS
1366 will ignore the promotable lock when attempting to create their own write lock.
1367 Then remove the master @file{#cvs.lock} directory in order to allow other
1368 processes to obtain read locks.
1369
1370 To obtain a write lock, first create the
1371 @file{#cvs.lock} directory, as with read locks.  Then
1372 check that there are no files whose names start with
1373 @file{#cvs.rfl.} and no files whose names start with @file{#cvs.pfl} that are
1374 not owned by the process attempting to get the write lock.  If either exist,
1375 remove @file{#cvs.lock}, wait for a while, and try again.  If
1376 there are no readers or promotable locks from other processes, then create a
1377 file whose name is @file{#cvs.wfl} followed by information of your choice
1378 (again, CVS uses the hostname and server process identification
1379 number).  Remove your @file{#cvs.pfl} file if present.  Hang on to the
1380 @file{#cvs.lock} lock.  Proceed
1381 with writing the repository.  When you are done, first
1382 remove the @file{#cvs.wfl} file and then the
1383 @file{#cvs.lock} directory. Note that unlike the
1384 @file{#cvs.rfl} file, the @file{#cvs.wfl} file is just
1385 informational; it has no effect on the locking operation
1386 beyond what is provided by holding on to the
1387 @file{#cvs.lock} lock itself.
1388
1389 Note that each lock (write lock or read lock) only locks
1390 a single directory in the repository, including
1391 @file{Attic} and @file{CVS} but not including
1392 subdirectories which represent other directories under
1393 version control.  To lock an entire tree, you need to
1394 lock each directory (note that if you fail to obtain
1395 any lock you need, you must release the whole tree
1396 before waiting and trying again, to avoid deadlocks).
1397
1398 Note also that @sc{cvs} expects write locks to control
1399 access to individual @file{foo,v} files.  @sc{rcs} has
1400 a scheme where the @file{,foo,} file serves as a lock,
1401 but @sc{cvs} does not implement it and so taking out a
1402 @sc{cvs} write lock is recommended.  See the comments at
1403 rcs_internal_lockfile in the @sc{cvs} source code for
1404 further discussion/rationale.
1405
1406 @node CVSROOT storage
1407 @subsection How files are stored in the CVSROOT directory
1408 @cindex CVSROOT, storage of files
1409
1410 The @file{$CVSROOT/CVSROOT} directory contains the
1411 various administrative files.  In some ways this
1412 directory is just like any other directory in the
1413 repository; it contains @sc{rcs} files whose names end
1414 in @samp{,v}, and many of the @sc{cvs} commands operate
1415 on it the same way.  However, there are a few
1416 differences.
1417
1418 For each administrative file, in addition to the
1419 @sc{rcs} file, there is also a checked out copy of the
1420 file.  For example, there is an @sc{rcs} file
1421 @file{loginfo,v} and a file @file{loginfo} which
1422 contains the latest revision contained in
1423 @file{loginfo,v}.  When you check in an administrative
1424 file, @sc{cvs} should print
1425
1426 @example
1427 cvs commit: Rebuilding administrative file database
1428 @end example
1429
1430 @noindent
1431 and update the checked out copy in
1432 @file{$CVSROOT/CVSROOT}.  If it does not, there is
1433 something wrong (@pxref{BUGS}).  To add your own files
1434 to the files to be updated in this fashion, you can add
1435 them to the @file{checkoutlist} administrative file
1436 (@pxref{checkoutlist}).
1437
1438 @cindex modules.db
1439 @cindex modules.pag
1440 @cindex modules.dir
1441 By default, the @file{modules} file behaves as
1442 described above.  If the modules file is very large,
1443 storing it as a flat text file may make looking up
1444 modules slow (I'm not sure whether this is as much of a
1445 concern now as when @sc{cvs} first evolved this
1446 feature; I haven't seen benchmarks).  Therefore, by
1447 making appropriate edits to the @sc{cvs} source code
1448 one can store the modules file in a database which
1449 implements the @code{ndbm} interface, such as Berkeley
1450 db or GDBM.  If this option is in use, then the modules
1451 database will be stored in the files @file{modules.db},
1452 @file{modules.pag}, and/or @file{modules.dir}.
1453 @c I think fileattr also will use the database stuff.
1454 @c Anything else?
1455
1456 For information on the meaning of the various
1457 administrative files, see @ref{Administrative files}.
1458
1459 @node Working directory storage
1460 @section How data is stored in the working directory
1461
1462 @c FIXME: Somewhere we should discuss timestamps (test
1463 @c case "stamps" in sanity.sh).  But not here.  Maybe
1464 @c in some kind of "working directory" chapter which
1465 @c would encompass the "Builds" one?  But I'm not sure
1466 @c whether that is a good organization (is it based on
1467 @c what the user wants to do?).
1468
1469 @cindex CVS directory, in working directory
1470 While we are discussing @sc{cvs} internals which may
1471 become visible from time to time, we might as well talk
1472 about what @sc{cvs} puts in the @file{CVS} directories
1473 in the working directories.  As with the repository,
1474 @sc{cvs} handles this information and one can usually
1475 access it via @sc{cvs} commands.  But in some cases it
1476 may be useful to look at it, and other programs, such
1477 as the @code{jCVS} graphical user interface or the
1478 @code{VC} package for emacs, may need to look at it.
1479 Such programs should follow the recommendations in this
1480 section if they hope to be able to work with other
1481 programs which use those files, including future
1482 versions of the programs just mentioned and the
1483 command-line @sc{cvs} client.
1484
1485 The @file{CVS} directory contains several files.
1486 Programs which are reading this directory should
1487 silently ignore files which are in the directory but
1488 which are not documented here, to allow for future
1489 expansion.
1490
1491 The files are stored according to the text file
1492 convention for the system in question.  This means that
1493 working directories are not portable between systems
1494 with differing conventions for storing text files.
1495 This is intentional, on the theory that the files being
1496 managed by @sc{cvs} probably will not be portable between
1497 such systems either.
1498
1499 @table @file
1500 @item Root
1501 This file contains the current @sc{cvs} root, as
1502 described in @ref{Specifying a repository}.
1503
1504 @cindex Repository file, in CVS directory
1505 @cindex CVS/Repository file
1506 @item Repository
1507 This file contains the directory within the repository
1508 which the current directory corresponds with.  It can
1509 be either an absolute pathname or a relative pathname;
1510 @sc{cvs} has had the ability to read either format
1511 since at least version 1.3 or so.  The relative
1512 pathname is relative to the root, and is the more
1513 sensible approach, but the absolute pathname is quite
1514 common and implementations should accept either.  For
1515 example, after the command
1516
1517 @example
1518 cvs -d :local:/usr/local/cvsroot checkout yoyodyne/tc
1519 @end example
1520
1521 @noindent
1522 @file{Root} will contain
1523
1524 @example
1525 :local:/usr/local/cvsroot
1526 @end example
1527
1528 @noindent
1529 and @file{Repository} will contain either
1530
1531 @example
1532 /usr/local/cvsroot/yoyodyne/tc
1533 @end example
1534
1535 @noindent
1536 or
1537
1538 @example
1539 yoyodyne/tc
1540 @end example
1541
1542 If the particular working directory does not correspond
1543 to a directory in the repository, then @file{Repository}
1544 should contain @file{CVSROOT/Emptydir}.
1545 @cindex Emptydir, in CVSROOT directory
1546 @cindex CVSROOT/Emptydir directory
1547
1548 @cindex Entries file, in CVS directory
1549 @cindex CVS/Entries file
1550 @item Entries
1551 This file lists the files and directories in the
1552 working directory.
1553 The first character of each line indicates what sort of
1554 line it is.  If the character is unrecognized, programs
1555 reading the file should silently skip that line, to
1556 allow for future expansion.
1557
1558 If the first character is @samp{/}, then the format is:
1559
1560 @example
1561 /@var{name}/@var{revision}/@var{timestamp}[+@var{conflict}]/@var{options}/@var{tagdate}
1562 @end example
1563
1564 @noindent
1565 where @samp{[} and @samp{]} are not part of the entry,
1566 but instead indicate that the @samp{+} and conflict
1567 marker are optional.  @var{name} is the name of the
1568 file within the directory.  @var{revision} is the
1569 revision that the file in the working derives from, or
1570 @samp{0} for an added file, or @samp{-} followed by a
1571 revision for a removed file.  @var{timestamp} is the
1572 timestamp of the file at the time that @sc{cvs} created
1573 it; if the timestamp differs with the actual
1574 modification time of the file it means the file has
1575 been modified.  It is stored in
1576 the format used by the ISO C asctime() function (for
1577 example, @samp{Sun Apr  7 01:29:26 1996}).  One may
1578 write a string which is not in that format, for
1579 example, @samp{Result of merge}, to indicate that the
1580 file should always be considered to be modified.  This
1581 is not a special case; to see whether a file is
1582 modified a program should take the timestamp of the file
1583 and simply do a string compare with @var{timestamp}.
1584 If there was a conflict, @var{conflict} can be set to
1585 the modification time of the file after the file has been
1586 written with conflict markers (@pxref{Conflicts example}).
1587 Thus if @var{conflict} is subsequently the same as the actual
1588 modification time of the file it means that the user
1589 has obviously not resolved the conflict.  @var{options}
1590 contains sticky options (for example @samp{-kb} for a
1591 binary file).  @var{tagdate} contains @samp{T} followed
1592 by a tag name, or @samp{D} for a date, followed by a
1593 sticky tag or date.  Note that if @var{timestamp}
1594 contains a pair of timestamps separated by a space,
1595 rather than a single timestamp, you are dealing with a
1596 version of @sc{cvs} earlier than @sc{cvs} 1.5 (not
1597 documented here).
1598
1599 The timezone on the timestamp in CVS/Entries (local or
1600 universal) should be the same as the operating system
1601 stores for the timestamp of the file itself.  For
1602 example, on Unix the file's timestamp is in universal
1603 time (UT), so the timestamp in CVS/Entries should be
1604 too.  On @sc{vms}, the file's timestamp is in local
1605 time, so @sc{cvs} on @sc{vms} should use local time.
1606 This rule is so that files do not appear to be modified
1607 merely because the timezone changed (for example, to or
1608 from summer time).
1609 @c See comments and calls to gmtime() and friends in
1610 @c src/vers_ts.c (function time_stamp).
1611
1612 If the first character of a line in @file{Entries} is
1613 @samp{D}, then it indicates a subdirectory.  @samp{D}
1614 on a line all by itself indicates that the program
1615 which wrote the @file{Entries} file does record
1616 subdirectories (therefore, if there is such a line and
1617 no other lines beginning with @samp{D}, one knows there
1618 are no subdirectories).  Otherwise, the line looks
1619 like:
1620
1621 @example
1622 D/@var{name}/@var{filler1}/@var{filler2}/@var{filler3}/@var{filler4}
1623 @end example
1624
1625 @noindent
1626 where @var{name} is the name of the subdirectory, and
1627 all the @var{filler} fields should be silently ignored,
1628 for future expansion.  Programs which modify
1629 @code{Entries} files should preserve these fields.
1630
1631 The lines in the @file{Entries} file can be in any order.
1632
1633 @cindex Entries.Log file, in CVS directory
1634 @cindex CVS/Entries.Log file
1635 @item Entries.Log
1636 This file does not record any information beyond that
1637 in @file{Entries}, but it does provide a way to update
1638 the information without having to rewrite the entire
1639 @file{Entries} file, including the ability to preserve
1640 the information even if the program writing
1641 @file{Entries} and @file{Entries.Log} abruptly aborts.
1642 Programs which are reading the @file{Entries} file
1643 should also check for @file{Entries.Log}.  If the latter
1644 exists, they should read @file{Entries} and then apply
1645 the changes mentioned in @file{Entries.Log}.  After
1646 applying the changes, the recommended practice is to
1647 rewrite @file{Entries} and then delete @file{Entries.Log}.
1648 The format of a line in @file{Entries.Log} is a single
1649 character command followed by a space followed by a
1650 line in the format specified for a line in
1651 @file{Entries}.  The single character command is
1652 @samp{A} to indicate that the entry is being added,
1653 @samp{R} to indicate that the entry is being removed,
1654 or any other character to indicate that the entire line
1655 in @file{Entries.Log} should be silently ignored (for
1656 future expansion).  If the second character of the line
1657 in @file{Entries.Log} is not a space, then it was
1658 written by an older version of @sc{cvs} (not documented
1659 here).
1660
1661 Programs which are writing rather than reading can
1662 safely ignore @file{Entries.Log} if they so choose.
1663
1664 @cindex Entries.Backup file, in CVS directory
1665 @cindex CVS/Entries.Backup file
1666 @item Entries.Backup
1667 This is a temporary file.  Recommended usage is to
1668 write a new entries file to @file{Entries.Backup}, and
1669 then to rename it (atomically, where possible) to @file{Entries}.
1670
1671 @cindex Entries.Static file, in CVS directory
1672 @cindex CVS/Entries.Static file
1673 @item Entries.Static
1674 The only relevant thing about this file is whether it
1675 exists or not.  If it exists, then it means that only
1676 part of a directory was gotten and @sc{cvs} will
1677 not create additional files in that directory.  To
1678 clear it, use the @code{update} command with the
1679 @samp{-d} option, which will get the additional files
1680 and remove @file{Entries.Static}.
1681 @c FIXME: This needs to be better documented, in places
1682 @c other than Working Directory Storage.
1683 @c FIXCVS: The fact that this setting exists needs to
1684 @c be more visible to the user.  For example "cvs
1685 @c status foo", in the case where the file would be
1686 @c gotten except for Entries.Static, might say
1687 @c something to distinguish this from other cases.
1688 @c One thing that periodically gets suggested is to
1689 @c have "cvs update" print something when it skips
1690 @c files due to Entries.Static, but IMHO that kind of
1691 @c noise pretty much makes the Entries.Static feature
1692 @c useless.
1693
1694 @cindex Tag file, in CVS directory
1695 @cindex CVS/Tag file
1696 @cindex Sticky tags/dates, per-directory
1697 @cindex Per-directory sticky tags/dates
1698 @item Tag
1699 This file contains per-directory sticky tags or dates.
1700 The first character is @samp{T} for a branch tag,
1701 @samp{N} for a non-branch tag, or @samp{D} for a date,
1702 or another character to mean the file should be
1703 silently ignored, for future expansion.  This character
1704 is followed by the tag or date.  Note that
1705 per-directory sticky tags or dates are used for things
1706 like applying to files which are newly added; they
1707 might not be the same as the sticky tags or dates on
1708 individual files.  For general information on sticky
1709 tags and dates, see @ref{Sticky tags}.
1710 @c FIXME: This needs to be much better documented,
1711 @c preferably not in the context of "working directory
1712 @c storage".
1713 @c FIXME: The Sticky tags node needs to discuss, or xref to
1714 @c someplace which discusses, per-directory sticky
1715 @c tags and the distinction with per-file sticky tags.
1716
1717 @cindex Notify file, in CVS directory
1718 @cindex CVS/Notify file
1719 @item Notify
1720 This file stores notifications (for example, for
1721 @code{edit} or @code{unedit}) which have not yet been
1722 sent to the server.  Its format is not yet documented
1723 here.
1724
1725 @cindex Notify.tmp file, in CVS directory
1726 @cindex CVS/Notify.tmp file
1727 @item Notify.tmp
1728 This file is to @file{Notify} as @file{Entries.Backup}
1729 is to @file{Entries}.  That is, to write @file{Notify},
1730 first write the new contents to @file{Notify.tmp} and
1731 then (atomically where possible), rename it to
1732 @file{Notify}.
1733
1734 @cindex Base directory, in CVS directory
1735 @cindex CVS/Base directory
1736 @item Base
1737 If watches are in use, then an @code{edit} command
1738 stores the original copy of the file in the @file{Base}
1739 directory.  This allows the @code{unedit} command to
1740 operate even if it is unable to communicate with the
1741 server.
1742
1743 @cindex Baserev file, in CVS directory
1744 @cindex CVS/Baserev file
1745 @item Baserev
1746 The file lists the revision for each of the files in
1747 the @file{Base} directory.  The format is:
1748
1749 @example
1750 B@var{name}/@var{rev}/@var{expansion}
1751 @end example
1752
1753 @noindent
1754 where @var{expansion} should be ignored, to allow for
1755 future expansion.
1756
1757 @cindex Baserev.tmp file, in CVS directory
1758 @cindex CVS/Baserev.tmp file
1759 @item Baserev.tmp
1760 This file is to @file{Baserev} as @file{Entries.Backup}
1761 is to @file{Entries}.  That is, to write @file{Baserev},
1762 first write the new contents to @file{Baserev.tmp} and
1763 then (atomically where possible), rename it to
1764 @file{Baserev}.
1765
1766 @cindex Template file, in CVS directory
1767 @cindex CVS/Template file
1768 @item Template
1769 This file contains the template specified by the
1770 @file{rcsinfo} file (@pxref{rcsinfo}).  It is only used
1771 by the client; the non-client/server @sc{cvs} consults
1772 @file{rcsinfo} directly.
1773 @end table
1774
1775 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1776 @node Intro administrative files
1777 @section The administrative files
1778 @cindex Administrative files (intro)
1779 @cindex Modules file
1780 @cindex CVSROOT, module name
1781 @cindex Defining modules (intro)
1782
1783 @c FIXME: this node should be reorganized into "general
1784 @c information about admin files" and put the "editing
1785 @c admin files" stuff up front rather than jumping into
1786 @c the details of modules right away.  Then the
1787 @c Administrative files node can go away, the information
1788 @c on each admin file distributed to a place appropriate
1789 @c to its function, and this node can contain a table
1790 @c listing each file and a @ref to its detailed description.
1791
1792 The directory @file{$CVSROOT/CVSROOT} contains some @dfn{administrative
1793 files}.  @xref{Administrative files}, for a complete description.
1794 You can use @sc{cvs} without any of these files, but
1795 some commands work better when at least the
1796 @file{modules} file is properly set up.
1797
1798 The most important of these files is the @file{modules}
1799 file.  It defines all modules in the repository.  This
1800 is a sample @file{modules} file.
1801
1802 @c FIXME: The CVSROOT line is a goofy example now that
1803 @c mkmodules doesn't exist.
1804 @example
1805 CVSROOT         CVSROOT
1806 modules         CVSROOT modules
1807 cvs             gnu/cvs
1808 rcs             gnu/rcs
1809 diff            gnu/diff
1810 tc              yoyodyne/tc
1811 @end example
1812
1813 The @file{modules} file is line oriented.  In its
1814 simplest form each line contains the name of the
1815 module, whitespace, and the directory where the module
1816 resides.  The directory is a path relative to
1817 @code{$CVSROOT}.  The last four lines in the example
1818 above are examples of such lines.
1819
1820 @c FIXME: might want to introduce the concept of options in modules file
1821 @c (the old example which was here, -i mkmodules, is obsolete).
1822
1823 The line that defines the module called @samp{modules}
1824 uses features that are not explained here.
1825 @xref{modules}, for a full explanation of all the
1826 available features.
1827
1828 @c FIXME: subsection without node is bogus
1829 @subsection Editing administrative files
1830 @cindex Editing administrative files
1831 @cindex Administrative files, editing them
1832
1833 You edit the administrative files in the same way that you would edit
1834 any other module.  Use @samp{cvs checkout CVSROOT} to get a working
1835 copy, edit it, and commit your changes in the normal way.
1836
1837 It is possible to commit an erroneous administrative
1838 file.  You can often fix the error and check in a new
1839 revision, but sometimes a particularly bad error in the
1840 administrative file makes it impossible to commit new
1841 revisions.
1842 @c @xref{Bad administrative files} for a hint
1843 @c about how to solve such situations.
1844 @c -- administrative file checking--
1845
1846 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1847 @node Multiple repositories
1848 @section Multiple repositories
1849 @cindex Multiple repositories
1850 @cindex Repositories, multiple
1851 @cindex Many repositories
1852 @cindex Parallel repositories
1853 @cindex Disjoint repositories
1854 @cindex CVSROOT, multiple repositories
1855
1856 In some situations it is a good idea to have more than
1857 one repository, for instance if you have two
1858 development groups that work on separate projects
1859 without sharing any code.  All you have to do to have
1860 several repositories is to specify the appropriate
1861 repository, using the @code{CVSROOT} environment
1862 variable, the @samp{-d} option to @sc{cvs}, or (once
1863 you have checked out a working directory) by simply
1864 allowing @sc{cvs} to use the repository that was used
1865 to check out the working directory
1866 (@pxref{Specifying a repository}).
1867
1868 The big advantage of having multiple repositories is
1869 that they can reside on different servers.  With @sc{cvs}
1870 version 1.10, a single command cannot recurse into
1871 directories from different repositories.  With development
1872 versions of @sc{cvs}, you can check out code from multiple
1873 servers into your working directory.  @sc{cvs} will
1874 recurse and handle all the details of making
1875 connections to as many server machines as necessary to
1876 perform the requested command.  Here is an example of
1877 how to set up a working directory:
1878
1879 @example
1880 cvs -d server1:/cvs co dir1
1881 cd dir1
1882 cvs -d server2:/root co sdir
1883 cvs update
1884 @end example
1885
1886 The @code{cvs co} commands set up the working
1887 directory, and then the @code{cvs update} command will
1888 contact server2, to update the dir1/sdir subdirectory,
1889 and server1, to update everything else.
1890
1891 @c FIXME: Does the FAQ have more about this?  I have a
1892 @c dim recollection, but I'm too lazy to check right now.
1893
1894 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1895 @node Creating a repository
1896 @section Creating a repository
1897
1898 @cindex Repository, setting up
1899 @cindex Creating a repository
1900 @cindex Setting up a repository
1901
1902 This section describes how to set up a @sc{cvs} repository for any
1903 sort of access method.  After completing the setup described in this
1904 section, you should be able to access your @sc{cvs} repository immediately
1905 via the local access method and several remote access methods.  For
1906 more information on setting up remote access to the repository you create
1907 in this section, please read the section on @xref{Remote repositories}.
1908
1909 To set up a @sc{cvs} repository, first choose the
1910 machine and disk on which you want to store the
1911 revision history of the source files.  CPU and memory
1912 requirements are modest, so most machines should be
1913 adequate.  For details see @ref{Server requirements}.
1914 @c Possible that we should be providing a quick rule of
1915 @c thumb, like the 32M memory for the server.  That
1916 @c might increase the number of people who are happy
1917 @c with the answer, without following the xref.
1918
1919 To estimate disk space
1920 requirements, if you are importing RCS files from
1921 another system, the size of those files is the
1922 approximate initial size of your repository, or if you
1923 are starting without any version history, a rule of
1924 thumb is to allow for the server approximately three
1925 times the size of the code to be under @sc{cvs} for the
1926 repository (you will eventually outgrow this, but not
1927 for a while).  On the machines on which the developers
1928 will be working, you'll want disk space for
1929 approximately one working directory for each developer
1930 (either the entire tree or a portion of it, depending
1931 on what each developer uses).
1932
1933 The repository should be accessible
1934 (directly or via a networked file system) from all
1935 machines which want to use @sc{cvs} in server or local
1936 mode; the client machines need not have any access to
1937 it other than via the @sc{cvs} protocol.  It is not
1938 possible to use @sc{cvs} to read from a repository
1939 which one only has read access to; @sc{cvs} needs to be
1940 able to create lock files (@pxref{Concurrency}).
1941
1942 @cindex init (subcommand)
1943 To create a repository, run the @code{cvs init}
1944 command.  It will set up an empty repository in the
1945 @sc{cvs} root specified in the usual way
1946 (@pxref{Repository}).  For example,
1947
1948 @example
1949 cvs -d /usr/local/cvsroot init
1950 @end example
1951
1952 @code{cvs init} is careful to never overwrite any
1953 existing files in the repository, so no harm is done if
1954 you run @code{cvs init} on an already set-up
1955 repository.
1956
1957 @code{cvs init} will enable history logging; if you
1958 don't want that, remove the history file after running
1959 @code{cvs init}.  @xref{history file}.
1960
1961 @node Backing up
1962 @section Backing up a repository
1963 @cindex Repository, backing up
1964 @cindex Backing up, repository
1965
1966 There is nothing particularly magical about the files
1967 in the repository; for the most part it is possible to
1968 back them up just like any other files.  However, there
1969 are a few issues to consider.
1970
1971 @cindex Locks, cvs, and backups
1972 @cindex #cvs.rfl, and backups
1973 The first is that to be paranoid, one should either not
1974 use @sc{cvs} during the backup, or have the backup
1975 program lock @sc{cvs} while doing the backup.  To not
1976 use @sc{cvs}, you might forbid logins to machines which
1977 can access the repository, turn off your @sc{cvs}
1978 server, or similar mechanisms.  The details would
1979 depend on your operating system and how you have
1980 @sc{cvs} set up.  To lock @sc{cvs}, you would create
1981 @file{#cvs.rfl} locks in each repository directory.
1982 See @ref{Concurrency}, for more on @sc{cvs} locks.
1983 Having said all this, if you just back up without any
1984 of these precautions, the results are unlikely to be
1985 particularly dire.  Restoring from backup, the
1986 repository might be in an inconsistent state, but this
1987 would not be particularly hard to fix manually.
1988
1989 When you restore a repository from backup, assuming
1990 that changes in the repository were made after the time
1991 of the backup, working directories which were not
1992 affected by the failure may refer to revisions which no
1993 longer exist in the repository.  Trying to run @sc{cvs}
1994 in such directories will typically produce an error
1995 message.  One way to get those changes back into the
1996 repository is as follows:
1997
1998 @itemize @bullet
1999 @item
2000 Get a new working directory.
2001
2002 @item
2003 Copy the files from the working directory from before
2004 the failure over to the new working directory (do not
2005 copy the contents of the @file{CVS} directories, of
2006 course).
2007
2008 @item
2009 Working in the new working directory, use commands such
2010 as @code{cvs update} and @code{cvs diff} to figure out
2011 what has changed, and then when you are ready, commit
2012 the changes into the repository.
2013 @end itemize
2014
2015 @node Moving a repository
2016 @section Moving a repository
2017 @cindex Repository, moving
2018 @cindex Moving a repository
2019 @cindex Copying a repository
2020
2021 Just as backing up the files in the repository is
2022 pretty much like backing up any other files, if you
2023 need to move a repository from one place to another it
2024 is also pretty much like just moving any other
2025 collection of files.
2026
2027 The main thing to consider is that working directories
2028 point to the repository.  The simplest way to deal with
2029 a moved repository is to just get a fresh working
2030 directory after the move.  Of course, you'll want to
2031 make sure that the old working directory had been
2032 checked in before the move, or you figured out some
2033 other way to make sure that you don't lose any
2034 changes.  If you really do want to reuse the existing
2035 working directory, it should be possible with manual
2036 surgery on the @file{CVS/Repository} files.  You can
2037 see @ref{Working directory storage}, for information on
2038 the @file{CVS/Repository} and @file{CVS/Root} files, but
2039 unless you are sure you want to bother, it probably
2040 isn't worth it.
2041 @c FIXME: Surgery on CVS/Repository should be avoided
2042 @c by making RELATIVE_REPOS the default.
2043 @c FIXME-maybe: might want some documented way to
2044 @c change the CVS/Root files in some particular tree.
2045 @c But then again, I don't know, maybe just having
2046 @c people do this in perl/shell/&c isn't so bad...
2047
2048 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
2049 @node Remote repositories
2050 @section Remote repositories
2051 @cindex Repositories, remote
2052 @cindex Remote repositories
2053 @cindex Client/Server Operation
2054 @cindex Server, CVS
2055 @cindex Remote repositories, port specification
2056 @cindex Repositories, remote, port specification
2057 @cindex Client/Server Operation, port specification
2058 @cindex pserver (client/server connection method), port specification
2059 @cindex kserver (client/server connection method), port specification
2060 @cindex gserver (client/server connection method), port specification
2061 @cindex port, specifying for remote repositories
2062
2063         Your working copy of the sources can be on a
2064 different machine than the repository.  Using @sc{cvs}
2065 in this manner is known as @dfn{client/server}
2066 operation.  You run @sc{cvs} on a machine which can
2067 mount your working directory, known as the
2068 @dfn{client}, and tell it to communicate to a machine
2069 which can mount the repository, known as the
2070 @dfn{server}.  Generally, using a remote
2071 repository is just like using a local one, except that
2072 the format of the repository name is:
2073
2074 @example
2075 [:@var{method}:][[@var{user}][:@var{password}]@@]@var{hostname}[:[@var{port}]]/path/to/repository
2076 @end example
2077
2078 Specifying a password in the repository name is not recommended during
2079 checkout, since this will cause @sc{cvs} to store a cleartext copy of the
2080 password in each created directory.  @code{cvs login} first instead
2081 (@pxref{Password authentication client}).
2082
2083 The details of exactly what needs to be set up depend
2084 on how you are connecting to the server.
2085
2086 @c Should we try to explain which platforms are which?
2087 @c Platforms like unix and VMS, which only allow
2088 @c privileged programs to bind to sockets <1024 lose on
2089 @c :server:
2090 @c Platforms like Mac and VMS, whose rsh program is
2091 @c unusable or nonexistent, lose on :ext:
2092 @c Platforms like OS/2 and NT probably could plausibly
2093 @c default either way (modulo -b troubles).
2094
2095 @menu
2096 * Server requirements::         Memory and other resources for servers
2097 * The connection method::       Connection methods and method options
2098 * Connecting via rsh::          Using the @code{rsh} program to connect
2099 * Password authenticated::      Direct connections using passwords
2100 * GSSAPI authenticated::        Direct connections using GSSAPI
2101 * Kerberos authenticated::      Direct connections with Kerberos
2102 * Connecting via fork::         Using a forked @code{cvs server} to connect
2103 * Write proxies::               Distributing load across several CVS servers
2104 @end menu
2105
2106 @node Server requirements
2107 @subsection Server requirements
2108
2109 The quick answer to what sort of machine is suitable as
2110 a server is that requirements are modest---a server
2111 with 32M of memory or even less can handle a fairly
2112 large source tree with a fair amount of activity.
2113 @c Say something about CPU speed too?  I'm even less sure
2114 @c what to say on that subject...
2115
2116 The real answer, of course, is more complicated.
2117 Estimating the known areas of large memory consumption
2118 should be sufficient to estimate memory requirements.
2119 There are two such areas documented here; other memory
2120 consumption should be small by comparison (if you find
2121 that is not the case, let us know, as described in
2122 @ref{BUGS}, so we can update this documentation).
2123
2124 The first area of big memory consumption is large
2125 checkouts, when using the @sc{cvs} server.  The server
2126 consists of two processes for each client that it is
2127 serving.  Memory consumption on the child process
2128 should remain fairly small.  Memory consumption on the
2129 parent process, particularly if the network connection
2130 to the client is slow, can be expected to grow to
2131 slightly more than the size of the sources in a single
2132 directory, or two megabytes, whichever is larger.
2133 @c "two megabytes" of course is SERVER_HI_WATER.  But
2134 @c we don't mention that here because we are
2135 @c documenting the default configuration of CVS.  If it
2136 @c is a "standard" thing to change that value, it
2137 @c should be some kind of run-time configuration.
2138 @c
2139 @c See cvsclient.texi for more on the design decision
2140 @c to not have locks in place while waiting for the
2141 @c client, which is what results in memory consumption
2142 @c as high as this.
2143
2144 Multiplying the size of each @sc{cvs} server by the
2145 number of servers which you expect to have active at
2146 one time should give an idea of memory requirements for
2147 the server.  For the most part, the memory consumed by
2148 the parent process probably can be swap space rather
2149 than physical memory.
2150 @c Has anyone verified that notion about swap space?
2151 @c I say it based pretty much on guessing that the
2152 @c ->text of the struct buffer_data only gets accessed
2153 @c in a first in, first out fashion, but I haven't
2154 @c looked very closely.
2155
2156 @c What about disk usage in /tmp on the server?  I think that
2157 @c it can be substantial, but I haven't looked at this
2158 @c again and tried to figure it out ("cvs import" is
2159 @c probably the worst case...).
2160
2161 The second area of large memory consumption is
2162 @code{diff}, when checking in large files.  This is
2163 required even for binary files.  The rule of thumb is
2164 to allow about ten times the size of the largest file
2165 you will want to check in, although five times may be
2166 adequate.  For example, if you want to check in a file
2167 which is 10 megabytes, you should have 100 megabytes of
2168 memory on the machine doing the checkin (the server
2169 machine for client/server, or the machine running
2170 @sc{cvs} for non-client/server).  This can be swap
2171 space rather than physical memory.  Because the memory
2172 is only required briefly, there is no particular need
2173 to allow memory for more than one such checkin at a
2174 time.
2175 @c The 5-10 times rule of thumb is from Paul Eggert for
2176 @c GNU diff.  I don't think it is in the GNU diff
2177 @c manual or anyplace like that.
2178 @c
2179 @c Probably we could be saying more about
2180 @c non-client/server CVS.
2181 @c I would guess for non-client/server CVS in an NFS
2182 @c environment the biggest issues are the network and
2183 @c the NFS server.
2184
2185 Resource consumption for the client is even more
2186 modest---any machine with enough capacity to run the
2187 operating system in question should have little
2188 trouble.
2189 @c Is that true?  I think the client still wants to
2190 @c (bogusly) store entire files in memory at times.
2191
2192 For information on disk space requirements, see
2193 @ref{Creating a repository}.
2194
2195 @node The connection method
2196 @subsection The connection method
2197
2198 In its simplest form, the @var{method} portion of the repository string
2199 (@pxref{Remote repositories}) may be one of @samp{ext}, @samp{fork},
2200 @samp{gserver}, @samp{kserver}, @samp{local}, @samp{pserver}, and, on some
2201 platforms, @samp{server}.
2202
2203 If @var{method} is not specified, and the repository
2204 name starts with a @samp{/}, then the default is @code{local}.
2205 If @var{method} is not specified, and the repository
2206 name does not start with a @samp{/}, then the default is @code{ext}
2207 or @code{server}, depending on your platform; both the @samp{ext}
2208 and @samp{server} methods are described in @ref{Connecting via rsh}.
2209
2210 @cindex connection method options
2211 @cindex options, connection method
2212 The @code{ext}, @code{fork}, @code{gserver}, and @code{pserver} connection
2213 methods all accept optional method options, specified as part of the
2214 @var{method} string, like so:
2215
2216 @example
2217 :@var{method}[;@var{option}=@var{arg}...]:@var{other_connection_data}
2218 @end example
2219
2220 @sc{cvs} is not sensitive to the case of @var{method} or @var{option}, though
2221 it may sometimes be sensitive to the case of @var{arg}.  The possible method
2222 options are as follows:
2223
2224 @table @code
2225 @cindex CVS_PROXY_PORT
2226 @cindex proxy, method option
2227 @cindex proxyport, method option
2228 @cindex proxies, web, connecting via
2229 @cindex web proxies, connecting via
2230 @cindex proxies, HTTP, connecting via
2231 @cindex HTTP proxies, connecting via
2232 @item proxy=@var{hostname}
2233 @itemx proxyport=@var{port}
2234 These two method options can be used to connect via an HTTP tunnel style web
2235 proxy.  @var{hostname} should be the name of the HTTP proxy server to connect
2236 through and @var{port} is the port number on the HTTP proxy server to connect
2237 via.  @var{port} defaults to 8080.
2238
2239 @strong{NOTE: An HTTP proxy server is not the same as a @sc{cvs} write proxy
2240 server - please see @ref{Write proxies} for more on @sc{cvs} write proxies.}
2241
2242 For example, to connect pserver via a web proxy listening on port 8000 of
2243 www.myproxy.net, you would use a method of:
2244
2245 @example
2246 :pserver;proxy=www.myproxy.net;proxyport=8000:@var{pserver_connection_string}
2247 @end example
2248
2249 @strong{NOTE: In the above example, @var{pserver_connection_string} is still
2250 required to connect and authenticate to the CVS server, as noted in the
2251 upcoming sections on password authentication, @code{gserver}, and
2252 @code{kserver}.  The example above only demonstrates a modification to the
2253 @var{method} portion of the repository name.}
2254
2255 These options first appeared in @sc{cvs} version 1.12.7 and are valid as
2256 modifcations to the @code{gserver} and @code{pserver} connection methods.
2257
2258 @cindex CVS_RSH method option
2259 @item CVS_RSH=@var{path}
2260 This method option can be used with the @code{ext} method to specify the path
2261 the @sc{cvs} client will use to find the remote shell used to contact the
2262 @sc{cvs} server and takes precedence over any path specified in the
2263 @code{$CVS_RSH} environment variable (@pxref{Connecting via rsh}).  For
2264 example, to connect to a @sc{cvs} server via the local
2265 @file{/path/to/ssh/command} command, you could choose to specify the following
2266 @var{path} via the @code{CVS_RSH} method option:
2267
2268 @example
2269 :ext;CVS_RSH=/path/to/ssh/command:@var{ext_connection_string}
2270 @end example
2271
2272 This method option first appeared in @sc{cvs} version 1.12.11 and is valid only
2273 as a modifcation to the @code{ext} connection method.
2274
2275 @cindex CVS_SERVER method option
2276 @item CVS_SERVER=@var{path}
2277 This method option can be used with the @code{ext} and @code{fork} methods to
2278 specify the path @sc{cvs} will use to find the @sc{cvs} executable on the
2279 @sc{cvs} server and takes precedence over any path specified in the
2280 @code{$CVS_SERVER} environment variable (@pxref{Connecting via rsh}).  For
2281 example, to select the remote @file{/path/to/cvs/command} executable as your
2282 @sc{cvs} server application on the @sc{cvs} server machine, you could choose to
2283 specify the following @var{path} via the @code{CVS_SERVER} method option:
2284
2285 @example
2286 :ext;CVS_SERVER=/path/to/cvs/command:@var{ext_connection_string}
2287 @end example
2288
2289 @noindent
2290 or, to select an executable named @samp{cvs-1.12.11}, assuming it is in your
2291 @code{$PATH} on the @sc{cvs} server:
2292
2293 @example
2294 :ext;CVS_SERVER=cvs-1.12.11:@var{ext_connection_string}
2295 @end example
2296
2297 This method option first appeared in @sc{cvs} version 1.12.11 and is valid
2298 as a modifcation to both the @code{ext} and @code{fork} connection methods.
2299
2300 @cindex Redirect, method option
2301 @item Redirect=@var{boolean-state}
2302 The @code{Redirect} method option determines whether the @sc{cvs} client will
2303 allow a @sc{cvs} server to redirect it to a different @sc{cvs} server, usually
2304 for write requests, as in a write proxy setup.
2305
2306 A @var{boolean-state} of any value acceptable for boolean @file{CVSROOT/config}
2307 file options is acceptable here (@pxref{config}).  For example, @samp{on},
2308 @samp{off}, @samp{true}, and @samp{false} are all valid values for
2309 @var{boolean-state}.  @var{boolean-state} for the @code{Redirect} method option
2310 defaults to @samp{on}.
2311
2312 This option will have no effect when talking to any non-secondary @sc{cvs}
2313 server.  For more on write proxies and secondary servers, please see
2314 @ref{Write proxies}.
2315
2316 This method option first appeared in @sc{cvs} version 1.12.11 and is valid only
2317 as a modifcation to the @code{ext} connection method.
2318 @end table
2319
2320 As a further example, to combine both the @code{CVS_RSH} and @code{CVS_SERVER}
2321 options, a method specification like the following would work:
2322
2323 @example
2324 :ext;CVS_RSH=/path/to/ssh/command;CVS_SERVER=/path/to/cvs/command:
2325 @end example
2326
2327 This means that you would not need to have
2328 the @code{CVS_SERVER} or @code{CVS_RSH} environment
2329 variables set correctly.  See @ref{Connecting via rsh}, for more details on
2330 these environment variables.
2331
2332 @node Connecting via rsh
2333 @subsection Connecting with rsh
2334
2335 @cindex rsh
2336 @sc{cvs} uses the @samp{rsh} protocol to perform these
2337 operations, so the remote user host needs to have a
2338 @file{.rhosts} file which grants access to the local
2339 user. Note that the program that @sc{cvs} uses for this
2340 purpose may be specified using the @file{--with-rsh}
2341 flag to configure.
2342
2343 For example, suppose you are the user @samp{mozart} on
2344 the local machine @samp{toe.example.com}, and the
2345 server machine is @samp{faun.example.org}.  On
2346 faun, put the following line into the file
2347 @file{.rhosts} in @samp{bach}'s home directory:
2348
2349 @example
2350 toe.example.com  mozart
2351 @end example
2352
2353 @noindent
2354 Then test that @samp{rsh} is working with
2355
2356 @example
2357 rsh -l bach faun.example.org 'echo $PATH'
2358 @end example
2359
2360 @cindex CVS_SERVER, environment variable
2361 Next you have to make sure that @code{rsh} will be able
2362 to find the server.  Make sure that the path which
2363 @code{rsh} printed in the above example includes the
2364 directory containing a program named @code{cvs} which
2365 is the server.  You need to set the path in
2366 @file{.bashrc}, @file{.cshrc}, etc., not @file{.login}
2367 or @file{.profile}.  Alternately, you can set the
2368 environment variable @code{CVS_SERVER} on the client
2369 machine to the filename of the server you want to use,
2370 for example @file{/usr/local/bin/cvs-1.6}.
2371 For the @code{ext} and @code{fork} methods, you may
2372 also specify @var{CVS_SERVER} as an otpion in the
2373 @var{CVSROOT} so that you may use different servers for
2374 differnt roots. See @ref{Remote repositories} for more
2375 details.
2376
2377 There is no need to edit @file{inetd.conf} or start a
2378 @sc{cvs} server daemon.
2379
2380 @cindex :server:, setting up
2381 @cindex :ext:, setting up
2382 @cindex Kerberos, using kerberized rsh
2383 @cindex SSH (rsh replacement)
2384 @cindex rsh replacements (Kerberized, SSH, &c)
2385 There are two access methods that you use in @code{CVSROOT}
2386 for rsh.  @code{:server:} specifies an internal rsh
2387 client, which is supported only by some @sc{cvs} ports.
2388 @code{:ext:} specifies an external rsh program.  By
2389 default this is @code{rsh} (unless otherwise specified
2390 by the @file{--with-rsh} flag to configure) but you may set the
2391 @code{CVS_RSH} environment variable to invoke another
2392 program which can access the remote server (for
2393 example, @code{remsh} on HP-UX 9 because @code{rsh} is
2394 something different).  It must be a program which can
2395 transmit data to and from the server without modifying
2396 it; for example the Windows NT @code{rsh} is not
2397 suitable since it by default translates between CRLF
2398 and LF.  The OS/2 @sc{cvs} port has a hack to pass @samp{-b}
2399 to @code{rsh} to get around this, but since this could
2400 potentially cause problems for programs other than the
2401 standard @code{rsh}, it may change in the future.  If
2402 you set @code{CVS_RSH} to @code{SSH} or some other rsh
2403 replacement, the instructions in the rest of this
2404 section concerning @file{.rhosts} and so on are likely
2405 to be inapplicable; consult the documentation for your rsh
2406 replacement.
2407
2408 You may choose to specify the @var{CVS_RSH} option as a method option
2409 in the @var{CVSROOT} string to allow you to use different connection tools
2410 for different roots (@pxref{The connection method}).  For example, allowing
2411 some roots to use @code{CVS_RSH=remsh} and some to use
2412 @code{CVS_RSH=ssh} for the @code{ext} method.  See also
2413 the @ref{Remote repositories} for more details.
2414 @c See also the comment in src/client.c for rationale
2415 @c concerning "rsh" being the default and never
2416 @c "remsh".
2417
2418 Continuing our example, supposing you want to access
2419 the module @file{foo} in the repository
2420 @file{/usr/local/cvsroot/}, on machine
2421 @file{faun.example.org}, you are ready to go:
2422
2423 @example
2424 cvs -d :ext:bach@@faun.example.org:/usr/local/cvsroot checkout foo
2425 @end example
2426
2427 @noindent
2428 (The @file{bach@@} can be omitted if the username is
2429 the same on both the local and remote hosts.)
2430
2431 @c Should we mention "rsh host echo hi" and "rsh host
2432 @c cat" (the latter followed by typing text and ^D)
2433 @c as troubleshooting techniques?  Probably yes
2434 @c (people tend to have trouble setting this up),
2435 @c but this kind of thing can be hard to spell out.
2436
2437 @node Password authenticated
2438 @subsection Direct connection with password authentication
2439
2440 The @sc{cvs} client can also connect to the server
2441 using a password protocol.  This is particularly useful
2442 if using @code{rsh} is not feasible (for example,
2443 the server is behind a firewall), and Kerberos also is
2444 not available.
2445
2446         To use this method, it is necessary to make
2447 some adjustments on both the server and client sides.
2448
2449 @menu
2450 * Password authentication server::     Setting up the server
2451 * Password authentication client::     Using the client
2452 * Password authentication security::   What this method does and does not do
2453 @end menu
2454
2455 @node Password authentication server
2456 @subsubsection Setting up the server for password authentication
2457
2458 First of all, you probably want to tighten the
2459 permissions on the @file{$CVSROOT} and
2460 @file{$CVSROOT/CVSROOT} directories.  See @ref{Password
2461 authentication security}, for more details.
2462
2463 @cindex pserver (subcommand)
2464 @cindex Remote repositories, port specification
2465 @cindex Repositories, remote, port specification
2466 @cindex Client/Server Operation, port specification
2467 @cindex pserver (client/server connection method), port specification
2468 @cindex kserver (client/server connection method), port specification
2469 @cindex gserver (client/server connection method), port specification
2470 @cindex port, specifying for remote repositories
2471 @cindex Password server, setting up
2472 @cindex Authenticating server, setting up
2473 @cindex inetd, configuring for pserver
2474 @cindex xinetd, configuring for pserver
2475 @c FIXME: this isn't quite right regarding port
2476 @c numbers; CVS looks up "cvspserver" in
2477 @c /etc/services (on unix, but what about non-unix?).
2478 On the server side, the file @file{/etc/inetd.conf}
2479 needs to be edited so @code{inetd} knows to run the
2480 command @code{cvs pserver} when it receives a
2481 connection on the right port.  By default, the port
2482 number is 2401; it would be different if your client
2483 were compiled with @code{CVS_AUTH_PORT} defined to
2484 something else, though.  This can also be specified in the CVSROOT variable
2485 (@pxref{Remote repositories}) or overridden with the CVS_CLIENT_PORT
2486 environment variable (@pxref{Environment variables}).
2487
2488         If your @code{inetd} allows raw port numbers in
2489 @file{/etc/inetd.conf}, then the following (all on a
2490 single line in @file{inetd.conf}) should be sufficient:
2491
2492 @example
2493 2401  stream  tcp  nowait  root  /usr/local/bin/cvs
2494 cvs -f --allow-root=/usr/cvsroot pserver
2495 @end example
2496
2497 @noindent
2498 (You could also use the
2499 @samp{-T} option to specify a temporary directory.)
2500
2501 The @samp{--allow-root} option specifies the allowable
2502 @sc{cvsroot} directory.  Clients which attempt to use a
2503 different @sc{cvsroot} directory will not be allowed to
2504 connect.  If there is more than one @sc{cvsroot}
2505 directory which you want to allow, repeat the option.
2506 (Unfortunately, many versions of @code{inetd} have very small
2507 limits on the number of arguments and/or the total length
2508 of the command.  The usual solution to this problem is
2509 to have @code{inetd} run a shell script which then invokes
2510 @sc{cvs} with the necessary arguments.)
2511
2512         If your @code{inetd} wants a symbolic service
2513 name instead of a raw port number, then put this in
2514 @file{/etc/services}:
2515
2516 @example
2517 cvspserver      2401/tcp
2518 @end example
2519
2520 @noindent
2521 and put @code{cvspserver} instead of @code{2401} in @file{inetd.conf}.
2522
2523 If your system uses @code{xinetd} instead of @code{inetd},
2524 the procedure is slightly different.
2525 Create a file called @file{/etc/xinetd.d/cvspserver} containing the following:
2526
2527 @example
2528 service cvspserver
2529 @{
2530    port        = 2401
2531    socket_type = stream
2532    protocol    = tcp
2533    wait        = no
2534    user        = root
2535    passenv     = PATH
2536    server      = /usr/local/bin/cvs
2537    server_args = -f --allow-root=/usr/cvsroot pserver
2538 @}
2539 @end example
2540
2541 @noindent
2542 (If @code{cvspserver} is defined in @file{/etc/services}, you can omit
2543 the @code{port} line.)
2544
2545         Once the above is taken care of, restart your
2546 @code{inetd}, or do whatever is necessary to force it
2547 to reread its initialization files.
2548
2549 If you are having trouble setting this up, see
2550 @ref{Connection}.
2551
2552 @cindex CVS passwd file
2553 @cindex passwd (admin file)
2554 Because the client stores and transmits passwords in
2555 cleartext (almost---see @ref{Password authentication
2556 security}, for details), a separate @sc{cvs} password
2557 file is generally used, so people don't compromise
2558 their regular passwords when they access the
2559 repository.  This file is
2560 @file{$CVSROOT/CVSROOT/passwd} (@pxref{Intro
2561 administrative files}).  It uses a colon-separated
2562 format, similar to @file{/etc/passwd} on Unix systems,
2563 except that it has fewer fields: @sc{cvs} username,
2564 optional password, and an optional system username for
2565 @sc{cvs} to run as if authentication succeeds.  Here is
2566 an example @file{passwd} file with five entries:
2567
2568 @example
2569 anonymous:
2570 bach:ULtgRLXo7NRxs
2571 spwang:1sOp854gDF3DY
2572 melissa:tGX1fS8sun6rY:pubcvs
2573 qproj:XR4EZcEs0szik:pubcvs
2574 @end example
2575
2576 @noindent
2577 (The passwords are encrypted according to the standard
2578 Unix @code{crypt()} function, so it is possible to
2579 paste in passwords directly from regular Unix
2580 @file{/etc/passwd} files.)
2581
2582 The first line in the example will grant access to any
2583 @sc{cvs} client attempting to authenticate as user
2584 @code{anonymous}, no matter what password they use,
2585 including an empty password.  (This is typical for
2586 sites granting anonymous read-only access; for
2587 information on how to do the "read-only" part, see
2588 @ref{Read-only access}.)
2589
2590 The second and third lines will grant access to
2591 @code{bach} and @code{spwang} if they supply their
2592 respective plaintext passwords.
2593
2594 @cindex User aliases
2595 The fourth line will grant access to @code{melissa}, if
2596 she supplies the correct password, but her @sc{cvs}
2597 operations will actually run on the server side under
2598 the system user @code{pubcvs}.  Thus, there need not be
2599 any system user named @code{melissa}, but there
2600 @emph{must} be one named @code{pubcvs}.
2601
2602 The fifth line shows that system user identities can be
2603 shared: any client who successfully authenticates as
2604 @code{qproj} will actually run as @code{pubcvs}, just
2605 as @code{melissa} does.  That way you could create a
2606 single, shared system user for each project in your
2607 repository, and give each developer their own line in
2608 the @file{$CVSROOT/CVSROOT/passwd} file.  The @sc{cvs}
2609 username on each line would be different, but the
2610 system username would be the same.  The reason to have
2611 different @sc{cvs} usernames is that @sc{cvs} will log their
2612 actions under those names: when @code{melissa} commits
2613 a change to a project, the checkin is recorded in the
2614 project's history under the name @code{melissa}, not
2615 @code{pubcvs}.  And the reason to have them share a
2616 system username is so that you can arrange permissions
2617 in the relevant area of the repository such that only
2618 that account has write-permission there.
2619
2620 If the system-user field is present, all
2621 password-authenticated @sc{cvs} commands run as that
2622 user; if no system user is specified, @sc{cvs} simply
2623 takes the @sc{cvs} username as the system username and
2624 runs commands as that user.  In either case, if there
2625 is no such user on the system, then the @sc{cvs}
2626 operation will fail (regardless of whether the client
2627 supplied a valid password).
2628
2629 The password and system-user fields can both be omitted
2630 (and if the system-user field is omitted, then also
2631 omit the colon that would have separated it from the
2632 encrypted password).  For example, this would be a
2633 valid @file{$CVSROOT/CVSROOT/passwd} file:
2634
2635 @example
2636 anonymous::pubcvs
2637 fish:rKa5jzULzmhOo:kfogel
2638 sussman:1sOp854gDF3DY
2639 @end example
2640
2641 @noindent
2642 When the password field is omitted or empty, then the
2643 client's authentication attempt will succeed with any
2644 password, including the empty string.  However, the
2645 colon after the @sc{cvs} username is always necessary,
2646 even if the password is empty.
2647
2648 @sc{cvs} can also fall back to use system authentication.
2649 When authenticating a password, the server first checks
2650 for the user in the @file{$CVSROOT/CVSROOT/passwd}
2651 file.  If it finds the user, it will use that entry for
2652 authentication as described above.  But if it does not
2653 find the user, or if the @sc{cvs} @file{passwd} file
2654 does not exist, then the server can try to authenticate
2655 the username and password using the operating system's
2656 user-lookup routines (this "fallback" behavior can be
2657 disabled by setting @code{SystemAuth=no} in the
2658 @sc{cvs} @file{config} file, @pxref{config}).
2659
2660 The default fallback behavior is to look in 
2661 @file{/etc/passwd} for this system user unless your
2662 system has PAM (Pluggable Authentication Modules)
2663 and your @sc{cvs} server executable was configured to
2664 use it at compile time (using @code{./configure --enable-pam} - see the
2665 INSTALL file for more).  In this case, PAM will be consulted instead.
2666 This means that @sc{cvs} can be configured to use any password
2667 authentication source PAM can be configured to use (possibilities
2668 include a simple UNIX password, NIS, LDAP, and others) in its
2669 global configuration file (usually @file{/etc/pam.conf}
2670 or possibly @file{/etc/pam.d/cvs}).  See your PAM documentation
2671 for more details on PAM configuration.
2672
2673 Note that PAM is an experimental feature in @sc{cvs} and feedback is
2674 encouraged.  Please send a mail to one of the @sc{cvs} mailing lists
2675 (@code{info-cvs@@nongnu.org} or @code{bug-cvs@@nongnu.org}) if you use the 
2676 @sc{cvs} PAM support.
2677
2678 @strong{WARNING: Using PAM gives the system administrator much more 
2679 flexibility about how @sc{cvs} users are authenticated but 
2680 no more security than other methods.  See below for more.} 
2681
2682 CVS needs an "auth", "account" and "session" module in the 
2683 PAM configuration file. A typical PAM configuration 
2684 would therefore have the following lines 
2685 in @file{/etc/pam.conf} to emulate the standard @sc{cvs} 
2686 system @file{/etc/passwd} authentication:
2687
2688 @example
2689 cvs     auth        required    pam_unix.so
2690 cvs     account     required    pam_unix.so
2691 cvs     session     required    pam_unix.so
2692 @end example
2693
2694 The the equivalent @file{/etc/pam.d/cvs} would contain
2695
2696 @example
2697 auth        required    pam_unix.so
2698 account     required    pam_unix.so
2699 session     required    pam_unix.so
2700 @end example
2701
2702 Some systems require a full path to the module so that
2703 @file{pam_unix.so} (Linux) would become something like 
2704 @file{/usr/lib/security/$ISA/pam_unix.so.1} (Sun Solaris).
2705 See the @file{contrib/pam} subdirectory of the @sc{cvs}
2706 source distribution for further example configurations.
2707
2708 The PAM service name given above as "cvs" is just
2709 the service name in the default configuration and can be
2710 set using
2711 @code{./configure --with-hardcoded-pam-service-name=<pam-service-name>}
2712 before compiling.  @sc{cvs} can also be configured to use whatever
2713 name it is invoked as as its PAM service name using
2714 @code{./configure --without-hardcoded-pam-service-name}, but this
2715 feature should not be used if you may not have control of the name
2716 @sc{cvs} will be invoked as.
2717
2718 Be aware, also, that falling back to system
2719 authentication might be a security risk: @sc{cvs}
2720 operations would then be authenticated with that user's
2721 regular login password, and the password flies across
2722 the network in plaintext.  See @ref{Password
2723 authentication security} for more on this.
2724 This may be more of a problem with PAM authentication
2725 because it is likely that the source of the system 
2726 password is some central authentication service like
2727 LDAP which is also used to authenticate other services.
2728
2729 On the other hand, PAM makes it very easy to change your password
2730 regularly.  If they are given the option of a one-password system for
2731 all of their activities, users are often more willing to change their
2732 password on a regular basis.
2733
2734 In the non-PAM configuration where the password is stored in the
2735 @file{CVSROOT/passwd} file, it is difficult to change passwords on a
2736 regular basis since only administrative users (or in some cases
2737 processes that act as an administrative user) are typically given
2738 access to modify this file.  Either there needs to be some
2739 hand-crafted web page or set-uid program to update the file, or the
2740 update needs to be done by submitting a request to an administrator to
2741 perform the duty by hand.  In the first case, having to remember to
2742 update a separate password on a periodic basis can be difficult.  In
2743 the second case, the manual nature of the change will typically mean
2744 that the password will not be changed unless it is absolutely
2745 necessary.
2746
2747 Note that PAM administrators should probably avoid configuring
2748 one-time-passwords (OTP) for @sc{cvs} authentication/authorization.  If
2749 OTPs are desired, the administrator may wish to encourage the use of
2750 one of the other Client/Server access methods.  See the section on
2751 @pxref{Remote repositories} for a list of other methods.
2752
2753 Right now, the only way to put a password in the
2754 @sc{cvs} @file{passwd} file is to paste it there from
2755 somewhere else.  Someday, there may be a @code{cvs
2756 passwd} command.
2757
2758 Unlike many of the files in @file{$CVSROOT/CVSROOT}, it
2759 is normal to edit the @file{passwd} file in-place,
2760 rather than via @sc{cvs}.  This is because of the
2761 possible security risks of having the @file{passwd}
2762 file checked out to people's working copies.  If you do
2763 want to include the @file{passwd} file in checkouts of
2764 @file{$CVSROOT/CVSROOT}, see @ref{checkoutlist}.
2765
2766 @c We might also suggest using the @code{htpasswd} command
2767 @c from freely available web servers as well, but that
2768 @c would open up a can of worms in that the users next
2769 @c questions are likely to be "where do I get it?" and
2770 @c "how do I use it?"
2771 @c Also note that htpasswd, at least the version I had,
2772 @c likes to clobber the third field.
2773
2774 @node Password authentication client
2775 @subsubsection Using the client with password authentication
2776 @cindex Login (subcommand)
2777 @cindex Password client, using
2778 @cindex Authenticated client, using
2779 @cindex :pserver:, setting up
2780 To run a @sc{cvs} command on a remote repository via
2781 the password-authenticating server, one specifies the
2782 @code{pserver} protocol, optional username, repository host, an
2783 optional port number, and path to the repository.  For example:
2784
2785 @example
2786 cvs -d :pserver:faun.example.org:/usr/local/cvsroot checkout someproj
2787 @end example
2788
2789 @noindent
2790 or
2791
2792 @example
2793 CVSROOT=:pserver:bach@@faun.example.org:2401/usr/local/cvsroot
2794 cvs checkout someproj
2795 @end example
2796
2797 However, unless you're connecting to a public-access
2798 repository (i.e., one where that username doesn't
2799 require a password), you'll need to supply a password or @dfn{log in} first.
2800 Logging in verifies your password with the repository and stores it in a file.
2801 It's done with the @code{login} command, which will
2802 prompt you interactively for the password if you didn't supply one as part of
2803 @var{$CVSROOT}:
2804
2805 @example
2806 cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot login
2807 CVS password:
2808 @end example
2809
2810 @noindent
2811 or
2812
2813 @example
2814 cvs -d :pserver:bach:p4ss30rd@@faun.example.org:/usr/local/cvsroot login
2815 @end example
2816
2817 After you enter the password, @sc{cvs} verifies it with
2818 the server.  If the verification succeeds, then that
2819 combination of username, host, repository, and password
2820 is permanently recorded, so future transactions with
2821 that repository won't require you to run @code{cvs
2822 login}.  (If verification fails, @sc{cvs} will exit
2823 complaining that the password was incorrect, and
2824 nothing will be recorded.)
2825
2826 The records are stored, by default, in the file
2827 @file{$HOME/.cvspass}.  That file's format is
2828 human-readable, and to a degree human-editable, but
2829 note that the passwords are not stored in
2830 cleartext---they are trivially encoded to protect them
2831 from "innocent" compromise (i.e., inadvertent viewing
2832 by a system administrator or other non-malicious
2833 person).
2834
2835 @cindex CVS_PASSFILE, environment variable
2836 You can change the default location of this file by
2837 setting the @code{CVS_PASSFILE} environment variable.
2838 If you use this variable, make sure you set it
2839 @emph{before} @code{cvs login} is run.  If you were to
2840 set it after running @code{cvs login}, then later
2841 @sc{cvs} commands would be unable to look up the
2842 password for transmission to the server.
2843   
2844 Once you have logged in, all @sc{cvs} commands using
2845 that remote repository and username will authenticate
2846 with the stored password.  So, for example
2847   
2848 @example
2849 cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot checkout foo
2850 @end example
2851
2852 @noindent
2853 should just work (unless the password changes on the
2854 server side, in which case you'll have to re-run
2855 @code{cvs login}).
2856
2857 Note that if the @samp{:pserver:} were not present in
2858 the repository specification, @sc{cvs} would assume it
2859 should use @code{rsh} to connect with the server
2860 instead (@pxref{Connecting via rsh}).
2861
2862 Of course, once you have a working copy checked out and
2863 are running @sc{cvs} commands from within it, there is
2864 no longer any need to specify the repository
2865 explicitly, because @sc{cvs} can deduce the repository
2866 from the working copy's @file{CVS} subdirectory.
2867
2868 @c FIXME: seems to me this needs somewhat more
2869 @c explanation.
2870 @cindex Logout (subcommand)
2871 The password for a given remote repository can be
2872 removed from the @code{CVS_PASSFILE} by using the
2873 @code{cvs logout} command.
2874
2875 @node Password authentication security
2876 @subsubsection Security considerations with password authentication
2877
2878 @cindex Security, of pserver
2879 The passwords are stored on the client side in a
2880 trivial encoding of the cleartext, and transmitted in
2881 the same encoding.  The encoding is done only to
2882 prevent inadvertent password compromises (i.e., a
2883 system administrator accidentally looking at the file),
2884 and will not prevent even a naive attacker from gaining
2885 the password.
2886
2887 @c FIXME: The bit about "access to the repository
2888 @c implies general access to the system is *not* specific
2889 @c to pserver; it applies to kerberos and SSH and
2890 @c everything else too.  Should reorganize the
2891 @c documentation to make this clear.
2892 The separate @sc{cvs} password file (@pxref{Password
2893 authentication server}) allows people
2894 to use a different password for repository access than
2895 for login access.  On the other hand, once a user has
2896 non-read-only
2897 access to the repository, she can execute programs on
2898 the server system through a variety of means.  Thus, repository
2899 access implies fairly broad system access as well.  It
2900 might be possible to modify @sc{cvs} to prevent that,
2901 but no one has done so as of this writing.
2902 @c OpenBSD uses chroot() and copies the repository to
2903 @c provide anonymous read-only access (for details see
2904 @c http://www.openbsd.org/anoncvs.shar).  While this
2905 @c closes the most obvious holes, I'm not sure it
2906 @c closes enough holes to recommend it (plus it is
2907 @c *very* easy to accidentally screw up a setup of this
2908 @c type).
2909
2910 Note that because the @file{$CVSROOT/CVSROOT} directory
2911 contains @file{passwd} and other files which are used
2912 to check security, you must control the permissions on
2913 this directory as tightly as the permissions on
2914 @file{/etc}.  The same applies to the @file{$CVSROOT}
2915 directory itself and any directory
2916 above it in the tree.  Anyone who has write access to
2917 such a directory will have the ability to become any
2918 user on the system.  Note that these permissions are
2919 typically tighter than you would use if you are not
2920 using pserver.
2921 @c TODO: Would be really nice to document/implement a
2922 @c scheme where the CVS server can run as some non-root
2923 @c user, e.g. "cvs".  CVSROOT/passwd would contain a
2924 @c bunch of entries of the form foo:xxx:cvs (or the "cvs"
2925 @c would be implicit).  This would greatly reduce
2926 @c security risks such as those hinted at in the
2927 @c previous paragraph.  I think minor changes to CVS
2928 @c might be required but mostly this would just need
2929 @c someone who wants to play with it, document it, &c.
2930
2931 In summary, anyone who gets the password gets
2932 repository access (which may imply some measure of general system
2933 access as well).  The password is available to anyone
2934 who can sniff network packets or read a protected
2935 (i.e., user read-only) file.  If you want real
2936 security, get Kerberos.
2937
2938 @node GSSAPI authenticated
2939 @subsection Direct connection with GSSAPI
2940
2941 @cindex GSSAPI
2942 @cindex Security, GSSAPI
2943 @cindex :gserver:, setting up
2944 @cindex Kerberos, using :gserver:
2945 GSSAPI is a generic interface to network security
2946 systems such as Kerberos 5.
2947 If you have a working GSSAPI library, you can have
2948 @sc{cvs} connect via a direct @sc{tcp} connection,
2949 authenticating with GSSAPI.
2950
2951 To do this, @sc{cvs} needs to be compiled with GSSAPI
2952 support; when configuring @sc{cvs} it tries to detect
2953 whether GSSAPI libraries using Kerberos version 5 are
2954 present.  You can also use the @file{--with-gssapi}
2955 flag to configure.
2956
2957 The connection is authenticated using GSSAPI, but the
2958 message stream is @emph{not} authenticated by default.
2959 You must use the @code{-a} global option to request
2960 stream authentication.
2961
2962 The data transmitted is @emph{not} encrypted by
2963 default.  Encryption support must be compiled into both
2964 the client and the server; use the
2965 @file{--enable-encrypt} configure option to turn it on.
2966 You must then use the @code{-x} global option to
2967 request encryption.
2968
2969 GSSAPI connections are handled on the server side by
2970 the same server which handles the password
2971 authentication server; see @ref{Password authentication
2972 server}.  If you are using a GSSAPI mechanism such as
2973 Kerberos which provides for strong authentication, you
2974 will probably want to disable the ability to
2975 authenticate via cleartext passwords.  To do so, create
2976 an empty @file{CVSROOT/passwd} password file, and set
2977 @code{SystemAuth=no} in the config file
2978 (@pxref{config}).
2979
2980 The GSSAPI server uses a principal name of
2981 cvs/@var{hostname}, where @var{hostname} is the
2982 canonical name of the server host.  You will have to
2983 set this up as required by your GSSAPI mechanism.
2984
2985 To connect using GSSAPI, use the @samp{:gserver:} method.  For
2986 example,
2987
2988 @example
2989 cvs -d :gserver:faun.example.org:/usr/local/cvsroot checkout foo
2990 @end example
2991
2992 @node Kerberos authenticated
2993 @subsection Direct connection with Kerberos
2994
2995 @cindex Kerberos, using :kserver:
2996 @cindex Security, Kerberos
2997 @cindex :kserver:, setting up
2998 The easiest way to use Kerberos is to use the Kerberos
2999 @code{rsh}, as described in @ref{Connecting via rsh}.
3000 The main disadvantage of using rsh is that all the data
3001 needs to pass through additional programs, so it may be
3002 slower.  So if you have Kerberos installed you can
3003 connect via a direct @sc{tcp} connection,
3004 authenticating with Kerberos.
3005
3006 This section concerns the Kerberos network security
3007 system, version 4.  Kerberos version 5 is supported via
3008 the GSSAPI generic network security interface, as
3009 described in the previous section.
3010
3011 To do this, @sc{cvs} needs to be compiled with Kerberos
3012 support; when configuring @sc{cvs} it tries to detect
3013 whether Kerberos is present or you can use the
3014 @file{--with-krb4} flag to configure.
3015
3016 The data transmitted is @emph{not} encrypted by
3017 default.  Encryption support must be compiled into both
3018 the client and server; use the
3019 @file{--enable-encryption} configure option to turn it
3020 on.  You must then use the @code{-x} global option to
3021 request encryption.
3022
3023 The CVS client will attempt to connect to port 1999 by default.
3024
3025 @cindex kinit
3026 When you want to use @sc{cvs}, get a ticket in the
3027 usual way (generally @code{kinit}); it must be a ticket
3028 which allows you to log into the server machine.  Then
3029 you are ready to go:
3030
3031 @example
3032 cvs -d :kserver:faun.example.org:/usr/local/cvsroot checkout foo
3033 @end example
3034
3035 Previous versions of @sc{cvs} would fall back to a
3036 connection via rsh; this version will not do so.
3037
3038 @node Connecting via fork
3039 @subsection Connecting with fork
3040
3041 @cindex fork, access method
3042 @cindex :fork:, setting up
3043 This access method allows you to connect to a
3044 repository on your local disk via the remote protocol.
3045 In other words it does pretty much the same thing as
3046 @code{:local:}, but various quirks, bugs and the like are
3047 those of the remote @sc{cvs} rather than the local
3048 @sc{cvs}.
3049
3050 For day-to-day operations you might prefer either
3051 @code{:local:} or @code{:fork:}, depending on your
3052 preferences.  Of course @code{:fork:} comes in
3053 particularly handy in testing or
3054 debugging @code{cvs} and the remote protocol.
3055 Specifically, we avoid all of the network-related
3056 setup/configuration, timeouts, and authentication
3057 inherent in the other remote access methods but still
3058 create a connection which uses the remote protocol.
3059
3060 To connect using the @code{fork} method, use
3061 @samp{:fork:} and the pathname to your local
3062 repository.  For example:
3063
3064 @example
3065 cvs -d :fork:/usr/local/cvsroot checkout foo
3066 @end example
3067
3068 @cindex CVS_SERVER, and :fork:
3069 As with @code{:ext:}, the server is called @samp{cvs}
3070 by default, or the value of the @code{CVS_SERVER}
3071 environment variable.
3072
3073
3074 @node Write proxies
3075 @subsection Distributing load across several CVS servers
3076
3077 @cindex PrimaryServer, in CVSROOT/config
3078 @cindex Primary server
3079 @cindex Secondary server
3080 @cindex proxy, write
3081 @cindex write proxy
3082 @sc{cvs} can be configured to distribute usage across several @sc{cvs}
3083 servers.  This is accomplished by means of one or more @dfn{write proxies}, or
3084 @dfn{secondary servers}, for a single @dfn{primary server}.
3085
3086 When a @sc{cvs} client accesses a secondary server and only sends read
3087 requests, then the secondary server handles the entire request.  If the client
3088 sends any write requests, however, the secondary server asks the client to
3089 redirect its write request to the primary server, if the client supports
3090 redirect requests, and otherwise becomes a transparent proxy for the primary
3091 server, which actually handles the write request.
3092
3093 In this manner, any number of read-only secondary servers may be configured as
3094 write proxies for the primary server, effectively distributing the load from
3095 all read operations between the secondary servers and restricting the load on
3096 the primary server to write operations and pushing changes to the secondaries.
3097
3098 Primary servers will not automatically push changes to secondaries.  This must
3099 be configured via @file{loginfo}, @file{postadmin}, @file{posttag}, &
3100 @file{postwatch} scripts (@pxref{Trigger Scripts}) like the following:
3101
3102 @example
3103 ALL     rsync -gopr -essh ./ secondary:/cvsroot/%p &
3104 @end example
3105
3106 You would probably actually want to lock directories for write on the secondary
3107 and for read on the primary before running the @samp{rsync} in the above
3108 example, but describing such a setup is beyond the scope of this document.
3109
3110 A secondary advantage of a write proxy setup is that users pointing at the
3111 secondary server can still execute fast read operations while on a network that
3112 connects to the primary over a slow link or even one where the link to the
3113 primary is periodically broken.  Only write operations will require the network
3114 link to the primary.
3115
3116 To configure write proxies, the primary must be specified with the
3117 @samp{PrimaryServer} option in @file{CVSROOT/config} (@pxref{config}).  For the
3118 transparent proxy mode to work, all secondary servers must also be running the
3119 same version of the @sc{cvs} server, or at least one that provides the same
3120 list of supported requests to the client as the primary server.  This is not
3121 necessary for redirection.
3122
3123 Once a primary server is configured, secondary servers may be configured by:
3124
3125 @enumerate
3126 @item
3127 Duplicating the primary repository at the new location.
3128 @item
3129 Setting up the @file{loginfo}, @file{postadmin}, @file{posttag}, and
3130 @file{postwatch} files on the primary to propagate writes to the new secondary.
3131 @item
3132 Configure remote access to the secondary(ies) as you would configure access
3133 to any other CVS server (@pxref{Remote repositories}).
3134 @item
3135 Ensuring that @code{--allow-root=@var{secondary-cvsroot}} is passed to
3136 @strong{all} incovations of the secondary server if the path to the @sc{cvs}
3137 repository directory is different on the two servers and you wish to support
3138 clients that do not handle the @samp{Redirect} resopnse (CVS 1.12.9 and earlier
3139 clients do not handle the @samp{Redirect} response).
3140
3141 Please note, again, that writethrough proxy suport requires
3142 @code{--allow-root=@var{secondary-cvsroot}} to be specified for @strong{all}
3143 incovations of the secondary server, not just @samp{pserver} invocations.
3144 This may require a wrapper script for the @sc{cvs} executable
3145 on your server machine.
3146 @end enumerate
3147
3148
3149 @c ---------------------------------------------------------------------
3150 @node Read-only access
3151 @section Read-only repository access
3152 @cindex Read-only repository access
3153 @cindex readers (admin file)
3154 @cindex writers (admin file)
3155
3156         It is possible to grant read-only repository
3157 access to people using the password-authenticated
3158 server (@pxref{Password authenticated}).  (The
3159 other access methods do not have explicit support for
3160 read-only users because those methods all assume login
3161 access to the repository machine anyway, and therefore
3162 the user can do whatever local file permissions allow
3163 her to do.)
3164
3165         A user who has read-only access can do only
3166 those @sc{cvs} operations which do not modify the
3167 repository, except for certain ``administrative'' files
3168 (such as lock files and the history file).  It may be
3169 desirable to use this feature in conjunction with
3170 user-aliasing (@pxref{Password authentication server}).
3171
3172 Unlike with previous versions of @sc{cvs}, read-only
3173 users should be able merely to read the repository, and
3174 not to execute programs on the server or otherwise gain
3175 unexpected levels of access.  Or to be more accurate,
3176 the @emph{known} holes have been plugged.  Because this
3177 feature is new and has not received a comprehensive
3178 security audit, you should use whatever level of
3179 caution seems warranted given your attitude concerning
3180 security.
3181
3182         There are two ways to specify read-only access
3183 for a user: by inclusion, and by exclusion.
3184
3185         "Inclusion" means listing that user
3186 specifically in the @file{$CVSROOT/CVSROOT/readers}
3187 file, which is simply a newline-separated list of
3188 users.  Here is a sample @file{readers} file:
3189
3190 @example
3191 melissa
3192 splotnik
3193 jrandom
3194 @end example
3195
3196 @noindent
3197         (Don't forget the newline after the last user.)
3198
3199         "Exclusion" means explicitly listing everyone
3200 who has @emph{write} access---if the file
3201
3202 @example
3203 $CVSROOT/CVSROOT/writers
3204 @end example
3205
3206 @noindent
3207 exists, then only
3208 those users listed in it have write access, and
3209 everyone else has read-only access (of course, even the
3210 read-only users still need to be listed in the
3211 @sc{cvs} @file{passwd} file).  The
3212 @file{writers} file has the same format as the
3213 @file{readers} file.
3214
3215         Note: if your @sc{cvs} @file{passwd}
3216 file maps cvs users onto system users (@pxref{Password
3217 authentication server}), make sure you deny or grant
3218 read-only access using the @emph{cvs} usernames, not
3219 the system usernames.  That is, the @file{readers} and
3220 @file{writers} files contain cvs usernames, which may
3221 or may not be the same as system usernames.
3222
3223         Here is a complete description of the server's
3224 behavior in deciding whether to grant read-only or
3225 read-write access:
3226
3227         If @file{readers} exists, and this user is
3228 listed in it, then she gets read-only access.  Or if
3229 @file{writers} exists, and this user is NOT listed in
3230 it, then she also gets read-only access (this is true
3231 even if @file{readers} exists but she is not listed
3232 there).  Otherwise, she gets full read-write access.
3233
3234         Of course there is a conflict if the user is
3235 listed in both files.  This is resolved in the more
3236 conservative way, it being better to protect the
3237 repository too much than too little: such a user gets
3238 read-only access.
3239
3240 @node Server temporary directory
3241 @section Temporary directories for the server
3242 @cindex Temporary directories, and server
3243 @cindex Server, temporary directories
3244
3245 While running, the @sc{cvs} server creates temporary
3246 directories.  They are named
3247
3248 @example
3249 cvs-serv@var{pid}
3250 @end example
3251
3252 @noindent
3253 where @var{pid} is the process identification number of
3254 the server.
3255 They are located in the directory specified by 
3256 the @samp{-T} global option (@pxref{Global options}), 
3257 the @code{TMPDIR} environment variable (@pxref{Environment variables}), 
3258 or, failing that, @file{/tmp}.
3259
3260 In most cases the server will remove the temporary
3261 directory when it is done, whether it finishes normally
3262 or abnormally.  However, there are a few cases in which
3263 the server does not or cannot remove the temporary
3264 directory, for example:
3265
3266 @itemize @bullet
3267 @item
3268 If the server aborts due to an internal server error,
3269 it may preserve the directory to aid in debugging
3270
3271 @item
3272 If the server is killed in a way that it has no way of
3273 cleaning up (most notably, @samp{kill -KILL} on unix).
3274
3275 @item
3276 If the system shuts down without an orderly shutdown,
3277 which tells the server to clean up.
3278 @end itemize
3279
3280 In cases such as this, you will need to manually remove
3281 the @file{cvs-serv@var{pid}} directories.  As long as
3282 there is no server running with process identification
3283 number @var{pid}, it is safe to do so.
3284
3285 @c ---------------------------------------------------------------------
3286 @node Starting a new project
3287 @chapter Starting a project with CVS
3288 @cindex Starting a project with CVS
3289 @cindex Creating a project
3290
3291 @comment --moduledb--
3292 Because renaming files and moving them between
3293 directories is somewhat inconvenient, the first thing
3294 you do when you start a new project should be to think
3295 through your file organization.  It is not impossible
3296 to rename or move files, but it does increase the
3297 potential for confusion and @sc{cvs} does have some
3298 quirks particularly in the area of renaming
3299 directories.  @xref{Moving files}.
3300
3301 What to do next depends on the situation at hand.
3302
3303 @menu
3304 * Setting up the files::        Getting the files into the repository
3305 * Defining the module::         How to make a module of the files
3306 @end menu
3307 @c -- File permissions!
3308
3309 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3310 @node Setting up the files
3311 @section Setting up the files
3312
3313 The first step is to create the files inside the repository.  This can
3314 be done in a couple of different ways.
3315
3316 @c -- The contributed scripts
3317 @menu
3318 * From files::                  This method is useful with old projects
3319                                 where files already exists.
3320 * From other version control systems::  Old projects where you want to
3321                                         preserve history from another system.
3322 * From scratch::                Creating a directory tree from scratch.
3323 @end menu
3324
3325 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3326 @node From files
3327 @subsection Creating a directory tree from a number of files
3328 @cindex Importing files
3329
3330 When you begin using @sc{cvs}, you will probably already have several
3331 projects that can be
3332 put under @sc{cvs} control.  In these cases the easiest way is to use the
3333 @code{import} command.  An example is probably the easiest way to
3334 explain how to use it.  If the files you want to install in
3335 @sc{cvs} reside in @file{@var{wdir}}, and you want them to appear in the
3336 repository as @file{$CVSROOT/yoyodyne/@var{rdir}}, you can do this:
3337
3338 @example
3339 $ cd @var{wdir}
3340 $ cvs import -m "Imported sources" yoyodyne/@var{rdir} yoyo start
3341 @end example
3342
3343 Unless you supply a log message with the @samp{-m}
3344 flag, @sc{cvs} starts an editor and prompts for a
3345 message.  The string @samp{yoyo} is a @dfn{vendor tag},
3346 and @samp{start} is a @dfn{release tag}.  They may fill
3347 no purpose in this context, but since @sc{cvs} requires
3348 them they must be present.  @xref{Tracking sources}, for
3349 more information about them.
3350
3351 You can now verify that it worked, and remove your
3352 original source directory.
3353 @c FIXME: Need to say more about "verify that it
3354 @c worked".  What should the user look for in the output
3355 @c from "diff -r"?
3356
3357 @example
3358 $ cd ..
3359 $ cvs checkout yoyodyne/@var{rdir}       # @r{Explanation below}
3360 $ diff -r @var{wdir} yoyodyne/@var{rdir}
3361 $ rm -r @var{wdir}
3362 @end example
3363
3364 @noindent
3365 Erasing the original sources is a good idea, to make sure that you do
3366 not accidentally edit them in @var{wdir}, bypassing @sc{cvs}.
3367 Of course, it would be wise to make sure that you have
3368 a backup of the sources before you remove them.
3369
3370 The @code{checkout} command can either take a module
3371 name as argument (as it has done in all previous
3372 examples) or a path name relative to @code{$CVSROOT},
3373 as it did in the example above.
3374
3375 It is a good idea to check that the permissions
3376 @sc{cvs} sets on the directories inside @code{$CVSROOT}
3377 are reasonable, and that they belong to the proper
3378 groups.  @xref{File permissions}.
3379
3380 If some of the files you want to import are binary, you
3381 may want to use the wrappers features to specify which
3382 files are binary and which are not.  @xref{Wrappers}.
3383
3384 @c The node name is too long, but I am having trouble
3385 @c thinking of something more concise.
3386 @node From other version control systems
3387 @subsection Creating Files From Other Version Control Systems
3388 @cindex Importing files, from other version control systems
3389
3390 If you have a project which you are maintaining with
3391 another version control system, such as @sc{rcs}, you
3392 may wish to put the files from that project into
3393 @sc{cvs}, and preserve the revision history of the
3394 files.
3395
3396 @table @asis
3397 @cindex RCS, importing files from
3398 @item From RCS
3399 If you have been using @sc{rcs}, find the @sc{rcs}
3400 files---usually a file named @file{foo.c} will have its
3401 @sc{rcs} file in @file{RCS/foo.c,v} (but it could be
3402 other places; consult the @sc{rcs} documentation for
3403 details).  Then create the appropriate directories in
3404 @sc{cvs} if they do not already exist.  Then copy the
3405 files into the appropriate directories in the @sc{cvs}
3406 repository (the name in the repository must be the name
3407 of the source file with @samp{,v} added; the files go
3408 directly in the appropriate directory of the repository,
3409 not in an @file{RCS} subdirectory).  This is one of the
3410 few times when it is a good idea to access the @sc{cvs}
3411 repository directly, rather than using @sc{cvs}
3412 commands.  Then you are ready to check out a new
3413 working directory.
3414 @c Someday there probably should be a "cvs import -t
3415 @c rcs" or some such.  It could even create magic
3416 @c branches.  It could also do something about the case
3417 @c where the RCS file had a (non-magic) "0" branch.
3418
3419 The @sc{rcs} file should not be locked when you move it