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