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