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