1 \input texinfo @c -*-texinfo-*-
2 @comment Documentation for CVS.
6 Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
7 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
8 Free Software Foundation, Inc.
10 @multitable @columnfractions .12 .88
12 @item @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005,
13 2006, 2007 Derek R. Price,
14 @item @tab Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007
15 Ximbiot @url{http://ximbiot.com},
16 @item @tab Copyright @copyright{} 1992, 1993, 1999 Signum Support AB,
17 @item @tab and Copyright @copyright{} others.
21 Permission is granted to process this file through Tex and print the
22 results, provided the printed document carries copying permission
23 notice identical to this one except for the removal of this paragraph
24 (this paragraph not being relevant to the printed manual).
27 Permission is granted to make and distribute verbatim copies of
28 this manual provided the copyright notice and this permission notice
29 are preserved on all copies.
31 Permission is granted to copy and distribute modified versions of this
32 manual under the conditions for verbatim copying, provided also that the
33 entire resulting derived work is distributed under the terms of a
34 permission notice identical to this one.
36 Permission is granted to copy and distribute translations of this manual
37 into another language, under the above conditions for modified versions,
38 except that this permission notice may be stated in a translation
39 approved by the Free Software Foundation.
42 @comment This file is part of the CVS distribution.
44 @comment CVS is free software; you can redistribute it and/or modify
45 @comment it under the terms of the GNU General Public License as published by
46 @comment the Free Software Foundation; either version 2, or (at your option)
47 @comment any later version.
49 @comment CVS is distributed in the hope that it will be useful,
50 @comment but WITHOUT ANY WARRANTY; without even the implied warranty of
51 @comment MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
52 @comment GNU General Public License for more details.
54 @c See ../README for A4 vs. US letter size.
55 @c When we provided A4 postscript, and people tried to
56 @c print it on US letter, the usual complaint was that the
57 @c page numbers would get cut off.
58 @c If one prints US letter on A4, reportedly there is
59 @c some extra space at the top and/or bottom, and the side
60 @c margins are a bit narrow, but no text is lost.
63 @c http://www.ft.uni-erlangen.de/~mskuhn/iso-paper.html
64 @c for more on paper sizes. Insuring that margins are
65 @c big enough to print on either A4 or US letter does
66 @c indeed seem to be the usual approach (RFC2346).
68 @c This document seems to get overfull hboxes with some
69 @c frequency (probably because the tendency is to
70 @c sanity-check it with "make info" and run TeX less
71 @c often). The big ugly boxes just seem to add insult
72 @c to injury, and I'm not aware of them helping to fix
73 @c the overfull hboxes at all.
77 @settitle CVS---Concurrent Versions System v@value{VERSION}
78 @setchapternewpage odd
81 @c -- Fix all lines that match "^@c -- "
82 @c -- Also places marked with FIXME should be manual
83 @c problems (as opposed to FIXCVS for CVS problems).
85 @c @splitrcskeyword{} is used to avoid keyword expansion. It is replaced by
86 @c @asis when generating info and dvi, and by <i></i> in the generated html,
87 @c such that keywords are not expanded in the generated html.
89 @macro splitrcskeyword {arg}
95 @macro splitrcskeyword {arg}
100 @dircategory GNU Packages
102 * CVS: (cvs). Concurrent Versions System
104 @dircategory Individual utilities
106 * cvs: (cvs)CVS commands. Concurrent Versions System
109 @comment The titlepage section does not appear in the Info file.
112 @comment The title is printed in a large font.
113 @center @titlefont{Version Management}
115 @center @titlefont{with}
117 @center @titlefont{CVS}
119 @center for @sc{cvs} @value{VERSION}
122 @center Per Cederqvist et al
124 @comment The following two commands start the copyright page
125 @comment for the printed manual. This will not appear in the Info file.
127 @vskip 0pt plus 1filll
135 @comment ================================================================
136 @comment The real text starts here
137 @comment ================================================================
140 @c ---------------------------------------------------------------------
144 This info manual describes how to use and administer
145 @sc{cvs} version @value{VERSION}.
152 @c This menu is pretty long. Not sure how easily that
153 @c can be fixed (no brilliant ideas right away)...
155 * Overview:: An introduction to CVS
156 * Repository:: Where all your sources are stored
157 * Starting a new project:: Starting a project with CVS
158 * Revisions:: Numeric and symbolic names for revisions
159 * Branching and merging:: Diverging/rejoining branches of development
160 * Recursive behavior:: CVS descends directories
161 * Adding and removing:: Adding/removing/renaming files/directories
162 * History browsing:: Viewing the history of files in various ways
164 CVS and the Real World.
165 -----------------------
166 * Binary files:: CVS can handle binary files
167 * Multiple developers:: How CVS helps a group of developers
168 * Revision management:: Policy questions for revision management
169 * Keyword substitution:: CVS can include the revision inside the file
170 * Tracking sources:: Tracking third-party sources
171 * Builds:: Issues related to CVS and builds
172 * Special Files:: Devices, links and other non-regular files
176 * CVS commands:: CVS commands share some things
177 * Invoking CVS:: Quick reference to CVS commands
178 * Administrative files:: Reference manual for the Administrative files
179 * Environment variables:: All environment variables which affect CVS
180 * Compatibility:: Upgrading CVS versions
181 * Troubleshooting:: Some tips when nothing works
182 * Credits:: Some of the contributors to this manual
183 * BUGS:: Dealing with bugs in CVS or this manual
187 @c ---------------------------------------------------------------------
192 This chapter is for people who have never used
193 @sc{cvs}, and perhaps have never used version control
196 If you are already familiar with @sc{cvs} and are just
197 trying to learn a particular feature or remember a
198 certain command, you can probably skip everything here.
201 * What is CVS?:: What you can do with @sc{cvs}
202 * What is CVS not?:: Problems @sc{cvs} doesn't try to solve
203 * A sample session:: A tour of basic @sc{cvs} usage
206 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
208 @section What is CVS?
210 @cindex Introduction to CVS
211 @cindex CVS, introduction to
213 @sc{cvs} is a version control system. Using it, you can
214 record the history of your source files.
217 @c -- ///Those who cannot remember the past are condemned to repeat it.
218 @c -- /// -- George Santayana
221 @c -- Insert history quote here!
222 For example, bugs sometimes creep in when
223 software is modified, and you might not detect the bug
224 until a long time after you make the modification.
225 With @sc{cvs}, you can easily retrieve old versions to see
226 exactly which change caused the bug. This can
227 sometimes be a big help.
229 You could of course save every version of every file
230 you have ever created. This would
231 however waste an enormous amount of disk space. @sc{cvs}
232 stores all the versions of a file in a single file in a
233 clever way that only stores the differences between
236 @sc{cvs} also helps you if you are part of a group of people working
237 on the same project. It is all too easy to overwrite
238 each others' changes unless you are extremely careful.
239 Some editors, like @sc{gnu} Emacs, try to make sure that
240 two people never modify the same file at the
241 same time. Unfortunately, if someone is using another
242 editor, that safeguard will not work. @sc{cvs} solves this problem
243 by insulating the different developers from each other. Every
244 developer works in his own directory, and @sc{cvs} merges
245 the work when each developer is done.
247 @cindex History of CVS
248 @cindex CVS, history of
249 @cindex Credits (CVS program)
250 @cindex Contributors (CVS program)
251 @sc{cvs} started out as a bunch of shell scripts written by
252 Dick Grune, posted to the newsgroup
253 @code{comp.sources.unix} in the volume 6
254 release of July, 1986. While no actual code from
255 these shell scripts is present in the current version
256 of @sc{cvs} much of the @sc{cvs} conflict resolution algorithms
259 In April, 1989, Brian Berliner designed and coded @sc{cvs}.
260 Jeff Polk later helped Brian with the design of the @sc{cvs}
261 module and vendor branch support.
263 @cindex Source, getting CVS source
264 You can get @sc{cvs} in a variety of ways, including
265 free download from the Internet. For more information
266 on downloading @sc{cvs} and other @sc{cvs} topics, see:
269 @url{http://cvs.nongnu.org/}
273 @cindex List, mailing list
275 There is a mailing list, known as @email{info-cvs@@nongnu.org},
276 devoted to @sc{cvs}. To subscribe or
279 @email{info-cvs-request@@nongnu.org}.
280 If you prefer a Usenet group, there is a one-way mirror (posts to the email
281 list are usually sent to the news group, but not vice versa) of
282 @email{info-cvs@@nongnu.org} at @url{news:gnu.cvs.help}. The right
283 Usenet group for posts is @url{news:comp.software.config-mgmt} which is for
284 @sc{cvs} discussions (along with other configuration
285 management systems). In the future, it might be
287 @code{comp.software.config-mgmt.cvs}, but probably only
288 if there is sufficient @sc{cvs} traffic on
289 @url{news:comp.software.config-mgmt}.
290 @c Other random data is that the tale was very
291 @c skeptical of comp.software.config-mgmt.cvs when the
292 @c subject came up around 1995 or so (for one
293 @c thing, because creating it would be a "reorg" which
294 @c would need to take a more comprehensive look at the
295 @c whole comp.software.config-mgmt.* hierarchy).
297 You can also subscribe to the @email{bug-cvs@@nongnu.org} mailing list,
298 described in more detail in @ref{BUGS}. To subscribe
299 send mail to @email{bug-cvs-request@@nongnu.org}. There is a two-way
300 Usenet mirror (posts to the Usenet group are usually sent to the email list and
301 vice versa) of @email{bug-cvs@@nongnu.org} named @url{news:gnu.cvs.bug}.
303 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
304 @node What is CVS not?
305 @section What is CVS not?
306 @cindex What is CVS not?
308 @sc{cvs} can do a lot of things for you, but it does
309 not try to be everything for everyone.
312 @item @sc{cvs} is not a build system.
314 Though the structure of your repository and modules
315 file interact with your build system
316 (e.g. @file{Makefile}s), they are essentially
319 @sc{cvs} does not dictate how you build anything. It
320 merely stores files for retrieval in a tree structure
323 @sc{cvs} does not dictate how to use disk space in the
324 checked out working directories. If you write your
325 @file{Makefile}s or scripts in every directory so they
326 have to know the relative positions of everything else,
327 you wind up requiring the entire repository to be
330 If you modularize your work, and construct a build
331 system that will share files (via links, mounts,
332 @code{VPATH} in @file{Makefile}s, etc.), you can
333 arrange your disk usage however you like.
335 But you have to remember that @emph{any} such system is
336 a lot of work to construct and maintain. @sc{cvs} does
337 not address the issues involved.
339 Of course, you should place the tools created to
340 support such a build system (scripts, @file{Makefile}s,
341 etc.) under @sc{cvs}.
343 Figuring out what files need to be rebuilt when
344 something changes is, again, something to be handled
345 outside the scope of @sc{cvs}. One traditional
346 approach is to use @code{make} for building, and use
347 some automated tool for generating the dependencies which
350 See @ref{Builds}, for more information on doing builds
351 in conjunction with @sc{cvs}.
353 @item @sc{cvs} is not a substitute for management.
355 Your managers and project leaders are expected to talk
356 to you frequently enough to make certain you are aware
357 of schedules, merge points, branch names and release
358 dates. If they don't, @sc{cvs} can't help.
360 @sc{cvs} is an instrument for making sources dance to
361 your tune. But you are the piper and the composer. No
362 instrument plays itself or writes its own music.
364 @item @sc{cvs} is not a substitute for developer communication.
366 When faced with conflicts within a single file, most
367 developers manage to resolve them without too much
368 effort. But a more general definition of ``conflict''
369 includes problems too difficult to solve without
370 communication between developers.
372 @sc{cvs} cannot determine when simultaneous changes
373 within a single file, or across a whole collection of
374 files, will logically conflict with one another. Its
375 concept of a @dfn{conflict} is purely textual, arising
376 when two changes to the same base file are near enough
377 to spook the merge (i.e., @code{diff3}) command.
379 @sc{cvs} does not claim to help at all in figuring out
380 non-textual or distributed conflicts in program logic.
382 For example: Say you change the arguments to function
383 @code{X} defined in file @file{A}. At the same time,
384 someone edits file @file{B}, adding new calls to
385 function @code{X} using the old arguments. You are
386 outside the realm of @sc{cvs}'s competence.
388 Acquire the habit of reading specs and talking to your
392 @item @sc{cvs} does not have change control
394 Change control refers to a number of things. First of
395 all it can mean @dfn{bug-tracking}, that is being able
396 to keep a database of reported bugs and the status of
397 each one (Is it fixed? In what release? Has the bug
398 submitter agreed that it is fixed?). For interfacing
399 @sc{cvs} to an external bug-tracking system, see the
400 @file{rcsinfo} and @file{verifymsg} files
401 (@pxref{Administrative files}).
403 Another aspect of change control is keeping track of
404 the fact that changes to several files were in fact
405 changed together as one logical change. If you check
406 in several files in a single @code{cvs commit}
407 operation, @sc{cvs} then forgets that those files were
408 checked in together, and the fact that they have the
409 same log message is the only thing tying them
410 together. Keeping a @sc{gnu} style @file{ChangeLog}
412 @c FIXME: should have an xref to a section which talks
413 @c more about keeping ChangeLog's with CVS, but that
414 @c section hasn't been written yet.
416 Another aspect of change control, in some systems, is
417 the ability to keep track of the status of each
418 change. Some changes have been written by a developer,
419 others have been reviewed by a second developer, and so
420 on. Generally, the way to do this with @sc{cvs} is to
421 generate a diff (using @code{cvs diff} or @code{diff})
422 and email it to someone who can then apply it using the
423 @code{patch} utility. This is very flexible, but
424 depends on mechanisms outside @sc{cvs} to make sure
425 nothing falls through the cracks.
427 @item @sc{cvs} is not an automated testing program
429 It should be possible to enforce mandatory use of a
430 test suite using the @code{commitinfo} file. I haven't
431 heard a lot about projects trying to do that or whether
432 there are subtle gotchas, however.
434 @item @sc{cvs} does not have a built-in process model
436 Some systems provide ways to ensure that changes or
437 releases go through various steps, with various
438 approvals as needed. Generally, one can accomplish
439 this with @sc{cvs} but it might be a little more work.
440 In some cases you'll want to use the @file{commitinfo},
441 @file{loginfo}, @file{rcsinfo}, or @file{verifymsg}
442 files, to require that certain steps be performed
443 before cvs will allow a checkin. Also consider whether
444 features such as branches and tags can be used to
445 perform tasks such as doing work in a development tree
446 and then merging certain changes over to a stable tree
447 only once they have been proven.
450 @c ---------------------------------------------------------------------
451 @node A sample session
452 @section A sample session
453 @cindex Example of a work-session
454 @cindex Getting started
455 @cindex Work-session, example of
456 @cindex tc, Trivial Compiler (example)
457 @cindex Trivial Compiler (example)
459 @c I think an example is a pretty good way to start. But
460 @c somewhere in here, maybe after the sample session,
461 @c we need something which is kind of
462 @c a "roadmap" which is more directed at sketching out
463 @c the functionality of CVS and pointing people to
464 @c various other parts of the manual. As it stands now
465 @c people who read in order get dumped right into all
466 @c manner of hair regarding remote repositories,
467 @c creating a repository, etc.
469 @c The following was in the old Basic concepts node. I don't
470 @c know how good a job it does at introducing modules,
471 @c or whether they need to be introduced so soon, but
472 @c something of this sort might go into some
473 @c introductory material somewhere.
475 @cindex Modules (intro)
476 The repository contains directories and files, in an
477 arbitrary tree. The @dfn{modules} feature can be used
478 to group together a set of directories or files into a
479 single entity (@pxref{modules}). A typical usage is to
480 define one module per project.
483 As a way of introducing @sc{cvs}, we'll go through a
484 typical work-session using @sc{cvs}. The first thing
485 to understand is that @sc{cvs} stores all files in a
486 centralized @dfn{repository} (@pxref{Repository}); this
487 section assumes that a repository is set up.
488 @c I'm not sure that the sentence concerning the
489 @c repository quite tells the user what they need to
490 @c know at this point. Might need to expand on "centralized"
491 @c slightly (maybe not here, maybe further down in the example?)
493 Suppose you are working on a simple compiler. The source
494 consists of a handful of C files and a @file{Makefile}.
495 The compiler is called @samp{tc} (Trivial Compiler),
496 and the repository is set up so that there is a module
500 * Getting the source:: Creating a workspace
501 * Committing your changes:: Making your work available to others
502 * Cleaning up:: Cleaning up
503 * Viewing differences:: Viewing differences
506 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
507 @node Getting the source
508 @subsection Getting the source
509 @cindex Getting the source
510 @cindex Checking out source
511 @cindex Fetching source
512 @cindex Source, getting from CVS
513 @cindex Checkout, example
515 The first thing you must do is to get your own working copy of the
516 source for @samp{tc}. For this, you use the @code{checkout} command:
523 This will create a new directory called @file{tc} and populate it with
529 CVS Makefile backend.c driver.c frontend.c parser.c
532 The @file{CVS} directory is used internally by
533 @sc{cvs}. Normally, you should not modify or remove
534 any of the files in it.
536 You start your favorite editor, hack away at @file{backend.c}, and a couple
537 of hours later you have added an optimization pass to the compiler.
538 A note to @sc{rcs} and @sc{sccs} users: There is no need to lock the files that
539 you want to edit. @xref{Multiple developers}, for an explanation.
541 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
542 @node Committing your changes
543 @subsection Committing your changes
544 @cindex Committing changes to files
545 @cindex Log message entry
547 When you have checked that the compiler is still compilable you decide
548 to make a new version of @file{backend.c}. This will
549 store your new @file{backend.c} in the repository and
550 make it available to anyone else who is using that same
554 $ cvs commit backend.c
558 @sc{cvs} starts an editor, to allow you to enter a log
559 message. You type in ``Added an optimization pass.'',
560 save the temporary file, and exit the editor.
562 @cindex CVSEDITOR, environment variable
563 @cindex EDITOR, environment variable
564 The environment variable @code{$CVSEDITOR} determines
565 which editor is started. If @code{$CVSEDITOR} is not
566 set, then if the environment variable @code{$EDITOR} is
567 set, it will be used. If both @code{$CVSEDITOR} and
568 @code{$EDITOR} are not set then there is a default
569 which will vary with your operating system, for example
570 @code{vi} for unix or @code{notepad} for Windows
573 @cindex VISUAL, environment variable
574 In addition, @sc{cvs} checks the @code{$VISUAL} environment
575 variable. Opinions vary on whether this behavior is desirable and
576 whether future releases of @sc{cvs} should check @code{$VISUAL} or
577 ignore it. You will be OK either way if you make sure that
578 @code{$VISUAL} is either unset or set to the same thing as
581 @c This probably should go into some new node
582 @c containing detailed info on the editor, rather than
583 @c the intro. In fact, perhaps some of the stuff with
584 @c CVSEDITOR and -m and so on should too.
585 When @sc{cvs} starts the editor, it includes a list of
586 files which are modified. For the @sc{cvs} client,
587 this list is based on comparing the modification time
588 of the file against the modification time that the file
589 had when it was last gotten or updated. Therefore, if
590 a file's modification time has changed but its contents
591 have not, it will show up as modified. The simplest
592 way to handle this is simply not to worry about it---if
593 you proceed with the commit @sc{cvs} will detect that
594 the contents are not modified and treat it as an
595 unmodified file. The next @code{update} will clue
596 @sc{cvs} in to the fact that the file is unmodified,
597 and it will reset its stored timestamp so that the file
598 will not show up in future editor sessions.
599 @c FIXCVS: Might be nice if "commit" and other commands
600 @c would reset that timestamp too, but currently commit
602 @c FIXME: Need to talk more about the process of
603 @c prompting for the log message. Like show an example
604 @c of what it pops up in the editor, for example. Also
605 @c a discussion of how to get the "a)bort, c)ontinue,
606 @c e)dit" prompt and what to do with it. Might also
607 @c work in the suggestion that if you want a diff, you
608 @c should make it before running commit (someone
609 @c suggested that the diff pop up in the editor. I'm
610 @c not sure that is better than telling people to run
611 @c "cvs diff" first if that is what they want, but if
612 @c we want to tell people that, the manual possibly
616 starting an editor you can specify the log message on
617 the command line using the @samp{-m} flag instead, like
621 $ cvs commit -m "Added an optimization pass" backend.c
624 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
626 @subsection Cleaning up
628 @cindex Working copy, removing
629 @cindex Removing your working copy
630 @cindex Releasing your working copy
632 Before you turn to other tasks you decide to remove your working copy of
633 tc. One acceptable way to do that is of course
641 but a better way is to use the @code{release} command (@pxref{release}):
648 You have [1] altered files in this repository.
649 Are you sure you want to release (and delete) directory `tc': n
650 ** `release' aborted by user choice.
653 The @code{release} command checks that all your modifications have been
654 committed. If history logging is enabled it also makes a note in the
655 history file. @xref{history file}.
657 When you use the @samp{-d} flag with @code{release}, it
658 also removes your working copy.
660 In the example above, the @code{release} command wrote a couple of lines
661 of output. @samp{? tc} means that the file @file{tc} is unknown to @sc{cvs}.
662 That is nothing to worry about: @file{tc} is the executable compiler,
663 and it should not be stored in the repository. @xref{cvsignore},
664 for information about how to make that warning go away.
665 @xref{release output}, for a complete explanation of
666 all possible output from @code{release}.
668 @samp{M driver.c} is more serious. It means that the
669 file @file{driver.c} has been modified since it was
672 The @code{release} command always finishes by telling
673 you how many modified files you have in your working
674 copy of the sources, and then asks you for confirmation
675 before deleting any files or making any note in the
678 You decide to play it safe and answer @kbd{n @key{RET}}
679 when @code{release} asks for confirmation.
681 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
682 @node Viewing differences
683 @subsection Viewing differences
684 @cindex Viewing differences
687 You do not remember modifying @file{driver.c}, so you want to see what
688 has happened to that file.
695 This command runs @code{diff} to compare the version of @file{driver.c}
696 that you checked out with your working copy. When you see the output
697 you remember that you added a command line option that enabled the
698 optimization pass. You check it in, and release the module.
699 @c FIXME: we haven't yet defined the term "check in".
702 $ cvs commit -m "Added an optimization pass" driver.c
703 Checking in driver.c;
704 /usr/local/cvsroot/tc/driver.c,v <-- driver.c
705 new revision: 1.2; previous revision: 1.1
710 You have [0] altered files in this repository.
711 Are you sure you want to release (and delete) directory `tc': y
714 @c ---------------------------------------------------------------------
716 @chapter The Repository
717 @cindex Repository (intro)
718 @cindex Repository, example
719 @cindex Layout of repository
720 @cindex Typical repository
721 @cindex /usr/local/cvsroot, as example repository
724 The @sc{cvs} @dfn{repository} stores a complete copy of
725 all the files and directories which are under version
728 Normally, you never access any of the files in the
729 repository directly. Instead, you use @sc{cvs}
730 commands to get your own copy of the files into a
731 @dfn{working directory}, and then
732 work on that copy. When you've finished a set of
733 changes, you check (or @dfn{commit}) them back into the
734 repository. The repository then contains the changes
735 which you have made, as well as recording exactly what
736 you changed, when you changed it, and other such
737 information. Note that the repository is not a
738 subdirectory of the working directory, or vice versa;
739 they should be in separate locations.
740 @c Need some example, e.g. repository
741 @c /usr/local/cvsroot; working directory
742 @c /home/joe/sources. But this node is too long
743 @c as it is; need a little reorganization...
745 @cindex :local:, setting up
746 @sc{cvs} can access a repository by a variety of
747 means. It might be on the local computer, or it might
748 be on a computer across the room or across the world.
749 To distinguish various ways to access a repository, the
750 repository name can start with an @dfn{access method}.
751 For example, the access method @code{:local:} means to
752 access a repository directory, so the repository
753 @code{:local:/usr/local/cvsroot} means that the
754 repository is in @file{/usr/local/cvsroot} on the
755 computer running @sc{cvs}. For information on other
756 access methods, see @ref{Remote repositories}.
758 @c Can se say this more concisely? Like by passing
759 @c more of the buck to the Remote repositories node?
760 If the access method is omitted, then if the repository
761 starts with @samp{/}, then @code{:local:} is
762 assumed. If it does not start with @samp{/} then either
763 @code{:ext:} or @code{:server:} is assumed. For
764 example, if you have a local repository in
765 @file{/usr/local/cvsroot}, you can use
766 @code{/usr/local/cvsroot} instead of
767 @code{:local:/usr/local/cvsroot}. But if (under
768 Windows NT, for example) your local repository is
769 @file{c:\src\cvsroot}, then you must specify the access
770 method, as in @code{:local:c:/src/cvsroot}.
772 @c This might appear to go in Repository storage, but
773 @c actually it is describing something which is quite
774 @c user-visible, when you do a "cvs co CVSROOT". This
775 @c isn't necessary the perfect place for that, though.
776 The repository is split in two parts. @file{$CVSROOT/CVSROOT} contains
777 administrative files for @sc{cvs}. The other directories contain the actual
778 user-defined modules.
781 * Specifying a repository:: Telling CVS where your repository is
782 * Repository storage:: The structure of the repository
783 * Working directory storage:: The structure of working directories
784 * Intro administrative files:: Defining modules
785 * Multiple repositories:: Multiple repositories
786 * Creating a repository:: Creating a repository
787 * Backing up:: Backing up a repository
788 * Moving a repository:: Moving a repository
789 * Remote repositories:: Accessing repositories on remote machines
790 * Read-only access:: Granting read-only access to the repository
791 * Server temporary directory:: The server creates temporary directories
794 @node Specifying a repository
795 @section Telling CVS where your repository is
797 There are several ways to tell @sc{cvs}
798 where to find the repository. You can name the
799 repository on the command line explicitly, with the
800 @code{-d} (for "directory") option:
803 cvs -d /usr/local/cvsroot checkout yoyodyne/tc
806 @cindex .profile, setting CVSROOT in
807 @cindex .cshrc, setting CVSROOT in
808 @cindex .tcshrc, setting CVSROOT in
809 @cindex .bashrc, setting CVSROOT in
810 @cindex CVSROOT, environment variable
811 Or you can set the @code{$CVSROOT} environment
812 variable to an absolute path to the root of the
813 repository, @file{/usr/local/cvsroot} in this example.
814 To set @code{$CVSROOT}, @code{csh} and @code{tcsh}
815 users should have this line in their @file{.cshrc} or
816 @file{.tcshrc} files:
819 setenv CVSROOT /usr/local/cvsroot
823 @code{sh} and @code{bash} users should instead have these lines in their
824 @file{.profile} or @file{.bashrc}:
827 CVSROOT=/usr/local/cvsroot
831 @cindex Root file, in CVS directory
832 @cindex CVS/Root file
833 A repository specified with @code{-d} will
834 override the @code{$CVSROOT} environment variable.
835 Once you've checked a working copy out from the
836 repository, it will remember where its repository is
837 (the information is recorded in the
838 @file{CVS/Root} file in the working copy).
840 The @code{-d} option and the @file{CVS/Root} file both
841 override the @code{$CVSROOT} environment variable. If
842 @code{-d} option differs from @file{CVS/Root}, the
843 former is used. Of course, for proper operation they
844 should be two ways of referring to the same repository.
846 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
847 @node Repository storage
848 @section How data is stored in the repository
849 @cindex Repository, how data is stored
851 For most purposes it isn't important @emph{how}
852 @sc{cvs} stores information in the repository. In
853 fact, the format has changed in the past, and is likely
854 to change in the future. Since in almost all cases one
855 accesses the repository via @sc{cvs} commands, such
856 changes need not be disruptive.
858 However, in some cases it may be necessary to
859 understand how @sc{cvs} stores data in the repository,
860 for example you might need to track down @sc{cvs} locks
861 (@pxref{Concurrency}) or you might need to deal with
862 the file permissions appropriate for the repository.
865 * Repository files:: What files are stored in the repository
866 * File permissions:: File permissions
867 * Windows permissions:: Issues specific to Windows
868 * Attic:: Some files are stored in the Attic
869 * CVS in repository:: Additional information in CVS directory
870 * Locks:: CVS locks control concurrent accesses
871 * CVSROOT storage:: A few things about CVSROOT are different
874 @node Repository files
875 @subsection Where files are stored within the repository
877 @c @cindex Filenames, legal
878 @c @cindex Legal filenames
879 @c Somewhere we need to say something about legitimate
880 @c characters in filenames in working directory and
881 @c repository. Not "/" (not even on non-unix). And
882 @c here is a specific set of issues:
883 @c Files starting with a - are handled inconsistently. They can not
884 @c be added to a repository with an add command, because it they are
885 @c interpreted as a switch. They can appear in a repository if they are
886 @c part of a tree that is imported. They can not be removed from the tree
887 @c once they are there.
888 @c Note that "--" *is* supported (as a
889 @c consequence of using GNU getopt). Should document
890 @c this somewhere ("Common options"?). The other usual technique,
891 @c "./-foo", isn't as effective, at least for "cvs add"
892 @c which doesn't support pathnames containing "/".
894 The overall structure of the repository is a directory
895 tree corresponding to the directories in the working
896 directory. For example, supposing the repository is in
903 here is a possible directory tree (showing only the
914 | (administrative files)
919 | | (source code to @sc{gnu} diff)
922 | | (source code to @sc{rcs})
925 | (source code to @sc{cvs})
935 +--(other Yoyodyne software)
938 With the directories are @dfn{history files} for each file
939 under version control. The name of the history file is
940 the name of the corresponding file with @samp{,v}
941 appended to the end. Here is what the repository for
942 the @file{yoyodyne/tc} directory might look like:
943 @c FIXME: Should also mention CVS (CVSREP)
944 @c FIXME? Should we introduce Attic with an xref to
945 @c Attic? Not sure whether that is a good idea or not.
968 @cindex History files
969 @cindex RCS history files
970 @c The first sentence, about what history files
971 @c contain, is kind of redundant with our intro to what the
972 @c repository does in node Repository....
973 The history files contain, among other things, enough
974 information to recreate any revision of the file, a log
975 of all commit messages and the user-name of the person
976 who committed the revision. The history files are
977 known as @dfn{RCS files}, because the first program to
978 store files in that format was a version control system
979 known as @sc{rcs}. For a full
980 description of the file format, see the @code{man} page
981 @cite{rcsfile(5)}, distributed with @sc{rcs}, or the
982 file @file{doc/RCSFILES} in the @sc{cvs} source
984 file format has become very common---many systems other
985 than @sc{cvs} or @sc{rcs} can at least import history
986 files in this format.
987 @c FIXME: Think about including documentation for this
988 @c rather than citing it? In the long run, getting
989 @c this to be a standard (not sure if we can cope with
990 @c a standards process as formal as IEEE/ANSI/ISO/etc,
991 @c though...) is the way to go, so maybe citing is
994 The @sc{rcs} files used in @sc{cvs} differ in a few
995 ways from the standard format. The biggest difference
996 is magic branches; for more information see @ref{Magic
997 branch numbers}. Also in @sc{cvs} the valid tag names
998 are a subset of what @sc{rcs} accepts; for @sc{cvs}'s
999 rules see @ref{Tags}.
1001 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1002 @node File permissions
1003 @subsection File permissions
1004 @c -- Move this to @node Creating a repository or similar
1005 @cindex Security, file permissions in repository
1006 @cindex File permissions, general
1007 @cindex Permissions, general
1008 @c FIXME: we need to somehow reflect "permissions in
1009 @c repository" versus "permissions in working
1010 @c directory" in the index entries.
1011 @cindex Group, UNIX file permissions, in repository
1012 @cindex Read-only files, in repository
1013 All @samp{,v} files are created read-only, and you
1014 should not change the permission of those files. The
1015 directories inside the repository should be writable by
1016 the persons that have permission to modify the files in
1017 each directory. This normally means that you must
1018 create a UNIX group (see group(5)) consisting of the
1019 persons that are to edit the files in a project, and
1020 set up the repository so that it is that group that
1022 (On some systems, you also need to set the set-group-ID-on-execution bit
1023 on the repository directories (see chmod(1)) so that newly-created files
1024 and directories get the group-ID of the parent directory rather than
1025 that of the current process.)
1027 @c See also comment in commitinfo node regarding cases
1028 @c which are really awkward with unix groups.
1030 This means that you can only control access to files on
1031 a per-directory basis.
1033 Note that users must also have write access to check
1034 out files, because @sc{cvs} needs to create lock files
1035 (@pxref{Concurrency}). You can use LockDir in CVSROOT/config
1036 to put the lock files somewhere other than in the repository
1037 if you want to allow read-only access to some directories
1040 @c CVS seems to use CVSUMASK in picking permissions for
1041 @c val-tags, but maybe we should say more about this.
1042 @c Like val-tags gets created by someone who doesn't
1043 @c have CVSUMASK set right?
1044 @cindex CVSROOT/val-tags file, and read-only access to projects
1045 @cindex val-tags file, and read-only access to projects
1046 Also note that users must have write access to the
1047 @file{CVSROOT/val-tags} file. @sc{cvs} uses it to keep
1048 track of what tags are valid tag names (it is sometimes
1049 updated when tags are used, as well as when they are
1052 Each @sc{rcs} file will be owned by the user who last
1053 checked it in. This has little significance; what
1054 really matters is who owns the directories.
1056 @cindex CVSUMASK, environment variable
1057 @cindex Umask, for repository files
1058 @sc{cvs} tries to set up reasonable file permissions
1059 for new directories that are added inside the tree, but
1060 you must fix the permissions manually when a new
1061 directory should have different permissions than its
1062 parent directory. If you set the @code{CVSUMASK}
1063 environment variable, that will control the file
1064 permissions which @sc{cvs} uses in creating directories
1065 and/or files in the repository. @code{CVSUMASK} does
1066 not affect the file permissions in the working
1067 directory; such files have the permissions which are
1068 typical for newly created files, except that sometimes
1069 @sc{cvs} creates them read-only (see the sections on
1070 watches, @ref{Setting a watch}; -r, @ref{Global
1071 options}; or @code{CVSREAD}, @ref{Environment variables}).
1072 @c FIXME: Need more discussion of which
1073 @c group should own the file in the repository.
1074 @c Include a somewhat detailed example of the usual
1075 @c case where CVSUMASK is 007, the developers are all
1076 @c in a group, and that group owns stuff in the
1077 @c repository. Need to talk about group ownership of
1078 @c newly-created directories/files (on some unices,
1079 @c such as SunOS4, setting the setgid bit on the
1080 @c directories will make files inherit the directory's
1081 @c group. On other unices, your mileage may vary. I
1082 @c can't remember what POSIX says about this, if
1085 Note that using the client/server @sc{cvs}
1086 (@pxref{Remote repositories}), there is no good way to
1087 set @code{CVSUMASK}; the setting on the client machine
1088 has no effect. If you are connecting with @code{rsh}, you
1089 can set @code{CVSUMASK} in @file{.bashrc} or @file{.cshrc}, as
1090 described in the documentation for your operating
1091 system. This behavior might change in future versions
1092 of @sc{cvs}; do not rely on the setting of
1093 @code{CVSUMASK} on the client having no effect.
1094 @c FIXME: need to explain what a umask is or cite
1095 @c someplace which does.
1097 @c There is also a larger (largely separate) issue
1098 @c about the meaning of CVSUMASK in a non-unix context.
1099 @c For example, whether there is
1100 @c an equivalent which fits better into other
1101 @c protection schemes like POSIX.6, VMS, &c.
1103 @c FIXME: Need one place which discusses this
1104 @c read-only files thing. Why would one use -r or
1105 @c CVSREAD? Why would one use watches? How do they
1108 @c FIXME: We need to state
1109 @c whether using CVSUMASK removes the need for manually
1110 @c fixing permissions (in fact, if we are going to mention
1111 @c manually fixing permission, we better document a lot
1112 @c better just what we mean by "fix").
1114 Using pserver, you will generally need stricter
1115 permissions on the @sc{cvsroot} directory and
1116 directories above it in the tree; see @ref{Password
1117 authentication security}.
1121 @cindex Security, setuid
1122 @cindex Installed images (VMS)
1123 Some operating systems have features which allow a
1124 particular program to run with the ability to perform
1125 operations which the caller of the program could not.
1126 For example, the set user ID (setuid) or set group ID
1127 (setgid) features of unix or the installed image
1128 feature of VMS. @sc{cvs} was not written to use such
1129 features and therefore attempting to install @sc{cvs} in
1130 this fashion will provide protection against only
1131 accidental lapses; anyone who is trying to circumvent
1132 the measure will be able to do so, and depending on how
1133 you have set it up may gain access to more than just
1134 @sc{cvs}. You may wish to instead consider pserver. It
1135 shares some of the same attributes, in terms of
1136 possibly providing a false sense of security or opening
1137 security holes wider than the ones you are trying to
1138 fix, so read the documentation on pserver security
1139 carefully if you are considering this option
1140 (@ref{Password authentication security}).
1142 @node Windows permissions
1143 @subsection File Permission issues specific to Windows
1144 @cindex Windows, and permissions
1145 @cindex File permissions, Windows-specific
1146 @cindex Permissions, Windows-specific
1148 Some file permission issues are specific to Windows
1149 operating systems (Windows 95, Windows NT, and
1150 presumably future operating systems in this family.
1151 Some of the following might apply to OS/2 but I'm not
1154 If you are using local @sc{cvs} and the repository is on a
1155 networked file system which is served by the Samba SMB
1156 server, some people have reported problems with
1157 permissions. Enabling WRITE=YES in the samba
1158 configuration is said to fix/workaround it.
1159 Disclaimer: I haven't investigated enough to know the
1160 implications of enabling that option, nor do I know
1161 whether there is something which @sc{cvs} could be doing
1162 differently in order to avoid the problem. If you find
1163 something out, please let us know as described in
1167 @subsection The attic
1170 You will notice that sometimes @sc{cvs} stores an
1171 @sc{rcs} file in the @code{Attic}. For example, if the
1172 @sc{cvsroot} is @file{/usr/local/cvsroot} and we are
1173 talking about the file @file{backend.c} in the
1174 directory @file{yoyodyne/tc}, then the file normally
1178 /usr/local/cvsroot/yoyodyne/tc/backend.c,v
1182 but if it goes in the attic, it would be in
1185 /usr/local/cvsroot/yoyodyne/tc/Attic/backend.c,v
1190 instead. It should not matter from a user point of
1191 view whether a file is in the attic; @sc{cvs} keeps
1192 track of this and looks in the attic when it needs to.
1193 But in case you want to know, the rule is that the RCS
1194 file is stored in the attic if and only if the head
1195 revision on the trunk has state @code{dead}. A
1196 @code{dead} state means that file has been removed, or
1197 never added, for that revision. For example, if you
1198 add a file on a branch, it will have a trunk revision
1199 in @code{dead} state, and a branch revision in a
1200 non-@code{dead} state.
1201 @c Probably should have some more concrete examples
1202 @c here, or somewhere (not sure exactly how we should
1203 @c arrange the discussion of the dead state, versus
1204 @c discussion of the attic).
1206 @node CVS in repository
1207 @subsection The CVS directory in the repository
1208 @cindex CVS directory, in repository
1210 The @file{CVS} directory in each repository directory
1211 contains information such as file attributes (in a file
1212 called @file{CVS/fileattr}. In the
1213 future additional files may be added to this directory,
1214 so implementations should silently ignore additional
1217 This behavior is implemented only by @sc{cvs} 1.7 and
1218 later; for details see @ref{Watches Compatibility}.
1220 The format of the @file{fileattr} file is a series of entries
1221 of the following form (where @samp{@{} and @samp{@}}
1222 means the text between the braces can be repeated zero
1225 @var{ent-type} @var{filename} <tab> @var{attrname} = @var{attrval}
1226 @{; @var{attrname} = @var{attrval}@} <linefeed>
1228 @var{ent-type} is @samp{F} for a file, in which case the entry specifies the
1229 attributes for that file.
1231 @var{ent-type} is @samp{D},
1232 and @var{filename} empty, to specify default attributes
1233 to be used for newly added files.
1235 Other @var{ent-type} are reserved for future expansion. @sc{cvs} 1.9 and older
1236 will delete them any time it writes file attributes.
1237 @sc{cvs} 1.10 and later will preserve them.
1239 Note that the order of the lines is not significant;
1240 a program writing the fileattr file may
1241 rearrange them at its convenience.
1243 There is currently no way of quoting tabs or line feeds in the
1244 filename, @samp{=} in @var{attrname},
1245 @samp{;} in @var{attrval}, etc. Note: some implementations also
1246 don't handle a NUL character in any of the fields, but
1247 implementations are encouraged to allow it.
1249 By convention, @var{attrname} starting with @samp{_} is for an attribute given
1250 special meaning by @sc{cvs}; other @var{attrname}s are for user-defined attributes
1251 (or will be, once implementations start supporting user-defined attributes).
1253 Built-in attributes:
1257 Present means the file is watched and should be checked out
1261 Users with watches for this file. Value is
1262 @var{watcher} > @var{type} @{ , @var{watcher} > @var{type} @}
1263 where @var{watcher} is a username, and @var{type}
1264 is zero or more of edit,unedit,commit separated by
1265 @samp{+} (that is, nothing if none; there is no "none" or "all" keyword).
1268 Users editing this file. Value is
1269 @var{editor} > @var{val} @{ , @var{editor} > @var{val} @}
1270 where @var{editor} is a username, and @var{val} is
1271 @var{time}+@var{hostname}+@var{pathname}, where
1272 @var{time} is when the @code{cvs edit} command (or
1273 equivalent) happened,
1274 and @var{hostname} and @var{pathname} are for the working directory.
1279 @c FIXME: sanity.sh should contain a similar test case
1280 @c so we can compare this example from something from
1281 @c Real Life(TM). See cvsclient.texi (under Notify) for more
1282 @c discussion of the date format of _editors.
1284 Ffile1 _watched=;_watchers=joe>edit,mary>commit
1285 Ffile2 _watched=;_editors=sue>8 Jan 1975+workstn1+/home/sue/cvs
1290 means that the file @file{file1} should be checked out
1291 read-only. Furthermore, joe is watching for edits and
1292 mary is watching for commits. The file @file{file2}
1293 should be checked out read-only; sue started editing it
1294 on 8 Jan 1975 in the directory @file{/home/sue/cvs} on
1295 the machine @code{workstn1}. Future files which are
1296 added should be checked out read-only. To represent
1297 this example here, we have shown a space after
1298 @samp{D}, @samp{Ffile1}, and @samp{Ffile2}, but in fact
1299 there must be a single tab character there and no spaces.
1302 @subsection CVS locks in the repository
1304 @cindex #cvs.rfl, technical details
1305 @cindex #cvs.wfl, technical details
1306 @cindex #cvs.lock, technical details
1307 @cindex Locks, cvs, technical details
1308 For an introduction to @sc{cvs} locks focusing on
1309 user-visible behavior, see @ref{Concurrency}. The
1310 following section is aimed at people who are writing
1311 tools which want to access a @sc{cvs} repository without
1312 interfering with other tools accessing the same
1313 repository. If you find yourself confused by concepts
1314 described here, like @dfn{read lock}, @dfn{write lock},
1315 and @dfn{deadlock}, you might consult the literature on
1316 operating systems or databases.
1319 Any file in the repository with a name starting
1320 with @file{#cvs.rfl.} is a read lock. Any file in
1321 the repository with a name starting with
1322 @file{#cvs.wfl} is a write lock. Old versions of @sc{cvs}
1323 (before @sc{cvs} 1.5) also created files with names starting
1324 with @file{#cvs.tfl}, but they are not discussed here.
1325 The directory @file{#cvs.lock} serves as a master
1326 lock. That is, one must obtain this lock first before
1327 creating any of the other locks.
1329 To obtain a read lock, first create the @file{#cvs.lock}
1330 directory. This operation must be atomic (which should
1331 be true for creating a directory under most operating
1332 systems). If it fails because the directory already
1333 existed, wait for a while and try again. After
1334 obtaining the @file{#cvs.lock} lock, create a file
1335 whose name is @file{#cvs.rfl.} followed by information
1336 of your choice (for example, hostname and process
1337 identification number). Then remove the
1338 @file{#cvs.lock} directory to release the master lock.
1339 Then proceed with reading the repository. When you are
1340 done, remove the @file{#cvs.rfl} file to release the
1343 To obtain a write lock, first create the
1344 @file{#cvs.lock} directory, as with read locks. Then
1345 check that there are no files whose names start with
1346 @file{#cvs.rfl.}. If there are, remove
1347 @file{#cvs.lock}, wait for a while, and try again. If
1348 there are no readers, then create a file whose name is
1349 @file{#cvs.wfl} followed by information of your choice
1350 (for example, hostname and process identification
1351 number). Hang on to the @file{#cvs.lock} lock. Proceed
1352 with writing the repository. When you are done, first
1353 remove the @file{#cvs.wfl} file and then the
1354 @file{#cvs.lock} directory. Note that unlike the
1355 @file{#cvs.rfl} file, the @file{#cvs.wfl} file is just
1356 informational; it has no effect on the locking operation
1357 beyond what is provided by holding on to the
1358 @file{#cvs.lock} lock itself.
1360 Note that each lock (write lock or read lock) only locks
1361 a single directory in the repository, including
1362 @file{Attic} and @file{CVS} but not including
1363 subdirectories which represent other directories under
1364 version control. To lock an entire tree, you need to
1365 lock each directory (note that if you fail to obtain
1366 any lock you need, you must release the whole tree
1367 before waiting and trying again, to avoid deadlocks).
1369 Note also that @sc{cvs} expects write locks to control
1370 access to individual @file{foo,v} files. @sc{rcs} has
1371 a scheme where the @file{,foo,} file serves as a lock,
1372 but @sc{cvs} does not implement it and so taking out a
1373 @sc{cvs} write lock is recommended. See the comments at
1374 rcs_internal_lockfile in the @sc{cvs} source code for
1375 further discussion/rationale.
1377 @node CVSROOT storage
1378 @subsection How files are stored in the CVSROOT directory
1379 @cindex CVSROOT, storage of files
1381 The @file{$CVSROOT/CVSROOT} directory contains the
1382 various administrative files. In some ways this
1383 directory is just like any other directory in the
1384 repository; it contains @sc{rcs} files whose names end
1385 in @samp{,v}, and many of the @sc{cvs} commands operate
1386 on it the same way. However, there are a few
1389 For each administrative file, in addition to the
1390 @sc{rcs} file, there is also a checked out copy of the
1391 file. For example, there is an @sc{rcs} file
1392 @file{loginfo,v} and a file @file{loginfo} which
1393 contains the latest revision contained in
1394 @file{loginfo,v}. When you check in an administrative
1395 file, @sc{cvs} should print
1398 cvs commit: Rebuilding administrative file database
1402 and update the checked out copy in
1403 @file{$CVSROOT/CVSROOT}. If it does not, there is
1404 something wrong (@pxref{BUGS}). To add your own files
1405 to the files to be updated in this fashion, you can add
1406 them to the @file{checkoutlist} administrative file
1407 (@pxref{checkoutlist}).
1412 By default, the @file{modules} file behaves as
1413 described above. If the modules file is very large,
1414 storing it as a flat text file may make looking up
1415 modules slow (I'm not sure whether this is as much of a
1416 concern now as when @sc{cvs} first evolved this
1417 feature; I haven't seen benchmarks). Therefore, by
1418 making appropriate edits to the @sc{cvs} source code
1419 one can store the modules file in a database which
1420 implements the @code{ndbm} interface, such as Berkeley
1421 db or GDBM. If this option is in use, then the modules
1422 database will be stored in the files @file{modules.db},
1423 @file{modules.pag}, and/or @file{modules.dir}.
1424 @c I think fileattr also will use the database stuff.
1427 For information on the meaning of the various
1428 administrative files, see @ref{Administrative files}.
1430 @node Working directory storage
1431 @section How data is stored in the working directory
1433 @c FIXME: Somewhere we should discuss timestamps (test
1434 @c case "stamps" in sanity.sh). But not here. Maybe
1435 @c in some kind of "working directory" chapter which
1436 @c would encompass the "Builds" one? But I'm not sure
1437 @c whether that is a good organization (is it based on
1438 @c what the user wants to do?).
1440 @cindex CVS directory, in working directory
1441 While we are discussing @sc{cvs} internals which may
1442 become visible from time to time, we might as well talk
1443 about what @sc{cvs} puts in the @file{CVS} directories
1444 in the working directories. As with the repository,
1445 @sc{cvs} handles this information and one can usually
1446 access it via @sc{cvs} commands. But in some cases it
1447 may be useful to look at it, and other programs, such
1448 as the @code{jCVS} graphical user interface or the
1449 @code{VC} package for emacs, may need to look at it.
1450 Such programs should follow the recommendations in this
1451 section if they hope to be able to work with other
1452 programs which use those files, including future
1453 versions of the programs just mentioned and the
1454 command-line @sc{cvs} client.
1456 The @file{CVS} directory contains several files.
1457 Programs which are reading this directory should
1458 silently ignore files which are in the directory but
1459 which are not documented here, to allow for future
1462 The files are stored according to the text file
1463 convention for the system in question. This means that
1464 working directories are not portable between systems
1465 with differing conventions for storing text files.
1466 This is intentional, on the theory that the files being
1467 managed by @sc{cvs} probably will not be portable between
1468 such systems either.
1472 This file contains the current @sc{cvs} root, as
1473 described in @ref{Specifying a repository}.
1475 @cindex Repository file, in CVS directory
1476 @cindex CVS/Repository file
1478 This file contains the directory within the repository
1479 which the current directory corresponds with. It can
1480 be either an absolute pathname or a relative pathname;
1481 @sc{cvs} has had the ability to read either format
1482 since at least version 1.3 or so. The relative
1483 pathname is relative to the root, and is the more
1484 sensible approach, but the absolute pathname is quite
1485 common and implementations should accept either. For
1486 example, after the command
1489 cvs -d :local:/usr/local/cvsroot checkout yoyodyne/tc
1493 @file{Root} will contain
1496 :local:/usr/local/cvsroot
1500 and @file{Repository} will contain either
1503 /usr/local/cvsroot/yoyodyne/tc
1513 If the particular working directory does not correspond
1514 to a directory in the repository, then @file{Repository}
1515 should contain @file{CVSROOT/Emptydir}.
1516 @cindex Emptydir, in CVSROOT directory
1517 @cindex CVSROOT/Emptydir directory
1519 @cindex Entries file, in CVS directory
1520 @cindex CVS/Entries file
1522 This file lists the files and directories in the
1524 The first character of each line indicates what sort of
1525 line it is. If the character is unrecognized, programs
1526 reading the file should silently skip that line, to
1527 allow for future expansion.
1529 If the first character is @samp{/}, then the format is:
1532 /@var{name}/@var{revision}/@var{timestamp}[+@var{conflict}]/@var{options}/@var{tagdate}
1536 where @samp{[} and @samp{]} are not part of the entry,
1537 but instead indicate that the @samp{+} and conflict
1538 marker are optional. @var{name} is the name of the
1539 file within the directory. @var{revision} is the
1540 revision that the file in the working derives from, or
1541 @samp{0} for an added file, or @samp{-} followed by a
1542 revision for a removed file. @var{timestamp} is the
1543 timestamp of the file at the time that @sc{cvs} created
1544 it; if the timestamp differs with the actual
1545 modification time of the file it means the file has
1546 been modified. It is stored in
1547 the format used by the ISO C asctime() function (for
1548 example, @samp{Sun Apr 7 01:29:26 1996}). One may
1549 write a string which is not in that format, for
1550 example, @samp{Result of merge}, to indicate that the
1551 file should always be considered to be modified. This
1552 is not a special case; to see whether a file is
1553 modified a program should take the timestamp of the file
1554 and simply do a string compare with @var{timestamp}.
1555 If there was a conflict, @var{conflict} can be set to
1556 the modification time of the file after the file has been
1557 written with conflict markers (@pxref{Conflicts example}).
1558 Thus if @var{conflict} is subsequently the same as the actual
1559 modification time of the file it means that the user
1560 has obviously not resolved the conflict. @var{options}
1561 contains sticky options (for example @samp{-kb} for a
1562 binary file). @var{tagdate} contains @samp{T} followed
1563 by a tag name, or @samp{D} for a date, followed by a
1564 sticky tag or date. Note that if @var{timestamp}
1565 contains a pair of timestamps separated by a space,
1566 rather than a single timestamp, you are dealing with a
1567 version of @sc{cvs} earlier than @sc{cvs} 1.5 (not
1570 The timezone on the timestamp in CVS/Entries (local or
1571 universal) should be the same as the operating system
1572 stores for the timestamp of the file itself. For
1573 example, on Unix the file's timestamp is in universal
1574 time (UT), so the timestamp in CVS/Entries should be
1575 too. On @sc{vms}, the file's timestamp is in local
1576 time, so @sc{cvs} on @sc{vms} should use local time.
1577 This rule is so that files do not appear to be modified
1578 merely because the timezone changed (for example, to or
1580 @c See comments and calls to gmtime() and friends in
1581 @c src/vers_ts.c (function time_stamp).
1583 If the first character of a line in @file{Entries} is
1584 @samp{D}, then it indicates a subdirectory. @samp{D}
1585 on a line all by itself indicates that the program
1586 which wrote the @file{Entries} file does record
1587 subdirectories (therefore, if there is such a line and
1588 no other lines beginning with @samp{D}, one knows there
1589 are no subdirectories). Otherwise, the line looks
1593 D/@var{name}/@var{filler1}/@var{filler2}/@var{filler3}/@var{filler4}
1597 where @var{name} is the name of the subdirectory, and
1598 all the @var{filler} fields should be silently ignored,
1599 for future expansion. Programs which modify
1600 @code{Entries} files should preserve these fields.
1602 The lines in the @file{Entries} file can be in any order.
1604 @cindex Entries.Log file, in CVS directory
1605 @cindex CVS/Entries.Log file
1607 This file does not record any information beyond that
1608 in @file{Entries}, but it does provide a way to update
1609 the information without having to rewrite the entire
1610 @file{Entries} file, including the ability to preserve
1611 the information even if the program writing
1612 @file{Entries} and @file{Entries.Log} abruptly aborts.
1613 Programs which are reading the @file{Entries} file
1614 should also check for @file{Entries.Log}. If the latter
1615 exists, they should read @file{Entries} and then apply
1616 the changes mentioned in @file{Entries.Log}. After
1617 applying the changes, the recommended practice is to
1618 rewrite @file{Entries} and then delete @file{Entries.Log}.
1619 The format of a line in @file{Entries.Log} is a single
1620 character command followed by a space followed by a
1621 line in the format specified for a line in
1622 @file{Entries}. The single character command is
1623 @samp{A} to indicate that the entry is being added,
1624 @samp{R} to indicate that the entry is being removed,
1625 or any other character to indicate that the entire line
1626 in @file{Entries.Log} should be silently ignored (for
1627 future expansion). If the second character of the line
1628 in @file{Entries.Log} is not a space, then it was
1629 written by an older version of @sc{cvs} (not documented
1632 Programs which are writing rather than reading can
1633 safely ignore @file{Entries.Log} if they so choose.
1635 @cindex Entries.Backup file, in CVS directory
1636 @cindex CVS/Entries.Backup file
1637 @item Entries.Backup
1638 This is a temporary file. Recommended usage is to
1639 write a new entries file to @file{Entries.Backup}, and
1640 then to rename it (atomically, where possible) to @file{Entries}.
1642 @cindex Entries.Static file, in CVS directory
1643 @cindex CVS/Entries.Static file
1644 @item Entries.Static
1645 The only relevant thing about this file is whether it
1646 exists or not. If it exists, then it means that only
1647 part of a directory was gotten and @sc{cvs} will
1648 not create additional files in that directory. To
1649 clear it, use the @code{update} command with the
1650 @samp{-d} option, which will get the additional files
1651 and remove @file{Entries.Static}.
1652 @c FIXME: This needs to be better documented, in places
1653 @c other than Working Directory Storage.
1654 @c FIXCVS: The fact that this setting exists needs to
1655 @c be more visible to the user. For example "cvs
1656 @c status foo", in the case where the file would be
1657 @c gotten except for Entries.Static, might say
1658 @c something to distinguish this from other cases.
1659 @c One thing that periodically gets suggested is to
1660 @c have "cvs update" print something when it skips
1661 @c files due to Entries.Static, but IMHO that kind of
1662 @c noise pretty much makes the Entries.Static feature
1665 @cindex Tag file, in CVS directory
1666 @cindex CVS/Tag file
1667 @cindex Sticky tags/dates, per-directory
1668 @cindex Per-directory sticky tags/dates
1670 This file contains per-directory sticky tags or dates.
1671 The first character is @samp{T} for a branch tag,
1672 @samp{N} for a non-branch tag, or @samp{D} for a date,
1673 or another character to mean the file should be
1674 silently ignored, for future expansion. This character
1675 is followed by the tag or date. Note that
1676 per-directory sticky tags or dates are used for things
1677 like applying to files which are newly added; they
1678 might not be the same as the sticky tags or dates on
1679 individual files. For general information on sticky
1680 tags and dates, see @ref{Sticky tags}.
1681 @c FIXME: This needs to be much better documented,
1682 @c preferably not in the context of "working directory
1684 @c FIXME: The Sticky tags node needs to discuss, or xref to
1685 @c someplace which discusses, per-directory sticky
1686 @c tags and the distinction with per-file sticky tags.
1688 @cindex Notify file, in CVS directory
1689 @cindex CVS/Notify file
1691 This file stores notifications (for example, for
1692 @code{edit} or @code{unedit}) which have not yet been
1693 sent to the server. Its format is not yet documented
1696 @cindex Notify.tmp file, in CVS directory
1697 @cindex CVS/Notify.tmp file
1699 This file is to @file{Notify} as @file{Entries.Backup}
1700 is to @file{Entries}. That is, to write @file{Notify},
1701 first write the new contents to @file{Notify.tmp} and
1702 then (atomically where possible), rename it to
1705 @cindex Base directory, in CVS directory
1706 @cindex CVS/Base directory
1708 If watches are in use, then an @code{edit} command
1709 stores the original copy of the file in the @file{Base}
1710 directory. This allows the @code{unedit} command to
1711 operate even if it is unable to communicate with the
1714 @cindex Baserev file, in CVS directory
1715 @cindex CVS/Baserev file
1717 The file lists the revision for each of the files in
1718 the @file{Base} directory. The format is:
1721 B@var{name}/@var{rev}/@var{expansion}
1725 where @var{expansion} should be ignored, to allow for
1728 @cindex Baserev.tmp file, in CVS directory
1729 @cindex CVS/Baserev.tmp file
1731 This file is to @file{Baserev} as @file{Entries.Backup}
1732 is to @file{Entries}. That is, to write @file{Baserev},
1733 first write the new contents to @file{Baserev.tmp} and
1734 then (atomically where possible), rename it to
1737 @cindex Template file, in CVS directory
1738 @cindex CVS/Template file
1740 This file contains the template specified by the
1741 @file{rcsinfo} file (@pxref{rcsinfo}). It is only used
1742 by the client; the non-client/server @sc{cvs} consults
1743 @file{rcsinfo} directly.
1746 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1747 @node Intro administrative files
1748 @section The administrative files
1749 @cindex Administrative files (intro)
1750 @cindex Modules file
1751 @cindex CVSROOT, module name
1752 @cindex Defining modules (intro)
1754 @c FIXME: this node should be reorganized into "general
1755 @c information about admin files" and put the "editing
1756 @c admin files" stuff up front rather than jumping into
1757 @c the details of modules right away. Then the
1758 @c Administrative files node can go away, the information
1759 @c on each admin file distributed to a place appropriate
1760 @c to its function, and this node can contain a table
1761 @c listing each file and a @ref to its detailed description.
1763 The directory @file{$CVSROOT/CVSROOT} contains some @dfn{administrative
1764 files}. @xref{Administrative files}, for a complete description.
1765 You can use @sc{cvs} without any of these files, but
1766 some commands work better when at least the
1767 @file{modules} file is properly set up.
1769 The most important of these files is the @file{modules}
1770 file. It defines all modules in the repository. This
1771 is a sample @file{modules} file.
1773 @c FIXME: The CVSROOT line is a goofy example now that
1774 @c mkmodules doesn't exist.
1777 modules CVSROOT modules
1784 The @file{modules} file is line oriented. In its
1785 simplest form each line contains the name of the
1786 module, whitespace, and the directory where the module
1787 resides. The directory is a path relative to
1788 @code{$CVSROOT}. The last four lines in the example
1789 above are examples of such lines.
1791 @c FIXME: might want to introduce the concept of options in modules file
1792 @c (the old example which was here, -i mkmodules, is obsolete).
1794 The line that defines the module called @samp{modules}
1795 uses features that are not explained here.
1796 @xref{modules}, for a full explanation of all the
1799 @c FIXME: subsection without node is bogus
1800 @subsection Editing administrative files
1801 @cindex Editing administrative files
1802 @cindex Administrative files, editing them
1804 You edit the administrative files in the same way that you would edit
1805 any other module. Use @samp{cvs checkout CVSROOT} to get a working
1806 copy, edit it, and commit your changes in the normal way.
1808 It is possible to commit an erroneous administrative
1809 file. You can often fix the error and check in a new
1810 revision, but sometimes a particularly bad error in the
1811 administrative file makes it impossible to commit new
1812 revisions. If and when this happens, you can correct
1813 the problem by temporarily copying a corrected administrative file
1814 directly into the @code{$CVSROOT/CVSROOT} repository directory,
1815 then committing the same correction via a checkout of the @file{CVSROOT}
1816 module. It is important that the correction also be made via the
1817 checked out copy, or the next checkout and commit to the
1818 <code>CVSROOT</code> module will overwrite the correction that was
1819 copied directly into the repository, possibly breaking things in such
1820 a way as to prevent commits again.
1821 @c @xref{Bad administrative files} for a hint
1822 @c about how to solve such situations.
1823 @c -- administrative file checking--
1825 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1826 @node Multiple repositories
1827 @section Multiple repositories
1828 @cindex Multiple repositories
1829 @cindex Repositories, multiple
1830 @cindex Many repositories
1831 @cindex Parallel repositories
1832 @cindex Disjoint repositories
1833 @cindex CVSROOT, multiple repositories
1835 In some situations it is a good idea to have more than
1836 one repository, for instance if you have two
1837 development groups that work on separate projects
1838 without sharing any code. All you have to do to have
1839 several repositories is to specify the appropriate
1840 repository, using the @code{CVSROOT} environment
1841 variable, the @samp{-d} option to @sc{cvs}, or (once
1842 you have checked out a working directory) by simply
1843 allowing @sc{cvs} to use the repository that was used
1844 to check out the working directory
1845 (@pxref{Specifying a repository}).
1847 The big advantage of having multiple repositories is
1848 that they can reside on different servers. With @sc{cvs}
1849 version 1.10, a single command cannot recurse into
1850 directories from different repositories. With development
1851 versions of @sc{cvs}, you can check out code from multiple
1852 servers into your working directory. @sc{cvs} will
1853 recurse and handle all the details of making
1854 connections to as many server machines as necessary to
1855 perform the requested command. Here is an example of
1856 how to set up a working directory:
1859 cvs -d server1:/cvs co dir1
1861 cvs -d server2:/root co sdir
1865 The @code{cvs co} commands set up the working
1866 directory, and then the @code{cvs update} command will
1867 contact server2, to update the dir1/sdir subdirectory,
1868 and server1, to update everything else.
1870 @c FIXME: Does the FAQ have more about this? I have a
1871 @c dim recollection, but I'm too lazy to check right now.
1873 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1874 @node Creating a repository
1875 @section Creating a repository
1877 @cindex Repository, setting up
1878 @cindex Creating a repository
1879 @cindex Setting up a repository
1881 This section describes how to set up a @sc{cvs} repository for any
1882 sort of access method. After completing the setup described in this
1883 section, you should be able to access your @sc{cvs} repository immediately
1884 via the local access method and several remote access methods. For
1885 more information on setting up remote access to the repository you create
1886 in this section, please read the section on @xref{Remote repositories}.
1888 To set up a @sc{cvs} repository, first choose the
1889 machine and disk on which you want to store the
1890 revision history of the source files. CPU and memory
1891 requirements are modest, so most machines should be
1892 adequate. For details see @ref{Server requirements}.
1893 @c Possible that we should be providing a quick rule of
1894 @c thumb, like the 32M memory for the server. That
1895 @c might increase the number of people who are happy
1896 @c with the answer, without following the xref.
1898 To estimate disk space
1899 requirements, if you are importing RCS files from
1900 another system, the size of those files is the
1901 approximate initial size of your repository, or if you
1902 are starting without any version history, a rule of
1903 thumb is to allow for the server approximately three
1904 times the size of the code to be under @sc{cvs} for the
1905 repository (you will eventually outgrow this, but not
1906 for a while). On the machines on which the developers
1907 will be working, you'll want disk space for
1908 approximately one working directory for each developer
1909 (either the entire tree or a portion of it, depending
1910 on what each developer uses).
1912 The repository should be accessible
1913 (directly or via a networked file system) from all
1914 machines which want to use @sc{cvs} in server or local
1915 mode; the client machines need not have any access to
1916 it other than via the @sc{cvs} protocol. It is not
1917 possible to use @sc{cvs} to read from a repository
1918 which one only has read access to; @sc{cvs} needs to be
1919 able to create lock files (@pxref{Concurrency}).
1921 @cindex init (subcommand)
1922 To create a repository, run the @code{cvs init}
1923 command. It will set up an empty repository in the
1924 @sc{cvs} root specified in the usual way
1925 (@pxref{Repository}). For example,
1928 cvs -d /usr/local/cvsroot init
1931 @code{cvs init} is careful to never overwrite any
1932 existing files in the repository, so no harm is done if
1933 you run @code{cvs init} on an already set-up
1936 @code{cvs init} will enable history logging; if you
1937 don't want that, remove the history file after running
1938 @code{cvs init}. @xref{history file}.
1941 @section Backing up a repository
1942 @cindex Repository, backing up
1943 @cindex Backing up, repository
1945 There is nothing particularly magical about the files
1946 in the repository; for the most part it is possible to
1947 back them up just like any other files. However, there
1948 are a few issues to consider.
1950 @cindex Locks, cvs, and backups
1951 @cindex #cvs.rfl, and backups
1952 The first is that to be paranoid, one should either not
1953 use @sc{cvs} during the backup, or have the backup
1954 program lock @sc{cvs} while doing the backup. To not
1955 use @sc{cvs}, you might forbid logins to machines which
1956 can access the repository, turn off your @sc{cvs}
1957 server, or similar mechanisms. The details would
1958 depend on your operating system and how you have
1959 @sc{cvs} set up. To lock @sc{cvs}, you would create
1960 @file{#cvs.rfl} locks in each repository directory.
1961 See @ref{Concurrency}, for more on @sc{cvs} locks.
1962 Having said all this, if you just back up without any
1963 of these precautions, the results are unlikely to be
1964 particularly dire. Restoring from backup, the
1965 repository might be in an inconsistent state, but this
1966 would not be particularly hard to fix manually.
1968 When you restore a repository from backup, assuming
1969 that changes in the repository were made after the time
1970 of the backup, working directories which were not
1971 affected by the failure may refer to revisions which no
1972 longer exist in the repository. Trying to run @sc{cvs}
1973 in such directories will typically produce an error
1974 message. One way to get those changes back into the
1975 repository is as follows:
1979 Get a new working directory.
1982 Copy the files from the working directory from before
1983 the failure over to the new working directory (do not
1984 copy the contents of the @file{CVS} directories, of
1988 Working in the new working directory, use commands such
1989 as @code{cvs update} and @code{cvs diff} to figure out
1990 what has changed, and then when you are ready, commit
1991 the changes into the repository.
1994 @node Moving a repository
1995 @section Moving a repository
1996 @cindex Repository, moving
1997 @cindex Moving a repository
1998 @cindex Copying a repository
2000 Just as backing up the files in the repository is
2001 pretty much like backing up any other files, if you
2002 need to move a repository from one place to another it
2003 is also pretty much like just moving any other
2004 collection of files.
2006 The main thing to consider is that working directories
2007 point to the repository. The simplest way to deal with
2008 a moved repository is to just get a fresh working
2009 directory after the move. Of course, you'll want to
2010 make sure that the old working directory had been
2011 checked in before the move, or you figured out some
2012 other way to make sure that you don't lose any
2013 changes. If you really do want to reuse the existing
2014 working directory, it should be possible with manual
2015 surgery on the @file{CVS/Repository} files. You can
2016 see @ref{Working directory storage}, for information on
2017 the @file{CVS/Repository} and @file{CVS/Root} files, but
2018 unless you are sure you want to bother, it probably
2020 @c FIXME: Surgery on CVS/Repository should be avoided
2021 @c by making RELATIVE_REPOS the default.
2022 @c FIXME-maybe: might want some documented way to
2023 @c change the CVS/Root files in some particular tree.
2024 @c But then again, I don't know, maybe just having
2025 @c people do this in perl/shell/&c isn't so bad...
2027 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
2028 @node Remote repositories
2029 @section Remote repositories
2030 @cindex Repositories, remote
2031 @cindex Remote repositories
2032 @cindex Client/Server Operation
2034 @cindex Remote repositories, port specification
2035 @cindex Repositories, remote, port specification
2036 @cindex Client/Server Operation, port specification
2037 @cindex pserver (client/server connection method), port specification
2038 @cindex kserver (client/server connection method), port specification
2039 @cindex gserver (client/server connection method), port specification
2040 @cindex port, specifying for remote repositories
2042 Your working copy of the sources can be on a
2043 different machine than the repository. Using @sc{cvs}
2044 in this manner is known as @dfn{client/server}
2045 operation. You run @sc{cvs} on a machine which can
2046 mount your working directory, known as the
2047 @dfn{client}, and tell it to communicate to a machine
2048 which can mount the repository, known as the
2049 @dfn{server}. Generally, using a remote
2050 repository is just like using a local one, except that
2051 the format of the repository name is:
2054 [:@var{method}:][[@var{user}][:@var{password}]@@]@var{hostname}[:[@var{port}]]/path/to/repository
2057 Specifying a password in the repository name is not recommended during
2058 checkout, since this will cause @sc{cvs} to store a cleartext copy of the
2059 password in each created directory. @code{cvs login} first instead
2060 (@pxref{Password authentication client}).
2062 The details of exactly what needs to be set up depend
2063 on how you are connecting to the server.
2065 If @var{method} is not specified, and the repository
2066 name contains @samp{:}, then the default is @code{ext}
2067 or @code{server}, depending on your platform; both are
2068 described in @ref{Connecting via rsh}.
2069 @c Should we try to explain which platforms are which?
2070 @c Platforms like unix and VMS, which only allow
2071 @c privileged programs to bind to sockets <1024 lose on
2073 @c Platforms like Mac and VMS, whose rsh program is
2074 @c unusable or nonexistent, lose on :ext:
2075 @c Platforms like OS/2 and NT probably could plausibly
2076 @c default either way (modulo -b troubles).
2078 @c FIXME: We need to have a better way of explaining
2079 @c what method to use. This presentation totally
2080 @c obscures the fact that :ext: and CVS_RSH is the way to
2081 @c use SSH, for example. Plus it incorrectly implies
2082 @c that you need an @code{rsh} binary on the client to use
2084 @c Also note that rsh not pserver is the right choice if you want
2085 @c users to be able to create their own repositories
2086 @c (because of the --allow-root related issues).
2088 * Server requirements:: Memory and other resources for servers
2089 * Connecting via rsh:: Using the @code{rsh} program to connect
2090 * Password authenticated:: Direct connections using passwords
2091 * GSSAPI authenticated:: Direct connections using GSSAPI
2092 * Kerberos authenticated:: Direct connections with Kerberos
2093 * Connecting via fork:: Using a forked @code{cvs server} to connect
2096 @node Server requirements
2097 @subsection Server requirements
2099 The quick answer to what sort of machine is suitable as
2100 a server is that requirements are modest---a server
2101 with 32M of memory or even less can handle a fairly
2102 large source tree with a fair amount of activity.
2103 @c Say something about CPU speed too? I'm even less sure
2104 @c what to say on that subject...
2106 The real answer, of course, is more complicated.
2107 Estimating the known areas of large memory consumption
2108 should be sufficient to estimate memory requirements.
2109 There are two such areas documented here; other memory
2110 consumption should be small by comparison (if you find
2111 that is not the case, let us know, as described in
2112 @ref{BUGS}, so we can update this documentation).
2114 The first area of big memory consumption is large
2115 checkouts, when using the @sc{cvs} server. The server
2116 consists of two processes for each client that it is
2117 serving. Memory consumption on the child process
2118 should remain fairly small. Memory consumption on the
2119 parent process, particularly if the network connection
2120 to the client is slow, can be expected to grow to
2121 slightly more than the size of the sources in a single
2122 directory, or two megabytes, whichever is larger.
2123 @c "two megabytes" of course is SERVER_HI_WATER. But
2124 @c we don't mention that here because we are
2125 @c documenting the default configuration of CVS. If it
2126 @c is a "standard" thing to change that value, it
2127 @c should be some kind of run-time configuration.
2129 @c See cvsclient.texi for more on the design decision
2130 @c to not have locks in place while waiting for the
2131 @c client, which is what results in memory consumption
2134 Multiplying the size of each @sc{cvs} server by the
2135 number of servers which you expect to have active at
2136 one time should give an idea of memory requirements for
2137 the server. For the most part, the memory consumed by
2138 the parent process probably can be swap space rather
2139 than physical memory.
2140 @c Has anyone verified that notion about swap space?
2141 @c I say it based pretty much on guessing that the
2142 @c ->text of the struct buffer_data only gets accessed
2143 @c in a first in, first out fashion, but I haven't
2144 @c looked very closely.
2146 @c What about disk usage in /tmp on the server? I think that
2147 @c it can be substantial, but I haven't looked at this
2148 @c again and tried to figure it out ("cvs import" is
2149 @c probably the worst case...).
2151 The second area of large memory consumption is
2152 @code{diff}, when checking in large files. This is
2153 required even for binary files. The rule of thumb is
2154 to allow about ten times the size of the largest file
2155 you will want to check in, although five times may be
2156 adequate. For example, if you want to check in a file
2157 which is 10 megabytes, you should have 100 megabytes of
2158 memory on the machine doing the checkin (the server
2159 machine for client/server, or the machine running
2160 @sc{cvs} for non-client/server). This can be swap
2161 space rather than physical memory. Because the memory
2162 is only required briefly, there is no particular need
2163 to allow memory for more than one such checkin at a
2165 @c The 5-10 times rule of thumb is from Paul Eggert for
2166 @c GNU diff. I don't think it is in the GNU diff
2167 @c manual or anyplace like that.
2169 @c Probably we could be saying more about
2170 @c non-client/server CVS.
2171 @c I would guess for non-client/server CVS in an NFS
2172 @c environment the biggest issues are the network and
2175 Resource consumption for the client is even more
2176 modest---any machine with enough capacity to run the
2177 operating system in question should have little
2179 @c Is that true? I think the client still wants to
2180 @c (bogusly) store entire files in memory at times.
2182 For information on disk space requirements, see
2183 @ref{Creating a repository}.
2185 @node Connecting via rsh
2186 @subsection Connecting with rsh or ssh
2189 @sc{cvs} may use the @samp{ssh} protocol to perform
2190 these operations, so the remote user host needs to have
2191 a either an agent like @code{ssh-agent} to hold
2192 credentials or a @file{.shosts} file which grants
2193 access to the local user. Note that the program that
2194 @sc{cvs} uses for this purpose may be specified using
2195 the @file{--with-ssh} flag to configure.
2198 @sc{cvs} uses the @samp{rsh} protocol to perform these
2199 operations, so the remote user host needs to have a
2200 @file{.rhosts} file which grants access to the local
2201 user. Note that the program that @sc{cvs} uses for this
2202 purpose may be specified using the @file{--with-rsh}
2205 For example, suppose you are the user @samp{mozart} on
2206 the local machine @samp{toe.example.com}, and the
2207 server machine is @samp{faun.example.org}. On
2208 faun, put the following line into the file
2209 @file{.rhosts} in @samp{bach}'s home directory:
2212 toe.example.com mozart
2216 Then test that @samp{rsh} is working with
2219 rsh -l bach faun.example.org 'echo $PATH'
2223 To test that @samp{ssh} is working use
2226 ssh -l bach faun.example.org 'echo $PATH'
2229 @cindex CVS_SERVER, environment variable
2230 Next you have to make sure that @code{rsh} will be able
2231 to find the server. Make sure that the path which
2232 @code{rsh} printed in the above example includes the
2233 directory containing a program named @code{cvs} which
2234 is the server. You need to set the path in
2235 @file{.bashrc}, @file{.cshrc}, etc., not @file{.login}
2236 or @file{.profile}. Alternately, you can set the
2237 environment variable @code{CVS_SERVER} on the client
2238 machine to the filename of the server you want to use,
2239 for example @file{/usr/local/bin/cvs-1.6}.
2240 @c FIXME: there should be a way to specify the
2241 @c program in CVSROOT, not CVS_SERVER, so that one can use
2242 @c different ones for different roots. e.g. ":server;cvs=cvs-1.6:"
2243 @c instead of ":server:".
2245 There is no need to edit @file{inetd.conf} or start a
2246 @sc{cvs} server daemon.
2248 @cindex :server:, setting up
2249 @cindex :ext:, setting up
2250 @cindex :extssh:, setting up
2251 @cindex Kerberos, using kerberized rsh
2252 @cindex SSH (rsh replacement)
2253 @cindex rsh replacements (Kerberized, SSH, &c)
2254 There are three access methods that you use in @code{CVSROOT}
2255 for rsh or ssh. @code{:server:} specifies an internal rsh
2256 client, which is supported only by some @sc{cvs} ports.
2257 @code{:extssh:} specifies an external ssh program. By
2258 default this is @code{ssh} (unless otherwise specified
2259 by the @file{--with-ssh} flag to configure) but you may set the
2260 @code{CVS_SSH} environment variable to invoke another
2261 program or wrapper script.
2262 @code{:ext:} specifies an external rsh program. By
2263 default this is @code{rsh} (unless otherwise specified
2264 by the @file{--with-rsh} flag to configure) but you may set the
2265 @code{CVS_RSH} environment variable to invoke another
2266 program which can access the remote server (for
2267 example, @code{remsh} on HP-UX 9 because @code{rsh} is
2268 something different). It must be a program which can
2269 transmit data to and from the server without modifying
2270 it; for example the Windows NT @code{rsh} is not
2271 suitable since it by default translates between CRLF
2272 and LF. The OS/2 @sc{cvs} port has a hack to pass @samp{-b}
2273 to @code{rsh} to get around this, but since this could
2274 potentially cause problems for programs other than the
2275 standard @code{rsh}, it may change in the future. If
2276 you set @code{CVS_RSH} to @code{SSH} or some other rsh
2277 replacement, the instructions in the rest of this
2278 section concerning @file{.rhosts} and so on are likely
2279 to be inapplicable; consult the documentation for your rsh
2281 @c FIXME: there should be a way to specify the
2282 @c program in CVSROOT, not CVS_RSH, so that one can use
2283 @c different ones for different roots. e.g.
2284 @c ":ext;CVS_RSH=remsh:" instead of ":ext:".
2285 @c See also the comment in src/client.c for rationale
2286 @c concerning "rsh" being the default and never
2289 Continuing our example, supposing you want to access
2290 the module @file{foo} in the repository
2291 @file{/usr/local/cvsroot/}, on machine
2292 @file{faun.example.org}, you are ready to go:
2295 cvs -d :ext:bach@@faun.example.org:/usr/local/cvsroot checkout foo
2299 (The @file{bach@@} can be omitted if the username is
2300 the same on both the local and remote hosts.)
2302 @c Should we mention "rsh host echo hi" and "rsh host
2303 @c cat" (the latter followed by typing text and ^D)
2304 @c as troubleshooting techniques? Probably yes
2305 @c (people tend to have trouble setting this up),
2306 @c but this kind of thing can be hard to spell out.
2308 @node Password authenticated
2309 @subsection Direct connection with password authentication
2311 The @sc{cvs} client can also connect to the server
2312 using a password protocol. This is particularly useful
2313 if using @code{rsh} is not feasible (for example,
2314 the server is behind a firewall), and Kerberos also is
2317 To use this method, it is necessary to make
2318 some adjustments on both the server and client sides.
2321 * Password authentication server:: Setting up the server
2322 * Password authentication client:: Using the client
2323 * Password authentication security:: What this method does and does not do
2326 @node Password authentication server
2327 @subsubsection Setting up the server for password authentication
2329 First of all, you probably want to tighten the
2330 permissions on the @file{$CVSROOT} and
2331 @file{$CVSROOT/CVSROOT} directories. See @ref{Password
2332 authentication security}, for more details.
2334 @cindex pserver (subcommand)
2335 @cindex Remote repositories, port specification
2336 @cindex Repositories, remote, port specification
2337 @cindex Client/Server Operation, port specification
2338 @cindex pserver (client/server connection method), port specification
2339 @cindex kserver (client/server connection method), port specification
2340 @cindex gserver (client/server connection method), port specification
2341 @cindex port, specifying for remote repositories
2342 @cindex Password server, setting up
2343 @cindex Authenticating server, setting up
2344 @cindex inetd, configuring for pserver
2345 @cindex xinetd, configuring for pserver
2346 @c FIXME: this isn't quite right regarding port
2347 @c numbers; CVS looks up "cvspserver" in
2348 @c /etc/services (on unix, but what about non-unix?).
2349 On the server side, the file @file{/etc/inetd.conf}
2350 needs to be edited so @code{inetd} knows to run the
2351 command @code{cvs pserver} when it receives a
2352 connection on the right port. By default, the port
2353 number is 2401; it would be different if your client
2354 were compiled with @code{CVS_AUTH_PORT} defined to
2355 something else, though. This can also be specified in the CVSROOT variable
2356 (@pxref{Remote repositories}) or overridden with the CVS_CLIENT_PORT
2357 environment variable (@pxref{Environment variables}).
2359 If your @code{inetd} allows raw port numbers in
2360 @file{/etc/inetd.conf}, then the following (all on a
2361 single line in @file{inetd.conf}) should be sufficient:
2364 2401 stream tcp nowait root /usr/local/bin/cvs
2365 cvs -f --allow-root=/usr/cvsroot pserver
2369 (You could also use the
2370 @samp{-T} option to specify a temporary directory.)
2372 The @samp{--allow-root} option specifies the allowable
2373 @sc{cvsroot} directory. Clients which attempt to use a
2374 different @sc{cvsroot} directory will not be allowed to
2375 connect. If there is more than one @sc{cvsroot}
2376 directory which you want to allow, repeat the option.
2377 (Unfortunately, many versions of @code{inetd} have very small
2378 limits on the number of arguments and/or the total length
2379 of the command. The usual solution to this problem is
2380 to have @code{inetd} run a shell script which then invokes
2381 @sc{cvs} with the necessary arguments.)
2383 If your @code{inetd} wants a symbolic service
2384 name instead of a raw port number, then put this in
2385 @file{/etc/services}:
2392 and put @code{cvspserver} instead of @code{2401} in @file{inetd.conf}.
2394 If your system uses @code{xinetd} instead of @code{inetd},
2395 the procedure is slightly different.
2396 Create a file called @file{/etc/xinetd.d/cvspserver} containing the following:
2402 socket_type = stream
2407 server = /usr/local/bin/cvs
2408 server_args = -f --allow-root=/usr/cvsroot pserver
2413 (If @code{cvspserver} is defined in @file{/etc/services}, you can omit
2414 the @code{port} line.)
2416 Once the above is taken care of, restart your
2417 @code{inetd}, or do whatever is necessary to force it
2418 to reread its initialization files.
2420 If you are having trouble setting this up, see
2423 @cindex CVS passwd file
2424 @cindex passwd (admin file)
2425 Because the client stores and transmits passwords in
2426 cleartext (almost---see @ref{Password authentication
2427 security}, for details), a separate @sc{cvs} password
2428 file is generally used, so people don't compromise
2429 their regular passwords when they access the
2430 repository. This file is
2431 @file{$CVSROOT/CVSROOT/passwd} (@pxref{Intro
2432 administrative files}). It uses a colon-separated
2433 format, similar to @file{/etc/passwd} on Unix systems,
2434 except that it has fewer fields: @sc{cvs} username,
2435 optional password, and an optional system username for
2436 @sc{cvs} to run as if authentication succeeds. Here is
2437 an example @file{passwd} file with five entries:
2442 spwang:1sOp854gDF3DY
2443 melissa:tGX1fS8sun6rY:pubcvs
2444 qproj:XR4EZcEs0szik:pubcvs
2448 (The passwords are encrypted according to the standard
2449 Unix @code{crypt()} function, so it is possible to
2450 paste in passwords directly from regular Unix
2451 @file{/etc/passwd} files.)
2453 The first line in the example will grant access to any
2454 @sc{cvs} client attempting to authenticate as user
2455 @code{anonymous}, no matter what password they use,
2456 including an empty password. (This is typical for
2457 sites granting anonymous read-only access; for
2458 information on how to do the "read-only" part, see
2459 @ref{Read-only access}.)
2461 The second and third lines will grant access to
2462 @code{bach} and @code{spwang} if they supply their
2463 respective plaintext passwords.
2465 @cindex User aliases
2466 The fourth line will grant access to @code{melissa}, if
2467 she supplies the correct password, but her @sc{cvs}
2468 operations will actually run on the server side under
2469 the system user @code{pubcvs}. Thus, there need not be
2470 any system user named @code{melissa}, but there
2471 @emph{must} be one named @code{pubcvs}.
2473 The fifth line shows that system user identities can be
2474 shared: any client who successfully authenticates as
2475 @code{qproj} will actually run as @code{pubcvs}, just
2476 as @code{melissa} does. That way you could create a
2477 single, shared system user for each project in your
2478 repository, and give each developer their own line in
2479 the @file{$CVSROOT/CVSROOT/passwd} file. The @sc{cvs}
2480 username on each line would be different, but the
2481 system username would be the same. The reason to have
2482 different @sc{cvs} usernames is that @sc{cvs} will log their
2483 actions under those names: when @code{melissa} commits
2484 a change to a project, the checkin is recorded in the
2485 project's history under the name @code{melissa}, not
2486 @code{pubcvs}. And the reason to have them share a
2487 system username is so that you can arrange permissions
2488 in the relevant area of the repository such that only
2489 that account has write-permission there.
2491 If the system-user field is present, all
2492 password-authenticated @sc{cvs} commands run as that
2493 user; if no system user is specified, @sc{cvs} simply
2494 takes the @sc{cvs} username as the system username and
2495 runs commands as that user. In either case, if there
2496 is no such user on the system, then the @sc{cvs}
2497 operation will fail (regardless of whether the client
2498 supplied a valid password).
2500 The password and system-user fields can both be omitted
2501 (and if the system-user field is omitted, then also
2502 omit the colon that would have separated it from the
2503 encrypted password). For example, this would be a
2504 valid @file{$CVSROOT/CVSROOT/passwd} file:
2508 fish:rKa5jzULzmhOo:kfogel
2509 sussman:1sOp854gDF3DY
2513 When the password field is omitted or empty, then the
2514 client's authentication attempt will succeed with any
2515 password, including the empty string. However, the
2516 colon after the @sc{cvs} username is always necessary,
2517 even if the password is empty.
2519 @sc{cvs} can also fall back to use system authentication.
2520 When authenticating a password, the server first checks
2521 for the user in the @file{$CVSROOT/CVSROOT/passwd}
2522 file. If it finds the user, it will use that entry for
2523 authentication as described above. But if it does not
2524 find the user, or if the @sc{cvs} @file{passwd} file
2525 does not exist, then the server can try to authenticate
2526 the username and password using the operating system's
2527 user-lookup routines (this "fallback" behavior can be
2528 disabled by setting @code{SystemAuth=no} in the
2529 @sc{cvs} @file{config} file, @pxref{config}). Be
2530 aware, however, that falling back to system
2531 authentication might be a security risk: @sc{cvs}
2532 operations would then be authenticated with that user's
2533 regular login password, and the password flies across
2534 the network in plaintext. See @ref{Password
2535 authentication security} for more on this.
2537 Right now, the only way to put a password in the
2538 @sc{cvs} @file{passwd} file is to paste it there from
2539 somewhere else. Someday, there may be a @code{cvs
2542 Unlike many of the files in @file{$CVSROOT/CVSROOT}, it
2543 is normal to edit the @file{passwd} file in-place,
2544 rather than via @sc{cvs}. This is because of the
2545 possible security risks of having the @file{passwd}
2546 file checked out to people's working copies. If you do
2547 want to include the @file{passwd} file in checkouts of
2548 @file{$CVSROOT/CVSROOT}, see @ref{checkoutlist}.
2550 @c We might also suggest using the @code{htpasswd} command
2551 @c from freely available web servers as well, but that
2552 @c would open up a can of worms in that the users next
2553 @c questions are likely to be "where do I get it?" and
2554 @c "how do I use it?"
2555 @c Also note that htpasswd, at least the version I had,
2556 @c likes to clobber the third field.
2558 @node Password authentication client
2559 @subsubsection Using the client with password authentication
2560 @cindex Login (subcommand)
2561 @cindex Password client, using
2562 @cindex Authenticated client, using
2563 @cindex :pserver:, setting up
2564 To run a @sc{cvs} command on a remote repository via
2565 the password-authenticating server, one specifies the
2566 @code{pserver} protocol, optional username, repository host, an
2567 optional port number, and path to the repository. For example:
2570 cvs -d :pserver:faun.example.org:/usr/local/cvsroot checkout someproj
2577 CVSROOT=:pserver:bach@@faun.example.org:2401/usr/local/cvsroot
2578 cvs checkout someproj
2581 However, unless you're connecting to a public-access
2582 repository (i.e., one where that username doesn't
2583 require a password), you'll need to supply a password or @dfn{log in} first.
2584 Logging in verifies your password with the repository and stores it in a file.
2585 It's done with the @code{login} command, which will
2586 prompt you interactively for the password if you didn't supply one as part of
2590 cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot login
2598 cvs -d :pserver:bach:p4ss30rd@@faun.example.org:/usr/local/cvsroot login
2601 After you enter the password, @sc{cvs} verifies it with
2602 the server. If the verification succeeds, then that
2603 combination of username, host, repository, and password
2604 is permanently recorded, so future transactions with
2605 that repository won't require you to run @code{cvs
2606 login}. (If verification fails, @sc{cvs} will exit
2607 complaining that the password was incorrect, and
2608 nothing will be recorded.)
2610 The records are stored, by default, in the file
2611 @file{$HOME/.cvspass}. That file's format is
2612 human-readable, and to a degree human-editable, but
2613 note that the passwords are not stored in
2614 cleartext---they are trivially encoded to protect them
2615 from "innocent" compromise (i.e., inadvertent viewing
2616 by a system administrator or other non-malicious
2619 @cindex CVS_PASSFILE, environment variable
2620 You can change the default location of this file by
2621 setting the @code{CVS_PASSFILE} environment variable.
2622 If you use this variable, make sure you set it
2623 @emph{before} @code{cvs login} is run. If you were to
2624 set it after running @code{cvs login}, then later
2625 @sc{cvs} commands would be unable to look up the
2626 password for transmission to the server.
2628 Once you have logged in, all @sc{cvs} commands using
2629 that remote repository and username will authenticate
2630 with the stored password. So, for example
2633 cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot checkout foo
2637 should just work (unless the password changes on the
2638 server side, in which case you'll have to re-run
2641 Note that if the @samp{:pserver:} were not present in
2642 the repository specification, @sc{cvs} would assume it
2643 should use @code{rsh} to connect with the server
2644 instead (@pxref{Connecting via rsh}).
2646 Of course, once you have a working copy checked out and
2647 are running @sc{cvs} commands from within it, there is
2648 no longer any need to specify the repository
2649 explicitly, because @sc{cvs} can deduce the repository
2650 from the working copy's @file{CVS} subdirectory.
2652 @c FIXME: seems to me this needs somewhat more
2654 @cindex Logout (subcommand)
2655 The password for a given remote repository can be
2656 removed from the @code{CVS_PASSFILE} by using the
2657 @code{cvs logout} command.
2659 @node Password authentication security
2660 @subsubsection Security considerations with password authentication
2662 @cindex Security, of pserver
2663 The passwords are stored on the client side in a
2664 trivial encoding of the cleartext, and transmitted in
2665 the same encoding. The encoding is done only to
2666 prevent inadvertent password compromises (i.e., a
2667 system administrator accidentally looking at the file),
2668 and will not prevent even a naive attacker from gaining
2671 @c FIXME: The bit about "access to the repository
2672 @c implies general access to the system is *not* specific
2673 @c to pserver; it applies to kerberos and SSH and
2674 @c everything else too. Should reorganize the
2675 @c documentation to make this clear.
2676 The separate @sc{cvs} password file (@pxref{Password
2677 authentication server}) allows people
2678 to use a different password for repository access than
2679 for login access. On the other hand, once a user has
2681 access to the repository, she can execute programs on
2682 the server system through a variety of means. Thus, repository
2683 access implies fairly broad system access as well. It
2684 might be possible to modify @sc{cvs} to prevent that,
2685 but no one has done so as of this writing.
2686 @c OpenBSD uses chroot() and copies the repository to
2687 @c provide anonymous read-only access (for details see
2688 @c http://www.openbsd.org/anoncvs.shar). While this
2689 @c closes the most obvious holes, I'm not sure it
2690 @c closes enough holes to recommend it (plus it is
2691 @c *very* easy to accidentally screw up a setup of this
2694 Note that because the @file{$CVSROOT/CVSROOT} directory
2695 contains @file{passwd} and other files which are used
2696 to check security, you must control the permissions on
2697 this directory as tightly as the permissions on
2698 @file{/etc}. The same applies to the @file{$CVSROOT}
2699 directory itself and any directory
2700 above it in the tree. Anyone who has write access to
2701 such a directory will have the ability to become any
2702 user on the system. Note that these permissions are
2703 typically tighter than you would use if you are not
2705 @c TODO: Would be really nice to document/implement a
2706 @c scheme where the CVS server can run as some non-root
2707 @c user, e.g. "cvs". CVSROOT/passwd would contain a
2708 @c bunch of entries of the form foo:xxx:cvs (or the "cvs"
2709 @c would be implicit). This would greatly reduce
2710 @c security risks such as those hinted at in the
2711 @c previous paragraph. I think minor changes to CVS
2712 @c might be required but mostly this would just need
2713 @c someone who wants to play with it, document it, &c.
2715 In summary, anyone who gets the password gets
2716 repository access (which may imply some measure of general system
2717 access as well). The password is available to anyone
2718 who can sniff network packets or read a protected
2719 (i.e., user read-only) file. If you want real
2720 security, get Kerberos.
2722 @node GSSAPI authenticated
2723 @subsection Direct connection with GSSAPI
2726 @cindex Security, GSSAPI
2727 @cindex :gserver:, setting up
2728 @cindex Kerberos, using :gserver:
2729 GSSAPI is a generic interface to network security
2730 systems such as Kerberos 5.
2731 If you have a working GSSAPI library, you can have
2732 @sc{cvs} connect via a direct @sc{tcp} connection,
2733 authenticating with GSSAPI.
2735 To do this, @sc{cvs} needs to be compiled with GSSAPI
2736 support; when configuring @sc{cvs} it tries to detect
2737 whether GSSAPI libraries using Kerberos version 5 are
2738 present. You can also use the @file{--with-gssapi}
2741 The connection is authenticated using GSSAPI, but the
2742 message stream is @emph{not} authenticated by default.
2743 You must use the @code{-a} global option to request
2744 stream authentication.
2746 The data transmitted is @emph{not} encrypted by
2747 default. Encryption support must be compiled into both
2748 the client and the server; use the
2749 @file{--enable-encrypt} configure option to turn it on.
2750 You must then use the @code{-x} global option to
2753 GSSAPI connections are handled on the server side by
2754 the same server which handles the password
2755 authentication server; see @ref{Password authentication
2756 server}. If you are using a GSSAPI mechanism such as
2757 Kerberos which provides for strong authentication, you
2758 will probably want to disable the ability to
2759 authenticate via cleartext passwords. To do so, create
2760 an empty @file{CVSROOT/passwd} password file, and set
2761 @code{SystemAuth=no} in the config file
2764 The GSSAPI server uses a principal name of
2765 cvs/@var{hostname}, where @var{hostname} is the
2766 canonical name of the server host. You will have to
2767 set this up as required by your GSSAPI mechanism.
2769 To connect using GSSAPI, use the @samp{:gserver:} method. For
2773 cvs -d :gserver:faun.example.org:/usr/local/cvsroot checkout foo
2776 @node Kerberos authenticated
2777 @subsection Direct connection with Kerberos
2779 @cindex Kerberos, using :kserver:
2780 @cindex Security, Kerberos
2781 @cindex :kserver:, setting up
2782 The easiest way to use Kerberos is to use the Kerberos
2783 @code{rsh}, as described in @ref{Connecting via rsh}.
2784 The main disadvantage of using rsh is that all the data
2785 needs to pass through additional programs, so it may be
2786 slower. So if you have Kerberos installed you can
2787 connect via a direct @sc{tcp} connection,
2788 authenticating with Kerberos.
2790 This section concerns the Kerberos network security
2791 system, version 4. Kerberos version 5 is supported via
2792 the GSSAPI generic network security interface, as
2793 described in the previous section.
2795 To do this, @sc{cvs} needs to be compiled with Kerberos
2796 support; when configuring @sc{cvs} it tries to detect
2797 whether Kerberos is present or you can use the
2798 @file{--with-krb4} flag to configure.
2800 The data transmitted is @emph{not} encrypted by
2801 default. Encryption support must be compiled into both
2802 the client and server; use the
2803 @file{--enable-encryption} configure option to turn it
2804 on. You must then use the @code{-x} global option to
2807 @cindex CVS_CLIENT_PORT
2808 You need to edit @file{inetd.conf} on the server
2809 machine to run @code{cvs kserver}. The client uses
2810 port 1999 by default; if you want to use another port
2811 specify it in the @code{CVSROOT} (@pxref{Remote repositories})
2812 or the @code{CVS_CLIENT_PORT} environment variable
2813 (@pxref{Environment variables}) on the client.
2816 When you want to use @sc{cvs}, get a ticket in the
2817 usual way (generally @code{kinit}); it must be a ticket
2818 which allows you to log into the server machine. Then
2819 you are ready to go:
2822 cvs -d :kserver:faun.example.org:/usr/local/cvsroot checkout foo
2825 Previous versions of @sc{cvs} would fall back to a
2826 connection via rsh; this version will not do so.
2828 @node Connecting via fork
2829 @subsection Connecting with fork
2831 @cindex fork, access method
2832 @cindex :fork:, setting up
2833 This access method allows you to connect to a
2834 repository on your local disk via the remote protocol.
2835 In other words it does pretty much the same thing as
2836 @code{:local:}, but various quirks, bugs and the like are
2837 those of the remote @sc{cvs} rather than the local
2840 For day-to-day operations you might prefer either
2841 @code{:local:} or @code{:fork:}, depending on your
2842 preferences. Of course @code{:fork:} comes in
2843 particularly handy in testing or
2844 debugging @code{cvs} and the remote protocol.
2845 Specifically, we avoid all of the network-related
2846 setup/configuration, timeouts, and authentication
2847 inherent in the other remote access methods but still
2848 create a connection which uses the remote protocol.
2850 To connect using the @code{fork} method, use
2851 @samp{:fork:} and the pathname to your local
2852 repository. For example:
2855 cvs -d :fork:/usr/local/cvsroot checkout foo
2858 @cindex CVS_SERVER, and :fork:
2859 As with @code{:ext:}, the server is called @samp{cvs}
2860 by default, or the value of the @code{CVS_SERVER}
2861 environment variable.
2863 @c ---------------------------------------------------------------------
2864 @node Read-only access
2865 @section Read-only repository access
2866 @cindex Read-only repository access
2867 @cindex readers (admin file)
2868 @cindex writers (admin file)
2870 It is possible to grant read-only repository
2871 access to people using the password-authenticated
2872 server (@pxref{Password authenticated}). (The
2873 other access methods do not have explicit support for
2874 read-only users because those methods all assume login
2875 access to the repository machine anyway, and therefore
2876 the user can do whatever local file permissions allow
2879 A user who has read-only access can do only
2880 those @sc{cvs} operations which do not modify the
2881 repository, except for certain ``administrative'' files
2882 (such as lock files and the history file). It may be
2883 desirable to use this feature in conjunction with
2884 user-aliasing (@pxref{Password authentication server}).
2886 Unlike with previous versions of @sc{cvs}, read-only
2887 users should be able merely to read the repository, and
2888 not to execute programs on the server or otherwise gain
2889 unexpected levels of access. Or to be more accurate,
2890 the @emph{known} holes have been plugged. Because this
2891 feature is new and has not received a comprehensive
2892 security audit, you should use whatever level of
2893 caution seems warranted given your attitude concerning
2896 There are two ways to specify read-only access
2897 for a user: by inclusion, and by exclusion.
2899 "Inclusion" means listing that user
2900 specifically in the @file{$CVSROOT/CVSROOT/readers}
2901 file, which is simply a newline-separated list of
2902 users. Here is a sample @file{readers} file:
2911 (Don't forget the newline after the last user.)
2913 "Exclusion" means explicitly listing everyone
2914 who has @emph{write} access---if the file
2917 $CVSROOT/CVSROOT/writers
2922 those users listed in it have write access, and
2923 everyone else has read-only access (of course, even the
2924 read-only users still need to be listed in the
2925 @sc{cvs} @file{passwd} file). The
2926 @file{writers} file has the same format as the
2927 @file{readers} file.
2929 Note: if your @sc{cvs} @file{passwd}
2930 file maps cvs users onto system users (@pxref{Password
2931 authentication server}), make sure you deny or grant
2932 read-only access using the @emph{cvs} usernames, not
2933 the system usernames. That is, the @file{readers} and
2934 @file{writers} files contain cvs usernames, which may
2935 or may not be the same as system usernames.
2937 Here is a complete description of the server's
2938 behavior in deciding whether to grant read-only or
2941 If @file{readers} exists, and this user is
2942 listed in it, then she gets read-only access. Or if
2943 @file{writers} exists, and this user is NOT listed in
2944 it, then she also gets read-only access (this is true
2945 even if @file{readers} exists but she is not listed
2946 there). Otherwise, she gets full read-write access.
2948 Of course there is a conflict if the user is
2949 listed in both files. This is resolved in the more
2950 conservative way, it being better to protect the
2951 repository too much than too little: such a user gets
2954 @node Server temporary directory
2955 @section Temporary directories for the server
2956 @cindex Temporary directories, and server
2957 @cindex Server, temporary directories
2959 While running, the @sc{cvs} server creates temporary
2960 directories. They are named
2967 where @var{pid} is the process identification number of
2969 They are located in the directory specified by
2970 the @samp{-T} global option (@pxref{Global options}),
2971 the @code{TMPDIR} environment variable (@pxref{Environment variables}),
2972 or, failing that, @file{/tmp}.
2974 In most cases the server will remove the temporary
2975 directory when it is done, whether it finishes normally
2976 or abnormally. However, there are a few cases in which
2977 the server does not or cannot remove the temporary
2978 directory, for example:
2982 If the server aborts due to an internal server error,
2983 it may preserve the directory to aid in debugging
2986 If the server is killed in a way that it has no way of
2987 cleaning up (most notably, @samp{kill -KILL} on unix).
2990 If the system shuts down without an orderly shutdown,
2991 which tells the server to clean up.
2994 In cases such as this, you will need to manually remove
2995 the @file{cvs-serv@var{pid}} directories. As long as
2996 there is no server running with process identification
2997 number @var{pid}, it is safe to do so.
2999 @c ---------------------------------------------------------------------
3000 @node Starting a new project
3001 @chapter Starting a project with CVS
3002 @cindex Starting a project with CVS
3003 @cindex Creating a project
3005 @comment --moduledb--
3006 Because renaming files and moving them between
3007 directories is somewhat inconvenient, the first thing
3008 you do when you start a new project should be to think
3009 through your file organization. It is not impossible
3010 to rename or move files, but it does increase the
3011 potential for confusion and @sc{cvs} does have some
3012 quirks particularly in the area of renaming
3013 directories. @xref{Moving files}.
3015 What to do next depends on the situation at hand.
3018 * Setting up the files:: Getting the files into the repository
3019 * Defining the module:: How to make a module of the files
3021 @c -- File permissions!
3023 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3024 @node Setting up the files
3025 @section Setting up the files
3027 The first step is to create the files inside the repository. This can
3028 be done in a couple of different ways.
3030 @c -- The contributed scripts
3032 * From files:: This method is useful with old projects
3033 where files already exists.
3034 * From other version control systems:: Old projects where you want to
3035 preserve history from another system.
3036 * From scratch:: Creating a directory tree from scratch.
3039 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3041 @subsection Creating a directory tree from a number of files
3042 @cindex Importing files
3044 When you begin using @sc{cvs}, you will probably already have several
3045 projects that can be
3046 put under @sc{cvs} control. In these cases the easiest way is to use the
3047 @code{import} command. An example is probably the easiest way to
3048 explain how to use it. If the files you want to install in
3049 @sc{cvs} reside in @file{@var{wdir}}, and you want them to appear in the
3050 repository as @file{$CVSROOT/yoyodyne/@var{rdir}}, you can do this:
3054 $ cvs import -m "Imported sources" yoyodyne/@var{rdir} yoyo start
3057 Unless you supply a log message with the @samp{-m}
3058 flag, @sc{cvs} starts an editor and prompts for a
3059 message. The string @samp{yoyo} is a @dfn{vendor tag},
3060 and @samp{start} is a @dfn{release tag}. They may fill
3061 no purpose in this context, but since @sc{cvs} requires
3062 them they must be present. @xref{Tracking sources}, for
3063 more information about them.
3065 You can now verify that it worked, and remove your
3066 original source directory.
3067 @c FIXME: Need to say more about "verify that it
3068 @c worked". What should the user look for in the output
3073 $ cvs checkout yoyodyne/@var{rdir} # @r{Explanation below}
3074 $ diff -r @var{wdir} yoyodyne/@var{rdir}
3079 Erasing the original sources is a good idea, to make sure that you do
3080 not accidentally edit them in @var{wdir}, bypassing @sc{cvs}.
3081 Of course, it would be wise to make sure that you have
3082 a backup of the sources before you remove them.
3084 The @code{checkout} command can either take a module
3085 name as argument (as it has done in all previous
3086 examples) or a path name relative to @code{$CVSROOT},
3087 as it did in the example above.
3089 It is a good idea to check that the permissions
3090 @sc{cvs} sets on the directories inside @code{$CVSROOT}
3091 are reasonable, and that they belong to the proper
3092 groups. @xref{File permissions}.
3094 If some of the files you want to import are binary, you
3095 may want to use the wrappers features to specify which
3096 files are binary and which are not. @xref{Wrappers}.
3098 @c The node name is too long, but I am having trouble
3099 @c thinking of something more concise.
3100 @node From other version control systems
3101 @subsection Creating Files From Other Version Control Systems
3102 @cindex Importing files, from other version control systems
3104 If you have a project which you are maintaining with
3105 another version control system, such as @sc{rcs}, you
3106 may wish to put the files from that project into
3107 @sc{cvs}, and preserve the revision history of the
3111 @cindex RCS, importing files from
3113 If you have been using @sc{rcs}, find the @sc{rcs}
3114 files---usually a file named @file{foo.c} will have its
3115 @sc{rcs} file in @file{RCS/foo.c,v} (but it could be
3116 other places; consult the @sc{rcs} documentation for
3117 details). Then create the appropriate directories in
3118 @sc{cvs} if they do not already exist. Then copy the
3119 files into the appropriate directories in the @sc{cvs}
3120 repository (the name in the repository must be the name
3121 of the source file with @samp{,v} added; the files go
3122 directly in the appropriate directory of the repository,
3123 not in an @file{RCS} subdirectory). This is one of the
3124 few times when it is a good idea to access the @sc{cvs}
3125 repository directly, rather than using @sc{cvs}
3126 commands. Then you are ready to check out a new
3128 @c Someday there probably should be a "cvs import -t
3129 @c rcs" or some such. It could even create magic
3130 @c branches. It could also do something about the case
3131 @c where the RCS file had a (non-magic) "0" branch.
3133 The @sc{rcs} file should not be locked when you move it
3134 into @sc{cvs}; if it is, @sc{cvs} will have trouble
3135 letting you operate on it.
3136 @c What is the easiest way to unlock your files if you
3137 @c have them locked? Especially if you have a lot of them?
3138 @c This is a CVS bug/misfeature; importing RCS files
3139 @c should ignore whether they are locked and leave them in
3140 @c an unlocked state. Yet another reason for a separate
3141 @c "import RCS file" command.
3143 @c How many is "many"? Or do they just import RCS files?
3144 @item From another version control system
3145 Many version control systems have the ability to export
3146 @sc{rcs} files in the standard format. If yours does,
3147 export the @sc{rcs} files and then follow the above
3150 Failing that, probably your best bet is to write a
3151 script that will check out the files one revision at a
3152 time using the command line interface to the other
3153 system, and then check the revisions into @sc{cvs}.
3154 The @file{sccs2rcs} script mentioned below may be a
3155 useful example to follow.
3157 @cindex SCCS, importing files from
3159 There is a script in the @file{contrib} directory of
3160 the @sc{cvs} source distribution called @file{sccs2rcs}
3161 which converts @sc{sccs} files to @sc{rcs} files.
3162 Note: you must run it on a machine which has both
3163 @sc{sccs} and @sc{rcs} installed, and like everything
3164 else in contrib it is unsupported (your mileage may
3167 @cindex PVCS, importing files from
3169 There is a script in the @file{contrib} directory of
3170 the @sc{cvs} source distribution called @file{pvcs_to_rcs}
3171 which converts @sc{pvcs} archives to @sc{rcs} files.
3172 You must run it on a machine which has both
3173 @sc{pvcs} and @sc{rcs} installed, and like everything
3174 else in contrib it is unsupported (your mileage may
3175 vary). See the comments in the script for details.
3177 @c CMZ and/or PATCHY were systems that were used in the
3178 @c high energy physics community (especially for
3179 @c CERNLIB). CERN has replaced them with CVS, but the
3180 @c CAR format seems to live on as a way to submit
3181 @c changes. There is a program car2cvs which converts
3182 @c but I'm not sure where one gets a copy.
3183 @c Not sure it is worth mentioning here, since it would
3184 @c appear to affect only one particular community.
3185 @c Best page for more information is:
3186 @c http://wwwcn1.cern.ch/asd/cvs/index.html
3188 @c http://ecponion.cern.ch/ecpsa/cernlib.html
3190 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3192 @subsection Creating a directory tree from scratch
3194 @c Also/instead should be documenting
3202 @c Using import to create the directories only is
3203 @c probably a somewhat confusing concept.
3204 For a new project, the easiest thing to do is probably
3205 to create an empty directory structure, like this:
3213 After that, you use the @code{import} command to create
3214 the corresponding (empty) directory structure inside
3219 $ cvs import -m "Created directory structure" yoyodyne/@var{dir} yoyo start
3222 This will add yoyodyne/@var{dir} as a directory under
3225 Use @code{checkout} to get the new project. Then, use @code{add}
3226 to add files (and new directories) as needed.
3230 $ cvs co yoyodyne/@var{dir}
3233 Check that the permissions @sc{cvs} sets on the
3234 directories inside @code{$CVSROOT} are reasonable.
3236 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3237 @node Defining the module
3238 @section Defining the module
3239 @cindex Defining a module
3240 @cindex Editing the modules file
3241 @cindex Module, defining
3242 @cindex Modules file, changing
3244 The next step is to define the module in the
3245 @file{modules} file. This is not strictly necessary,
3246 but modules can be convenient in grouping together
3247 related files and directories.
3249 In simple cases these steps are sufficient to define a module.
3253 Get a working copy of the modules file.
3256 $ cvs checkout CVSROOT/modules
3261 Edit the file and insert a line that defines the module. @xref{Intro
3262 administrative files}, for an introduction. @xref{modules}, for a full
3263 description of the modules file. You can use the
3264 following line to define the module @samp{tc}:
3271 Commit your changes to the modules file.
3274 $ cvs commit -m "Added the tc module." modules
3278 Release the modules module.
3282 $ cvs release -d CVSROOT
3286 @c ---------------------------------------------------------------------
3290 For many uses of @sc{cvs}, one doesn't need to worry
3291 too much about revision numbers; @sc{cvs} assigns
3292 numbers such as @code{1.1}, @code{1.2}, and so on, and
3293 that is all one needs to know. However, some people
3294 prefer to have more knowledge and control concerning
3295 how @sc{cvs} assigns revision numbers.
3297 If one wants to keep track of a set of revisions
3298 involving more than one file, such as which revisions
3299 went into a particular release, one uses a @dfn{tag},
3300 which is a symbolic revision which can be assigned to a
3301 numeric revision in each file.
3304 * Revision numbers:: The meaning of a revision number
3305 * Versions revisions releases:: Terminology used in this manual
3306 * Assigning revisions:: Assigning revisions
3307 * Tags:: Tags--Symbolic revisions
3308 * Tagging the working directory:: The cvs tag command
3309 * Tagging by date/tag:: The cvs rtag command
3310 * Modifying tags:: Adding, renaming, and deleting tags
3311 * Tagging add/remove:: Tags with adding and removing files
3312 * Sticky tags:: Certain tags are persistent
3315 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3316 @node Revision numbers
3317 @section Revision numbers
3318 @cindex Revision numbers
3319 @cindex Revision tree
3320 @cindex Linear development
3321 @cindex Number, revision-
3322 @cindex Decimal revision number
3323 @cindex Branch number
3324 @cindex Number, branch
3326 Each version of a file has a unique @dfn{revision
3327 number}. Revision numbers look like @samp{1.1},
3328 @samp{1.2}, @samp{1.3.2.2} or even @samp{1.3.2.2.4.5}.
3329 A revision number always has an even number of
3330 period-separated decimal integers. By default revision
3331 1.1 is the first revision of a file. Each successive
3332 revision is given a new number by increasing the
3333 rightmost number by one. The following figure displays
3334 a few revisions, with newer revisions to the right.
3337 +-----+ +-----+ +-----+ +-----+ +-----+
3338 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
3339 +-----+ +-----+ +-----+ +-----+ +-----+
3342 It is also possible to end up with numbers containing
3343 more than one period, for example @samp{1.3.2.2}. Such
3344 revisions represent revisions on branches
3345 (@pxref{Branching and merging}); such revision numbers
3346 are explained in detail in @ref{Branches and
3349 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3350 @node Versions revisions releases
3351 @section Versions, revisions and releases
3352 @cindex Revisions, versions and releases
3353 @cindex Versions, revisions and releases
3354 @cindex Releases, revisions and versions
3356 A file can have several versions, as described above.
3357 Likewise, a software product can have several versions.
3358 A software product is often given a version number such
3361 Versions in the first sense are called @dfn{revisions}
3362 in this document, and versions in the second sense are
3363 called @dfn{releases}. To avoid confusion, the word
3364 @dfn{version} is almost never used in this document.
3366 @node Assigning revisions
3367 @section Assigning revisions
3369 @c We avoid the "major revision" terminology. It seems
3370 @c like jargon. Hopefully "first number" is clear enough.
3371 By default, @sc{cvs} will assign numeric revisions by
3372 leaving the first number the same and incrementing the
3373 second number. For example, @code{1.1}, @code{1.2},
3376 When adding a new file, the second number will always
3377 be one and the first number will equal the highest
3378 first number of any file in that directory. For
3379 example, the current directory contains files whose
3380 highest numbered revisions are @code{1.7}, @code{3.1},
3381 and @code{4.12}, then an added file will be given the
3382 numeric revision @code{4.1}.
3383 (When using client/server @sc{cvs},
3384 only files that are actually sent to the server are considered.)
3386 @c This is sort of redundant with something we said a
3387 @c while ago. Somewhere we need a better way of
3388 @c introducing how the first number can be anything
3389 @c except "1", perhaps. Also I don't think this
3390 @c presentation is clear on why we are discussing releases
3391 @c and first numbers of numeric revisions in the same
3393 Normally there is no reason to care
3394 about the revision numbers---it is easier to treat them
3395 as internal numbers that @sc{cvs} maintains, and tags
3396 provide a better way to distinguish between things like
3397 release 1 versus release 2 of your product
3398 (@pxref{Tags}). However, if you want to set the
3399 numeric revisions, the @samp{-r} option to @code{cvs
3400 commit} can do that. The @samp{-r} option implies the
3401 @samp{-f} option, in the sense that it causes the
3402 files to be committed even if they are not modified.
3404 For example, to bring all your files up to
3405 revision 3.0 (including those that haven't changed),
3412 Note that the number you specify with @samp{-r} must be
3413 larger than any existing revision number. That is, if
3414 revision 3.0 exists, you cannot @samp{cvs commit
3415 -r 1.3}. If you want to maintain several releases in
3416 parallel, you need to use a branch (@pxref{Branching and merging}).
3418 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3420 @section Tags--Symbolic revisions
3423 The revision numbers live a life of their own. They
3424 need not have anything at all to do with the release
3425 numbers of your software product. Depending
3426 on how you use @sc{cvs} the revision numbers might change several times
3427 between two releases. As an example, some of the
3428 source files that make up @sc{rcs} 5.6 have the following
3430 @cindex RCS revision numbers
3447 @cindex tag, command, introduction
3448 @cindex Tag, symbolic name
3449 @cindex Symbolic name (tag)
3450 @cindex Name, symbolic (tag)
3451 @cindex HEAD, as reserved tag name
3452 @cindex BASE, as reserved tag name
3453 You can use the @code{tag} command to give a symbolic name to a
3454 certain revision of a file. You can use the @samp{-v} flag to the
3455 @code{status} command to see all tags that a file has, and
3456 which revision numbers they represent. Tag names must
3457 start with an uppercase or lowercase letter and can
3458 contain uppercase and lowercase letters, digits,
3459 @samp{-}, and @samp{_}. The two tag names @code{BASE}
3460 and @code{HEAD} are reserved for use by @sc{cvs}. It
3461 is expected that future names which are special to
3462 @sc{cvs} will be specially named, for example by
3463 starting with @samp{.}, rather than being named analogously to
3464 @code{BASE} and @code{HEAD}, to avoid conflicts with
3466 @c Including a character such as % or = has also been
3467 @c suggested as the naming convention for future
3468 @c special tag names. Starting with . is nice because
3469 @c that is not a legal tag name as far as RCS is concerned.
3470 @c FIXME: CVS actually accepts quite a few characters
3471 @c in tag names, not just the ones documented above
3472 @c (see RCS_check_tag). RCS
3473 @c defines legitimate tag names by listing illegal
3474 @c characters rather than legal ones. CVS is said to lose its
3475 @c mind if you try to use "/" (try making such a tag sticky
3476 @c and using "cvs status" client/server--see remote
3477 @c protocol format for entries line for probable cause).
3478 @c TODO: The testsuite
3479 @c should test for whatever are documented above as
3480 @c officially-OK tag names, and CVS should at least reject
3481 @c characters that won't work, like "/".
3483 You'll want to choose some convention for naming tags,
3484 based on information such as the name of the program
3485 and the version number of the release. For example,
3486 one might take the name of the program, immediately
3487 followed by the version number with @samp{.} changed to
3488 @samp{-}, so that @sc{cvs} 1.9 would be tagged with the name
3489 @code{cvs1-9}. If you choose a consistent convention,
3490 then you won't constantly be guessing whether a tag is
3491 @code{cvs-1-9} or @code{cvs1_9} or what. You might
3492 even want to consider enforcing your convention in the
3493 @file{taginfo} file (@pxref{taginfo}).
3494 @c Might be nice to say more about using taginfo this
3495 @c way, like giving an example, or pointing out any particular
3496 @c issues which arise.
3498 @cindex Adding a tag
3499 @cindex Tag, example
3500 The following example shows how you can add a tag to a
3501 file. The commands must be issued inside your working
3502 directory. That is, you should issue the
3503 command in the directory where @file{backend.c}
3507 $ cvs tag rel-0-4 backend.c
3509 $ cvs status -v backend.c
3510 ===================================================================
3511 File: backend.c Status: Up-to-date
3513 Version: 1.4 Tue Dec 1 14:39:01 1992
3514 RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v
3517 Sticky Options: (none)
3520 rel-0-4 (revision: 1.4)
3524 For a complete summary of the syntax of @code{cvs tag},
3525 including the various options, see @ref{Invoking CVS}.
3527 There is seldom reason to tag a file in isolation. A more common use is
3528 to tag all the files that constitute a module with the same tag at
3529 strategic points in the development life-cycle, such as when a release
3543 (When you give @sc{cvs} a directory as argument, it generally applies the
3544 operation to all the files in that directory, and (recursively), to any
3545 subdirectories that it may contain. @xref{Recursive behavior}.)
3547 @cindex Retrieving an old revision using tags
3548 @cindex Tag, retrieving old revisions
3549 The @code{checkout} command has a flag, @samp{-r}, that lets you check out
3550 a certain revision of a module. This flag makes it easy to
3551 retrieve the sources that make up release 1.0 of the module @samp{tc} at
3552 any time in the future:
3555 $ cvs checkout -r rel-1-0 tc
3559 This is useful, for instance, if someone claims that there is a bug in
3560 that release, but you cannot find the bug in the current working copy.
3562 You can also check out a module as it was at any given date.
3563 @xref{checkout options}. When specifying @samp{-r} to
3564 any of these commands, you will need beware of sticky
3565 tags; see @ref{Sticky tags}.
3567 When you tag more than one file with the same tag you
3568 can think about the tag as "a curve drawn through a
3569 matrix of filename vs.@: revision number." Say we have 5
3570 files with the following revisions:
3574 file1 file2 file3 file4 file5
3576 1.1 1.1 1.1 1.1 /--1.1* <-*- TAG
3577 1.2*- 1.2 1.2 -1.2*-
3578 1.3 \- 1.3*- 1.3 / 1.3
3585 At some time in the past, the @code{*} versions were tagged.
3586 You can think of the tag as a handle attached to the curve
3587 drawn through the tagged revisions. When you pull on
3588 the handle, you get all the tagged revisions. Another
3589 way to look at it is that you "sight" through a set of
3590 revisions that is "flat" along the tagged revisions,
3595 file1 file2 file3 file4 file5
3601 1.2*----1.3*----1.5*----1.2*----1.1 (--- <--- Look here
3608 @node Tagging the working directory
3609 @section Specifying what to tag from the working directory
3611 @cindex tag (subcommand)
3612 The example in the previous section demonstrates one of
3613 the most common ways to choose which revisions to tag.
3614 Namely, running the @code{cvs tag} command without
3615 arguments causes @sc{cvs} to select the revisions which
3616 are checked out in the current working directory. For
3617 example, if the copy of @file{backend.c} in working
3618 directory was checked out from revision 1.4, then
3619 @sc{cvs} will tag revision 1.4. Note that the tag is
3620 applied immediately to revision 1.4 in the repository;
3621 tagging is not like modifying a file, or other
3622 operations in which one first modifies the working
3623 directory and then runs @code{cvs commit} to transfer
3624 that modification to the repository.
3626 One potentially surprising aspect of the fact that
3627 @code{cvs tag} operates on the repository is that you
3628 are tagging the checked-in revisions, which may differ
3629 from locally modified files in your working directory.
3630 If you want to avoid doing this by mistake, specify the
3631 @samp{-c} option to @code{cvs tag}. If there are any
3632 locally modified files, @sc{cvs} will abort with an
3633 error before it tags any files:
3636 $ cvs tag -c rel-0-4
3637 cvs tag: backend.c is locally modified
3638 cvs [tag aborted]: correct the above errors first!
3641 @node Tagging by date/tag
3642 @section Specifying what to tag by date or revision
3643 @cindex rtag (subcommand)
3645 The @code{cvs rtag} command tags the repository as of a
3646 certain date or time (or can be used to tag the latest
3647 revision). @code{rtag} works directly on the
3648 repository contents (it requires no prior checkout and
3649 does not look for a working directory).
3651 The following options specify which date or revision to
3652 tag. See @ref{Common options}, for a complete
3653 description of them.
3657 Tag the most recent revision no later than @var{date}.
3660 Only useful with the @samp{-D @var{date}} or @samp{-r @var{tag}}
3661 flags. If no matching revision is found, use the most
3662 recent revision (instead of ignoring the file).
3665 Only tag those files that contain existing tag @var{tag}.
3668 The @code{cvs tag} command also allows one to specify
3669 files by revision or date, using the same @samp{-r},
3670 @samp{-D}, and @samp{-f} options. However, this
3671 feature is probably not what you want. The reason is
3672 that @code{cvs tag} chooses which files to tag based on
3673 the files that exist in the working directory, rather
3674 than the files which existed as of the given tag/date.
3675 Therefore, you are generally better off using @code{cvs
3676 rtag}. The exceptions might be cases like:
3679 cvs tag -r 1.4 backend.c
3682 @node Modifying tags
3683 @section Deleting, moving, and renaming tags
3686 @c "How do I move or rename a magic branch tag?"
3687 @c in the FAQ (I think the issues it talks about still
3688 @c apply, but this could use some sanity.sh work).
3690 Normally one does not modify tags. They exist in order
3691 to record the history of the repository and so deleting
3692 them or changing their meaning would, generally, not be
3695 However, there might be cases in which one uses a tag
3696 temporarily or accidentally puts one in the wrong
3697 place. Therefore, one might delete, move, or rename a
3701 @strong{WARNING: The commands in this section are
3702 dangerous; they permanently discard historical
3703 information and it can be difficult or impossible to
3704 recover from errors. If you are a @sc{cvs}
3705 administrator, you may consider restricting these
3706 commands with the @file{taginfo} file (@pxref{taginfo}).}
3708 @cindex Deleting tags
3709 @cindex Deleting branch tags
3710 @cindex Removing tags
3711 @cindex Removing branch tags
3712 @cindex Tags, deleting
3713 @cindex Branch tags, deleting
3714 To delete a tag, specify the @samp{-d} option to either
3715 @code{cvs tag} or @code{cvs rtag}. For example:
3718 cvs rtag -d rel-0-4 tc
3722 deletes the non-branch tag @code{rel-0-4} from the module @code{tc}.
3723 In the event that branch tags are encountered within the repository
3724 with the given name, a warning message will be issued and the branch
3725 tag will not be deleted. If you are absolutely certain you know what
3726 you are doing, the @code{-B} option may be specified to allow deletion
3727 of branch tags. In that case, any non-branch tags encountered will
3728 trigger warnings and will not be deleted.
3731 @strong{WARNING: Moving branch tags is very dangerous! If you think
3732 you need the @code{-B} option, think again and ask your @sc{cvs}
3733 administrator about it (if that isn't you). There is almost certainly
3734 another way to accomplish what you want to accomplish.}
3737 @cindex Moving branch tags
3738 @cindex Tags, moving
3739 @cindex Branch tags, moving
3740 When we say @dfn{move} a tag, we mean to make the same
3741 name point to different revisions. For example, the
3742 @code{stable} tag may currently point to revision 1.4
3743 of @file{backend.c} and perhaps we want to make it
3744 point to revision 1.6. To move a non-branch tag, specify the
3745 @samp{-F} option to either @code{cvs tag} or @code{cvs
3746 rtag}. For example, the task just mentioned might be
3750 cvs tag -r 1.6 -F stable backend.c
3754 If any branch tags are encountered in the repository
3755 with the given name, a warning is issued and the branch
3756 tag is not disturbed. If you are absolutely certain you
3757 wish to move the branch tag, the @code{-B} option may be specified.
3758 In that case, non-branch tags encountered with the given
3759 name are ignored with a warning message.
3762 @strong{WARNING: Moving branch tags is very dangerous! If you think you
3763 need the @code{-B} option, think again and ask your @sc{cvs}
3764 administrator about it (if that isn't you). There is almost certainly
3765 another way to accomplish what you want to accomplish.}
3767 @cindex Renaming tags
3768 @cindex Tags, renaming
3769 When we say @dfn{rename} a tag, we mean to make a
3770 different name point to the same revisions as the old
3771 tag. For example, one may have misspelled the tag name
3772 and want to correct it (hopefully before others are
3773 relying on the old spelling). To rename a tag, first
3774 create a new tag using the @samp{-r} option to
3775 @code{cvs rtag}, and then delete the old name. (Caution:
3776 this method will not work with branch tags.)
3777 This leaves the new tag on exactly the
3778 same files as the old tag. For example:
3781 cvs rtag -r old-name-0-4 rel-0-4 tc
3782 cvs rtag -d old-name-0-4 tc
3785 @node Tagging add/remove
3786 @section Tagging and adding and removing files
3788 The subject of exactly how tagging interacts with
3789 adding and removing files is somewhat obscure; for the
3790 most part @sc{cvs} will keep track of whether files
3791 exist or not without too much fussing. By default,
3792 tags are applied to only files which have a revision
3793 corresponding to what is being tagged. Files which did
3794 not exist yet, or which were already removed, simply
3795 omit the tag, and @sc{cvs} knows to treat the absence
3796 of a tag as meaning that the file didn't exist as of
3799 However, this can lose a small amount of information.
3800 For example, suppose a file was added and then removed.
3801 Then, if the tag is missing for that file, there is no
3802 way to know whether the tag refers to the time before
3803 the file was added, or the time after it was removed.
3804 If you specify the @samp{-r} option to @code{cvs rtag},
3805 then @sc{cvs} tags the files which have been removed,
3806 and thereby avoids this problem. For example, one
3807 might specify @code{-r HEAD} to tag the head.
3809 On the subject of adding and removing files, the
3810 @code{cvs rtag} command has a @samp{-a} option which
3811 means to clear the tag from removed files that would
3812 not otherwise be tagged. For example, one might
3813 specify this option in conjunction with @samp{-F} when
3814 moving a tag. If one moved a tag without @samp{-a},
3815 then the tag in the removed files might still refer to
3816 the old revision, rather than reflecting the fact that
3817 the file had been removed. I don't think this is
3818 necessary if @samp{-r} is specified, as noted above.
3820 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3822 @section Sticky tags
3824 @cindex Tags, sticky
3826 @c A somewhat related issue is per-directory sticky
3827 @c tags (see comment at CVS/Tag in node Working
3828 @c directory storage); we probably want to say
3829 @c something like "you can set a sticky tag for only
3830 @c some files, but you don't want to" or some such.
3832 Sometimes a working copy's revision has extra data
3833 associated with it, for example it might be on a branch
3834 (@pxref{Branching and merging}), or restricted to
3835 versions prior to a certain date by @samp{checkout -D}
3836 or @samp{update -D}. Because this data persists --
3837 that is, it applies to subsequent commands in the
3838 working copy -- we refer to it as @dfn{sticky}.
3840 Most of the time, stickiness is an obscure aspect of
3841 @sc{cvs} that you don't need to think about. However,
3842 even if you don't want to use the feature, you may need
3843 to know @emph{something} about sticky tags (for
3844 example, how to avoid them!).
3846 You can use the @code{status} command to see if any
3847 sticky tags or dates are set:
3850 $ cvs status driver.c
3851 ===================================================================
3852 File: driver.c Status: Up-to-date
3854 Version: 1.7.2.1 Sat Dec 5 19:35:03 1992
3855 RCS Version: 1.7.2.1 /u/cvsroot/yoyodyne/tc/driver.c,v
3856 Sticky Tag: rel-1-0-patches (branch: 1.7.2)
3858 Sticky Options: (none)
3862 @cindex Resetting sticky tags
3863 @cindex Sticky tags, resetting
3864 @cindex Deleting sticky tags
3865 The sticky tags will remain on your working files until
3866 you delete them with @samp{cvs update -A}. The
3867 @samp{-A} option merges local changes into the version of the
3868 file from the head of the trunk, removing any sticky tags,
3869 dates, or options (other than sticky @samp{-k} options on locally
3870 modified files). See @ref{update} for more on the operation
3871 of @code{cvs update}.
3874 The most common use of sticky tags is to identify which
3875 branch one is working on, as described in
3876 @ref{Accessing branches}. However, non-branch
3877 sticky tags have uses as well. For example,
3878 suppose that you want to avoid updating your working
3879 directory, to isolate yourself from possibly
3880 destabilizing changes other people are making. You
3881 can, of course, just refrain from running @code{cvs
3882 update}. But if you want to avoid updating only a
3883 portion of a larger tree, then sticky tags can help.
3884 If you check out a certain revision (such as 1.4) it
3885 will become sticky. Subsequent @code{cvs update}
3887 not retrieve the latest revision until you reset the
3888 tag with @code{cvs update -A}. Likewise, use of the
3889 @samp{-D} option to @code{update} or @code{checkout}
3890 sets a @dfn{sticky date}, which, similarly, causes that
3891 date to be used for future retrievals.
3893 People often want to retrieve an old version of
3894 a file without setting a sticky tag. This can
3895 be done with the @samp{-p} option to @code{checkout} or
3896 @code{update}, which sends the contents of the file to
3897 standard output. For example:
3899 $ cvs update -p -r 1.1 file1 >file1
3900 ===================================================================
3902 RCS: /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v
3908 However, this isn't the easiest way, if you are asking
3909 how to undo a previous checkin (in this example, put
3910 @file{file1} back to the way it was as of revision
3911 1.1). In that case you are better off using the
3912 @samp{-j} option to @code{update}; for further
3913 discussion see @ref{Merging two revisions}.
3915 @c ---------------------------------------------------------------------
3916 @node Branching and merging
3917 @chapter Branching and merging
3920 @cindex Copying changes
3921 @cindex Main trunk and branches
3922 @cindex Revision tree, making branches
3923 @cindex Branches, copying changes between
3924 @cindex Changes, copying between branches
3925 @cindex Modifications, copying between branches
3927 @sc{cvs} allows you to isolate changes onto a separate
3928 line of development, known as a @dfn{branch}. When you
3929 change files on a branch, those changes do not appear
3930 on the main trunk or other branches.
3932 Later you can move changes from one branch to another
3933 branch (or the main trunk) by @dfn{merging}. Merging
3934 involves first running @code{cvs update -j}, to merge
3935 the changes into the working directory.
3936 You can then commit that revision, and thus effectively
3937 copy the changes onto another branch.
3940 * Branches motivation:: What branches are good for
3941 * Creating a branch:: Creating a branch
3942 * Accessing branches:: Checking out and updating branches
3943 * Branches and revisions:: Branches are reflected in revision numbers
3944 * Magic branch numbers:: Magic branch numbers
3945 * Merging a branch:: Merging an entire branch
3946 * Merging more than once:: Merging from a branch several times
3947 * Merging two revisions:: Merging differences between two revisions
3948 * Merging adds and removals:: What if files are added or removed?
3949 * Merging and keywords:: Avoiding conflicts due to keyword substitution
3952 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3953 @node Branches motivation
3954 @section What branches are good for
3955 @cindex Branches motivation
3956 @cindex What branches are good for
3957 @cindex Motivation for branches
3959 @c FIXME: this node mentions one way to use branches,
3960 @c but it is by no means the only way. For example,
3961 @c the technique of committing a new feature on a branch,
3962 @c until it is ready for the main trunk. The whole
3963 @c thing is generally speaking more akin to the
3964 @c "Revision management" node although it isn't clear to
3965 @c me whether policy matters should be centralized or
3966 @c distributed throughout the relevant sections.
3967 Suppose that release 1.0 of tc has been made. You are continuing to
3968 develop tc, planning to create release 1.1 in a couple of months. After a
3969 while your customers start to complain about a fatal bug. You check
3970 out release 1.0 (@pxref{Tags}) and find the bug
3971 (which turns out to have a trivial fix). However, the current revision
3972 of the sources are in a state of flux and are not expected to be stable
3973 for at least another month. There is no way to make a
3974 bug fix release based on the newest sources.
3976 The thing to do in a situation like this is to create a @dfn{branch} on
3977 the revision trees for all the files that make up
3978 release 1.0 of tc. You can then make
3979 modifications to the branch without disturbing the main trunk. When the
3980 modifications are finished you can elect to either incorporate them on
3981 the main trunk, or leave them on the branch.
3983 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3984 @node Creating a branch
3985 @section Creating a branch
3986 @cindex Creating a branch
3987 @cindex Branch, creating a
3988 @cindex tag, creating a branch using
3989 @cindex rtag, creating a branch using
3991 You can create a branch with @code{tag -b}; for
3992 example, assuming you're in a working copy:
3995 $ cvs tag -b rel-1-0-patches
3998 @c FIXME: we should be more explicit about the value of
3999 @c having a tag on the branchpoint. For example
4000 @c "cvs tag rel-1-0-patches-branchpoint" before
4001 @c the "cvs tag -b". This points out that
4002 @c rel-1-0-patches is a pretty awkward name for
4003 @c this example (more so than for the rtag example
4006 This splits off a branch based on the current revisions
4007 in the working copy, assigning that branch the name
4008 @samp{rel-1-0-patches}.
4010 It is important to understand that branches get created
4011 in the repository, not in the working copy. Creating a
4012 branch based on current revisions, as the above example
4013 does, will @emph{not} automatically switch the working
4014 copy to be on the new branch. For information on how
4015 to do that, see @ref{Accessing branches}.
4017 You can also create a branch without reference to any
4018 working copy, by using @code{rtag}:
4021 $ cvs rtag -b -r rel-1-0 rel-1-0-patches tc
4024 @samp{-r rel-1-0} says that this branch should be
4025 rooted at the revision that
4026 corresponds to the tag @samp{rel-1-0}. It need not
4027 be the most recent revision -- it's often useful to
4028 split a branch off an old revision (for example, when
4029 fixing a bug in a past release otherwise known to be
4032 As with @samp{tag}, the @samp{-b} flag tells
4033 @code{rtag} to create a branch (rather than just a
4034 symbolic revision name). Note that the numeric
4035 revision number that matches @samp{rel-1-0} will
4036 probably be different from file to file.
4038 So, the full effect of the command is to create a new
4039 branch -- named @samp{rel-1-0-patches} -- in module
4040 @samp{tc}, rooted in the revision tree at the point tagged
4043 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4044 @node Accessing branches
4045 @section Accessing branches
4046 @cindex Check out a branch
4047 @cindex Retrieve a branch
4048 @cindex Access a branch
4049 @cindex Identifying a branch
4050 @cindex Branch, check out
4051 @cindex Branch, retrieving
4052 @cindex Branch, accessing
4053 @cindex Branch, identifying
4055 You can retrieve a branch in one of two ways: by
4056 checking it out fresh from the repository, or by
4057 switching an existing working copy over to the branch.
4059 To check out a branch from the repository, invoke
4060 @samp{checkout} with the @samp{-r} flag, followed by
4061 the tag name of the branch (@pxref{Creating a branch}):
4064 $ cvs checkout -r rel-1-0-patches tc
4067 Or, if you already have a working copy, you can switch
4068 it to a given branch with @samp{update -r}:
4071 $ cvs update -r rel-1-0-patches tc
4079 $ cvs update -r rel-1-0-patches
4082 It does not matter if the working copy was originally
4083 on the main trunk or on some other branch -- the above
4084 command will switch it to the named branch. And
4085 similarly to a regular @samp{update} command,
4086 @samp{update -r} merges any changes you have made,
4087 notifying you of conflicts where they occur.
4089 Once you have a working copy tied to a particular
4090 branch, it remains there until you tell it otherwise.
4091 This means that changes checked in from the working
4092 copy will add new revisions on that branch, while
4093 leaving the main trunk and other branches unaffected.
4095 @cindex Branches, sticky
4096 To find out what branch a working copy is on, you can
4097 use the @samp{status} command. In its output, look for
4098 the field named @samp{Sticky tag} (@pxref{Sticky tags})
4099 -- that's @sc{cvs}'s way of telling you the branch, if
4100 any, of the current working files:
4103 $ cvs status -v driver.c backend.c
4104 ===================================================================
4105 File: driver.c Status: Up-to-date
4107 Version: 1.7 Sat Dec 5 18:25:54 1992
4108 RCS Version: 1.7 /u/cvsroot/yoyodyne/tc/driver.c,v
4109 Sticky Tag: rel-1-0-patches (branch: 1.7.2)
4111 Sticky Options: (none)
4114 rel-1-0-patches (branch: 1.7.2)
4115 rel-1-0 (revision: 1.7)
4117 ===================================================================
4118 File: backend.c Status: Up-to-date
4120 Version: 1.4 Tue Dec 1 14:39:01 1992
4121 RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v
4122 Sticky Tag: rel-1-0-patches (branch: 1.4.2)
4124 Sticky Options: (none)
4127 rel-1-0-patches (branch: 1.4.2)
4128 rel-1-0 (revision: 1.4)
4129 rel-0-4 (revision: 1.4)
4133 Don't be confused by the fact that the branch numbers
4134 for each file are different (@samp{1.7.2} and
4135 @samp{1.4.2} respectively). The branch tag is the
4136 same, @samp{rel-1-0-patches}, and the files are
4137 indeed on the same branch. The numbers simply reflect
4138 the point in each file's revision history at which the
4139 branch was made. In the above example, one can deduce
4140 that @samp{driver.c} had been through more changes than
4141 @samp{backend.c} before this branch was created.
4143 See @ref{Branches and revisions} for details about how
4144 branch numbers are constructed.
4146 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4147 @node Branches and revisions
4148 @section Branches and revisions
4149 @cindex Branch number
4150 @cindex Number, branch
4151 @cindex Revision numbers (branches)
4153 Ordinarily, a file's revision history is a linear
4154 series of increments (@pxref{Revision numbers}):
4157 +-----+ +-----+ +-----+ +-----+ +-----+
4158 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
4159 +-----+ +-----+ +-----+ +-----+ +-----+
4162 However, @sc{cvs} is not limited to linear development. The
4163 @dfn{revision tree} can be split into @dfn{branches},
4164 where each branch is a self-maintained line of
4165 development. Changes made on one branch can easily be
4166 moved back to the main trunk.
4168 Each branch has a @dfn{branch number}, consisting of an
4169 odd number of period-separated decimal integers. The
4170 branch number is created by appending an integer to the
4171 revision number where the corresponding branch forked
4172 off. Having branch numbers allows more than one branch
4173 to be forked off from a certain revision.
4176 All revisions on a branch have revision numbers formed
4177 by appending an ordinal number to the branch number.
4178 The following figure illustrates branching with an
4182 @c This example used to have a 1.2.2.4 revision, which
4183 @c might help clarify that development can continue on
4184 @c 1.2.2. Might be worth reinstating if it can be done
4185 @c without overfull hboxes.
4188 Branch 1.2.2.3.2 -> ! 1.2.2.3.2.1 !
4192 +---------+ +---------+ +---------+
4193 Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
4194 / +---------+ +---------+ +---------+
4197 +-----+ +-----+ +-----+ +-----+ +-----+
4198 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
4199 +-----+ +-----+ +-----+ +-----+ +-----+
4202 ! +---------+ +---------+ +---------+
4203 Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 !
4204 +---------+ +---------+ +---------+
4209 @c -- However, at least for me the figure is not enough. I suggest more
4210 @c -- text to accompany it. "A picture is worth a thousand words", so you
4211 @c -- have to make sure the reader notices the couple of hundred words
4212 @c -- *you* had in mind more than the others!
4214 @c -- Why an even number of segments? This section implies that this is
4215 @c -- how the main trunk is distinguished from branch roots, but you never
4216 @c -- explicitly say that this is the purpose of the [by itself rather
4217 @c -- surprising] restriction to an even number of segments.
4219 The exact details of how the branch number is
4220 constructed is not something you normally need to be
4221 concerned about, but here is how it works: When
4222 @sc{cvs} creates a branch number it picks the first
4223 unused even integer, starting with 2. So when you want
4224 to create a branch from revision 6.4 it will be
4225 numbered 6.4.2. All branch numbers ending in a zero
4226 (such as 6.4.0) are used internally by @sc{cvs}
4227 (@pxref{Magic branch numbers}). The branch 1.1.1 has a
4228 special meaning. @xref{Tracking sources}.
4230 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4231 @node Magic branch numbers
4232 @section Magic branch numbers
4234 @c Want xref to here from "log"?
4236 This section describes a @sc{cvs} feature called
4237 @dfn{magic branches}. For most purposes, you need not
4238 worry about magic branches; @sc{cvs} handles them for
4239 you. However, they are visible to you in certain
4240 circumstances, so it may be useful to have some idea of
4243 Externally, branch numbers consist of an odd number of
4244 dot-separated decimal integers. @xref{Revision
4245 numbers}. That is not the whole truth, however. For
4246 efficiency reasons @sc{cvs} sometimes inserts an extra 0
4247 in the second rightmost position (1.2.4 becomes
4248 1.2.0.4, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so
4251 @sc{cvs} does a pretty good job at hiding these so
4252 called magic branches, but in a few places the hiding
4257 @c This is in ignore as I'm taking their word for it,
4258 @c that this was fixed
4259 @c a long time ago. But before deleting this
4260 @c entirely, I'd rather verify it (and add a test
4261 @c case to the testsuite).
4263 The magic branch can appear in the output from
4264 @code{cvs status} in vanilla @sc{cvs} 1.3. This is
4265 fixed in @sc{cvs} 1.3-s2.
4269 The magic branch number appears in the output from
4271 @c What output should appear instead?
4274 You cannot specify a symbolic branch name to @code{cvs
4279 @c Can CVS do this automatically the first time
4280 @c you check something in to that branch? Should
4282 You can use the @code{admin} command to reassign a
4283 symbolic name to a branch the way @sc{rcs} expects it
4284 to be. If @code{R4patches} is assigned to the branch
4285 1.4.2 (magic branch number 1.4.0.2) in file
4286 @file{numbers.c} you can do this:
4289 $ cvs admin -NR4patches:1.4.2 numbers.c
4292 It only works if at least one revision is already
4293 committed on the branch. Be very careful so that you
4294 do not assign the tag to the wrong number. (There is
4295 no way to see how the tag was assigned yesterday).
4297 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4298 @node Merging a branch
4299 @section Merging an entire branch
4300 @cindex Merging a branch
4301 @cindex -j (merging branches)
4303 You can merge changes made on a branch into your working copy by giving
4304 the @samp{-j @var{branchname}} flag to the @code{update} subcommand. With one
4305 @samp{-j @var{branchname}} option it merges the changes made between the
4306 greatest common ancestor (GCA) of the branch and the destination revision (in
4307 the simple case below the GCA is the point where the branch forked) and the
4308 newest revision on that branch into your working copy.
4311 The @samp{-j} stands for ``join''.
4313 @cindex Branch merge example
4314 @cindex Example, branch merge
4315 @cindex Merge, branch example
4316 Consider this revision tree:
4319 +-----+ +-----+ +-----+ +-----+
4320 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 ! <- The main trunk
4321 +-----+ +-----+ +-----+ +-----+
4324 ! +---------+ +---------+
4325 Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
4326 +---------+ +---------+
4330 The branch 1.2.2 has been given the tag (symbolic name) @samp{R1fix}. The
4331 following example assumes that the module @samp{mod} contains only one
4335 $ cvs checkout mod # @r{Retrieve the latest revision, 1.4}
4337 $ cvs update -j R1fix m.c # @r{Merge all changes made on the branch,}
4338 # @r{i.e. the changes between revision 1.2}
4339 # @r{and 1.2.2.2, into your working copy}
4342 $ cvs commit -m "Included R1fix" # @r{Create revision 1.5.}
4345 A conflict can result from a merge operation. If that
4346 happens, you should resolve it before committing the
4347 new revision. @xref{Conflicts example}.
4349 If your source files contain keywords (@pxref{Keyword substitution}),
4350 you might be getting more conflicts than strictly necessary. See
4351 @ref{Merging and keywords}, for information on how to avoid this.
4353 The @code{checkout} command also supports the @samp{-j @var{branchname}} flag. The
4354 same effect as above could be achieved with this:
4357 $ cvs checkout -j R1fix mod
4358 $ cvs commit -m "Included R1fix"
4361 It should be noted that @code{update -j @var{tagname}} will also work but may
4362 not produce the desired result. @xref{Merging adds and removals}, for more.
4364 @node Merging more than once
4365 @section Merging from a branch several times
4367 Continuing our example, the revision tree now looks
4371 +-----+ +-----+ +-----+ +-----+ +-----+
4372 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
4373 +-----+ +-----+ +-----+ +-----+ +-----+
4376 ! +---------+ +---------+
4377 Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
4378 +---------+ +---------+
4382 where the starred line represents the merge from the
4383 @samp{R1fix} branch to the main trunk, as just
4386 Now suppose that development continues on the
4387 @samp{R1fix} branch:
4390 +-----+ +-----+ +-----+ +-----+ +-----+
4391 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
4392 +-----+ +-----+ +-----+ +-----+ +-----+
4395 ! +---------+ +---------+ +---------+
4396 Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
4397 +---------+ +---------+ +---------+
4401 and then you want to merge those new changes onto the
4402 main trunk. If you just use the @code{cvs update -j
4403 R1fix m.c} command again, @sc{cvs} will attempt to
4404 merge again the changes which you have already merged,
4405 which can have undesirable side effects.
4407 So instead you need to specify that you only want to
4408 merge the changes on the branch which have not yet been
4409 merged into the trunk. To do that you specify two
4410 @samp{-j} options, and @sc{cvs} merges the changes from
4411 the first revision to the second revision. For
4412 example, in this case the simplest way would be
4415 cvs update -j 1.2.2.2 -j R1fix m.c # @r{Merge changes from 1.2.2.2 to the}
4416 # @r{head of the R1fix branch}
4419 The problem with this is that you need to specify the
4420 1.2.2.2 revision manually. A slightly better approach
4421 might be to use the date the last merge was done:
4424 cvs update -j R1fix:yesterday -j R1fix m.c
4427 Better yet, tag the R1fix branch after every merge into
4428 the trunk, and then use that tag for subsequent merges:
4431 cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c
4434 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4435 @node Merging two revisions
4436 @section Merging differences between any two revisions
4437 @cindex Merging two revisions
4438 @cindex Revisions, merging differences between
4439 @cindex Differences, merging
4441 With two @samp{-j @var{revision}} flags, the @code{update}
4442 (and @code{checkout}) command can merge the differences
4443 between any two revisions into your working file.
4445 @cindex Undoing a change
4446 @cindex Removing a change
4448 $ cvs update -j 1.5 -j 1.3 backend.c
4452 will undo all changes made between revision
4453 1.3 and 1.5. Note the order of the revisions!
4455 If you try to use this option when operating on
4456 multiple files, remember that the numeric revisions will
4457 probably be very different between the various files.
4458 You almost always use symbolic
4459 tags rather than revision numbers when operating on
4462 @cindex Restoring old version of removed file
4463 @cindex Resurrecting old version of dead file
4464 Specifying two @samp{-j} options can also undo file
4465 removals or additions. For example, suppose you have
4467 named @file{file1} which existed as revision 1.1, and
4468 you then removed it (thus adding a dead revision 1.2).
4469 Now suppose you want to add it again, with the same
4470 contents it had previously. Here is how to do it:
4473 $ cvs update -j 1.2 -j 1.1 file1
4475 $ cvs commit -m test
4477 /tmp/cvs-sanity/cvsroot/first-dir/file1,v <-- file1
4478 new revision: 1.3; previous revision: 1.2
4483 @node Merging adds and removals
4484 @section Merging can add or remove files
4486 If the changes which you are merging involve removing
4487 or adding some files, @code{update -j} will reflect
4488 such additions or removals.
4490 @c FIXME: This example needs a lot more explanation.
4491 @c We also need other examples for some of the other
4492 @c cases (not all--there are too many--as long as we present a
4493 @c coherent general principle).
4498 cvs add a b c ; cvs ci -m "added" a b c
4499 cvs tag -b branchtag
4500 cvs update -r branchtag
4503 cvs ci -m "added d, removed a"
4505 cvs update -jbranchtag
4508 After these commands are executed and a @samp{cvs commit} is done,
4509 file @file{a} will be removed and file @file{d} added in the main branch.
4510 @c (which was determined by trying it)
4512 Note that using a single static tag (@samp{-j @var{tagname}})
4513 rather than a dynamic tag (@samp{-j @var{branchname}}) to merge
4514 changes from a branch will usually not remove files which were removed on the
4515 branch since @sc{cvs} does not automatically add static tags to dead revisions.
4516 The exception to this rule occurs when
4517 a static tag has been attached to a dead revision manually. Use the branch tag
4518 to merge all changes from the branch or use two static tags as merge endpoints
4519 to be sure that all intended changes are propagated in the merge.
4521 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4522 @node Merging and keywords
4523 @section Merging and keywords
4524 @cindex Merging, and keyword substitution
4525 @cindex Keyword substitution, and merging
4526 @cindex -j (merging branches), and keyword substitution
4527 @cindex -kk, to avoid conflicts during a merge
4529 If you merge files containing keywords (@pxref{Keyword
4530 substitution}), you will normally get numerous
4531 conflicts during the merge, because the keywords are
4532 expanded differently in the revisions which you are
4535 Therefore, you will often want to specify the
4536 @samp{-kk} (@pxref{Substitution modes}) switch to the
4537 merge command line. By substituting just the name of
4538 the keyword, not the expanded value of that keyword,
4539 this option ensures that the revisions which you are
4540 merging will be the same as each other, and avoid
4543 For example, suppose you have a file like this:
4557 and your working directory is currently on the trunk
4558 (revision 1.2). Then you might get the following
4559 results from a merge:
4563 key $@splitrcskeyword{Revision}: 1.2 $
4567 RCS file: /cvsroot/first-dir/file1,v
4568 retrieving revision 1.1
4569 retrieving revision 1.1.2.1
4570 Merging differences between 1.1 and 1.1.2.1 into file1
4571 rcsmerge: warning: conflicts during merge
4573 @asis{}<<<<<<< file1
4574 key $@splitrcskeyword{Revision}: 1.2 $
4576 key $@splitrcskeyword{Revision}: 1.1.2.1 $
4577 @asis{}>>>>>>> 1.1.2.1
4581 What happened was that the merge tried to merge the
4582 differences between 1.1 and 1.1.2.1 into your working
4583 directory. So, since the keyword changed from
4584 @code{Revision: 1.1} to @code{Revision: 1.1.2.1},
4585 @sc{cvs} tried to merge that change into your working
4586 directory, which conflicted with the fact that your
4587 working directory had contained @code{Revision: 1.2}.
4589 Here is what happens if you had used @samp{-kk}:
4593 key $@splitrcskeyword{Revision}: 1.2 $
4595 $ cvs update -kk -j br1
4597 RCS file: /cvsroot/first-dir/file1,v
4598 retrieving revision 1.1
4599 retrieving revision 1.1.2.1
4600 Merging differences between 1.1 and 1.1.2.1 into file1
4602 key $@splitrcskeyword{Revision}$
4606 What is going on here is that revision 1.1 and 1.1.2.1
4607 both expand as plain @code{Revision}, and therefore
4608 merging the changes between them into the working
4609 directory need not change anything. Therefore, there
4612 There is, however, one major caveat with using
4613 @samp{-kk} on merges. Namely, it overrides whatever
4614 keyword expansion mode @sc{cvs} would normally have
4615 used. In particular, this is a problem if the mode had
4616 been @samp{-kb} for a binary file. Therefore, if your
4617 repository contains binary files, you will need to deal
4618 with the conflicts rather than using @samp{-kk}.
4621 The following seems rather confusing, possibly buggy,
4622 and in general, in need of much more thought before it
4623 is a recommended technique. For one thing, does it
4624 apply on Windows as well as on Unix?
4626 Unchanged binary files will undergo the same keyword substitution
4627 but will not be checked in on a subsequent
4628 @code{cvs commit}. Be aware that binary files containing keyword
4629 strings which are present in or below the working directory
4630 will most likely remain corrupt until repaired, however. A simple
4631 @code{cvs update -A} is sufficient to fix these otherwise unaltered binary files
4632 if the merge is being done to the main branch but
4633 this must be done after the merge has been committed or the merge itself
4638 cvs update -Akk -jbranchtag
4644 will update the current directory from the main trunk of the
4645 repository, substituting the base keyword strings for keywords,
4646 and merge changes made on the branch @samp{branchtag} into the new
4647 work files, performing the same keyword substitution on that file set before
4648 comparing the two sets. The final @code{cvs update -A} will restore any
4649 corrupted binary files as well as resetting the sticky @samp{-kk} tags which
4650 were present on the files in and below the working directory.
4651 Unfortunately, this doesn't work as well with an arbitrary branch tag, as the
4652 @samp{-r @var{branchtag}} switch does not reset the sticky @samp{-kk}
4653 switches attached to the working files as @samp{-A} does. The workaround
4654 for this is to release the working directory after the merge has been
4655 committed and check it out again.
4658 As a result of using @samp{-kk} during the merge, each file examined by the
4659 update will have @samp{-kk} set as sticky options. Running @code{update -A}
4660 will clear the sticky options on unmodified files, but it will not clear
4661 the sticky options on modified files. To get back to the default keyword
4662 substitution for modified files, you must commit the results of the merge
4663 and then run @code{update -A}.
4665 @c ---------------------------------------------------------------------
4666 @node Recursive behavior
4667 @chapter Recursive behavior
4668 @cindex Recursive (directory descending)
4669 @cindex Directory, descending
4670 @cindex Descending directories
4671 @cindex Subdirectories
4673 Almost all of the subcommands of @sc{cvs} work
4674 recursively when you specify a directory as an
4675 argument. For instance, consider this directory
4684 | (internal @sc{cvs} files)
4693 | | (internal @sc{cvs} files)
4699 | (internal @sc{cvs} files)
4705 If @file{tc} is the current working directory, the
4710 @samp{cvs update testing} is equivalent to
4713 cvs update testing/testpgm.t testing/test2.t
4717 @samp{cvs update testing man} updates all files in the
4721 @samp{cvs update .} or just @samp{cvs update} updates
4722 all files in the @code{tc} directory
4725 If no arguments are given to @code{update} it will
4726 update all files in the current working directory and
4727 all its subdirectories. In other words, @file{.} is a
4728 default argument to @code{update}. This is also true
4729 for most of the @sc{cvs} subcommands, not only the
4730 @code{update} command.
4732 The recursive behavior of the @sc{cvs} subcommands can be
4733 turned off with the @samp{-l} option.
4734 Conversely, the @samp{-R} option can be used to force recursion if
4735 @samp{-l} is specified in @file{~/.cvsrc} (@pxref{~/.cvsrc}).
4738 $ cvs update -l # @r{Don't update files in subdirectories}
4741 @c ---------------------------------------------------------------------
4742 @node Adding and removing
4743 @chapter Adding, removing, and renaming files and directories
4745 In the course of a project, one will often add new
4746 files. Likewise with removing or renaming, or with
4747 directories. The general concept to keep in mind in
4748 all these cases is that instead of making an
4749 irreversible change you want @sc{cvs} to record the
4750 fact that a change has taken place, just as with
4751 modifying an existing file. The exact mechanisms to do
4752 this in @sc{cvs} vary depending on the situation.
4755 * Adding files:: Adding files
4756 * Removing files:: Removing files
4757 * Removing directories:: Removing directories
4758 * Moving files:: Moving and renaming files
4759 * Moving directories:: Moving and renaming directories
4763 @section Adding files to a directory
4764 @cindex Adding files
4766 To add a new file to a directory, follow these steps.
4770 You must have a working copy of the directory.
4771 @xref{Getting the source}.
4774 Create the new file inside your working copy of the directory.
4777 Use @samp{cvs add @var{filename}} to tell @sc{cvs} that you
4778 want to version control the file. If the file contains
4779 binary data, specify @samp{-kb} (@pxref{Binary files}).
4782 Use @samp{cvs commit @var{filename}} to actually check
4783 in the file into the repository. Other developers
4784 cannot see the file until you perform this step.
4787 You can also use the @code{add} command to add a new
4789 @c FIXCVS and/or FIXME: Adding a directory doesn't
4790 @c require the commit step. This probably can be
4791 @c considered a CVS bug, but it is possible we should
4792 @c warn people since this behavior probably won't be
4793 @c changing right away.
4795 Unlike most other commands, the @code{add} command is
4796 not recursive. You have to explicitly name files and
4797 directories that you wish to add to the repository.
4798 However, each directory will need to be added
4799 separately before you will be able to add new files
4800 to those directories.
4804 $ cp ~/myfile foo/bar/myfile
4805 $ cvs add foo foo/bar
4806 $ cvs add foo/bar/myfile
4809 @cindex add (subcommand)
4810 @deffn Command {cvs add} [@code{-k} kflag] [@code{-m} message] files @dots{}
4812 Schedule @var{files} to be added to the repository.
4813 The files or directories specified with @code{add} must
4814 already exist in the current directory. To add a whole
4815 new directory hierarchy to the source repository (for
4816 example, files received from a third-party vendor), use
4817 the @code{import} command instead. @xref{import}.
4819 The added files are not placed in the source repository
4820 until you use @code{commit} to make the change
4821 permanent. Doing an @code{add} on a file that was
4822 removed with the @code{remove} command will undo the
4823 effect of the @code{remove}, unless a @code{commit}
4824 command intervened. @xref{Removing files}, for an
4827 The @samp{-k} option specifies the default way that
4828 this file will be checked out; for more information see
4829 @ref{Substitution modes}.
4831 @c As noted in BUGS, -m is broken client/server (Nov
4832 @c 96). Also see testsuite log2-* tests.
4833 The @samp{-m} option specifies a description for the
4834 file. This description appears in the history log (if
4835 it is enabled, @pxref{history file}). It will also be
4836 saved in the version history inside the repository when
4837 the file is committed. The @code{log} command displays
4838 this description. The description can be changed using
4839 @samp{admin -t}. @xref{admin}. If you omit the
4840 @samp{-m @var{description}} flag, an empty string will
4841 be used. You will not be prompted for a description.
4844 For example, the following commands add the file
4845 @file{backend.c} to the repository:
4847 @c This example used to specify
4848 @c -m "Optimizer and code generation passes."
4849 @c to the cvs add command, but that doesn't work
4850 @c client/server (see log2 in sanity.sh). Should fix CVS,
4851 @c but also seems strange to document things which
4855 $ cvs commit -m "Early version. Not yet compilable." backend.c
4858 When you add a file it is added only on the branch
4859 which you are working on (@pxref{Branching and merging}). You can
4860 later merge the additions to another branch if you want
4861 (@pxref{Merging adds and removals}).
4862 @c Should we mention that earlier versions of CVS
4863 @c lacked this feature (1.3) or implemented it in a buggy
4864 @c way (well, 1.8 had many bugs in cvs update -j)?
4865 @c Should we mention the bug/limitation regarding a
4866 @c file being a regular file on one branch and a directory
4868 @c FIXME: This needs an example, or several, here or
4869 @c elsewhere, for it to make much sense.
4870 @c Somewhere we need to discuss the aspects of death
4871 @c support which don't involve branching, I guess.
4872 @c Like the ability to re-create a release from a tag.
4874 @c ---------------------------------------------------------------------
4875 @node Removing files
4876 @section Removing files
4877 @cindex Removing files
4878 @cindex Deleting files
4880 @c FIXME: this node wants to be split into several
4881 @c smaller nodes. Could make these children of
4882 @c "Adding and removing", probably (death support could
4883 @c be its own section, for example, as could the
4884 @c various bits about undoing mistakes in adding and
4886 Directories change. New files are added, and old files
4887 disappear. Still, you want to be able to retrieve an
4888 exact copy of old releases.
4890 Here is what you can do to remove a file,
4891 but remain able to retrieve old revisions:
4894 @c FIXME: should probably be saying something about
4895 @c having a working directory in the first place.
4897 Make sure that you have not made any uncommitted
4898 modifications to the file. @xref{Viewing differences},
4899 for one way to do that. You can also use the
4900 @code{status} or @code{update} command. If you remove
4901 the file without committing your changes, you will of
4902 course not be able to retrieve the file as it was
4903 immediately before you deleted it.
4906 Remove the file from your working copy of the directory.
4907 You can for instance use @code{rm}.
4910 Use @samp{cvs remove @var{filename}} to tell @sc{cvs} that
4911 you really want to delete the file.
4914 Use @samp{cvs commit @var{filename}} to actually
4915 perform the removal of the file from the repository.
4918 @c FIXME: Somehow this should be linked in with a more
4919 @c general discussion of death support. I don't know
4920 @c whether we want to use the term "death support" or
4921 @c not (we can perhaps get by without it), but we do
4922 @c need to discuss the "dead" state in "cvs log" and
4923 @c related subjects. The current discussion is
4924 @c scattered around, and not xref'd to each other.
4925 @c FIXME: I think this paragraph wants to be moved
4926 @c later down, at least after the first example.
4927 When you commit the removal of the file, @sc{cvs}
4928 records the fact that the file no longer exists. It is
4929 possible for a file to exist on only some branches and
4930 not on others, or to re-add another file with the same
4931 name later. @sc{cvs} will correctly create or not create
4932 the file, based on the @samp{-r} and @samp{-D} options
4933 specified to @code{checkout} or @code{update}.
4935 @c FIXME: This style seems to clash with how we
4936 @c document things in general.
4937 @cindex Remove (subcommand)
4938 @deffn Command {cvs remove} [options] files @dots{}
4940 Schedule file(s) to be removed from the repository
4941 (files which have not already been removed from the
4942 working directory are not processed). This command
4943 does not actually remove the file from the repository
4944 until you commit the removal. For a full list of
4945 options, see @ref{Invoking CVS}.
4948 Here is an example of removing several files:
4954 cvs remove: Removing .
4955 cvs remove: scheduling a.c for removal
4956 cvs remove: scheduling b.c for removal
4957 cvs remove: use 'cvs commit' to remove these files permanently
4958 $ cvs ci -m "Removed unneeded files"
4959 cvs commit: Examining .
4960 cvs commit: Committing .
4963 As a convenience you can remove the file and @code{cvs
4964 remove} it in one step, by specifying the @samp{-f}
4965 option. For example, the above example could also be
4971 cvs remove: scheduling a.c for removal
4972 cvs remove: scheduling b.c for removal
4973 cvs remove: use 'cvs commit' to remove these files permanently
4974 $ cvs ci -m "Removed unneeded files"
4975 cvs commit: Examining .
4976 cvs commit: Committing .
4979 If you execute @code{remove} for a file, and then
4980 change your mind before you commit, you can undo the
4981 @code{remove} with an @code{add} command.
4983 @c is this worth saying or not? Somehow it seems
4986 since you have removed your copy of file in the working
4987 directory, @sc{cvs} does not necessarily bring back the
4988 contents of the file from right before you executed
4989 @code{remove}; instead it gets the file from the
4993 @c FIXME: what if you change your mind after you commit
4994 @c it? (answer is also "cvs add" but we don't say that...).
4995 @c We need some index entries for thinks like "undoing
5003 cvs remove: scheduling oj.c for removal
5004 cvs remove: use 'cvs commit' to remove this file permanently
5007 cvs add: oj.c, version 1.1.1.1, resurrected
5010 If you realize your mistake before you run the
5011 @code{remove} command you can use @code{update} to
5017 cvs update: warning: oj.c was lost
5021 When you remove a file it is removed only on the branch
5022 which you are working on (@pxref{Branching and merging}). You can
5023 later merge the removals to another branch if you want
5024 (@pxref{Merging adds and removals}).
5026 @node Removing directories
5027 @section Removing directories
5028 @cindex Removing directories
5029 @cindex Directories, removing
5031 In concept, removing directories is somewhat similar to
5032 removing files---you want the directory to not exist in
5033 your current working directories, but you also want to
5034 be able to retrieve old releases in which the directory
5037 The way that you remove a directory is to remove all
5038 the files in it. You don't remove the directory
5039 itself; there is no way to do that.
5040 Instead you specify the @samp{-P} option to
5041 @code{cvs update} or @code{cvs checkout},
5042 which will cause @sc{cvs} to remove empty
5043 directories from working directories.
5044 (Note that @code{cvs export} always removes empty directories.)
5046 best way to do this is to always specify @samp{-P}; if
5047 you want an empty directory then put a dummy file (for
5048 example @file{.keepme}) in it to prevent @samp{-P} from
5051 @c I'd try to give a rationale for this, but I'm not
5052 @c sure there is a particularly convincing one. What
5053 @c we would _like_ is for CVS to do a better job of version
5054 @c controlling whether directories exist, to eliminate the
5055 @c need for -P and so that a file can be a directory in
5056 @c one revision and a regular file in another.
5057 Note that @samp{-P} is implied by the @samp{-r} or @samp{-D}
5058 options of @code{checkout}. This way,
5059 @sc{cvs} will be able to correctly create the directory
5060 or not depending on whether the particular version you
5061 are checking out contains any files in that directory.
5063 @c ---------------------------------------------------------------------
5065 @section Moving and renaming files
5066 @cindex Moving files
5067 @cindex Renaming files
5068 @cindex Files, moving
5070 Moving files to a different directory or renaming them
5071 is not difficult, but some of the ways in which this
5072 works may be non-obvious. (Moving or renaming a
5073 directory is even harder. @xref{Moving directories}.).
5075 The examples below assume that the file @var{old} is renamed to
5079 * Outside:: The normal way to Rename
5080 * Inside:: A tricky, alternative way
5081 * Rename by copying:: Another tricky, alternative way
5084 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
5086 @subsection The Normal way to Rename
5088 @c More rename issues. Not sure whether these are
5089 @c worth documenting; I'm putting them here because
5090 @c it seems to be as good a place as any to try to
5091 @c set down the issues.
5092 @c * "cvs annotate" will annotate either the new
5093 @c file or the old file; it cannot annotate _each
5094 @c line_ based on whether it was last changed in the
5095 @c new or old file. Unlike "cvs log", where the
5096 @c consequences of having to select either the new
5097 @c or old name seem fairly benign, this may be a
5098 @c real advantage to having CVS know about renames
5099 @c other than as a deletion and an addition.
5101 The normal way to move a file is to copy @var{old} to
5102 @var{new}, and then issue the normal @sc{cvs} commands
5103 to remove @var{old} from the repository, and add
5105 @c The following sentence is not true: one must cd into
5106 @c the directory to run "cvs add".
5107 @c (Both @var{old} and @var{new} could
5108 @c contain relative paths, for example @file{foo/bar.c}).
5111 $ mv @var{old} @var{new}
5112 $ cvs remove @var{old}
5114 $ cvs commit -m "Renamed @var{old} to @var{new}" @var{old} @var{new}
5117 This is the simplest way to move a file, it is not
5118 error-prone, and it preserves the history of what was
5119 done. Note that to access the history of the file you
5120 must specify the old or the new name, depending on what
5121 portion of the history you are accessing. For example,
5122 @code{cvs log @var{old}} will give the log up until the
5125 When @var{new} is committed its revision numbers will
5126 start again, usually at 1.1, so if that bothers you,
5127 use the @samp{-r rev} option to commit. For more
5128 information see @ref{Assigning revisions}.
5130 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
5132 @subsection Moving the history file
5134 This method is more dangerous, since it involves moving
5135 files inside the repository. Read this entire section
5136 before trying it out!
5139 $ cd $CVSROOT/@var{dir}
5140 $ mv @var{old},v @var{new},v
5148 The log of changes is maintained intact.
5151 The revision numbers are not affected.
5159 Old releases cannot easily be fetched from the
5160 repository. (The file will show up as @var{new} even
5161 in revisions from the time before it was renamed).
5164 There is no log information of when the file was renamed.
5167 Nasty things might happen if someone accesses the history file
5168 while you are moving it. Make sure no one else runs any of the @sc{cvs}
5169 commands while you move it.
5172 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
5173 @node Rename by copying
5174 @subsection Copying the history file
5176 This way also involves direct modifications to the
5177 repository. It is safe, but not without drawbacks.
5180 # @r{Copy the @sc{rcs} file inside the repository}
5181 $ cd $CVSROOT/@var{dir}
5182 $ cp @var{old},v @var{new},v
5183 # @r{Remove the old file}
5186 $ cvs remove @var{old}
5187 $ cvs commit @var{old}
5188 # @r{Remove all tags from @var{new}}
5189 $ cvs update @var{new}
5190 $ cvs log @var{new} # @r{Remember the non-branch tag names}
5191 $ cvs tag -d @var{tag1} @var{new}
5192 $ cvs tag -d @var{tag2} @var{new}
5196 By removing the tags you will be able to check out old
5204 @c FIXME: Is this true about -D now that we have death
5205 @c support? See 5B.3 in the FAQ.
5206 Checking out old revisions works correctly, as long as
5207 you use @samp{-r@var{tag}} and not @samp{-D@var{date}}
5208 to retrieve the revisions.
5211 The log of changes is maintained intact.
5214 The revision numbers are not affected.
5222 You cannot easily see the history of the file across the rename.
5225 @c Is this true? I don't see how the revision numbers
5226 @c _could_ start over, when new,v is just old,v with
5227 @c the tags deleted.
5228 @c If there is some need to reinstate this text,
5229 @c it is "usually 1.1", not "1.0" and it needs an
5230 @c xref to Assigning revisions
5232 Unless you use the @samp{-r rev} (@pxref{commit
5233 options}) flag when @var{new} is committed its revision
5234 numbers will start at 1.0 again.
5238 @c ---------------------------------------------------------------------
5239 @node Moving directories
5240 @section Moving and renaming directories
5241 @cindex Moving directories
5242 @cindex Renaming directories
5243 @cindex Directories, moving
5245 The normal way to rename or move a directory is to
5246 rename or move each file within it as described in
5247 @ref{Outside}. Then check out with the @samp{-P}
5248 option, as described in @ref{Removing directories}.
5250 If you really want to hack the repository to rename or
5251 delete a directory in the repository, you can do it
5256 Inform everyone who has a checked out copy of the directory that the
5257 directory will be renamed. They should commit all their changes in all their
5258 copies of the project containing the directory to be removed, and remove
5259 all their working copies of said project, before you take the steps below.
5262 Rename the directory inside the repository.
5265 $ cd $CVSROOT/@var{parent-dir}
5266 $ mv @var{old-dir} @var{new-dir}
5270 Fix the @sc{cvs} administrative files, if necessary (for
5271 instance if you renamed an entire module).
5274 Tell everyone that they can check out again and continue
5279 If someone had a working copy the @sc{cvs} commands will
5280 cease to work for him, until he removes the directory
5281 that disappeared inside the repository.
5283 It is almost always better to move the files in the
5284 directory instead of moving the directory. If you move the
5285 directory you are unlikely to be able to retrieve old
5286 releases correctly, since they probably depend on the
5287 name of the directories.
5289 @c ---------------------------------------------------------------------
5290 @node History browsing
5291 @chapter History browsing
5292 @cindex History browsing
5293 @cindex Traceability
5297 @c This is too long for an introduction (goal is
5298 @c one 20x80 character screen), and also mixes up a
5299 @c variety of issues (parallel development, history,
5300 @c maybe even touches on process control).
5302 @c -- @quote{To lose ones history is to lose ones soul.}
5304 @c -- ///Those who cannot remember the past are condemned to repeat it.
5305 @c -- /// -- George Santayana
5308 @sc{cvs} tries to make it easy for a group of people to work
5309 together. This is done in two ways:
5313 Isolation---You have your own working copy of the
5314 source. You are not affected by modifications made by
5315 others until you decide to incorporate those changes
5316 (via the @code{update} command---@pxref{update}).
5319 Traceability---When something has changed, you can
5320 always see @emph{exactly} what changed.
5323 There are several features of @sc{cvs} that together lead
5328 Each revision of a file has an accompanying log
5332 All commits are optionally logged to a central history
5336 Logging information can be sent to a user-defined
5337 program (@pxref{loginfo}).
5340 @c -- More text here.
5342 This chapter should talk about the history file, the
5343 @code{log} command, the usefulness of ChangeLogs
5344 even when you run @sc{cvs}, and things like that.
5348 @c kind of lame, in a lot of ways the above text inside
5349 @c the @ignore motivates this chapter better
5350 Once you have used @sc{cvs} to store a version control
5351 history---what files have changed when, how, and by
5352 whom, there are a variety of mechanisms for looking
5353 through the history.
5355 @c FIXME: should also be talking about how you look at
5356 @c old revisions (e.g. "cvs update -p -r 1.2 foo.c").
5358 * log messages:: Log messages
5359 * history database:: The history database
5360 * user-defined logging:: User-defined logging
5363 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
5365 @section Log messages
5367 @c FIXME: @xref to place where we talk about how to
5368 @c specify message to commit.
5369 Whenever you commit a file you specify a log message.
5371 @c FIXME: bring the information here, and get rid of or
5372 @c greatly shrink the "log" node.
5373 To look through the log messages which have been
5374 specified for every revision which has been committed,
5375 use the @code{cvs log} command (@pxref{log}).
5377 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
5378 @node history database
5379 @section The history database
5381 @c FIXME: bring the information from the history file
5382 @c and history nodes here. Rewrite it to be motivated
5383 @c better (start out by clearly explaining what gets
5384 @c logged in history, for example).
5385 You can use the history file (@pxref{history file}) to
5386 log various @sc{cvs} actions. To retrieve the
5387 information from the history file, use the @code{cvs
5388 history} command (@pxref{history}).
5390 Note: you can control what is logged to this file by using the
5391 @samp{LogHistory} keyword in the @file{CVSROOT/config} file
5395 @c The history database has many problems:
5396 @c * It is very unclear what field means what. This
5397 @c could be improved greatly by better documentation,
5398 @c but there are still non-orthogonalities (for
5399 @c example, tag does not record the "repository"
5400 @c field but most records do).
5401 @c * Confusion about files, directories, and modules.
5402 @c Some commands record one, some record others.
5403 @c * File removal is not logged. There is an 'R'
5404 @c record type documented, but CVS never uses it.
5405 @c * Tags are only logged for the "cvs rtag" command,
5406 @c not "cvs tag". The fix for this is not completely
5407 @c clear (see above about modules vs. files).
5408 @c * Are there other cases of operations that are not
5409 @c logged? One would hope for all changes to the
5410 @c repository to be logged somehow (particularly
5411 @c operations like tagging, "cvs admin -k", and other
5412 @c operations which do not record a history that one
5413 @c can get with "cvs log"). Operations on the working
5414 @c directory, like export, get, and release, are a
5415 @c second category also covered by the current "cvs
5417 @c * The history file does not record the options given
5418 @c to a command. The most serious manifestation of
5419 @c this is perhaps that it doesn't record whether a command
5420 @c was recursive. It is not clear to me whether one
5421 @c wants to log at a level very close to the command
5422 @c line, as a sort of way of logging each command
5423 @c (more or less), or whether one wants
5424 @c to log more at the level of what was changed (or
5425 @c something in between), but either way the current
5426 @c information has pretty big gaps.
5427 @c * Further details about a tag--like whether it is a
5428 @c branch tag or, if a non-branch tag, which branch it
5429 @c is on. One can find out this information about the
5430 @c tag as it exists _now_, but if the tag has been
5431 @c moved, one doesn't know what it was like at the time
5432 @c the history record was written.
5433 @c * Whether operating on a particular tag, date, or
5434 @c options was implicit (sticky) or explicit.
5436 @c Another item, only somewhat related to the above, is a
5437 @c way to control what is logged in the history file.
5438 @c This is probably the only good way to handle
5439 @c different people having different ideas about
5440 @c information/space tradeoffs.
5442 @c It isn't really clear that it makes sense to try to
5443 @c patch up the history file format as it exists now to
5444 @c include all that stuff. It might be better to
5445 @c design a whole new CVSROOT/nhistory file and "cvs
5446 @c nhistory" command, or some such, or in some other
5447 @c way trying to come up with a clean break from the
5448 @c past, which can address the above concerns. Another
5449 @c open question is how/whether this relates to
5450 @c taginfo/loginfo/etc.
5452 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
5453 @node user-defined logging
5454 @section User-defined logging
5456 @c FIXME: probably should centralize this information
5457 @c here, at least to some extent. Maybe by moving the
5458 @c loginfo, etc., nodes here and replacing
5459 @c the "user-defined logging" node with one node for
5461 You can customize @sc{cvs} to log various kinds of
5462 actions, in whatever manner you choose. These
5463 mechanisms operate by executing a script at various
5464 times. The script might append a message to a file
5465 listing the information and the programmer who created
5466 it, or send mail to a group of developers, or, perhaps,
5467 post a message to a particular newsgroup. To log
5468 commits, use the @file{loginfo} file (@pxref{loginfo}).
5469 To log tags, use the @file{taginfo} file (@pxref{taginfo}).
5470 @c FIXME: What is difference between doing it in the
5471 @c modules file and using loginfo/taginfo? Why should
5472 @c user use one or the other?
5473 To log checkouts, exports, and tags,
5474 respectively, you can also use the
5475 @samp{-o}, @samp{-e}, and @samp{-t} options in the
5476 modules file. For a more flexible way of giving
5477 notifications to various users, which requires less in
5478 the way of keeping centralized scripts up to date, use
5479 the @code{cvs watch add} command (@pxref{Getting
5480 Notified}); this command is useful even if you are not
5481 using @code{cvs watch on}.
5483 @c ---------------------------------------------------------------------
5485 @chapter Handling binary files
5486 @cindex Binary files
5488 The most common use for @sc{cvs} is to store text
5489 files. With text files, @sc{cvs} can merge revisions,
5490 display the differences between revisions in a
5491 human-visible fashion, and other such operations.
5492 However, if you are willing to give up a few of these
5493 abilities, @sc{cvs} can store binary files. For
5494 example, one might store a web site in @sc{cvs}
5495 including both text files and binary images.
5498 * Binary why:: More details on issues with binary files
5499 * Binary howto:: How to store them
5503 @section The issues with binary files
5505 While the need to manage binary files may seem obvious
5506 if the files that you customarily work with are binary,
5507 putting them into version control does present some
5510 One basic function of version control is to show the
5511 differences between two revisions. For example, if
5512 someone else checked in a new version of a file, you
5513 may wish to look at what they changed and determine
5514 whether their changes are good. For text files,
5515 @sc{cvs} provides this functionality via the @code{cvs
5516 diff} command. For binary files, it may be possible to
5517 extract the two revisions and then compare them with a
5518 tool external to @sc{cvs} (for example, word processing
5519 software often has such a feature). If there is no
5520 such tool, one must track changes via other mechanisms,
5521 such as urging people to write good log messages, and
5522 hoping that the changes they actually made were the
5523 changes that they intended to make.
5525 Another ability of a version control system is the
5526 ability to merge two revisions. For @sc{cvs} this
5527 happens in two contexts. The first is when users make
5528 changes in separate working directories
5529 (@pxref{Multiple developers}). The second is when one
5530 merges explicitly with the @samp{update -j} command
5531 (@pxref{Branching and merging}).
5534 files, @sc{cvs} can merge changes made independently,
5535 and signal a conflict if the changes conflict. With
5536 binary files, the best that @sc{cvs} can do is present
5537 the two different copies of the file, and leave it to
5538 the user to resolve the conflict. The user may choose
5539 one copy or the other, or may run an external merge
5540 tool which knows about that particular file format, if
5542 Note that having the user merge relies primarily on the
5543 user to not accidentally omit some changes, and thus is
5544 potentially error prone.
5546 If this process is thought to be undesirable, the best
5547 choice may be to avoid merging. To avoid the merges
5548 that result from separate working directories, see the
5549 discussion of reserved checkouts (file locking) in
5550 @ref{Multiple developers}. To avoid the merges
5551 resulting from branches, restrict use of branches.
5554 @section How to store binary files
5556 There are two issues with using @sc{cvs} to store
5557 binary files. The first is that @sc{cvs} by default
5558 converts line endings between the canonical form in
5559 which they are stored in the repository (linefeed
5560 only), and the form appropriate to the operating system
5561 in use on the client (for example, carriage return
5562 followed by line feed for Windows NT).
5564 The second is that a binary file might happen to
5565 contain data which looks like a keyword (@pxref{Keyword
5566 substitution}), so keyword expansion must be turned
5569 @c FIXME: the third is that one can't do merges with
5570 @c binary files. xref to Multiple Developers and the
5571 @c reserved checkout issues.
5573 The @samp{-kb} option available with some @sc{cvs}
5574 commands insures that neither line ending conversion
5575 nor keyword expansion will be done.
5577 Here is an example of how you can create a new file
5578 using the @samp{-kb} flag:
5581 $ echo '$@splitrcskeyword{Id}$' > kotest
5582 $ cvs add -kb -m"A test file" kotest
5583 $ cvs ci -m"First checkin; contains a keyword" kotest
5586 If a file accidentally gets added without @samp{-kb},
5587 one can use the @code{cvs admin} command to recover.
5591 $ echo '$@splitrcskeyword{Id}$' > kotest
5592 $ cvs add -m"A test file" kotest
5593 $ cvs ci -m"First checkin; contains a keyword" kotest
5594 $ cvs admin -kb kotest
5595 $ cvs update -A kotest
5596 # @r{For non-unix systems:}
5597 # @r{Copy in a good copy of the file from outside CVS}
5598 $ cvs commit -m "make it binary" kotest
5601 @c Trying to describe this for both unix and non-unix
5602 @c in the same description is very confusing. Might
5603 @c want to split the two, or just ditch the unix "shortcut"
5604 @c (unixheads don't do much with binary files, anyway).
5605 @c This used to say "(Try the above example, and do a
5606 @c @code{cat kotest} after every command)". But that
5607 @c only really makes sense for the unix case.
5608 When you check in the file @file{kotest} the file is
5609 not preserved as a binary file, because you did not
5610 check it in as a binary file. The @code{cvs
5611 admin -kb} command sets the default keyword
5612 substitution method for this file, but it does not
5613 alter the working copy of the file that you have. If you need to
5614 cope with line endings (that is, you are using
5615 @sc{cvs} on a non-unix system), then you need to
5616 check in a new copy of the file, as shown by the
5617 @code{cvs commit} command above.
5618 On unix, the @code{cvs update -A} command suffices.
5619 @c FIXME: should also describe what the *other users*
5620 @c need to do, if they have checked out copies which
5621 @c have been corrupted by lack of -kb. I think maybe
5622 @c "cvs update -kb" or "cvs
5623 @c update -A" would suffice, although the user who
5624 @c reported this suggested removing the file, manually
5625 @c removing it from CVS/Entries, and then "cvs update"
5626 (Note that you can use @code{cvs log} to determine the default keyword
5627 substitution method for a file and @code{cvs status} to determine
5628 the keyword substitution method for a working copy.)
5630 However, in using @code{cvs admin -k} to change the
5631 keyword expansion, be aware that the keyword expansion
5632 mode is not version controlled. This means that, for
5633 example, that if you have a text file in old releases,
5634 and a binary file with the same name in new releases,
5635 @sc{cvs} provides no way to check out the file in text
5636 or binary mode depending on what version you are
5637 checking out. There is no good workaround for this
5640 You can also set a default for whether @code{cvs add}
5641 and @code{cvs import} treat a file as binary based on
5642 its name; for example you could say that files who
5643 names end in @samp{.exe} are binary. @xref{Wrappers}.
5644 There is currently no way to have @sc{cvs} detect
5645 whether a file is binary based on its contents. The
5646 main difficulty with designing such a feature is that
5647 it is not clear how to distinguish between binary and
5648 non-binary files, and the rules to apply would vary
5649 considerably with the operating system.
5650 @c For example, it would be good on MS-DOS-family OSes
5651 @c for anything containing ^Z to be binary. Having
5652 @c characters with the 8th bit set imply binary is almost
5653 @c surely a bad idea in the context of ISO-8859-* and
5654 @c other such character sets. On VMS or the Mac, we
5655 @c could use the OS's file typing. This is a
5656 @c commonly-desired feature, and something of this sort
5657 @c may make sense. But there are a lot of pitfalls here.
5659 @c Another, probably better, way to tell is to read the
5660 @c file in text mode, write it to a temp file in text
5661 @c mode, and then do a binary mode compare of the two
5662 @c files. If they differ, it is a binary file. This
5663 @c might have problems on VMS (or some other system
5664 @c with several different text modes), but in general
5665 @c should be relatively portable. The only other
5666 @c downside I can think of is that it would be fairly
5667 @c slow, but that is perhaps a small price to pay for
5668 @c not having your files corrupted. Another issue is
5669 @c what happens if you import a text file with bare
5670 @c linefeeds on Windows. Such files will show up on
5671 @c Windows sometimes (I think some native windows
5672 @c programs even write them, on occasion). Perhaps it
5673 @c is reasonable to treat such files as binary; after
5674 @c all it is something of a presumption to assume that
5675 @c the user would want the linefeeds converted to CRLF.
5677 @c ---------------------------------------------------------------------
5678 @node Multiple developers
5679 @chapter Multiple developers
5680 @cindex Multiple developers
5681 @cindex Team of developers
5682 @cindex File locking
5683 @cindex Locking files
5684 @cindex Working copy
5685 @cindex Reserved checkouts
5686 @cindex Unreserved checkouts
5687 @cindex RCS-style locking
5689 When more than one person works on a software project
5690 things often get complicated. Often, two people try to
5691 edit the same file simultaneously. One solution, known
5692 as @dfn{file locking} or @dfn{reserved checkouts}, is
5693 to allow only one person to edit each file at a time.
5694 This is the only solution with some version control
5695 systems, including @sc{rcs} and @sc{sccs}. Currently
5696 the usual way to get reserved checkouts with @sc{cvs}
5697 is the @code{cvs admin -l} command (@pxref{admin
5698 options}). This is not as nicely integrated into
5699 @sc{cvs} as the watch features, described below, but it
5700 seems that most people with a need for reserved
5701 checkouts find it adequate.
5702 @c Or "find it better than worrying about implementing
5703 @c nicely integrated reserved checkouts" or ...?
5704 It also may be possible to use the watches
5705 features described below, together with suitable
5706 procedures (not enforced by software), to avoid having
5707 two people edit at the same time.
5709 @c Our unreserved checkout model might not
5710 @c be quite the same as others. For example, I
5711 @c think that some systems will tend to create a branch
5712 @c in the case where CVS prints "up-to-date check failed".
5713 @c It isn't clear to me whether we should try to
5714 @c explore these subtleties; it could easily just
5716 The default model with @sc{cvs} is known as
5717 @dfn{unreserved checkouts}. In this model, developers
5718 can edit their own @dfn{working copy} of a file
5719 simultaneously. The first person that commits his
5720 changes has no automatic way of knowing that another
5721 has started to edit it. Others will get an error
5722 message when they try to commit the file. They must
5723 then use @sc{cvs} commands to bring their working copy
5724 up to date with the repository revision. This process
5725 is almost automatic.
5727 @c FIXME? should probably use the word "watch" here, to
5728 @c tie this into the text below and above.
5729 @sc{cvs} also supports mechanisms which facilitate
5730 various kinds of communication, without actually
5731 enforcing rules like reserved checkouts do.
5733 The rest of this chapter describes how these various
5734 models work, and some of the issues involved in
5735 choosing between them.
5738 Here is a draft reserved checkout design or discussion
5739 of the issues. This seems like as good a place as any
5742 Might want a cvs lock/cvs unlock--in which the names
5743 differ from edit/unedit because the network must be up
5744 for these to work. unedit gives an error if there is a
5745 reserved checkout in place (so that people don't
5746 accidentally leave locks around); unlock gives an error
5747 if one is not in place (this is more arguable; perhaps
5748 it should act like unedit in that case).
5750 On the other hand, might want it so that emacs,
5751 scripts, etc., can get ready to edit a file without
5752 having to know which model is in use. In that case we
5753 would have a "cvs watch lock" (or .cvsrc?) (that is,
5754 three settings, "on", "off", and "lock"). Having cvs
5755 watch lock set would cause a get to record in the CVS
5756 directory which model is in use, and cause "cvs edit"
5757 to change behaviors. We'd want a way to query which
5758 setting is in effect (this would be handy even if it is
5759 only "on" or "off" as presently). If lock is in
5760 effect, then commit would require a lock before
5761 allowing a checkin; chmod wouldn't suffice (might be
5762 debatable--see chmod comment below, in watches--but it
5763 is the way people expect RCS to work and I can't think
5764 of any significant downside. On the other hand, maybe
5765 it isn't worth bothering, because people who are used
5766 to RCS wouldn't think to use chmod anyway).
5768 Implementation: use file attributes or use RCS
5769 locking. The former avoids more dependence on RCS
5770 behaviors we will need to re-implement as we librarify
5771 RCS, and makes it easier to import/export RCS files (in
5772 that context, want to ignore the locker field). But
5773 note that RCS locks are per-branch, which is the
5774 correct behavior (this is also an issue for the "watch
5775 on" features; they should be per-branch too).
5777 Here are a few more random notes about implementation
5778 details, assuming "cvs watch lock" and
5780 CVS/Watched file? Or try to fit this into CVS/Entries somehow?
5781 Cases: (1) file is checked out (unreserved or with watch on) by old
5782 version of @sc{cvs}, now we do something with new one, (2) file is checked
5783 out by new version, now we do something with old one.
5785 Remote protocol would have a "Watched" analogous to "Mode". Of course
5786 it would apply to all Updated-like requests. How do we keep this
5787 setting up to date? I guess that there wants to be a Watched request,
5788 and the server would send a new one if it isn't up to date? (Ugh--hard
5789 to implement and slows down "cvs -q update"--is there an easier way?)
5791 "cvs edit"--checks CVS/Watched, and if watch lock, then sends
5792 "edit-lock" request. Which comes back with a Checked-in with
5793 appropriate Watched (off, on, lock, locked, or some such?), or error
5794 message if already locked.
5796 "cvs commit"--only will commit if off/on/locked. lock is not OK.
5799 note that "cvs edit" must be connected to network if watch lock is in
5802 Talk about what to do if someone has locked a file and you want to
5803 edit that file. (breaking locks, or lack thereof).
5806 One other idea (which could work along with the
5807 existing "cvs admin -l" reserved checkouts, as well as
5810 "cvs editors" could show who has the file locked, if
5816 * File status:: A file can be in several states
5817 * Updating a file:: Bringing a file up-to-date
5818 * Conflicts example:: An informative example
5819 * Informing others:: To cooperate you must inform
5820 * Concurrency:: Simultaneous repository access
5821 * Watches:: Mechanisms to track who is editing files
5822 * Choosing a model:: Reserved or unreserved checkouts?
5825 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
5827 @section File status
5829 @cindex Status of a file
5831 @c Shouldn't this start with an example or something,
5832 @c introducing the unreserved checkout model? Before we
5833 @c dive into listing states?
5834 Based on what operations you have performed on a
5835 checked out file, and what operations others have
5836 performed to that file in the repository, one can
5837 classify a file in a number of states. The states, as
5838 reported by the @code{status} command, are:
5840 @c The order of items is chosen to group logically
5841 @c similar outputs together.
5842 @c People who want alphabetical can use the index...
5846 The file is identical with the latest revision in the
5847 repository for the branch in use.
5848 @c FIXME: should we clarify "in use"? The answer is
5849 @c sticky tags, and trying to distinguish branch sticky
5850 @c tags from non-branch sticky tags seems rather awkward
5852 @c FIXME: What happens with non-branch sticky tags? Is
5853 @c a stuck file "Up-to-date" or "Needs checkout" or what?
5855 @item Locally Modified
5856 @cindex Locally Modified
5857 You have edited the file, and not yet committed your changes.
5860 @cindex Locally Added
5861 You have added the file with @code{add}, and not yet
5862 committed your changes.
5863 @c There are many cases involving the file being
5864 @c added/removed/modified in the working directory, and
5865 @c added/removed/modified in the repository, which we
5866 @c don't try to describe here. I'm not sure that "cvs
5867 @c status" produces a non-confusing output in most of
5870 @item Locally Removed
5871 @cindex Locally Removed
5872 You have removed the file with @code{remove}, and not yet
5873 committed your changes.
5875 @item Needs Checkout
5876 @cindex Needs Checkout
5877 Someone else has committed a newer revision to the
5878 repository. The name is slightly misleading; you will
5879 ordinarily use @code{update} rather than
5880 @code{checkout} to get that newer revision.
5884 @c See also newb-123j0 in sanity.sh (although that case
5885 @c should probably be changed rather than documented).
5886 Like Needs Checkout, but the @sc{cvs} server will send
5887 a patch rather than the entire file. Sending a patch or
5888 sending an entire file accomplishes the same thing.
5892 Someone else has committed a newer revision to the repository, and you
5893 have also made modifications to the file.
5895 @item Unresolved Conflict
5896 @cindex Unresolved Conflict
5897 @c FIXCVS - This file status needs to be changed to some more informative
5898 @c text that distinguishes it more clearly from each of the Locally Added,
5899 @c File had conflicts on merge, and Unknown status types, but an exact and
5900 @c succinct wording escapes me at the moment.
5901 A file with the same name as this new file has been added to the repository
5902 from a second workspace. This file will need to be moved out of the way
5903 to allow an @code{update} to complete.
5905 @item File had conflicts on merge
5906 @cindex File had conflicts on merge
5907 @c is it worth saying that this message was "Unresolved
5908 @c Conflict" in CVS 1.9 and earlier? I'm inclined to
5909 @c think that is unnecessarily confusing to new users.
5910 This is like Locally Modified, except that a previous
5911 @code{update} command gave a conflict. If you have not
5912 already done so, you need to
5913 resolve the conflict as described in @ref{Conflicts example}.
5917 @sc{cvs} doesn't know anything about this file. For
5918 example, you have created a new file and have not run
5921 @c "Entry Invalid" and "Classify Error" are also in the
5922 @c status.c. The latter definitely indicates a CVS bug
5923 @c (should it be worded more like "internal error" so
5924 @c people submit bug reports if they see it?). The former
5925 @c I'm not as sure; I haven't tracked down whether/when it
5926 @c appears in "cvs status" output.
5930 To help clarify the file status, @code{status} also
5931 reports the @code{Working revision} which is the
5932 revision that the file in the working directory derives
5933 from, and the @code{Repository revision} which is the
5934 latest revision in the repository for the branch in
5936 @c FIXME: should we clarify "in use"? The answer is
5937 @c sticky tags, and trying to distinguish branch sticky
5938 @c tags from non-branch sticky tags seems rather awkward
5940 @c FIXME: What happens with non-branch sticky tags?
5941 @c What is the Repository Revision there? See the
5942 @c comment at vn_rcs in cvs.h, which is kind of
5943 @c confused--we really need to document better what this
5945 @c Q: Should we document "New file!" and other such
5946 @c outputs or are they self-explanatory?
5947 @c FIXME: what about the date to the right of "Working
5948 @c revision"? It doesn't appear with client/server and
5949 @c seems unnecessary (redundant with "ls -l") so
5950 @c perhaps it should be removed for non-client/server too?
5951 @c FIXME: Need some examples.
5952 @c FIXME: Working revision can also be something like
5953 @c "-1.3" for a locally removed file. Not at all
5954 @c self-explanatory (and it is possible that CVS should
5955 @c be changed rather than documenting this).
5957 @c Would be nice to have an @example showing output
5958 @c from cvs status, with comments showing the xref
5959 @c where each part of the output is described. This
5960 @c might fit in nicely if it is desirable to split this
5961 @c node in two; one to introduce "cvs status" and one
5962 @c to list each of the states.
5963 The options to @code{status} are listed in
5964 @ref{Invoking CVS}. For information on its @code{Sticky tag}
5965 and @code{Sticky date} output, see @ref{Sticky tags}.
5966 For information on its @code{Sticky options} output,
5967 see the @samp{-k} option in @ref{update options}.
5969 You can think of the @code{status} and @code{update}
5970 commands as somewhat complementary. You use
5971 @code{update} to bring your files up to date, and you
5972 can use @code{status} to give you some idea of what an
5973 @code{update} would do (of course, the state of the
5974 repository might change before you actually run
5975 @code{update}). In fact, if you want a command to
5976 display file status in a more brief format than is
5977 displayed by the @code{status} command, you can invoke
5979 @cindex update, to display file status
5984 The @samp{-n} option means to not actually do the
5985 update, but merely to display statuses; the @samp{-q}
5986 option avoids printing the name of each directory. For
5987 more information on the @code{update} command, and
5988 these options, see @ref{Invoking CVS}.
5990 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
5991 @node Updating a file
5992 @section Bringing a file up to date
5993 @cindex Bringing a file up to date
5994 @cindex Updating a file
5995 @cindex Merging a file
5996 @cindex Update, introduction
5998 When you want to update or merge a file, use the @code{cvs update -d}
5999 command. For files that are not up to date this is roughly equivalent
6000 to a @code{checkout} command: the newest revision of the file is
6001 extracted from the repository and put in your working directory. The
6002 @code{-d} option, not necessary with @code{checkout}, tells @sc{cvs}
6003 that you wish it to create directories added by other developers.
6005 Your modifications to a file are never lost when you
6006 use @code{update}. If no newer revision exists,
6007 running @code{update} has no effect. If you have
6008 edited the file, and a newer revision is available,
6009 @sc{cvs} will merge all changes into your working copy.
6011 For instance, imagine that you checked out revision 1.4 and started
6012 editing it. In the meantime someone else committed revision 1.5, and
6013 shortly after that revision 1.6. If you run @code{update} on the file
6014 now, @sc{cvs} will incorporate all changes between revision 1.4 and 1.6 into
6018 If any of the changes between 1.4 and 1.6 were made too
6019 close to any of the changes you have made, an
6020 @dfn{overlap} occurs. In such cases a warning is
6021 printed, and the resulting file includes both
6022 versions of the lines that overlap, delimited by
6024 @xref{update}, for a complete description of the
6025 @code{update} command.
6027 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
6028 @node Conflicts example
6029 @section Conflicts example
6030 @cindex Merge, an example
6031 @cindex Example of merge
6032 @cindex driver.c (merge example)
6034 Suppose revision 1.4 of @file{driver.c} contains this:
6045 fprintf(stderr, "No code generated.\n");
6046 exit(nerr == 0 ? 0 : 1);
6051 Revision 1.6 of @file{driver.c} contains this:
6062 fprintf(stderr, "tc: No args expected.\n");
6068 fprintf(stderr, "No code generated.\n");
6074 Your working copy of @file{driver.c}, based on revision
6075 1.4, contains this before you run @samp{cvs update}:
6076 @c -- Really include "cvs"?
6089 fprintf(stderr, "No code generated.\n");
6090 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
6095 You run @samp{cvs update}:
6096 @c -- Really include "cvs"?
6099 $ cvs update driver.c
6100 RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v
6101 retrieving revision 1.4
6102 retrieving revision 1.6
6103 Merging differences between 1.4 and 1.6 into driver.c
6104 rcsmerge warning: overlaps during merge
6105 cvs update: conflicts found in driver.c
6110 @cindex Conflicts (merge example)
6111 @sc{cvs} tells you that there were some conflicts.
6112 Your original working file is saved unmodified in
6113 @file{.#driver.c.1.4}. The new version of
6114 @file{driver.c} contains this:
6127 fprintf(stderr, "tc: No args expected.\n");
6133 fprintf(stderr, "No code generated.\n");
6134 @asis{}<<<<<<< driver.c
6135 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
6143 @cindex Markers, conflict
6144 @cindex Conflict markers
6149 Note how all non-overlapping modifications are incorporated in your working
6150 copy, and that the overlapping section is clearly marked with
6151 @samp{<<<<<<<}, @samp{=======} and @samp{>>>>>>>}.
6153 @cindex Resolving a conflict
6154 @cindex Conflict resolution
6155 You resolve the conflict by editing the file, removing the markers and
6156 the erroneous line. Suppose you end up with this file:
6157 @c -- Add xref to the pcl-cvs manual when it talks
6170 fprintf(stderr, "tc: No args expected.\n");
6176 fprintf(stderr, "No code generated.\n");
6177 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
6182 You can now go ahead and commit this as revision 1.7.
6185 $ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c
6186 Checking in driver.c;
6187 /usr/local/cvsroot/yoyodyne/tc/driver.c,v <-- driver.c
6188 new revision: 1.7; previous revision: 1.6
6192 For your protection, @sc{cvs} will refuse to check in a
6193 file if a conflict occurred and you have not resolved
6194 the conflict. Currently to resolve a conflict, you
6195 must change the timestamp on the file. In previous
6196 versions of @sc{cvs}, you also needed to
6197 insure that the file contains no conflict markers.
6199 your file may legitimately contain conflict markers (that
6200 is, occurrences of @samp{>>>>>>> } at the start of a
6201 line that don't mark a conflict), the current
6202 version of @sc{cvs} will print a warning and proceed to
6204 @c The old behavior was really icky; the only way out
6205 @c was to start hacking on
6206 @c the @code{CVS/Entries} file or other such workarounds.
6208 @c If the timestamp thing isn't considered nice enough,
6209 @c maybe there should be a "cvs resolved" command
6210 @c which clears the conflict indication. For a nice user
6211 @c interface, this should be invoked by an interactive
6212 @c merge tool like emerge rather than by the user
6213 @c directly--such a tool can verify that the user has
6214 @c really dealt with each conflict.
6217 If you use release 1.04 or later of pcl-cvs (a @sc{gnu}
6218 Emacs front-end for @sc{cvs}) you can use an Emacs
6219 package called emerge to help you resolve conflicts.
6220 See the documentation for pcl-cvs.
6222 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
6223 @node Informing others
6224 @section Informing others about commits
6225 @cindex Informing others
6226 @cindex Spreading information
6227 @cindex Mail, automatic mail on commit
6229 It is often useful to inform others when you commit a
6230 new revision of a file. The @file{loginfo} file can be
6231 used to automate this process.
6232 @xref{loginfo}. You can use these features of @sc{cvs}
6233 to, for instance, instruct @sc{cvs} to mail a
6234 message to all developers, or post a message to a local
6236 @c -- More text would be nice here.
6239 @section Several developers simultaneously attempting to run CVS
6241 @cindex Locks, cvs, introduction
6242 @c For a discussion of *why* CVS creates locks, see
6243 @c the comment at the start of src/lock.c
6244 If several developers try to run @sc{cvs} at the same
6245 time, one may get the following message:
6248 [11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo
6251 @cindex #cvs.rfl, removing
6252 @cindex #cvs.wfl, removing
6253 @cindex #cvs.lock, removing
6254 @sc{cvs} will try again every 30 seconds, and either
6255 continue with the operation or print the message again,
6256 if it still needs to wait. If a lock seems to stick
6257 around for an undue amount of time, find the person
6258 holding the lock and ask them about the cvs command
6259 they are running. If they aren't running a cvs
6260 command, look in the repository directory mentioned in
6261 the message and remove files which they own whose names
6262 start with @file{#cvs.rfl},
6263 @file{#cvs.wfl}, or @file{#cvs.lock}.
6265 Note that these locks are to protect @sc{cvs}'s
6266 internal data structures and have no relationship to
6267 the word @dfn{lock} in the sense used by
6268 @sc{rcs}---which refers to reserved checkouts
6269 (@pxref{Multiple developers}).
6271 Any number of people can be reading from a given
6272 repository at a time; only when someone is writing do
6273 the locks prevent other people from reading or writing.
6275 @cindex Atomic transactions, lack of
6276 @cindex Transactions, atomic, lack of
6277 @c the following talks about what one might call commit/update
6279 @c Probably also should say something about
6280 @c commit/commit atomicity, that is, "An update will
6281 @c not get partial versions of more than one commit".
6282 @c CVS currently has this property and I guess we can
6283 @c make it a documented feature.
6284 @c For example one person commits
6285 @c a/one.c and b/four.c and another commits a/two.c and
6286 @c b/three.c. Then an update cannot get the new a/one.c
6287 @c and a/two.c and the old b/four.c and b/three.c.
6288 One might hope for the following property:
6291 If someone commits some changes in one cvs command,
6292 then an update by someone else will either get all the
6293 changes, or none of them.
6297 but @sc{cvs} does @emph{not} have this property. For
6298 example, given the files
6311 cvs ci a/two.c b/three.c
6315 and someone else runs @code{cvs update} at the same
6316 time, the person running @code{update} might get only
6317 the change to @file{b/three.c} and not the change to
6321 @section Mechanisms to track who is editing files
6324 For many groups, use of @sc{cvs} in its default mode is
6325 perfectly satisfactory. Users may sometimes go to
6326 check in a modification only to find that another
6327 modification has intervened, but they deal with it and
6328 proceed with their check in. Other groups prefer to be
6329 able to know who is editing what files, so that if two
6330 people try to edit the same file they can choose to
6331 talk about who is doing what when rather than be
6332 surprised at check in time. The features in this
6333 section allow such coordination, while retaining the
6334 ability of two developers to edit the same file at the
6337 @c Some people might ask why CVS does not enforce the
6338 @c rule on chmod, by requiring a cvs edit before a cvs
6339 @c commit. The main reason is that it could always be
6340 @c circumvented--one could edit the file, and
6341 @c then when ready to check it in, do the cvs edit and put
6342 @c in the new contents and do the cvs commit. One
6343 @c implementation note: if we _do_ want to have cvs commit
6344 @c require a cvs edit, we should store the state on
6345 @c whether the cvs edit has occurred in the working
6346 @c directory, rather than having the server try to keep
6347 @c track of what working directories exist.
6348 @c FIXME: should the above discussion be part of the
6349 @c manual proper, somewhere, not just in a comment?
6350 For maximum benefit developers should use @code{cvs
6351 edit} (not @code{chmod}) to make files read-write to
6352 edit them, and @code{cvs release} (not @code{rm}) to
6353 discard a working directory which is no longer in use,
6354 but @sc{cvs} is not able to enforce this behavior.
6356 @c I'm a little dissatisfied with this presentation,
6357 @c because "watch on"/"edit"/"editors" are one set of
6358 @c functionality, and "watch add"/"watchers" is another
6359 @c which is somewhat orthogonal even though they interact in
6360 @c various ways. But I think it might be
6361 @c confusing to describe them separately (e.g. "watch
6362 @c add" with loginfo). I don't know.
6365 * Setting a watch:: Telling CVS to watch certain files
6366 * Getting Notified:: Telling CVS to notify you
6367 * Editing files:: How to edit a file which is being watched
6368 * Watch information:: Information about who is watching and editing
6369 * Watches Compatibility:: Watches interact poorly with CVS 1.6 or earlier
6372 @node Setting a watch
6373 @subsection Telling CVS to watch certain files
6375 To enable the watch features, you first specify that
6376 certain files are to be watched.
6378 @cindex watch on (subcommand)
6379 @deffn Command {cvs watch on} [@code{-lR}] [@var{files}]@dots{}
6381 @cindex Read-only files, and watches
6382 Specify that developers should run @code{cvs edit}
6383 before editing @var{files}. @sc{cvs} will create working
6384 copies of @var{files} read-only, to remind developers
6385 to run the @code{cvs edit} command before working on
6388 If @var{files} includes the name of a directory, @sc{cvs}
6389 arranges to watch all files added to the corresponding
6390 repository directory, and sets a default for files
6391 added in the future; this allows the user to set
6392 notification policies on a per-directory basis. The
6393 contents of the directory are processed recursively,
6394 unless the @code{-l} option is given.
6395 The @code{-R} option can be used to force recursion if the @code{-l}
6396 option is set in @file{~/.cvsrc} (@pxref{~/.cvsrc}).
6398 If @var{files} is omitted, it defaults to the current directory.
6400 @cindex watch off (subcommand)
6403 @deffn Command {cvs watch off} [@code{-lR}] [@var{files}]@dots{}
6405 Do not create @var{files} read-only on checkout; thus,
6406 developers will not be reminded to use @code{cvs edit}
6407 and @code{cvs unedit}.
6409 @sc{cvs} will check out @var{files}
6410 read-write as usual, unless other permissions override
6411 due to the @code{PreservePermissions} option being
6412 enabled in the @file{config} administrative file
6413 (@pxref{Special Files}, @pxref{config})
6416 The @var{files} and options are processed as for @code{cvs
6421 @node Getting Notified
6422 @subsection Telling CVS to notify you
6424 You can tell @sc{cvs} that you want to receive
6425 notifications about various actions taken on a file.
6426 You can do this without using @code{cvs watch on} for
6427 the file, but generally you will want to use @code{cvs
6428 watch on}, to remind developers to use the @code{cvs edit}
6431 @cindex watch add (subcommand)
6432 @deffn Command {cvs watch add} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{}
6434 Add the current user to the list of people to receive notification of
6435 work done on @var{files}.
6437 The @code{-a} option specifies what kinds of events @sc{cvs} should notify
6438 the user about. @var{action} is one of the following:
6443 Another user has applied the @code{cvs edit} command (described
6444 below) to a watched file.
6447 Another user has committed changes to one of the named @var{files}.
6450 Another user has abandoned editing a file (other than by committing changes).
6451 They can do this in several ways, by:
6456 applying the @code{cvs unedit} command (described below) to the file
6459 applying the @code{cvs release} command (@pxref{release}) to the file's parent directory
6460 (or recursively to a directory more than one level up)
6463 deleting the file and allowing @code{cvs update} to recreate it
6471 None of the above. (This is useful with @code{cvs edit},
6476 The @code{-a} option may appear more than once, or not at all. If
6477 omitted, the action defaults to @code{all}.
6479 The @var{files} and options are processed as for
6480 @code{cvs watch on}.
6485 @cindex watch remove (subcommand)
6486 @deffn Command {cvs watch remove} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{}
6488 Remove a notification request established using @code{cvs watch add};
6489 the arguments are the same. If the @code{-a} option is present, only
6490 watches for the specified actions are removed.
6494 @cindex notify (admin file)
6495 When the conditions exist for notification, @sc{cvs}
6496 calls the @file{notify} administrative file. Edit
6497 @file{notify} as one edits the other administrative
6498 files (@pxref{Intro administrative files}). This
6499 file follows the usual conventions for administrative
6500 files (@pxref{syntax}), where each line is a regular
6501 expression followed by a command to execute. The
6502 command should contain a single occurrence of @samp{%s}
6503 which will be replaced by the user to notify; the rest
6504 of the information regarding the notification will be
6505 supplied to the command on standard input. The
6506 standard thing to put in the @code{notify} file is the
6510 ALL mail %s -s "CVS notification"
6514 This causes users to be notified by electronic mail.
6515 @c FIXME: should it be this hard to set up this
6516 @c behavior (and the result when one fails to do so,
6517 @c silent failure to notify, so non-obvious)? Should
6518 @c CVS give a warning if no line in notify matches (and
6519 @c document the use of "DEFAULT :" for the case where
6520 @c skipping the notification is indeed desired)?
6522 @cindex users (admin file)
6523 Note that if you set this up in the straightforward
6524 way, users receive notifications on the server machine.
6525 One could of course write a @file{notify} script which
6526 directed notifications elsewhere, but to make this
6527 easy, @sc{cvs} allows you to associate a notification
6528 address for each user. To do so create a file
6529 @file{users} in @file{CVSROOT} with a line for each
6530 user in the format @var{user}:@var{value}. Then
6531 instead of passing the name of the user to be notified
6532 to @file{notify}, @sc{cvs} will pass the @var{value}
6533 (normally an email address on some other machine).
6535 @sc{cvs} does not notify you for your own changes.
6536 Currently this check is done based on whether the user
6537 name of the person taking the action which triggers
6538 notification matches the user name of the person
6539 getting notification. In fact, in general, the watches
6540 features only track one edit by each user. It probably
6541 would be more useful if watches tracked each working
6542 directory separately, so this behavior might be worth
6544 @c "behavior might be worth changing" is an effort to
6545 @c point to future directions while also not promising
6546 @c that "they" (as in "why don't they fix CVS to....")
6548 @c one implementation issue is identifying whether a
6549 @c working directory is same or different. Comparing
6550 @c pathnames/hostnames is hopeless, but having the server
6551 @c supply a serial number which the client stores in the
6552 @c CVS directory as a magic cookie should work.
6555 @subsection How to edit a file which is being watched
6557 @cindex Checkout, as term for getting ready to edit
6558 Since a file which is being watched is checked out
6559 read-only, you cannot simply edit it. To make it
6560 read-write, and inform others that you are planning to
6561 edit it, use the @code{cvs edit} command. Some systems
6562 call this a @dfn{checkout}, but @sc{cvs} uses that term
6563 for obtaining a copy of the sources (@pxref{Getting the
6564 source}), an operation which those systems call a
6565 @dfn{get} or a @dfn{fetch}.
6566 @c Issue to think about: should we transition CVS
6567 @c towards the "get" terminology? "cvs get" is already a
6568 @c synonym for "cvs checkout" and that section of the
6569 @c manual refers to "Getting the source". If this is
6570 @c done, needs to be done gingerly (for example, we should
6571 @c still accept "checkout" in .cvsrc files indefinitely
6572 @c even if the CVS's messages are changed from "cvs checkout: "
6574 @c There is a concern about whether "get" is not as
6575 @c good for novices because it is a more general term
6576 @c than "checkout" (and thus arguably harder to assign
6577 @c a technical meaning for).
6579 @cindex edit (subcommand)
6580 @deffn Command {cvs edit} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{}
6582 Prepare to edit the working files @var{files}. @sc{cvs} makes the
6583 @var{files} read-write, and notifies users who have requested
6584 @code{edit} notification for any of @var{files}.
6586 The @code{cvs edit} command accepts the same options as the
6587 @code{cvs watch add} command, and establishes a temporary watch for the
6588 user on @var{files}; @sc{cvs} will remove the watch when @var{files} are
6589 @code{unedit}ed or @code{commit}ted. If the user does not wish to
6590 receive notifications, she should specify @code{-a none}.
6592 The @var{files} and the options are processed as for the @code{cvs
6596 @strong{Caution: If the @code{PreservePermissions}
6597 option is enabled in the repository (@pxref{config}),
6598 @sc{cvs} will not change the permissions on any of the
6599 @var{files}. The reason for this change is to ensure
6600 that using @samp{cvs edit} does not interfere with the
6601 ability to store file permissions in the @sc{cvs}
6607 Normally when you are done with a set of changes, you
6608 use the @code{cvs commit} command, which checks in your
6609 changes and returns the watched files to their usual
6610 read-only state. But if you instead decide to abandon
6611 your changes, or not to make any changes, you can use
6612 the @code{cvs unedit} command.
6614 @cindex unedit (subcommand)
6615 @cindex Abandoning work
6616 @cindex Reverting to repository version
6617 @deffn Command {cvs unedit} [@code{-lR}] [@var{files}]@dots{}
6619 Abandon work on the working files @var{files}, and revert them to the
6620 repository versions on which they are based. @sc{cvs} makes those
6621 @var{files} read-only for which users have requested notification using
6622 @code{cvs watch on}. @sc{cvs} notifies users who have requested @code{unedit}
6623 notification for any of @var{files}.
6625 The @var{files} and options are processed as for the
6626 @code{cvs watch} commands.
6628 If watches are not in use, the @code{unedit} command
6629 probably does not work, and the way to revert to the
6630 repository version is with the command @code{cvs update -C file}
6633 not precisely the same; the latter may also
6634 bring in some changes which have been made in the
6635 repository since the last time you updated.
6636 @c It would be a useful enhancement to CVS to make
6637 @c unedit work in the non-watch case as well.
6640 When using client/server @sc{cvs}, you can use the
6641 @code{cvs edit} and @code{cvs unedit} commands even if
6642 @sc{cvs} is unable to successfully communicate with the
6643 server; the notifications will be sent upon the next
6644 successful @sc{cvs} command.
6646 @node Watch information
6647 @subsection Information about who is watching and editing
6649 @cindex watchers (subcommand)
6650 @deffn Command {cvs watchers} [@code{-lR}] [@var{files}]@dots{}
6652 List the users currently watching changes to @var{files}. The report
6653 includes the files being watched, and the mail address of each watcher.
6655 The @var{files} and options are processed as for the
6656 @code{cvs watch} commands.
6661 @cindex editors (subcommand)
6662 @deffn Command {cvs editors} [@code{-lR}] [@var{files}]@dots{}
6664 List the users currently working on @var{files}. The report
6665 includes the mail address of each user, the time when the user began
6666 working with the file, and the host and path of the working directory
6667 containing the file.
6669 The @var{files} and options are processed as for the
6670 @code{cvs watch} commands.
6674 @node Watches Compatibility
6675 @subsection Using watches with old versions of CVS
6677 @cindex CVS 1.6, and watches
6678 If you use the watch features on a repository, it
6679 creates @file{CVS} directories in the repository and
6680 stores the information about watches in that directory.
6681 If you attempt to use @sc{cvs} 1.6 or earlier with the
6682 repository, you get an error message such as the
6683 following (all on one line):
6686 cvs update: cannot open CVS/Entries for reading:
6687 No such file or directory
6691 and your operation will likely be aborted. To use the
6692 watch features, you must upgrade all copies of @sc{cvs}
6693 which use that repository in local or server mode. If
6694 you cannot upgrade, use the @code{watch off} and
6695 @code{watch remove} commands to remove all watches, and
6696 that will restore the repository to a state which
6697 @sc{cvs} 1.6 can cope with.
6699 @node Choosing a model
6700 @section Choosing between reserved or unreserved checkouts
6701 @cindex Choosing, reserved or unreserved checkouts
6703 Reserved and unreserved checkouts each have pros and
6704 cons. Let it be said that a lot of this is a matter of
6705 opinion or what works given different groups' working
6706 styles, but here is a brief description of some of the
6707 issues. There are many ways to organize a team of
6708 developers. @sc{cvs} does not try to enforce a certain
6709 organization. It is a tool that can be used in several
6712 Reserved checkouts can be very counter-productive. If
6713 two persons want to edit different parts of a file,
6714 there may be no reason to prevent either of them from
6715 doing so. Also, it is common for someone to take out a
6716 lock on a file, because they are planning to edit it,
6717 but then forget to release the lock.
6719 @c "many groups"? specifics? cites to papers on this?
6720 @c some way to weasel-word it a bit more so we don't
6722 People, especially people who are familiar with
6723 reserved checkouts, often wonder how often conflicts
6724 occur if unreserved checkouts are used, and how
6725 difficult they are to resolve. The experience with
6726 many groups is that they occur rarely and usually are
6727 relatively straightforward to resolve.
6729 The rarity of serious conflicts may be surprising, until one realizes
6730 that they occur only when two developers disagree on the proper design
6731 for a given section of code; such a disagreement suggests that the
6732 team has not been communicating properly in the first place. In order
6733 to collaborate under @emph{any} source management regimen, developers
6734 must agree on the general design of the system; given this agreement,
6735 overlapping changes are usually straightforward to merge.
6737 In some cases unreserved checkouts are clearly
6738 inappropriate. If no merge tool exists for the kind of
6739 file you are managing (for example word processor files
6740 or files edited by Computer Aided Design programs), and
6741 it is not desirable to change to a program which uses a
6742 mergeable data format, then resolving conflicts is
6743 going to be unpleasant enough that you generally will
6744 be better off to simply avoid the conflicts instead, by
6745 using reserved checkouts.
6747 The watches features described above in @ref{Watches}
6748 can be considered to be an intermediate model between
6749 reserved checkouts and unreserved checkouts. When you
6750 go to edit a file, it is possible to find out who else
6751 is editing it. And rather than having the system
6752 simply forbid both people editing the file, it can tell
6753 you what the situation is and let you figure out
6754 whether it is a problem in that particular case or not.
6755 Therefore, for some groups it can be considered the
6756 best of both the reserved checkout and unreserved
6759 @c ---------------------------------------------------------------------
6760 @node Revision management
6761 @chapter Revision management
6762 @cindex Revision management
6764 @c -- This chapter could be expanded a lot.
6765 @c -- Experiences are very welcome!
6767 If you have read this far, you probably have a pretty
6768 good grasp on what @sc{cvs} can do for you. This
6769 chapter talks a little about things that you still have
6772 If you are doing development on your own using @sc{cvs}
6773 you could probably skip this chapter. The questions
6774 this chapter takes up become more important when more
6775 than one person is working in a repository.
6778 * When to commit:: Some discussion on the subject
6781 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
6782 @node When to commit
6783 @section When to commit?
6784 @cindex When to commit
6785 @cindex Committing, when to
6788 Your group should decide which policy to use regarding
6789 commits. Several policies are possible, and as your
6790 experience with @sc{cvs} grows you will probably find
6791 out what works for you.
6793 If you commit files too quickly you might commit files
6794 that do not even compile. If your partner updates his
6795 working sources to include your buggy file, he will be
6796 unable to compile the code. On the other hand, other
6797 persons will not be able to benefit from the
6798 improvements you make to the code if you commit very
6799 seldom, and conflicts will probably be more common.
6801 It is common to only commit files after making sure
6802 that they can be compiled. Some sites require that the
6803 files pass a test suite. Policies like this can be
6804 enforced using the commitinfo file
6805 (@pxref{commitinfo}), but you should think twice before
6806 you enforce such a convention. By making the
6807 development environment too controlled it might become
6808 too regimented and thus counter-productive to the real
6809 goal, which is to get software written.
6811 @c ---------------------------------------------------------------------
6812 @node Keyword substitution
6813 @chapter Keyword substitution
6814 @cindex Keyword substitution
6815 @cindex Keyword expansion
6816 @cindex Identifying files
6818 @comment Be careful when editing this chapter.
6819 @comment Remember that this file is kept under
6820 @comment version control, so we must not accidentally
6821 @comment include a valid keyword in the running text.
6823 As long as you edit source files inside a working
6824 directory you can always find out the state of
6825 your files via @samp{cvs status} and @samp{cvs log}.
6826 But as soon as you export the files from your
6827 development environment it becomes harder to identify
6828 which revisions they are.
6830 @sc{cvs} can use a mechanism known as @dfn{keyword
6831 substitution} (or @dfn{keyword expansion}) to help
6832 identifying the files. Embedded strings of the form
6833 @code{$@var{keyword}$} and
6834 @code{$@var{keyword}:@dots{}$} in a file are replaced
6835 with strings of the form
6836 @code{$@var{keyword}:@var{value}$} whenever you obtain
6837 a new revision of the file.
6840 * Keyword list:: Keywords
6841 * Using keywords:: Using keywords
6842 * Avoiding substitution:: Avoiding substitution
6843 * Substitution modes:: Substitution modes
6844 * Log keyword:: Problems with the $@splitrcskeyword{Log}$ keyword.
6847 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
6849 @section Keyword List
6850 @cindex Keyword List
6852 @c FIXME: need some kind of example here I think,
6854 @c "Keyword intro" node. The intro in the "Keyword
6855 @c substitution" node itself seems OK, but to launch
6856 @c into a list of the keywords somehow seems too abrupt.
6858 This is a list of the keywords:
6861 @cindex Author keyword
6862 @item $@splitrcskeyword{Author}$
6863 The login name of the user who checked in the revision.
6865 @cindex Date keyword
6866 @item $@splitrcskeyword{Date}$
6867 The date and time (UTC) the revision was checked in.
6869 @cindex Header keyword
6870 @item $@splitrcskeyword{Header}$
6871 A standard header containing the full pathname of the
6872 @sc{rcs} file, the revision number, the date (UTC), the
6873 author, the state, and the locker (if locked). Files
6874 will normally never be locked when you use @sc{cvs}.
6877 @item $@splitrcskeyword{Id}$
6878 Same as @code{$@splitrcskeyword{Header}$}, except that the @sc{rcs}
6879 filename is without a path.
6881 @cindex Name keyword
6882 @item $@splitrcskeyword{Name}$
6883 Tag name used to check out this file. The keyword is
6884 expanded only if one checks out with an explicit tag
6885 name. For example, when running the command @code{cvs
6886 co -r first}, the keyword expands to @samp{Name: first}.
6888 @cindex Locker keyword
6889 @item $@splitrcskeyword{Locker}$
6890 The login name of the user who locked the revision
6891 (empty if not locked, which is the normal case unless
6892 @code{cvs admin -l} is in use).
6895 @item $@splitrcskeyword{Log}$
6896 The log message supplied during commit, preceded by a
6897 header containing the @sc{rcs} filename, the revision
6898 number, the author, and the date (UTC). Existing log
6899 messages are @emph{not} replaced. Instead, the new log
6900 message is inserted after @code{$@splitrcskeyword{Log}:@dots{}$}.
6901 Each new line is prefixed with the same string which
6902 precedes the @code{$Log} keyword. For example, if the
6906 /* Here is what people have been up to:
6908 * $@splitrcskeyword{Log}: frob.c,v $
6909 * Revision 1.1 1997/01/03 14:23:51 joe
6910 * Add the superfrobnicate option
6916 then additional lines which are added when expanding
6917 the @code{$Log} keyword will be preceded by @samp{ * }.
6918 Unlike previous versions of @sc{cvs} and @sc{rcs}, the
6919 @dfn{comment leader} from the @sc{rcs} file is not used.
6920 The @code{$Log} keyword is useful for
6921 accumulating a complete change log in a source file,
6922 but for several reasons it can be problematic.
6925 @cindex RCSfile keyword
6926 @item $@splitrcskeyword{RCSfile}$
6927 The name of the RCS file without a path.
6929 @cindex Revision keyword
6930 @item $@splitrcskeyword{Revision}$
6931 The revision number assigned to the revision.
6933 @cindex Source keyword
6934 @item $@splitrcskeyword{Source}$
6935 The full pathname of the RCS file.
6937 @cindex State keyword
6938 @item $@splitrcskeyword{State}$
6939 The state assigned to the revision. States can be
6940 assigned with @code{cvs admin -s}---see @ref{admin options}.
6944 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
6945 @node Using keywords
6946 @section Using keywords
6948 To include a keyword string you simply include the
6949 relevant text string, such as @code{$@splitrcskeyword{Id}$}, inside the
6950 file, and commit the file. @sc{cvs} will automatically (Or,
6951 more accurately, as part of the update run that
6952 automatically happens after a commit.)
6953 expand the string as part of the commit operation.
6955 It is common to embed the @code{$@splitrcskeyword{Id}$} string in
6956 the source files so that it gets passed through to
6957 generated files. For example, if you are managing
6958 computer program source code, you might include a
6959 variable which is initialized to contain that string.
6960 Or some C compilers may provide a @code{#pragma ident}
6961 directive. Or a document management system might
6962 provide a way to pass a string through to generated
6965 @c Would be nice to give an example, but doing this in
6966 @c portable C is not possible and the problem with
6967 @c picking any one language (VMS HELP files, Ada,
6968 @c troff, whatever) is that people use CVS for all
6971 @cindex Ident (shell command)
6972 The @code{ident} command (which is part of the @sc{rcs}
6973 package) can be used to extract keywords and their
6974 values from a file. This can be handy for text files,
6975 but it is even more useful for extracting keywords from
6981 $@splitrcskeyword{Id}: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
6985 $@splitrcskeyword{Id}: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
6988 @cindex What (shell command)
6989 S@sc{ccs} is another popular revision control system.
6990 It has a command, @code{what}, which is very similar to
6991 @code{ident} and used for the same purpose. Many sites
6992 without @sc{rcs} have @sc{sccs}. Since @code{what}
6993 looks for the character sequence @code{@@(#)} it is
6994 easy to include keywords that are detected by either
6995 command. Simply prefix the keyword with the
6996 magic @sc{sccs} phrase, like this:
6999 static char *id="@@(#) $@splitrcskeyword{Id}: ab.c,v 1.5 1993/10/19 14:57:32 ceder Exp $";
7002 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
7003 @node Avoiding substitution
7004 @section Avoiding substitution
7006 Keyword substitution has its disadvantages. Sometimes
7007 you might want the literal text string
7008 @samp{$@splitrcskeyword{Author}$} to appear inside a file without
7009 @sc{cvs} interpreting it as a keyword and expanding it
7010 into something like @samp{$@splitrcskeyword{Author}: ceder $}.
7012 There is unfortunately no way to selectively turn off
7013 keyword substitution. You can use @samp{-ko}
7014 (@pxref{Substitution modes}) to turn off keyword
7015 substitution entirely.
7017 In many cases you can avoid using keywords in
7018 the source, even though they appear in the final
7019 product. For example, the source for this manual
7020 contains @samp{$@@asis@{@}Author$} whenever the text
7021 @samp{$@splitrcskeyword{Author}$} should appear. In @code{nroff}
7022 and @code{troff} you can embed the null-character
7023 @code{\&} inside the keyword for a similar effect.
7025 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
7026 @node Substitution modes
7027 @section Substitution modes
7028 @cindex Keyword substitution, changing modes
7029 @cindex -k (keyword substitution)
7032 @c FIXME: This could be made more coherent, by expanding it
7033 @c with more examples or something.
7034 Each file has a stored default substitution mode, and
7035 each working directory copy of a file also has a
7036 substitution mode. The former is set by the @samp{-k}
7037 option to @code{cvs add} and @code{cvs admin}; the
7038 latter is set by the @samp{-k} or @samp{-A} options to @code{cvs
7039 checkout} or @code{cvs update}.
7040 @code{cvs diff} and @code{cvs rdiff} also
7041 have @samp{-k} options.
7043 see @ref{Binary files}, and @ref{Merging and keywords}.
7044 @c The fact that -A is overloaded to mean both reset
7045 @c sticky options and reset sticky tags/dates is
7046 @c somewhat questionable. Perhaps there should be
7047 @c separate options to reset sticky options (e.g. -k
7048 @c A") and tags/dates (someone suggested -r HEAD could
7049 @c do this instead of setting a sticky tag of "HEAD"
7050 @c as in the status quo but I haven't thought much
7051 @c about that idea. Of course -r .reset or something
7052 @c could be coined if this needs to be a new option).
7053 @c On the other hand, having -A mean "get things back
7054 @c into the state after a fresh checkout" has a certain
7055 @c appeal, and maybe there is no sufficient reason for
7056 @c creeping featurism in this area.
7058 The modes available are:
7062 Generate keyword strings using the default form, e.g.
7063 @code{$@splitrcskeyword{Revision}: 5.7 $} for the @code{Revision}
7067 Like @samp{-kkv}, except that a locker's name is always
7068 inserted if the given revision is currently locked.
7069 The locker's name is only relevant if @code{cvs admin
7073 Generate only keyword names in keyword strings; omit
7074 their values. For example, for the @code{Revision}
7075 keyword, generate the string @code{$@splitrcskeyword{Revision}$}
7076 instead of @code{$@splitrcskeyword{Revision}: 5.7 $}. This option
7077 is useful to ignore differences due to keyword
7078 substitution when comparing different revisions of a
7079 file (@pxref{Merging and keywords}).
7082 Generate the old keyword string, present in the working
7083 file just before it was checked in. For example, for
7084 the @code{Revision} keyword, generate the string
7085 @code{$@splitrcskeyword{Revision}: 1.1 $} instead of
7086 @code{$@splitrcskeyword{Revision}: 5.7 $} if that is how the
7087 string appeared when the file was checked in.
7090 Like @samp{-ko}, but also inhibit conversion of line
7091 endings between the canonical form in which they are
7092 stored in the repository (linefeed only), and the form
7093 appropriate to the operating system in use on the
7094 client. For systems, like unix, which use linefeed
7095 only to terminate lines, this is the same as
7096 @samp{-ko}. For more information on binary files, see
7100 Generate only keyword values for keyword strings. For
7101 example, for the @code{Revision} keyword, generate the string
7102 @code{5.7} instead of @code{$@splitrcskeyword{Revision}: 5.7 $}.
7103 This can help generate files in programming languages
7104 where it is hard to strip keyword delimiters like
7105 @code{$@splitrcskeyword{Revision}: $} from a string. However,
7106 further keyword substitution cannot be performed once
7107 the keyword names are removed, so this option should be
7110 One often would like to use @samp{-kv} with @code{cvs
7111 export}---@pxref{export}. But be aware that doesn't
7112 handle an export containing binary files correctly.
7116 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
7118 @section Problems with the $@splitrcskeyword{Log}$ keyword.
7120 The @code{$@splitrcskeyword{Log}$} keyword is somewhat
7121 controversial. As long as you are working on your
7122 development system the information is easily accessible
7123 even if you do not use the @code{$@splitrcskeyword{Log}$}
7124 keyword---just do a @code{cvs log}. Once you export
7125 the file the history information might be useless
7128 A more serious concern is that @sc{cvs} is not good at
7129 handling @code{$@splitrcskeyword{Log}$} entries when a branch is
7130 merged onto the main trunk. Conflicts often result
7131 from the merging operation.
7132 @c Might want to check whether the CVS implementation
7133 @c of RCS_merge has this problem the same way rcsmerge
7134 @c does. I would assume so....
7136 People also tend to "fix" the log entries in the file
7137 (correcting spelling mistakes and maybe even factual
7138 errors). If that is done the information from
7139 @code{cvs log} will not be consistent with the
7140 information inside the file. This may or may not be a
7141 problem in real life.
7143 It has been suggested that the @code{$@splitrcskeyword{Log}$}
7144 keyword should be inserted @emph{last} in the file, and
7145 not in the files header, if it is to be used at all.
7146 That way the long list of change messages will not
7147 interfere with everyday source file browsing.
7149 @c ---------------------------------------------------------------------
7150 @node Tracking sources
7151 @chapter Tracking third-party sources
7152 @cindex Third-party sources
7153 @cindex Tracking sources
7155 @c FIXME: Need discussion of added and removed files.
7156 @c FIXME: This doesn't really adequately introduce the
7157 @c concepts of "vendor" and "you". They don't *have*
7158 @c to be separate organizations or separate people.
7159 @c We want a description which is somewhat more based on
7160 @c the technical issues of which sources go where, but
7161 @c also with enough examples of how this relates to
7162 @c relationships like customer-supplier, developer-QA,
7163 @c maintainer-contributor, or whatever, to make it
7165 If you modify a program to better fit your site, you
7166 probably want to include your modifications when the next
7167 release of the program arrives. @sc{cvs} can help you with
7171 @cindex Vendor branch
7172 @cindex Branch, vendor-
7173 In the terminology used in @sc{cvs}, the supplier of the
7174 program is called a @dfn{vendor}. The unmodified
7175 distribution from the vendor is checked in on its own
7176 branch, the @dfn{vendor branch}. @sc{cvs} reserves branch
7179 When you modify the source and commit it, your revision
7180 will end up on the main trunk. When a new release is
7181 made by the vendor, you commit it on the vendor branch
7182 and copy the modifications onto the main trunk.
7184 Use the @code{import} command to create and update
7185 the vendor branch. When you import a new file,
7186 the vendor branch is made the `head' revision, so
7187 anyone that checks out a copy of the file gets that
7188 revision. When a local modification is committed it is
7189 placed on the main trunk, and made the `head'
7193 * First import:: Importing for the first time
7194 * Update imports:: Updating with the import command
7195 * Reverting local changes:: Reverting to the latest vendor release
7196 * Binary files in imports:: Binary files require special handling
7197 * Keywords in imports:: Keyword substitution might be undesirable
7198 * Multiple vendor branches:: What if you get sources from several places?
7201 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
7203 @section Importing for the first time
7204 @cindex Importing modules
7206 @c Should mention naming conventions for vendor tags,
7207 @c release tags, and perhaps directory names.
7208 Use the @code{import} command to check in the sources
7209 for the first time. When you use the @code{import}
7210 command to track third-party sources, the @dfn{vendor
7211 tag} and @dfn{release tags} are useful. The
7212 @dfn{vendor tag} is a symbolic name for the branch
7213 (which is always 1.1.1, unless you use the @samp{-b
7214 @var{branch}} flag---see @ref{Multiple vendor branches}.). The
7215 @dfn{release tags} are symbolic names for a particular
7216 release, such as @samp{FSF_0_04}.
7218 @c I'm not completely sure this belongs here. But
7219 @c we need to say it _somewhere_ reasonably obvious; it
7220 @c is a common misconception among people first learning CVS
7221 Note that @code{import} does @emph{not} change the
7222 directory in which you invoke it. In particular, it
7223 does not set up that directory as a @sc{cvs} working
7224 directory; if you want to work with the sources import
7225 them first and then check them out into a different
7226 directory (@pxref{Getting the source}).
7228 @cindex wdiff (import example)
7229 Suppose you have the sources to a program called
7230 @code{wdiff} in a directory @file{wdiff-0.04},
7231 and are going to make private modifications that you
7232 want to be able to use even when new releases are made
7233 in the future. You start by importing the source to
7238 $ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04
7241 The vendor tag is named @samp{FSF_DIST} in the above
7242 example, and the only release tag assigned is
7244 @c FIXME: Need to say where fsf/wdiff comes from.
7246 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
7247 @node Update imports
7248 @section Updating with the import command
7250 When a new release of the source arrives, you import it into the
7251 repository with the same @code{import} command that you used to set up
7252 the repository in the first place. The only difference is that you
7253 specify a different release tag this time:
7256 $ tar xfz wdiff-0.05.tar.gz
7258 $ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF_DIST WDIFF_0_05
7261 @strong{WARNING: If you use a release tag that already exists in one of the
7262 repository archives, files removed by an import may not be detected.}
7264 For files that have not been modified locally, the newly created
7265 revision becomes the head revision. If you have made local
7266 changes, @code{import} will warn you that you must merge the changes
7267 into the main trunk, and tell you to use @samp{checkout -j} to do so:
7269 @c FIXME: why "wdiff" here and "fsf/wdiff" in the
7270 @c "import"? I think the assumption is that one has
7271 @c "wdiff fsf/wdiff" or some such in modules, but it
7272 @c would be better to not use modules in this example.
7274 $ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff
7278 The above command will check out the latest revision of
7279 @samp{wdiff}, merging the changes made on the vendor branch @samp{FSF_DIST}
7280 since yesterday into the working copy. If any conflicts arise during
7281 the merge they should be resolved in the normal way (@pxref{Conflicts
7282 example}). Then, the modified files may be committed.
7284 However, it is much better to use the two release tags rather than using
7285 a date on the branch as suggested above:
7288 $ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff
7292 The reason this is better is that
7293 using a date, as suggested above, assumes that you do
7294 not import more than one release of a product per day.
7295 More importantly, using the release tags allows @sc{cvs} to detect files
7296 that were removed between the two vendor releases and mark them for
7297 removal. Since @code{import} has no way to detect removed files, you
7298 should do a merge like this even if @code{import} doesn't tell you to.
7300 @node Reverting local changes
7301 @section Reverting to the latest vendor release
7303 You can also revert local changes completely and return
7304 to the latest vendor release by changing the `head'
7305 revision back to the vendor branch on all files. For
7306 example, if you have a checked-out copy of the sources
7307 in @file{~/work.d/wdiff}, and you want to revert to the
7308 vendor's version for all the files in that directory,
7313 $ cvs admin -bFSF_DIST .
7317 You must specify the @samp{-bFSF_DIST} without any space
7318 after the @samp{-b}. @xref{admin options}.
7320 @node Binary files in imports
7321 @section How to handle binary files with cvs import
7323 Use the @samp{-k} wrapper option to tell import which
7324 files are binary. @xref{Wrappers}.
7326 @node Keywords in imports
7327 @section How to handle keyword substitution with cvs import
7329 The sources which you are importing may contain
7330 keywords (@pxref{Keyword substitution}). For example,
7331 the vendor may use @sc{cvs} or some other system
7332 which uses similar keyword expansion syntax. If you
7333 just import the files in the default fashion, then
7334 the keyword expansions supplied by the vendor will
7335 be replaced by keyword expansions supplied by your
7336 own copy of @sc{cvs}. It may be more convenient to
7337 maintain the expansions supplied by the vendor, so
7338 that this information can supply information about
7339 the sources that you imported from the vendor.
7341 To maintain the keyword expansions supplied by the
7342 vendor, supply the @samp{-ko} option to @code{cvs
7343 import} the first time you import the file.
7344 This will turn off keyword expansion
7345 for that file entirely, so if you want to be more
7346 selective you'll have to think about what you want
7347 and use the @samp{-k} option to @code{cvs update} or
7348 @code{cvs admin} as appropriate.
7349 @c Supplying -ko to import if the file already existed
7350 @c has no effect. Not clear to me whether it should
7353 @node Multiple vendor branches
7354 @section Multiple vendor branches
7356 All the examples so far assume that there is only one
7357 vendor from which you are getting sources. In some
7358 situations you might get sources from a variety of
7359 places. For example, suppose that you are dealing with
7360 a project where many different people and teams are
7361 modifying the software. There are a variety of ways to
7362 handle this, but in some cases you have a bunch of
7363 source trees lying around and what you want to do more
7364 than anything else is just to all put them in @sc{cvs} so
7365 that you at least have them in one place.
7367 For handling situations in which there may be more than
7368 one vendor, you may specify the @samp{-b} option to
7369 @code{cvs import}. It takes as an argument the vendor
7370 branch to import to. The default is @samp{-b 1.1.1}.
7372 For example, suppose that there are two teams, the red
7373 team and the blue team, that are sending you sources.
7374 You want to import the red team's efforts to branch
7375 1.1.1 and use the vendor tag RED. You want to import
7376 the blue team's efforts to branch 1.1.3 and use the
7377 vendor tag BLUE. So the commands you might use are:
7380 $ cvs import dir RED RED_1-0
7381 $ cvs import -b 1.1.3 dir BLUE BLUE_1-5
7384 Note that if your vendor tag does not match your
7385 @samp{-b} option, @sc{cvs} will not detect this case! For
7389 $ cvs import -b 1.1.3 dir RED RED_1-0
7393 Be careful; this kind of mismatch is sure to sow
7394 confusion or worse. I can't think of a useful purpose
7395 for the ability to specify a mismatch here, but if you
7396 discover such a use, don't. @sc{cvs} is likely to make this
7397 an error in some future release.
7399 @c Probably should say more about the semantics of
7400 @c multiple branches. What about the default branch?
7401 @c What about joining (perhaps not as useful with
7402 @c multiple branches, or perhaps it is. Either way
7403 @c should be mentioned).
7405 @c I'm not sure about the best location for this. In
7406 @c one sense, it might belong right after we've introduced
7407 @c CVS's basic version control model, because people need
7408 @c to figure out builds right away. The current location
7409 @c is based on the theory that it kind of akin to the
7410 @c "Revision management" section.
7412 @chapter How your build system interacts with CVS
7416 As mentioned in the introduction, @sc{cvs} does not
7417 contain software for building your software from source
7418 code. This section describes how various aspects of
7419 your build system might interact with @sc{cvs}.
7421 @c Is there a way to discuss this without reference to
7422 @c tools other than CVS? I'm not sure there is; I
7423 @c wouldn't think that people who learn CVS first would
7424 @c even have this concern.
7425 One common question, especially from people who are
7426 accustomed to @sc{rcs}, is how to make their build get
7427 an up to date copy of the sources. The answer to this
7428 with @sc{cvs} is two-fold. First of all, since
7429 @sc{cvs} itself can recurse through directories, there
7430 is no need to modify your @file{Makefile} (or whatever
7431 configuration file your build tool uses) to make sure
7432 each file is up to date. Instead, just use two
7433 commands, first @code{cvs -q update} and then
7434 @code{make} or whatever the command is to invoke your
7435 build tool. Secondly, you do not necessarily
7436 @emph{want} to get a copy of a change someone else made
7437 until you have finished your own work. One suggested
7438 approach is to first update your sources, then
7439 implement, build and
7440 test the change you were thinking of, and then commit
7441 your sources (updating first if necessary). By
7442 periodically (in between changes, using the approach
7443 just described) updating your entire tree, you ensure
7444 that your sources are sufficiently up to date.
7446 @cindex Bill of materials
7447 One common need is to record which versions of which
7448 source files went into a particular build. This kind
7449 of functionality is sometimes called @dfn{bill of
7450 materials} or something similar. The best way to do
7451 this with @sc{cvs} is to use the @code{tag} command to
7452 record which versions went into a given build
7455 Using @sc{cvs} in the most straightforward manner
7456 possible, each developer will have a copy of the entire
7457 source tree which is used in a particular build. If
7458 the source tree is small, or if developers are
7459 geographically dispersed, this is the preferred
7460 solution. In fact one approach for larger projects is
7461 to break a project down into smaller
7462 @c I say subsystem instead of module because they may or
7463 @c may not use the modules file.
7464 separately-compiled subsystems, and arrange a way of
7465 releasing them internally so that each developer need
7466 check out only those subsystems which they are
7467 actively working on.
7469 Another approach is to set up a structure which allows
7470 developers to have their own copies of some files, and
7471 for other files to access source files from a central
7472 location. Many people have come up with some such a
7473 @c two such people are paul@sander.cupertino.ca.us (for
7474 @c a previous employer)
7475 @c and gunnar.tornblom@se.abb.com (spicm and related tools),
7476 @c but as far as I know
7477 @c no one has nicely packaged or released such a system (or
7478 @c instructions for constructing one).
7479 system using features such as the symbolic link feature
7480 found in many operating systems, or the @code{VPATH}
7481 feature found in many versions of @code{make}. One build
7482 tool which is designed to help with this kind of thing
7484 @code{ftp://ftp.cs.colorado.edu/pub/distribs/odin}).
7485 @c Should we be saying more about Odin? Or how you use
7486 @c it with CVS? Also, the Prime Time Freeware for Unix
7487 @c disk (see http://www.ptf.com/) has Odin (with a nice
7488 @c paragraph summarizing it on the web), so that might be a
7489 @c semi-"official" place to point people.
7491 @c Of course, many non-CVS systems have this kind of
7492 @c functionality, for example OSF's ODE
7493 @c (http://www.osf.org/ode/) or mk
7494 @c (http://www.grin.net/~pzi/mk-3.18.4.docs/mk_toc.html
7495 @c He has changed providers in the past; a search engine search
7496 @c for "Peter Ziobrzynski" probably won't get too many
7497 @c spurious hits :-). A more stable URL might be
7498 @c ftp://ftp.uu.net/pub/cmvc/mk). But I'm not sure
7499 @c there is any point in mentioning them here unless they
7500 @c can work with CVS.
7502 @c ---------------------------------------------------------------------
7504 @chapter Special Files
7506 @cindex Special files
7507 @cindex Device nodes
7508 @cindex Ownership, saving in CVS
7509 @cindex Permissions, saving in CVS
7511 @cindex Symbolic links
7513 In normal circumstances, @sc{cvs} works only with regular
7514 files. Every file in a project is assumed to be
7515 persistent; it must be possible to open, read and close
7516 them; and so on. @sc{cvs} also ignores file permissions and
7517 ownerships, leaving such issues to be resolved by the
7518 developer at installation time. In other words, it is
7519 not possible to "check in" a device into a repository;
7520 if the device file cannot be opened, @sc{cvs} will refuse to
7521 handle it. Files also lose their ownerships and
7522 permissions during repository transactions.
7525 If the configuration variable @code{PreservePermissions}
7526 (@pxref{config}) is set in the repository, @sc{cvs} will
7527 save the following file characteristics in the
7531 @item user and group ownership
7533 @item major and minor device numbers
7534 @item symbolic links
7535 @item hard link structure
7538 Using the @code{PreservePermissions} option affects the
7539 behavior of @sc{cvs} in several ways. First, some of the
7540 new operations supported by @sc{cvs} are not accessible to
7541 all users. In particular, file ownership and special
7542 file characteristics may only be changed by the
7543 superuser. When the @code{PreservePermissions}
7544 configuration variable is set, therefore, users will
7545 have to be `root' in order to perform @sc{cvs} operations.
7547 When @code{PreservePermissions} is in use, some @sc{cvs}
7548 operations (such as @samp{cvs status}) will not
7549 recognize a file's hard link structure, and so will
7550 emit spurious warnings about mismatching hard links.
7551 The reason is that @sc{cvs}'s internal structure does not
7552 make it easy for these operations to collect all the
7553 necessary data about hard links, so they check for file
7554 conflicts with inaccurate data.
7556 A more subtle difference is that @sc{cvs} considers a file
7557 to have changed only if its contents have changed
7558 (specifically, if the modification time of the working
7559 file does not match that of the repository's file).
7560 Therefore, if only the permissions, ownership or hard
7561 linkage have changed, or if a device's major or minor
7562 numbers have changed, @sc{cvs} will not notice. In order to
7563 commit such a change to the repository, you must force
7564 the commit with @samp{cvs commit -f}. This also means
7565 that if a file's permissions have changed and the
7566 repository file is newer than the working copy,
7567 performing @samp{cvs update} will silently change the
7568 permissions on the working copy.
7570 Changing hard links in a @sc{cvs} repository is particularly
7571 delicate. Suppose that file @file{foo} is linked to
7572 file @file{old}, but is later relinked to file
7573 @file{new}. You can wind up in the unusual situation
7574 where, although @file{foo}, @file{old} and @file{new}
7575 have all had their underlying link patterns changed,
7576 only @file{foo} and @file{new} have been modified, so
7577 @file{old} is not considered a candidate for checking
7578 in. It can be very easy to produce inconsistent
7579 results this way. Therefore, we recommend that when it
7580 is important to save hard links in a repository, the
7581 prudent course of action is to @code{touch} any file
7582 whose linkage or status has changed since the last
7583 checkin. Indeed, it may be wise to @code{touch *}
7584 before each commit in a directory with complex hard
7587 It is worth noting that only regular files may
7588 be merged, for reasons that hopefully are obvious. If
7589 @samp{cvs update} or @samp{cvs checkout -j} attempts to
7590 merge a symbolic link with a regular file, or two
7591 device files for different kinds of devices, @sc{cvs} will
7592 report a conflict and refuse to perform the merge. At
7593 the same time, @samp{cvs diff} will not report any
7594 differences between these files, since no meaningful
7595 textual comparisons can be made on files which contain
7598 The @code{PreservePermissions} features do not work
7599 with client/server @sc{cvs}. Another limitation is
7600 that hard links must be to other files within the same
7601 directory; hard links across directories are not
7605 @c ---------------------------------------------------------------------
7606 @c ----- START MAN 1 -----
7608 @appendix Guide to CVS commands
7610 This appendix describes the overall structure of
7611 @sc{cvs} commands, and describes some commands in
7612 detail (others are described elsewhere; for a quick
7613 reference to @sc{cvs} commands, @pxref{Invoking CVS}).
7614 @c The idea is that we want to move the commands which
7615 @c are described here into the main body of the manual,
7616 @c in the process reorganizing the manual to be
7617 @c organized around what the user wants to do, not
7618 @c organized around CVS commands.
7620 @c Note that many users do expect a manual which is
7621 @c organized by command. At least some users do.
7622 @c One good addition to the "organized by command"
7623 @c section (if any) would be "see also" links.
7624 @c The awk manual might be a good example; it has a
7625 @c reference manual which is more verbose than Invoking
7626 @c CVS but probably somewhat less verbose than CVS
7630 * Structure:: Overall structure of CVS commands
7631 * Exit status:: Indicating CVS's success or failure
7632 * ~/.cvsrc:: Default options with the ~/.cvsrc file
7633 * Global options:: Options you give to the left of cvs_command
7634 * Common options:: Options you give to the right of cvs_command
7635 * add:: Add files and directories to the repository
7636 * admin:: Administration
7637 * annotate:: What revision modified each line of a file?
7638 * checkout:: Checkout sources for editing
7639 * commit:: Check files into the repository
7640 * diff:: Show differences between revisions
7641 * export:: Export sources from CVS, similar to checkout
7642 * history:: Show status of files and users
7643 * import:: Import sources into CVS, using vendor branches
7644 * log:: Show log messages for files
7645 * rdiff:: 'patch' format diffs between releases
7646 * release:: Indicate that a directory is no longer in use
7647 * remove:: Remove files from active development
7648 * update:: Bring work tree in sync with repository
7651 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
7653 @appendixsec Overall structure of CVS commands
7655 @cindex CVS command structure
7656 @cindex Command structure
7657 @cindex Format of CVS commands
7659 The overall format of all @sc{cvs} commands is:
7662 cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ]
7667 The name of the @sc{cvs} program.
7670 Some options that affect all sub-commands of @sc{cvs}. These are
7674 One of several different sub-commands. Some of the commands have
7675 aliases that can be used instead; those aliases are noted in the
7676 reference manual for that command. There are only two situations
7677 where you may omit @samp{cvs_command}: @samp{cvs -H} elicits a
7678 list of available commands, and @samp{cvs -v} displays version
7679 information on @sc{cvs} itself.
7681 @item command_options
7682 Options that are specific for the command.
7685 Arguments to the commands.
7688 There is unfortunately some confusion between
7689 @code{cvs_options} and @code{command_options}.
7690 When given as a @code{cvs_option}, some options only
7691 affect some of the commands. When given as a
7692 @code{command_option} it may have a different meaning, and
7693 be accepted by more commands. In other words, do not
7694 take the above categorization too seriously. Look at
7695 the documentation instead.
7698 @appendixsec CVS's exit status
7699 @cindex Exit status, of CVS
7701 @sc{cvs} can indicate to the calling environment whether it
7702 succeeded or failed by setting its @dfn{exit status}.
7703 The exact way of testing the exit status will vary from
7704 one operating system to another. For example in a unix
7705 shell script the @samp{$?} variable will be 0 if the
7706 last command returned a successful exit status, or
7707 greater than 0 if the exit status indicated failure.
7709 If @sc{cvs} is successful, it returns a successful status;
7710 if there is an error, it prints an error message and
7711 returns a failure status. The one exception to this is
7712 the @code{cvs diff} command. It will return a
7713 successful status if it found no differences, or a
7714 failure status if there were differences or if there
7715 was an error. Because this behavior provides no good
7716 way to detect errors, in the future it is possible that
7717 @code{cvs diff} will be changed to behave like the
7718 other @sc{cvs} commands.
7719 @c It might seem like checking whether cvs -q diff
7720 @c produces empty or non-empty output can tell whether
7721 @c there were differences or not. But it seems like
7722 @c there are cases with output but no differences
7723 @c (testsuite basica-8b). It is not clear to me how
7724 @c useful it is for a script to be able to check
7725 @c whether there were differences.
7726 @c FIXCVS? In previous versions of CVS, cvs diff
7727 @c returned 0 for no differences, 1 for differences, or
7728 @c 2 for errors. Is this behavior worth trying to
7729 @c bring back (but what does it mean for VMS?)?
7731 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
7733 @appendixsec Default options and the ~/.cvsrc file
7735 @cindex Option defaults
7737 There are some @code{command_options} that are used so
7738 often that you might have set up an alias or some other
7739 means to make sure you always specify that option. One
7740 example (the one that drove the implementation of the
7741 @file{.cvsrc} support, actually) is that many people find the
7742 default output of the @samp{diff} command to be very
7743 hard to read, and that either context diffs or unidiffs
7744 are much easier to understand.
7746 The @file{~/.cvsrc} file is a way that you can add
7747 default options to @code{cvs_commands} within cvs,
7748 instead of relying on aliases or other shell scripts.
7750 The format of the @file{~/.cvsrc} file is simple. The
7751 file is searched for a line that begins with the same
7752 name as the @code{cvs_command} being executed. If a
7753 match is found, then the remainder of the line is split
7754 up (at whitespace characters) into separate options and
7755 added to the command arguments @emph{before} any
7756 options from the command line.
7758 If a command has two names (e.g., @code{checkout} and
7759 @code{co}), the official name, not necessarily the one
7760 used on the command line, will be used to match against
7761 the file. So if this is the contents of the user's
7762 @file{~/.cvsrc} file:
7774 the command @samp{cvs checkout foo} would have the
7775 @samp{-P} option added to the arguments, as well as
7778 With the example file above, the output from @samp{cvs
7779 diff foobar} will be in unidiff format. @samp{cvs diff
7780 -c foobar} will provide context diffs, as usual.
7781 Getting "old" format diffs would be slightly more
7782 complicated, because @code{diff} doesn't have an option
7783 to specify use of the "old" format, so you would need
7784 @samp{cvs -f diff foobar}.
7786 In place of the command name you can use @code{cvs} to
7787 specify global options (@pxref{Global options}). For
7788 example the following line in @file{.cvsrc}
7795 causes @sc{cvs} to use compression level 6.
7797 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
7798 @node Global options
7799 @appendixsec Global options
7800 @cindex Options, global
7801 @cindex Global options
7802 @cindex Left-hand options
7804 The available @samp{cvs_options} (that are given to the
7805 left of @samp{cvs_command}) are:
7808 @item --allow-root=@var{rootdir}
7809 Specify legal @sc{cvsroot} directory. See
7810 @ref{Password authentication server}.
7812 @cindex Authentication, stream
7813 @cindex Stream authentication
7815 Authenticate all communication between the client and
7816 the server. Only has an effect on the @sc{cvs} client.
7817 As of this writing, this is only implemented when using
7818 a GSSAPI connection (@pxref{GSSAPI authenticated}).
7819 Authentication prevents certain sorts of attacks
7820 involving hijacking the active @sc{tcp} connection.
7821 Enabling authentication does not enable encryption.
7823 @cindex RCSBIN, overriding
7824 @cindex Overriding RCSBIN
7825 @item -b @var{bindir}
7826 In @sc{cvs} 1.9.18 and older, this specified that
7827 @sc{rcs} programs are in the @var{bindir} directory.
7828 Current versions of @sc{cvs} do not run @sc{rcs}
7829 programs; for compatibility this option is accepted,
7830 but it does nothing.
7832 @cindex TMPDIR, overriding
7833 @cindex Overriding TMPDIR
7834 @item -T @var{tempdir}
7835 Use @var{tempdir} as the directory where temporary files are
7836 located. Overrides the setting of the @code{$TMPDIR} environment
7837 variable and any precompiled directory. This parameter should be
7838 specified as an absolute pathname.
7839 (When running client/server, @samp{-T} affects only the local process;
7840 specifying @samp{-T} for the client has no effect on the server and
7843 @cindex CVSROOT, overriding
7844 @cindex Overriding CVSROOT
7845 @item -d @var{cvs_root_directory}
7846 Use @var{cvs_root_directory} as the root directory
7847 pathname of the repository. Overrides the setting of
7848 the @code{$CVSROOT} environment variable. See @ref{Repository}.
7850 @cindex EDITOR, overriding
7851 @cindex Overriding EDITOR
7852 @item -e @var{editor}
7853 Use @var{editor} to enter revision log information. Overrides the
7854 setting of the @code{$CVSEDITOR} and @code{$EDITOR}
7855 environment variables. For more information, see
7856 @ref{Committing your changes}.
7859 Do not read the @file{~/.cvsrc} file. This
7860 option is most often used because of the
7861 non-orthogonality of the @sc{cvs} option set. For
7862 example, the @samp{cvs log} option @samp{-N} (turn off
7863 display of tag names) does not have a corresponding
7864 option to turn the display on. So if you have
7865 @samp{-N} in the @file{~/.cvsrc} entry for @samp{log},
7866 you may need to use @samp{-f} to show the tag names.
7870 Display usage information about the specified @samp{cvs_command}
7871 (but do not actually execute the command). If you don't specify
7872 a command name, @samp{cvs -H} displays overall help for
7873 @sc{cvs}, including a list of other help options.
7874 @c It seems to me it is better to document it this way
7875 @c rather than trying to update this documentation
7876 @c every time that we add a --help-foo option. But
7877 @c perhaps that is confusing...
7879 @cindex Read-only mode
7881 Do not change any files. Attempt to execute the
7882 @samp{cvs_command}, but only to issue reports; do not remove,
7883 update, or merge any existing files, or create any new files.
7885 Note that @sc{cvs} will not necessarily produce exactly
7886 the same output as without @samp{-n}. In some cases
7887 the output will be the same, but in other cases
7888 @sc{cvs} will skip some of the processing that would
7889 have been required to produce the exact same output.
7892 Cause the command to be really quiet; the command will only
7893 generate output for serious problems.
7896 Cause the command to be somewhat quiet; informational messages,
7897 such as reports of recursion through subdirectories, are
7900 @cindex Read-only files, and -r
7902 Make new working files read-only. Same effect
7903 as if the @code{$CVSREAD} environment variable is set
7904 (@pxref{Environment variables}). The default is to
7905 make working files writable, unless watches are on
7908 @item -s @var{variable}=@var{value}
7909 Set a user variable (@pxref{Variables}).
7913 Trace program execution; display messages showing the steps of
7914 @sc{cvs} activity. Particularly useful with @samp{-n} to explore the
7915 potential impact of an unfamiliar command.
7919 Display version and copyright information for @sc{cvs}.
7921 @cindex CVSREAD, overriding
7922 @cindex Overriding CVSREAD
7924 Make new working files read-write. Overrides the
7925 setting of the @code{$CVSREAD} environment variable.
7926 Files are created read-write by default, unless @code{$CVSREAD} is
7927 set or @samp{-r} is given.
7928 @c Note that -w only overrides -r and CVSREAD; it has
7929 @c no effect on files which are readonly because of
7930 @c "cvs watch on". My guess is that is the way it
7931 @c should be (or should "cvs -w get" on a watched file
7932 @c be the same as a get and a cvs edit?), but I'm not
7933 @c completely sure whether to document it this way.
7937 Encrypt all communication between the client and the
7938 server. Only has an effect on the @sc{cvs} client. As
7939 of this writing, this is only implemented when using a
7940 GSSAPI connection (@pxref{GSSAPI authenticated}) or a
7941 Kerberos connection (@pxref{Kerberos authenticated}).
7942 Enabling encryption implies that message traffic is
7943 also authenticated. Encryption support is not
7944 available by default; it must be enabled using a
7945 special configure option, @file{--enable-encryption},
7946 when you build @sc{cvs}.
7948 @item -z @var{gzip-level}
7951 Set the compression level.
7952 Valid levels are 1 (high speed, low compression) to
7953 9 (low speed, high compression), or 0 to disable
7954 compression (the default).
7955 Only has an effect on the @sc{cvs} client.
7959 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
7960 @node Common options
7961 @appendixsec Common command options
7962 @cindex Common options
7963 @cindex Right-hand options
7965 This section describes the @samp{command_options} that
7966 are available across several @sc{cvs} commands. These
7967 options are always given to the right of
7968 @samp{cvs_command}. Not all
7969 commands support all of these options; each option is
7970 only supported for commands where it makes sense.
7971 However, when a command has one of these options you
7972 can almost always count on the same behavior of the
7973 option as in other commands. (Other command options,
7974 which are listed with the individual commands, may have
7975 different behavior from one @sc{cvs} command to the other).
7977 @strong{The @samp{history} command is an exception; it supports
7978 many options that conflict even with these standard options.}
7983 @cindex Specifying dates
7984 @item -D @var{date_spec}
7985 Use the most recent revision no later than @var{date_spec}.
7986 @var{date_spec} is a single argument, a date description
7987 specifying a date in the past.
7989 The specification is @dfn{sticky} when you use it to make a
7990 private copy of a source file; that is, when you get a working
7991 file using @samp{-D}, @sc{cvs} records the date you specified, so that
7992 further updates in the same directory will use the same date
7993 (for more information on sticky tags/dates, @pxref{Sticky tags}).
7995 @samp{-D} is available with the @code{annotate}, @code{checkout},
7996 @code{diff}, @code{export}, @code{history},
7997 @code{rdiff}, @code{rtag}, and @code{update} commands.
7998 (The @code{history} command uses this option in a
7999 slightly different way; @pxref{history options}).
8001 @c What other formats should we accept? I don't want
8002 @c to start accepting a whole mess of non-standard
8003 @c new formats (there are a lot which are in wide use in
8004 @c one context or another), but practicality does
8005 @c dictate some level of flexibility.
8006 @c * POSIX.2 (e.g. touch, ls output, date) and other
8007 @c POSIX and/or de facto unix standards (e.g. at). The
8008 @c practice here is too inconsistent to be of any use.
8009 @c * VMS dates. This is not a formal standard, but
8010 @c there is a published specification (see SYS$ASCTIM
8011 @c and SYS$BINTIM in the _VMS System Services Reference
8012 @c Manual_), it is implemented consistently in VMS
8013 @c utilities, and VMS users will expect CVS running on
8014 @c VMS to support this format (and if we're going to do
8015 @c that, better to make CVS support it on all
8016 @c platforms. Maybe).
8018 @c NOTE: The tar manual has some documentation for
8019 @c getdate.y (just for our info; we don't want to
8020 @c attempt to document all the formats accepted by
8023 @c One more note: In output, CVS should consistently
8024 @c use one date format, and that format should be one that
8025 @c it accepts in input as well. The former isn't
8026 @c really true (see survey below), and I'm not
8027 @c sure that either of those formats is accepted in
8031 @c current 1996/01/02 13:45:31
8032 @c Internet 02 Jan 1996 13:45:31 UT
8033 @c ISO 1996-01-02 13:45:31
8035 @c current 02-Jan-96
8036 @c Internet-like 02 Jan 96
8039 @c current Tue Jun 11 02:54:53 1996
8040 @c Internet [Tue,] 11 Jun 1996 02:54:53
8041 @c ISO 1996-06-11 02:54:53
8042 @c note: date possibly should be omitted entirely for
8045 @c current Tue Jun 11 02:54:53 1996 GMT
8047 @c current 06/11 02:54 +0000
8049 @c There is a good chance the proper solution has to
8050 @c involve at least some level of letting the user
8051 @c decide which format (with the default being the
8052 @c formats CVS has always used; changing these might be
8053 @c _very_ disruptive since scripts may very well be
8056 @c Another random bit of prior art concerning dates is
8057 @c the strptime function which takes templates such as
8058 @c "%m/%d/%y", and apparent a variant of getdate()
8059 @c which also honors them. See
8060 @c X/Open CAE Specification, System Interfaces and
8061 @c Headers Issue 4, Version 2 (September 1994), in the
8062 @c entry for getdate() on page 231
8064 @cindex Timezone, in input
8065 @cindex Zone, time, in input
8066 A wide variety of date formats are supported by
8067 @sc{cvs}. The most standard ones are ISO8601 (from the
8068 International Standards Organization) and the Internet
8069 e-mail standard (specified in RFC822 as amended by
8072 @c Probably should be doing more to spell out just what
8073 @c the rules are, rather than just giving examples.
8074 @c But I want to keep this simple too.
8075 @c So I don't know....
8076 @c A few specific issues: (1) Maybe should reassure
8077 @c people that years after 2000
8078 @c work (they are in the testsuite, so they do indeed
8079 @c work). (2) What do two digit years
8080 @c mean? Where do we accept them? (3) Local times can
8081 @c be ambiguous or nonexistent if they fall during the
8082 @c hour when daylight savings time goes into or out of
8083 @c effect. Pretty obscure, so I'm not at all sure we
8084 @c should be documenting the behavior in that case.
8085 ISO8601 dates have many variants but a few examples
8092 @c I doubt we really accept all ISO8601 format dates
8093 @c (for example, decimal hours like 1972-09-24 20,2)
8094 @c I'm not sure we should, many of them are pretty
8095 @c bizarre and it has lots of gratuitous multiple ways
8096 @c to specify the same thing.
8098 There are a lot more ISO8601 date formats, and @sc{cvs}
8099 accepts many of them, but you probably don't want to
8100 hear the @emph{whole} long story :-).
8102 @c Citing a URL here is kind of problematic given how
8103 @c much they change and people who have old versions of
8104 @c this manual, but in case we want to reinstate an
8105 @c ISO8601 URL, a few are:
8106 @c http://www.saqqara.demon.co.uk/datefmt.htm
8107 @c http://www.cl.cam.ac.uk/~mgk25/iso-time.html
8108 @c Citing some other ISO8601 source is probably even
8111 In addition to the dates allowed in Internet e-mail
8112 itself, @sc{cvs} also allows some of the fields to be
8113 omitted. For example:
8114 @c FIXME: Need to figure out better, and document,
8115 @c what we want to allow the user to omit.
8116 @c NOTE: "omit" does not imply "reorder".
8117 @c FIXME: Need to cite a web page describing how to get
8125 The date is interpreted as being in the
8126 local timezone, unless a specific timezone is
8129 These two date formats are preferred. However,
8130 @sc{cvs} currently accepts a wide variety of other date
8131 formats. They are intentionally not documented here in
8132 any detail, and future versions of @sc{cvs} might not
8134 @c We should document and testsuite "now" and
8135 @c "yesterday". "now" is mentioned in the FAQ and
8136 @c "yesterday" is mentioned in this document (and the
8137 @c message from "cvs import" suggesting a merge
8138 @c command). What else? Probably some/all of the "3
8139 @c weeks ago" family.
8142 @c some point have CVS start give warnings on "unofficial"
8143 @c formats (many of which might be typos or user
8144 @c misunderstandings, and/or formats people never/rarely
8145 @c use to specify dates)?
8148 @code{@var{month}/@var{day}/@var{year}}. This may
8149 confuse people who are accustomed to having the month
8150 and day in the other order; @samp{1/4/96} is January 4,
8153 Remember to quote the argument to the @samp{-D}
8154 flag so that your shell doesn't interpret spaces as
8155 argument separators. A command using the @samp{-D}
8156 flag can look like this:
8159 $ cvs diff -D "1 hour ago" cvs.texinfo
8162 @cindex Forcing a tag match
8164 When you specify a particular date or tag to @sc{cvs} commands, they
8165 normally ignore files that do not contain the tag (or did not
8166 exist prior to the date) that you specified. Use the @samp{-f} option
8167 if you want files retrieved even when there is no match for the
8168 tag or date. (The most recent revision of the file
8171 Note that even with @samp{-f}, a tag that you specify
8172 must exist (that is, in some file, not necessary in
8173 every file). This is so that @sc{cvs} will continue to
8174 give an error if you mistype a tag name.
8177 @samp{-f} is available with these commands:
8178 @code{annotate}, @code{checkout}, @code{export},
8179 @code{rdiff}, @code{rtag}, and @code{update}.
8181 @strong{WARNING: The @code{commit} and @code{remove}
8182 commands also have a
8183 @samp{-f} option, but it has a different behavior for
8184 those commands. See @ref{commit options}, and
8185 @ref{Removing files}.}
8187 @item -k @var{kflag}
8188 Alter the default processing of keywords.
8189 See @ref{Keyword substitution}, for the meaning of
8190 @var{kflag}. Your @var{kflag} specification is
8191 @dfn{sticky} when you use it to create a private copy
8192 of a source file; that is, when you use this option
8193 with the @code{checkout} or @code{update} commands,
8194 @sc{cvs} associates your selected @var{kflag} with the
8195 file, and continues to use it with future update
8196 commands on the same file until you specify otherwise.
8198 The @samp{-k} option is available with the @code{add},
8199 @code{checkout}, @code{diff}, @code{rdiff}, @code{import} and
8200 @code{update} commands.
8203 Local; run only in current working directory, rather than
8204 recursing through subdirectories.
8206 Available with the following commands: @code{annotate}, @code{checkout},
8207 @code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export},
8208 @code{log}, @code{rdiff}, @code{remove}, @code{rtag},
8209 @code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch},
8210 and @code{watchers}.
8212 @cindex Editor, avoiding invocation of
8213 @cindex Avoiding editor invocation
8214 @item -m @var{message}
8215 Use @var{message} as log information, instead of
8218 Available with the following commands: @code{add},
8219 @code{commit} and @code{import}.
8222 Do not run any tag program. (A program can be
8223 specified to run in the modules
8224 database (@pxref{modules}); this option bypasses it).
8226 @strong{This is not the same as the @samp{cvs -n}
8227 program option, which you can specify to the left of a cvs command!}
8229 Available with the @code{checkout}, @code{export},
8230 and @code{rtag} commands.
8233 Prune empty directories. See @ref{Removing directories}.
8236 Pipe the files retrieved from the repository to standard output,
8237 rather than writing them in the current directory. Available
8238 with the @code{checkout} and @code{update} commands.
8241 Process directories recursively. This is on by default.
8243 Available with the following commands: @code{annotate}, @code{checkout},
8244 @code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export},
8245 @code{rdiff}, @code{remove}, @code{rtag},
8246 @code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch},
8247 and @code{watchers}.
8250 @cindex HEAD, special tag
8251 @cindex BASE, special tag
8252 Use the revision specified by the @var{tag} argument instead of the
8253 default @dfn{head} revision. As well as arbitrary tags defined
8254 with the @code{tag} or @code{rtag} command, two special tags are
8255 always available: @samp{HEAD} refers to the most recent version
8256 available in the repository, and @samp{BASE} refers to the
8257 revision you last checked out into the current working directory.
8259 @c FIXME: What does HEAD really mean? I believe that
8260 @c the current answer is the head of the default branch
8261 @c for all cvs commands except diff. For diff, it
8262 @c seems to be (a) the head of the trunk (or the default
8263 @c branch?) if there is no sticky tag, (b) the head of the
8264 @c branch for the sticky tag, if there is a sticky tag.
8265 @c (b) is ugly as it differs
8266 @c from what HEAD means for other commands, but people
8267 @c and/or scripts are quite possibly used to it.
8268 @c See "head" tests in sanity.sh.
8269 @c Probably the best fix is to introduce two new
8270 @c special tags, ".thead" for the head of the trunk,
8271 @c and ".bhead" for the head of the current branch.
8272 @c Then deprecate HEAD. This has the advantage of
8273 @c not surprising people with a change to HEAD, and a
8274 @c side benefit of also phasing out the poorly-named
8275 @c HEAD (see discussion of reserved tag names in node
8276 @c "Tags"). Of course, .thead and .bhead should be
8277 @c carefully implemented (with the implementation the
8278 @c same for "diff" as for everyone else), test cases
8279 @c written (similar to the ones in "head"), new tests
8280 @c cases written for things like default branches, &c.
8282 The tag specification is sticky when you use this
8284 with @code{checkout} or @code{update} to make your own
8285 copy of a file: @sc{cvs} remembers the tag and continues to use it on
8286 future update commands, until you specify otherwise (for more information
8287 on sticky tags/dates, @pxref{Sticky tags}).
8289 The tag can be either a symbolic or numeric tag, as
8290 described in @ref{Tags}, or the name of a branch, as
8291 described in @ref{Branching and merging}.
8292 When a command expects a specific revision,
8293 the name of a branch is interpreted as the most recent
8294 revision on that branch.
8296 Specifying the @samp{-q} global option along with the
8297 @samp{-r} command option is often useful, to suppress
8298 the warning messages when the @sc{rcs} file
8299 does not contain the specified tag.
8301 @strong{This is not the same as the overall @samp{cvs -r} option,
8302 which you can specify to the left of a @sc{cvs} command!}
8304 @samp{-r} is available with the @code{annotate}, @code{checkout},
8305 @code{commit}, @code{diff}, @code{history}, @code{export}, @code{rdiff},
8306 @code{rtag}, and @code{update} commands.
8309 Specify file names that should be filtered. You can
8310 use this option repeatedly. The spec can be a file
8311 name pattern of the same type that you can specify in
8312 the @file{.cvswrappers} file.
8313 Available with the following commands: @code{import},
8318 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
8320 @appendixsec add---Add files and directories to the repository
8321 @cindex add (subcommand)
8325 Synopsis: add [-k rcs-kflag] [-m message] files...
8327 Requires: repository, working directory.
8329 Changes: repository, working directory.
8332 The @code{add} command is used to present new files
8333 and directories for addition into the @sc{cvs}
8334 repository. When @code{add} is used on a directory,
8335 a new directory is created in the repository
8336 immediately. When used on a file, only the working
8337 directory is updated. Changes to the repository are
8338 not made until the @code{commit} command is used on
8339 the newly added file.
8341 The @code{add} command also resurrects files that
8342 have been previously removed. This can be done
8343 before or after the @code{commit} command is used
8344 to finalize the removal of files. Resurrected files
8345 are restored into the working directory at the time
8346 the @code{add} command is executed.
8349 * add options:: add options
8350 * add examples:: add examples
8353 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8355 @appendixsubsec add options
8357 These standard options are supported by @code{add}
8358 (@pxref{Common options}, for a complete description of
8362 @item -k @var{kflag}
8363 Process keywords according to @var{kflag}. See
8364 @ref{Keyword substitution}.
8365 This option is sticky; future updates of
8366 this file in this working directory will use the same
8367 @var{kflag}. The @code{status} command can be viewed
8368 to see the sticky options. For more information on
8369 the @code{status} command, @xref{Invoking CVS}.
8371 @item -m @var{message}
8372 Use @var{message} as the log message, instead of
8376 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8378 @appendixsubsec add examples
8380 @appendixsubsubsec Adding a directory
8385 Directory /path/to/repository/doc added to the repository
8388 @appendixsubsubsec Adding a file
8394 cvs add: scheduling file `TODO' for addition
8395 cvs add: use 'cvs commit' to add this file permanently
8398 @appendixsubsubsec Undoing a @code{remove} command
8402 $ cvs remove makefile
8403 cvs remove: scheduling `makefile' for removal
8404 cvs remove: use 'cvs commit' to remove this file permanently
8407 cvs add: makefile, version 1.2, resurrected
8410 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
8412 @appendixsec admin---Administration
8413 @cindex Admin (subcommand)
8417 Requires: repository, working directory.
8419 Changes: repository.
8424 This is the @sc{cvs} interface to assorted
8425 administrative facilities. Some of them have
8426 questionable usefulness for @sc{cvs} but exist for
8427 historical purposes. Some of the questionable options
8428 are likely to disappear in the future. This command
8429 @emph{does} work recursively, so extreme care should be
8433 On unix, if there is a group named @code{cvsadmin},
8434 only members of that group can run @code{cvs admin}
8435 (except for the @code{cvs admin -k} command, which can
8436 be run by anybody). This group should exist on the
8437 server, or any system running the non-client/server
8438 @sc{cvs}. To disallow @code{cvs admin} for all users,
8439 create a group with no users in it. On NT, the
8440 @code{cvsadmin} feature does not exist and all users
8441 can run @code{cvs admin}.
8444 * admin options:: admin options
8447 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8449 @appendixsubsec admin options
8451 Some of these options have questionable usefulness for
8452 @sc{cvs} but exist for historical purposes. Some even
8453 make it impossible to use @sc{cvs} until you undo the
8457 @item -A@var{oldfile}
8458 Might not work together with @sc{cvs}. Append the
8459 access list of @var{oldfile} to the access list of the
8462 @item -a@var{logins}
8463 Might not work together with @sc{cvs}. Append the
8464 login names appearing in the comma-separated list
8465 @var{logins} to the access list of the @sc{rcs} file.
8468 Set the default branch to @var{rev}. In @sc{cvs}, you
8469 normally do not manipulate default branches; sticky
8470 tags (@pxref{Sticky tags}) are a better way to decide
8471 which branch you want to work on. There is one reason
8472 to run @code{cvs admin -b}: to revert to the vendor's
8473 version when using vendor branches (@pxref{Reverting
8475 There can be no space between @samp{-b} and its argument.
8476 @c Hmm, we don't document the usage where rev is
8477 @c omitted. Maybe that usage can/should be deprecated
8478 @c (and replaced with -bHEAD or something?) (so we can toss
8479 @c the optional argument). Note that -bHEAD does not
8480 @c work, as of 17 Sep 1997, but probably will once "cvs
8481 @c admin" is internal to CVS.
8483 @cindex Comment leader
8484 @item -c@var{string}
8485 Sets the comment leader to @var{string}. The comment
8486 leader is not used by current versions of @sc{cvs} or
8487 @sc{rcs} 5.7. Therefore, you can almost surely not
8488 worry about it. See @ref{Keyword substitution}.
8490 @item -e[@var{logins}]
8491 Might not work together with @sc{cvs}. Erase the login
8492 names appearing in the comma-separated list
8493 @var{logins} from the access list of the RCS file. If
8494 @var{logins} is omitted, erase the entire access list.
8495 There can be no space between @samp{-e} and its argument.
8498 Run interactively, even if the standard input is not a
8499 terminal. This option does not work with the
8500 client/server @sc{cvs} and is likely to disappear in
8501 a future release of @sc{cvs}.
8504 Useless with @sc{cvs}. This creates and initializes a
8505 new @sc{rcs} file, without depositing a revision. With
8506 @sc{cvs}, add files with the @code{cvs add} command
8507 (@pxref{Adding files}).
8510 Set the default keyword
8511 substitution to @var{subst}. See @ref{Keyword
8512 substitution}. Giving an explicit @samp{-k} option to
8513 @code{cvs update}, @code{cvs export}, or @code{cvs
8514 checkout} overrides this default.
8517 Lock the revision with number @var{rev}. If a branch
8518 is given, lock the latest revision on that branch. If
8519 @var{rev} is omitted, lock the latest revision on the
8520 default branch. There can be no space between
8521 @samp{-l} and its argument.
8523 This can be used in conjunction with the
8524 @file{rcslock.pl} script in the @file{contrib}
8525 directory of the @sc{cvs} source distribution to
8526 provide reserved checkouts (where only one user can be
8527 editing a given file at a time). See the comments in
8528 that file for details (and see the @file{README} file
8529 in that directory for disclaimers about the unsupported
8530 nature of contrib). According to comments in that
8531 file, locking must set to strict (which is the default).
8534 Set locking to strict. Strict locking means that the
8535 owner of an RCS file is not exempt from locking for
8536 checkin. For use with @sc{cvs}, strict locking must be
8537 set; see the discussion under the @samp{-l} option above.
8539 @cindex Changing a log message
8540 @cindex Replacing a log message
8541 @cindex Correcting a log message
8542 @cindex Fixing a log message
8543 @cindex Log message, correcting
8544 @item -m@var{rev}:@var{msg}
8545 Replace the log message of revision @var{rev} with
8548 @c The rcs -M option, to suppress sending mail, has never been
8549 @c documented as a cvs admin option.
8551 @item -N@var{name}[:[@var{rev}]]
8552 Act like @samp{-n}, except override any previous
8553 assignment of @var{name}. For use with magic branches,
8554 see @ref{Magic branch numbers}.
8556 @item -n@var{name}[:[@var{rev}]]
8557 Associate the symbolic name @var{name} with the branch
8558 or revision @var{rev}. It is normally better to use
8559 @samp{cvs tag} or @samp{cvs rtag} instead. Delete the
8560 symbolic name if both @samp{:} and @var{rev} are
8561 omitted; otherwise, print an error message if
8562 @var{name} is already associated with another number.
8563 If @var{rev} is symbolic, it is expanded before
8564 association. A @var{rev} consisting of a branch number
8565 followed by a @samp{.} stands for the current latest
8566 revision in the branch. A @samp{:} with an empty
8567 @var{rev} stands for the current latest revision on the
8568 default branch, normally the trunk. For example,
8569 @samp{cvs admin -n@var{name}:} associates @var{name} with the
8570 current latest revision of all the RCS files;
8571 this contrasts with @samp{cvs admin -n@var{name}:$} which
8572 associates @var{name} with the revision numbers
8573 extracted from keyword strings in the corresponding
8576 @cindex Deleting revisions
8577 @cindex Outdating revisions
8578 @cindex Saving space
8580 Deletes (@dfn{outdates}) the revisions given by
8583 Note that this command can be quite dangerous unless
8584 you know @emph{exactly} what you are doing (for example
8585 see the warnings below about how the
8586 @var{rev1}:@var{rev2} syntax is confusing).
8588 If you are short on disc this option might help you.
8589 But think twice before using it---there is no way short
8590 of restoring the latest backup to undo this command!
8591 If you delete different revisions than you planned,
8592 either due to carelessness or (heaven forbid) a @sc{cvs}
8593 bug, there is no opportunity to correct the error
8594 before the revisions are deleted. It probably would be
8595 a good idea to experiment on a copy of the repository
8598 Specify @var{range} in one of the following ways:
8601 @item @var{rev1}::@var{rev2}
8602 Collapse all revisions between rev1 and rev2, so that
8603 @sc{cvs} only stores the differences associated with going
8604 from rev1 to rev2, not intermediate steps. For
8605 example, after @samp{-o 1.3::1.5} one can retrieve
8606 revision 1.3, revision 1.5, or the differences to get
8607 from 1.3 to 1.5, but not the revision 1.4, or the
8608 differences between 1.3 and 1.4. Other examples:
8609 @samp{-o 1.3::1.4} and @samp{-o 1.3::1.3} have no
8610 effect, because there are no intermediate revisions to
8614 Collapse revisions between the beginning of the branch
8615 containing @var{rev} and @var{rev} itself. The
8616 branchpoint and @var{rev} are left intact. For
8617 example, @samp{-o ::1.3.2.6} deletes revision 1.3.2.1,
8618 revision 1.3.2.5, and everything in between, but leaves
8619 1.3 and 1.3.2.6 intact.
8622 Collapse revisions between @var{rev} and the end of the
8623 branch containing @var{rev}. Revision @var{rev} is
8624 left intact but the head revision is deleted.
8627 Delete the revision @var{rev}. For example, @samp{-o
8628 1.3} is equivalent to @samp{-o 1.2::1.4}.
8630 @item @var{rev1}:@var{rev2}
8631 Delete the revisions from @var{rev1} to @var{rev2},
8632 inclusive, on the same branch. One will not be able to
8633 retrieve @var{rev1} or @var{rev2} or any of the
8634 revisions in between. For example, the command
8635 @samp{cvs admin -oR_1_01:R_1_02 .} is rarely useful.
8636 It means to delete revisions up to, and including, the
8637 tag R_1_02. But beware! If there are files that have not
8638 changed between R_1_02 and R_1_03 the file will have
8639 @emph{the same} numerical revision number assigned to
8640 the tags R_1_02 and R_1_03. So not only will it be
8641 impossible to retrieve R_1_02; R_1_03 will also have to
8642 be restored from the tapes! In most cases you want to
8643 specify @var{rev1}::@var{rev2} instead.
8646 Delete revisions from the beginning of the
8647 branch containing @var{rev} up to and including
8651 Delete revisions from revision @var{rev}, including
8652 @var{rev} itself, to the end of the branch containing
8656 None of the revisions to be deleted may have
8659 If any of the revisions to be deleted have symbolic
8660 names, and one specifies one of the @samp{::} syntaxes,
8661 then @sc{cvs} will give an error and not delete any
8662 revisions. If you really want to delete both the
8663 symbolic names and the revisions, first delete the
8664 symbolic names with @code{cvs tag -d}, then run
8665 @code{cvs admin -o}. If one specifies the
8666 non-@samp{::} syntaxes, then @sc{cvs} will delete the
8667 revisions but leave the symbolic names pointing to
8668 nonexistent revisions. This behavior is preserved for
8669 compatibility with previous versions of @sc{cvs}, but
8670 because it isn't very useful, in the future it may
8671 change to be like the @samp{::} case.
8673 Due to the way @sc{cvs} handles branches @var{rev}
8674 cannot be specified symbolically if it is a branch.
8675 See @ref{Magic branch numbers} for an explanation.
8676 @c FIXME: is this still true? I suspect not.
8678 Make sure that no-one has checked out a copy of the
8679 revision you outdate. Strange things will happen if he
8680 starts to edit it and tries to check it back in. For
8681 this reason, this option is not a good way to take back
8682 a bogus commit; commit a new revision undoing the bogus
8683 change instead (@pxref{Merging two revisions}).
8686 Run quietly; do not print diagnostics.
8688 @item -s@var{state}[:@var{rev}]
8689 Useful with @sc{cvs}. Set the state attribute of the
8690 revision @var{rev} to @var{state}. If @var{rev} is a
8691 branch number, assume the latest revision on that
8692 branch. If @var{rev} is omitted, assume the latest
8693 revision on the default branch. Any identifier is
8694 acceptable for @var{state}. A useful set of states is
8695 @samp{Exp} (for experimental), @samp{Stab} (for
8696 stable), and @samp{Rel} (for released). By default,
8697 the state of a new revision is set to @samp{Exp} when
8698 it is created. The state is visible in the output from
8699 @var{cvs log} (@pxref{log}), and in the
8700 @samp{$@splitrcskeyword{Log}$} and @samp{$@splitrcskeyword{State}$} keywords
8701 (@pxref{Keyword substitution}). Note that @sc{cvs}
8702 uses the @code{dead} state for its own purposes (@pxref{Attic}); to
8703 take a file to or from the @code{dead} state use
8704 commands like @code{cvs remove} and @code{cvs add}
8705 (@pxref{Adding and removing}), not @code{cvs admin -s}.
8707 @item -t[@var{file}]
8708 Useful with @sc{cvs}. Write descriptive text from the
8709 contents of the named @var{file} into the RCS file,
8710 deleting the existing text. The @var{file} pathname
8711 may not begin with @samp{-}. The descriptive text can be seen in the
8712 output from @samp{cvs log} (@pxref{log}).
8713 There can be no space between @samp{-t} and its argument.
8715 If @var{file} is omitted,
8716 obtain the text from standard input, terminated by
8717 end-of-file or by a line containing @samp{.} by itself.
8718 Prompt for the text if interaction is possible; see
8721 @item -t-@var{string}
8722 Similar to @samp{-t@var{file}}. Write descriptive text
8723 from the @var{string} into the @sc{rcs} file, deleting
8725 There can be no space between @samp{-t} and its argument.
8727 @c The rcs -T option, do not update last-mod time for
8728 @c minor changes, has never been documented as a
8729 @c cvs admin option.
8732 Set locking to non-strict. Non-strict locking means
8733 that the owner of a file need not lock a revision for
8734 checkin. For use with @sc{cvs}, strict locking must be
8735 set; see the discussion under the @samp{-l} option
8739 See the option @samp{-l} above, for a discussion of
8740 using this option with @sc{cvs}. Unlock the revision
8741 with number @var{rev}. If a branch is given, unlock
8742 the latest revision on that branch. If @var{rev} is
8743 omitted, remove the latest lock held by the caller.
8744 Normally, only the locker of a revision may unlock it;
8745 somebody else unlocking a revision breaks the lock.
8746 This causes the original locker to be sent a @code{commit}
8747 notification (@pxref{Getting Notified}).
8748 There can be no space between @samp{-u} and its argument.
8751 In previous versions of @sc{cvs}, this option meant to
8752 write an @sc{rcs} file which would be acceptable to
8753 @sc{rcs} version @var{n}, but it is now obsolete and
8754 specifying it will produce an error.
8755 @c Note that -V without an argument has never been
8756 @c documented as a cvs admin option.
8758 @item -x@var{suffixes}
8759 In previous versions of @sc{cvs}, this was documented
8760 as a way of specifying the names of the @sc{rcs}
8761 files. However, @sc{cvs} has always required that the
8762 @sc{rcs} files used by @sc{cvs} end in @samp{,v}, so
8763 this option has never done anything useful.
8765 @c The rcs -z option, to specify the timezone, has
8766 @c never been documented as a cvs admin option.
8770 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
8772 @appendixsec annotate---What revision modified each line of a file?
8773 @cindex annotate (subcommand)
8777 Synopsis: annotate [options] files@dots{}
8779 Requires: repository.
8786 For each file in @var{files}, print the head revision
8787 of the trunk, together with information on the last
8788 modification for each line.
8791 * annotate options:: annotate options
8792 * annotate example:: annotate example
8795 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8796 @node annotate options
8797 @appendixsubsec annotate options
8799 These standard options are supported by @code{annotate}
8800 (@pxref{Common options} for a complete description of
8805 Local directory only, no recursion.
8808 Process directories recursively.
8811 Use head revision if tag/date not found.
8814 Annotate binary files.
8816 @item -r @var{revision}
8817 Annotate file as of specified revision/tag.
8820 Annotate file as of specified date.
8823 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8824 @node annotate example
8825 @appendixsubsec annotate example
8830 $ cvs annotate ssfile
8831 Annotations for ssfile
8833 1.1 (mary 27-Mar-96): ssfile line 1
8834 1.2 (joe 28-Mar-96): ssfile line 2
8837 The file @file{ssfile} currently contains two lines.
8838 The @code{ssfile line 1} line was checked in by
8839 @code{mary} on March 27. Then, on March 28, @code{joe}
8840 added a line @code{ssfile line 2}, without modifying
8841 the @code{ssfile line 1} line. This report doesn't
8842 tell you anything about lines which have been deleted
8843 or replaced; you need to use @code{cvs diff} for that
8846 The options to @code{cvs annotate} are listed in
8847 @ref{Invoking CVS}, and can be used to select the files
8848 and revisions to annotate. The options are described
8849 in more detail there and in @ref{Common options}.
8851 @c FIXME: maybe an example using the options? Just
8852 @c what it means to select a revision might be worth a
8853 @c few words of explanation ("you want to see who
8854 @c changed this line *before* 1.4"...).
8857 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
8859 @appendixsec checkout---Check out sources for editing
8860 @cindex checkout (subcommand)
8861 @cindex co (subcommand)
8865 Synopsis: checkout [options] modules@dots{}
8867 Requires: repository.
8869 Changes: working directory.
8874 Create or update a working directory containing copies of the
8875 source files specified by @var{modules}. You must execute
8876 @code{checkout} before using most of the other @sc{cvs}
8877 commands, since most of them operate on your working
8880 The @var{modules} are either
8881 symbolic names for some
8882 collection of source directories and files, or paths to
8883 directories or files in the repository. The symbolic
8884 names are defined in the @samp{modules} file.
8886 @c Needs an example, particularly of the non-"modules"
8887 @c case but probably of both.
8889 @c FIXME: this seems like a very odd place to introduce
8890 @c people to how CVS works. The bit about unreserved
8891 @c checkouts is also misleading as it depends on how
8892 @c things are set up.
8893 Depending on the modules you specify, @code{checkout} may
8894 recursively create directories and populate them with
8895 the appropriate source files. You can then edit these
8896 source files at any time (regardless of whether other
8897 software developers are editing their own copies of the
8898 sources); update them to include new changes applied by
8899 others to the source repository; or commit your work as
8900 a permanent change to the source repository.
8902 Note that @code{checkout} is used to create
8903 directories. The top-level directory created is always
8904 added to the directory where @code{checkout} is
8905 invoked, and usually has the same name as the specified
8906 module. In the case of a module alias, the created
8907 sub-directory may have a different name, but you can be
8908 sure that it will be a sub-directory, and that
8909 @code{checkout} will show the relative path leading to
8910 each file as it is extracted into your private work
8911 area (unless you specify the @samp{-Q} global option).
8913 The files created by @code{checkout} are created
8914 read-write, unless the @samp{-r} option to @sc{cvs}
8915 (@pxref{Global options}) is specified, the
8916 @code{CVSREAD} environment variable is specified
8917 (@pxref{Environment variables}), or a watch is in
8918 effect for that file (@pxref{Watches}).
8920 Note that running @code{checkout} on a directory that was already
8921 built by a prior @code{checkout} is also permitted.
8922 This is similar to specifying the @samp{-d} option
8923 to the @code{update} command in the sense that new
8924 directories that have been created in the repository
8925 will appear in your work area.
8926 However, @code{checkout} takes a module name whereas
8927 @code{update} takes a directory name. Also
8928 to use @code{checkout} this way it must be run from the
8929 top level directory (where you originally ran
8930 @code{checkout} from), so before you run
8931 @code{checkout} to update an existing directory, don't
8932 forget to change your directory to the top level
8935 For the output produced by the @code{checkout} command,
8936 @xref{update output}.
8939 * checkout options:: checkout options
8940 * checkout examples:: checkout examples
8943 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8944 @node checkout options
8945 @appendixsubsec checkout options
8947 These standard options are supported by @code{checkout}
8948 (@pxref{Common options} for a complete description of
8953 Use the most recent revision no later than @var{date}.
8954 This option is sticky, and implies @samp{-P}. See
8955 @ref{Sticky tags} for more information on sticky tags/dates.
8958 Only useful with the @samp{-D @var{date}} or @samp{-r
8959 @var{tag}} flags. If no matching revision is found,
8960 retrieve the most recent revision (instead of ignoring
8963 @item -k @var{kflag}
8964 Process keywords according to @var{kflag}. See
8965 @ref{Keyword substitution}.
8966 This option is sticky; future updates of
8967 this file in this working directory will use the same
8968 @var{kflag}. The @code{status} command can be viewed
8969 to see the sticky options. See @ref{Invoking CVS} for
8970 more information on the @code{status} command.
8973 Local; run only in current working directory.
8976 Do not run any checkout program (as specified
8977 with the @samp{-o} option in the modules file;
8981 Prune empty directories. See @ref{Moving directories}.
8984 Pipe files to the standard output.
8987 Checkout directories recursively. This option is on by default.
8990 Use revision @var{tag}. This option is sticky, and implies @samp{-P}.
8991 See @ref{Sticky tags}, for more information on sticky tags/dates.
8994 In addition to those, you can use these special command
8995 options with @code{checkout}:
8999 Reset any sticky tags, dates, or @samp{-k} options.
9000 Does not reset sticky @samp{-k} options on modified files.
9001 See @ref{Sticky tags} for more information on sticky tags/dates.
9004 Copy the module file, sorted, to the standard output,
9005 instead of creating or modifying any files or
9006 directories in your working directory.
9009 Create a directory called @var{dir} for the working
9010 files, instead of using the module name. In general,
9011 using this flag is equivalent to using @samp{mkdir
9012 @var{dir}; cd @var{dir}} followed by the checkout
9013 command without the @samp{-d} flag.
9015 There is an important exception, however. It is very
9016 convenient when checking out a single item to have the
9017 output appear in a directory that doesn't contain empty
9018 intermediate directories. In this case @emph{only},
9019 @sc{cvs} tries to ``shorten'' pathnames to avoid those empty
9022 For example, given a module @samp{foo} that contains
9023 the file @samp{bar.c}, the command @samp{cvs co -d dir
9024 foo} will create directory @samp{dir} and place
9025 @samp{bar.c} inside. Similarly, given a module
9026 @samp{bar} which has subdirectory @samp{baz} wherein
9027 there is a file @samp{quux.c}, the command @samp{cvs co
9028 -d dir bar/baz} will create directory @samp{dir} and
9029 place @samp{quux.c} inside.
9031 Using the @samp{-N} flag will defeat this behavior.
9032 Given the same module definitions above, @samp{cvs co
9033 -N -d dir foo} will create directories @samp{dir/foo}
9034 and place @samp{bar.c} inside, while @samp{cvs co -N -d
9035 dir bar/baz} will create directories @samp{dir/bar/baz}
9036 and place @samp{quux.c} inside.
9039 With two @samp{-j} options, merge changes from the
9040 revision specified with the first @samp{-j} option to
9041 the revision specified with the second @samp{j} option,
9042 into the working directory.
9044 With one @samp{-j} option, merge changes from the
9045 ancestor revision to the revision specified with the
9046 @samp{-j} option, into the working directory. The
9047 ancestor revision is the common ancestor of the
9048 revision which the working directory is based on, and
9049 the revision specified in the @samp{-j} option.
9051 In addition, each -j option can contain an optional
9052 date specification which, when used with branches, can
9053 limit the chosen revision to one within a specific
9054 date. An optional date is specified by adding a colon
9056 @samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}.
9058 See @ref{Branching and merging}.
9061 Only useful together with @samp{-d @var{dir}}. With
9062 this option, @sc{cvs} will not ``shorten'' module paths
9063 in your working directory when you check out a single
9064 module. See the @samp{-d} flag for examples and a
9068 Like @samp{-c}, but include the status of all modules,
9069 and sort it by the status string. See @ref{modules}, for
9070 info about the @samp{-s} option that is used inside the
9071 modules file to set the module status.
9074 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9075 @node checkout examples
9076 @appendixsubsec checkout examples
9078 Get a copy of the module @samp{tc}:
9084 Get a copy of the module @samp{tc} as it looked one day
9088 $ cvs checkout -D yesterday tc
9091 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
9093 @appendixsec commit---Check files into the repository
9094 @cindex commit (subcommand)
9098 Synopsis: commit [-lRf] [-m 'log_message' |
9099 -F file] [-r revision] [files@dots{}]
9101 Requires: working directory, repository.
9103 Changes: repository.
9108 Use @code{commit} when you want to incorporate changes
9109 from your working source files into the source
9112 If you don't specify particular files to commit, all of
9113 the files in your working current directory are
9114 examined. @code{commit} is careful to change in the
9115 repository only those files that you have really
9116 changed. By default (or if you explicitly specify the
9117 @samp{-R} option), files in subdirectories are also
9118 examined and committed if they have changed; you can
9119 use the @samp{-l} option to limit @code{commit} to the
9120 current directory only.
9122 @code{commit} verifies that the selected files are up
9123 to date with the current revisions in the source
9124 repository; it will notify you, and exit without
9125 committing, if any of the specified files must be made
9126 current first with @code{update} (@pxref{update}).
9127 @code{commit} does not call the @code{update} command
9128 for you, but rather leaves that for you to do when the
9131 When all is well, an editor is invoked to allow you to
9132 enter a log message that will be written to one or more
9133 logging programs (@pxref{modules}, and @pxref{loginfo})
9134 and placed in the @sc{rcs} file inside the
9135 repository. This log message can be retrieved with the
9136 @code{log} command; @xref{log}. You can specify the
9137 log message on the command line with the @samp{-m
9138 @var{message}} option, and thus avoid the editor invocation,
9139 or use the @samp{-F @var{file}} option to specify
9140 that the argument file contains the log message.
9143 * commit options:: commit options
9144 * commit examples:: commit examples
9147 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9148 @node commit options
9149 @appendixsubsec commit options
9151 These standard options are supported by @code{commit}
9152 (@pxref{Common options} for a complete description of
9157 Local; run only in current working directory.
9160 Commit directories recursively. This is on by default.
9162 @item -r @var{revision}
9163 Commit to @var{revision}. @var{revision} must be
9164 either a branch, or a revision on the main trunk that
9165 is higher than any existing revision number
9166 (@pxref{Assigning revisions}). You
9167 cannot commit to a specific revision on a branch.
9168 @c FIXME: Need xref for branch case.
9171 @code{commit} also supports these options:
9175 Read the log message from @var{file}, instead
9176 of invoking an editor.
9179 Note that this is not the standard behavior of
9180 the @samp{-f} option as defined in @ref{Common options}.
9182 Force @sc{cvs} to commit a new revision even if you haven't
9183 made any changes to the file. If the current revision
9184 of @var{file} is 1.7, then the following two commands
9188 $ cvs commit -f @var{file}
9189 $ cvs commit -r 1.8 @var{file}
9192 @c This is odd, but it's how CVS has worked for some
9194 The @samp{-f} option disables recursion (i.e., it
9195 implies @samp{-l}). To force @sc{cvs} to commit a new
9196 revision for all files in all subdirectories, you must
9199 @item -m @var{message}
9200 Use @var{message} as the log message, instead of
9205 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9206 @node commit examples
9207 @appendixsubsec commit examples
9209 @c FIXME: this material wants to be somewhere
9210 @c in "Branching and merging".
9212 @appendixsubsubsec Committing to a branch
9214 You can commit to a branch revision (one that has an
9215 even number of dots) with the @samp{-r} option. To
9216 create a branch revision, use the @samp{-b} option
9217 of the @code{rtag} or @code{tag} commands
9218 (@pxref{Branching and merging}). Then, either @code{checkout} or
9219 @code{update} can be used to base your sources on the
9220 newly created branch. From that point on, all
9221 @code{commit} changes made within these working sources
9222 will be automatically added to a branch revision,
9223 thereby not disturbing main-line development in any
9224 way. For example, if you had to create a patch to the
9225 1.2 version of the product, even though the 2.0 version
9226 is already under development, you might do:
9229 $ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module
9230 $ cvs checkout -r FCS1_2_Patch product_module
9237 This works automatically since the @samp{-r} option is
9240 @appendixsubsubsec Creating the branch after editing
9242 Say you have been working on some extremely
9243 experimental software, based on whatever revision you
9244 happened to checkout last week. If others in your
9245 group would like to work on this software with you, but
9246 without disturbing main-line development, you could
9247 commit your change to a new branch. Others can then
9248 checkout your experimental stuff and utilize the full
9249 benefit of @sc{cvs} conflict resolution. The scenario might
9252 @c FIXME: Should we be recommending tagging the branchpoint?
9254 [[ hacked sources are present ]]
9256 $ cvs update -r EXPR1
9260 The @code{update} command will make the @samp{-r
9261 EXPR1} option sticky on all files. Note that your
9262 changes to the files will never be removed by the
9263 @code{update} command. The @code{commit} will
9264 automatically commit to the correct branch, because the
9265 @samp{-r} is sticky. You could also do like this:
9267 @c FIXME: Should we be recommending tagging the branchpoint?
9269 [[ hacked sources are present ]]
9271 $ cvs commit -r EXPR1
9275 but then, only those files that were changed by you
9276 will have the @samp{-r EXPR1} sticky flag. If you hack
9277 away, and commit without specifying the @samp{-r EXPR1}
9278 flag, some files may accidentally end up on the main
9281 To work with you on the experimental change, others
9285 $ cvs checkout -r EXPR1 whatever_module
9288 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
9290 @appendixsec diff---Show differences between revisions
9291 @cindex diff (subcommand)
9295 Synopsis: diff [-lR] [-k kflag] [format_options] [[-r rev1 | -D date1] [-r rev2 | -D date2]] [files@dots{}]
9297 Requires: working directory, repository.
9302 The @code{diff} command is used to compare different
9303 revisions of files. The default action is to compare
9304 your working files with the revisions they were based
9305 on, and report any differences that are found.
9307 If any file names are given, only those files are
9308 compared. If any directories are given, all files
9309 under them will be compared.
9311 The exit status for diff is different than for other
9312 @sc{cvs} commands; for details @xref{Exit status}.
9315 * diff options:: diff options
9316 * diff examples:: diff examples
9319 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9321 @appendixsubsec diff options
9323 These standard options are supported by @code{diff}
9324 (@pxref{Common options} for a complete description of
9329 Use the most recent revision no later than @var{date}.
9330 See @samp{-r} for how this affects the comparison.
9332 @item -k @var{kflag}
9333 Process keywords according to @var{kflag}. See
9334 @ref{Keyword substitution}.
9337 Local; run only in current working directory.
9340 Examine directories recursively. This option is on by
9344 Compare with revision @var{tag}. Zero, one or two
9345 @samp{-r} options can be present. With no @samp{-r}
9346 option, the working file will be compared with the
9347 revision it was based on. With one @samp{-r}, that
9348 revision will be compared to your current working file.
9349 With two @samp{-r} options those two revisions will be
9350 compared (and your working file will not affect the
9351 outcome in any way).
9352 @c We should be a lot more explicit, with examples,
9353 @c about the difference between "cvs diff" and "cvs
9354 @c diff -r HEAD". This often confuses new users.
9356 One or both @samp{-r} options can be replaced by a
9357 @samp{-D @var{date}} option, described above.
9360 @c Conceptually, this is a disaster. There are 3
9361 @c zillion diff formats that we support via the diff
9362 @c library. It is not obvious to me that we should
9363 @c document them all. Maybe just the most common ones
9364 @c like -c and -u, and think about phasing out the
9366 @c FIXCVS: also should be a way to specify an external
9367 @c diff program (which can be different for different
9368 @c file types) and pass through
9369 @c arbitrary options, so that the user can do
9370 @c "--pass=-Z --pass=foo" or something even if CVS
9371 @c doesn't know about the "-Z foo" option to diff.
9372 @c This would fit nicely with deprecating/eliminating
9373 @c the obscure options of the diff library, because it
9374 @c would let people specify an external GNU diff if
9375 @c they are into that sort of thing.
9376 The following options specify the format of the
9377 output. They have the same meaning as in GNU diff.
9378 Most options have two equivalent names, one of which is a single letter
9379 preceded by @samp{-}, and the other of which is a long name preceded by
9384 Show @var{lines} (an integer) lines of context. This option does not
9385 specify an output format by itself; it has no effect unless it is
9386 combined with @samp{-c} or @samp{-u}. This option is obsolete. For proper
9387 operation, @code{patch} typically needs at least two lines of context.
9390 Treat all files as text and compare them line-by-line, even if they
9391 do not seem to be text.
9394 Ignore trailing white space and consider all other sequences of one or
9395 more white space characters to be equivalent.
9398 Ignore changes that just insert or delete blank lines.
9401 Read and write data in binary mode.
9404 Report only whether the files differ, not the details of the
9408 Use the context output format.
9410 @item -C @var{lines}
9411 @itemx --context@r{[}=@var{lines}@r{]}
9412 Use the context output format, showing @var{lines} (an integer) lines of
9413 context, or three if @var{lines} is not given.
9414 For proper operation, @code{patch} typically needs at least two lines of
9417 @item --changed-group-format=@var{format}
9418 Use @var{format} to output a line group containing differing lines from
9419 both files in if-then-else format. See @ref{Line group formats}.
9422 Change the algorithm to perhaps find a smaller set of changes. This makes
9423 @code{diff} slower (sometimes much slower).
9427 Make output that is a valid @code{ed} script.
9430 Expand tabs to spaces in the output, to preserve the alignment of tabs
9434 Make output that looks vaguely like an @code{ed} script but has changes
9435 in the order they appear in the file.
9437 @item -F @var{regexp}
9438 In context and unified format, for each hunk of differences, show some
9439 of the last preceding line that matches @var{regexp}.
9442 Make output that looks vaguely like an @code{ed} script but has changes
9443 in the order they appear in the file.
9446 Use heuristics to speed handling of large files that have numerous
9447 scattered small changes.
9449 @item --horizon-lines=@var{lines}
9450 Do not discard the last @var{lines} lines of the common prefix
9451 and the first @var{lines} lines of the common suffix.
9454 Ignore changes in case; consider upper- and lower-case letters
9457 @item -I @var{regexp}
9458 Ignore changes that just insert or delete lines that match @var{regexp}.
9460 @item --ifdef=@var{name}
9461 Make merged if-then-else output using @var{name}.
9463 @item --ignore-all-space
9464 Ignore white space when comparing lines.
9466 @item --ignore-blank-lines
9467 Ignore changes that just insert or delete blank lines.
9470 Ignore changes in case; consider upper- and lower-case to be the same.
9472 @item --ignore-matching-lines=@var{regexp}
9473 Ignore changes that just insert or delete lines that match @var{regexp}.
9475 @item --ignore-space-change
9476 Ignore trailing white space and consider all other sequences of one or
9477 more white space characters to be equivalent.
9480 Output a tab rather than a space before the text of a line in normal or
9481 context format. This causes the alignment of tabs in the line to look
9484 @item -L @var{label}
9485 Use @var{label} instead of the file name in the context format
9486 and unified format headers.
9488 @item --label=@var{label}
9489 Use @var{label} instead of the file name in the context format
9490 and unified format headers.
9493 Print only the left column of two common lines in side by side format.
9495 @item --line-format=@var{format}
9496 Use @var{format} to output all input lines in if-then-else format.
9497 See @ref{Line formats}.
9500 Change the algorithm to perhaps find a smaller set of changes. This
9501 makes @code{diff} slower (sometimes much slower).
9504 Output RCS-format diffs; like @samp{-f} except that each command
9505 specifies the number of lines affected.
9509 In directory comparison, if a file is found in only one directory,
9510 treat it as present but empty in the other directory.
9512 @item --new-group-format=@var{format}
9513 Use @var{format} to output a group of lines taken from just the second
9514 file in if-then-else format. See @ref{Line group formats}.
9516 @item --new-line-format=@var{format}
9517 Use @var{format} to output a line taken from just the second file in
9518 if-then-else format. See @ref{Line formats}.
9520 @item --old-group-format=@var{format}
9521 Use @var{format} to output a group of lines taken from just the first
9522 file in if-then-else format. See @ref{Line group formats}.
9524 @item --old-line-format=@var{format}
9525 Use @var{format} to output a line taken from just the first file in
9526 if-then-else format. See @ref{Line formats}.
9529 Show which C function each change is in.
9532 Output RCS-format diffs; like @samp{-f} except that each command
9533 specifies the number of lines affected.
9535 @item --report-identical-files
9537 Report when two files are the same.
9539 @item --show-c-function
9540 Show which C function each change is in.
9542 @item --show-function-line=@var{regexp}
9543 In context and unified format, for each hunk of differences, show some
9544 of the last preceding line that matches @var{regexp}.
9546 @item --side-by-side
9547 Use the side by side output format.
9549 @item --speed-large-files
9550 Use heuristics to speed handling of large files that have numerous
9551 scattered small changes.
9553 @item --suppress-common-lines
9554 Do not print common lines in side by side format.
9557 Expand tabs to spaces in the output, to preserve the alignment of tabs
9561 Output a tab rather than a space before the text of a line in normal or
9562 context format. This causes the alignment of tabs in the line to look
9566 Treat all files as text and compare them line-by-line, even if they
9567 do not appear to be text.
9570 Use the unified output format.
9572 @item --unchanged-group-format=@var{format}
9573 Use @var{format} to output a group of common lines taken from both files
9574 in if-then-else format. @xref{Line group formats}.
9576 @item --unchanged-line-format=@var{format}
9577 Use @var{format} to output a line common to both files in if-then-else
9578 format. @xref{Line formats}.
9580 @item -U @var{lines}
9581 @itemx --unified@r{[}=@var{lines}@r{]}
9582 Use the unified output format, showing @var{lines} (an integer) lines of
9583 context, or three if @var{lines} is not given.
9584 For proper operation, @code{patch} typically needs at least two lines of
9588 Ignore white space when comparing lines.
9590 @item -W @var{columns}
9591 @itemx --width=@var{columns}
9592 Use an output width of @var{columns} in side by side format.
9595 Use the side by side output format.
9599 * Line group formats:: Line group formats
9600 * Line formats:: Line formats
9603 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9604 @node Line group formats
9605 @appendixsubsubsec Line group formats
9607 Line group formats let you specify formats suitable for many
9608 applications that allow if-then-else input, including programming
9609 languages and text formatting languages. A line group format specifies
9610 the output format for a contiguous group of similar lines.
9612 For example, the following command compares the TeX file @file{myfile}
9613 with the original version from the repository,
9614 and outputs a merged file in which old regions are
9615 surrounded by @samp{\begin@{em@}}-@samp{\end@{em@}} lines, and new
9616 regions are surrounded by @samp{\begin@{bf@}}-@samp{\end@{bf@}} lines.
9620 --old-group-format='\begin@{em@}
9623 --new-group-format='\begin@{bf@}
9629 The following command is equivalent to the above example, but it is a
9630 little more verbose, because it spells out the default line group formats.
9634 --old-group-format='\begin@{em@}
9637 --new-group-format='\begin@{bf@}
9640 --unchanged-group-format='%=' \
9641 --changed-group-format='\begin@{em@}
9649 Here is a more advanced example, which outputs a diff listing with
9650 headers containing line numbers in a ``plain English'' style.
9654 --unchanged-group-format='' \
9655 --old-group-format='-------- %dn line%(n=1?:s) deleted at %df:
9657 --new-group-format='-------- %dN line%(N=1?:s) added after %de:
9659 --changed-group-format='-------- %dn line%(n=1?:s) changed at %df:
9665 To specify a line group format, use one of the options
9666 listed below. You can specify up to four line group formats, one for
9667 each kind of line group. You should quote @var{format}, because it
9668 typically contains shell metacharacters.
9671 @item --old-group-format=@var{format}
9672 These line groups are hunks containing only lines from the first file.
9673 The default old group format is the same as the changed group format if
9674 it is specified; otherwise it is a format that outputs the line group as-is.
9676 @item --new-group-format=@var{format}
9677 These line groups are hunks containing only lines from the second
9678 file. The default new group format is same as the changed group
9679 format if it is specified; otherwise it is a format that outputs the
9682 @item --changed-group-format=@var{format}
9683 These line groups are hunks containing lines from both files. The
9684 default changed group format is the concatenation of the old and new
9687 @item --unchanged-group-format=@var{format}
9688 These line groups contain lines common to both files. The default
9689 unchanged group format is a format that outputs the line group as-is.
9692 In a line group format, ordinary characters represent themselves;
9693 conversion specifications start with @samp{%} and have one of the
9698 stands for the lines from the first file, including the trailing newline.
9699 Each line is formatted according to the old line format (@pxref{Line formats}).
9702 stands for the lines from the second file, including the trailing newline.
9703 Each line is formatted according to the new line format.
9706 stands for the lines common to both files, including the trailing newline.
9707 Each line is formatted according to the unchanged line format.
9710 stands for @samp{%}.
9713 where @var{C} is a single character, stands for @var{C}.
9714 @var{C} may not be a backslash or an apostrophe.
9715 For example, @samp{%c':'} stands for a colon, even inside
9716 the then-part of an if-then-else format, which a colon would
9720 where @var{O} is a string of 1, 2, or 3 octal digits,
9721 stands for the character with octal code @var{O}.
9722 For example, @samp{%c'\0'} stands for a null character.
9724 @item @var{F}@var{n}
9725 where @var{F} is a @code{printf} conversion specification and @var{n} is one
9726 of the following letters, stands for @var{n}'s value formatted with @var{F}.
9730 The line number of the line just before the group in the old file.
9733 The line number of the first line in the group in the old file;
9737 The line number of the last line in the group in the old file.
9740 The line number of the line just after the group in the old file;
9744 The number of lines in the group in the old file; equals @var{l} - @var{f} + 1.
9747 Likewise, for lines in the new file.
9751 The @code{printf} conversion specification can be @samp{%d},
9752 @samp{%o}, @samp{%x}, or @samp{%X}, specifying decimal, octal,
9753 lower case hexadecimal, or upper case hexadecimal output
9754 respectively. After the @samp{%} the following options can appear in
9755 sequence: a @samp{-} specifying left-justification; an integer
9756 specifying the minimum field width; and a period followed by an
9757 optional integer specifying the minimum number of digits.
9758 For example, @samp{%5dN} prints the number of new lines in the group
9759 in a field of width 5 characters, using the @code{printf} format @code{"%5d"}.
9761 @item (@var{A}=@var{B}?@var{T}:@var{E})
9762 If @var{A} equals @var{B} then @var{T} else @var{E}.
9763 @var{A} and @var{B} are each either a decimal constant
9764 or a single letter interpreted as above.
9765 This format spec is equivalent to @var{T} if
9766 @var{A}'s value equals @var{B}'s; otherwise it is equivalent to @var{E}.
9768 For example, @samp{%(N=0?no:%dN) line%(N=1?:s)} is equivalent to
9769 @samp{no lines} if @var{N} (the number of lines in the group in the
9770 new file) is 0, to @samp{1 line} if @var{N} is 1, and to @samp{%dN lines}
9774 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9776 @appendixsubsubsec Line formats
9778 Line formats control how each line taken from an input file is
9779 output as part of a line group in if-then-else format.
9781 For example, the following command outputs text with a one-column
9782 change indicator to the left of the text. The first column of output
9783 is @samp{-} for deleted lines, @samp{|} for added lines, and a space
9784 for unchanged lines. The formats contain newline characters where
9785 newlines are desired on output.
9789 --old-line-format='-%l
9791 --new-line-format='|%l
9793 --unchanged-line-format=' %l
9798 To specify a line format, use one of the following options. You should
9799 quote @var{format}, since it often contains shell metacharacters.
9802 @item --old-line-format=@var{format}
9803 formats lines just from the first file.
9805 @item --new-line-format=@var{format}
9806 formats lines just from the second file.
9808 @item --unchanged-line-format=@var{format}
9809 formats lines common to both files.
9811 @item --line-format=@var{format}
9812 formats all lines; in effect, it sets all three above options simultaneously.
9815 In a line format, ordinary characters represent themselves;
9816 conversion specifications start with @samp{%} and have one of the
9821 stands for the contents of the line, not counting its trailing
9822 newline (if any). This format ignores whether the line is incomplete.
9825 stands for the contents of the line, including its trailing newline
9826 (if any). If a line is incomplete, this format preserves its
9830 stands for @samp{%}.
9833 where @var{C} is a single character, stands for @var{C}.
9834 @var{C} may not be a backslash or an apostrophe.
9835 For example, @samp{%c':'} stands for a colon.
9838 where @var{O} is a string of 1, 2, or 3 octal digits,
9839 stands for the character with octal code @var{O}.
9840 For example, @samp{%c'\0'} stands for a null character.
9843 where @var{F} is a @code{printf} conversion specification,
9844 stands for the line number formatted with @var{F}.
9845 For example, @samp{%.5dn} prints the line number using the
9846 @code{printf} format @code{"%.5d"}. @xref{Line group formats}, for
9847 more about printf conversion specifications.
9851 The default line format is @samp{%l} followed by a newline character.
9853 If the input contains tab characters and it is important that they line
9854 up on output, you should ensure that @samp{%l} or @samp{%L} in a line
9855 format is just after a tab stop (e.g.@: by preceding @samp{%l} or
9856 @samp{%L} with a tab character), or you should use the @samp{-t} or
9857 @samp{--expand-tabs} option.
9859 Taken together, the line and line group formats let you specify many
9860 different formats. For example, the following command uses a format
9861 similar to @code{diff}'s normal format. You can tailor this command
9862 to get fine control over @code{diff}'s output.
9866 --old-line-format='< %l
9868 --new-line-format='> %l
9870 --old-group-format='%df%(f=l?:,%dl)d%dE
9872 --new-group-format='%dea%dF%(F=L?:,%dL)
9874 --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL)
9877 --unchanged-group-format='' \
9881 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9883 @appendixsubsec diff examples
9885 The following line produces a Unidiff (@samp{-u} flag)
9886 between revision 1.14 and 1.19 of
9887 @file{backend.c}. Due to the @samp{-kk} flag no
9888 keywords are substituted, so differences that only depend
9889 on keyword substitution are ignored.
9892 $ cvs diff -kk -u -r 1.14 -r 1.19 backend.c
9895 Suppose the experimental branch EXPR1 was based on a
9896 set of files tagged RELEASE_1_0. To see what has
9897 happened on that branch, the following can be used:
9900 $ cvs diff -r RELEASE_1_0 -r EXPR1
9903 A command like this can be used to produce a context
9904 diff between two releases:
9907 $ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs
9910 If you are maintaining ChangeLogs, a command like the following
9911 just before you commit your changes may help you write
9912 the ChangeLog entry. All local modifications that have
9913 not yet been committed will be printed.
9916 $ cvs diff -u | less
9919 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
9921 @appendixsec export---Export sources from CVS, similar to checkout
9922 @cindex export (subcommand)
9926 Synopsis: export [-flNnR] [-r rev|-D date] [-k subst] [-d dir] module@dots{}
9928 Requires: repository.
9930 Changes: current directory.
9933 This command is a variant of @code{checkout}; use it
9934 when you want a copy of the source for module without
9935 the @sc{cvs} administrative directories. For example, you
9936 might use @code{export} to prepare source for shipment
9937 off-site. This command requires that you specify a
9938 date or tag (with @samp{-D} or @samp{-r}), so that you
9939 can count on reproducing the source you ship to others
9940 (and thus it always prunes empty directories).
9942 One often would like to use @samp{-kv} with @code{cvs
9943 export}. This causes any keywords to be
9944 expanded such that an import done at some other site
9945 will not lose the keyword revision information. But be
9946 aware that doesn't handle an export containing binary
9947 files correctly. Also be aware that after having used
9948 @samp{-kv}, one can no longer use the @code{ident}
9949 command (which is part of the @sc{rcs} suite---see
9950 ident(1)) which looks for keyword strings. If
9951 you want to be able to use @code{ident} you must not
9955 * export options:: export options
9958 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9959 @node export options
9960 @appendixsubsec export options
9962 These standard options are supported by @code{export}
9963 (@pxref{Common options}, for a complete description of
9968 Use the most recent revision no later than @var{date}.
9971 If no matching revision is found, retrieve the most
9972 recent revision (instead of ignoring the file).
9975 Local; run only in current working directory.
9978 Do not run any checkout program.
9981 Export directories recursively. This is on by default.
9984 Use revision @var{tag}.
9987 In addition, these options (that are common to
9988 @code{checkout} and @code{export}) are also supported:
9992 Create a directory called @var{dir} for the working
9993 files, instead of using the module name.
9994 See @ref{checkout options} for complete details on how
9995 @sc{cvs} handles this flag.
9997 @item -k @var{subst}
9998 Set keyword expansion mode (@pxref{Substitution modes}).
10001 Only useful together with @samp{-d @var{dir}}.
10002 See @ref{checkout options} for complete details on how
10003 @sc{cvs} handles this flag.
10007 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10008 @c @node export examples
10009 @appendixsubsec export examples
10011 Contributed examples are gratefully accepted.
10012 @c -- Examples here!!
10015 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
10017 @appendixsec history---Show status of files and users
10018 @cindex history (subcommand)
10022 Synopsis: history [-report] [-flags] [-options args] [files@dots{}]
10024 Requires: the file @file{$CVSROOT/CVSROOT/history}
10029 @sc{cvs} can keep a history file that tracks each use of the
10030 @code{checkout}, @code{commit}, @code{rtag},
10031 @code{update}, and @code{release} commands. You can
10032 use @code{history} to display this information in
10035 Logging must be enabled by creating the file
10036 @file{$CVSROOT/CVSROOT/history}.
10038 @strong{@code{history} uses @samp{-f}, @samp{-l},
10039 @samp{-n}, and @samp{-p} in ways that conflict with the
10040 normal use inside @sc{cvs} (@pxref{Common options}).}
10043 * history options:: history options
10046 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10047 @node history options
10048 @appendixsubsec history options
10050 Several options (shown above as @samp{-report}) control what
10051 kind of report is generated:
10055 Report on each time commit was used (i.e., each time
10056 the repository was modified).
10059 Everything (all record types). Equivalent to
10060 specifying @samp{-x} with all record types. Of course,
10061 @samp{-e} will also include record types which are
10062 added in a future version of @sc{cvs}; if you are
10063 writing a script which can only handle certain record
10064 types, you'll want to specify @samp{-x}.
10066 @item -m @var{module}
10067 Report on a particular module. (You can meaningfully
10068 use @samp{-m} more than once on the command line.)
10071 Report on checked-out modules. This is the default report type.
10074 Report on all tags.
10076 @item -x @var{type}
10077 Extract a particular set of record types @var{type} from the @sc{cvs}
10078 history. The types are indicated by single letters,
10079 which you may specify in combination.
10081 Certain commands have a single record type:
10095 One of five record types may result from an update:
10099 A merge was necessary but collisions were
10100 detected (requiring manual merging).
10102 A merge was necessary and it succeeded.
10104 A working file was copied from the repository.
10106 A working file was patched to match the repository.
10108 The working copy of a file was deleted during
10109 update (because it was gone from the repository).
10113 One of three record types results from commit:
10117 A file was added for the first time.
10119 A file was modified.
10121 A file was removed.
10125 The options shown as @samp{-flags} constrain or expand
10126 the report without requiring option arguments:
10130 Show data for all users (the default is to show data
10131 only for the user executing @code{history}).
10134 Show last modification only.
10137 Show only the records for modifications done from the
10138 same working directory where @code{history} is
10142 The options shown as @samp{-options @var{args}} constrain the report
10143 based on an argument:
10147 Show data back to a record containing the string
10148 @var{str} in either the module name, the file name, or
10149 the repository path.
10151 @item -D @var{date}
10152 Show data since @var{date}. This is slightly different
10153 from the normal use of @samp{-D @var{date}}, which
10154 selects the newest revision older than @var{date}.
10156 @item -f @var{file}
10157 Show data for a particular file
10158 (you can specify several @samp{-f} options on the same command line).
10159 This is equivalent to specifying the file on the command line.
10161 @item -n @var{module}
10162 Show data for a particular module
10163 (you can specify several @samp{-n} options on the same command line).
10165 @item -p @var{repository}
10166 Show data for a particular source repository (you
10167 can specify several @samp{-p} options on the same command
10171 Show records referring to revisions since the revision
10172 or tag named @var{rev} appears in individual @sc{rcs}
10173 files. Each @sc{rcs} file is searched for the revision or
10177 Show records since tag @var{tag} was last added to the
10178 history file. This differs from the @samp{-r} flag
10179 above in that it reads only the history file, not the
10180 @sc{rcs} files, and is much faster.
10182 @item -u @var{name}
10183 Show records for user @var{name}.
10185 @item -z @var{timezone}
10186 Show times in the selected records using the specified
10187 time zone instead of UTC.
10191 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10192 @c @node history examples
10193 @appendixsubsec history examples
10195 Contributed examples will gratefully be accepted.
10196 @c -- Examples here!
10199 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
10201 @appendixsec import---Import sources into CVS, using vendor branches
10202 @cindex import (subcommand)
10204 @c FIXME: This node is way too long for one which has subnodes.
10208 Synopsis: import [-options] repository vendortag releasetag@dots{}
10210 Requires: Repository, source distribution directory.
10212 Changes: repository.
10215 Use @code{import} to incorporate an entire source
10216 distribution from an outside source (e.g., a source
10217 vendor) into your source repository directory. You can
10218 use this command both for initial creation of a
10219 repository, and for wholesale updates to the module
10220 from the outside source. See @ref{Tracking sources} for
10221 a discussion on this subject.
10223 The @var{repository} argument gives a directory name
10224 (or a path to a directory) under the @sc{cvs} root directory
10225 for repositories; if the directory did not exist,
10228 When you use import for updates to source that has been
10229 modified in your source repository (since a prior
10230 import), it will notify you of any files that conflict
10231 in the two branches of development; use @samp{checkout
10232 -j} to reconcile the differences, as import instructs
10235 If @sc{cvs} decides a file should be ignored
10236 (@pxref{cvsignore}), it does not import it and prints
10237 @samp{I } followed by the filename (@pxref{import output} for a
10238 complete description of the output).
10240 If the file @file{$CVSROOT/CVSROOT/cvswrappers} exists,
10241 any file whose names match the specifications in that
10242 file will be treated as packages and the appropriate
10243 filtering will be performed on the file/directory
10244 before being imported. See @ref{Wrappers}.
10246 The outside source is saved in a first-level
10247 branch, by default 1.1.1. Updates are leaves of this
10248 branch; for example, files from the first imported
10249 collection of source will be revision 1.1.1.1, then
10250 files from the first imported update will be revision
10251 1.1.1.2, and so on.
10253 At least three arguments are required.
10254 @var{repository} is needed to identify the collection
10255 of source. @var{vendortag} is a tag for the entire
10256 branch (e.g., for 1.1.1). You must also specify at
10257 least one @var{releasetag} to uniquely identify the files at
10258 the leaves created each time you execute @code{import}. The
10259 @var{releasetag} should be new, not previously existing in the
10260 repository file, and uniquely identify the imported release,
10262 @c I'm not completely sure this belongs here. But
10263 @c we need to say it _somewhere_ reasonably obvious; it
10264 @c is a common misconception among people first learning CVS
10265 Note that @code{import} does @emph{not} change the
10266 directory in which you invoke it. In particular, it
10267 does not set up that directory as a @sc{cvs} working
10268 directory; if you want to work with the sources import
10269 them first and then check them out into a different
10270 directory (@pxref{Getting the source}).
10273 * import options:: import options
10274 * import output:: import output
10275 * import examples:: import examples
10278 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10279 @node import options
10280 @appendixsubsec import options
10282 This standard option is supported by @code{import}
10283 (@pxref{Common options} for a complete description):
10286 @item -m @var{message}
10287 Use @var{message} as log information, instead of
10288 invoking an editor.
10291 There are the following additional special options.
10294 @item -b @var{branch}
10295 See @ref{Multiple vendor branches}.
10297 @item -k @var{subst}
10298 Indicate the keyword expansion mode desired. This
10299 setting will apply to all files created during the
10300 import, but not to any files that previously existed in
10301 the repository. See @ref{Substitution modes} for a
10302 list of valid @samp{-k} settings.
10304 @item -I @var{name}
10305 Specify file names that should be ignored during
10306 import. You can use this option repeatedly. To avoid
10307 ignoring any files at all (even those ignored by
10308 default), specify `-I !'.
10310 @var{name} can be a file name pattern of the same type
10311 that you can specify in the @file{.cvsignore} file.
10312 See @ref{cvsignore}.
10313 @c -- Is this really true?
10315 @item -W @var{spec}
10316 Specify file names that should be filtered during
10317 import. You can use this option repeatedly.
10319 @var{spec} can be a file name pattern of the same type
10320 that you can specify in the @file{.cvswrappers}
10321 file. @xref{Wrappers}.
10324 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10325 @node import output
10326 @appendixsubsec import output
10328 @code{import} keeps you informed of its progress by printing a line
10329 for each file, preceded by one character indicating the status of the file:
10333 The file already exists in the repository and has not been locally
10334 modified; a new revision has been created (if necessary).
10337 The file is a new file which has been added to the repository.
10340 The file already exists in the repository but has been locally modified;
10341 you will have to merge the changes.
10344 The file is being ignored (@pxref{cvsignore}).
10346 @cindex Symbolic link, importing
10347 @cindex Link, symbolic, importing
10348 @c FIXME: also (somewhere else) probably
10349 @c should be documenting what happens if you "cvs add"
10350 @c a symbolic link. Also maybe what happens if
10351 @c you manually create symbolic links within the
10352 @c repository (? - not sure why we'd want to suggest
10355 The file is a symbolic link; @code{cvs import} ignores symbolic links.
10356 People periodically suggest that this behavior should
10357 be changed, but if there is a consensus on what it
10358 should be changed to, it doesn't seem to be apparent.
10359 (Various options in the @file{modules} file can be used
10360 to recreate symbolic links on checkout, update, etc.;
10364 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10365 @node import examples
10366 @appendixsubsec import examples
10368 See @ref{Tracking sources}, and @ref{From files}.
10370 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
10372 @appendixsec log---Print out log information for files
10373 @cindex log (subcommand)
10377 Synopsis: log [options] [files@dots{}]
10379 Requires: repository, working directory.
10384 Display log information for files. @code{log} used to
10385 call the @sc{rcs} utility @code{rlog}. Although this
10386 is no longer true in the current sources, this history
10387 determines the format of the output and the options,
10388 which are not quite in the style of the other @sc{cvs}
10391 @cindex Timezone, in output
10392 @cindex Zone, time, in output
10393 @c Kind of a funny place to document the timezone used
10394 @c in output from commands other than @code{log}.
10395 @c There is also more we need to say about this,
10396 @c including what happens in a client/server environment.
10397 The output includes the location of the @sc{rcs} file,
10398 the @dfn{head} revision (the latest revision on the
10399 trunk), all symbolic names (tags) and some other
10400 things. For each revision, the revision number, the
10401 author, the number of lines added/deleted and the log
10402 message are printed. All times are displayed in
10403 Coordinated Universal Time (UTC). (Other parts of
10404 @sc{cvs} print times in the local timezone).
10405 @c FIXCVS: need a better way to control the timezone
10406 @c used in output. Previous/current versions of CVS did/do
10407 @c sometimes support -z in RCSINIT, and/or an
10408 @c undocumented (except by reference to 'rlog') -z option
10409 @c to cvs log, but this has not been a consistent,
10410 @c documented feature. Perhaps a new global option,
10411 @c where LT means the client's timezone, which the
10412 @c client then communicates to the server, is the
10415 @strong{@code{log} uses @samp{-R} in a way that conflicts
10416 with the normal use inside @sc{cvs} (@pxref{Common options}).}
10419 * log options:: log options
10420 * log examples:: log examples
10423 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10425 @appendixsubsec log options
10427 By default, @code{log} prints all information that is
10428 available. All other options restrict the output. Note that the revision
10429 selection options (@code{-b}, @code{-d}, @code{-r}, @code{-s}, and @code{-w})
10431 effect, other than possibly causing a search for files in Attic directories,
10432 when used in conjunction with the options that restrict the output to only
10433 @code{log} header fields (@code{-h}, @code{-R}, and @code{-t})
10434 unless the @code{-S} option is also specified.
10438 Print information about the revisions on the default
10439 branch, normally the highest branch on the trunk.
10441 @item -d @var{dates}
10442 Print information about revisions with a checkin
10443 date/time in the range given by the
10444 semicolon-separated list of dates. The date formats
10445 accepted are those accepted by the @samp{-D} option to
10446 many other @sc{cvs} commands (@pxref{Common options}).
10447 Dates can be combined into ranges as follows:
10449 @c Should we be thinking about accepting ISO8601
10450 @c ranges? For example "1972-09-10/1972-09-12".
10452 @item @var{d1}<@var{d2}
10453 @itemx @var{d2}>@var{d1}
10454 Select the revisions that were deposited between
10455 @var{d1} and @var{d2}.
10459 Select all revisions dated @var{d} or earlier.
10463 Select all revisions dated @var{d} or later.
10466 Select the single, latest revision dated @var{d} or
10470 The @samp{>} or @samp{<} characters may be followed by
10471 @samp{=} to indicate an inclusive range rather than an
10474 Note that the separator is a semicolon (;).
10477 Print only the name of the @sc{rcs} file, name
10478 of the file in the working directory, head,
10479 default branch, access list, locks, symbolic names, and
10483 Local; run only in current working directory. (Default
10484 is to run recursively).
10487 Do not print the list of tags for this file. This
10488 option can be very useful when your site uses a lot of
10489 tags, so rather than "more"'ing over 3 pages of tag
10490 information, the log information is presented without
10494 Print the list of tags for this file. This option can
10495 be very useful when your @file{.cvsrc} file has a
10496 @samp{log -N} entry as a way to get a full list of all
10500 Print only the name of the @sc{rcs} file.
10502 @c Note that using a bare revision (in addition to not
10503 @c being explicitly documented here) is potentially
10504 @c confusing; it shows the log message to get from the
10505 @c previous revision to that revision. "-r1.3 -r1.6"
10506 @c (equivalent to "-r1.3,1.6") is even worse; it
10507 @c prints the messages to get from 1.2 to 1.3 and 1.5
10508 @c to 1.6. By analogy with "cvs diff", users might
10509 @c expect that it is more like specifying a range.
10510 @c It is not 100% clear to me how much of this should
10511 @c be documented (for example, multiple -r options
10512 @c perhaps could/should be deprecated given the false
10513 @c analogy with "cvs diff").
10514 @c In general, this section should be rewritten to talk
10515 @c about messages to get from revision rev1 to rev2,
10516 @c rather than messages for revision rev2 (that is, the
10517 @c messages are associated with a change not a static
10518 @c revision and failing to make this distinction causes
10519 @c much confusion).
10520 @item -r@var{revisions}
10521 Print information about revisions given in the
10522 comma-separated list @var{revisions} of revisions and
10523 ranges. The following table explains the available
10527 @item @var{rev1}:@var{rev2}
10528 Revisions @var{rev1} to @var{rev2} (which must be on
10531 @item @var{rev1}::@var{rev2}
10532 The same, but excluding @var{rev1}.
10536 Revisions from the beginning of the branch up to
10537 and including @var{rev}.
10540 Revisions starting with @var{rev} to the end of the
10541 branch containing @var{rev}.
10544 Revisions starting just after @var{rev} to the end of the
10545 branch containing @var{rev}.
10548 An argument that is a branch means all revisions on
10551 @item @var{branch1}:@var{branch2}
10552 @itemx @var{branch1}::@var{branch2}
10553 A range of branches means all revisions
10554 on the branches in that range.
10556 @item @var{branch}.
10557 The latest revision in @var{branch}.
10560 A bare @samp{-r} with no revisions means the latest
10561 revision on the default branch, normally the trunk.
10562 There can be no space between the @samp{-r} option and
10566 Suppress the header if no revisions are selected.
10568 @item -s @var{states}
10569 Print information about revisions whose state
10570 attributes match one of the states given in the
10571 comma-separated list @var{states}. Individual states may
10572 be any text string, though @sc{cvs} commonly only uses two
10573 states, @samp{Exp} and @samp{dead}. See @ref{admin options}
10574 for more information.
10577 Print the same as @samp{-h}, plus the descriptive text.
10579 @item -w@var{logins}
10580 Print information about revisions checked in by users
10581 with login names appearing in the comma-separated list
10582 @var{logins}. If @var{logins} is omitted, the user's
10583 login is assumed. There can be no space between the
10584 @samp{-w} option and its argument.
10587 @code{log} prints the intersection of the revisions
10588 selected with the options @samp{-d}, @samp{-s}, and
10589 @samp{-w}, intersected with the union of the revisions
10590 selected by @samp{-b} and @samp{-r}.
10592 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10594 @appendixsubsec log examples
10596 Contributed examples are gratefully accepted.
10598 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
10600 @appendixsec rdiff---'patch' format diffs between releases
10601 @cindex rdiff (subcommand)
10605 rdiff [-flags] [-V vn] [-r t|-D d [-r t2|-D d2]] modules@dots{}
10607 Requires: repository.
10614 Builds a Larry Wall format patch(1) file between two
10615 releases, that can be fed directly into the @code{patch}
10616 program to bring an old release up-to-date with the new
10617 release. (This is one of the few @sc{cvs} commands that
10618 operates directly from the repository, and doesn't
10619 require a prior checkout.) The diff output is sent to
10620 the standard output device.
10622 You can specify (using the standard @samp{-r} and
10623 @samp{-D} options) any combination of one or two
10624 revisions or dates. If only one revision or date is
10625 specified, the patch file reflects differences between
10626 that revision or date and the current head revisions in
10629 Note that if the software release affected is contained
10630 in more than one directory, then it may be necessary to
10631 specify the @samp{-p} option to the @code{patch} command when
10632 patching the old sources, so that @code{patch} is able to find
10633 the files that are located in other directories.
10636 * rdiff options:: rdiff options
10637 * rdiff examples:: rdiff examples
10640 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10641 @node rdiff options
10642 @appendixsubsec rdiff options
10644 These standard options are supported by @code{rdiff}
10645 (@pxref{Common options} for a complete description of
10649 @item -D @var{date}
10650 Use the most recent revision no later than @var{date}.
10653 If no matching revision is found, retrieve the most
10654 recent revision (instead of ignoring the file).
10656 @item -k @var{kflag}
10657 Process keywords according to @var{kflag}. See
10658 @ref{Keyword substitution}.
10661 Local; don't descend subdirectories.
10664 Examine directories recursively. This option is on by default.
10667 Use revision @var{tag}.
10670 In addition to the above, these options are available:
10674 Use the context diff format. This is the default format.
10677 Create a summary change report instead of a patch. The
10678 summary includes information about files that were
10679 changed or added between the releases. It is sent to
10680 the standard output device. This is useful for finding
10681 out, for example, which files have changed between two
10682 dates or revisions.
10685 A diff of the top two revisions is sent to the standard
10686 output device. This is most useful for seeing what the
10687 last change to a file was.
10690 Use the unidiff format for the context diffs.
10691 Remember that old versions
10692 of the @code{patch} program can't handle the unidiff
10693 format, so if you plan to post this patch to the net
10694 you should probably not use @samp{-u}.
10697 Expand keywords according to the rules current in
10698 @sc{rcs} version @var{vn} (the expansion format changed with
10699 @sc{rcs} version 5). Note that this option is no
10700 longer accepted. @sc{cvs} will always expand keywords the
10701 way that @sc{rcs} version 5 does.
10704 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10705 @node rdiff examples
10706 @appendixsubsec rdiff examples
10708 Suppose you receive mail from @t{foo@@example.net} asking for an
10709 update from release 1.2 to 1.4 of the tc compiler. You
10710 have no such patches on hand, but with @sc{cvs} that can
10711 easily be fixed with a command such as this:
10714 $ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \
10715 > Mail -s 'The patches you asked for' foo@@example.net
10718 Suppose you have made release 1.3, and forked a branch
10719 called @samp{R_1_3fix} for bug fixes. @samp{R_1_3_1}
10720 corresponds to release 1.3.1, which was made some time
10721 ago. Now, you want to see how much development has been
10722 done on the branch. This command can be used:
10725 $ cvs patch -s -r R_1_3_1 -r R_1_3fix module-name
10726 cvs rdiff: Diffing module-name
10727 File ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6
10728 File foo.c,v changed from revision 1.52.2.3 to 1.52.2.4
10729 File bar.h,v changed from revision 1.29.2.1 to 1.2
10732 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
10734 @appendixsec release---Indicate that a Module is no longer in use
10735 @cindex release (subcommand)
10739 release [-d] directories@dots{}
10741 Requires: Working directory.
10743 Changes: Working directory, history log.
10746 This command is meant to safely cancel the effect of
10747 @samp{cvs checkout}. Since @sc{cvs} doesn't lock files, it
10748 isn't strictly necessary to use this command. You can
10749 always simply delete your working directory, if you
10750 like; but you risk losing changes you may have
10751 forgotten, and you leave no trace in the @sc{cvs} history
10752 file (@pxref{history file}) that you've abandoned your
10755 Use @samp{cvs release} to avoid these problems. This
10756 command checks that no uncommitted changes are
10757 present; that you are executing it from immediately
10758 above a @sc{cvs} working directory; and that the repository
10759 recorded for your files is the same as the repository
10760 defined in the module database.
10762 If all these conditions are true, @samp{cvs release}
10763 leaves a record of its execution (attesting to your
10764 intentionally abandoning your checkout) in the @sc{cvs}
10768 * release options:: release options
10769 * release output:: release output
10770 * release examples:: release examples
10773 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10774 @node release options
10775 @appendixsubsec release options
10777 The @code{release} command supports one command option:
10781 Delete your working copy of the file if the release
10782 succeeds. If this flag is not given your files will
10783 remain in your working directory.
10785 @strong{WARNING: The @code{release} command deletes
10786 all directories and files recursively. This
10787 has the very serious side-effect that any directory
10788 created inside checked-out sources, and not added to
10789 the repository (using the @code{add} command;
10790 @pxref{Adding files}) will be silently deleted---even
10791 if it is non-empty!}
10794 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10795 @node release output
10796 @appendixsubsec release output
10798 Before @code{release} releases your sources it will
10799 print a one-line message for any file that is not
10804 @itemx P @var{file}
10805 There exists a newer revision of this file in the
10806 repository, and you have not modified your local copy
10807 of the file (@samp{U} and @samp{P} mean the same thing).
10810 The file has been added to your private copy of the
10811 sources, but has not yet been committed to the
10812 repository. If you delete your copy of the sources
10813 this file will be lost.
10816 The file has been removed from your private copy of the
10817 sources, but has not yet been removed from the
10818 repository, since you have not yet committed the
10819 removal. See @ref{commit}.
10822 The file is modified in your working directory. There
10823 might also be a newer revision inside the repository.
10826 @var{file} is in your working directory, but does not
10827 correspond to anything in the source repository, and is
10828 not in the list of files for @sc{cvs} to ignore (see the
10829 description of the @samp{-I} option, and
10830 @pxref{cvsignore}). If you remove your working
10831 sources, this file will be lost.
10834 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10835 @node release examples
10836 @appendixsubsec release examples
10838 Release the @file{tc} directory, and delete your local working copy
10842 $ cd .. # @r{You must stand immediately above the}
10843 # @r{sources when you issue @samp{cvs release}.}
10844 $ cvs release -d tc
10845 You have [0] altered files in this repository.
10846 Are you sure you want to release (and delete) directory `tc': y
10850 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
10852 @appendixsec remove---Remove files from active use
10853 @cindex remove (subcommand)
10857 Synopsis: remove [-flR] [files...]
10859 Requires: repository, working directory.
10861 Changes: working directory.
10864 The @code{remove} command is used to remove unwanted
10865 files from active use. The user normally deletes the
10866 files from the working directory prior to invocation
10867 of the @code{remove} command. Only the working
10868 directory is updated. Changes to the repository are
10869 not made until the @code{commit} command is run.
10871 The @code{remove} command does not delete files from
10872 from the repository. @sc{cvs} keeps all historical
10873 data in the repository so that it is possible to
10874 reconstruct previous states of the projects under
10877 To undo @sc{cvs} @code{remove} or to resurrect files
10878 that were previously removed, @xref{add}.
10881 * remove options:: remove options
10882 * remove examples:: remove examples
10885 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10886 @node remove options
10887 @appendixsubsec remove options
10889 These standard options are supported by @code{remove}
10890 (@pxref{Common options} for a complete description of
10895 Local; run only in current working directory. See @ref{Recursive behavior}.
10898 Process directories recursively. See @ref{Recursive behavior}.
10902 In addition, these options are also supported:
10906 Note that this is not the standard behavior of
10907 the @samp{-f} option as defined in @ref{Common options}.
10909 Delete files before removing them.
10911 Entire directory hierarchies are easily removed
10912 using @samp{-f}, but take note that it is not as
10913 easy to resurrect directory hierarchies as it is
10918 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10919 @node remove examples
10920 @appendixsubsec remove examples
10922 @appendixsubsubsec Removing a file
10925 $ cvs remove remove.me
10926 cvs remove: file `remove.me' still in working directory
10927 cvs remove: 1 file exists; remove it first
10929 $ cvs remove remove.me
10930 cvs remove: scheduling `remove.me' for removal
10931 cvs remove: use 'cvs commit' to remove this file permanently
10935 $ cvs remove -f remove.it
10936 cvs remove: scheduling `remove.it' for removal
10937 cvs remove: use 'cvs commit' to remove this file permanently
10940 @appendixsubsubsec Removing entire directories
10950 cvs remove: Removing a
10951 cvs remove: Removing a/b
10952 cvs remove: scheduling `a/b/c' for removal
10953 cvs remove: use 'cvs commit' to remove this file permanently
10956 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
10958 @appendixsec update---Bring work tree in sync with repository
10959 @cindex update (subcommand)
10963 update [-ACdflPpR] [-I name] [-j rev [-j rev]] [-k kflag] [-r tag|-D date] [-W spec] files@dots{}
10965 Requires: repository, working directory.
10967 Changes: working directory.
10970 After you've run checkout to create your private copy
10971 of source from the common repository, other developers
10972 will continue changing the central source. From time
10973 to time, when it is convenient in your development
10974 process, you can use the @code{update} command from
10975 within your working directory to reconcile your work
10976 with any revisions applied to the source repository
10977 since your last checkout or update.
10980 * update options:: update options
10981 * update output:: update output
10984 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10985 @node update options
10986 @appendixsubsec update options
10988 These standard options are available with @code{update}
10989 (@pxref{Common options} for a complete description of
10994 Use the most recent revision no later than @var{date}.
10995 This option is sticky, and implies @samp{-P}.
10996 See @ref{Sticky tags} for more information on sticky tags/dates.
10999 Only useful with the @samp{-D @var{date}} or @samp{-r
11000 @var{tag}} flags. If no matching revision is found,
11001 retrieve the most recent revision (instead of ignoring
11004 @item -k @var{kflag}
11005 Process keywords according to @var{kflag}. See
11006 @ref{Keyword substitution}.
11007 This option is sticky; future updates of
11008 this file in this working directory will use the same
11009 @var{kflag}. The @code{status} command can be viewed
11010 to see the sticky options. See @ref{Invoking CVS} for
11011 more information on the @code{status} command.
11014 Local; run only in current working directory. See @ref{Recursive behavior}.
11017 Prune empty directories. See @ref{Moving directories}.
11020 Pipe files to the standard output.
11023 Update directories recursively (default). See @ref{Recursive
11027 Retrieve revision/tag @var{rev}. This option is sticky,
11028 and implies @samp{-P}.
11029 See @ref{Sticky tags}, for more information on sticky tags/dates.
11033 These special options are also available with
11038 Reset any sticky tags, dates, or @samp{-k} options.
11039 Does not reset sticky @samp{-k} options on modified files.
11040 See @ref{Sticky tags} for more information on sticky tags/dates.
11043 Overwrite locally modified files with clean copies from
11044 the repository (the modified file is saved in
11045 @file{.#@var{file}.@var{revision}}, however).
11048 Create any directories that exist in the repository if
11049 they're missing from the working directory. Normally,
11050 @code{update} acts only on directories and files that
11051 were already enrolled in your working directory.
11053 This is useful for updating directories that were
11054 created in the repository since the initial checkout;
11055 but it has an unfortunate side effect. If you
11056 deliberately avoided certain directories in the
11057 repository when you created your working directory
11058 (either through use of a module name or by listing
11059 explicitly the files and directories you wanted on the
11060 command line), then updating with @samp{-d} will create
11061 those directories, which may not be what you want.
11063 @item -I @var{name}
11064 Ignore files whose names match @var{name} (in your
11065 working directory) during the update. You can specify
11066 @samp{-I} more than once on the command line to specify
11067 several files to ignore. Use @samp{-I !} to avoid
11068 ignoring any files at all. See @ref{cvsignore} for other
11069 ways to make @sc{cvs} ignore some files.
11072 Specify file names that should be filtered during
11073 update. You can use this option repeatedly.
11075 @var{spec} can be a file name pattern of the same type
11076 that you can specify in the @file{.cvswrappers}
11077 file. See @ref{Wrappers}.
11079 @item -j@var{revision}
11080 With two @samp{-j} options, merge changes from the
11081 revision specified with the first @samp{-j} option to
11082 the revision specified with the second @samp{j} option,
11083 into the working directory.
11085 With one @samp{-j} option, merge changes from the
11086 ancestor revision to the revision specified with the
11087 @samp{-j} option, into the working directory. The
11088 ancestor revision is the common ancestor of the
11089 revision which the working directory is based on, and
11090 the revision specified in the @samp{-j} option.
11092 Note that using a single @samp{-j @var{tagname}} option rather than
11093 @samp{-j @var{branchname}} to merge changes from a branch will
11094 often not remove files which were removed on the branch.
11095 See @ref{Merging adds and removals} for more information.
11097 In addition, each @samp{-j} option can contain an optional
11098 date specification which, when used with branches, can
11099 limit the chosen revision to one within a specific
11100 date. An optional date is specified by adding a colon
11102 @samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}.
11104 See @ref{Branching and merging}.
11108 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11109 @node update output
11110 @appendixsubsec update output
11112 @code{update} and @code{checkout} keep you informed of
11113 their progress by printing a line for each file, preceded
11114 by one character indicating the status of the file:
11118 The file was brought up to date with respect to the
11119 repository. This is done for any file that exists in
11120 the repository but not in your working directory, and for files
11121 that you haven't changed but are not the most recent
11122 versions available in the repository.
11125 Like @samp{U}, but the @sc{cvs} server sends a patch instead of an entire
11126 file. This accomplishes the same thing as @samp{U} using less bandwidth.
11129 The file has been added to your private copy of the
11130 sources, and will be added to the source repository
11131 when you run @code{commit} on the file. This is a
11132 reminder to you that the file needs to be committed.
11135 The file has been removed from your private copy of the
11136 sources, and will be removed from the source repository
11137 when you run @code{commit} on the file. This is a
11138 reminder to you that the file needs to be committed.
11141 The file is modified in your working directory.
11143 @samp{M} can indicate one of two states for a file
11144 you're working on: either there were no modifications
11145 to the same file in the repository, so that your file
11146 remains as you last saw it; or there were modifications
11147 in the repository as well as in your copy, but they
11148 were merged successfully, without conflict, in your
11151 @sc{cvs} will print some messages if it merges your work,
11152 and a backup copy of your working file (as it looked
11153 before you ran @code{update}) will be made. The exact
11154 name of that file is printed while @code{update} runs.
11158 @cindex __ files (VMS)
11159 A conflict was detected while trying to merge your
11160 changes to @var{file} with changes from the source
11161 repository. @var{file} (the copy in your working
11162 directory) is now the result of attempting to merge
11163 the two revisions; an unmodified copy of your file
11164 is also in your working directory, with the name
11165 @file{.#@var{file}.@var{revision}} where @var{revision}
11166 is the revision that your modified file started
11167 from. Resolve the conflict as described in
11168 @ref{Conflicts example}.
11169 @c "some systems" as in out-of-the-box OSes? Not as
11170 @c far as I know. We need to advise sysadmins as well
11171 @c as users how to set up this kind of purge, if that is
11173 @c We also might want to think about cleaner solutions,
11174 @c like having CVS remove the .# file once the conflict
11175 @c has been resolved or something like that.
11176 (Note that some systems automatically purge
11177 files that begin with @file{.#} if they have not been
11178 accessed for a few days. If you intend to keep a copy
11179 of your original file, it is a very good idea to rename
11180 it.) Under @sc{vms}, the file name starts with
11181 @file{__} rather than @file{.#}.
11184 @var{file} is in your working directory, but does not
11185 correspond to anything in the source repository, and is
11186 not in the list of files for @sc{cvs} to ignore (see the
11187 description of the @samp{-I} option, and
11188 @pxref{cvsignore}).
11191 @c ----- END MAN 1 -----
11192 @c ---------------------------------------------------------------------
11194 @appendix Quick reference to CVS commands
11195 @cindex Command reference
11196 @cindex Reference, commands
11197 @cindex Invoking CVS
11199 This appendix describes how to invoke @sc{cvs}, with
11200 references to where each command or feature is
11201 described in detail. For other references run the
11202 @code{cvs --help} command, or see @ref{Index}.
11204 A @sc{cvs} command looks like:
11207 cvs [ @var{global_options} ] @var{command} [ @var{command_options} ] [ @var{command_args} ]
11213 @item --allow-root=@var{rootdir}
11214 Specify legal @sc{cvsroot} directory (server only) (not
11215 in @sc{cvs} 1.9 and older). See @ref{Password
11216 authentication server}.
11219 Authenticate all communication (client only) (not in @sc{cvs}
11220 1.9 and older). See @ref{Global options}.
11223 Specify RCS location (@sc{cvs} 1.9 and older). See
11224 @ref{Global options}.
11226 @item -d @var{root}
11227 Specify the @sc{cvsroot}. See @ref{Repository}.
11229 @item -e @var{editor}
11230 Edit messages with @var{editor}. See @ref{Committing
11234 Do not read the @file{~/.cvsrc} file. See @ref{Global
11239 Print a help message. See @ref{Global options}.
11242 Do not change any files. See @ref{Global options}.
11245 Be really quiet. See @ref{Global options}.
11248 Be somewhat quiet. See @ref{Global options}.
11251 Make new working files read-only. See @ref{Global options}.
11253 @item -s @var{variable}=@var{value}
11254 Set a user variable. See @ref{Variables}.
11256 @item -T @var{tempdir}
11257 Put temporary files in @var{tempdir}. See @ref{Global
11261 Trace @sc{cvs} execution. See @ref{Global options}.
11265 Display version and copyright information for @sc{cvs}.
11268 Make new working files read-write. See @ref{Global
11272 Encrypt all communication (client only).
11273 See @ref{Global options}.
11275 @item -z @var{gzip-level}
11276 @cindex Compression
11278 Set the compression level (client only).
11279 See @ref{Global options}.
11282 Keyword expansion modes (@pxref{Substitution modes}):
11285 -kkv $@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp $
11286 -kkvl $@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
11287 -kk $@splitrcskeyword{Id}$
11288 -kv file1,v 1.1 1993/12/09 03:21:13 joe Exp
11289 -ko @i{no expansion}
11290 -kb @i{no expansion, file is binary}
11293 Keywords (@pxref{Keyword list}):
11296 $@splitrcskeyword{Author}: joe $
11297 $@splitrcskeyword{Date}: 1993/12/09 03:21:13 $
11298 $@splitrcskeyword{Header}: /home/files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
11299 $@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
11300 $@splitrcskeyword{Locker}: harry $
11301 $@splitrcskeyword{Name}: snapshot_1_14 $
11302 $@splitrcskeyword{RCSfile}: file1,v $
11303 $@splitrcskeyword{Revision}: 1.1 $
11304 $@splitrcskeyword{Source}: /home/files/file1,v $
11305 $@splitrcskeyword{State}: Exp $
11306 $@splitrcskeyword{Log}: file1,v $
11307 Revision 1.1 1993/12/09 03:30:17 joe
11312 @c The idea behind this table is that we want each item
11313 @c to be a sentence or two at most. Preferably a
11316 @c In some cases refs to "foo options" are just to get
11317 @c this thing written quickly, not because the "foo
11318 @c options" node is really the best place to point.
11319 Commands, command options, and command arguments:
11322 @c ------------------------------------------------------------
11323 @item add [@var{options}] [@var{files}@dots{}]
11324 Add a new file/directory. See @ref{Adding files}.
11327 @item -k @var{kflag}
11328 Set keyword expansion.
11331 Set file description.
11334 @c ------------------------------------------------------------
11335 @item admin [@var{options}] [@var{files}@dots{}]
11336 Administration of history files in the repository. See
11338 @c This list omits those options which are not
11339 @c documented as being useful with CVS. That might be
11343 @item -b[@var{rev}]
11344 Set default branch. See @ref{Reverting local changes}.
11346 @item -c@var{string}
11347 Set comment leader.
11349 @item -k@var{subst}
11350 Set keyword substitution. See @ref{Keyword
11353 @item -l[@var{rev}]
11354 Lock revision @var{rev}, or latest revision.
11356 @item -m@var{rev}:@var{msg}
11357 Replace the log message of revision @var{rev} with
11360 @item -o@var{range}
11361 Delete revisions from the repository. See
11362 @ref{admin options}.
11365 Run quietly; do not print diagnostics.
11367 @item -s@var{state}[:@var{rev}]
11368 Set the state. See @ref{admin options} for more information on possible
11371 @c Does not work for client/server CVS
11373 Set file description from standard input.
11376 Set file description from @var{file}.
11378 @item -t-@var{string}
11379 Set file description to @var{string}.
11381 @item -u[@var{rev}]
11382 Unlock revision @var{rev}, or latest revision.
11385 @c ------------------------------------------------------------
11386 @item annotate [@var{options}] [@var{files}@dots{}]
11387 Show last revision where each line was modified. See
11391 @item -D @var{date}
11392 Annotate the most recent revision no later than
11393 @var{date}. See @ref{Common options}.
11396 Force annotation of binary files. (Without this option,
11397 binary files are skipped with a message.)
11400 Use head revision if tag/date not found. See
11401 @ref{Common options}.
11404 Local; run only in current working directory. @xref{Recursive behavior}.
11407 Operate recursively (default). @xref{Recursive
11411 Annotate revision @var{tag}. See @ref{Common options}.
11414 @c ------------------------------------------------------------
11415 @item checkout [@var{options}] @var{modules}@dots{}
11416 Get a copy of the sources. See @ref{checkout}.
11420 Reset any sticky tags/date/options. See @ref{Sticky
11421 tags} and @ref{Keyword substitution}.
11424 Output the module database. See @ref{checkout options}.
11426 @item -D @var{date}
11427 Check out revisions as of @var{date} (is sticky). See
11428 @ref{Common options}.
11431 Check out into @var{dir}. See @ref{checkout options}.
11434 Use head revision if tag/date not found. See
11435 @ref{Common options}.
11437 @c Probably want to use rev1/rev2 style like for diff
11438 @c -r. Here and in on-line help.
11440 Merge in changes. See @ref{checkout options}.
11442 @item -k @var{kflag}
11443 Use @var{kflag} keyword expansion. See
11444 @ref{Substitution modes}.
11447 Local; run only in current working directory. @xref{Recursive behavior}.
11450 Don't ``shorten'' module paths if -d specified. See
11451 @ref{checkout options}.
11454 Do not run module program (if any). See @ref{checkout options}.
11457 Prune empty directories. See @ref{Moving directories}.
11460 Check out files to standard output (avoids
11461 stickiness). See @ref{checkout options}.
11464 Operate recursively (default). @xref{Recursive
11468 Checkout revision @var{tag} (is sticky). See @ref{Common options}.
11471 Like -c, but include module status. See @ref{checkout options}.
11474 @c ------------------------------------------------------------
11475 @item commit [@var{options}] [@var{files}@dots{}]
11476 Check changes into the repository. See @ref{commit}.
11479 @item -F @var{file}
11480 Read log message from @var{file}. See @ref{commit options}.
11483 @c What is this "disables recursion"? It is from the
11484 @c on-line help; is it documented in this manual?
11485 Force the file to be committed; disables recursion.
11486 See @ref{commit options}.
11489 Local; run only in current working directory. See @ref{Recursive behavior}.
11492 Use @var{msg} as log message. See @ref{commit options}.
11495 Do not run module program (if any). See @ref{commit options}.
11498 Operate recursively (default). @xref{Recursive
11502 Commit to @var{rev}. See @ref{commit options}.
11503 @c FIXME: should be dragging over text from
11504 @c commit options, especially if it can be cleaned up
11505 @c and made concise enough.
11508 @c ------------------------------------------------------------
11509 @item diff [@var{options}] [@var{files}@dots{}]
11510 Show differences between revisions. See @ref{diff}.
11511 In addition to the options shown below, accepts a wide
11512 variety of options to control output style, for example
11513 @samp{-c} for context diffs.
11516 @item -D @var{date1}
11517 Diff revision for date against working file. See
11518 @ref{diff options}.
11520 @item -D @var{date2}
11521 Diff @var{rev1}/@var{date1} against @var{date2}. See
11522 @ref{diff options}.
11525 Local; run only in current working directory. See @ref{Recursive behavior}.
11528 Include diffs for added and removed files. See
11529 @ref{diff options}.
11532 Operate recursively (default). @xref{Recursive
11535 @item -r @var{rev1}
11536 Diff revision for @var{rev1} against working file. See
11537 @ref{diff options}.
11539 @item -r @var{rev2}
11540 Diff @var{rev1}/@var{date1} against @var{rev2}. See @ref{diff options}.
11543 @c ------------------------------------------------------------
11544 @item edit [@var{options}] [@var{files}@dots{}]
11545 Get ready to edit a watched file. See @ref{Editing files}.
11548 @item -a @var{actions}
11549 Specify actions for temporary watch, where
11550 @var{actions} is @code{edit}, @code{unedit},
11551 @code{commit}, @code{all}, or @code{none}. See
11552 @ref{Editing files}.
11555 Local; run only in current working directory. See @ref{Recursive behavior}.
11558 Operate recursively (default). @xref{Recursive
11562 @c ------------------------------------------------------------
11563 @item editors [@var{options}] [@var{files}@dots{}]
11564 See who is editing a watched file. See @ref{Watch information}.
11568 Local; run only in current working directory. See @ref{Recursive behavior}.
11571 Operate recursively (default). @xref{Recursive
11575 @c ------------------------------------------------------------
11576 @item export [@var{options}] @var{modules}@dots{}
11577 Export files from @sc{cvs}. See @ref{export}.
11580 @item -D @var{date}
11581 Check out revisions as of @var{date}. See
11582 @ref{Common options}.
11585 Check out into @var{dir}. See @ref{export options}.
11588 Use head revision if tag/date not found. See
11589 @ref{Common options}.
11591 @item -k @var{kflag}
11592 Use @var{kflag} keyword expansion. See
11593 @ref{Substitution modes}.
11596 Local; run only in current working directory. @xref{Recursive behavior}.
11599 Don't ``shorten'' module paths if -d specified. See
11600 @ref{export options}.
11603 Do not run module program (if any). See @ref{export options}.
11606 Operate recursively (default). @xref{Recursive
11610 Checkout revision @var{tag}. See @ref{Common options}.
11613 @c ------------------------------------------------------------
11614 @item history [@var{options}] [@var{files}@dots{}]
11615 Show repository access history. See @ref{history}.
11619 All users (default is self). See @ref{history options}.
11622 Back to record with @var{str} in module/file/repos
11623 field. See @ref{history options}.
11626 Report on committed (modified) files. See @ref{history options}.
11628 @item -D @var{date}
11629 Since @var{date}. See @ref{history options}.
11632 Report on all record types. See @ref{history options}.
11635 Last modified (committed or modified report). See @ref{history options}.
11637 @item -m @var{module}
11638 Report on @var{module} (repeatable). See @ref{history options}.
11640 @item -n @var{module}
11641 In @var{module}. See @ref{history options}.
11644 Report on checked out modules. See @ref{history options}.
11646 @item -p @var{repository}
11647 In @var{repository}. See @ref{history options}.
11650 Since revision @var{rev}. See @ref{history options}.
11653 @c What the @#$@# is a TAG? Same as a tag? This
11654 @c wording is also in the online-line help.
11655 Produce report on all TAGs. See @ref{history options}.
11658 Since tag record placed in history file (by anyone).
11659 See @ref{history options}.
11661 @item -u @var{user}
11662 For user @var{user} (repeatable). See @ref{history options}.
11665 Working directory must match. See @ref{history options}.
11667 @item -x @var{types}
11668 Report on @var{types}, one or more of
11669 @code{TOEFWUPCGMAR}. See @ref{history options}.
11671 @item -z @var{zone}
11672 Output for time zone @var{zone}. See @ref{history options}.
11675 @c ------------------------------------------------------------
11676 @item import [@var{options}] @var{repository} @var{vendor-tag} @var{release-tags}@dots{}
11677 Import files into @sc{cvs}, using vendor branches. See
11682 Import to vendor branch @var{bra}. See
11683 @ref{Multiple vendor branches}.
11686 Use the file's modification time as the time of
11687 import. See @ref{import options}.
11689 @item -k @var{kflag}
11690 Set default keyword substitution mode. See
11691 @ref{import options}.
11694 Use @var{msg} for log message. See
11695 @ref{import options}.
11698 More files to ignore (! to reset). See
11699 @ref{import options}.
11701 @item -W @var{spec}
11702 More wrappers. See @ref{import options}.
11705 @c ------------------------------------------------------------
11707 Create a @sc{cvs} repository if it doesn't exist. See
11708 @ref{Creating a repository}.
11710 @c ------------------------------------------------------------
11712 Kerberos authenticated server.
11713 See @ref{Kerberos authenticated}.
11715 @c ------------------------------------------------------------
11716 @item log [@var{options}] [@var{files}@dots{}]
11717 Print out history information for files. See @ref{log}.
11721 Only list revisions on the default branch. See @ref{log options}.
11723 @item -d @var{dates}
11724 Specify dates (@var{d1}<@var{d2} for range, @var{d} for
11725 latest before). See @ref{log options}.
11728 Only print header. See @ref{log options}.
11731 Local; run only in current working directory. See @ref{Recursive behavior}.
11734 Do not list tags. See @ref{log options}.
11737 Only print name of RCS file. See @ref{log options}.
11740 Only list revisions @var{revs}. See @ref{log options}.
11742 @item -s @var{states}
11743 Only list revisions with specified states. See @ref{log options}.
11746 Only print header and descriptive text. See @ref{log
11749 @item -w@var{logins}
11750 Only list revisions checked in by specified logins. See @ref{log options}.
11753 @c ------------------------------------------------------------
11755 Prompt for password for authenticating server. See
11756 @ref{Password authentication client}.
11758 @c ------------------------------------------------------------
11760 Remove stored password for authenticating server. See
11761 @ref{Password authentication client}.
11763 @c ------------------------------------------------------------
11765 Password authenticated server.
11766 See @ref{Password authentication server}.
11768 @c ------------------------------------------------------------
11769 @item rannotate [@var{options}] [@var{modules}@dots{}]
11770 Show last revision where each line was modified. See
11774 @item -D @var{date}
11775 Annotate the most recent revision no later than
11776 @var{date}. See @ref{Common options}.
11779 Force annotation of binary files. (Without this option,
11780 binary files are skipped with a message.)
11783 Use head revision if tag/date not found. See
11784 @ref{Common options}.
11787 Local; run only in current working directory. @xref{Recursive behavior}.
11790 Operate recursively (default). @xref{Recursive behavior}.
11793 Annotate revision @var{tag}. See @ref{Common options}.
11796 @c ------------------------------------------------------------
11797 @item rdiff [@var{options}] @var{modules}@dots{}
11798 Show differences between releases. See @ref{rdiff}.
11802 Context diff output format (default). See @ref{rdiff options}.
11804 @item -D @var{date}
11805 Select revisions based on @var{date}. See @ref{Common options}.
11808 Use head revision if tag/date not found. See
11809 @ref{Common options}.
11812 Local; run only in current working directory. See @ref{Recursive behavior}.
11815 Operate recursively (default). @xref{Recursive
11819 Select revisions based on @var{rev}. See @ref{Common options}.
11822 Short patch - one liner per file. See @ref{rdiff options}.
11825 Top two diffs - last change made to the file. See
11826 @ref{diff options}.
11829 Unidiff output format. See @ref{rdiff options}.
11831 @item -V @var{vers}
11832 Use RCS Version @var{vers} for keyword expansion (obsolete). See
11833 @ref{rdiff options}.
11836 @c ------------------------------------------------------------
11837 @item release [@var{options}] @var{directory}
11838 Indicate that a directory is no longer in use. See
11843 Delete the given directory. See @ref{release options}.
11846 @c ------------------------------------------------------------
11847 @item remove [@var{options}] [@var{files}@dots{}]
11848 Remove an entry from the repository. See @ref{Removing files}.
11852 Delete the file before removing it. See @ref{Removing files}.
11855 Local; run only in current working directory. See @ref{Recursive behavior}.
11858 Operate recursively (default). @xref{Recursive
11862 @c ------------------------------------------------------------
11863 @item rlog [@var{options}] [@var{files}@dots{}]
11864 Print out history information for modules. See @ref{log}.
11868 Only list revisions on the default branch. See @ref{log options}.
11870 @item -d @var{dates}
11871 Specify dates (@var{d1}<@var{d2} for range, @var{d} for
11872 latest before). See @ref{log options}.
11875 Only print header. See @ref{log options}.
11878 Local; run only in current working directory. See @ref{Recursive behavior}.
11881 Do not list tags. See @ref{log options}.
11884 Only print name of RCS file. See @ref{log options}.
11887 Only list revisions @var{revs}. See @ref{log options}.
11889 @item -s @var{states}
11890 Only list revisions with specified states. See @ref{log options}.
11893 Only print header and descriptive text. See @ref{log options}.
11895 @item -w@var{logins}
11896 Only list revisions checked in by specified logins. See @ref{log options}.
11899 @c ------------------------------------------------------------
11900 @item rtag [@var{options}] @var{tag} @var{modules}@dots{}
11901 Add a symbolic tag to a module.
11902 See @ref{Revisions} and @ref{Branching and merging}.
11906 Clear tag from removed files that would not otherwise
11907 be tagged. See @ref{Tagging add/remove}.
11910 Create a branch named @var{tag}. See @ref{Branching and merging}.
11913 Used in conjunction with -F or -d, enables movement and deletion of
11914 branch tags. Use with extreme caution.
11916 @item -D @var{date}
11917 Tag revisions as of @var{date}. See @ref{Tagging by date/tag}.
11920 Delete @var{tag}. See @ref{Modifying tags}.
11923 Move @var{tag} if it already exists. See @ref{Modifying tags}.
11926 Force a head revision match if tag/date not found.
11927 See @ref{Tagging by date/tag}.
11930 Local; run only in current working directory. See @ref{Recursive behavior}.
11933 No execution of tag program. See @ref{Common options}.
11936 Operate recursively (default). @xref{Recursive
11940 Tag existing tag @var{rev}. See @ref{Tagging by date/tag}.
11943 @c ------------------------------------------------------------
11945 Rsh server. See @ref{Connecting via rsh}.
11947 @c ------------------------------------------------------------
11948 @item status [@var{options}] @var{files}@dots{}
11949 Display status information in a working directory. See
11954 Local; run only in current working directory. See @ref{Recursive behavior}.
11957 Operate recursively (default). @xref{Recursive
11961 Include tag information for file. See @ref{Tags}.
11964 @c ------------------------------------------------------------
11965 @item tag [@var{options}] @var{tag} [@var{files}@dots{}]
11966 Add a symbolic tag to checked out version of files.
11967 See @ref{Revisions} and @ref{Branching and merging}.
11971 Create a branch named @var{tag}. See @ref{Branching and merging}.
11974 Check that working files are unmodified. See
11975 @ref{Tagging the working directory}.
11977 @item -D @var{date}
11978 Tag revisions as of @var{date}. See @ref{Tagging by date/tag}.
11981 Delete @var{tag}. See @ref{Modifying tags}.
11984 Move @var{tag} if it already exists. See @ref{Modifying tags}.
11987 Force a head revision match if tag/date not found.
11988 See @ref{Tagging by date/tag}.
11991 Local; run only in current working directory. See @ref{Recursive behavior}.
11994 Operate recursively (default). @xref{Recursive
11998 Tag existing tag @var{rev}. See @ref{Tagging by date/tag}.
12001 @c ------------------------------------------------------------
12002 @item unedit [@var{options}] [@var{files}@dots{}]
12003 Undo an edit command. See @ref{Editing files}.
12007 Local; run only in current working directory. See @ref{Recursive behavior}.
12010 Operate recursively (default). @xref{Recursive behavior}.
12013 @c ------------------------------------------------------------
12014 @item update [@var{options}] [@var{files}@dots{}]
12015 Bring work tree in sync with repository. See
12020 Reset any sticky tags/date/options. See @ref{Sticky
12021 tags} and @ref{Keyword substitution}.
12024 Overwrite locally modified files with clean copies from
12025 the repository (the modified file is saved in
12026 @file{.#@var{file}.@var{revision}}, however).
12028 @item -D @var{date}
12029 Check out revisions as of @var{date} (is sticky). See
12030 @ref{Common options}.
12033 Create directories. See @ref{update options}.
12036 Use head revision if tag/date not found. See
12037 @ref{Common options}.
12040 More files to ignore (! to reset). See
12041 @ref{import options}.
12043 @c Probably want to use rev1/rev2 style like for diff
12044 @c -r. Here and in on-line help.
12046 Merge in changes. See @ref{update options}.
12048 @item -k @var{kflag}
12049 Use @var{kflag} keyword expansion. See
12050 @ref{Substitution modes}.
12053 Local; run only in current working directory. @xref{Recursive behavior}.
12056 Prune empty directories. See @ref{Moving directories}.
12059 Check out files to standard output (avoids
12060 stickiness). See @ref{update options}.
12063 Operate recursively (default). @xref{Recursive
12067 Checkout revision @var{tag} (is sticky). See @ref{Common options}.
12069 @item -W @var{spec}
12070 More wrappers. See @ref{import options}.
12073 @c ------------------------------------------------------------
12075 @cindex version (subcommand)
12077 Display the version of @sc{cvs} being used. If the repository
12078 is remote, display both the client and server versions.
12080 @c ------------------------------------------------------------
12081 @item watch [on|off|add|remove] [@var{options}] [@var{files}@dots{}]
12083 on/off: turn on/off read-only checkouts of files. See
12084 @ref{Setting a watch}.
12086 add/remove: add or remove notification on actions. See
12087 @ref{Getting Notified}.
12090 @item -a @var{actions}
12091 Specify actions for temporary watch, where
12092 @var{actions} is @code{edit}, @code{unedit},
12093 @code{commit}, @code{all}, or @code{none}. See
12094 @ref{Editing files}.
12097 Local; run only in current working directory. See @ref{Recursive behavior}.
12100 Operate recursively (default). @xref{Recursive
12104 @c ------------------------------------------------------------
12105 @item watchers [@var{options}] [@var{files}@dots{}]
12106 See who is watching a file. See @ref{Watch information}.
12110 Local; run only in current working directory. See @ref{Recursive behavior}.
12113 Operate recursively (default). @xref{Recursive
12119 @c ---------------------------------------------------------------------
12120 @node Administrative files
12121 @appendix Reference manual for Administrative files
12122 @cindex Administrative files (reference)
12123 @cindex Files, reference manual
12124 @cindex Reference manual (files)
12125 @cindex CVSROOT (file)
12127 @c FIXME? Somewhere there needs to be a more "how-to"
12128 @c guide to writing these. I think the triggers
12129 @c (commitinfo, loginfo, taginfo, &c) are perhaps a
12130 @c different case than files like modules. One
12131 @c particular issue that people sometimes are
12132 @c (unnecessarily?) worried about is performance, and
12133 @c the impact of writing in perl or sh or ____.
12134 Inside the repository, in the directory
12135 @file{$CVSROOT/CVSROOT}, there are a number of
12136 supportive files for @sc{cvs}. You can use @sc{cvs} in a limited
12137 fashion without any of them, but if they are set up
12138 properly they can help make life easier. For a
12139 discussion of how to edit them, see @ref{Intro
12140 administrative files}.
12142 The most important of these files is the @file{modules}
12143 file, which defines the modules inside the repository.
12146 * modules:: Defining modules
12147 * Wrappers:: Specify binary-ness based on file name
12148 * Trigger Scripts:: Some notes on the commit support files and
12149 taginfo, referenced below.
12150 * commit files:: The commit support files (commitinfo,
12151 verifymsg, editinfo, loginfo)
12152 * taginfo:: Verifying/Logging tags
12153 * rcsinfo:: Templates for the log messages
12154 * cvsignore:: Ignoring files via cvsignore
12155 * checkoutlist:: Adding your own administrative files
12156 * history file:: History information
12157 * Variables:: Various variables are expanded
12158 * config:: Miscellaneous CVS configuration
12161 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
12163 @appendixsec The modules file
12164 @cindex Modules (admin file)
12165 @cindex Defining modules (reference manual)
12167 The @file{modules} file records your definitions of
12168 names for collections of source code. @sc{cvs} will
12169 use these definitions if you use @sc{cvs} to update the
12170 modules file (use normal commands like @code{add},
12171 @code{commit}, etc).
12173 The @file{modules} file may contain blank lines and
12174 comments (lines beginning with @samp{#}) as well as
12175 module definitions. Long lines can be continued on the
12176 next line by specifying a backslash (@samp{\}) as the
12177 last character on the line.
12179 There are three basic types of modules: alias modules,
12180 regular modules, and ampersand modules. The difference
12181 between them is the way that they map files in the
12182 repository to files in the working directory. In all
12183 of the following examples, the top-level repository
12184 contains a directory called @file{first-dir}, which
12185 contains two files, @file{file1} and @file{file2}, and a
12186 directory @file{sdir}. @file{first-dir/sdir} contains
12187 a file @file{sfile}.
12189 @c FIXME: should test all the examples in this section.
12192 * Alias modules:: The simplest kind of module
12193 * Regular modules::
12194 * Ampersand modules::
12195 * Excluding directories:: Excluding directories from a module
12196 * Module options:: Regular and ampersand modules can take options
12197 * Module program options:: How the modules ``program options'' programs
12201 @node Alias modules
12202 @appendixsubsec Alias modules
12203 @cindex Alias modules
12204 @cindex -a, in modules file
12206 Alias modules are the simplest kind of module:
12209 @item @var{mname} -a @var{aliases}@dots{}
12210 This represents the simplest way of defining a module
12211 @var{mname}. The @samp{-a} flags the definition as a
12212 simple alias: @sc{cvs} will treat any use of @var{mname} (as
12213 a command argument) as if the list of names
12214 @var{aliases} had been specified instead.
12215 @var{aliases} may contain either other module names or
12216 paths. When you use paths in aliases, @code{checkout}
12217 creates all intermediate directories in the working
12218 directory, just as if the path had been specified
12219 explicitly in the @sc{cvs} arguments.
12222 For example, if the modules file contains:
12225 amodule -a first-dir
12229 then the following two commands are equivalent:
12237 and they each would provide output such as:
12240 cvs checkout: Updating first-dir
12243 cvs checkout: Updating first-dir/sdir
12244 U first-dir/sdir/sfile
12247 @node Regular modules
12248 @appendixsubsec Regular modules
12249 @cindex Regular modules
12252 @item @var{mname} [ options ] @var{dir} [ @var{files}@dots{} ]
12253 In the simplest case, this form of module definition
12254 reduces to @samp{@var{mname} @var{dir}}. This defines
12255 all the files in directory @var{dir} as module mname.
12256 @var{dir} is a relative path (from @code{$CVSROOT}) to a
12257 directory of source in the source repository. In this
12258 case, on checkout, a single directory called
12259 @var{mname} is created as a working directory; no
12260 intermediate directory levels are used by default, even
12261 if @var{dir} was a path involving several directory
12265 For example, if a module is defined by:
12268 regmodule first-dir
12272 then regmodule will contain the files from first-dir:
12276 cvs checkout: Updating regmodule
12279 cvs checkout: Updating regmodule/sdir
12280 U regmodule/sdir/sfile
12284 By explicitly specifying files in the module definition
12285 after @var{dir}, you can select particular files from
12286 directory @var{dir}. Here is
12290 regfiles first-dir/sdir sfile
12294 With this definition, getting the regfiles module
12295 will create a single working directory
12296 @file{regfiles} containing the file listed, which
12297 comes from a directory deeper
12298 in the @sc{cvs} source repository:
12306 @node Ampersand modules
12307 @appendixsubsec Ampersand modules
12308 @cindex Ampersand modules
12309 @cindex &, in modules file
12311 A module definition can refer to other modules by
12312 including @samp{&@var{module}} in its definition.
12314 @var{mname} [ options ] @var{&module}@dots{}
12317 Then getting the module creates a subdirectory for each such
12318 module, in the directory containing the module. For
12319 example, if modules contains
12322 ampermod &first-dir
12326 then a checkout will create an @code{ampermod} directory
12327 which contains a directory called @code{first-dir},
12328 which in turns contains all the directories and files
12329 which live there. For example, the command
12336 will create the following files:
12339 ampermod/first-dir/file1
12340 ampermod/first-dir/file2
12341 ampermod/first-dir/sdir/sfile
12344 There is one quirk/bug: the messages that @sc{cvs}
12345 prints omit the @file{ampermod}, and thus do not
12346 correctly display the location to which it is checking
12351 cvs checkout: Updating first-dir
12354 cvs checkout: Updating first-dir/sdir
12355 U first-dir/sdir/sfile
12359 Do not rely on this buggy behavior; it may get fixed in
12360 a future release of @sc{cvs}.
12362 @c FIXCVS: What happens if regular and & modules are
12363 @c combined, as in "ampermodule first-dir &second-dir"?
12364 @c When I tried it, it seemed to just ignore the
12365 @c "first-dir". I think perhaps it should be an error
12366 @c (but this needs further investigation).
12367 @c In addition to discussing what each one does, we
12368 @c should put in a few words about why you would use one or
12369 @c the other in various situations.
12371 @node Excluding directories
12372 @appendixsubsec Excluding directories
12373 @cindex Excluding directories, in modules file
12374 @cindex !, in modules file
12376 An alias module may exclude particular directories from
12377 other modules by using an exclamation mark (@samp{!})
12378 before the name of each directory to be excluded.
12380 For example, if the modules file contains:
12383 exmodule -a !first-dir/sdir first-dir
12387 then checking out the module @samp{exmodule} will check
12388 out everything in @samp{first-dir} except any files in
12389 the subdirectory @samp{first-dir/sdir}.
12390 @c Note that the "!first-dir/sdir" sometimes must be listed
12391 @c before "first-dir". That seems like a probable bug, in which
12392 @c case perhaps it should be fixed (to allow either
12393 @c order) rather than documented. See modules4 in testsuite.
12395 @node Module options
12396 @appendixsubsec Module options
12397 @cindex Options, in modules file
12399 Either regular modules or ampersand modules can contain
12400 options, which supply additional information concerning
12404 @cindex -d, in modules file
12405 @item -d @var{name}
12406 Name the working directory something other than the
12408 @c FIXME: Needs a bunch of examples, analogous to the
12409 @c examples for alias, regular, and ampersand modules
12410 @c which show where the files go without -d.
12412 @cindex Export program
12413 @cindex -e, in modules file
12414 @item -e @var{prog}
12415 Specify a program @var{prog} to run whenever files in a
12416 module are exported. @var{prog} runs with a single
12417 argument, the module name.
12418 @c FIXME: Is it run on server? client?
12420 @cindex Checkout program
12421 @cindex -o, in modules file
12422 @item -o @var{prog}
12423 Specify a program @var{prog} to run whenever files in a
12424 module are checked out. @var{prog} runs with a single
12425 argument, the module name. See @ref{Module program options} for
12426 information on how @var{prog} is called.
12427 @c FIXME: Is it run on server? client?
12429 @cindex Status of a module
12430 @cindex Module status
12431 @cindex -s, in modules file
12432 @item -s @var{status}
12433 Assign a status to the module. When the module file is
12434 printed with @samp{cvs checkout -s} the modules are
12435 sorted according to primarily module status, and
12436 secondarily according to the module name. This option
12437 has no other meaning. You can use this option for
12438 several things besides status: for instance, list the
12439 person that is responsible for this module.
12441 @cindex Tag program
12442 @cindex -t, in modules file
12443 @item -t @var{prog}
12444 Specify a program @var{prog} to run whenever files in a
12445 module are tagged with @code{rtag}. @var{prog} runs
12446 with two arguments: the module name and the symbolic
12447 tag specified to @code{rtag}. It is not run
12448 when @code{tag} is executed. Generally you will find
12449 that the @file{taginfo} file is a better solution (@pxref{taginfo}).
12450 @c FIXME: Is it run on server? client?
12451 @c Problems with -t include:
12452 @c * It is run after the tag not before
12453 @c * It doesn't get passed all the information that
12454 @c taginfo does ("mov", &c).
12455 @c * It only is run for rtag, not tag.
12458 You should also see @pxref{Module program options} about how the
12459 ``program options'' programs are run.
12461 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
12463 @node Module program options
12464 @appendixsubsec How the modules file ``program options'' programs are run
12465 @cindex Modules file program options
12466 @cindex -t, in modules file
12467 @cindex -o, in modules file
12468 @cindex -e, in modules file
12471 For checkout, rtag, and export, the program is server-based, and as such the
12472 following applies:-
12474 If using remote access methods (pserver, ext, etc.),
12475 @sc{cvs} will execute this program on the server from a temporary
12476 directory. The path is searched for this program.
12478 If using ``local access'' (on a local or remote NFS file system, i.e.,
12479 repository set just to a path),
12480 the program will be executed from the newly checked-out tree, if
12481 found there, or alternatively searched for in the path if not.
12483 The programs are all run after the operation has effectively
12487 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
12489 @appendixsec The cvswrappers file
12490 @cindex cvswrappers (admin file)
12491 @cindex CVSWRAPPERS, environment variable
12494 @c FIXME: need some better way of separating this out
12495 @c by functionality. -m is
12496 @c one feature, and -k is a another. And this discussion
12497 @c should be better motivated (e.g. start with the
12498 @c problems, then explain how the feature solves it).
12500 Wrappers refers to a @sc{cvs} feature which lets you
12501 control certain settings based on the name of the file
12502 which is being operated on. The settings are @samp{-k}
12503 for binary files, and @samp{-m} for nonmergeable text
12506 The @samp{-m} option
12507 specifies the merge methodology that should be used when
12508 a non-binary file is updated. @code{MERGE} means the usual
12509 @sc{cvs} behavior: try to merge the files. @code{COPY}
12510 means that @code{cvs update} will refuse to merge
12511 files, as it also does for files specified as binary
12512 with @samp{-kb} (but if the file is specified as
12513 binary, there is no need to specify @samp{-m 'COPY'}).
12514 @sc{cvs} will provide the user with the
12515 two versions of the files, and require the user using
12516 mechanisms outside @sc{cvs}, to insert any necessary
12519 @strong{WARNING: Do not use @code{COPY} with
12520 @sc{cvs} 1.9 or earlier - such versions of @sc{cvs} will
12521 copy one version of your file over the other, wiping
12522 out the previous contents.}
12523 @c Ordinarily we don't document the behavior of old
12524 @c versions. But this one is so dangerous, I think we
12525 @c must. I almost renamed it to -m 'NOMERGE' so we
12526 @c could say "never use -m 'COPY'".
12527 The @samp{-m} wrapper option only affects behavior when
12528 merging is done on update; it does not affect how files
12529 are stored. See @ref{Binary files}, for more on
12532 The basic format of the file @file{cvswrappers} is:
12534 @c FIXME: @example is all wrong for this. Use @deffn or
12535 @c something more sensible.
12537 wildcard [option value][option value]...
12539 where option is one of
12540 -m update methodology value: MERGE or COPY
12541 -k keyword expansion value: expansion mode
12543 and value is a single-quote delimited value.
12548 *.nib -f 'unwrap %s' -t 'wrap %s %s' -m 'COPY'
12549 *.c -t 'indent %s %s'
12551 @c When does the filter need to be an absolute pathname
12552 @c and when will something like the above work? I
12553 @c suspect it relates to the PATH of the server (which
12554 @c in turn depends on all kinds of stuff, e.g. inetd
12555 @c for pserver). I'm not sure whether/where to discuss
12557 @c FIXME: What do the %s's stand for?
12560 The above example of a @file{cvswrappers} file
12561 states that all files/directories that end with a @code{.nib}
12562 should be filtered with the @file{wrap} program before
12563 checking the file into the repository. The file should
12564 be filtered though the @file{unwrap} program when the
12565 file is checked out of the repository. The
12566 @file{cvswrappers} file also states that a @code{COPY}
12567 methodology should be used when updating the files in
12568 the repository (that is, no merging should be performed).
12570 @c What pitfalls arise when using indent this way? Is
12571 @c it a winning thing to do? Would be nice to at least
12572 @c hint at those issues; we want our examples to tell
12573 @c how to solve problems, not just to say that cvs can
12574 @c do certain things.
12575 The last example line says that all files that end with
12576 @code{.c} should be filtered with @file{indent}
12577 before being checked into the repository. Unlike the previous
12578 example, no filtering of the @code{.c} file is done when
12579 it is checked out of the repository.
12581 The @code{-t} filter is called with two arguments,
12582 the first is the name of the file/directory to filter
12583 and the second is the pathname to where the resulting
12584 filtered file should be placed.
12587 The @code{-f} filter is called with one argument,
12588 which is the name of the file to filter from. The end
12589 result of this filter will be a file in the users directory
12590 that they can work on as they normally would.
12592 Note that the @samp{-t}/@samp{-f} features do not
12593 conveniently handle one portion of @sc{cvs}'s operation:
12594 determining when files are modified. @sc{cvs} will still
12595 want a file (or directory) to exist, and it will use
12596 its modification time to determine whether a file is
12597 modified. If @sc{cvs} erroneously thinks a file is
12598 unmodified (for example, a directory is unchanged but
12599 one of the files within it is changed), you can force
12600 it to check in the file anyway by specifying the
12601 @samp{-f} option to @code{cvs commit} (@pxref{commit
12603 @c This is, of course, a serious design flaw in -t/-f.
12604 @c Probably the whole functionality needs to be
12605 @c redesigned (starting from requirements) to fix this.
12608 @c FIXME: We don't document -W or point to where it is
12609 @c documented. Or .cvswrappers.
12610 For example, the following command imports a
12611 directory, treating files whose name ends in
12612 @samp{.exe} as binary:
12615 cvs import -I ! -W "*.exe -k 'b'" first-dir vendortag reltag
12618 @c Another good example, would be storing files
12619 @c (e.g. binary files) compressed in the repository.
12620 @c ::::::::::::::::::
12622 @c ::::::::::::::::::
12624 @c *.t[0-9][0-9] -f 'gunzipcp %s' -t 'gzipcp %s %s' -m 'COPY'
12626 @c ::::::::::::::::::
12628 @c ::::::::::::::::::
12630 @c [ -f $1 ] || exit 1
12631 @c zcat $1 > /tmp/.#$1.$$
12632 @c mv /tmp/.#$1.$$ $1
12634 @c ::::::::::::::::::
12636 @c ::::::::::::::::::
12638 @c DIRNAME=`echo $1 | sed -e "s|/.*/||g"`
12639 @c if [ ! -d $DIRNAME ] ; then
12640 @c DIRNAME=`echo $1 | sed -e "s|.*/||g"`
12642 @c gzip -c $DIRNAME > $2
12643 @c One catch--"cvs diff" will not invoke the wrappers
12644 @c (probably a CVS bug, although I haven't thought it out).
12646 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12647 @node Trigger Scripts
12648 @appendixsec The Trigger Scripts
12650 @cindex Trigger scripts
12652 Several of the administrative files support triggers, or the launching external
12653 scripts or programs at specific times before or after particular events. The
12654 individual files are discussed in the later sections, @ref{commit files} and
12655 @ref{taginfo}, but some of the common elements are discussed here.
12657 All the trigger scripts are launched in a copy of the user sandbox being
12658 committed, on the server, in client-server mode. In local mode, the scripts
12659 are actually launched directly from the user sandbox directory being committed.
12660 For most intents and purposes, the same scripts can be run in both locations
12661 without alteration.
12664 * syntax:: The common syntax
12665 * Trigger Script Security:: Trigger script security
12668 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12670 @appendixsubsec The common syntax
12671 @cindex Info files (syntax)
12672 @cindex Syntax of info files
12673 @cindex Common syntax of info files
12675 @c FIXME: having this so totally separate from the
12676 @c Variables node is rather bogus.
12678 The administrative files such as @file{commitinfo},
12679 @file{loginfo}, @file{rcsinfo}, @file{verifymsg}, etc.,
12680 all have a common format. The purpose of the files are
12681 described later on. The common syntax is described
12684 @cindex Regular expression syntax
12685 Each line contains the following:
12688 @c Say anything about DEFAULT and ALL? Right now we
12689 @c leave that to the description of each file (and in fact
12690 @c the practice is inconsistent which is really annoying).
12691 A regular expression. This is a basic regular
12692 expression in the syntax used by GNU emacs.
12693 @c FIXME: What we probably should be saying is "POSIX Basic
12694 @c Regular Expression with the following extensions (`\('
12696 @c rather than define it with reference to emacs.
12697 @c The reference to emacs is not strictly speaking
12698 @c true, as we don't support \=, \s, or \S. Also it isn't
12699 @c clear we should document and/or promise to continue to
12700 @c support all the obscure emacs extensions like \<.
12701 @c Also need to better cite (or include) full
12702 @c documentation for the syntax.
12703 @c Also see comment in configure.in about what happens to the
12704 @c syntax if we pick up a system-supplied regexp matcher.
12707 A whitespace separator---one or more spaces and/or tabs.
12710 A file name or command-line template.
12714 Blank lines are ignored. Lines that start with the
12715 character @samp{#} are treated as comments. Long lines
12716 unfortunately can @emph{not} be broken in two parts in
12719 The first regular expression that matches the current
12720 directory name in the repository is used. The rest of the line
12721 is used as a file name or command-line as appropriate.
12723 @c FIXME: need an example. In particular, show what
12724 @c the regular expression is matched against (one
12725 @c ordinarily clueful person got confused about whether it
12726 @c includes the filename--"directory name" above should be
12727 @c unambiguous but there is nothing like an example to
12728 @c confirm people's understanding of this sort of thing).
12730 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12731 @node Trigger Script Security
12732 @appendixsubsec Security and the Trigger Scripts
12733 @cindex Info files, security
12734 @cindex Trigger scripts, security
12736 Security is a huge subject, and implementing a secure system is a non-trivial
12737 task. This section will barely touch on all the issues involved, but it is
12738 well to note that, as with any script you will be allowing an untrusted
12739 user to run on your server, there are measures you can take to help prevent
12740 your trigger scripts from being abused.
12742 For instance, since the CVS trigger scripts all run in a copy of the user's
12743 sandbox on the server, a naively coded Perl trigger script which attempts to
12744 use a Perl module that is not installed on the system can be hijacked by any
12745 user with commit access who is checking in a file with the correct name. Other
12746 scripting languages may be vulnerable to similar hacks.
12748 One way to make a script more secure, at least with Perl, is to use scripts
12749 which invoke the @code{-T}, or "taint-check" switch on their @code{#!} line.
12750 In the most basic terms, this causes Perl to avoid running code that may have
12751 come from an external source. Please run the @code{perldoc perlsec} command
12752 for more on Perl security. Again, other languages may implement other security
12753 verification hooks which look more or less like Perl's "taint-check" mechanism.
12755 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
12757 @appendixsec The commit support files
12758 @cindex Committing, administrative support files
12760 There are three kinds of trigger scripts (@pxref{Trigger Scripts}) that can be
12761 run at various times during a commit. They are specified in files in the
12762 repository, as described below. The following table summarizes the
12763 file names and the purpose of the corresponding programs.
12767 The program is responsible for checking that the commit
12768 is allowed. If it exits with a non-zero exit status
12769 the commit will be aborted.
12772 The specified program is used to evaluate the log message,
12773 and possibly verify that it contains all required
12774 fields. This is most useful in combination with the
12775 @file{rcsinfo} file, which can hold a log message
12776 template (@pxref{rcsinfo}).
12779 The specified program is used to edit the log message,
12780 and possibly verify that it contains all required
12781 fields. This is most useful in combination with the
12782 @file{rcsinfo} file, which can hold a log message
12783 template (@pxref{rcsinfo}). (obsolete)
12786 The specified program is called when the commit is
12787 complete. It receives the log message and some
12788 additional information and can store the log message in
12789 a file, or mail it to appropriate persons, or maybe
12790 post it to a local newsgroup, or@dots{} Your
12791 imagination is the limit!
12795 * commitinfo:: Pre-commit checking
12796 * verifymsg:: How are log messages evaluated?
12797 * editinfo:: Specifying how log messages are created
12799 * loginfo:: Where should log messages be sent?
12802 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
12804 @appendixsubsec Commitinfo
12805 @cindex @file{commitinfo}
12806 @cindex Commits, precommit verification of
12807 @cindex Precommit checking
12809 The @file{commitinfo} file defines programs to execute
12810 whenever @samp{cvs commit} is about to execute. These
12811 programs are used for pre-commit checking to verify
12812 that the modified, added and removed files are really
12813 ready to be committed. This could be used, for
12814 instance, to verify that the changed files conform to
12815 to your site's standards for coding practice.
12817 As mentioned earlier, each line in the
12818 @file{commitinfo} file consists of a regular expression
12819 and a command-line template. The template can include
12820 a program name and any number of arguments you wish to
12821 supply to it. The full path to the current source
12822 repository is appended to the template, followed by the
12823 file names of any files involved in the commit (added,
12824 removed, and modified files).
12826 @cindex Exit status, of commitinfo
12827 The first line with a regular expression matching the
12828 directory within the repository will be used. If the
12829 command returns a non-zero exit status the commit will
12831 @c FIXME: need example(s) of what "directory within the
12832 @c repository" means.
12834 @cindex DEFAULT in commitinfo
12835 If the repository name does not match any of the
12836 regular expressions in this file, the @samp{DEFAULT}
12837 line is used, if it is specified.
12839 @cindex ALL in commitinfo
12840 All occurrences of the name @samp{ALL} appearing as a
12841 regular expression are used in addition to the first
12842 matching regular expression or the name @samp{DEFAULT}.
12844 @cindex @file{commitinfo}, working directory
12845 @cindex @file{commitinfo}, command environment
12846 The command will be run in the root of the workspace
12847 containing the new versions of any files the user would like
12848 to modify (commit), @emph{or in a copy of the workspace on
12849 the server (@pxref{Remote repositories})}. If a file is
12850 being removed, there will be no copy of the file under the
12851 current directory. If a file is being added, there will be
12852 no corresponding archive file in the repository unless the
12853 file is being resurrected.
12855 Note that both the repository directory and the corresponding
12856 Attic (@pxref{Attic}) directory may need to be checked to
12857 locate the archive file corresponding to any given file being
12858 committed. Much of the information about the specific commit
12859 request being made, including the destination branch, commit
12860 message, and command line options specified, is not available
12863 @c FIXME: should discuss using commitinfo to control
12864 @c who has checkin access to what (e.g. Joe can check into
12865 @c directories a, b, and c, and Mary can check into
12866 @c directories b, c, and d--note this case cannot be
12867 @c conveniently handled with unix groups). Of course,
12868 @c adding a new set of features to CVS might be a more
12869 @c natural way to fix this problem than telling people to
12871 @c FIXME: Should make some reference, especially in
12872 @c the context of controlling who has access, to the fact
12873 @c that commitinfo can be circumvented. Perhaps
12874 @c mention SETXID (but has it been carefully examined
12875 @c for holes?). This fits in with the discussion of
12876 @c general CVS security in "Password authentication
12877 @c security" (the bit which is not pserver-specific).
12879 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
12881 @appendixsubsec Verifying log messages
12882 @cindex @file{verifymsg} (admin file)
12883 @cindex Log message, verifying
12885 Once you have entered a log message, you can evaluate
12886 that message to check for specific content, such as
12887 a bug ID. Use the @file{verifymsg} file to
12888 specify a program that is used to verify the log message.
12889 This program could be a simple script that checks
12890 that the entered message contains the required fields.
12892 The @file{verifymsg} file is often most useful together
12893 with the @file{rcsinfo} file, which can be used to
12894 specify a log message template.
12896 Each line in the @file{verifymsg} file consists of a
12897 regular expression and a command-line template. The
12898 template must include a program name, and can include
12899 any number of arguments. The full path to the current
12900 log message template file is appended to the template.
12902 One thing that should be noted is that the @samp{ALL}
12903 keyword is not supported. If more than one matching
12904 line is found, the first one is used. This can be
12905 useful for specifying a default verification script in a
12906 directory, and then overriding it in a subdirectory.
12908 @cindex DEFAULT in @file{verifymsg}
12909 If the repository name does not match any of the
12910 regular expressions in this file, the @samp{DEFAULT}
12911 line is used, if it is specified.
12913 @cindex Exit status, of @file{verifymsg}
12914 If the verification script exits with a non-zero exit status,
12915 the commit is aborted.
12917 @cindex @file{verifymsg}, changing the log message
12918 In the default configuration, CVS allows the
12919 verification script to change the log message. This is
12920 controlled via the RereadLogAfterVerify CVSROOT/config
12923 When @samp{RereadLogAfterVerify=always} or
12924 @samp{RereadLogAfterVerify=stat}, the log message will
12925 either always be reread after the verification script
12926 is run or reread only if the log message file status
12929 @xref{config}, for more on CVSROOT/config options.
12931 It is NOT a good idea for a @file{verifymsg} script to
12932 interact directly with the user in the various
12933 client/server methods. For the @code{pserver} method,
12934 there is no protocol support for communicating between
12935 @file{verifymsg} and the client on the remote end. For the
12936 @code{ext} and @code{server} methods, it is possible
12937 for CVS to become confused by the characters going
12938 along the same channel as the CVS protocol
12939 messages. See @ref{Remote repositories}, for more
12940 information on client/server setups. In addition, at the time
12941 the @file{verifymsg} script runs, the CVS
12942 server has locks in place in the repository. If control is
12943 returned to the user here then other users may be stuck waiting
12944 for access to the repository.
12946 This option can be useful if you find yourself using an
12947 rcstemplate that needs to be modified to remove empty
12948 elements or to fill in default values. It can also be
12949 useful if the rcstemplate has changed in the repository
12950 and the CVS/Template was not updated, but is able to be
12951 adapted to the new format by the verification script
12952 that is run by @file{verifymsg}.
12954 An example of an update might be to change all
12955 occurrences of 'BugId:' to be 'DefectId:' (which can be
12956 useful if the rcstemplate has recently been changed and
12957 there are still checked-out user trees with cached
12958 copies in the CVS/Template file of the older version).
12960 Another example of an update might be to delete a line
12961 that contains 'BugID: none' from the log message after
12962 validation of that value as being allowed is made.
12964 The following is a little silly example of a
12965 @file{verifymsg} file, together with the corresponding
12966 @file{rcsinfo} file, the log message template and an
12967 verification script. We begin with the log message template.
12968 We want to always record a bug-id number on the first
12969 line of the log message. The rest of log message is
12970 free text. The following template is found in the file
12971 @file{/usr/cvssupport/tc.template}.
12977 The script @file{/usr/cvssupport/bugid.verify} is used to
12978 evaluate the log message.
12983 # bugid.verify filename
12985 # Verify that the log message contains a valid bugid
12986 # on the first line.
12988 if sed 1q < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then
12990 elif sed 1q < $1 | grep '^BugId:[ ]*none$' > /dev/null; then
12991 # It is okay to allow commits with 'BugId: none',
12992 # but do not put that text into the real log message.
12993 grep -v '^BugId:[ ]*none$' > $1.rewrite
12997 echo "No BugId found."
13002 The @file{verifymsg} file contains this line:
13005 ^tc /usr/cvssupport/bugid.verify
13008 The @file{rcsinfo} file contains this line:
13011 ^tc /usr/cvssupport/tc.template
13014 The @file{config} file contains this line:
13017 RereadLogAfterVerify=always
13022 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
13024 @appendixsubsec Editinfo
13025 @cindex editinfo (admin file)
13026 @cindex Editor, specifying per module
13027 @cindex Per-module editor
13028 @cindex Log messages, editing
13030 @strong{The @file{editinfo} feature has been
13031 rendered obsolete. To set a default editor for log
13032 messages use the @code{CVSEDITOR}, @code{EDITOR} environment variables
13033 (@pxref{Environment variables}) or the @samp{-e} global
13034 option (@pxref{Global options}). See @ref{verifymsg},
13035 for information on the use of the @file{verifymsg}
13036 feature for evaluating log messages.}
13038 If you want to make sure that all log messages look the
13039 same way, you can use the @file{editinfo} file to
13040 specify a program that is used to edit the log message.
13041 This program could be a custom-made editor that always
13042 enforces a certain style of the log message, or maybe a
13043 simple shell script that calls an editor, and checks
13044 that the entered message contains the required fields.
13046 If no matching line is found in the @file{editinfo}
13047 file, the editor specified in the environment variable
13048 @code{$CVSEDITOR} is used instead. If that variable is
13049 not set, then the environment variable @code{$EDITOR}
13050 is used instead. If that variable is not
13051 set a default will be used. See @ref{Committing your changes}.
13053 The @file{editinfo} file is often most useful together
13054 with the @file{rcsinfo} file, which can be used to
13055 specify a log message template.
13057 Each line in the @file{editinfo} file consists of a
13058 regular expression and a command-line template. The
13059 template must include a program name, and can include
13060 any number of arguments. The full path to the current
13061 log message template file is appended to the template.
13063 One thing that should be noted is that the @samp{ALL}
13064 keyword is not supported. If more than one matching
13065 line is found, the first one is used. This can be
13066 useful for specifying a default edit script in a
13067 module, and then overriding it in a subdirectory.
13069 @cindex DEFAULT in editinfo
13070 If the repository name does not match any of the
13071 regular expressions in this file, the @samp{DEFAULT}
13072 line is used, if it is specified.
13074 If the edit script exits with a non-zero exit status,
13075 the commit is aborted.
13077 Note: when @sc{cvs} is accessing a remote repository,
13078 or when the @samp{-m} or @samp{-F} options to @code{cvs
13079 commit} are used, @file{editinfo} will not be consulted.
13080 There is no good workaround for this; use
13081 @file{verifymsg} instead.
13084 * editinfo example:: Editinfo example
13087 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13088 @node editinfo example
13089 @appendixsubsubsec Editinfo example
13091 The following is a little silly example of a
13092 @file{editinfo} file, together with the corresponding
13093 @file{rcsinfo} file, the log message template and an
13094 editor script. We begin with the log message template.
13095 We want to always record a bug-id number on the first
13096 line of the log message. The rest of log message is
13097 free text. The following template is found in the file
13098 @file{/usr/cvssupport/tc.template}.
13104 The script @file{/usr/cvssupport/bugid.edit} is used to
13105 edit the log message.
13110 # bugid.edit filename
13112 # Call $EDITOR on FILENAME, and verify that the
13113 # resulting file contains a valid bugid on the first
13115 if [ "x$EDITOR" = "x" ]; then EDITOR=vi; fi
13116 if [ "x$CVSEDITOR" = "x" ]; then CVSEDITOR=$EDITOR; fi
13118 until head -1|grep '^BugId:[ ]*[0-9][0-9]*$' < $1
13119 do echo -n "No BugId found. Edit again? ([y]/n)"
13128 The @file{editinfo} file contains this line:
13131 ^tc /usr/cvssupport/bugid.edit
13134 The @file{rcsinfo} file contains this line:
13137 ^tc /usr/cvssupport/tc.template
13140 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
13142 @appendixsubsec Loginfo
13143 @cindex loginfo (admin file)
13144 @cindex Storing log messages
13145 @cindex Mailing log messages
13146 @cindex Distributing log messages
13147 @cindex Log messages
13149 @c "cvs commit" is not quite right. What we
13150 @c mean is "when the repository gets changed" which
13151 @c also includes "cvs import" and "cvs add" on a directory.
13152 The @file{loginfo} file is used to control where
13153 @samp{cvs commit} log information is sent. The first
13154 entry on a line is a regular expression which is tested
13155 against the directory that the change is being made to,
13156 relative to the @code{$CVSROOT}. If a match is found, then
13157 the remainder of the line is a filter program that
13158 should expect log information on its standard input.
13159 Note that the filter program @strong{must} read @strong{all}
13160 of the log information or @sc{cvs} may fail with a broken pipe signal.
13162 If the repository name does not match any of the
13163 regular expressions in this file, the @samp{DEFAULT}
13164 line is used, if it is specified.
13166 All occurrences of the name @samp{ALL} appearing as a
13167 regular expression are used in addition to the first
13168 matching regular expression or @samp{DEFAULT}.
13170 The first matching regular expression is used.
13172 @xref{commit files}, for a description of the syntax of
13173 the @file{loginfo} file.
13175 The user may specify a format string as
13176 part of the filter. The string is composed of a
13177 @samp{%} followed by a space, or followed by a single
13178 format character, or followed by a set of format
13179 characters surrounded by @samp{@{} and @samp{@}} as
13180 separators. The format characters are:
13186 old version number (pre-checkin)
13188 new version number (post-checkin)
13191 All other characters that appear in a format string
13192 expand to an empty field (commas separating fields are
13195 For example, some valid format strings are @samp{%},
13196 @samp{%s}, @samp{%@{s@}}, and @samp{%@{sVv@}}.
13198 The output will be a space separated string of tokens enclosed in
13199 quotation marks (@t{"}).
13200 Any embedded dollar signs (@t{$}), backticks (@t{`}),
13201 backslashes (@t{\}), or quotation marks will be preceded
13202 by a backslash (this allows the shell to correctly parse it
13203 as a single string, reguardless of the characters it contains).
13204 For backwards compatibility, the first
13205 token will be the repository subdirectory. The rest of the
13206 tokens will be comma-delimited lists of the information
13207 requested in the format string. For example, if
13208 @samp{/u/src/master/yoyodyne/tc} is the repository, @samp{%@{sVv@}}
13209 is the format string, and three files (@t{ChangeLog},
13210 @t{Makefile}, @t{foo.c}) were modified, the output
13214 "yoyodyne/tc ChangeLog,1.1,1.2 Makefile,1.3,1.4 foo.c,1.12,1.13"
13217 As another example, @samp{%@{@}} means that only the
13218 name of the repository will be generated.
13220 Note: when @sc{cvs} is accessing a remote repository,
13221 @file{loginfo} will be run on the @emph{remote}
13222 (i.e., server) side, not the client side (@pxref{Remote
13226 * loginfo example:: Loginfo example
13227 * Keeping a checked out copy:: Updating a tree on every checkin
13230 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13231 @node loginfo example
13232 @appendixsubsubsec Loginfo example
13234 The following @file{loginfo} file, together with the
13235 tiny shell-script below, appends all log messages
13236 to the file @file{$CVSROOT/CVSROOT/commitlog},
13237 and any commits to the administrative files (inside
13238 the @file{CVSROOT} directory) are also logged in
13239 @file{/usr/adm/cvsroot-log}.
13240 Commits to the @file{prog1} directory are mailed to @t{ceder}.
13242 @c FIXME: is it a CVS feature or bug that only the
13243 @c first matching line is used? It is documented
13244 @c above, but is it useful? For example, if we wanted
13245 @c to run both "cvs-log" and "Mail" for the CVSROOT
13246 @c directory, it is kind of awkward if
13247 @c only the first matching line is used.
13249 ALL /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog $USER
13250 ^CVSROOT /usr/local/bin/cvs-log /usr/adm/cvsroot-log
13251 ^prog1 Mail -s %s ceder
13254 The shell-script @file{/usr/local/bin/cvs-log} looks
13259 (echo "------------------------------------------------------";
13266 @node Keeping a checked out copy
13267 @appendixsubsubsec Keeping a checked out copy
13269 @c What other index entries? It seems like
13270 @c people might want to use a lot of different
13271 @c words for this functionality.
13272 @cindex Keeping a checked out copy
13273 @cindex Checked out copy, keeping
13274 @cindex Web pages, maintaining with CVS
13276 It is often useful to maintain a directory tree which
13277 contains files which correspond to the latest version
13278 in the repository. For example, other developers might
13279 want to refer to the latest sources without having to
13280 check them out, or you might be maintaining a web site
13281 with @sc{cvs} and want every checkin to cause the files
13282 used by the web server to be updated.
13283 @c Can we offer more details on the web example? Or
13284 @c point the user at how to figure it out? This text
13285 @c strikes me as sufficient for someone who already has
13286 @c some idea of what we mean but not enough for the naive
13287 @c user/sysadmin to understand it and set it up.
13289 The way to do this is by having loginfo invoke
13290 @code{cvs update}. Doing so in the naive way will
13291 cause a problem with locks, so the @code{cvs update}
13292 must be run in the background.
13293 @c Should we try to describe the problem with locks?
13294 @c It seems like a digression for someone who just
13295 @c wants to know how to make it work.
13296 @c Another choice which might work for a single file
13297 @c is to use "cvs -n update -p" which doesn't take
13298 @c out locks (I think) but I don't see many advantages
13299 @c of that and we might as well document something which
13300 @c works for multiple files.
13301 Here is an example for unix (this should all be on one line):
13304 ^cyclic-pages (date; cat; (sleep 2; cd /u/www/local-docs;
13305 cvs -q update -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1
13308 This will cause checkins to repository directories
13309 starting with @code{cyclic-pages} to update the checked
13310 out tree in @file{/u/www/local-docs}.
13311 @c More info on some of the details? The "sleep 2" is
13312 @c so if we are lucky the lock will be gone by the time
13313 @c we start and we can wait 2 seconds instead of 30.
13315 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
13317 @appendixsec Rcsinfo
13318 @cindex rcsinfo (admin file)
13319 @cindex Form for log message
13320 @cindex Log message template
13321 @cindex Template for log message
13323 The @file{rcsinfo} file can be used to specify a form to
13324 edit when filling out the commit log. The
13325 @file{rcsinfo} file has a syntax similar to the
13326 @file{verifymsg}, @file{commitinfo} and @file{loginfo}
13327 files. @xref{syntax}. Unlike the other files the second
13328 part is @emph{not} a command-line template. Instead,
13329 the part after the regular expression should be a full pathname to
13330 a file containing the log message template.
13332 If the repository name does not match any of the
13333 regular expressions in this file, the @samp{DEFAULT}
13334 line is used, if it is specified.
13336 All occurrences of the name @samp{ALL} appearing as a
13337 regular expression are used in addition to the first
13338 matching regular expression or @samp{DEFAULT}.
13340 @c FIXME: should be offering advice, somewhere around
13341 @c here, about where to put the template file. The
13342 @c verifymsg example uses /usr/cvssupport but doesn't
13343 @c say anything about what that directory is for or
13344 @c whether it is hardwired into CVS or who creates
13345 @c it or anything. In particular we should say
13346 @c how to version control the template file. A
13347 @c probably better answer than the /usr/cvssupport
13348 @c stuff is to use checkoutlist (with xref to the
13349 @c checkoutlist doc).
13350 @c Also I am starting to see a connection between
13351 @c this and the Keeping a checked out copy node.
13352 @c Probably want to say something about that.
13353 The log message template will be used as a default log
13354 message. If you specify a log message with @samp{cvs
13355 commit -m @var{message}} or @samp{cvs commit -f
13356 @var{file}} that log message will override the
13359 @xref{verifymsg}, for an example @file{rcsinfo}
13362 When @sc{cvs} is accessing a remote repository,
13363 the contents of @file{rcsinfo} at the time a directory
13364 is first checked out will specify a template which does
13365 not then change. If you edit @file{rcsinfo} or its
13366 templates, you may need to check out a new working
13368 @c Would be nice to fix CVS so this isn't needed. For
13369 @c example, a mechanism analogous to CVS/Entries, where
13370 @c the client keeps track of what version of the template
13373 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
13375 @appendixsec Taginfo
13376 @cindex taginfo (admin file)
13377 @cindex Tags, logging
13378 @cindex Tags, verifying
13379 The @file{taginfo} file defines programs to execute
13380 when someone executes a @code{tag} or @code{rtag}
13381 command. The @file{taginfo} file has the standard form
13382 for trigger scripts (@pxref{Trigger Scripts}),
13383 where each line is a regular expression
13384 followed by a command to execute (@pxref{syntax}). The arguments passed
13385 to the command are, in order, the @var{tagname},
13386 @var{operation} (@code{add} for @code{tag},
13387 @code{mov} for @code{tag -F}, and @code{del} for
13388 @code{tag -d}), @var{repository}, and any remaining are
13389 pairs of @var{filename} @var{revision}. A non-zero
13390 exit of the filter program will cause the tag to be
13393 Here is an example of using the @file{taginfo} file
13394 to log @code{tag} and @code{rtag}
13395 commands. In the @file{taginfo} file put:
13398 ALL /usr/local/cvsroot/CVSROOT/loggit
13402 Where @file{/usr/local/cvsroot/CVSROOT/loggit} contains the
13407 echo "$@@" >>/home/kingdon/cvsroot/CVSROOT/taglog
13410 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
13412 @appendixsec Ignoring files via cvsignore
13413 @cindex cvsignore (admin file), global
13414 @cindex Global cvsignore
13415 @cindex Ignoring files
13416 @c -- This chapter should maybe be moved to the
13417 @c tutorial part of the manual?
13419 There are certain file names that frequently occur
13420 inside your working copy, but that you don't want to
13421 put under @sc{cvs} control. Examples are all the object
13422 files that you get while you compile your sources.
13423 Normally, when you run @samp{cvs update}, it prints a
13424 line for each file it encounters that it doesn't know
13425 about (@pxref{update output}).
13427 @sc{cvs} has a list of files (or sh(1) file name patterns)
13428 that it should ignore while running @code{update},
13429 @code{import} and @code{release}.
13430 @c -- Are those the only three commands affected?
13431 This list is constructed in the following way.
13435 The list is initialized to include certain file name
13436 patterns: names associated with @sc{cvs}
13437 administration, or with other common source control
13438 systems; common names for patch files, object files,
13439 archive files, and editor backup files; and other names
13440 that are usually artifacts of assorted utilities.
13441 Currently, the default list of ignored file name
13444 @cindex Ignored files
13445 @cindex Automatically ignored files
13447 RCS SCCS CVS CVS.adm
13450 .make.state .nse_depinfo
13451 *~ #* .#* ,* _$* *$
13452 *.old *.bak *.BAK *.orig *.rej .del-*
13453 *.a *.olb *.o *.obj *.so *.exe
13459 The per-repository list in
13460 @file{$CVSROOT/CVSROOT/cvsignore} is appended to
13461 the list, if that file exists.
13464 The per-user list in @file{.cvsignore} in your home
13465 directory is appended to the list, if it exists.
13468 Any entries in the environment variable
13469 @code{$CVSIGNORE} is appended to the list.
13472 Any @samp{-I} options given to @sc{cvs} is appended.
13475 As @sc{cvs} traverses through your directories, the contents
13476 of any @file{.cvsignore} will be appended to the list.
13477 The patterns found in @file{.cvsignore} are only valid
13478 for the directory that contains them, not for
13479 any sub-directories.
13482 In any of the 5 places listed above, a single
13483 exclamation mark (@samp{!}) clears the ignore list.
13484 This can be used if you want to store any file which
13485 normally is ignored by @sc{cvs}.
13487 Specifying @samp{-I !} to @code{cvs import} will import
13488 everything, which is generally what you want to do if
13489 you are importing files from a pristine distribution or
13490 any other source which is known to not contain any
13491 extraneous files. However, looking at the rules above
13492 you will see there is a fly in the ointment; if the
13493 distribution contains any @file{.cvsignore} files, then
13494 the patterns from those files will be processed even if
13495 @samp{-I !} is specified. The only workaround is to
13496 remove the @file{.cvsignore} files in order to do the
13497 import. Because this is awkward, in the future
13498 @samp{-I !} might be modified to override
13499 @file{.cvsignore} files in each directory.
13501 Note that the syntax of the ignore files consists of a
13502 series of lines, each of which contains a space
13503 separated list of filenames. This offers no clean way
13504 to specify filenames which contain spaces, but you can
13505 use a workaround like @file{foo?bar} to match a file
13506 named @file{foo bar} (it also matches @file{fooxbar}
13507 and the like). Also note that there is currently no
13508 way to specify comments.
13509 @c FIXCVS? I don't _like_ this syntax at all, but
13510 @c changing it raises all the usual compatibility
13511 @c issues and I'm also not sure what to change it to.
13514 @appendixsec The checkoutlist file
13515 @cindex checkoutlist
13517 It may be helpful to use @sc{cvs} to maintain your own
13518 files in the @file{CVSROOT} directory. For example,
13519 suppose that you have a script @file{logcommit.pl}
13520 which you run by including the following line in the
13521 @file{commitinfo} administrative file:
13524 ALL $CVSROOT/CVSROOT/logcommit.pl
13527 To maintain @file{logcommit.pl} with @sc{cvs} you would
13528 add the following line to the @file{checkoutlist}
13529 administrative file:
13535 The format of @file{checkoutlist} is one line for each
13536 file that you want to maintain using @sc{cvs}, giving
13537 the name of the file, followed optionally by more whitespace
13538 and any error message that should print if the file cannot be
13539 checked out into CVSROOT after a commit:
13542 logcommit.pl Could not update CVSROOT/logcommit.pl.
13545 After setting up @file{checkoutlist} in this fashion,
13546 the files listed there will function just like
13547 @sc{cvs}'s built-in administrative files. For example,
13548 when checking in one of the files you should get a
13552 cvs commit: Rebuilding administrative file database
13556 and the checked out copy in the @file{CVSROOT}
13557 directory should be updated.
13559 Note that listing @file{passwd} (@pxref{Password
13560 authentication server}) in @file{checkoutlist} is not
13561 recommended for security reasons.
13563 For information about keeping a checkout out copy in a
13564 more general context than the one provided by
13565 @file{checkoutlist}, see @ref{Keeping a checked out
13568 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
13570 @appendixsec The history file
13571 @cindex History file
13572 @cindex Log information, saving
13574 The file @file{$CVSROOT/CVSROOT/history} is used
13575 to log information for the @code{history} command
13576 (@pxref{history}). This file must be created to turn
13577 on logging. This is done automatically if the
13578 @code{cvs init} command is used to set up the
13579 repository (@pxref{Creating a repository}).
13581 The file format of the @file{history} file is
13582 documented only in comments in the @sc{cvs} source
13583 code, but generally programs should use the @code{cvs
13584 history} command to access it anyway, in case the
13585 format changes with future releases of @sc{cvs}.
13588 @appendixsec Expansions in administrative files
13589 @cindex Internal variables
13592 Sometimes in writing an administrative file, you might
13593 want the file to be able to know various things based
13594 on environment @sc{cvs} is running in. There are
13595 several mechanisms to do that.
13597 To find the home directory of the user running @sc{cvs}
13598 (from the @code{HOME} environment variable), use
13599 @samp{~} followed by @samp{/} or the end of the line.
13600 Likewise for the home directory of @var{user}, use
13601 @samp{~@var{user}}. These variables are expanded on
13602 the server machine, and don't get any reasonable
13603 expansion if pserver (@pxref{Password authenticated})
13604 is in use; therefore user variables (see below) may be
13605 a better choice to customize behavior based on the user
13607 @c Based on these limitations, should we deprecate ~?
13608 @c What is it good for? Are people using it?
13610 One may want to know about various pieces of
13611 information internal to @sc{cvs}. A @sc{cvs} internal
13612 variable has the syntax @code{$@{@var{variable}@}},
13613 where @var{variable} starts with a letter and consists
13614 of alphanumeric characters and @samp{_}. If the
13615 character following @var{variable} is a
13616 non-alphanumeric character other than @samp{_}, the
13617 @samp{@{} and @samp{@}} can be omitted. The @sc{cvs}
13618 internal variables are:
13622 @cindex CVSROOT, internal variable
13623 This is the absolute path to the current @sc{cvs} root directory.
13624 @xref{Repository}, for a description of the various
13625 ways to specify this, but note that the internal
13626 variable contains just the directory and not any
13627 of the access method information.
13630 @cindex RCSBIN, internal variable
13631 In @sc{cvs} 1.9.18 and older, this specified the
13632 directory where @sc{cvs} was looking for @sc{rcs}
13633 programs. Because @sc{cvs} no longer runs @sc{rcs}
13634 programs, specifying this internal variable is now an
13638 @cindex CVSEDITOR, internal variable
13640 @cindex EDITOR, internal variable
13642 @cindex VISUAL, internal variable
13643 These all expand to the same value, which is the editor
13644 that @sc{cvs} is using. @xref{Global options}, for how
13648 @cindex USER, internal variable
13649 Username of the user running @sc{cvs} (on the @sc{cvs}
13651 When using pserver, this is the user specified in the repository
13652 specification which need not be the same as the username the
13653 server is running as (@pxref{Password authentication server}).
13654 Do not confuse this with the environment variable of the same name.
13657 If you want to pass a value to the administrative files
13658 which the user who is running @sc{cvs} can specify,
13659 use a user variable.
13660 @cindex User variables
13661 To expand a user variable, the
13662 administrative file contains
13663 @code{$@{=@var{variable}@}}. To set a user variable,
13664 specify the global option @samp{-s} to @sc{cvs}, with
13665 argument @code{@var{variable}=@var{value}}. It may be
13666 particularly useful to specify this option via
13667 @file{.cvsrc} (@pxref{~/.cvsrc}).
13669 For example, if you want the administrative file to
13670 refer to a test directory you might create a user
13671 variable @code{TESTDIR}. Then if @sc{cvs} is invoked
13675 cvs -s TESTDIR=/work/local/tests
13680 administrative file contains @code{sh
13681 $@{=TESTDIR@}/runtests}, then that string is expanded
13682 to @code{sh /work/local/tests/runtests}.
13684 All other strings containing @samp{$} are reserved;
13685 there is no way to quote a @samp{$} character so that
13686 @samp{$} represents itself.
13688 Environment variables passed to administrative files are:
13691 @cindex environment variables, passed to administrative files
13694 @cindex CVS_USER, environment variable
13695 The @sc{cvs}-specific username provided by the user, if it
13696 can be provided (currently just for the pserver access
13697 method), and to the empty string otherwise. (@code{CVS_USER}
13698 and @code{USER} may differ when @file{$CVSROOT/CVSROOT/passwd}
13699 is used to map @sc{cvs} usernames to system usernames.)
13702 @cindex LOGNAME, environment variable
13703 The username of the system user.
13706 @cindex USER, environment variable
13707 Same as @code{LOGNAME}.
13708 Do not confuse this with the internal variable of the same name.
13712 @appendixsec The CVSROOT/config configuration file
13714 @cindex config, in CVSROOT
13715 @cindex CVSROOT/config
13717 The administrative file @file{config} contains various
13718 miscellaneous settings which affect the behavior of
13719 @sc{cvs}. The syntax is slightly different from the
13720 other administrative files. Variables are not
13721 expanded. Lines which start with @samp{#} are
13722 considered comments.
13723 @c FIXME: where do we define comments for the other
13724 @c administrative files.
13725 Other lines consist of a keyword, @samp{=}, and a
13726 value. Note that this syntax is very strict.
13727 Extraneous spaces or tabs are not permitted.
13728 @c See comments in parseinfo.c:parse_config for more
13729 @c discussion of this strictness.
13731 Currently defined keywords are:
13734 @cindex RCSBIN, in CVSROOT/config
13735 @item RCSBIN=@var{bindir}
13736 For @sc{cvs} 1.9.12 through 1.9.18, this setting told
13737 @sc{cvs} to look for @sc{rcs} programs in the
13738 @var{bindir} directory. Current versions of @sc{cvs}
13739 do not run @sc{rcs} programs; for compatibility this
13740 setting is accepted, but it does nothing.
13742 @cindex SystemAuth, in CVSROOT/config
13743 @item SystemAuth=@var{value}
13744 If @var{value} is @samp{yes}, then pserver should check
13745 for users in the system's user database if not found in
13746 @file{CVSROOT/passwd}. If it is @samp{no}, then all
13747 pserver users must exist in @file{CVSROOT/passwd}.
13748 The default is @samp{yes}. For more on pserver, see
13749 @ref{Password authenticated}.
13752 @cindex PreservePermissions, in CVSROOT/config
13753 @item PreservePermissions=@var{value}
13754 Enable support for saving special device files,
13755 symbolic links, file permissions and ownerships in the
13756 repository. The default value is @samp{no}.
13757 @xref{Special Files}, for the full implications of using
13761 @cindex TopLevelAdmin, in CVSROOT/config
13762 @item TopLevelAdmin=@var{value}
13763 Modify the @samp{checkout} command to create a
13764 @samp{CVS} directory at the top level of the new
13765 working directory, in addition to @samp{CVS}
13766 directories created within checked-out directories.
13767 The default value is @samp{no}.
13769 This option is useful if you find yourself performing
13770 many commands at the top level of your working
13771 directory, rather than in one of the checked out
13772 subdirectories. The @file{CVS} directory created there
13773 will mean you don't have to specify @code{CVSROOT} for
13774 each command. It also provides a place for the
13775 @file{CVS/Template} file (@pxref{Working directory
13778 @cindex LockDir, in CVSROOT/config
13779 @item LockDir=@var{directory}
13780 Put @sc{cvs} lock files in @var{directory} rather than
13781 directly in the repository. This is useful if you want
13782 to let users read from the repository while giving them
13783 write access only to @var{directory}, not to the
13785 It can also be used to put the locks on a very fast
13786 in-memory file system to speed up locking and unlocking
13788 You need to create @var{directory}, but
13789 @sc{cvs} will create subdirectories of @var{directory} as it
13790 needs them. For information on @sc{cvs} locks, see
13793 @c Mention this in Compatibility section?
13794 Before enabling the LockDir option, make sure that you
13795 have tracked down and removed any copies of @sc{cvs} 1.9 or
13796 older. Such versions neither support LockDir, nor will
13797 give an error indicating that they don't support it.
13798 The result, if this is allowed to happen, is that some
13799 @sc{cvs} users will put the locks one place, and others will
13800 put them another place, and therefore the repository
13801 could become corrupted. @sc{cvs} 1.10 does not support
13802 LockDir but it will print a warning if run on a
13803 repository with LockDir enabled.
13805 @cindex LogHistory, in CVSROOT/config
13806 @item LogHistory=@var{value}
13807 Control what is logged to the @file{CVSROOT/history} file (@pxref{history}).
13808 Default of @samp{TOEFWUPCGMAR} (or simply @samp{all}) will log
13809 all transactions. Any subset of the default is
13810 legal. (For example, to only log transactions that modify the
13811 @file{*,v} files, use @samp{LogHistory=TMAR}.)
13813 @cindex RereadLogAfterVerify, in CVSROOT/config
13814 @cindex @file{verifymsg}, changing the log message
13815 @item RereadLogAfterVerify=@var{value}
13816 Modify the @samp{commit} command such that CVS will reread the
13817 log message after running the program specified by @file{verifymsg}.
13818 @var{value} may be one of @samp{yes} or @samp{always}, indicating that
13819 the log message should always be reread; @samp{no}
13820 or @samp{never}, indicating that it should never be
13821 reread; or @var{value} may be @samp{stat}, indicating
13822 that the file should be checked with the file system
13823 @samp{stat()} function to see if it has changed (see warning below)
13824 before rereading. The default value is @samp{always}.
13826 @strong{The `stat' mode can cause CVS to pause for up to
13827 one extra second per directory committed. This can be less IO and
13828 CPU intensive but is not recommended for use with large repositories}
13830 @xref{verifymsg}, for more information on how verifymsg
13833 @cindex IgnoreUnknownConfigKeys, in CVSROOT/config
13834 @item IgnoreUnknownConfigKeys=@var{value}
13835 If @var{value} is @samp{yes}, then @sc{cvs} should
13836 ignore any keywords in @file{CVSROOT/config} which it
13837 does not recognize. This option is intended primarily
13838 for transitions between versions of @sc{cvs} which
13839 support more configuration options in an environment
13840 where a read-only mirror of the current @sc{cvs} server
13841 may be maintained by someone else who is not yet ready
13842 to upgrade to the same version. It is recommended that
13843 this option be used only for a short time so that
13844 problems with the @file{CVSROOT/config} file will be
13845 found quickly. The default is @samp{no}.
13848 @c ---------------------------------------------------------------------
13849 @node Environment variables
13850 @appendix All environment variables which affect CVS
13851 @cindex Environment variables
13852 @cindex Reference manual for variables
13854 This is a complete list of all environment variables
13855 that affect @sc{cvs}.
13858 @cindex CVSIGNORE, environment variable
13860 A whitespace-separated list of file name patterns that
13861 @sc{cvs} should ignore. @xref{cvsignore}.
13863 @cindex CVSWRAPPERS, environment variable
13865 A whitespace-separated list of file name patterns that
13866 @sc{cvs} should treat as wrappers. @xref{Wrappers}.
13868 @cindex CVSREAD, environment variable
13869 @cindex Read-only files, and CVSREAD
13871 If this is set, @code{checkout} and @code{update} will
13872 try hard to make the files in your working directory
13873 read-only. When this is not set, the default behavior
13874 is to permit modification of your working files.
13877 Controls permissions of files in the repository. See
13878 @ref{File permissions}.
13881 Should contain the full pathname to the root of the @sc{cvs}
13882 source repository (where the @sc{rcs} files are
13883 kept). This information must be available to @sc{cvs} for
13884 most commands to execute; if @code{$CVSROOT} is not set,
13885 or if you wish to override it for one invocation, you
13886 can supply it on the command line: @samp{cvs -d cvsroot
13887 cvs_command@dots{}} Once you have checked out a working
13888 directory, @sc{cvs} stores the appropriate root (in
13889 the file @file{CVS/Root}), so normally you only need to
13890 worry about this when initially checking out a working
13894 @cindex CVSEDITOR, environment variable
13896 @cindex EDITOR, environment variable
13898 @cindex VISUAL, environment variable
13899 Specifies the program to use for recording log messages
13900 during commit. @code{$CVSEDITOR} overrides
13901 @code{$EDITOR}, which overrides @code{$VISUAL}.
13902 See @ref{Committing your changes} for more or
13903 @ref{Global options} for alternative ways of specifying a
13906 @cindex PATH, environment variable
13908 If @code{$RCSBIN} is not set, and no path is compiled
13909 into @sc{cvs}, it will use @code{$PATH} to try to find all
13912 @cindex HOME, environment variable
13914 @cindex HOMEPATH, environment variable
13916 @cindex HOMEDRIVE, environment variable
13918 Used to locate the directory where the @file{.cvsrc}
13919 file, and other such files, are searched. On Unix, @sc{cvs}
13920 just checks for @code{HOME}. On Windows NT, the system will
13921 set @code{HOMEDRIVE}, for example to @samp{d:} and @code{HOMEPATH},
13922 for example to @file{\joe}. On Windows 95, you'll
13923 probably need to set @code{HOMEDRIVE} and @code{HOMEPATH} yourself.
13924 @c We are being vague about whether HOME works on
13925 @c Windows; see long comment in windows-NT/filesubr.c.
13927 @cindex CVS_RSH, environment variable
13929 Specifies the external program which @sc{cvs} connects with,
13930 when @code{:ext:} access method is specified.
13931 @pxref{Connecting via rsh}.
13933 @cindex CVS_SSH, environment variable
13935 Specifies the external program which @sc{cvs} connects with,
13936 when @code{:extssh:} access method is specified.
13937 @pxref{Connecting via rsh}.
13940 Used in client-server mode when accessing a remote
13941 repository using @sc{rsh}. It specifies the name of
13942 the program to start on the server side (and any
13943 necessary arguments) when accessing a remote repository
13944 using the @code{:ext:}, @code{:fork:}, or @code{:server:} access methods.
13945 The default value for @code{:ext:} and @code{:server:} is @code{cvs};
13946 the default value for @code{:fork:} is the name used to run the client.
13947 @pxref{Connecting via rsh}
13949 @item $CVS_PASSFILE
13950 Used in client-server mode when accessing the @code{cvs
13951 login server}. Default value is @file{$HOME/.cvspass}.
13952 @pxref{Password authentication client}
13954 @item $CVS_CLIENT_PORT
13955 Used in client-server mode to set the port to use when accessing the server
13956 via Kerberos, GSSAPI, or @sc{cvs}'s password authentication protocol
13957 if the port is not specified in the CVSROOT.
13958 @pxref{Remote repositories}
13960 @cindex CVS_RCMD_PORT, environment variable
13961 @item $CVS_RCMD_PORT
13962 Used in client-server mode. If set, specifies the port
13963 number to be used when accessing the @sc{rcmd} demon on
13964 the server side. (Currently not used for Unix clients).
13966 @cindex CVS_CLIENT_LOG, environment variable
13967 @item $CVS_CLIENT_LOG
13968 Used for debugging only in client-server
13969 mode. If set, everything sent to the server is logged
13970 into @file{@code{$CVS_CLIENT_LOG}.in} and everything
13971 sent from the server is logged into
13972 @file{@code{$CVS_CLIENT_LOG}.out}.
13974 @cindex CVS_SERVER_SLEEP, environment variable
13975 @item $CVS_SERVER_SLEEP
13976 Used only for debugging the server side in
13977 client-server mode. If set, delays the start of the
13978 server child process the specified amount of
13979 seconds so that you can attach to it with a debugger.
13981 @cindex CVS_IGNORE_REMOTE_ROOT, environment variable
13982 @item $CVS_IGNORE_REMOTE_ROOT
13983 For @sc{cvs} 1.10 and older, setting this variable
13984 prevents @sc{cvs} from overwriting the @file{CVS/Root}
13985 file when the @samp{-d} global option is specified.
13986 Later versions of @sc{cvs} do not rewrite
13987 @file{CVS/Root}, so @code{CVS_IGNORE_REMOTE_ROOT} has no
13990 @cindex COMSPEC, environment variable
13992 Used under OS/2 only. It specifies the name of the
13993 command interpreter and defaults to @sc{cmd.exe}.
13995 @cindex TMPDIR, environment variable
13997 @cindex TMP, environment variable
13999 @cindex TEMP, environment variable
14001 @cindex Temporary files, location of
14002 @c This is quite nuts. We don't talk about tempnam
14003 @c or mkstemp which we sometimes use. The discussion
14004 @c of "Global options" is semi-incoherent.
14005 @c I'm not even sure those are the only inaccuracies.
14006 @c Furthermore, the conventions are
14007 @c pretty crazy and they should be simplified.
14008 Directory in which temporary files are located.
14009 The @sc{cvs} server uses
14010 @code{TMPDIR}. @xref{Global options}, for a
14011 description of how to specify this.
14012 Some parts of @sc{cvs} will always use @file{/tmp} (via
14013 the @code{tmpnam} function provided by the system).
14015 On Windows NT, @code{TMP} is used (via the @code{_tempnam}
14016 function provided by the system).
14018 The @code{patch} program which is used by the @sc{cvs}
14019 client uses @code{TMPDIR}, and if it is not set, uses
14020 @file{/tmp} (at least with GNU patch 2.1). Note that
14021 if your server and client are both running @sc{cvs}
14022 1.9.10 or later, @sc{cvs} will not invoke an external
14023 @code{patch} program.
14026 @node Compatibility
14027 @appendix Compatibility between CVS Versions
14029 @cindex CVS, versions of
14030 @cindex Versions, of CVS
14031 @cindex Compatibility, between CVS versions
14032 @c We don't mention versions older than CVS 1.3
14033 @c on the theory that it would clutter it up for the vast
14034 @c majority of people, who don't have anything that old.
14036 The repository format is compatible going back to
14037 @sc{cvs} 1.3. But see @ref{Watches Compatibility}, if
14038 you have copies of @sc{cvs} 1.6 or older and you want
14039 to use the optional developer communication features.
14040 @c If you "cvs rm" and commit using 1.3, then you'll
14041 @c want to run "rcs -sdead <file,v>" on each of the
14042 @c files in the Attic if you then want 1.5 and
14043 @c later to recognize those files as dead (I think the
14044 @c symptom if this is not done is that files reappear
14045 @c in joins). (Wait: the above will work but really to
14046 @c be strictly correct we should suggest checking
14047 @c in a new revision rather than just changing the
14048 @c state of the head revision, shouldn't we?).
14049 @c The old convert.sh script was for this, but it never
14050 @c did get updated to reflect use of the RCS "dead"
14052 @c Note: this is tricky to document without confusing
14053 @c people--need to carefully say what CVS version we
14054 @c are talking about and keep in mind the distinction
14056 @c repository created with 1.3 and on which one now
14057 @c uses 1.5+, and a repository on which one wants to
14058 @c use both versions side by side (e.g. during a
14059 @c transition period).
14060 @c Wait, can't CVS just detect the case in which a file
14061 @c is in the Attic but the head revision is not dead?
14062 @c Not sure whether this should produce a warning or
14063 @c something, and probably needs further thought, but
14064 @c it would appear that the situation can be detected.
14066 @c We might want to separate out the 1.3 compatibility
14067 @c section (for repository & working directory) from the
14068 @c rest--that might help avoid confusing people who
14069 @c are upgrading (for example) from 1.6 to 1.8.
14071 @c A minor incompatibility is if a current version of CVS
14072 @c puts "Nfoo" into CVS/Tag, then CVS 1.9 or older will
14073 @c see this as if there is no tag. Seems to me this is
14074 @c too obscure to mention.
14076 The working directory format is compatible going back
14077 to @sc{cvs} 1.5. It did change between @sc{cvs} 1.3
14078 and @sc{cvs} 1.5. If you run @sc{cvs} 1.5 or newer on
14079 a working directory checked out with @sc{cvs} 1.3,
14080 @sc{cvs} will convert it, but to go back to @sc{cvs}
14081 1.3 you need to check out a new working directory with
14084 The remote protocol is interoperable going back to @sc{cvs} 1.5, but no
14085 further (1.5 was the first official release with the remote protocol,
14086 but some older versions might still be floating around). In many
14087 cases you need to upgrade both the client and the server to take
14088 advantage of new features and bug fixes, however.
14090 @c Perhaps should be saying something here about the
14091 @c "D" lines in Entries (written by CVS 1.9; 1.8 and
14092 @c older don't use them). These are supposed to be
14093 @c compatible in both directions, but I'm not sure
14094 @c they quite are 100%. One common gripe is if you
14095 @c "rm -r" a directory and 1.9 gets confused, as it
14096 @c still sees it in Entries. That one is fixed in
14097 @c (say) 1.9.6. Someone else reported problems with
14098 @c starting with a directory which was checked out with
14099 @c an old version, and then using a new version, and
14100 @c some "D" lines appeared, but not for every
14101 @c directory, causing some directories to be skipped.
14102 @c They weren't sure how to reproduce this, though.
14104 @c ---------------------------------------------------------------------
14105 @node Troubleshooting
14106 @appendix Troubleshooting
14108 If you are having trouble with @sc{cvs}, this appendix
14109 may help. If there is a particular error message which
14110 you are seeing, then you can look up the message
14111 alphabetically. If not, you can look through the
14112 section on other problems to see if your problem is
14116 * Error messages:: Partial list of CVS errors
14117 * Connection:: Trouble making a connection to a CVS server
14118 * Other problems:: Problems not readily listed by error message
14122 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
14123 @c @node Bad administrative files
14124 @appendixsec Bad administrative files
14126 @c -- Give hints on how to fix them
14129 @node Error messages
14130 @appendixsec Partial list of error messages
14132 Here is a partial list of error messages that you may
14133 see from @sc{cvs}. It is not a complete list---@sc{cvs}
14134 is capable of printing many, many error messages, often
14135 with parts of them supplied by the operating system,
14136 but the intention is to list the common and/or
14137 potentially confusing error messages.
14139 The messages are alphabetical, but introductory text
14140 such as @samp{cvs update: } is not considered in
14143 In some cases the list includes messages printed by old
14144 versions of @sc{cvs} (partly because users may not be
14145 sure which version of @sc{cvs} they are using at any
14146 particular moment).
14147 @c If we want to start retiring messages, perhaps we
14148 @c should pick a cutoff version (for example, no more
14149 @c messages which are specific to versions before 1.9)
14150 @c and then move the old messages to an "old messages"
14151 @c node rather than deleting them completely.
14154 @c FIXME: What is the correct way to format a multiline
14155 @c error message here? Maybe @table is the wrong
14156 @c choice? Texinfo gurus?
14157 @item @var{file}:@var{line}: Assertion '@var{text}' failed
14158 The exact format of this message may vary depending on
14159 your system. It indicates a bug in @sc{cvs}, which can
14160 be handled as described in @ref{BUGS}.
14162 @item cvs @var{command}: authorization failed: server @var{host} rejected access
14163 This is a generic response when trying to connect to a
14164 pserver server which chooses not to provide a
14165 specific reason for denying authorization. Check that
14166 the username and password specified are correct and
14167 that the @code{CVSROOT} specified is allowed by @samp{--allow-root}
14168 in @file{inetd.conf}. See @ref{Password authenticated}.
14170 @item cvs @var{command}: conflict: removed @var{file} was modified by second party
14171 This message indicates that you removed a file, and
14172 someone else modified it. To resolve the conflict,
14173 first run @samp{cvs add @var{file}}. If desired, look
14174 at the other party's modification to decide whether you
14175 still want to remove it. If you don't want to remove
14176 it, stop here. If you do want to remove it, proceed
14177 with @samp{cvs remove @var{file}} and commit your
14179 @c Tests conflicts2-142b* in sanity.sh test for this.
14181 @item cannot change permissions on temporary directory
14183 Operation not permitted
14185 This message has been happening in a non-reproducible,
14186 occasional way when we run the client/server testsuite,
14187 both on Red Hat Linux 3.0.3 and 4.1. We haven't been
14188 able to figure out what causes it, nor is it known
14189 whether it is specific to Linux (or even to this
14190 particular machine!). If the problem does occur on
14191 other unices, @samp{Operation not permitted} would be
14192 likely to read @samp{Not owner} or whatever the system
14193 in question uses for the unix @code{EPERM} error. If
14194 you have any information to add, please let us know as
14195 described in @ref{BUGS}. If you experience this error
14196 while using @sc{cvs}, retrying the operation which
14197 produced it should work fine.
14198 @c This has been seen in a variety of tests, including
14199 @c multibranch-2, multibranch-5, and basic1-24-rm-rm,
14200 @c so it doesn't seem particularly specific to any one
14203 @item cvs [server aborted]: Cannot check out files into the repository itself
14204 The obvious cause for this message (especially for
14205 non-client/server @sc{cvs}) is that the @sc{cvs} root
14206 is, for example, @file{/usr/local/cvsroot} and you try
14207 to check out files when you are in a subdirectory, such
14208 as @file{/usr/local/cvsroot/test}. However, there is a
14209 more subtle cause, which is that the temporary
14210 directory on the server is set to a subdirectory of the
14211 root (which is also not allowed). If this is the
14212 problem, set the temporary directory to somewhere else,
14213 for example @file{/var/tmp}; see @code{TMPDIR} in
14214 @ref{Environment variables}, for how to set the
14215 temporary directory.
14217 @item cannot commit files as 'root'
14218 See @samp{'root' is not allowed to commit files}.
14220 @c For one example see basica-1a10 in the testsuite
14221 @c For another example, "cvs co ." on NT; see comment
14222 @c at windows-NT/filesubr.c (expand_wild).
14223 @c For another example, "cvs co foo/bar" where foo exists.
14224 @item cannot open CVS/Entries for reading: No such file or directory
14225 This generally indicates a @sc{cvs} internal error, and
14226 can be handled as with other @sc{cvs} bugs
14227 (@pxref{BUGS}). Usually there is a workaround---the
14228 exact nature of which would depend on the situation but
14229 which hopefully could be figured out.
14231 @c This is more obscure than it might sound; it only
14232 @c happens if you run "cvs init" from a directory which
14233 @c contains a CVS/Root file at the start.
14234 @item cvs [init aborted]: cannot open CVS/Root: No such file or directory
14235 This message is harmless. Provided it is not
14236 accompanied by other errors, the operation has
14237 completed successfully. This message should not occur
14238 with current versions of @sc{cvs}, but it is documented
14239 here for the benefit of @sc{cvs} 1.9 and older.
14241 @item cvs server: cannot open /root/.cvsignore: Permission denied
14242 @itemx cvs [server aborted]: can't chdir(/root): Permission denied
14243 See @ref{Connection}.
14245 @item cvs [checkout aborted]: cannot rename file @var{file} to CVS/,,@var{file}: Invalid argument
14246 This message has been reported as intermittently
14247 happening with @sc{cvs} 1.9 on Solaris 2.5. The cause is
14248 unknown; if you know more about what causes it, let us
14249 know as described in @ref{BUGS}.
14251 @item cvs [@var{command} aborted]: cannot start server via rcmd
14252 This, unfortunately, is a rather nonspecific error
14253 message which @sc{cvs} 1.9 will print if you are
14254 running the @sc{cvs} client and it is having trouble
14255 connecting to the server. Current versions of @sc{cvs}
14256 should print a much more specific error message. If
14257 you get this message when you didn't mean to run the
14258 client at all, you probably forgot to specify
14259 @code{:local:}, as described in @ref{Repository}.
14261 @item ci: @var{file},v: bad diff output line: Binary files - and /tmp/T2a22651 differ
14262 @sc{cvs} 1.9 and older will print this message
14263 when trying to check in a binary file if
14264 @sc{rcs} is not correctly installed. Re-read the
14265 instructions that came with your @sc{rcs} distribution
14266 and the @sc{install} file in the @sc{cvs}
14267 distribution. Alternately, upgrade to a current
14268 version of @sc{cvs}, which checks in files itself
14269 rather than via @sc{rcs}.
14271 @item cvs checkout: could not check out @var{file}
14272 With @sc{cvs} 1.9, this can mean that the @code{co} program
14273 (part of @sc{rcs}) returned a failure. It should be
14274 preceded by another error message, however it has been
14275 observed without another error message and the cause is
14276 not well-understood. With the current version of @sc{cvs},
14277 which does not run @code{co}, if this message occurs
14278 without another error message, it is definitely a @sc{cvs}
14279 bug (@pxref{BUGS}).
14280 @c My current suspicion is that the RCS in the rcs (not
14281 @c cvs/winnt/rcs57nt.zip) directory on the _Practical_
14282 @c CD is bad (remains to be confirmed).
14283 @c There is also a report of something which looks
14284 @c very similar on SGI, Irix 5.2, so I dunno.
14286 @item cvs [login aborted]: could not find out home directory
14287 This means that you need to set the environment
14288 variables that @sc{cvs} uses to locate your home directory.
14289 See the discussion of @code{HOME}, @code{HOMEDRIVE}, and @code{HOMEPATH} in
14290 @ref{Environment variables}.
14292 @item cvs update: could not merge revision @var{rev} of @var{file}: No such file or directory
14293 @sc{cvs} 1.9 and older will print this message if there was
14294 a problem finding the @code{rcsmerge} program. Make
14295 sure that it is in your @code{PATH}, or upgrade to a
14296 current version of @sc{cvs}, which does not require
14297 an external @code{rcsmerge} program.
14299 @item cvs [update aborted]: could not patch @var{file}: No such file or directory
14300 This means that there was a problem finding the
14301 @code{patch} program. Make sure that it is in your
14302 @code{PATH}. Note that despite appearances the message
14303 is @emph{not} referring to whether it can find @var{file}.
14304 If both the client and the server are running a current
14305 version of @sc{cvs}, then there is no need for an
14306 external patch program and you should not see this
14307 message. But if either client or server is running
14308 @sc{cvs} 1.9, then you need @code{patch}.
14310 @item cvs update: could not patch @var{file}; will refetch
14311 This means that for whatever reason the client was
14312 unable to apply a patch that the server sent. The
14313 message is nothing to be concerned about, because
14314 inability to apply the patch only slows things down and
14315 has no effect on what @sc{cvs} does.
14316 @c xref to update output. Or File status?
14317 @c Or some place else that
14318 @c explains this whole "patch"/P/Needs Patch thing?
14320 @item dying gasps from @var{server} unexpected
14321 There is a known bug in the server for @sc{cvs} 1.9.18
14322 and older which can cause this. For me, this was
14323 reproducible if I used the @samp{-t} global option. It
14324 was fixed by Andy Piper's 14 Nov 1997 change to
14325 src/filesubr.c, if anyone is curious.
14326 If you see the message,
14327 you probably can just retry the operation which failed,
14328 or if you have discovered information concerning its
14329 cause, please let us know as described in @ref{BUGS}.
14331 @item end of file from server (consult above messages if any)
14332 The most common cause for this message is if you are
14333 using an external @code{rsh} or @code{ssh} program and it exited with
14334 an error. In this case the @code{rsh} program should
14335 have printed a message, which will appear before the
14336 above message. For more information on setting up a
14337 @sc{cvs} client and server, see @ref{Remote repositories}.
14339 @item cvs [update aborted]: EOF in key in RCS file @var{file},v
14340 @itemx cvs [checkout aborted]: EOF while looking for end of string in RCS file @var{file},v
14341 This means that there is a syntax error in the given
14342 @sc{rcs} file. Note that this might be true even if @sc{rcs} can
14343 read the file OK; @sc{cvs} does more error checking of
14344 errors in the RCS file. That is why you may see this
14345 message when upgrading from @sc{cvs} 1.9 to @sc{cvs}
14346 1.10. The likely cause for the original corruption is
14347 hardware, the operating system, or the like. Of
14348 course, if you find a case in which @sc{cvs} seems to
14349 corrupting the file, by all means report it,
14351 There are quite a few variations of this error message,
14352 depending on exactly where in the @sc{rcs} file @sc{cvs}
14353 finds the syntax error.
14356 @item cvs commit: Executing 'mkmodules'
14357 This means that your repository is set up for a version
14358 of @sc{cvs} prior to @sc{cvs} 1.8. When using @sc{cvs}
14359 1.8 or later, the above message will be preceded by
14362 cvs commit: Rebuilding administrative file database
14365 If you see both messages, the database is being rebuilt
14366 twice, which is unnecessary but harmless. If you wish
14367 to avoid the duplication, and you have no versions of
14368 @sc{cvs} 1.7 or earlier in use, remove @code{-i mkmodules}
14369 every place it appears in your @code{modules}
14370 file. For more information on the @code{modules} file,
14373 @c This message comes from "co", and I believe is
14374 @c possible only with older versions of CVS which call
14375 @c co. The problem with being able to create the bogus
14376 @c RCS file still exists, though (and I think maybe
14377 @c there is a different symptom(s) now).
14378 @c FIXME: Would be nice to have a more exact wording
14379 @c for this message.
14380 @item missing author
14381 Typically this can happen if you created an RCS file
14382 with your username set to empty. @sc{cvs} will, bogusly,
14383 create an illegal RCS file with no value for the author
14384 field. The solution is to make sure your username is
14385 set to a non-empty value and re-create the RCS file.
14386 @c "make sure your username is set" is complicated in
14387 @c and of itself, as there are the environment
14388 @c variables the system login name, &c, and it depends
14389 @c on the version of CVS.
14391 @item cvs [checkout aborted]: no such tag @var{tag}
14392 This message means that @sc{cvs} isn't familiar with
14393 the tag @var{tag}. Usually this means that you have
14394 mistyped a tag name; however there are (relatively
14395 obscure) cases in which @sc{cvs} will require you to
14396 @c Search sanity.sh for "no such tag" to see some of
14397 @c the relatively obscure cases.
14398 try a few other @sc{cvs} commands involving that tag,
14399 before you find one which will cause @sc{cvs} to update
14400 @cindex CVSROOT/val-tags file, forcing tags into
14401 @cindex val-tags file, forcing tags into
14402 the @file{val-tags} file; see discussion of val-tags in
14403 @ref{File permissions}. You only need to worry about
14404 this once for a given tag; when a tag is listed in
14405 @file{val-tags}, it stays there. Note that using
14406 @samp{-f} to not require tag matches does not override
14407 this check; see @ref{Common options}.
14409 @item *PANIC* administration files missing
14410 This typically means that there is a directory named
14411 @sc{cvs} but it does not contain the administrative files
14412 which @sc{cvs} puts in a CVS directory. If the problem is
14413 that you created a CVS directory via some mechanism
14414 other than @sc{cvs}, then the answer is simple, use a name
14415 other than @sc{cvs}. If not, it indicates a @sc{cvs} bug
14418 @item rcs error: Unknown option: -x,v/
14419 This message will be followed by a usage message for
14420 @sc{rcs}. It means that you have an old version of
14421 @sc{rcs} (probably supplied with your operating
14422 system), as well as an old version of @sc{cvs}.
14423 @sc{cvs} 1.9.18 and earlier only work with @sc{rcs} version 5 and
14424 later; current versions of @sc{cvs} do not run @sc{rcs} programs.
14425 @c For more information on installing @sc{cvs}, see
14426 @c (FIXME: where? it depends on whether you are
14427 @c getting binaries or sources or what).
14428 @c The message can also say "ci error" or something
14429 @c instead of "rcs error", I suspect.
14431 @item cvs [server aborted]: received broken pipe signal
14432 This message can be caused by a loginfo program that fails to
14433 read all of the log information from its standard input.
14434 If you find it happening in any other circumstances,
14435 please let us know as described in @ref{BUGS}.
14437 @item 'root' is not allowed to commit files
14438 When committing a permanent change, @sc{cvs} makes a log entry of
14439 who committed the change. If you are committing the change logged
14440 in as "root" (not under "su" or other root-priv giving program),
14441 @sc{cvs} cannot determine who is actually making the change.
14442 As such, by default, @sc{cvs} disallows changes to be committed by users
14443 logged in as "root". (You can disable this option by passing the
14444 @code{--enable-rootcommit} option to @file{configure} and recompiling @sc{cvs}.
14445 On some systems this means editing the appropriate @file{config.h} file
14446 before building @sc{cvs}.)
14448 @item Terminated with fatal signal 11
14449 This message usually indicates that @sc{cvs} (the server, if you're
14450 using client/server mode) has run out of (virtual) memory.
14451 Although @sc{cvs} tries to catch the error and issue a more meaningful
14452 message, there are many circumstances where that is not possible.
14453 If you appear to have lots of memory available to the system,
14454 the problem is most likely that you're running into a system-wide
14455 limit on the amount of memory a single process can use or a
14456 similar process-specific limit.
14457 The mechanisms for displaying and setting such limits vary from
14458 system to system, so you'll have to consult an expert for your
14459 particular system if you don't know how to do that.
14461 @item Too many arguments!
14462 This message is typically printed by the @file{log.pl}
14463 script which is in the @file{contrib} directory in the
14464 @sc{cvs} source distribution. In some versions of
14465 @sc{cvs}, @file{log.pl} has been part of the default
14466 @sc{cvs} installation. The @file{log.pl} script gets
14467 called from the @file{loginfo} administrative file.
14468 Check that the arguments passed in @file{loginfo} match
14469 what your version of @file{log.pl} expects. In
14470 particular, the @file{log.pl} from @sc{cvs} 1.3 and
14471 older expects the log file as an argument whereas the
14472 @file{log.pl} from @sc{cvs} 1.5 and newer expects the
14473 log file to be specified with a @samp{-f} option. Of
14474 course, if you don't need @file{log.pl} you can just
14475 comment it out of @file{loginfo}.
14477 @item cvs [update aborted]: unexpected EOF reading @var{file},v
14478 See @samp{EOF in key in RCS file}.
14480 @item cvs [login aborted]: unrecognized auth response from @var{server}
14481 This message typically means that the server is not set
14482 up properly. For example, if @file{inetd.conf} points
14483 to a nonexistent cvs executable. To debug it further,
14484 find the log file which inetd writes
14485 (@file{/var/log/messages} or whatever inetd uses on
14486 your system). For details, see @ref{Connection}, and
14487 @ref{Password authentication server}.
14489 @item cvs commit: Up-to-date check failed for `@var{file}'
14490 This means that someone else has committed a change to
14491 that file since the last time that you did a @code{cvs
14492 update}. So before proceeding with your @code{cvs
14493 commit} you need to @code{cvs update}. @sc{cvs} will merge
14494 the changes that you made and the changes that the
14495 other person made. If it does not detect any conflicts
14496 it will report @samp{M @var{file}} and you are ready
14497 to @code{cvs commit}. If it detects conflicts it will
14498 print a message saying so, will report @samp{C @var{file}},
14499 and you need to manually resolve the
14500 conflict. For more details on this process see
14501 @ref{Conflicts example}.
14503 @item Usage: diff3 [-exEX3 [-i | -m] [-L label1 -L label3]] file1 file2 file3
14505 Only one of [exEX3] allowed
14507 This indicates a problem with the installation of
14508 @code{diff3} and @code{rcsmerge}. Specifically
14509 @code{rcsmerge} was compiled to look for GNU diff3, but
14510 it is finding unix diff3 instead. The exact text of
14511 the message will vary depending on the system. The
14512 simplest solution is to upgrade to a current version of
14513 @sc{cvs}, which does not rely on external
14514 @code{rcsmerge} or @code{diff3} programs.
14516 @item warning: unrecognized response `@var{text}' from cvs server
14517 If @var{text} contains a valid response (such as
14518 @samp{ok}) followed by an extra carriage return
14519 character (on many systems this will cause the second
14520 part of the message to overwrite the first part), then
14521 it probably means that you are using the @samp{:ext:}
14522 access method with a version of rsh, such as most
14523 non-unix rsh versions, which does not by default
14524 provide a transparent data stream. In such cases you
14525 probably want to try @samp{:server:} instead of
14526 @samp{:ext:}. If @var{text} is something else, this
14527 may signify a problem with your @sc{cvs} server.
14528 Double-check your installation against the instructions
14529 for setting up the @sc{cvs} server.
14530 @c FIXCVS: should be printing CR as \r or \015 or some
14533 @item cvs commit: [@var{time}] waiting for @var{user}'s lock in @var{directory}
14534 This is a normal message, not an error. See
14535 @ref{Concurrency}, for more details.
14537 @item cvs commit: warning: editor session failed
14538 @cindex Exit status, of editor
14539 This means that the editor which @sc{cvs} is using exits with a nonzero
14540 exit status. Some versions of vi will do this even when there was not
14541 a problem editing the file. If so, point the
14542 @code{CVSEDITOR} environment variable to a small script
14551 @item cvs update: warning: @var{file} was lost
14552 This means that the working copy of @var{file} has been deleted
14553 but it has not been removed from @sc{cvs}.
14554 This is nothing to be concerned about,
14555 the update will just recreate the local file from the repository.
14556 (This is a convenient way to discard local changes to a file:
14557 just delete it and then run @code{cvs update}.)
14559 @item cvs update: warning: @var{file} is not (any longer) pertinent
14560 This means that the working copy of @var{file} has been deleted,
14561 it has not been removed from @sc{cvs} in the current working directory,
14562 but it has been removed from @sc{cvs} in some other working directory.
14563 This is nothing to be concerned about,
14564 the update would have removed the local file anyway.
14569 @appendixsec Trouble making a connection to a CVS server
14571 This section concerns what to do if you are having
14572 trouble making a connection to a @sc{cvs} server. If
14573 you are running the @sc{cvs} command line client
14574 running on Windows, first upgrade the client to
14575 @sc{cvs} 1.9.12 or later. The error reporting in
14576 earlier versions provided much less information about
14577 what the problem was. If the client is non-Windows,
14578 @sc{cvs} 1.9 should be fine.
14580 If the error messages are not sufficient to track down
14581 the problem, the next steps depend largely on which
14582 access method you are using.
14585 @cindex :ext:, troubleshooting
14587 Try running the rsh program from the command line. For
14588 example: "rsh servername cvs -v" should print @sc{cvs}
14589 version information. If this doesn't work, you need to
14590 fix it before you can worry about @sc{cvs} problems.
14592 @cindex :server:, troubleshooting
14594 You don't need a command line rsh program to use this
14595 access method, but if you have an rsh program around,
14596 it may be useful as a debugging tool. Follow the
14597 directions given for :ext:.
14599 @cindex :pserver:, troubleshooting
14601 Errors along the lines of "connection refused" typically indicate
14602 that inetd isn't even listening for connections on port 2401
14603 whereas errors like "connection reset by peer",
14604 "received broken pipe signal", "recv() from server: EOF",
14605 or "end of file from server"
14606 typically indicate that inetd is listening for
14607 connections but is unable to start @sc{cvs} (this is frequently
14608 caused by having an incorrect path in @file{inetd.conf}
14609 or by firewall software rejecting the connection).
14610 "unrecognized auth response" errors are caused by a bad command
14611 line in @file{inetd.conf}, typically an invalid option or forgetting
14612 to put the @samp{pserver} command at the end of the line.
14613 Another less common problem is invisible control characters that
14614 your editor "helpfully" added without you noticing.
14616 One good debugging tool is to "telnet servername
14617 2401". After connecting, send any text (for example
14618 "foo" followed by return). If @sc{cvs} is working
14619 correctly, it will respond with
14622 cvs [pserver aborted]: bad auth protocol start: foo
14625 If instead you get:
14628 Usage: cvs [cvs-options] command [command-options-and-arguments]
14633 then you're missing the @samp{pserver} command at the end of the
14634 line in @file{inetd.conf}; check to make sure that the entire command
14635 is on one line and that it's complete.
14637 Likewise, if you get something like:
14640 Unknown command: `pserved'
14643 add Add a new file/directory to the repository
14648 then you've misspelled @samp{pserver} in some way. If it isn't
14649 obvious, check for invisible control characters (particularly
14650 carriage returns) in @file{inetd.conf}.
14652 If it fails to work at all, then make sure inetd is working
14653 right. Change the invocation in @file{inetd.conf} to run the
14654 echo program instead of cvs. For example:
14657 2401 stream tcp nowait root /bin/echo echo hello
14660 After making that change and instructing inetd to
14661 re-read its configuration file, "telnet servername
14662 2401" should show you the text hello and then the
14663 server should close the connection. If this doesn't
14664 work, you need to fix it before you can worry about
14667 On AIX systems, the system will often have its own
14668 program trying to use port 2401. This is AIX's problem
14669 in the sense that port 2401 is registered for use with
14670 @sc{cvs}. I hear that there is an AIX patch available
14671 to address this problem.
14673 Another good debugging tool is the @samp{-d}
14674 (debugging) option to inetd. Consult your system
14675 documentation for more information.
14677 If you seem to be connecting but get errors like:
14680 cvs server: cannot open /root/.cvsignore: Permission denied
14681 cvs [server aborted]: can't chdir(/root): Permission denied
14685 then you probably haven't specified @samp{-f} in @file{inetd.conf}.
14686 (In releases prior to @sc{cvs} 1.11.1, this problem can be caused by
14687 your system setting the @code{$HOME} environment variable
14688 for programs being run by inetd. In this case, you can either
14689 have inetd run a shell script that unsets @code{$HOME} and then runs
14690 @sc{cvs}, or you can use @code{env} to run @sc{cvs} with a pristine
14693 If you can connect successfully for a while but then can't,
14694 you've probably hit inetd's rate limit.
14695 (If inetd receives too many requests for the same service
14696 in a short period of time, it assumes that something is wrong
14697 and temporarily disables the service.)
14698 Check your inetd documentation to find out how to adjust the
14699 rate limit (some versions of inetd have a single rate limit,
14700 others allow you to set the limit for each service separately.)
14703 @node Other problems
14704 @appendixsec Other common problems
14706 Here is a list of problems which do not fit into the
14707 above categories. They are in no particular order.
14711 On Windows, if there is a 30 second or so delay when
14712 you run a @sc{cvs} command, it may mean that you have
14713 your home directory set to @file{C:/}, for example (see
14714 @code{HOMEDRIVE} and @code{HOMEPATH} in
14715 @ref{Environment variables}). @sc{cvs} expects the home
14716 directory to not end in a slash, for example @file{C:}
14718 @c FIXCVS: CVS should at least detect this and print an
14719 @c error, presumably.
14722 If you are running @sc{cvs} 1.9.18 or older, and
14723 @code{cvs update} finds a conflict and tries to
14724 merge, as described in @ref{Conflicts example}, but
14725 doesn't tell you there were conflicts, then you may
14726 have an old version of @sc{rcs}. The easiest solution
14727 probably is to upgrade to a current version of
14728 @sc{cvs}, which does not rely on external @sc{rcs}
14732 @c ---------------------------------------------------------------------
14736 @cindex Contributors (manual)
14737 @cindex Credits (manual)
14738 Roland Pesch, then of Cygnus Support <@t{roland@@wrs.com}>
14739 wrote the manual pages which were distributed with
14740 @sc{cvs} 1.3. Much of their text was copied into this
14741 manual. He also read an early draft
14742 of this manual and contributed many ideas and
14745 The mailing-list @code{info-cvs} is sometimes
14746 informative. I have included information from postings
14747 made by the following persons:
14748 David G. Grubbs <@t{dgg@@think.com}>.
14750 Some text has been extracted from the man pages for
14753 The @sc{cvs} @sc{faq} by David G. Grubbs has provided
14754 useful material. The @sc{faq} is no longer maintained,
14755 however, and this manual is about the closest thing there
14756 is to a successor (with respect to documenting how to
14757 use @sc{cvs}, at least).
14759 In addition, the following persons have helped by
14760 telling me about mistakes I've made:
14763 Roxanne Brunskill <@t{rbrunski@@datap.ca}>,
14764 Kathy Dyer <@t{dyer@@phoenix.ocf.llnl.gov}>,
14765 Karl Pingle <@t{pingle@@acuson.com}>,
14766 Thomas A Peterson <@t{tap@@src.honeywell.com}>,
14767 Inge Wallin <@t{ingwa@@signum.se}>,
14768 Dirk Koschuetzki <@t{koschuet@@fmi.uni-passau.de}>
14769 and Michael Brown <@t{brown@@wi.extrel.com}>.
14772 The list of contributors here is not comprehensive; for a more
14773 complete list of who has contributed to this manual see
14774 the file @file{doc/ChangeLog} in the @sc{cvs} source
14777 @c ---------------------------------------------------------------------
14779 @appendix Dealing with bugs in CVS or this manual
14781 @cindex Bugs in this manual or CVS
14782 Neither @sc{cvs} nor this manual is perfect, and they
14783 probably never will be. If you are having trouble
14784 using @sc{cvs}, or think you have found a bug, there
14785 are a number of things you can do about it. Note that
14786 if the manual is unclear, that can be considered a bug
14787 in the manual, so these problems are often worth doing
14788 something about as well as problems with @sc{cvs} itself.
14790 @cindex Reporting bugs
14791 @cindex Bugs, reporting
14792 @cindex Errors, reporting
14795 If you want someone to help you and fix bugs that you
14796 report, there are companies which will do that for a
14797 fee. One such company is:
14800 @cindex Support, getting CVS support
14805 Rochester Hills, MI 48307-6636
14807 Email: info@@ximbiot.com
14808 Phone: (248) 835-1260
14809 Fax: (248) 835-1263
14810 @url{http://ximbiot.com/}
14815 If you got @sc{cvs} through a distributor, such as an
14816 operating system vendor or a vendor of freeware
14817 @sc{cd-rom}s, you may wish to see whether the
14818 distributor provides support. Often, they will provide
14819 no support or minimal support, but this may vary from
14820 distributor to distributor.
14823 If you have the skills and time to do so, you may wish
14824 to fix the bug yourself. If you wish to submit your
14825 fix for inclusion in future releases of @sc{cvs}, see
14826 the file @sc{hacking} in the @sc{cvs} source
14827 distribution. It contains much more information on the
14828 process of submitting fixes.
14831 There may be resources on the net which can help. A
14832 good place to start is:
14835 @url{http://cvs.nongnu.org/}
14838 If you are so inspired, increasing the information
14839 available on the net is likely to be appreciated. For
14840 example, before the standard @sc{cvs} distribution
14841 worked on Windows 95, there was a web page with some
14842 explanation and patches for running @sc{cvs} on Windows
14843 95, and various people helped out by mentioning this
14844 page on mailing lists or newsgroups when the subject
14848 It is also possible to report bugs to @email{bug-cvs@@nongnu.org}.
14849 Note that someone may or may not want to do anything
14850 with your bug report---if you need a solution consider
14851 one of the options mentioned above. People probably do
14852 want to hear about bugs which are particularly severe
14853 in consequences and/or easy to fix, however. You can
14854 also increase your odds by being as clear as possible
14855 about the exact nature of the bug and any other
14856 relevant information. The way to report bugs is to
14857 send email to @email{bug-cvs@@nongnu.org}. Note
14858 that submissions to @email{bug-cvs@@nongnu.org} may be distributed
14859 under the terms of the @sc{gnu} Public License, so if
14860 you don't like this, don't submit them. There is
14861 usually no justification for sending mail directly to
14862 one of the @sc{cvs} maintainers rather than to
14863 @email{bug-cvs@@nongnu.org}; those maintainers who want to hear
14864 about such bug reports read @email{bug-cvs@@nongnu.org}. Also note
14865 that sending a bug report to other mailing lists or
14866 newsgroups is @emph{not} a substitute for sending it to
14867 @email{bug-cvs@@nongnu.org}. It is fine to discuss @sc{cvs} bugs on
14868 whatever forum you prefer, but there are not
14869 necessarily any maintainers reading bug reports sent
14870 anywhere except @email{bug-cvs@@nongnu.org}.
14873 @cindex Known bugs in this manual or CVS
14874 People often ask if there is a list of known bugs or
14875 whether a particular bug is a known one. The file
14876 @sc{bugs} in the @sc{cvs} source distribution is one
14877 list of known bugs, but it doesn't necessarily try to
14878 be comprehensive. Perhaps there will never be a
14879 comprehensive, detailed list of known bugs.
14881 @c ---------------------------------------------------------------------