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