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