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