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