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