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