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