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