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 Free Software Foundation, Inc.
9 @multitable @columnfractions .12 .88
11 @item @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004
13 @item @tab Copyright @copyright{} 2002, 2003, 2004
14 Ximbiot @url{http://ximbiot.com},
15 @item @tab Copyright @copyright{} 1992, 1993, 1999 Signum Support AB,
16 @item @tab and Copyright @copyright{} others.
20 Permission is granted to process this file through Tex and print the
21 results, provided the printed document carries copying permission
22 notice identical to this one except for the removal of this paragraph
23 (this paragraph not being relevant to the printed manual).
26 Permission is granted to make and distribute verbatim copies of
27 this manual provided the copyright notice and this permission notice
28 are preserved on all copies.
30 Permission is granted to copy and distribute modified versions of this
31 manual under the conditions for verbatim copying, provided also that the
32 entire resulting derived work is distributed under the terms of a
33 permission notice identical to this one.
35 Permission is granted to copy and distribute translations of this manual
36 into another language, under the above conditions for modified versions,
37 except that this permission notice may be stated in a translation
38 approved by the Free Software Foundation.
41 @comment This file is part of the CVS distribution.
43 @comment CVS is free software; you can redistribute it and/or modify
44 @comment it under the terms of the GNU General Public License as published by
45 @comment the Free Software Foundation; either version 2, or (at your option)
46 @comment any later version.
48 @comment CVS is distributed in the hope that it will be useful,
49 @comment but WITHOUT ANY WARRANTY; without even the implied warranty of
50 @comment MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
51 @comment GNU General Public License for more details.
53 @c See ../README for A4 vs. US letter size.
54 @c When we provided A4 postscript, and people tried to
55 @c print it on US letter, the usual complaint was that the
56 @c page numbers would get cut off.
57 @c If one prints US letter on A4, reportedly there is
58 @c some extra space at the top and/or bottom, and the side
59 @c margins are a bit narrow, but no text is lost.
62 @c http://www.ft.uni-erlangen.de/~mskuhn/iso-paper.html
63 @c for more on paper sizes. Insuring that margins are
64 @c big enough to print on either A4 or US letter does
65 @c indeed seem to be the usual approach (RFC2346).
67 @c This document seems to get overfull hboxes with some
68 @c frequency (probably because the tendency is to
69 @c sanity-check it with "make info" and run TeX less
70 @c often). The big ugly boxes just seem to add insult
71 @c to injury, and I'm not aware of them helping to fix
72 @c the overfull hboxes at all.
76 @settitle CVS---Concurrent Versions System v@value{VERSION}
77 @setchapternewpage odd
80 @c -- Fix all lines that match "^@c -- "
81 @c -- Also places marked with FIXME should be manual
82 @c problems (as opposed to FIXCVS for CVS problems).
84 @c @splitrcskeyword{} is used to avoid keyword expansion. It is replaced by
85 @c @asis when generating info and dvi, and by <i></i> in the generated html,
86 @c such that keywords are not expanded in the generated html.
88 @macro splitrcskeyword {arg}
94 @macro splitrcskeyword {arg}
99 @dircategory GNU Packages
101 * CVS: (cvs). Concurrent Versions System
103 @dircategory Individual utilities
105 * cvs: (cvs)CVS commands. Concurrent Versions System
108 @comment The titlepage section does not appear in the Info file.
111 @comment The title is printed in a large font.
112 @center @titlefont{Version Management}
114 @center @titlefont{with}
116 @center @titlefont{CVS}
118 @center for @sc{cvs} @value{VERSION}
121 @center Per Cederqvist et al
123 @comment The following two commands start the copyright page
124 @comment for the printed manual. This will not appear in the Info file.
126 @vskip 0pt plus 1filll
130 @comment ================================================================
131 @comment The real text starts here
132 @comment ================================================================
135 @c ---------------------------------------------------------------------
139 This info manual describes how to use and administer
140 @sc{cvs} version @value{VERSION}.
147 @c This menu is pretty long. Not sure how easily that
148 @c can be fixed (no brilliant ideas right away)...
150 * Overview:: An introduction to CVS
151 * Repository:: Where all your sources are stored
152 * Starting a new project:: Starting a project with CVS
153 * Revisions:: Numeric and symbolic names for revisions
154 * Branching and merging:: Diverging/rejoining branches of development
155 * Recursive behavior:: CVS descends directories
156 * Adding and removing:: Adding/removing/renaming files/directories
157 * History browsing:: Viewing the history of files in various ways
159 CVS and the Real World.
160 -----------------------
161 * Binary files:: CVS can handle binary files
162 * Multiple developers:: How CVS helps a group of developers
163 * Revision management:: Policy questions for revision management
164 * Keyword substitution:: CVS can include the revision inside the file
165 * Tracking sources:: Tracking third-party sources
166 * Builds:: Issues related to CVS and builds
167 * Special Files:: Devices, links and other non-regular files
171 * CVS commands:: CVS commands share some things
172 * Invoking CVS:: Quick reference to CVS commands
173 * Administrative files:: Reference manual for the Administrative files
174 * Environment variables:: All environment variables which affect CVS
175 * Compatibility:: Upgrading CVS versions
176 * Troubleshooting:: Some tips when nothing works
177 * Credits:: Some of the contributors to this manual
178 * BUGS:: Dealing with bugs in CVS or this manual
182 @c ---------------------------------------------------------------------
187 This chapter is for people who have never used
188 @sc{cvs}, and perhaps have never used version control
191 If you are already familiar with @sc{cvs} and are just
192 trying to learn a particular feature or remember a
193 certain command, you can probably skip everything here.
196 * What is CVS?:: What you can do with @sc{cvs}
197 * What is CVS not?:: Problems @sc{cvs} doesn't try to solve
198 * A sample session:: A tour of basic @sc{cvs} usage
201 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
203 @section What is CVS?
205 @cindex Introduction to CVS
206 @cindex CVS, introduction to
208 @sc{cvs} is a version control system. Using it, you can
209 record the history of your source files.
212 @c -- ///Those who cannot remember the past are condemned to repeat it.
213 @c -- /// -- George Santayana
216 @c -- Insert history quote here!
217 For example, bugs sometimes creep in when
218 software is modified, and you might not detect the bug
219 until a long time after you make the modification.
220 With @sc{cvs}, you can easily retrieve old versions to see
221 exactly which change caused the bug. This can
222 sometimes be a big help.
224 You could of course save every version of every file
225 you have ever created. This would
226 however waste an enormous amount of disk space. @sc{cvs}
227 stores all the versions of a file in a single file in a
228 clever way that only stores the differences between
231 @sc{cvs} also helps you if you are part of a group of people working
232 on the same project. It is all too easy to overwrite
233 each others' changes unless you are extremely careful.
234 Some editors, like @sc{gnu} Emacs, try to make sure that
235 the same file is never modified by two people at the
236 same time. Unfortunately, if someone is using another
237 editor, that safeguard will not work. @sc{cvs} solves this problem
238 by insulating the different developers from each other. Every
239 developer works in his own directory, and @sc{cvs} merges
240 the work when each developer is done.
242 @cindex History of CVS
243 @cindex CVS, history of
244 @cindex Credits (CVS program)
245 @cindex Contributors (CVS program)
246 @sc{cvs} started out as a bunch of shell scripts written by
247 Dick Grune, posted to the newsgroup
248 @code{comp.sources.unix} in the volume 6
249 release of July, 1986. While no actual code from
250 these shell scripts is present in the current version
251 of @sc{cvs} much of the @sc{cvs} conflict resolution algorithms
254 In April, 1989, Brian Berliner designed and coded @sc{cvs}.
255 Jeff Polk later helped Brian with the design of the @sc{cvs}
256 module and vendor branch support.
258 @cindex Source, getting CVS source
259 You can get @sc{cvs} in a variety of ways, including
260 free download from the Internet. For more information
261 on downloading @sc{cvs} and other @sc{cvs} topics, see:
264 @url{http://www.cvshome.org/}
268 @cindex List, mailing list
270 There is a mailing list, known as @email{info-cvs@@gnu.org},
271 devoted to @sc{cvs}. To subscribe or
274 @email{info-cvs-request@@gnu.org}.
275 If you prefer a Usenet group, there is a one-way mirror (posts to the email
276 list are usually sent to the news group, but not visa versa) of
277 @email{info-cvs@@gnu.org} at @url{news:gnu.cvs.help}. The right
278 Usenet group for posts is @url{news:comp.software.config-mgmt} which is for
279 @sc{cvs} discussions (along with other configuration
280 management systems). In the future, it might be
282 @code{comp.software.config-mgmt.cvs}, but probably only
283 if there is sufficient @sc{cvs} traffic on
284 @url{news:comp.software.config-mgmt}.
285 @c Other random data is that the tale was very
286 @c skeptical of comp.software.config-mgmt.cvs when the
287 @c subject came up around 1995 or so (for one
288 @c thing, because creating it would be a "reorg" which
289 @c would need to take a more comprehensive look at the
290 @c whole comp.software.config-mgmt.* hierarchy).
292 You can also subscribe to the @email{bug-cvs@@gnu.org} mailing list,
293 described in more detail in @ref{BUGS}. To subscribe
294 send mail to @email{bug-cvs-request@@gnu.org}. There is a two-way
295 Usenet mirror (posts to the Usenet group are usually sent to the email list and
296 visa versa) of @email{bug-cvs@@gnu.org} named @url{news:gnu.cvs.bug}.
298 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
299 @node What is CVS not?
300 @section What is CVS not?
301 @cindex What is CVS not?
303 @sc{cvs} can do a lot of things for you, but it does
304 not try to be everything for everyone.
307 @item @sc{cvs} is not a build system.
309 Though the structure of your repository and modules
310 file interact with your build system
311 (e.g. @file{Makefile}s), they are essentially
314 @sc{cvs} does not dictate how you build anything. It
315 merely stores files for retrieval in a tree structure
318 @sc{cvs} does not dictate how to use disk space in the
319 checked out working directories. If you write your
320 @file{Makefile}s or scripts in every directory so they
321 have to know the relative positions of everything else,
322 you wind up requiring the entire repository to be
325 If you modularize your work, and construct a build
326 system that will share files (via links, mounts,
327 @code{VPATH} in @file{Makefile}s, etc.), you can
328 arrange your disk usage however you like.
330 But you have to remember that @emph{any} such system is
331 a lot of work to construct and maintain. @sc{cvs} does
332 not address the issues involved.
334 Of course, you should place the tools created to
335 support such a build system (scripts, @file{Makefile}s,
338 Figuring out what files need to be rebuilt when
339 something changes is, again, something to be handled
340 outside the scope of @sc{cvs}. One traditional
341 approach is to use @code{make} for building, and use
342 some automated tool for generating the dependencies which
345 See @ref{Builds}, for more information on doing builds
346 in conjunction with @sc{cvs}.
348 @item @sc{cvs} is not a substitute for management.
350 Your managers and project leaders are expected to talk
351 to you frequently enough to make certain you are aware
352 of schedules, merge points, branch names and release
353 dates. If they don't, @sc{cvs} can't help.
355 @sc{cvs} is an instrument for making sources dance to
356 your tune. But you are the piper and the composer. No
357 instrument plays itself or writes its own music.
359 @item @sc{cvs} is not a substitute for developer communication.
361 When faced with conflicts within a single file, most
362 developers manage to resolve them without too much
363 effort. But a more general definition of ``conflict''
364 includes problems too difficult to solve without
365 communication between developers.
367 @sc{cvs} cannot determine when simultaneous changes
368 within a single file, or across a whole collection of
369 files, will logically conflict with one another. Its
370 concept of a @dfn{conflict} is purely textual, arising
371 when two changes to the same base file are near enough
372 to spook the merge (i.e. @code{diff3}) command.
374 @sc{cvs} does not claim to help at all in figuring out
375 non-textual or distributed conflicts in program logic.
377 For example: Say you change the arguments to function
378 @code{X} defined in file @file{A}. At the same time,
379 someone edits file @file{B}, adding new calls to
380 function @code{X} using the old arguments. You are
381 outside the realm of @sc{cvs}'s competence.
383 Acquire the habit of reading specs and talking to your
387 @item @sc{cvs} does not have change control
389 Change control refers to a number of things. First of
390 all it can mean @dfn{bug-tracking}, that is being able
391 to keep a database of reported bugs and the status of
392 each one (is it fixed? in what release? has the bug
393 submitter agreed that it is fixed?). For interfacing
394 @sc{cvs} to an external bug-tracking system, see the
395 @file{rcsinfo} and @file{verifymsg} files
396 (@pxref{Administrative files}).
398 Another aspect of change control is keeping track of
399 the fact that changes to several files were in fact
400 changed together as one logical change. If you check
401 in several files in a single @code{cvs commit}
402 operation, @sc{cvs} then forgets that those files were
403 checked in together, and the fact that they have the
404 same log message is the only thing tying them
405 together. Keeping a @sc{gnu} style @file{ChangeLog}
407 @c FIXME: should have an xref to a section which talks
408 @c more about keeping ChangeLog's with CVS, but that
409 @c section hasn't been written yet.
411 Another aspect of change control, in some systems, is
412 the ability to keep track of the status of each
413 change. Some changes have been written by a developer,
414 others have been reviewed by a second developer, and so
415 on. Generally, the way to do this with @sc{cvs} is to
416 generate a diff (using @code{cvs diff} or @code{diff})
417 and email it to someone who can then apply it using the
418 @code{patch} utility. This is very flexible, but
419 depends on mechanisms outside @sc{cvs} to make sure
420 nothing falls through the cracks.
422 @item @sc{cvs} is not an automated testing program
424 It should be possible to enforce mandatory use of a
425 test suite using the @code{commitinfo} file. I haven't
426 heard a lot about projects trying to do that or whether
427 there are subtle gotchas, however.
429 @item @sc{cvs} does not have a built-in process model
431 Some systems provide ways to ensure that changes or
432 releases go through various steps, with various
433 approvals as needed. Generally, one can accomplish
434 this with @sc{cvs} but it might be a little more work.
435 In some cases you'll want to use the @file{commitinfo},
436 @file{loginfo}, @file{rcsinfo}, or @file{verifymsg}
437 files, to require that certain steps be performed
438 before cvs will allow a checkin. Also consider whether
439 features such as branches and tags can be used to
440 perform tasks such as doing work in a development tree
441 and then merging certain changes over to a stable tree
442 only once they have been proven.
445 @c ---------------------------------------------------------------------
446 @node A sample session
447 @section A sample session
448 @cindex Example of a work-session
449 @cindex Getting started
450 @cindex Work-session, example of
451 @cindex tc, Trivial Compiler (example)
452 @cindex Trivial Compiler (example)
454 @c I think an example is a pretty good way to start. But
455 @c somewhere in here, maybe after the sample session,
456 @c we need something which is kind of
457 @c a "roadmap" which is more directed at sketching out
458 @c the functionality of CVS and pointing people to
459 @c various other parts of the manual. As it stands now
460 @c people who read in order get dumped right into all
461 @c manner of hair regarding remote repositories,
462 @c creating a repository, etc.
464 @c The following was in the old Basic concepts node. I don't
465 @c know how good a job it does at introducing modules,
466 @c or whether they need to be introduced so soon, but
467 @c something of this sort might go into some
468 @c introductory material somewhere.
470 @cindex Modules (intro)
471 The repository contains directories and files, in an
472 arbitrary tree. The @dfn{modules} feature can be used
473 to group together a set of directories or files into a
474 single entity (@pxref{modules}). A typical usage is to
475 define one module per project.
478 As a way of introducing @sc{cvs}, we'll go through a
479 typical work-session using @sc{cvs}. The first thing
480 to understand is that @sc{cvs} stores all files in a
481 centralized @dfn{repository} (@pxref{Repository}); this
482 section assumes that a repository is set up.
483 @c I'm not sure that the sentence concerning the
484 @c repository quite tells the user what they need to
485 @c know at this point. Might need to expand on "centralized"
486 @c slightly (maybe not here, maybe further down in the example?)
488 Suppose you are working on a simple compiler. The source
489 consists of a handful of C files and a @file{Makefile}.
490 The compiler is called @samp{tc} (Trivial Compiler),
491 and the repository is set up so that there is a module
495 * Getting the source:: Creating a workspace
496 * Committing your changes:: Making your work available to others
497 * Cleaning up:: Cleaning up
498 * Viewing differences:: Viewing differences
501 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
502 @node Getting the source
503 @subsection Getting the source
504 @cindex Getting the source
505 @cindex Checking out source
506 @cindex Fetching source
507 @cindex Source, getting from CVS
508 @cindex Checkout, example
510 The first thing you must do is to get your own working copy of the
511 source for @samp{tc}. For this, you use the @code{checkout} command:
518 This will create a new directory called @file{tc} and populate it with
524 CVS Makefile backend.c driver.c frontend.c parser.c
527 The @file{CVS} directory is used internally by
528 @sc{cvs}. Normally, you should not modify or remove
529 any of the files in it.
531 You start your favorite editor, hack away at @file{backend.c}, and a couple
532 of hours later you have added an optimization pass to the compiler.
533 A note to @sc{rcs} and @sc{sccs} users: There is no need to lock the files that
534 you want to edit. @xref{Multiple developers}, for an explanation.
536 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
537 @node Committing your changes
538 @subsection Committing your changes
539 @cindex Committing changes to files
540 @cindex Log message entry
542 When you have checked that the compiler is still compilable you decide
543 to make a new version of @file{backend.c}. This will
544 store your new @file{backend.c} in the repository and
545 make it available to anyone else who is using that same
549 $ cvs commit backend.c
553 @sc{cvs} starts an editor, to allow you to enter a log
554 message. You type in ``Added an optimization pass.'',
555 save the temporary file, and exit the editor.
557 @cindex CVSEDITOR, environment variable
558 @cindex EDITOR, environment variable
559 The environment variable @code{$CVSEDITOR} determines
560 which editor is started. If @code{$CVSEDITOR} is not
561 set, then if the environment variable @code{$EDITOR} is
562 set, it will be used. If both @code{$CVSEDITOR} and
563 @code{$EDITOR} are not set then there is a default
564 which will vary with your operating system, for example
565 @code{vi} for unix or @code{notepad} for Windows
568 @cindex VISUAL, environment variable
569 In addition, @sc{cvs} checks the @code{$VISUAL} environment
570 variable. Opinions vary on whether this behavior is desirable and
571 whether future releases of @sc{cvs} should check @code{$VISUAL} or
572 ignore it. You will be OK either way if you make sure that
573 @code{$VISUAL} is either unset or set to the same thing as
576 @c This probably should go into some new node
577 @c containing detailed info on the editor, rather than
578 @c the intro. In fact, perhaps some of the stuff with
579 @c CVSEDITOR and -m and so on should too.
580 When @sc{cvs} starts the editor, it includes a list of
581 files which are modified. For the @sc{cvs} client,
582 this list is based on comparing the modification time
583 of the file against the modification time that the file
584 had when it was last gotten or updated. Therefore, if
585 a file's modification time has changed but its contents
586 have not, it will show up as modified. The simplest
587 way to handle this is simply not to worry about it---if
588 you proceed with the commit @sc{cvs} will detect that
589 the contents are not modified and treat it as an
590 unmodified file. The next @code{update} will clue
591 @sc{cvs} in to the fact that the file is unmodified,
592 and it will reset its stored timestamp so that the file
593 will not show up in future editor sessions.
594 @c FIXCVS: Might be nice if "commit" and other commands
595 @c would reset that timestamp too, but currently commit
597 @c FIXME: Need to talk more about the process of
598 @c prompting for the log message. Like show an example
599 @c of what it pops up in the editor, for example. Also
600 @c a discussion of how to get the "a)bort, c)ontinue,
601 @c e)dit" prompt and what to do with it. Might also
602 @c work in the suggestion that if you want a diff, you
603 @c should make it before running commit (someone
604 @c suggested that the diff pop up in the editor. I'm
605 @c not sure that is better than telling people to run
606 @c "cvs diff" first if that is what they want, but if
607 @c we want to tell people that, the manual possibly
611 starting an editor you can specify the log message on
612 the command line using the @samp{-m} flag instead, like
616 $ cvs commit -m "Added an optimization pass" backend.c
619 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
621 @subsection Cleaning up
623 @cindex Working copy, removing
624 @cindex Removing your working copy
625 @cindex Releasing your working copy
627 Before you turn to other tasks you decide to remove your working copy of
628 tc. One acceptable way to do that is of course
636 but a better way is to use the @code{release} command (@pxref{release}):
643 You have [1] altered files in this repository.
644 Are you sure you want to release (and delete) directory `tc': n
645 ** `release' aborted by user choice.
648 The @code{release} command checks that all your modifications have been
649 committed. If history logging is enabled it also makes a note in the
650 history file. @xref{history file}.
652 When you use the @samp{-d} flag with @code{release}, it
653 also removes your working copy.
655 In the example above, the @code{release} command wrote a couple of lines
656 of output. @samp{? tc} means that the file @file{tc} is unknown to @sc{cvs}.
657 That is nothing to worry about: @file{tc} is the executable compiler,
658 and it should not be stored in the repository. @xref{cvsignore},
659 for information about how to make that warning go away.
660 @xref{release output}, for a complete explanation of
661 all possible output from @code{release}.
663 @samp{M driver.c} is more serious. It means that the
664 file @file{driver.c} has been modified since it was
667 The @code{release} command always finishes by telling
668 you how many modified files you have in your working
669 copy of the sources, and then asks you for confirmation
670 before deleting any files or making any note in the
673 You decide to play it safe and answer @kbd{n @key{RET}}
674 when @code{release} asks for confirmation.
676 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
677 @node Viewing differences
678 @subsection Viewing differences
679 @cindex Viewing differences
682 You do not remember modifying @file{driver.c}, so you want to see what
683 has happened to that file.
690 This command runs @code{diff} to compare the version of @file{driver.c}
691 that you checked out with your working copy. When you see the output
692 you remember that you added a command line option that enabled the
693 optimization pass. You check it in, and release the module.
694 @c FIXME: we haven't yet defined the term "check in".
697 $ cvs commit -m "Added an optimization pass" driver.c
698 Checking in driver.c;
699 /usr/local/cvsroot/tc/driver.c,v <-- driver.c
700 new revision: 1.2; previous revision: 1.1
705 You have [0] altered files in this repository.
706 Are you sure you want to release (and delete) directory `tc': y
709 @c ---------------------------------------------------------------------
711 @chapter The Repository
712 @cindex Repository (intro)
713 @cindex Repository, example
714 @cindex Layout of repository
715 @cindex Typical repository
716 @cindex /usr/local/cvsroot, as example repository
719 The @sc{cvs} @dfn{repository} stores a complete copy of
720 all the files and directories which are under version
723 Normally, you never access any of the files in the
724 repository directly. Instead, you use @sc{cvs}
725 commands to get your own copy of the files into a
726 @dfn{working directory}, and then
727 work on that copy. When you've finished a set of
728 changes, you check (or @dfn{commit}) them back into the
729 repository. The repository then contains the changes
730 which you have made, as well as recording exactly what
731 you changed, when you changed it, and other such
732 information. Note that the repository is not a
733 subdirectory of the working directory, or vice versa;
734 they should be in separate locations.
735 @c Need some example, e.g. repository
736 @c /usr/local/cvsroot; working directory
737 @c /home/joe/sources. But this node is too long
738 @c as it is; need a little reorganization...
740 @cindex :local:, setting up
741 @sc{cvs} can access a repository by a variety of
742 means. It might be on the local computer, or it might
743 be on a computer across the room or across the world.
744 To distinguish various ways to access a repository, the
745 repository name can start with an @dfn{access method}.
746 For example, the access method @code{:local:} means to
747 access a repository directory, so the repository
748 @code{:local:/usr/local/cvsroot} means that the
749 repository is in @file{/usr/local/cvsroot} on the
750 computer running @sc{cvs}. For information on other
751 access methods, see @ref{Remote repositories}.
753 @c Can se say this more concisely? Like by passing
754 @c more of the buck to the Remote repositories node?
755 If the access method is omitted, then if the repository
756 starts with @samp{/}, then @code{:local:} is
757 assumed. If it does not start with @samp{/} then either
758 @code{:ext:} or @code{:server:} is assumed. For
759 example, if you have a local repository in
760 @file{/usr/local/cvsroot}, you can use
761 @code{/usr/local/cvsroot} instead of
762 @code{:local:/usr/local/cvsroot}. But if (under
763 Windows NT, for example) your local repository is
764 @file{c:\src\cvsroot}, then you must specify the access
765 method, as in @code{:local:c:/src/cvsroot}.
767 @c This might appear to go in Repository storage, but
768 @c actually it is describing something which is quite
769 @c user-visible, when you do a "cvs co CVSROOT". This
770 @c isn't necessary the perfect place for that, though.
771 The repository is split in two parts. @file{$CVSROOT/CVSROOT} contains
772 administrative files for @sc{cvs}. The other directories contain the actual
773 user-defined modules.
776 * Specifying a repository:: Telling CVS where your repository is
777 * Repository storage:: The structure of the repository
778 * Working directory storage:: The structure of working directories
779 * Intro administrative files:: Defining modules
780 * Multiple repositories:: Multiple repositories
781 * Creating a repository:: Creating a repository
782 * Backing up:: Backing up a repository
783 * Moving a repository:: Moving a repository
784 * Remote repositories:: Accessing repositories on remote machines
785 * Read-only access:: Granting read-only access to the repository
786 * Server temporary directory:: The server creates temporary directories
789 @node Specifying a repository
790 @section Telling CVS where your repository is
792 There are several ways to tell @sc{cvs}
793 where to find the repository. You can name the
794 repository on the command line explicitly, with the
795 @code{-d} (for "directory") option:
798 cvs -d /usr/local/cvsroot checkout yoyodyne/tc
801 @cindex .profile, setting CVSROOT in
802 @cindex .cshrc, setting CVSROOT in
803 @cindex .tcshrc, setting CVSROOT in
804 @cindex .bashrc, setting CVSROOT in
805 @cindex CVSROOT, environment variable
806 Or you can set the @code{$CVSROOT} environment
807 variable to an absolute path to the root of the
808 repository, @file{/usr/local/cvsroot} in this example.
809 To set @code{$CVSROOT}, @code{csh} and @code{tcsh}
810 users should have this line in their @file{.cshrc} or
811 @file{.tcshrc} files:
814 setenv CVSROOT /usr/local/cvsroot
818 @code{sh} and @code{bash} users should instead have these lines in their
819 @file{.profile} or @file{.bashrc}:
822 CVSROOT=/usr/local/cvsroot
826 @cindex Root file, in CVS directory
827 @cindex CVS/Root file
828 A repository specified with @code{-d} will
829 override the @code{$CVSROOT} environment variable.
830 Once you've checked a working copy out from the
831 repository, it will remember where its repository is
832 (the information is recorded in the
833 @file{CVS/Root} file in the working copy).
835 The @code{-d} option and the @file{CVS/Root} file both
836 override the @code{$CVSROOT} environment variable. If
837 @code{-d} option differs from @file{CVS/Root}, the
838 former is used. Of course, for proper operation they
839 should be two ways of referring to the same repository.
841 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
842 @node Repository storage
843 @section How data is stored in the repository
844 @cindex Repository, how data is stored
846 For most purposes it isn't important @emph{how}
847 @sc{cvs} stores information in the repository. In
848 fact, the format has changed in the past, and is likely
849 to change in the future. Since in almost all cases one
850 accesses the repository via @sc{cvs} commands, such
851 changes need not be disruptive.
853 However, in some cases it may be necessary to
854 understand how @sc{cvs} stores data in the repository,
855 for example you might need to track down @sc{cvs} locks
856 (@pxref{Concurrency}) or you might need to deal with
857 the file permissions appropriate for the repository.
860 * Repository files:: What files are stored in the repository
861 * File permissions:: File permissions
862 * Windows permissions:: Issues specific to Windows
863 * Attic:: Some files are stored in the Attic
864 * CVS in repository:: Additional information in CVS directory
865 * Locks:: CVS locks control concurrent accesses
866 * CVSROOT storage:: A few things about CVSROOT are different
869 @node Repository files
870 @subsection Where files are stored within the repository
872 @c @cindex Filenames, legal
873 @c @cindex Legal filenames
874 @c Somewhere we need to say something about legitimate
875 @c characters in filenames in working directory and
876 @c repository. Not "/" (not even on non-unix). And
877 @c here is a specific set of issues:
878 @c Files starting with a - are handled inconsistently. They can not
879 @c be added to a repository with an add command, because it they are
880 @c interpreted as a switch. They can appear in a repository if they are
881 @c part of a tree that is imported. They can not be removed from the tree
882 @c once they are there.
883 @c Note that "--" *is* supported (as a
884 @c consequence of using GNU getopt). Should document
885 @c this somewhere ("Common options"?). The other usual technique,
886 @c "./-foo", isn't as effective, at least for "cvs add"
887 @c which doesn't support pathnames containing "/".
889 The overall structure of the repository is a directory
890 tree corresponding to the directories in the working
891 directory. For example, supposing the repository is in
898 here is a possible directory tree (showing only the
909 | (administrative files)
914 | | (source code to @sc{gnu} diff)
917 | | (source code to @sc{rcs})
920 | (source code to @sc{cvs})
930 +--(other Yoyodyne software)
933 With the directories are @dfn{history files} for each file
934 under version control. The name of the history file is
935 the name of the corresponding file with @samp{,v}
936 appended to the end. Here is what the repository for
937 the @file{yoyodyne/tc} directory might look like:
938 @c FIXME: Should also mention CVS (CVSREP)
939 @c FIXME? Should we introduce Attic with an xref to
940 @c Attic? Not sure whether that is a good idea or not.
963 @cindex History files
964 @cindex RCS history files
965 @c The first sentence, about what history files
966 @c contain, is kind of redundant with our intro to what the
967 @c repository does in node Repository....
968 The history files contain, among other things, enough
969 information to recreate any revision of the file, a log
970 of all commit messages and the user-name of the person
971 who committed the revision. The history files are
972 known as @dfn{RCS files}, because the first program to
973 store files in that format was a version control system
974 known as @sc{rcs}. For a full
975 description of the file format, see the @code{man} page
976 @cite{rcsfile(5)}, distributed with @sc{rcs}, or the
977 file @file{doc/RCSFILES} in the @sc{cvs} source
979 file format has become very common---many systems other
980 than @sc{cvs} or @sc{rcs} can at least import history
981 files in this format.
982 @c FIXME: Think about including documentation for this
983 @c rather than citing it? In the long run, getting
984 @c this to be a standard (not sure if we can cope with
985 @c a standards process as formal as IEEE/ANSI/ISO/etc,
986 @c though...) is the way to go, so maybe citing is
989 The @sc{rcs} files used in @sc{cvs} differ in a few
990 ways from the standard format. The biggest difference
991 is magic branches; for more information see @ref{Magic
992 branch numbers}. Also in @sc{cvs} the valid tag names
993 are a subset of what @sc{rcs} accepts; for @sc{cvs}'s
994 rules see @ref{Tags}.
996 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
997 @node File permissions
998 @subsection File permissions
999 @c -- Move this to @node Creating a repository or similar
1000 @cindex Security, file permissions in repository
1001 @cindex File permissions, general
1002 @cindex Permissions, general
1003 @c FIXME: we need to somehow reflect "permissions in
1004 @c repository" versus "permissions in working
1005 @c directory" in the index entries.
1006 @cindex Group, UNIX file permissions, in repository
1007 @cindex Read-only files, in repository
1008 All @samp{,v} files are created read-only, and you
1009 should not change the permission of those files. The
1010 directories inside the repository should be writable by
1011 the persons that have permission to modify the files in
1012 each directory. This normally means that you must
1013 create a UNIX group (see group(5)) consisting of the
1014 persons that are to edit the files in a project, and
1015 set up the repository so that it is that group that
1017 (On some systems, you also need to set the set-group-ID-on-execution bit
1018 on the repository directories (see chmod(1)) so that newly-created files
1019 and directories get the group-ID of the parent directory rather than
1020 that of the current process.)
1022 @c See also comment in commitinfo node regarding cases
1023 @c which are really awkward with unix groups.
1025 This means that you can only control access to files on
1026 a per-directory basis.
1028 Note that users must also have write access to check
1029 out files, because @sc{cvs} needs to create lock files
1030 (@pxref{Concurrency}). You can use LockDir in CVSROOT/config
1031 to put the lock files somewhere other than in the repository
1032 if you want to allow read-only access to some directories
1035 @c CVS seems to use CVSUMASK in picking permissions for
1036 @c val-tags, but maybe we should say more about this.
1037 @c Like val-tags gets created by someone who doesn't
1038 @c have CVSUMASK set right?
1039 @cindex CVSROOT/val-tags file, and read-only access to projects
1040 @cindex val-tags file, and read-only access to projects
1041 Also note that users must have write access to the
1042 @file{CVSROOT/val-tags} file. @sc{cvs} uses it to keep
1043 track of what tags are valid tag names (it is sometimes
1044 updated when tags are used, as well as when they are
1047 Each @sc{rcs} file will be owned by the user who last
1048 checked it in. This has little significance; what
1049 really matters is who owns the directories.
1051 @cindex CVSUMASK, environment variable
1052 @cindex Umask, for repository files
1053 @sc{cvs} tries to set up reasonable file permissions
1054 for new directories that are added inside the tree, but
1055 you must fix the permissions manually when a new
1056 directory should have different permissions than its
1057 parent directory. If you set the @code{CVSUMASK}
1058 environment variable that will control the file
1059 permissions which @sc{cvs} uses in creating directories
1060 and/or files in the repository. @code{CVSUMASK} does
1061 not affect the file permissions in the working
1062 directory; such files have the permissions which are
1063 typical for newly created files, except that sometimes
1064 @sc{cvs} creates them read-only (see the sections on
1065 watches, @ref{Setting a watch}; -r, @ref{Global
1066 options}; or @code{CVSREAD}, @ref{Environment variables}).
1067 @c FIXME: Need more discussion of which
1068 @c group should own the file in the repository.
1069 @c Include a somewhat detailed example of the usual
1070 @c case where CVSUMASK is 007, the developers are all
1071 @c in a group, and that group owns stuff in the
1072 @c repository. Need to talk about group ownership of
1073 @c newly-created directories/files (on some unices,
1074 @c such as SunOS4, setting the setgid bit on the
1075 @c directories will make files inherit the directory's
1076 @c group. On other unices, your mileage may vary. I
1077 @c can't remember what POSIX says about this, if
1080 Note that using the client/server @sc{cvs}
1081 (@pxref{Remote repositories}), there is no good way to
1082 set @code{CVSUMASK}; the setting on the client machine
1083 has no effect. If you are connecting with @code{rsh}, you
1084 can set @code{CVSUMASK} in @file{.bashrc} or @file{.cshrc}, as
1085 described in the documentation for your operating
1086 system. This behavior might change in future versions
1087 of @sc{cvs}; do not rely on the setting of
1088 @code{CVSUMASK} on the client having no effect.
1089 @c FIXME: need to explain what a umask is or cite
1090 @c someplace which does.
1092 @c There is also a larger (largely separate) issue
1093 @c about the meaning of CVSUMASK in a non-unix context.
1094 @c For example, whether there is
1095 @c an equivalent which fits better into other
1096 @c protection schemes like POSIX.6, VMS, &c.
1098 @c FIXME: Need one place which discusses this
1099 @c read-only files thing. Why would one use -r or
1100 @c CVSREAD? Why would one use watches? How do they
1103 @c FIXME: We need to state
1104 @c whether using CVSUMASK removes the need for manually
1105 @c fixing permissions (in fact, if we are going to mention
1106 @c manually fixing permission, we better document a lot
1107 @c better just what we mean by "fix").
1109 Using pserver, you will generally need stricter
1110 permissions on the @sc{cvsroot} directory and
1111 directories above it in the tree; see @ref{Password
1112 authentication security}.
1116 @cindex Security, setuid
1117 @cindex Installed images (VMS)
1118 Some operating systems have features which allow a
1119 particular program to run with the ability to perform
1120 operations which the caller of the program could not.
1121 For example, the set user ID (setuid) or set group ID
1122 (setgid) features of unix or the installed image
1123 feature of VMS. @sc{cvs} was not written to use such
1124 features and therefore attempting to install @sc{cvs} in
1125 this fashion will provide protection against only
1126 accidental lapses; anyone who is trying to circumvent
1127 the measure will be able to do so, and depending on how
1128 you have set it up may gain access to more than just
1129 @sc{cvs}. You may wish to instead consider pserver. It
1130 shares some of the same attributes, in terms of
1131 possibly providing a false sense of security or opening
1132 security holes wider than the ones you are trying to
1133 fix, so read the documentation on pserver security
1134 carefully if you are considering this option
1135 (@ref{Password authentication security}).
1137 @node Windows permissions
1138 @subsection File Permission issues specific to Windows
1139 @cindex Windows, and permissions
1140 @cindex File permissions, Windows-specific
1141 @cindex Permissions, Windows-specific
1143 Some file permission issues are specific to Windows
1144 operating systems (Windows 95, Windows NT, and
1145 presumably future operating systems in this family.
1146 Some of the following might apply to OS/2 but I'm not
1149 If you are using local @sc{cvs} and the repository is on a
1150 networked file system which is served by the Samba SMB
1151 server, some people have reported problems with
1152 permissions. Enabling WRITE=YES in the samba
1153 configuration is said to fix/workaround it.
1154 Disclaimer: I haven't investigated enough to know the
1155 implications of enabling that option, nor do I know
1156 whether there is something which @sc{cvs} could be doing
1157 differently in order to avoid the problem. If you find
1158 something out, please let us know as described in
1162 @subsection The attic
1165 You will notice that sometimes @sc{cvs} stores an
1166 @sc{rcs} file in the @code{Attic}. For example, if the
1167 @sc{cvsroot} is @file{/usr/local/cvsroot} and we are
1168 talking about the file @file{backend.c} in the
1169 directory @file{yoyodyne/tc}, then the file normally
1173 /usr/local/cvsroot/yoyodyne/tc/backend.c,v
1177 but if it goes in the attic, it would be in
1180 /usr/local/cvsroot/yoyodyne/tc/Attic/backend.c,v
1185 instead. It should not matter from a user point of
1186 view whether a file is in the attic; @sc{cvs} keeps
1187 track of this and looks in the attic when it needs to.
1188 But in case you want to know, the rule is that the RCS
1189 file is stored in the attic if and only if the head
1190 revision on the trunk has state @code{dead}. A
1191 @code{dead} state means that file has been removed, or
1192 never added, for that revision. For example, if you
1193 add a file on a branch, it will have a trunk revision
1194 in @code{dead} state, and a branch revision in a
1195 non-@code{dead} state.
1196 @c Probably should have some more concrete examples
1197 @c here, or somewhere (not sure exactly how we should
1198 @c arrange the discussion of the dead state, versus
1199 @c discussion of the attic).
1201 @node CVS in repository
1202 @subsection The CVS directory in the repository
1203 @cindex CVS directory, in repository
1205 The @file{CVS} directory in each repository directory
1206 contains information such as file attributes (in a file
1207 called @file{CVS/fileattr}. In the
1208 future additional files may be added to this directory,
1209 so implementations should silently ignore additional
1212 This behavior is implemented only by @sc{cvs} 1.7 and
1213 later; for details see @ref{Watches Compatibility}.
1215 The format of the @file{fileattr} file is a series of entries
1216 of the following form (where @samp{@{} and @samp{@}}
1217 means the text between the braces can be repeated zero
1220 @var{ent-type} @var{filename} <tab> @var{attrname} = @var{attrval}
1221 @{; @var{attrname} = @var{attrval}@} <linefeed>
1223 @var{ent-type} is @samp{F} for a file, in which case the entry specifies the
1224 attributes for that file.
1226 @var{ent-type} is @samp{D},
1227 and @var{filename} empty, to specify default attributes
1228 to be used for newly added files.
1230 Other @var{ent-type} are reserved for future expansion. @sc{cvs} 1.9 and older
1231 will delete them any time it writes file attributes.
1232 @sc{cvs} 1.10 and later will preserve them.
1234 Note that the order of the lines is not significant;
1235 a program writing the fileattr file may
1236 rearrange them at its convenience.
1238 There is currently no way of quoting tabs or line feeds in the
1239 filename, @samp{=} in @var{attrname},
1240 @samp{;} in @var{attrval}, etc. Note: some implementations also
1241 don't handle a NUL character in any of the fields, but
1242 implementations are encouraged to allow it.
1244 By convention, @var{attrname} starting with @samp{_} is for an attribute given
1245 special meaning by @sc{cvs}; other @var{attrname}s are for user-defined attributes
1246 (or will be, once implementations start supporting user-defined attributes).
1248 Built-in attributes:
1252 Present means the file is watched and should be checked out
1256 Users with watches for this file. Value is
1257 @var{watcher} > @var{type} @{ , @var{watcher} > @var{type} @}
1258 where @var{watcher} is a username, and @var{type}
1259 is zero or more of edit,unedit,commit separated by
1260 @samp{+} (that is, nothing if none; there is no "none" or "all" keyword).
1263 Users editing this file. Value is
1264 @var{editor} > @var{val} @{ , @var{editor} > @var{val} @}
1265 where @var{editor} is a username, and @var{val} is
1266 @var{time}+@var{hostname}+@var{pathname}, where
1267 @var{time} is when the @code{cvs edit} command (or
1268 equivalent) happened,
1269 and @var{hostname} and @var{pathname} are for the working directory.
1274 @c FIXME: sanity.sh should contain a similar test case
1275 @c so we can compare this example from something from
1276 @c Real Life(TM). See cvsclient.texi (under Notify) for more
1277 @c discussion of the date format of _editors.
1279 Ffile1 _watched=;_watchers=joe>edit,mary>commit
1280 Ffile2 _watched=;_editors=sue>8 Jan 1975+workstn1+/home/sue/cvs
1285 means that the file @file{file1} should be checked out
1286 read-only. Furthermore, joe is watching for edits and
1287 mary is watching for commits. The file @file{file2}
1288 should be checked out read-only; sue started editing it
1289 on 8 Jan 1975 in the directory @file{/home/sue/cvs} on
1290 the machine @code{workstn1}. Future files which are
1291 added should be checked out read-only. To represent
1292 this example here, we have shown a space after
1293 @samp{D}, @samp{Ffile1}, and @samp{Ffile2}, but in fact
1294 there must be a single tab character there and no spaces.
1297 @subsection CVS locks in the repository
1299 @cindex #cvs.rfl, technical details
1300 @cindex #cvs.pfl, technical details
1301 @cindex #cvs.wfl, technical details
1302 @cindex #cvs.lock, technical details
1303 @cindex Locks, cvs, technical details
1304 For an introduction to @sc{cvs} locks focusing on
1305 user-visible behavior, see @ref{Concurrency}. The
1306 following section is aimed at people who are writing
1307 tools which want to access a @sc{cvs} repository without
1308 interfering with other tools accessing the same
1309 repository. If you find yourself confused by concepts
1310 described here, like @dfn{read lock}, @dfn{write lock},
1311 and @dfn{deadlock}, you might consult the literature on
1312 operating systems or databases.
1315 Any file in the repository with a name starting
1316 with @file{#cvs.rfl.} is a read lock. Any file in
1317 the repository with a name starting with
1318 @file{#cvs.pfl} is a promotable read lock. Any file in
1319 the repository with a name starting with
1320 @file{#cvs.wfl} is a write lock. Old versions of @sc{cvs}
1321 (before @sc{cvs} 1.5) also created files with names starting
1322 with @file{#cvs.tfl}, but they are not discussed here.
1323 The directory @file{#cvs.lock} serves as a master
1324 lock. That is, one must obtain this lock first before
1325 creating any of the other locks.
1327 To obtain a read lock, first create the @file{#cvs.lock}
1328 directory. This operation must be atomic (which should
1329 be true for creating a directory under most operating
1330 systems). If it fails because the directory already
1331 existed, wait for a while and try again. After
1332 obtaining the @file{#cvs.lock} lock, create a file
1333 whose name is @file{#cvs.rfl.} followed by information
1334 of your choice (for example, hostname and process
1335 identification number). Then remove the
1336 @file{#cvs.lock} directory to release the master lock.
1337 Then proceed with reading the repository. When you are
1338 done, remove the @file{#cvs.rfl} file to release the
1341 Promotable read locks are a concept you may not find in other literature on
1342 concurrency. They are used to allow a two (or more) pass process to only lock
1343 a file for read on the first (read) pass(es), then upgrade its read locks to
1344 write locks if necessary for a final pass, still assured that the files have
1345 not changed since they were first read. @sc{cvs} uses promotable read locks,
1346 for example, to prevent commit and tag verification passes from interfering
1347 with other reading processes. It can then lock only a single directory at a
1348 time for write during the write pass.
1350 To obtain a promotable read lock, first create the @file{#cvs.lock} directory,
1351 as with a non-promotable read lock. Then check
1352 that there are no files that start with
1353 @file{#cvs.pfl}. If there are, remove the master @file{#cvs.lock} directory,
1354 wait awhile (CVS waits 30 seconds between lock attempts), and try again. If
1355 there are no other promotable locks, go ahead and create a file whose name is
1356 @file{#cvs.pfl} followed by information of your choice (for example, CVS uses
1357 its hostname and the process identification number of the CVS server process
1358 creating the lock). If versions of @sc{cvs} older than version 1.12.4 access
1359 your repository directly (not via a @sc{cvs} server of version 1.12.4 or
1360 later), then you should also create a read lock since older versions of CVS
1361 will ignore the promotable lock when attempting to create their own write lock.
1362 Then remove the master @file{#cvs.lock} directory in order to allow other
1363 processes to obtain read locks.
1365 To obtain a write lock, first create the
1366 @file{#cvs.lock} directory, as with read locks. Then
1367 check that there are no files whose names start with
1368 @file{#cvs.rfl.} and no files whose names start with @file{#cvs.pfl} that are
1369 not owned by the process attempting to get the write lock. If either exist,
1370 remove @file{#cvs.lock}, wait for a while, and try again. If
1371 there are no readers or promotable locks from other processes, then create a
1372 file whose name is @file{#cvs.wfl} followed by information of your choice
1373 (again, CVS uses the hostname and server process identification
1374 number). Remove your @file{#cvs.pfl} file if present. Hang on to the
1375 @file{#cvs.lock} lock. Proceed
1376 with writing the repository. When you are done, first
1377 remove the @file{#cvs.wfl} file and then the
1378 @file{#cvs.lock} directory. Note that unlike the
1379 @file{#cvs.rfl} file, the @file{#cvs.wfl} file is just
1380 informational; it has no effect on the locking operation
1381 beyond what is provided by holding on to the
1382 @file{#cvs.lock} lock itself.
1384 Note that each lock (write lock or read lock) only locks
1385 a single directory in the repository, including
1386 @file{Attic} and @file{CVS} but not including
1387 subdirectories which represent other directories under
1388 version control. To lock an entire tree, you need to
1389 lock each directory (note that if you fail to obtain
1390 any lock you need, you must release the whole tree
1391 before waiting and trying again, to avoid deadlocks).
1393 Note also that @sc{cvs} expects write locks to control
1394 access to individual @file{foo,v} files. @sc{rcs} has
1395 a scheme where the @file{,foo,} file serves as a lock,
1396 but @sc{cvs} does not implement it and so taking out a
1397 @sc{cvs} write lock is recommended. See the comments at
1398 rcs_internal_lockfile in the @sc{cvs} source code for
1399 further discussion/rationale.
1401 @node CVSROOT storage
1402 @subsection How files are stored in the CVSROOT directory
1403 @cindex CVSROOT, storage of files
1405 The @file{$CVSROOT/CVSROOT} directory contains the
1406 various administrative files. In some ways this
1407 directory is just like any other directory in the
1408 repository; it contains @sc{rcs} files whose names end
1409 in @samp{,v}, and many of the @sc{cvs} commands operate
1410 on it the same way. However, there are a few
1413 For each administrative file, in addition to the
1414 @sc{rcs} file, there is also a checked out copy of the
1415 file. For example, there is an @sc{rcs} file
1416 @file{loginfo,v} and a file @file{loginfo} which
1417 contains the latest revision contained in
1418 @file{loginfo,v}. When you check in an administrative
1419 file, @sc{cvs} should print
1422 cvs commit: Rebuilding administrative file database
1426 and update the checked out copy in
1427 @file{$CVSROOT/CVSROOT}. If it does not, there is
1428 something wrong (@pxref{BUGS}). To add your own files
1429 to the files to be updated in this fashion, you can add
1430 them to the @file{checkoutlist} administrative file
1431 (@pxref{checkoutlist}).
1436 By default, the @file{modules} file behaves as
1437 described above. If the modules file is very large,
1438 storing it as a flat text file may make looking up
1439 modules slow (I'm not sure whether this is as much of a
1440 concern now as when @sc{cvs} first evolved this
1441 feature; I haven't seen benchmarks). Therefore, by
1442 making appropriate edits to the @sc{cvs} source code
1443 one can store the modules file in a database which
1444 implements the @code{ndbm} interface, such as Berkeley
1445 db or GDBM. If this option is in use, then the modules
1446 database will be stored in the files @file{modules.db},
1447 @file{modules.pag}, and/or @file{modules.dir}.
1448 @c I think fileattr also will use the database stuff.
1451 For information on the meaning of the various
1452 administrative files, see @ref{Administrative files}.
1454 @node Working directory storage
1455 @section How data is stored in the working directory
1457 @c FIXME: Somewhere we should discuss timestamps (test
1458 @c case "stamps" in sanity.sh). But not here. Maybe
1459 @c in some kind of "working directory" chapter which
1460 @c would encompass the "Builds" one? But I'm not sure
1461 @c whether that is a good organization (is it based on
1462 @c what the user wants to do?).
1464 @cindex CVS directory, in working directory
1465 While we are discussing @sc{cvs} internals which may
1466 become visible from time to time, we might as well talk
1467 about what @sc{cvs} puts in the @file{CVS} directories
1468 in the working directories. As with the repository,
1469 @sc{cvs} handles this information and one can usually
1470 access it via @sc{cvs} commands. But in some cases it
1471 may be useful to look at it, and other programs, such
1472 as the @code{jCVS} graphical user interface or the
1473 @code{VC} package for emacs, may need to look at it.
1474 Such programs should follow the recommendations in this
1475 section if they hope to be able to work with other
1476 programs which use those files, including future
1477 versions of the programs just mentioned and the
1478 command-line @sc{cvs} client.
1480 The @file{CVS} directory contains several files.
1481 Programs which are reading this directory should
1482 silently ignore files which are in the directory but
1483 which are not documented here, to allow for future
1486 The files are stored according to the text file
1487 convention for the system in question. This means that
1488 working directories are not portable between systems
1489 with differing conventions for storing text files.
1490 This is intentional, on the theory that the files being
1491 managed by @sc{cvs} probably will not be portable between
1492 such systems either.
1496 This file contains the current @sc{cvs} root, as
1497 described in @ref{Specifying a repository}.
1499 @cindex Repository file, in CVS directory
1500 @cindex CVS/Repository file
1502 This file contains the directory within the repository
1503 which the current directory corresponds with. It can
1504 be either an absolute pathname or a relative pathname;
1505 @sc{cvs} has had the ability to read either format
1506 since at least version 1.3 or so. The relative
1507 pathname is relative to the root, and is the more
1508 sensible approach, but the absolute pathname is quite
1509 common and implementations should accept either. For
1510 example, after the command
1513 cvs -d :local:/usr/local/cvsroot checkout yoyodyne/tc
1517 @file{Root} will contain
1520 :local:/usr/local/cvsroot
1524 and @file{Repository} will contain either
1527 /usr/local/cvsroot/yoyodyne/tc
1537 If the particular working directory does not correspond
1538 to a directory in the repository, then @file{Repository}
1539 should contain @file{CVSROOT/Emptydir}.
1540 @cindex Emptydir, in CVSROOT directory
1541 @cindex CVSROOT/Emptydir directory
1543 @cindex Entries file, in CVS directory
1544 @cindex CVS/Entries file
1546 This file lists the files and directories in the
1548 The first character of each line indicates what sort of
1549 line it is. If the character is unrecognized, programs
1550 reading the file should silently skip that line, to
1551 allow for future expansion.
1553 If the first character is @samp{/}, then the format is:
1556 /@var{name}/@var{revision}/@var{timestamp}[+@var{conflict}]/@var{options}/@var{tagdate}
1560 where @samp{[} and @samp{]} are not part of the entry,
1561 but instead indicate that the @samp{+} and conflict
1562 marker are optional. @var{name} is the name of the
1563 file within the directory. @var{revision} is the
1564 revision that the file in the working derives from, or
1565 @samp{0} for an added file, or @samp{-} followed by a
1566 revision for a removed file. @var{timestamp} is the
1567 timestamp of the file at the time that @sc{cvs} created
1568 it; if the timestamp differs with the actual
1569 modification time of the file it means the file has
1570 been modified. It is stored in
1571 the format used by the ISO C asctime() function (for
1572 example, @samp{Sun Apr 7 01:29:26 1996}). One may
1573 write a string which is not in that format, for
1574 example, @samp{Result of merge}, to indicate that the
1575 file should always be considered to be modified. This
1576 is not a special case; to see whether a file is
1577 modified a program should take the timestamp of the file
1578 and simply do a string compare with @var{timestamp}.
1579 If there was a conflict, @var{conflict} can be set to
1580 the modification time of the file after the file has been
1581 written with conflict markers (@pxref{Conflicts example}).
1582 Thus if @var{conflict} is subsequently the same as the actual
1583 modification time of the file it means that the user
1584 has obviously not resolved the conflict. @var{options}
1585 contains sticky options (for example @samp{-kb} for a
1586 binary file). @var{tagdate} contains @samp{T} followed
1587 by a tag name, or @samp{D} for a date, followed by a
1588 sticky tag or date. Note that if @var{timestamp}
1589 contains a pair of timestamps separated by a space,
1590 rather than a single timestamp, you are dealing with a
1591 version of @sc{cvs} earlier than @sc{cvs} 1.5 (not
1594 The timezone on the timestamp in CVS/Entries (local or
1595 universal) should be the same as the operating system
1596 stores for the timestamp of the file itself. For
1597 example, on Unix the file's timestamp is in universal
1598 time (UT), so the timestamp in CVS/Entries should be
1599 too. On @sc{vms}, the file's timestamp is in local
1600 time, so @sc{cvs} on @sc{vms} should use local time.
1601 This rule is so that files do not appear to be modified
1602 merely because the timezone changed (for example, to or
1604 @c See comments and calls to gmtime() and friends in
1605 @c src/vers_ts.c (function time_stamp).
1607 If the first character of a line in @file{Entries} is
1608 @samp{D}, then it indicates a subdirectory. @samp{D}
1609 on a line all by itself indicates that the program
1610 which wrote the @file{Entries} file does record
1611 subdirectories (therefore, if there is such a line and
1612 no other lines beginning with @samp{D}, one knows there
1613 are no subdirectories). Otherwise, the line looks
1617 D/@var{name}/@var{filler1}/@var{filler2}/@var{filler3}/@var{filler4}
1621 where @var{name} is the name of the subdirectory, and
1622 all the @var{filler} fields should be silently ignored,
1623 for future expansion. Programs which modify
1624 @code{Entries} files should preserve these fields.
1626 The lines in the @file{Entries} file can be in any order.
1628 @cindex Entries.Log file, in CVS directory
1629 @cindex CVS/Entries.Log file
1631 This file does not record any information beyond that
1632 in @file{Entries}, but it does provide a way to update
1633 the information without having to rewrite the entire
1634 @file{Entries} file, including the ability to preserve
1635 the information even if the program writing
1636 @file{Entries} and @file{Entries.Log} abruptly aborts.
1637 Programs which are reading the @file{Entries} file
1638 should also check for @file{Entries.Log}. If the latter
1639 exists, they should read @file{Entries} and then apply
1640 the changes mentioned in @file{Entries.Log}. After
1641 applying the changes, the recommended practice is to
1642 rewrite @file{Entries} and then delete @file{Entries.Log}.
1643 The format of a line in @file{Entries.Log} is a single
1644 character command followed by a space followed by a
1645 line in the format specified for a line in
1646 @file{Entries}. The single character command is
1647 @samp{A} to indicate that the entry is being added,
1648 @samp{R} to indicate that the entry is being removed,
1649 or any other character to indicate that the entire line
1650 in @file{Entries.Log} should be silently ignored (for
1651 future expansion). If the second character of the line
1652 in @file{Entries.Log} is not a space, then it was
1653 written by an older version of @sc{cvs} (not documented
1656 Programs which are writing rather than reading can
1657 safely ignore @file{Entries.Log} if they so choose.
1659 @cindex Entries.Backup file, in CVS directory
1660 @cindex CVS/Entries.Backup file
1661 @item Entries.Backup
1662 This is a temporary file. Recommended usage is to
1663 write a new entries file to @file{Entries.Backup}, and
1664 then to rename it (atomically, where possible) to @file{Entries}.
1666 @cindex Entries.Static file, in CVS directory
1667 @cindex CVS/Entries.Static file
1668 @item Entries.Static
1669 The only relevant thing about this file is whether it
1670 exists or not. If it exists, then it means that only
1671 part of a directory was gotten and @sc{cvs} will
1672 not create additional files in that directory. To
1673 clear it, use the @code{update} command with the
1674 @samp{-d} option, which will get the additional files
1675 and remove @file{Entries.Static}.
1676 @c FIXME: This needs to be better documented, in places
1677 @c other than Working Directory Storage.
1678 @c FIXCVS: The fact that this setting exists needs to
1679 @c be more visible to the user. For example "cvs
1680 @c status foo", in the case where the file would be
1681 @c gotten except for Entries.Static, might say
1682 @c something to distinguish this from other cases.
1683 @c One thing that periodically gets suggested is to
1684 @c have "cvs update" print something when it skips
1685 @c files due to Entries.Static, but IMHO that kind of
1686 @c noise pretty much makes the Entries.Static feature
1689 @cindex Tag file, in CVS directory
1690 @cindex CVS/Tag file
1691 @cindex Sticky tags/dates, per-directory
1692 @cindex Per-directory sticky tags/dates
1694 This file contains per-directory sticky tags or dates.
1695 The first character is @samp{T} for a branch tag,
1696 @samp{N} for a non-branch tag, or @samp{D} for a date,
1697 or another character to mean the file should be
1698 silently ignored, for future expansion. This character
1699 is followed by the tag or date. Note that
1700 per-directory sticky tags or dates are used for things
1701 like applying to files which are newly added; they
1702 might not be the same as the sticky tags or dates on
1703 individual files. For general information on sticky
1704 tags and dates, see @ref{Sticky tags}.
1705 @c FIXME: This needs to be much better documented,
1706 @c preferably not in the context of "working directory
1708 @c FIXME: The Sticky tags node needs to discuss, or xref to
1709 @c someplace which discusses, per-directory sticky
1710 @c tags and the distinction with per-file sticky tags.
1712 @cindex Notify file, in CVS directory
1713 @cindex CVS/Notify file
1715 This file stores notifications (for example, for
1716 @code{edit} or @code{unedit}) which have not yet been
1717 sent to the server. Its format is not yet documented
1720 @cindex Notify.tmp file, in CVS directory
1721 @cindex CVS/Notify.tmp file
1723 This file is to @file{Notify} as @file{Entries.Backup}
1724 is to @file{Entries}. That is, to write @file{Notify},
1725 first write the new contents to @file{Notify.tmp} and
1726 then (atomically where possible), rename it to
1729 @cindex Base directory, in CVS directory
1730 @cindex CVS/Base directory
1732 If watches are in use, then an @code{edit} command
1733 stores the original copy of the file in the @file{Base}
1734 directory. This allows the @code{unedit} command to
1735 operate even if it is unable to communicate with the
1738 @cindex Baserev file, in CVS directory
1739 @cindex CVS/Baserev file
1741 The file lists the revision for each of the files in
1742 the @file{Base} directory. The format is:
1745 B@var{name}/@var{rev}/@var{expansion}
1749 where @var{expansion} should be ignored, to allow for
1752 @cindex Baserev.tmp file, in CVS directory
1753 @cindex CVS/Baserev.tmp file
1755 This file is to @file{Baserev} as @file{Entries.Backup}
1756 is to @file{Entries}. That is, to write @file{Baserev},
1757 first write the new contents to @file{Baserev.tmp} and
1758 then (atomically where possible), rename it to
1761 @cindex Template file, in CVS directory
1762 @cindex CVS/Template file
1764 This file contains the template specified by the
1765 @file{rcsinfo} file (@pxref{rcsinfo}). It is only used
1766 by the client; the non-client/server @sc{cvs} consults
1767 @file{rcsinfo} directly.
1770 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1771 @node Intro administrative files
1772 @section The administrative files
1773 @cindex Administrative files (intro)
1774 @cindex Modules file
1775 @cindex CVSROOT, module name
1776 @cindex Defining modules (intro)
1778 @c FIXME: this node should be reorganized into "general
1779 @c information about admin files" and put the "editing
1780 @c admin files" stuff up front rather than jumping into
1781 @c the details of modules right away. Then the
1782 @c Administrative files node can go away, the information
1783 @c on each admin file distributed to a place appropriate
1784 @c to its function, and this node can contain a table
1785 @c listing each file and a @ref to its detailed description.
1787 The directory @file{$CVSROOT/CVSROOT} contains some @dfn{administrative
1788 files}. @xref{Administrative files}, for a complete description.
1789 You can use @sc{cvs} without any of these files, but
1790 some commands work better when at least the
1791 @file{modules} file is properly set up.
1793 The most important of these files is the @file{modules}
1794 file. It defines all modules in the repository. This
1795 is a sample @file{modules} file.
1797 @c FIXME: The CVSROOT line is a goofy example now that
1798 @c mkmodules doesn't exist.
1801 modules CVSROOT modules
1808 The @file{modules} file is line oriented. In its
1809 simplest form each line contains the name of the
1810 module, whitespace, and the directory where the module
1811 resides. The directory is a path relative to
1812 @code{$CVSROOT}. The last four lines in the example
1813 above are examples of such lines.
1815 @c FIXME: might want to introduce the concept of options in modules file
1816 @c (the old example which was here, -i mkmodules, is obsolete).
1818 The line that defines the module called @samp{modules}
1819 uses features that are not explained here.
1820 @xref{modules}, for a full explanation of all the
1823 @c FIXME: subsection without node is bogus
1824 @subsection Editing administrative files
1825 @cindex Editing administrative files
1826 @cindex Administrative files, editing them
1828 You edit the administrative files in the same way that you would edit
1829 any other module. Use @samp{cvs checkout CVSROOT} to get a working
1830 copy, edit it, and commit your changes in the normal way.
1832 It is possible to commit an erroneous administrative
1833 file. You can often fix the error and check in a new
1834 revision, but sometimes a particularly bad error in the
1835 administrative file makes it impossible to commit new
1837 @c @xref{Bad administrative files} for a hint
1838 @c about how to solve such situations.
1839 @c -- administrative file checking--
1841 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1842 @node Multiple repositories
1843 @section Multiple repositories
1844 @cindex Multiple repositories
1845 @cindex Repositories, multiple
1846 @cindex Many repositories
1847 @cindex Parallel repositories
1848 @cindex Disjoint repositories
1849 @cindex CVSROOT, multiple repositories
1851 In some situations it is a good idea to have more than
1852 one repository, for instance if you have two
1853 development groups that work on separate projects
1854 without sharing any code. All you have to do to have
1855 several repositories is to specify the appropriate
1856 repository, using the @code{CVSROOT} environment
1857 variable, the @samp{-d} option to @sc{cvs}, or (once
1858 you have checked out a working directory) by simply
1859 allowing @sc{cvs} to use the repository that was used
1860 to check out the working directory
1861 (@pxref{Specifying a repository}).
1863 The big advantage of having multiple repositories is
1864 that they can reside on different servers. With @sc{cvs}
1865 version 1.10, a single command cannot recurse into
1866 directories from different repositories. With development
1867 versions of @sc{cvs}, you can check out code from multiple
1868 servers into your working directory. @sc{cvs} will
1869 recurse and handle all the details of making
1870 connections to as many server machines as necessary to
1871 perform the requested command. Here is an example of
1872 how to set up a working directory:
1875 cvs -d server1:/cvs co dir1
1877 cvs -d server2:/root co sdir
1881 The @code{cvs co} commands set up the working
1882 directory, and then the @code{cvs update} command will
1883 contact server2, to update the dir1/sdir subdirectory,
1884 and server1, to update everything else.
1886 @c FIXME: Does the FAQ have more about this? I have a
1887 @c dim recollection, but I'm too lazy to check right now.
1889 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1890 @node Creating a repository
1891 @section Creating a repository
1893 @cindex Repository, setting up
1894 @cindex Creating a repository
1895 @cindex Setting up a repository
1897 To set up a @sc{cvs} repository, first choose the
1898 machine and disk on which you want to store the
1899 revision history of the source files. CPU and memory
1900 requirements are modest, so most machines should be
1901 adequate. For details see @ref{Server requirements}.
1902 @c Possible that we should be providing a quick rule of
1903 @c thumb, like the 32M memory for the server. That
1904 @c might increase the number of people who are happy
1905 @c with the answer, without following the xref.
1907 To estimate disk space
1908 requirements, if you are importing RCS files from
1909 another system, the size of those files is the
1910 approximate initial size of your repository, or if you
1911 are starting without any version history, a rule of
1912 thumb is to allow for the server approximately three
1913 times the size of the code to be under @sc{cvs} for the
1914 repository (you will eventually outgrow this, but not
1915 for a while). On the machines on which the developers
1916 will be working, you'll want disk space for
1917 approximately one working directory for each developer
1918 (either the entire tree or a portion of it, depending
1919 on what each developer uses).
1921 The repository should be accessible
1922 (directly or via a networked file system) from all
1923 machines which want to use @sc{cvs} in server or local
1924 mode; the client machines need not have any access to
1925 it other than via the @sc{cvs} protocol. It is not
1926 possible to use @sc{cvs} to read from a repository
1927 which one only has read access to; @sc{cvs} needs to be
1928 able to create lock files (@pxref{Concurrency}).
1930 @cindex init (subcommand)
1931 To create a repository, run the @code{cvs init}
1932 command. It will set up an empty repository in the
1933 @sc{cvs} root specified in the usual way
1934 (@pxref{Repository}). For example,
1937 cvs -d /usr/local/cvsroot init
1940 @code{cvs init} is careful to never overwrite any
1941 existing files in the repository, so no harm is done if
1942 you run @code{cvs init} on an already set-up
1945 @code{cvs init} will enable history logging; if you
1946 don't want that, remove the history file after running
1947 @code{cvs init}. @xref{history file}.
1950 @section Backing up a repository
1951 @cindex Repository, backing up
1952 @cindex Backing up, repository
1954 There is nothing particularly magical about the files
1955 in the repository; for the most part it is possible to
1956 back them up just like any other files. However, there
1957 are a few issues to consider.
1959 @cindex Locks, cvs, and backups
1960 @cindex #cvs.rfl, and backups
1961 The first is that to be paranoid, one should either not
1962 use @sc{cvs} during the backup, or have the backup
1963 program lock @sc{cvs} while doing the backup. To not
1964 use @sc{cvs}, you might forbid logins to machines which
1965 can access the repository, turn off your @sc{cvs}
1966 server, or similar mechanisms. The details would
1967 depend on your operating system and how you have
1968 @sc{cvs} set up. To lock @sc{cvs}, you would create
1969 @file{#cvs.rfl} locks in each repository directory.
1970 See @ref{Concurrency}, for more on @sc{cvs} locks.
1971 Having said all this, if you just back up without any
1972 of these precautions, the results are unlikely to be
1973 particularly dire. Restoring from backup, the
1974 repository might be in an inconsistent state, but this
1975 would not be particularly hard to fix manually.
1977 When you restore a repository from backup, assuming
1978 that changes in the repository were made after the time
1979 of the backup, working directories which were not
1980 affected by the failure may refer to revisions which no
1981 longer exist in the repository. Trying to run @sc{cvs}
1982 in such directories will typically produce an error
1983 message. One way to get those changes back into the
1984 repository is as follows:
1988 Get a new working directory.
1991 Copy the files from the working directory from before
1992 the failure over to the new working directory (do not
1993 copy the contents of the @file{CVS} directories, of
1997 Working in the new working directory, use commands such
1998 as @code{cvs update} and @code{cvs diff} to figure out
1999 what has changed, and then when you are ready, commit
2000 the changes into the repository.
2003 @node Moving a repository
2004 @section Moving a repository
2005 @cindex Repository, moving
2006 @cindex Moving a repository
2007 @cindex Copying a repository
2009 Just as backing up the files in the repository is
2010 pretty much like backing up any other files, if you
2011 need to move a repository from one place to another it
2012 is also pretty much like just moving any other
2013 collection of files.
2015 The main thing to consider is that working directories
2016 point to the repository. The simplest way to deal with
2017 a moved repository is to just get a fresh working
2018 directory after the move. Of course, you'll want to
2019 make sure that the old working directory had been
2020 checked in before the move, or you figured out some
2021 other way to make sure that you don't lose any
2022 changes. If you really do want to reuse the existing
2023 working directory, it should be possible with manual
2024 surgery on the @file{CVS/Repository} files. You can
2025 see @ref{Working directory storage}, for information on
2026 the @file{CVS/Repository} and @file{CVS/Root} files, but
2027 unless you are sure you want to bother, it probably
2029 @c FIXME: Surgery on CVS/Repository should be avoided
2030 @c by making RELATIVE_REPOS the default.
2031 @c FIXME-maybe: might want some documented way to
2032 @c change the CVS/Root files in some particular tree.
2033 @c But then again, I don't know, maybe just having
2034 @c people do this in perl/shell/&c isn't so bad...
2036 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
2037 @node Remote repositories
2038 @section Remote repositories
2039 @cindex Repositories, remote
2040 @cindex Remote repositories
2041 @cindex Client/Server Operation
2043 @cindex Remote repositories, port specification
2044 @cindex Repositories, remote, port specification
2045 @cindex Client/Server Operation, port specification
2046 @cindex pserver (client/server connection method), port specification
2047 @cindex kserver (client/server connection method), port specification
2048 @cindex gserver (client/server connection method), port specification
2049 @cindex port, specifying for remote repositories
2051 Your working copy of the sources can be on a
2052 different machine than the repository. Using @sc{cvs}
2053 in this manner is known as @dfn{client/server}
2054 operation. You run @sc{cvs} on a machine which can
2055 mount your working directory, known as the
2056 @dfn{client}, and tell it to communicate to a machine
2057 which can mount the repository, known as the
2058 @dfn{server}. Generally, using a remote
2059 repository is just like using a local one, except that
2060 the format of the repository name is:
2063 [:@var{method}:][[@var{user}][:@var{password}]@@]@var{hostname}[:[@var{port}]]/path/to/repository
2066 Specifying a password in the repository name is not recommended during
2067 checkout, since this will cause @sc{cvs} to store a cleartext copy of the
2068 password in each created directory. @code{cvs login} first instead
2069 (@pxref{Password authentication client}).
2071 The details of exactly what needs to be set up depend
2072 on how you are connecting to the server.
2074 @c Should we try to explain which platforms are which?
2075 @c Platforms like unix and VMS, which only allow
2076 @c privileged programs to bind to sockets <1024 lose on
2078 @c Platforms like Mac and VMS, whose rsh program is
2079 @c unusable or nonexistent, lose on :ext:
2080 @c Platforms like OS/2 and NT probably could plausibly
2081 @c default either way (modulo -b troubles).
2084 * Server requirements:: Memory and other resources for servers
2085 * The connection method:: Connection methods and method options
2086 * Connecting via rsh:: Using the @code{rsh} program to connect
2087 * Password authenticated:: Direct connections using passwords
2088 * GSSAPI authenticated:: Direct connections using GSSAPI
2089 * Kerberos authenticated:: Direct connections with Kerberos
2090 * Connecting via fork:: Using a forked @code{cvs server} to connect
2091 * Write proxies:: Distributing load across several CVS servers
2094 @node Server requirements
2095 @subsection Server requirements
2097 The quick answer to what sort of machine is suitable as
2098 a server is that requirements are modest---a server
2099 with 32M of memory or even less can handle a fairly
2100 large source tree with a fair amount of activity.
2101 @c Say something about CPU speed too? I'm even less sure
2102 @c what to say on that subject...
2104 The real answer, of course, is more complicated.
2105 Estimating the known areas of large memory consumption
2106 should be sufficient to estimate memory requirements.
2107 There are two such areas documented here; other memory
2108 consumption should be small by comparison (if you find
2109 that is not the case, let us know, as described in
2110 @ref{BUGS}, so we can update this documentation).
2112 The first area of big memory consumption is large
2113 checkouts, when using the @sc{cvs} server. The server
2114 consists of two processes for each client that it is
2115 serving. Memory consumption on the child process
2116 should remain fairly small. Memory consumption on the
2117 parent process, particularly if the network connection
2118 to the client is slow, can be expected to grow to
2119 slightly more than the size of the sources in a single
2120 directory, or two megabytes, whichever is larger.
2121 @c "two megabytes" of course is SERVER_HI_WATER. But
2122 @c we don't mention that here because we are
2123 @c documenting the default configuration of CVS. If it
2124 @c is a "standard" thing to change that value, it
2125 @c should be some kind of run-time configuration.
2127 @c See cvsclient.texi for more on the design decision
2128 @c to not have locks in place while waiting for the
2129 @c client, which is what results in memory consumption
2132 Multiplying the size of each @sc{cvs} server by the
2133 number of servers which you expect to have active at
2134 one time should give an idea of memory requirements for
2135 the server. For the most part, the memory consumed by
2136 the parent process probably can be swap space rather
2137 than physical memory.
2138 @c Has anyone verified that notion about swap space?
2139 @c I say it based pretty much on guessing that the
2140 @c ->text of the struct buffer_data only gets accessed
2141 @c in a first in, first out fashion, but I haven't
2142 @c looked very closely.
2144 @c What about disk usage in /tmp on the server? I think that
2145 @c it can be substantial, but I haven't looked at this
2146 @c again and tried to figure it out ("cvs import" is
2147 @c probably the worst case...).
2149 The second area of large memory consumption is
2150 @code{diff}, when checking in large files. This is
2151 required even for binary files. The rule of thumb is
2152 to allow about ten times the size of the largest file
2153 you will want to check in, although five times may be
2154 adequate. For example, if you want to check in a file
2155 which is 10 megabytes, you should have 100 megabytes of
2156 memory on the machine doing the checkin (the server
2157 machine for client/server, or the machine running
2158 @sc{cvs} for non-client/server). This can be swap
2159 space rather than physical memory. Because the memory
2160 is only required briefly, there is no particular need
2161 to allow memory for more than one such checkin at a
2163 @c The 5-10 times rule of thumb is from Paul Eggert for
2164 @c GNU diff. I don't think it is in the GNU diff
2165 @c manual or anyplace like that.
2167 @c Probably we could be saying more about
2168 @c non-client/server CVS.
2169 @c I would guess for non-client/server CVS in an NFS
2170 @c environment the biggest issues are the network and
2173 Resource consumption for the client is even more
2174 modest---any machine with enough capacity to run the
2175 operating system in question should have little
2177 @c Is that true? I think the client still wants to
2178 @c (bogusly) store entire files in memory at times.
2180 For information on disk space requirements, see
2181 @ref{Creating a repository}.
2183 @node The connection method
2184 @subsection The connection method
2186 In its simplest form, the @var{method} portion of the repository string
2187 (@pxref{Remote repositories}) may be one of @samp{ext}, @samp{fork},
2188 @samp{gserver}, @samp{kserver}, @samp{local}, @samp{pserver}, and, on some
2189 platforms, @samp{server}.
2191 If @var{method} is not specified, and the repository
2192 name starts with a @samp{/}, then the default is @code{local}.
2193 If @var{method} is not specified, and the repository
2194 name does not start with a @samp{/}, then the default is @code{ext}
2195 or @code{server}, depending on your platform; both the @samp{ext}
2196 and @samp{server} methods are described in @ref{Connecting via rsh}.
2198 @cindex connection method options
2199 @cindex options, connection method
2200 The @code{ext}, @code{fork}, @code{gserver}, and @code{pserver} connection
2201 methods all accept optional method options, specified as part of the
2202 @var{method} string, like so:
2205 :@var{method}[;@var{option}=@var{arg}...]:@var{other_connection_data}
2208 @sc{cvs} is not sensitive to the case of @var{method} or @var{option}, though
2209 it may sometimes be sensitive to the case of @var{arg}. The possible method
2210 options are as follows:
2213 @cindex CVS_PROXY_PORT
2214 @cindex proxy, method option
2215 @cindex proxyport, method option
2216 @cindex proxies, web, connecting via
2217 @cindex web proxies, connecting via
2218 @cindex proxies, HTTP, connecting via
2219 @cindex HTTP proxies, connecting via
2220 @item proxy=@var{hostname}
2221 @itemx proxyport=@var{port}
2222 These two method options can be used to connect via an HTTP tunnel style web
2223 proxy. @var{hostname} should be the name of the HTTP proxy server to connect
2224 through and @var{port} is the port number on the HTTP proxy server to connect
2225 via. @var{port} defaults to 8080.
2227 @strong{NOTE: An HTTP proxy server is not the same as a @sc{cvs} write proxy
2228 server - please see @ref{Write proxies} for more on @sc{cvs} write proxies.}
2230 For example, to connect pserver via a web proxy listening on port 8000 of
2231 www.myproxy.net, you would use a method of:
2234 :pserver;proxy=www.myproxy.net;proxyport=8000:@var{pserver_connection_string}
2237 @strong{NOTE: In the above example, @var{pserver_connection_string} is still
2238 required to connect and authenticate to the CVS server, as noted in the
2239 upcoming sections on password authentication, @code{gserver}, and
2240 @code{kserver}. The example above only demonstrates a modification to the
2241 @var{method} portion of the repository name.}
2243 These options first appeared in @sc{cvs} version 1.12.7 and are valid as
2244 modifcations to the @code{gserver} and @code{pserver} connection methods.
2246 @cindex CVS_RSH method option
2247 @item CVS_RSH=@var{path}
2248 This method option can be used with the @code{ext} method to specify the path
2249 the @sc{cvs} client will use to find the remote shell used to contact the
2250 @sc{cvs} server and takes precedence over any path specified in the
2251 @code{$CVS_RSH} environment variable (@pxref{Connecting via rsh}). For
2252 example, to connect to a @sc{cvs} server via the local
2253 @file{/path/to/ssh/command} command, you could choose to specify the following
2254 @var{path} via the @code{CVS_RSH} method option:
2257 :ext;CVS_RSH=/path/to/ssh/command:@var{ext_connection_string}
2260 This method option first appeared in @sc{cvs} version 1.12.11 and is valid only
2261 as a modifcation to the @code{ext} connection method.
2263 @cindex CVS_SERVER method option
2264 @item CVS_SERVER=@var{path}
2265 This method option can be used with the @code{ext} and @code{fork} methods to
2266 specify the path @sc{cvs} will use to find the @sc{cvs} executable on the
2267 @sc{cvs} server and takes precedence over any path specified in the
2268 @code{$CVS_SERVER} environment variable (@pxref{Connecting via rsh}). For
2269 example, to select the remote @file{/path/to/cvs/command} executable as your
2270 @sc{cvs} server application on the @sc{cvs} server machine, you could choose to
2271 specify the following @var{path} via the @code{CVS_SERVER} method option:
2274 :ext;CVS_SERVER=/path/to/cvs/command:@var{ext_connection_string}
2278 or, to select an executable named @samp{cvs-1.12.11}, assuming it is in your
2279 @code{$PATH} on the @sc{cvs} server:
2282 :ext;CVS_SERVER=cvs-1.12.11:@var{ext_connection_string}
2285 This method option first appeared in @sc{cvs} version 1.12.11 and is valid
2286 as a modifcation to both the @code{ext} and @code{fork} connection methods.
2288 @cindex Redirect, method option
2289 @item Redirect=@var{boolean-state}
2290 The @code{Redirect} method option determines whether the @sc{cvs} client will
2291 allow a @sc{cvs} server to redirect it to a different @sc{cvs} server, usually
2292 for write requests, as in a write proxy setup.
2294 A @var{boolean-state} of any value acceptable for boolean @file{CVSROOT/config}
2295 file options is acceptable here (@pxref{config}). For example, @samp{on},
2296 @samp{off}, @samp{true}, and @samp{false} are all valid values for
2297 @var{boolean-state}. @var{boolean-state} for the @code{Redirect} method option
2298 defaults to @samp{on}.
2300 This option will have no effect when talking to any non-secondary @sc{cvs}
2301 server. For more on write proxies and secondary servers, please see
2302 @ref{Write proxies}.
2304 This method option first appeared in @sc{cvs} version 1.12.11 and is valid only
2305 as a modifcation to the @code{ext} connection method.
2308 As a further example, to combine both the @code{CVS_RSH} and @code{CVS_SERVER}
2309 options, a method specification like the following would work:
2312 :ext;CVS_RSH=/path/to/ssh/command;CVS_SERVER=/path/to/cvs/command:
2315 This means that you would not need to have
2316 the @code{CVS_SERVER} or @code{CVS_RSH} environment
2317 variables set correctly. See @ref{Connecting via rsh}, for more details on
2318 these environment variables.
2320 @node Connecting via rsh
2321 @subsection Connecting with rsh
2324 @sc{cvs} uses the @samp{rsh} protocol to perform these
2325 operations, so the remote user host needs to have a
2326 @file{.rhosts} file which grants access to the local
2327 user. Note that the program that @sc{cvs} uses for this
2328 purpose may be specified using the @file{--with-rsh}
2331 For example, suppose you are the user @samp{mozart} on
2332 the local machine @samp{toe.example.com}, and the
2333 server machine is @samp{faun.example.org}. On
2334 faun, put the following line into the file
2335 @file{.rhosts} in @samp{bach}'s home directory:
2338 toe.example.com mozart
2342 Then test that @samp{rsh} is working with
2345 rsh -l bach faun.example.org 'echo $PATH'
2348 @cindex CVS_SERVER, environment variable
2349 Next you have to make sure that @code{rsh} will be able
2350 to find the server. Make sure that the path which
2351 @code{rsh} printed in the above example includes the
2352 directory containing a program named @code{cvs} which
2353 is the server. You need to set the path in
2354 @file{.bashrc}, @file{.cshrc}, etc., not @file{.login}
2355 or @file{.profile}. Alternately, you can set the
2356 environment variable @code{CVS_SERVER} on the client
2357 machine to the filename of the server you want to use,
2358 for example @file{/usr/local/bin/cvs-1.6}.
2359 For the @code{ext} and @code{fork} methods, you may
2360 also specify @var{CVS_SERVER} as an otpion in the
2361 @var{CVSROOT} so that you may use different servers for
2362 differnt roots. See @ref{Remote repositories} for more
2365 There is no need to edit @file{inetd.conf} or start a
2366 @sc{cvs} server daemon.
2368 @cindex :server:, setting up
2369 @cindex :ext:, setting up
2370 @cindex Kerberos, using kerberized rsh
2371 @cindex SSH (rsh replacement)
2372 @cindex rsh replacements (Kerberized, SSH, &c)
2373 There are two access methods that you use in @code{CVSROOT}
2374 for rsh. @code{:server:} specifies an internal rsh
2375 client, which is supported only by some @sc{cvs} ports.
2376 @code{:ext:} specifies an external rsh program. By
2377 default this is @code{rsh} (unless otherwise specified
2378 by the @file{--with-rsh} flag to configure) but you may set the
2379 @code{CVS_RSH} environment variable to invoke another
2380 program which can access the remote server (for
2381 example, @code{remsh} on HP-UX 9 because @code{rsh} is
2382 something different). It must be a program which can
2383 transmit data to and from the server without modifying
2384 it; for example the Windows NT @code{rsh} is not
2385 suitable since it by default translates between CRLF
2386 and LF. The OS/2 @sc{cvs} port has a hack to pass @samp{-b}
2387 to @code{rsh} to get around this, but since this could
2388 potentially cause problems for programs other than the
2389 standard @code{rsh}, it may change in the future. If
2390 you set @code{CVS_RSH} to @code{SSH} or some other rsh
2391 replacement, the instructions in the rest of this
2392 section concerning @file{.rhosts} and so on are likely
2393 to be inapplicable; consult the documentation for your rsh
2396 You may choose to specify the @var{CVS_RSH} option in
2397 the @var{CVSROOT} to allow you to use different ones
2398 for different roots. For example, allowing some roots
2399 to use @var{CVS_RSH=remsh} and some to use
2400 @var{CVS_RSH=ssh} for the @code{ext} method. See also
2401 the @ref{Remote repositories} for more details.
2402 @c See also the comment in src/client.c for rationale
2403 @c concerning "rsh" being the default and never
2406 Continuing our example, supposing you want to access
2407 the module @file{foo} in the repository
2408 @file{/usr/local/cvsroot/}, on machine
2409 @file{faun.example.org}, you are ready to go:
2412 cvs -d :ext:bach@@faun.example.org:/usr/local/cvsroot checkout foo
2416 (The @file{bach@@} can be omitted if the username is
2417 the same on both the local and remote hosts.)
2419 @c Should we mention "rsh host echo hi" and "rsh host
2420 @c cat" (the latter followed by typing text and ^D)
2421 @c as troubleshooting techniques? Probably yes
2422 @c (people tend to have trouble setting this up),
2423 @c but this kind of thing can be hard to spell out.
2425 @node Password authenticated
2426 @subsection Direct connection with password authentication
2428 The @sc{cvs} client can also connect to the server
2429 using a password protocol. This is particularly useful
2430 if using @code{rsh} is not feasible (for example,
2431 the server is behind a firewall), and Kerberos also is
2434 To use this method, it is necessary to make
2435 some adjustments on both the server and client sides.
2438 * Password authentication server:: Setting up the server
2439 * Password authentication client:: Using the client
2440 * Password authentication security:: What this method does and does not do
2443 @node Password authentication server
2444 @subsubsection Setting up the server for password authentication
2446 First of all, you probably want to tighten the
2447 permissions on the @file{$CVSROOT} and
2448 @file{$CVSROOT/CVSROOT} directories. See @ref{Password
2449 authentication security}, for more details.
2451 @cindex pserver (subcommand)
2452 @cindex Remote repositories, port specification
2453 @cindex Repositories, remote, port specification
2454 @cindex Client/Server Operation, port specification
2455 @cindex pserver (client/server connection method), port specification
2456 @cindex kserver (client/server connection method), port specification
2457 @cindex gserver (client/server connection method), port specification
2458 @cindex port, specifying for remote repositories
2459 @cindex Password server, setting up
2460 @cindex Authenticating server, setting up
2461 @cindex inetd, configuring for pserver
2462 @cindex xinetd, configuring for pserver
2463 @c FIXME: this isn't quite right regarding port
2464 @c numbers; CVS looks up "cvspserver" in
2465 @c /etc/services (on unix, but what about non-unix?).
2466 On the server side, the file @file{/etc/inetd.conf}
2467 needs to be edited so @code{inetd} knows to run the
2468 command @code{cvs pserver} when it receives a
2469 connection on the right port. By default, the port
2470 number is 2401; it would be different if your client
2471 were compiled with @code{CVS_AUTH_PORT} defined to
2472 something else, though. This can also be specified in the CVSROOT variable
2473 (@pxref{Remote repositories}) or overridden with the CVS_CLIENT_PORT
2474 environment variable (@pxref{Environment variables}).
2476 If your @code{inetd} allows raw port numbers in
2477 @file{/etc/inetd.conf}, then the following (all on a
2478 single line in @file{inetd.conf}) should be sufficient:
2481 2401 stream tcp nowait root /usr/local/bin/cvs
2482 cvs -f --allow-root=/usr/cvsroot pserver
2486 (You could also use the
2487 @samp{-T} option to specify a temporary directory.)
2489 The @samp{--allow-root} option specifies the allowable
2490 @sc{cvsroot} directory. Clients which attempt to use a
2491 different @sc{cvsroot} directory will not be allowed to
2492 connect. If there is more than one @sc{cvsroot}
2493 directory which you want to allow, repeat the option.
2494 (Unfortunately, many versions of @code{inetd} have very small
2495 limits on the number of arguments and/or the total length
2496 of the command. The usual solution to this problem is
2497 to have @code{inetd} run a shell script which then invokes
2498 @sc{cvs} with the necessary arguments.)
2500 If your @code{inetd} wants a symbolic service
2501 name instead of a raw port number, then put this in
2502 @file{/etc/services}:
2509 and put @code{cvspserver} instead of @code{2401} in @file{inetd.conf}.
2511 If your system uses @code{xinetd} instead of @code{inetd},
2512 the procedure is slightly different.
2513 Create a file called @file{/etc/xinetd.d/cvspserver} containing the following:
2519 socket_type = stream
2524 server = /usr/local/bin/cvs
2525 server_args = -f --allow-root=/usr/cvsroot pserver
2530 (If @code{cvspserver} is defined in @file{/etc/services}, you can omit
2531 the @code{port} line.)
2533 Once the above is taken care of, restart your
2534 @code{inetd}, or do whatever is necessary to force it
2535 to reread its initialization files.
2537 If you are having trouble setting this up, see
2540 @cindex CVS passwd file
2541 @cindex passwd (admin file)
2542 Because the client stores and transmits passwords in
2543 cleartext (almost---see @ref{Password authentication
2544 security}, for details), a separate @sc{cvs} password
2545 file is generally used, so people don't compromise
2546 their regular passwords when they access the
2547 repository. This file is
2548 @file{$CVSROOT/CVSROOT/passwd} (@pxref{Intro
2549 administrative files}). It uses a colon-separated
2550 format, similar to @file{/etc/passwd} on Unix systems,
2551 except that it has fewer fields: @sc{cvs} username,
2552 optional password, and an optional system username for
2553 @sc{cvs} to run as if authentication succeeds. Here is
2554 an example @file{passwd} file with five entries:
2559 spwang:1sOp854gDF3DY
2560 melissa:tGX1fS8sun6rY:pubcvs
2561 qproj:XR4EZcEs0szik:pubcvs
2565 (The passwords are encrypted according to the standard
2566 Unix @code{crypt()} function, so it is possible to
2567 paste in passwords directly from regular Unix
2568 @file{/etc/passwd} files.)
2570 The first line in the example will grant access to any
2571 @sc{cvs} client attempting to authenticate as user
2572 @code{anonymous}, no matter what password they use,
2573 including an empty password. (This is typical for
2574 sites granting anonymous read-only access; for
2575 information on how to do the "read-only" part, see
2576 @ref{Read-only access}.)
2578 The second and third lines will grant access to
2579 @code{bach} and @code{spwang} if they supply their
2580 respective plaintext passwords.
2582 @cindex User aliases
2583 The fourth line will grant access to @code{melissa}, if
2584 she supplies the correct password, but her @sc{cvs}
2585 operations will actually run on the server side under
2586 the system user @code{pubcvs}. Thus, there need not be
2587 any system user named @code{melissa}, but there
2588 @emph{must} be one named @code{pubcvs}.
2590 The fifth line shows that system user identities can be
2591 shared: any client who successfully authenticates as
2592 @code{qproj} will actually run as @code{pubcvs}, just
2593 as @code{melissa} does. That way you could create a
2594 single, shared system user for each project in your
2595 repository, and give each developer their own line in
2596 the @file{$CVSROOT/CVSROOT/passwd} file. The @sc{cvs}
2597 username on each line would be different, but the
2598 system username would be the same. The reason to have
2599 different @sc{cvs} usernames is that @sc{cvs} will log their
2600 actions under those names: when @code{melissa} commits
2601 a change to a project, the checkin is recorded in the
2602 project's history under the name @code{melissa}, not
2603 @code{pubcvs}. And the reason to have them share a
2604 system username is so that you can arrange permissions
2605 in the relevant area of the repository such that only
2606 that account has write-permission there.
2608 If the system-user field is present, all
2609 password-authenticated @sc{cvs} commands run as that
2610 user; if no system user is specified, @sc{cvs} simply
2611 takes the @sc{cvs} username as the system username and
2612 runs commands as that user. In either case, if there
2613 is no such user on the system, then the @sc{cvs}
2614 operation will fail (regardless of whether the client
2615 supplied a valid password).
2617 The password and system-user fields can both be omitted
2618 (and if the system-user field is omitted, then also
2619 omit the colon that would have separated it from the
2620 encrypted password). For example, this would be a
2621 valid @file{$CVSROOT/CVSROOT/passwd} file:
2625 fish:rKa5jzULzmhOo:kfogel
2626 sussman:1sOp854gDF3DY
2630 When the password field is omitted or empty, then the
2631 client's authentication attempt will succeed with any
2632 password, including the empty string. However, the
2633 colon after the @sc{cvs} username is always necessary,
2634 even if the password is empty.
2636 @sc{cvs} can also fall back to use system authentication.
2637 When authenticating a password, the server first checks
2638 for the user in the @file{$CVSROOT/CVSROOT/passwd}
2639 file. If it finds the user, it will use that entry for
2640 authentication as described above. But if it does not
2641 find the user, or if the @sc{cvs} @file{passwd} file
2642 does not exist, then the server can try to authenticate
2643 the username and password using the operating system's
2644 user-lookup routines (this "fallback" behavior can be
2645 disabled by setting @code{SystemAuth=no} in the
2646 @sc{cvs} @file{config} file, @pxref{config}).
2648 The default fallback behavior is to look in
2649 @file{/etc/passwd} for this system user unless your
2650 system has PAM (Pluggable Authentication Modules)
2651 and your @sc{cvs} server executable was configured to
2652 use it at compile time (using @code{./configure --enable-pam} - see the
2653 INSTALL file for more). In this case, PAM will be consulted instead.
2654 This means that @sc{cvs} can be configured to use any password
2655 authentication source PAM can be configured to use (possibilities
2656 include a simple UNIX password, NIS, LDAP, and others) in its
2657 global configuration file (usually @file{/etc/pam.conf}
2658 or possibly @file{/etc/pam.d/cvs}). See your PAM documentation
2659 for more details on PAM configuration.
2661 Note that PAM is an experimental feature in @sc{cvs} and feedback is
2662 encouraged. Please send a mail to one of the @sc{cvs} mailing lists
2663 (@code{info-cvs@@gnu.org} or @code{bug-cvs@@gnu.org}) if you use the
2664 @sc{cvs} PAM support.
2666 @strong{WARNING: Using PAM gives the system administrator much more
2667 flexibility about how @sc{cvs} users are authenticated but
2668 no more security than other methods. See below for more.}
2670 CVS needs an "auth", "account" and "session" module in the
2671 PAM configuration file. A typical PAM configuration
2672 would therefore have the following lines
2673 in @file{/etc/pam.conf} to emulate the standard @sc{cvs}
2674 system @file{/etc/passwd} authentication:
2677 cvs auth required pam_unix.so
2678 cvs account required pam_unix.so
2679 cvs session required pam_unix.so
2682 The the equivalent @file{/etc/pam.d/cvs} would contain
2685 auth required pam_unix.so
2686 account required pam_unix.so
2687 session required pam_unix.so
2690 Some systems require a full path to the module so that
2691 @file{pam_unix.so} (Linux) would become something like
2692 @file{/usr/lib/security/$ISA/pam_unix.so.1} (Sun Solaris).
2693 See the @file{contrib/pam} subdirectory of the @sc{cvs}
2694 source distribution for further example configurations.
2696 The PAM service name given above as "cvs" is just
2697 the service name in the default configuration and can be
2699 @code{./configure --with-hardcoded-pam-service-name=<pam-service-name>}
2700 before compiling. @sc{cvs} can also be configured to use whatever
2701 name it is invoked as as its PAM service name using
2702 @code{./configure --without-hardcoded-pam-service-name}, but this
2703 feature should not be used if you may not have control of the name
2704 @sc{cvs} will be invoked as.
2706 Be aware, also, that falling back to system
2707 authentication might be a security risk: @sc{cvs}
2708 operations would then be authenticated with that user's
2709 regular login password, and the password flies across
2710 the network in plaintext. See @ref{Password
2711 authentication security} for more on this.
2712 This may be more of a problem with PAM authentication
2713 because it is likely that the source of the system
2714 password is some central authentication service like
2715 LDAP which is also used to authenticate other services.
2717 On the other hand, PAM makes it very easy to change your password
2718 regularly. If they are given the option of a one-password system for
2719 all of their activities, users are often more willing to change their
2720 password on a regular basis.
2722 In the non-PAM configuration where the password is stored in the
2723 @file{CVSROOT/passwd} file, it is difficult to change passwords on a
2724 regular basis since only administrative users (or in some cases
2725 processes that act as an administrative user) are typically given
2726 access to modify this file. Either there needs to be some
2727 hand-crafted web page or set-uid program to update the file, or the
2728 update needs to be done by submitting a request to an administrator to
2729 perform the duty by hand. In the first case, having to remember to
2730 update a separate password on a periodic basis can be difficult. In
2731 the second case, the manual nature of the change will typically mean
2732 that the password will not be changed unless it is absolutely
2735 Note that PAM administrators should probably avoid configuring
2736 one-time-passwords (OTP) for @sc{cvs} authentication/authorization. If
2737 OTPs are desired, the administrator may wish to encourage the use of
2738 one of the other Client/Server access methods. See the section on
2739 @pxref{Remote repositories} for a list of other methods.
2741 Right now, the only way to put a password in the
2742 @sc{cvs} @file{passwd} file is to paste it there from
2743 somewhere else. Someday, there may be a @code{cvs
2746 Unlike many of the files in @file{$CVSROOT/CVSROOT}, it
2747 is normal to edit the @file{passwd} file in-place,
2748 rather than via @sc{cvs}. This is because of the
2749 possible security risks of having the @file{passwd}
2750 file checked out to people's working copies. If you do
2751 want to include the @file{passwd} file in checkouts of
2752 @file{$CVSROOT/CVSROOT}, see @ref{checkoutlist}.
2754 @c We might also suggest using the @code{htpasswd} command
2755 @c from freely available web servers as well, but that
2756 @c would open up a can of worms in that the users next
2757 @c questions are likely to be "where do I get it?" and
2758 @c "how do I use it?"
2759 @c Also note that htpasswd, at least the version I had,
2760 @c likes to clobber the third field.
2762 @node Password authentication client
2763 @subsubsection Using the client with password authentication
2764 @cindex Login (subcommand)
2765 @cindex Password client, using
2766 @cindex Authenticated client, using
2767 @cindex :pserver:, setting up
2768 To run a @sc{cvs} command on a remote repository via
2769 the password-authenticating server, one specifies the
2770 @code{pserver} protocol, optional username, repository host, an
2771 optional port number, and path to the repository. For example:
2774 cvs -d :pserver:faun.example.org:/usr/local/cvsroot checkout someproj
2781 CVSROOT=:pserver:bach@@faun.example.org:2401/usr/local/cvsroot
2782 cvs checkout someproj
2785 However, unless you're connecting to a public-access
2786 repository (i.e., one where that username doesn't
2787 require a password), you'll need to supply a password or @dfn{log in} first.
2788 Logging in verifies your password with the repository and stores it in a file.
2789 It's done with the @code{login} command, which will
2790 prompt you interactively for the password if you didn't supply one as part of
2794 cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot login
2802 cvs -d :pserver:bach:p4ss30rd@@faun.example.org:/usr/local/cvsroot login
2805 After you enter the password, @sc{cvs} verifies it with
2806 the server. If the verification succeeds, then that
2807 combination of username, host, repository, and password
2808 is permanently recorded, so future transactions with
2809 that repository won't require you to run @code{cvs
2810 login}. (If verification fails, @sc{cvs} will exit
2811 complaining that the password was incorrect, and
2812 nothing will be recorded.)
2814 The records are stored, by default, in the file
2815 @file{$HOME/.cvspass}. That file's format is
2816 human-readable, and to a degree human-editable, but
2817 note that the passwords are not stored in
2818 cleartext---they are trivially encoded to protect them
2819 from "innocent" compromise (i.e., inadvertent viewing
2820 by a system administrator or other non-malicious
2823 @cindex CVS_PASSFILE, environment variable
2824 You can change the default location of this file by
2825 setting the @code{CVS_PASSFILE} environment variable.
2826 If you use this variable, make sure you set it
2827 @emph{before} @code{cvs login} is run. If you were to
2828 set it after running @code{cvs login}, then later
2829 @sc{cvs} commands would be unable to look up the
2830 password for transmission to the server.
2832 Once you have logged in, all @sc{cvs} commands using
2833 that remote repository and username will authenticate
2834 with the stored password. So, for example
2837 cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot checkout foo
2841 should just work (unless the password changes on the
2842 server side, in which case you'll have to re-run
2845 Note that if the @samp{:pserver:} were not present in
2846 the repository specification, @sc{cvs} would assume it
2847 should use @code{rsh} to connect with the server
2848 instead (@pxref{Connecting via rsh}).
2850 Of course, once you have a working copy checked out and
2851 are running @sc{cvs} commands from within it, there is
2852 no longer any need to specify the repository
2853 explicitly, because @sc{cvs} can deduce the repository
2854 from the working copy's @file{CVS} subdirectory.
2856 @c FIXME: seems to me this needs somewhat more
2858 @cindex Logout (subcommand)
2859 The password for a given remote repository can be
2860 removed from the @code{CVS_PASSFILE} by using the
2861 @code{cvs logout} command.
2863 @node Password authentication security
2864 @subsubsection Security considerations with password authentication
2866 @cindex Security, of pserver
2867 The passwords are stored on the client side in a
2868 trivial encoding of the cleartext, and transmitted in
2869 the same encoding. The encoding is done only to
2870 prevent inadvertent password compromises (i.e., a
2871 system administrator accidentally looking at the file),
2872 and will not prevent even a naive attacker from gaining
2875 @c FIXME: The bit about "access to the repository
2876 @c implies general access to the system is *not* specific
2877 @c to pserver; it applies to kerberos and SSH and
2878 @c everything else too. Should reorganize the
2879 @c documentation to make this clear.
2880 The separate @sc{cvs} password file (@pxref{Password
2881 authentication server}) allows people
2882 to use a different password for repository access than
2883 for login access. On the other hand, once a user has
2885 access to the repository, she can execute programs on
2886 the server system through a variety of means. Thus, repository
2887 access implies fairly broad system access as well. It
2888 might be possible to modify @sc{cvs} to prevent that,
2889 but no one has done so as of this writing.
2890 @c OpenBSD uses chroot() and copies the repository to
2891 @c provide anonymous read-only access (for details see
2892 @c http://www.openbsd.org/anoncvs.shar). While this
2893 @c closes the most obvious holes, I'm not sure it
2894 @c closes enough holes to recommend it (plus it is
2895 @c *very* easy to accidentally screw up a setup of this
2898 Note that because the @file{$CVSROOT/CVSROOT} directory
2899 contains @file{passwd} and other files which are used
2900 to check security, you must control the permissions on
2901 this directory as tightly as the permissions on
2902 @file{/etc}. The same applies to the @file{$CVSROOT}
2903 directory itself and any directory
2904 above it in the tree. Anyone who has write access to
2905 such a directory will have the ability to become any
2906 user on the system. Note that these permissions are
2907 typically tighter than you would use if you are not
2909 @c TODO: Would be really nice to document/implement a
2910 @c scheme where the CVS server can run as some non-root
2911 @c user, e.g. "cvs". CVSROOT/passwd would contain a
2912 @c bunch of entries of the form foo:xxx:cvs (or the "cvs"
2913 @c would be implicit). This would greatly reduce
2914 @c security risks such as those hinted at in the
2915 @c previous paragraph. I think minor changes to CVS
2916 @c might be required but mostly this would just need
2917 @c someone who wants to play with it, document it, &c.
2919 In summary, anyone who gets the password gets
2920 repository access (which may imply some measure of general system
2921 access as well). The password is available to anyone
2922 who can sniff network packets or read a protected
2923 (i.e., user read-only) file. If you want real
2924 security, get Kerberos.
2926 @node GSSAPI authenticated
2927 @subsection Direct connection with GSSAPI
2930 @cindex Security, GSSAPI
2931 @cindex :gserver:, setting up
2932 @cindex Kerberos, using :gserver:
2933 GSSAPI is a generic interface to network security
2934 systems such as Kerberos 5.
2935 If you have a working GSSAPI library, you can have
2936 @sc{cvs} connect via a direct @sc{tcp} connection,
2937 authenticating with GSSAPI.
2939 To do this, @sc{cvs} needs to be compiled with GSSAPI
2940 support; when configuring @sc{cvs} it tries to detect
2941 whether GSSAPI libraries using Kerberos version 5 are
2942 present. You can also use the @file{--with-gssapi}
2945 The connection is authenticated using GSSAPI, but the
2946 message stream is @emph{not} authenticated by default.
2947 You must use the @code{-a} global option to request
2948 stream authentication.
2950 The data transmitted is @emph{not} encrypted by
2951 default. Encryption support must be compiled into both
2952 the client and the server; use the
2953 @file{--enable-encrypt} configure option to turn it on.
2954 You must then use the @code{-x} global option to
2957 GSSAPI connections are handled on the server side by
2958 the same server which handles the password
2959 authentication server; see @ref{Password authentication
2960 server}. If you are using a GSSAPI mechanism such as
2961 Kerberos which provides for strong authentication, you
2962 will probably want to disable the ability to
2963 authenticate via cleartext passwords. To do so, create
2964 an empty @file{CVSROOT/passwd} password file, and set
2965 @code{SystemAuth=no} in the config file
2968 The GSSAPI server uses a principal name of
2969 cvs/@var{hostname}, where @var{hostname} is the
2970 canonical name of the server host. You will have to
2971 set this up as required by your GSSAPI mechanism.
2973 To connect using GSSAPI, use the @samp{:gserver:} method. For
2977 cvs -d :gserver:faun.example.org:/usr/local/cvsroot checkout foo
2980 @node Kerberos authenticated
2981 @subsection Direct connection with Kerberos
2983 @cindex Kerberos, using :kserver:
2984 @cindex Security, Kerberos
2985 @cindex :kserver:, setting up
2986 The easiest way to use Kerberos is to use the Kerberos
2987 @code{rsh}, as described in @ref{Connecting via rsh}.
2988 The main disadvantage of using rsh is that all the data
2989 needs to pass through additional programs, so it may be
2990 slower. So if you have Kerberos installed you can
2991 connect via a direct @sc{tcp} connection,
2992 authenticating with Kerberos.
2994 This section concerns the Kerberos network security
2995 system, version 4. Kerberos version 5 is supported via
2996 the GSSAPI generic network security interface, as
2997 described in the previous section.
2999 To do this, @sc{cvs} needs to be compiled with Kerberos
3000 support; when configuring @sc{cvs} it tries to detect
3001 whether Kerberos is present or you can use the
3002 @file{--with-krb4} flag to configure.
3004 The data transmitted is @emph{not} encrypted by
3005 default. Encryption support must be compiled into both
3006 the client and server; use the
3007 @file{--enable-encryption} configure option to turn it
3008 on. You must then use the @code{-x} global option to
3011 The CVS client will attempt to connect to port 1999 by default.
3014 When you want to use @sc{cvs}, get a ticket in the
3015 usual way (generally @code{kinit}); it must be a ticket
3016 which allows you to log into the server machine. Then
3017 you are ready to go:
3020 cvs -d :kserver:faun.example.org:/usr/local/cvsroot checkout foo
3023 Previous versions of @sc{cvs} would fall back to a
3024 connection via rsh; this version will not do so.
3026 @node Connecting via fork
3027 @subsection Connecting with fork
3029 @cindex fork, access method
3030 @cindex :fork:, setting up
3031 This access method allows you to connect to a
3032 repository on your local disk via the remote protocol.
3033 In other words it does pretty much the same thing as
3034 @code{:local:}, but various quirks, bugs and the like are
3035 those of the remote @sc{cvs} rather than the local
3038 For day-to-day operations you might prefer either
3039 @code{:local:} or @code{:fork:}, depending on your
3040 preferences. Of course @code{:fork:} comes in
3041 particularly handy in testing or
3042 debugging @code{cvs} and the remote protocol.
3043 Specifically, we avoid all of the network-related
3044 setup/configuration, timeouts, and authentication
3045 inherent in the other remote access methods but still
3046 create a connection which uses the remote protocol.
3048 To connect using the @code{fork} method, use
3049 @samp{:fork:} and the pathname to your local
3050 repository. For example:
3053 cvs -d :fork:/usr/local/cvsroot checkout foo
3056 @cindex CVS_SERVER, and :fork:
3057 As with @code{:ext:}, the server is called @samp{cvs}
3058 by default, or the value of the @code{CVS_SERVER}
3059 environment variable.
3063 @subsection Distributing load across several CVS servers
3065 @cindex PrimaryServer, in CVSROOT/config
3066 @cindex Primary server
3067 @cindex Secondary server
3068 @cindex proxy, write
3070 @sc{cvs} can be configured to distribute usage across several @sc{cvs}
3071 servers. This is accomplished by means of one or more @dfn{write proxies}, or
3072 @dfn{secondary servers}, for a single @dfn{primary server}.
3074 When a @sc{cvs} client accesses a secondary server and only sends read
3075 requests, then the secondary server handles the entire request. If the client
3076 sends any write requests, however, the secondary server asks the client to
3077 redirect its write request to the primary server, if the client supports
3078 redirect requests, and otherwise becomes a transparent proxy for the primary
3079 server, which actually handles the write request.
3081 In this manner, any number of read-only secondary servers may be configured as
3082 write proxies for the primary server, effectively distributing the load from
3083 all read operations between the secondary servers and restricting the load on
3084 the primary server to write operations and pushing changes to the secondaries.
3086 Primary servers will not automatically push changes to secondaries. This must
3087 be configured via @file{loginfo}, @file{postadmin}, @file{posttag}, &
3088 @file{postwatch} scripts (@pxref{script hooks}) like the following:
3091 ALL rsync -gopr -essh ./ secondary:/cvsroot/%p &
3094 You would probably actually want to lock directories for write on the secondary
3095 and for read on the primary before running the @samp{rsync} in the above
3096 example, but describing such a setup is beyond the scope of this document.
3098 A secondary advantage of a write proxy setup is that users pointing at the
3099 secondary server can still execute fast read operations while on a network that
3100 connects to the primary over a slow link or even one where the link to the
3101 primary is periodically broken. Only write operations will require the network
3102 link to the primary.
3104 To configure write proxies, the primary must be specified with the
3105 @samp{PrimaryServer} option in @file{CVSROOT/config} (@pxref{config}). For the
3106 transparent proxy mode to work, all secondary servers must also be running the
3107 same version of the @sc{cvs} server, or at least one that provides the same
3108 list of supported requests to the client as the primary server. This is not
3109 necessary for redirection.
3111 Once a primary server is configured, secondary servers may be configured by:
3115 Duplicating the primary repository at the new location.
3117 Setting up the @file{loginfo}, @file{postadmin}, @file{posttag}, and
3118 @file{postwatch} files on the primary to propagate writes to the new secondary.
3120 Configure remote access to the secondary(ies) as you would configure access
3121 to any other CVS server (@pxref{Remote repositories}).
3123 Ensuring that @code{--allow-root=@var{secondary-cvsroot}} is passed to
3124 @strong{all} incovations of the secondary server if the path to the @sc{cvs}
3125 repository directory is different on the two servers and you wish to support
3126 clients that do not handle the @samp{Redirect} resopnse (CVS 1.12.9 and earlier
3127 clients do not handle the @samp{Redirect} response).
3129 Please note, again, that writethrough proxy suport requires
3130 @code{--allow-root=@var{secondary-cvsroot}} to be specified for @strong{all}
3131 incovations of the secondary server, not just @samp{pserver} invocations.
3132 This may require a wrapper script for the @sc{cvs} executable
3133 on your server machine.
3137 @c ---------------------------------------------------------------------
3138 @node Read-only access
3139 @section Read-only repository access
3140 @cindex Read-only repository access
3141 @cindex readers (admin file)
3142 @cindex writers (admin file)
3144 It is possible to grant read-only repository
3145 access to people using the password-authenticated
3146 server (@pxref{Password authenticated}). (The
3147 other access methods do not have explicit support for
3148 read-only users because those methods all assume login
3149 access to the repository machine anyway, and therefore
3150 the user can do whatever local file permissions allow
3153 A user who has read-only access can do only
3154 those @sc{cvs} operations which do not modify the
3155 repository, except for certain ``administrative'' files
3156 (such as lock files and the history file). It may be
3157 desirable to use this feature in conjunction with
3158 user-aliasing (@pxref{Password authentication server}).
3160 Unlike with previous versions of @sc{cvs}, read-only
3161 users should be able merely to read the repository, and
3162 not to execute programs on the server or otherwise gain
3163 unexpected levels of access. Or to be more accurate,
3164 the @emph{known} holes have been plugged. Because this
3165 feature is new and has not received a comprehensive
3166 security audit, you should use whatever level of
3167 caution seems warranted given your attitude concerning
3170 There are two ways to specify read-only access
3171 for a user: by inclusion, and by exclusion.
3173 "Inclusion" means listing that user
3174 specifically in the @file{$CVSROOT/CVSROOT/readers}
3175 file, which is simply a newline-separated list of
3176 users. Here is a sample @file{readers} file:
3185 (Don't forget the newline after the last user.)
3187 "Exclusion" means explicitly listing everyone
3188 who has @emph{write} access---if the file
3191 $CVSROOT/CVSROOT/writers
3196 those users listed in it have write access, and
3197 everyone else has read-only access (of course, even the
3198 read-only users still need to be listed in the
3199 @sc{cvs} @file{passwd} file). The
3200 @file{writers} file has the same format as the
3201 @file{readers} file.
3203 Note: if your @sc{cvs} @file{passwd}
3204 file maps cvs users onto system users (@pxref{Password
3205 authentication server}), make sure you deny or grant
3206 read-only access using the @emph{cvs} usernames, not
3207 the system usernames. That is, the @file{readers} and
3208 @file{writers} files contain cvs usernames, which may
3209 or may not be the same as system usernames.
3211 Here is a complete description of the server's
3212 behavior in deciding whether to grant read-only or
3215 If @file{readers} exists, and this user is
3216 listed in it, then she gets read-only access. Or if
3217 @file{writers} exists, and this user is NOT listed in
3218 it, then she also gets read-only access (this is true
3219 even if @file{readers} exists but she is not listed
3220 there). Otherwise, she gets full read-write access.
3222 Of course there is a conflict if the user is
3223 listed in both files. This is resolved in the more
3224 conservative way, it being better to protect the
3225 repository too much than too little: such a user gets
3228 @node Server temporary directory
3229 @section Temporary directories for the server
3230 @cindex Temporary directories, and server
3231 @cindex Server, temporary directories
3233 While running, the @sc{cvs} server creates temporary
3234 directories. They are named
3241 where @var{pid} is the process identification number of
3243 They are located in the directory specified by
3244 the @samp{-T} global option (@pxref{Global options}),
3245 the @code{TMPDIR} environment variable (@pxref{Environment variables}),
3246 or, failing that, @file{/tmp}.
3248 In most cases the server will remove the temporary
3249 directory when it is done, whether it finishes normally
3250 or abnormally. However, there are a few cases in which
3251 the server does not or cannot remove the temporary
3252 directory, for example:
3256 If the server aborts due to an internal server error,
3257 it may preserve the directory to aid in debugging
3260 If the server is killed in a way that it has no way of
3261 cleaning up (most notably, @samp{kill -KILL} on unix).
3264 If the system shuts down without an orderly shutdown,
3265 which tells the server to clean up.
3268 In cases such as this, you will need to manually remove
3269 the @file{cvs-serv@var{pid}} directories. As long as
3270 there is no server running with process identification
3271 number @var{pid}, it is safe to do so.
3273 @c ---------------------------------------------------------------------
3274 @node Starting a new project
3275 @chapter Starting a project with CVS
3276 @cindex Starting a project with CVS
3277 @cindex Creating a project
3279 @comment --moduledb--
3280 Because renaming files and moving them between
3281 directories is somewhat inconvenient, the first thing
3282 you do when you start a new project should be to think
3283 through your file organization. It is not impossible
3284 to rename or move files, but it does increase the
3285 potential for confusion and @sc{cvs} does have some
3286 quirks particularly in the area of renaming
3287 directories. @xref{Moving files}.
3289 What to do next depends on the situation at hand.
3292 * Setting up the files:: Getting the files into the repository
3293 * Defining the module:: How to make a module of the files
3295 @c -- File permissions!
3297 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3298 @node Setting up the files
3299 @section Setting up the files
3301 The first step is to create the files inside the repository. This can
3302 be done in a couple of different ways.
3304 @c -- The contributed scripts
3306 * From files:: This method is useful with old projects
3307 where files already exists.
3308 * From other version control systems:: Old projects where you want to
3309 preserve history from another system.
3310 * From scratch:: Creating a directory tree from scratch.
3313 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3315 @subsection Creating a directory tree from a number of files
3316 @cindex Importing files
3318 When you begin using @sc{cvs}, you will probably already have several
3319 projects that can be
3320 put under @sc{cvs} control. In these cases the easiest way is to use the
3321 @code{import} command. An example is probably the easiest way to
3322 explain how to use it. If the files you want to install in
3323 @sc{cvs} reside in @file{@var{wdir}}, and you want them to appear in the
3324 repository as @file{$CVSROOT/yoyodyne/@var{rdir}}, you can do this:
3328 $ cvs import -m "Imported sources" yoyodyne/@var{rdir} yoyo start
3331 Unless you supply a log message with the @samp{-m}
3332 flag, @sc{cvs} starts an editor and prompts for a
3333 message. The string @samp{yoyo} is a @dfn{vendor tag},
3334 and @samp{start} is a @dfn{release tag}. They may fill
3335 no purpose in this context, but since @sc{cvs} requires
3336 them they must be present. @xref{Tracking sources}, for
3337 more information about them.
3339 You can now verify that it worked, and remove your
3340 original source directory.
3341 @c FIXME: Need to say more about "verify that it
3342 @c worked". What should the user look for in the output
3347 $ cvs checkout yoyodyne/@var{rdir} # @r{Explanation below}
3348 $ diff -r @var{wdir} yoyodyne/@var{rdir}
3353 Erasing the original sources is a good idea, to make sure that you do
3354 not accidentally edit them in @var{wdir}, bypassing @sc{cvs}.
3355 Of course, it would be wise to make sure that you have
3356 a backup of the sources before you remove them.
3358 The @code{checkout} command can either take a module
3359 name as argument (as it has done in all previous
3360 examples) or a path name relative to @code{$CVSROOT},
3361 as it did in the example above.
3363 It is a good idea to check that the permissions
3364 @sc{cvs} sets on the directories inside @code{$CVSROOT}
3365 are reasonable, and that they belong to the proper
3366 groups. @xref{File permissions}.
3368 If some of the files you want to import are binary, you
3369 may want to use the wrappers features to specify which
3370 files are binary and which are not. @xref{Wrappers}.
3372 @c The node name is too long, but I am having trouble
3373 @c thinking of something more concise.
3374 @node From other version control systems
3375 @subsection Creating Files From Other Version Control Systems
3376 @cindex Importing files, from other version control systems
3378 If you have a project which you are maintaining with
3379 another version control system, such as @sc{rcs}, you
3380 may wish to put the files from that project into
3381 @sc{cvs}, and preserve the revision history of the
3385 @cindex RCS, importing files from
3387 If you have been using @sc{rcs}, find the @sc{rcs}
3388 files---usually a file named @file{foo.c} will have its
3389 @sc{rcs} file in @file{RCS/foo.c,v} (but it could be
3390 other places; consult the @sc{rcs} documentation for
3391 details). Then create the appropriate directories in
3392 @sc{cvs} if they do not already exist. Then copy the
3393 files into the appropriate directories in the @sc{cvs}
3394 repository (the name in the repository must be the name
3395 of the source file with @samp{,v} added; the files go
3396 directly in the appropriate directory of the repository,
3397 not in an @file{RCS} subdirectory). This is one of the
3398 few times when it is a good idea to access the @sc{cvs}
3399 repository directly, rather than using @sc{cvs}
3400 commands. Then you are ready to check out a new
3402 @c Someday there probably should be a "cvs import -t
3403 @c rcs" or some such. It could even create magic
3404 @c branches. It could also do something about the case
3405 @c where the RCS file had a (non-magic) "0" branch.
3407 The @sc{rcs} file should not be locked when you move it
3408 into @sc{cvs}; if it is, @sc{cvs} will have trouble
3409 letting you operate on it.
3410 @c What is the easiest way to unlock your files if you
3411 @c have them locked? Especially if you have a lot of them?
3412 @c This is a CVS bug/misfeature; importing RCS files
3413 @c should ignore whether they are locked and leave them in
3414 @c an unlocked state. Yet another reason for a separate
3415 @c "import RCS file" command.
3417 @c How many is "many"? Or do they just import RCS files?
3418 @item From another version control system
3419 Many version control systems have the ability to export
3420 @sc{rcs} files in the standard format. If yours does,
3421 export the @sc{rcs} files and then follow the above
3424 Failing that, probably your best bet is to write a
3425 script that will check out the files one revision at a
3426 time using the command line interface to the other
3427 system, and then check the revisions into @sc{cvs}.
3428 The @file{sccs2rcs} script mentioned below may be a
3429 useful example to follow.
3431 @cindex SCCS, importing files from
3433 There is a script in the @file{contrib} directory of
3434 the @sc{cvs} source distribution called @file{sccs2rcs}
3435 which converts @sc{sccs} files to @sc{rcs} files.
3436 Note: you must run it on a machine which has both
3437 @sc{sccs} and @sc{rcs} installed, and like everything
3438 else in contrib it is unsupported (your mileage may
3441 @cindex PVCS, importing files from
3443 There is a script in the @file{contrib} directory of
3444 the @sc{cvs} source distribution called @file{pvcs_to_rcs}
3445 which converts @sc{pvcs} archives to @sc{rcs} files.
3446 You must run it on a machine which has both
3447 @sc{pvcs} and @sc{rcs} installed, and like everything
3448 else in contrib it is unsupported (your mileage may
3449 vary). See the comments in the script for details.
3451 @c CMZ and/or PATCHY were systems that were used in the
3452 @c high energy physics community (especially for
3453 @c CERNLIB). CERN has replaced them with CVS, but the
3454 @c CAR format seems to live on as a way to submit
3455 @c changes. There is a program car2cvs which converts
3456 @c but I'm not sure where one gets a copy.
3457 @c Not sure it is worth mentioning here, since it would
3458 @c appear to affect only one particular community.
3459 @c Best page for more information is:
3460 @c http://wwwcn1.cern.ch/asd/cvs/index.html
3462 @c http://ecponion.cern.ch/ecpsa/cernlib.html
3464 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3466 @subsection Creating a directory tree from scratch
3468 @c Also/instead should be documenting
3476 @c Using import to create the directories only is
3477 @c probably a somewhat confusing concept.
3478 For a new project, the easiest thing to do is probably
3479 to create an empty directory structure, like this:
3487 After that, you use the @code{import} command to create
3488 the corresponding (empty) directory structure inside
3493 $ cvs import -m "Created directory structure" yoyodyne/@var{dir} yoyo start
3496 This will add yoyodyne/@var{dir} as a directory under
3499 Then, use @code{add} to add files (and new directories)
3502 Check that the permissions @sc{cvs} sets on the
3503 directories inside @code{$CVSROOT} are reasonable.
3505 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3506 @node Defining the module
3507 @section Defining the module
3508 @cindex Defining a module
3509 @cindex Editing the modules file
3510 @cindex Module, defining
3511 @cindex Modules file, changing
3513 The next step is to define the module in the
3514 @file{modules} file. This is not strictly necessary,
3515 but modules can be convenient in grouping together
3516 related files and directories.
3518 In simple cases these steps are sufficient to define a module.
3522 Get a working copy of the modules file.
3525 $ cvs checkout CVSROOT/modules
3530 Edit the file and insert a line that defines the module. @xref{Intro
3531 administrative files}, for an introduction. @xref{modules}, for a full
3532 description of the modules file. You can use the
3533 following line to define the module @samp{tc}:
3540 Commit your changes to the modules file.
3543 $ cvs commit -m "Added the tc module." modules
3547 Release the modules module.
3551 $ cvs release -d CVSROOT
3555 @c ---------------------------------------------------------------------
3559 For many uses of @sc{cvs}, one doesn't need to worry
3560 too much about revision numbers; @sc{cvs} assigns
3561 numbers such as @code{1.1}, @code{1.2}, and so on, and
3562 that is all one needs to know. However, some people
3563 prefer to have more knowledge and control concerning
3564 how @sc{cvs} assigns revision numbers.
3566 If one wants to keep track of a set of revisions
3567 involving more than one file, such as which revisions
3568 went into a particular release, one uses a @dfn{tag},
3569 which is a symbolic revision which can be assigned to a
3570 numeric revision in each file.
3573 * Revision numbers:: The meaning of a revision number
3574 * Versions revisions releases:: Terminology used in this manual
3575 * Assigning revisions:: Assigning revisions
3576 * Tags:: Tags--Symbolic revisions
3577 * Tagging the working directory:: The cvs tag command
3578 * Tagging by date/tag:: The cvs rtag command
3579 * Modifying tags:: Adding, renaming, and deleting tags
3580 * Tagging add/remove:: Tags with adding and removing files
3581 * Sticky tags:: Certain tags are persistent
3584 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3585 @node Revision numbers
3586 @section Revision numbers
3587 @cindex Revision numbers
3588 @cindex Revision tree
3589 @cindex Linear development
3590 @cindex Number, revision-
3591 @cindex Decimal revision number
3592 @cindex Branch number
3593 @cindex Number, branch
3595 Each version of a file has a unique @dfn{revision
3596 number}. Revision numbers look like @samp{1.1},
3597 @samp{1.2}, @samp{1.3.2.2} or even @samp{1.3.2.2.4.5}.
3598 A revision number always has an even number of
3599 period-separated decimal integers. By default revision
3600 1.1 is the first revision of a file. Each successive
3601 revision is given a new number by increasing the
3602 rightmost number by one. The following figure displays
3603 a few revisions, with newer revisions to the right.
3606 +-----+ +-----+ +-----+ +-----+ +-----+
3607 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
3608 +-----+ +-----+ +-----+ +-----+ +-----+
3611 It is also possible to end up with numbers containing
3612 more than one period, for example @samp{1.3.2.2}. Such
3613 revisions represent revisions on branches
3614 (@pxref{Branching and merging}); such revision numbers
3615 are explained in detail in @ref{Branches and
3618 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3619 @node Versions revisions releases
3620 @section Versions, revisions and releases
3621 @cindex Revisions, versions and releases
3622 @cindex Versions, revisions and releases
3623 @cindex Releases, revisions and versions
3625 A file can have several versions, as described above.
3626 Likewise, a software product can have several versions.
3627 A software product is often given a version number such
3630 Versions in the first sense are called @dfn{revisions}
3631 in this document, and versions in the second sense are
3632 called @dfn{releases}. To avoid confusion, the word
3633 @dfn{version} is almost never used in this document.
3635 @node Assigning revisions
3636 @section Assigning revisions
3638 @c We avoid the "major revision" terminology. It seems
3639 @c like jargon. Hopefully "first number" is clear enough.
3641 @c Well, in the context of software release numbers,
3642 @c "major" and "minor" release or version numbers are
3643 @c documented in at least the GNU Coding Standards, but I'm
3644 @c still not sure I find that a valid reason to apply the
3645 @c terminology to RCS revision numbers. "First", "Second",
3646 @c "subsequent", and so on is almost surely clearer,
3647 @c especially to a novice reader. -DRP
3648 By default, @sc{cvs} will assign numeric revisions by
3649 leaving the first number the same and incrementing the
3650 second number. For example, @code{1.1}, @code{1.2},
3653 When adding a new file, the second number will always
3654 be one and the first number will equal the highest
3655 first number of any file in that directory. For
3656 example, the current directory contains files whose
3657 highest numbered revisions are @code{1.7}, @code{3.1},
3658 and @code{4.12}, then an added file will be given the
3659 numeric revision @code{4.1}.
3660 (When using client/server @sc{cvs},
3661 only files that are actually sent to the server are considered.)
3663 @c This is sort of redundant with something we said a
3664 @c while ago. Somewhere we need a better way of
3665 @c introducing how the first number can be anything
3666 @c except "1", perhaps. Also I don't think this
3667 @c presentation is clear on why we are discussing releases
3668 @c and first numbers of numeric revisions in the same
3670 Normally there is no reason to care
3671 about the revision numbers---it is easier to treat them
3672 as internal numbers that @sc{cvs} maintains, and tags
3673 provide a better way to distinguish between things like
3674 release 1 versus release 2 of your product
3675 (@pxref{Tags}). However, if you want to set the
3676 numeric revisions, the @samp{-r} option to @code{cvs
3677 commit} can do that. The @samp{-r} option implies the
3678 @samp{-f} option, in the sense that it causes the
3679 files to be committed even if they are not modified.
3681 For example, to bring all your files up to
3682 revision 3.0 (including those that haven't changed),
3689 Note that the number you specify with @samp{-r} must be
3690 larger than any existing revision number. That is, if
3691 revision 3.0 exists, you cannot @samp{cvs commit
3692 -r 1.3}. If you want to maintain several releases in
3693 parallel, you need to use a branch (@pxref{Branching and merging}).
3695 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3697 @section Tags--Symbolic revisions
3700 The revision numbers live a life of their own. They
3701 need not have anything at all to do with the release
3702 numbers of your software product. Depending
3703 on how you use @sc{cvs} the revision numbers might change several times
3704 between two releases. As an example, some of the
3705 source files that make up @sc{rcs} 5.6 have the following
3707 @cindex RCS revision numbers
3724 @cindex tag (subcommand), introduction
3725 @cindex Tags, symbolic name
3726 @cindex Symbolic name (tag)
3727 @cindex Name, symbolic (tag)
3728 @cindex HEAD, as reserved tag name
3729 @cindex BASE, as reserved tag name
3730 You can use the @code{tag} command to give a symbolic name to a
3731 certain revision of a file. You can use the @samp{-v} flag to the
3732 @code{status} command to see all tags that a file has, and
3733 which revision numbers they represent. Tag names must
3734 start with an uppercase or lowercase letter and can
3735 contain uppercase and lowercase letters, digits,
3736 @samp{-}, and @samp{_}. The two tag names @code{BASE}
3737 and @code{HEAD} are reserved for use by @sc{cvs}. It
3738 is expected that future names which are special to
3739 @sc{cvs} will be specially named, for example by
3740 starting with @samp{.}, rather than being named analogously to
3741 @code{BASE} and @code{HEAD}, to avoid conflicts with
3743 @c Including a character such as % or = has also been
3744 @c suggested as the naming convention for future
3745 @c special tag names. Starting with . is nice because
3746 @c that is not a legal tag name as far as RCS is concerned.
3747 @c FIXME: CVS actually accepts quite a few characters
3748 @c in tag names, not just the ones documented above
3749 @c (see RCS_check_tag). RCS
3750 @c defines legitimate tag names by listing illegal
3751 @c characters rather than legal ones. CVS is said to lose its
3752 @c mind if you try to use "/" (try making such a tag sticky
3753 @c and using "cvs status" client/server--see remote
3754 @c protocol format for entries line for probable cause).
3755 @c TODO: The testsuite
3756 @c should test for whatever are documented above as
3757 @c officially-OK tag names, and CVS should at least reject
3758 @c characters that won't work, like "/".
3760 You'll want to choose some convention for naming tags,
3761 based on information such as the name of the program
3762 and the version number of the release. For example,
3763 one might take the name of the program, immediately
3764 followed by the version number with @samp{.} changed to
3765 @samp{-}, so that @sc{cvs} 1.9 would be tagged with the name
3766 @code{cvs1-9}. If you choose a consistent convention,
3767 then you won't constantly be guessing whether a tag is
3768 @code{cvs-1-9} or @code{cvs1_9} or what. You might
3769 even want to consider enforcing your convention in the
3770 @file{taginfo} file (@pxref{taginfo}).
3771 @c Might be nice to say more about using taginfo this
3772 @c way, like giving an example, or pointing out any particular
3773 @c issues which arise.
3775 @cindex Adding a tag
3776 @cindex Tags, example
3777 The following example shows how you can add a tag to a
3778 file. The commands must be issued inside your working
3779 directory. That is, you should issue the
3780 command in the directory where @file{backend.c}
3784 $ cvs tag rel-0-4 backend.c
3786 $ cvs status -v backend.c
3787 ===================================================================
3788 File: backend.c Status: Up-to-date
3790 Version: 1.4 Tue Dec 1 14:39:01 1992
3791 RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v
3794 Sticky Options: (none)
3797 rel-0-4 (revision: 1.4)
3801 For a complete summary of the syntax of @code{cvs tag},
3802 including the various options, see @ref{Invoking CVS}.
3804 There is seldom reason to tag a file in isolation. A more common use is
3805 to tag all the files that constitute a module with the same tag at
3806 strategic points in the development life-cycle, such as when a release
3820 (When you give @sc{cvs} a directory as argument, it generally applies the
3821 operation to all the files in that directory, and (recursively), to any
3822 subdirectories that it may contain. @xref{Recursive behavior}.)
3824 @cindex Retrieving an old revision using tags
3825 @cindex Tags, retrieving old revisions
3826 The @code{checkout} command has a flag, @samp{-r}, that lets you check out
3827 a certain revision of a module. This flag makes it easy to
3828 retrieve the sources that make up release 1.0 of the module @samp{tc} at
3829 any time in the future:
3832 $ cvs checkout -r rel-1-0 tc
3836 This is useful, for instance, if someone claims that there is a bug in
3837 that release, but you cannot find the bug in the current working copy.
3839 You can also check out a module as it was at any given date.
3840 @xref{checkout options}. When specifying @samp{-r} to
3841 any of these commands, you will need beware of sticky
3842 tags; see @ref{Sticky tags}.
3844 When you tag more than one file with the same tag you
3845 can think about the tag as "a curve drawn through a
3846 matrix of filename vs. revision number." Say we have 5
3847 files with the following revisions:
3851 file1 file2 file3 file4 file5
3853 1.1 1.1 1.1 1.1 /--1.1* <-*- TAG
3854 1.2*- 1.2 1.2 -1.2*-
3855 1.3 \- 1.3*- 1.3 / 1.3
3862 At some time in the past, the @code{*} versions were tagged.
3863 You can think of the tag as a handle attached to the curve
3864 drawn through the tagged revisions. When you pull on
3865 the handle, you get all the tagged revisions. Another
3866 way to look at it is that you "sight" through a set of
3867 revisions that is "flat" along the tagged revisions,
3872 file1 file2 file3 file4 file5
3878 1.2*----1.3*----1.5*----1.2*----1.1* (--- <--- Look here
3885 @node Tagging the working directory
3886 @section Specifying what to tag from the working directory
3888 @cindex tag (subcommand)
3889 The example in the previous section demonstrates one of
3890 the most common ways to choose which revisions to tag.
3891 Namely, running the @code{cvs tag} command without
3892 arguments causes @sc{cvs} to select the revisions which
3893 are checked out in the current working directory. For
3894 example, if the copy of @file{backend.c} in working
3895 directory was checked out from revision 1.4, then
3896 @sc{cvs} will tag revision 1.4. Note that the tag is
3897 applied immediately to revision 1.4 in the repository;
3898 tagging is not like modifying a file, or other
3899 operations in which one first modifies the working
3900 directory and then runs @code{cvs commit} to transfer
3901 that modification to the repository.
3903 One potentially surprising aspect of the fact that
3904 @code{cvs tag} operates on the repository is that you
3905 are tagging the checked-in revisions, which may differ
3906 from locally modified files in your working directory.
3907 If you want to avoid doing this by mistake, specify the
3908 @samp{-c} option to @code{cvs tag}. If there are any
3909 locally modified files, @sc{cvs} will abort with an
3910 error before it tags any files:
3913 $ cvs tag -c rel-0-4
3914 cvs tag: backend.c is locally modified
3915 cvs [tag aborted]: correct the above errors first!
3918 @node Tagging by date/tag
3919 @section Specifying what to tag by date or revision
3920 @cindex rtag (subcommand)
3922 The @code{cvs rtag} command tags the repository as of a
3923 certain date or time (or can be used to tag the latest
3924 revision). @code{rtag} works directly on the
3925 repository contents (it requires no prior checkout and
3926 does not look for a working directory).
3928 The following options specify which date or revision to
3929 tag. See @ref{Common options}, for a complete
3930 description of them.
3934 Tag the most recent revision no later than @var{date}.
3937 Only useful with the @samp{-D @var{date}} or @samp{-r @var{tag}}
3938 flags. If no matching revision is found, use the most
3939 recent revision (instead of ignoring the file).
3942 Only tag those files that contain existing tag @var{tag}.
3945 The @code{cvs tag} command also allows one to specify
3946 files by revision or date, using the same @samp{-r},
3947 @samp{-D}, and @samp{-f} options. However, this
3948 feature is probably not what you want. The reason is
3949 that @code{cvs tag} chooses which files to tag based on
3950 the files that exist in the working directory, rather
3951 than the files which existed as of the given tag/date.
3952 Therefore, you are generally better off using @code{cvs
3953 rtag}. The exceptions might be cases like:
3956 cvs tag -r 1.4 stable backend.c
3959 @node Modifying tags
3960 @section Deleting, moving, and renaming tags
3963 @c "How do I move or rename a magic branch tag?"
3964 @c in the FAQ (I think the issues it talks about still
3965 @c apply, but this could use some sanity.sh work).
3967 Normally one does not modify tags. They exist in order
3968 to record the history of the repository and so deleting
3969 them or changing their meaning would, generally, not be
3972 However, there might be cases in which one uses a tag
3973 temporarily or accidentally puts one in the wrong
3974 place. Therefore, one might delete, move, or rename a
3978 @strong{WARNING: the commands in this section are
3979 dangerous; they permanently discard historical
3980 information and it can be difficult or impossible to
3981 recover from errors. If you are a @sc{cvs}
3982 administrator, you may consider restricting these
3983 commands with the @file{taginfo} file (@pxref{taginfo}).}
3985 @cindex Deleting tags
3986 @cindex Deleting branch tags
3987 @cindex Removing tags
3988 @cindex Removing branch tags
3989 @cindex Tags, deleting
3990 @cindex Branch tags, deleting
3991 To delete a tag, specify the @samp{-d} option to either
3992 @code{cvs tag} or @code{cvs rtag}. For example:
3995 cvs rtag -d rel-0-4 tc
3999 deletes the non-branch tag @code{rel-0-4} from the module @code{tc}.
4000 In the event that branch tags are encountered within the repository
4001 with the given name, a warning message will be issued and the branch
4002 tag will not be deleted. If you are absolutely certain you know what
4003 you are doing, the @code{-B} option may be specified to allow deletion
4004 of branch tags. In that case, any non-branch tags encountered will
4005 trigger warnings and will not be deleted.
4008 @strong{WARNING: Moving branch tags is very dangerous! If you think
4009 you need the @code{-B} option, think again and ask your @sc{cvs}
4010 administrator about it (if that isn't you). There is almost certainly
4011 another way to accomplish what you want to accomplish.}
4014 @cindex Moving branch tags
4015 @cindex Tags, moving
4016 @cindex Branch tags, moving
4017 When we say @dfn{move} a tag, we mean to make the same
4018 name point to different revisions. For example, the
4019 @code{stable} tag may currently point to revision 1.4
4020 of @file{backend.c} and perhaps we want to make it
4021 point to revision 1.6. To move a non-branch tag, specify the
4022 @samp{-F} option to either @code{cvs tag} or @code{cvs
4023 rtag}. For example, the task just mentioned might be
4027 cvs tag -r 1.6 -F stable backend.c
4031 If any branch tags are encountered in the repository
4032 with the given name, a warning is issued and the branch
4033 tag is not disturbed. If you are absolutely certain you
4034 wish to move the branch tag, the @code{-B} option may be specified.
4035 In that case, non-branch tags encountered with the given
4036 name are ignored with a warning message.
4039 @strong{WARNING: Moving branch tags is very dangerous! If you think you
4040 need the @code{-B} option, think again and ask your @sc{cvs}
4041 administrator about it (if that isn't you). There is almost certainly
4042 another way to accomplish what you want to accomplish.}
4044 @cindex Renaming tags
4045 @cindex Tags, renaming
4046 When we say @dfn{rename} a tag, we mean to make a
4047 different name point to the same revisions as the old
4048 tag. For example, one may have misspelled the tag name
4049 and want to correct it (hopefully before others are
4050 relying on the old spelling). To rename a tag, first
4051 create a new tag using the @samp{-r} option to
4052 @code{cvs rtag}, and then delete the old name. (Caution:
4053 this method will not work with branch tags.)
4054 This leaves the new tag on exactly the
4055 same files as the old tag. For example:
4058 cvs rtag -r old-name-0-4 rel-0-4 tc
4059 cvs rtag -d old-name-0-4 tc
4062 @node Tagging add/remove
4063 @section Tagging and adding and removing files
4065 The subject of exactly how tagging interacts with
4066 adding and removing files is somewhat obscure; for the
4067 most part @sc{cvs} will keep track of whether files
4068 exist or not without too much fussing. By default,
4069 tags are applied to only files which have a revision
4070 corresponding to what is being tagged. Files which did
4071 not exist yet, or which were already removed, simply
4072 omit the tag, and @sc{cvs} knows to treat the absence
4073 of a tag as meaning that the file didn't exist as of
4076 However, this can lose a small amount of information.
4077 For example, suppose a file was added and then removed.
4078 Then, if the tag is missing for that file, there is no
4079 way to know whether the tag refers to the time before
4080 the file was added, or the time after it was removed.
4081 If you specify the @samp{-r} option to @code{cvs rtag},
4082 then @sc{cvs} tags the files which have been removed,
4083 and thereby avoids this problem. For example, one
4084 might specify @code{-r HEAD} to tag the head.
4086 On the subject of adding and removing files, the
4087 @code{cvs rtag} command has a @samp{-a} option which
4088 means to clear the tag from removed files that would
4089 not otherwise be tagged. For example, one might
4090 specify this option in conjunction with @samp{-F} when
4091 moving a tag. If one moved a tag without @samp{-a},
4092 then the tag in the removed files might still refer to
4093 the old revision, rather than reflecting the fact that
4094 the file had been removed. I don't think this is
4095 necessary if @samp{-r} is specified, as noted above.
4097 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4099 @section Sticky tags
4101 @cindex Tags, sticky
4103 @c A somewhat related issue is per-directory sticky
4104 @c tags (see comment at CVS/Tag in node Working
4105 @c directory storage); we probably want to say
4106 @c something like "you can set a sticky tag for only
4107 @c some files, but you don't want to" or some such.
4109 Sometimes a working copy's revision has extra data
4110 associated with it, for example it might be on a branch
4111 (@pxref{Branching and merging}), or restricted to
4112 versions prior to a certain date by @samp{checkout -D}
4113 or @samp{update -D}. Because this data persists --
4114 that is, it applies to subsequent commands in the
4115 working copy -- we refer to it as @dfn{sticky}.
4117 Most of the time, stickiness is an obscure aspect of
4118 @sc{cvs} that you don't need to think about. However,
4119 even if you don't want to use the feature, you may need
4120 to know @emph{something} about sticky tags (for
4121 example, how to avoid them!).
4123 You can use the @code{status} command to see if any
4124 sticky tags or dates are set:
4127 $ cvs status driver.c
4128 ===================================================================
4129 File: driver.c Status: Up-to-date
4131 Version: 1.7.2.1 Sat Dec 5 19:35:03 1992
4132 RCS Version: 1.7.2.1 /u/cvsroot/yoyodyne/tc/driver.c,v
4133 Sticky Tag: rel-1-0-patches (branch: 1.7.2)
4135 Sticky Options: (none)
4139 @cindex Resetting sticky tags
4140 @cindex Sticky tags, resetting
4141 @cindex Deleting sticky tags
4142 The sticky tags will remain on your working files until
4143 you delete them with @samp{cvs update -A}. The
4144 @samp{-A} option merges local changes into the version of the
4145 file from the head of the trunk, removing any sticky tags,
4146 dates, or options. See @ref{update} for more on the operation
4147 of @code{cvs update}.
4150 The most common use of sticky tags is to identify which
4151 branch one is working on, as described in
4152 @ref{Accessing branches}. However, non-branch
4153 sticky tags have uses as well. For example,
4154 suppose that you want to avoid updating your working
4155 directory, to isolate yourself from possibly
4156 destabilizing changes other people are making. You
4157 can, of course, just refrain from running @code{cvs
4158 update}. But if you want to avoid updating only a
4159 portion of a larger tree, then sticky tags can help.
4160 If you check out a certain revision (such as 1.4) it
4161 will become sticky. Subsequent @code{cvs update}
4163 not retrieve the latest revision until you reset the
4164 tag with @code{cvs update -A}. Likewise, use of the
4165 @samp{-D} option to @code{update} or @code{checkout}
4166 sets a @dfn{sticky date}, which, similarly, causes that
4167 date to be used for future retrievals.
4169 People often want to retrieve an old version of
4170 a file without setting a sticky tag. This can
4171 be done with the @samp{-p} option to @code{checkout} or
4172 @code{update}, which sends the contents of the file to
4173 standard output. For example:
4175 $ cvs update -p -r 1.1 file1 >file1
4176 ===================================================================
4178 RCS: /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v
4184 However, this isn't the easiest way, if you are asking
4185 how to undo a previous checkin (in this example, put
4186 @file{file1} back to the way it was as of revision
4187 1.1). In that case you are better off using the
4188 @samp{-j} option to @code{update}; for further
4189 discussion see @ref{Merging two revisions}.
4191 @c ---------------------------------------------------------------------
4192 @node Branching and merging
4193 @chapter Branching and merging
4196 @cindex Copying changes
4197 @cindex Main trunk and branches
4198 @cindex Revision tree, making branches
4199 @cindex Branches, copying changes between
4200 @cindex Changes, copying between branches
4201 @cindex Modifications, copying between branches
4203 @sc{cvs} allows you to isolate changes onto a separate
4204 line of development, known as a @dfn{branch}. When you
4205 change files on a branch, those changes do not appear
4206 on the main trunk or other branches.
4208 Later you can move changes from one branch to another
4209 branch (or the main trunk) by @dfn{merging}. Merging
4210 involves first running @code{cvs update -j}, to merge
4211 the changes into the working directory.
4212 You can then commit that revision, and thus effectively
4213 copy the changes onto another branch.
4216 * Branches motivation:: What branches are good for
4217 * Creating a branch:: Creating a branch
4218 * Accessing branches:: Checking out and updating branches
4219 * Branches and revisions:: Branches are reflected in revision numbers
4220 * Magic branch numbers:: Magic branch numbers
4221 * Merging a branch:: Merging an entire branch
4222 * Merging more than once:: Merging from a branch several times
4223 * Merging two revisions:: Merging differences between two revisions
4224 * Merging adds and removals:: What if files are added or removed?
4225 * Merging and keywords:: Avoiding conflicts due to keyword substitution
4228 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4229 @node Branches motivation
4230 @section What branches are good for
4231 @cindex Branches motivation
4232 @cindex What branches are good for
4233 @cindex Motivation for branches
4235 @c FIXME: this node mentions one way to use branches,
4236 @c but it is by no means the only way. For example,
4237 @c the technique of committing a new feature on a branch,
4238 @c until it is ready for the main trunk. The whole
4239 @c thing is generally speaking more akin to the
4240 @c "Revision management" node although it isn't clear to
4241 @c me whether policy matters should be centralized or
4242 @c distributed throughout the relevant sections.
4243 Suppose that release 1.0 of tc has been made. You are continuing to
4244 develop tc, planning to create release 1.1 in a couple of months. After a
4245 while your customers start to complain about a fatal bug. You check
4246 out release 1.0 (@pxref{Tags}) and find the bug
4247 (which turns out to have a trivial fix). However, the current revision
4248 of the sources are in a state of flux and are not expected to be stable
4249 for at least another month. There is no way to make a
4250 bug fix release based on the newest sources.
4252 The thing to do in a situation like this is to create a @dfn{branch} on
4253 the revision trees for all the files that make up
4254 release 1.0 of tc. You can then make
4255 modifications to the branch without disturbing the main trunk. When the
4256 modifications are finished you can elect to either incorporate them on
4257 the main trunk, or leave them on the branch.
4259 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4260 @node Creating a branch
4261 @section Creating a branch
4262 @cindex Creating a branch
4263 @cindex Branch, creating a
4264 @cindex tag (subcommand), creating a branch using
4265 @cindex rtag (subcommand), creating a branch using
4267 You can create a branch with @code{tag -b}; for
4268 example, assuming you're in a working copy:
4271 $ cvs tag -b rel-1-0-patches
4274 @c FIXME: we should be more explicit about the value of
4275 @c having a tag on the branchpoint. For example
4276 @c "cvs tag rel-1-0-patches-branchpoint" before
4277 @c the "cvs tag -b". This points out that
4278 @c rel-1-0-patches is a pretty awkward name for
4279 @c this example (more so than for the rtag example
4282 This splits off a branch based on the current revisions
4283 in the working copy, assigning that branch the name
4284 @samp{rel-1-0-patches}.
4286 It is important to understand that branches get created
4287 in the repository, not in the working copy. Creating a
4288 branch based on current revisions, as the above example
4289 does, will @emph{not} automatically switch the working
4290 copy to be on the new branch. For information on how
4291 to do that, see @ref{Accessing branches}.
4293 You can also create a branch without reference to any
4294 working copy, by using @code{rtag}:
4297 $ cvs rtag -b -r rel-1-0 rel-1-0-patches tc
4300 @samp{-r rel-1-0} says that this branch should be
4301 rooted at the revision that
4302 corresponds to the tag @samp{rel-1-0}. It need not
4303 be the most recent revision -- it's often useful to
4304 split a branch off an old revision (for example, when
4305 fixing a bug in a past release otherwise known to be
4308 As with @samp{tag}, the @samp{-b} flag tells
4309 @code{rtag} to create a branch (rather than just a
4310 symbolic revision name). Note that the numeric
4311 revision number that matches @samp{rel-1-0} will
4312 probably be different from file to file.
4314 So, the full effect of the command is to create a new
4315 branch -- named @samp{rel-1-0-patches} -- in module
4316 @samp{tc}, rooted in the revision tree at the point tagged
4319 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4320 @node Accessing branches
4321 @section Accessing branches
4322 @cindex Check out a branch
4323 @cindex Retrieve a branch
4324 @cindex Access a branch
4325 @cindex Identifying a branch
4326 @cindex Branch, check out
4327 @cindex Branch, retrieving
4328 @cindex Branch, accessing
4329 @cindex Branch, identifying
4331 You can retrieve a branch in one of two ways: by
4332 checking it out fresh from the repository, or by
4333 switching an existing working copy over to the branch.
4335 To check out a branch from the repository, invoke
4336 @samp{checkout} with the @samp{-r} flag, followed by
4337 the tag name of the branch (@pxref{Creating a branch}):
4340 $ cvs checkout -r rel-1-0-patches tc
4343 Or, if you already have a working copy, you can switch
4344 it to a given branch with @samp{update -r}:
4347 $ cvs update -r rel-1-0-patches tc
4355 $ cvs update -r rel-1-0-patches
4358 It does not matter if the working copy was originally
4359 on the main trunk or on some other branch -- the above
4360 command will switch it to the named branch. And
4361 similarly to a regular @samp{update} command,
4362 @samp{update -r} merges any changes you have made,
4363 notifying you of conflicts where they occur.
4365 Once you have a working copy tied to a particular
4366 branch, it remains there until you tell it otherwise.
4367 This means that changes checked in from the working
4368 copy will add new revisions on that branch, while
4369 leaving the main trunk and other branches unaffected.
4371 @cindex Branches, sticky
4372 To find out what branch a working copy is on, you can
4373 use the @samp{status} command. In its output, look for
4374 the field named @samp{Sticky tag} (@pxref{Sticky tags})
4375 -- that's @sc{cvs}'s way of telling you the branch, if
4376 any, of the current working files:
4379 $ cvs status -v driver.c backend.c
4380 ===================================================================
4381 File: driver.c Status: Up-to-date
4383 Version: 1.7 Sat Dec 5 18:25:54 1992
4384 RCS Version: 1.7 /u/cvsroot/yoyodyne/tc/driver.c,v
4385 Sticky Tag: rel-1-0-patches (branch: 1.7.2)
4387 Sticky Options: (none)
4390 rel-1-0-patches (branch: 1.7.2)
4391 rel-1-0 (revision: 1.7)
4393 ===================================================================
4394 File: backend.c Status: Up-to-date
4396 Version: 1.4 Tue Dec 1 14:39:01 1992
4397 RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v
4398 Sticky Tag: rel-1-0-patches (branch: 1.4.2)
4400 Sticky Options: (none)
4403 rel-1-0-patches (branch: 1.4.2)
4404 rel-1-0 (revision: 1.4)
4405 rel-0-4 (revision: 1.4)
4409 Don't be confused by the fact that the branch numbers
4410 for each file are different (@samp{1.7.2} and
4411 @samp{1.4.2} respectively). The branch tag is the
4412 same, @samp{rel-1-0-patches}, and the files are
4413 indeed on the same branch. The numbers simply reflect
4414 the point in each file's revision history at which the
4415 branch was made. In the above example, one can deduce
4416 that @samp{driver.c} had been through more changes than
4417 @samp{backend.c} before this branch was created.
4419 See @ref{Branches and revisions} for details about how
4420 branch numbers are constructed.
4422 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4423 @node Branches and revisions
4424 @section Branches and revisions
4425 @cindex Branch number
4426 @cindex Number, branch
4427 @cindex Revision numbers (branches)
4429 Ordinarily, a file's revision history is a linear
4430 series of increments (@pxref{Revision numbers}):
4433 +-----+ +-----+ +-----+ +-----+ +-----+
4434 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
4435 +-----+ +-----+ +-----+ +-----+ +-----+
4438 However, @sc{cvs} is not limited to linear development. The
4439 @dfn{revision tree} can be split into @dfn{branches},
4440 where each branch is a self-maintained line of
4441 development. Changes made on one branch can easily be
4442 moved back to the main trunk.
4444 Each branch has a @dfn{branch number}, consisting of an
4445 odd number of period-separated decimal integers. The
4446 branch number is created by appending an integer to the
4447 revision number where the corresponding branch forked
4448 off. Having branch numbers allows more than one branch
4449 to be forked off from a certain revision.
4452 All revisions on a branch have revision numbers formed
4453 by appending an ordinal number to the branch number.
4454 The following figure illustrates branching with an
4458 @c This example used to have a 1.2.2.4 revision, which
4459 @c might help clarify that development can continue on
4460 @c 1.2.2. Might be worth reinstating if it can be done
4461 @c without overfull hboxes.
4464 Branch 1.2.2.3.2 -> ! 1.2.2.3.2.1 !
4468 +---------+ +---------+ +---------+
4469 Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
4470 / +---------+ +---------+ +---------+
4473 +-----+ +-----+ +-----+ +-----+ +-----+
4474 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
4475 +-----+ +-----+ +-----+ +-----+ +-----+
4478 ! +---------+ +---------+ +---------+
4479 Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 !
4480 +---------+ +---------+ +---------+
4485 @c -- However, at least for me the figure is not enough. I suggest more
4486 @c -- text to accompany it. "A picture is worth a thousand words", so you
4487 @c -- have to make sure the reader notices the couple of hundred words
4488 @c -- *you* had in mind more than the others!
4490 @c -- Why an even number of segments? This section implies that this is
4491 @c -- how the main trunk is distinguished from branch roots, but you never
4492 @c -- explicitly say that this is the purpose of the [by itself rather
4493 @c -- surprising] restriction to an even number of segments.
4495 The exact details of how the branch number is
4496 constructed is not something you normally need to be
4497 concerned about, but here is how it works: When
4498 @sc{cvs} creates a branch number it picks the first
4499 unused even integer, starting with 2. So when you want
4500 to create a branch from revision 6.4 it will be
4501 numbered 6.4.2. All branch numbers ending in a zero
4502 (such as 6.4.0) are used internally by @sc{cvs}
4503 (@pxref{Magic branch numbers}). The branch 1.1.1 has a
4504 special meaning. @xref{Tracking sources}.
4506 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4507 @node Magic branch numbers
4508 @section Magic branch numbers
4510 @c Want xref to here from "log"?
4512 This section describes a @sc{cvs} feature called
4513 @dfn{magic branches}. For most purposes, you need not
4514 worry about magic branches; @sc{cvs} handles them for
4515 you. However, they are visible to you in certain
4516 circumstances, so it may be useful to have some idea of
4519 Externally, branch numbers consist of an odd number of
4520 dot-separated decimal integers. @xref{Revision
4521 numbers}. That is not the whole truth, however. For
4522 efficiency reasons @sc{cvs} sometimes inserts an extra 0
4523 in the second rightmost position (1.2.4 becomes
4524 1.2.0.4, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so
4527 @sc{cvs} does a pretty good job at hiding these so
4528 called magic branches, but in a few places the hiding
4533 @c This is in ignore as I'm taking their word for it,
4534 @c that this was fixed
4535 @c a long time ago. But before deleting this
4536 @c entirely, I'd rather verify it (and add a test
4537 @c case to the testsuite).
4539 The magic branch can appear in the output from
4540 @code{cvs status} in vanilla @sc{cvs} 1.3. This is
4541 fixed in @sc{cvs} 1.3-s2.
4545 The magic branch number appears in the output from
4547 @c What output should appear instead?
4550 You cannot specify a symbolic branch name to @code{cvs
4555 @c Can CVS do this automatically the first time
4556 @c you check something in to that branch? Should
4558 You can use the @code{admin} command to reassign a
4559 symbolic name to a branch the way @sc{rcs} expects it
4560 to be. If @code{R4patches} is assigned to the branch
4561 1.4.2 (magic branch number 1.4.0.2) in file
4562 @file{numbers.c} you can do this:
4565 $ cvs admin -NR4patches:1.4.2 numbers.c
4568 It only works if at least one revision is already
4569 committed on the branch. Be very careful so that you
4570 do not assign the tag to the wrong number. (There is
4571 no way to see how the tag was assigned yesterday).
4573 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4574 @node Merging a branch
4575 @section Merging an entire branch
4576 @cindex Merging a branch
4577 @cindex -j (merging branches)
4579 You can merge changes made on a branch into your working copy by giving
4580 the @samp{-j @var{branchname}} flag to the @code{update} subcommand. With one
4581 @samp{-j @var{branchname}} option it merges the changes made between the
4582 greatest common ancestor (GCA) of the branch and the destination revision (in
4583 the simple case below the GCA is the point where the branch forked) and the
4584 newest revision on that branch into your working copy.
4587 The @samp{-j} stands for ``join''.
4589 @cindex Branch merge example
4590 @cindex Example, branch merge
4591 @cindex Merge, branch example
4592 Consider this revision tree:
4595 +-----+ +-----+ +-----+ +-----+
4596 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 ! <- The main trunk
4597 +-----+ +-----+ +-----+ +-----+
4600 ! +---------+ +---------+
4601 Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
4602 +---------+ +---------+
4606 The branch 1.2.2 has been given the tag (symbolic name) @samp{R1fix}. The
4607 following example assumes that the module @samp{mod} contains only one
4611 $ cvs checkout mod # @r{Retrieve the latest revision, 1.4}
4613 $ cvs update -j R1fix m.c # @r{Merge all changes made on the branch,}
4614 # @r{i.e. the changes between revision 1.2}
4615 # @r{and 1.2.2.2, into your working copy}
4618 $ cvs commit -m "Included R1fix" # @r{Create revision 1.5.}
4621 A conflict can result from a merge operation. If that
4622 happens, you should resolve it before committing the
4623 new revision. @xref{Conflicts example}.
4625 If your source files contain keywords (@pxref{Keyword substitution}),
4626 you might be getting more conflicts than strictly necessary. See
4627 @ref{Merging and keywords}, for information on how to avoid this.
4629 The @code{checkout} command also supports the @samp{-j @var{branchname}} flag. The
4630 same effect as above could be achieved with this:
4633 $ cvs checkout -j R1fix mod
4634 $ cvs commit -m "Included R1fix"
4637 It should be noted that @code{update -j @var{tagname}} will also work but may
4638 not produce the desired result. @xref{Merging adds and removals}, for more.
4640 @node Merging more than once
4641 @section Merging from a branch several times
4643 Continuing our example, the revision tree now looks
4647 +-----+ +-----+ +-----+ +-----+ +-----+
4648 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
4649 +-----+ +-----+ +-----+ +-----+ +-----+
4652 ! +---------+ +---------+
4653 Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
4654 +---------+ +---------+
4658 where the starred line represents the merge from the
4659 @samp{R1fix} branch to the main trunk, as just
4662 Now suppose that development continues on the
4663 @samp{R1fix} branch:
4666 +-----+ +-----+ +-----+ +-----+ +-----+
4667 ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
4668 +-----+ +-----+ +-----+ +-----+ +-----+
4671 ! +---------+ +---------+ +---------+
4672 Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
4673 +---------+ +---------+ +---------+
4677 and then you want to merge those new changes onto the
4678 main trunk. If you just use the @code{cvs update -j
4679 R1fix m.c} command again, @sc{cvs} will attempt to
4680 merge again the changes which you have already merged,
4681 which can have undesirable side effects.
4683 So instead you need to specify that you only want to
4684 merge the changes on the branch which have not yet been
4685 merged into the trunk. To do that you specify two
4686 @samp{-j} options, and @sc{cvs} merges the changes from
4687 the first revision to the second revision. For
4688 example, in this case the simplest way would be
4691 cvs update -j 1.2.2.2 -j R1fix m.c # @r{Merge changes from 1.2.2.2 to the}
4692 # @r{head of the R1fix branch}
4695 The problem with this is that you need to specify the
4696 1.2.2.2 revision manually. A slightly better approach
4697 might be to use the date the last merge was done:
4700 cvs update -j R1fix:yesterday -j R1fix m.c
4703 Better yet, tag the R1fix branch after every merge into
4704 the trunk, and then use that tag for subsequent merges:
4707 cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c
4710 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4711 @node Merging two revisions
4712 @section Merging differences between any two revisions
4713 @cindex Merging two revisions
4714 @cindex Revisions, merging differences between
4715 @cindex Differences, merging
4717 With two @samp{-j @var{revision}} flags, the @code{update}
4718 (and @code{checkout}) command can merge the differences
4719 between any two revisions into your working file.
4721 @cindex Undoing a change
4722 @cindex Removing a change
4724 $ cvs update -j 1.5 -j 1.3 backend.c
4728 will undo all changes made between revision
4729 1.3 and 1.5. Note the order of the revisions!
4731 If you try to use this option when operating on
4732 multiple files, remember that the numeric revisions will
4733 probably be very different between the various files.
4734 You almost always use symbolic
4735 tags rather than revision numbers when operating on
4738 @cindex Restoring old version of removed file
4739 @cindex Resurrecting old version of dead file
4740 Specifying two @samp{-j} options can also undo file
4741 removals or additions. For example, suppose you have
4743 named @file{file1} which existed as revision 1.1, and
4744 you then removed it (thus adding a dead revision 1.2).
4745 Now suppose you want to add it again, with the same
4746 contents it had previously. Here is how to do it:
4749 $ cvs update -j 1.2 -j 1.1 file1
4751 $ cvs commit -m test
4753 /tmp/cvs-sanity/cvsroot/first-dir/file1,v <-- file1
4754 new revision: 1.3; previous revision: 1.2
4759 @node Merging adds and removals
4760 @section Merging can add or remove files
4762 If the changes which you are merging involve removing
4763 or adding some files, @code{update -j} will reflect
4764 such additions or removals.
4766 @c FIXME: This example needs a lot more explanation.
4767 @c We also need other examples for some of the other
4768 @c cases (not all--there are too many--as long as we present a
4769 @c coherent general principle).
4774 cvs add a b c ; cvs ci -m "added" a b c
4775 cvs tag -b branchtag
4776 cvs update -r branchtag
4779 cvs ci -m "added d, removed a"
4781 cvs update -jbranchtag
4784 After these commands are executed and a @samp{cvs commit} is done,
4785 file @file{a} will be removed and file @file{d} added in the main branch.
4786 @c (which was determined by trying it)
4788 Note that using a single static tag (@samp{-j @var{tagname}})
4789 rather than a dynamic tag (@samp{-j @var{branchname}}) to merge
4790 changes from a branch will usually not remove files which were removed on the
4791 branch since @sc{cvs} does not automatically add static tags to dead revisions.
4792 The exception to this rule occurs when
4793 a static tag has been attached to a dead revision manually. Use the branch tag
4794 to merge all changes from the branch or use two static tags as merge endpoints
4795 to be sure that all intended changes are propagated in the merge.
4797 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
4798 @node Merging and keywords
4799 @section Merging and keywords
4800 @cindex Merging, and keyword substitution
4801 @cindex Keyword substitution, and merging
4802 @cindex -j (merging branches), and keyword substitution
4803 @cindex -kk, to avoid conflicts during a merge
4805 If you merge files containing keywords (@pxref{Keyword
4806 substitution}), you will normally get numerous
4807 conflicts during the merge, because the keywords are
4808 expanded differently in the revisions which you are
4811 Therefore, you will often want to specify the
4812 @samp{-kk} (@pxref{Substitution modes}) switch to the
4813 merge command line. By substituting just the name of
4814 the keyword, not the expanded value of that keyword,
4815 this option ensures that the revisions which you are
4816 merging will be the same as each other, and avoid
4819 For example, suppose you have a file like this:
4833 and your working directory is currently on the trunk
4834 (revision 1.2). Then you might get the following
4835 results from a merge:
4839 key $@splitrcskeyword{Revision}: 1.2 $
4843 RCS file: /cvsroot/first-dir/file1,v
4844 retrieving revision 1.1
4845 retrieving revision 1.1.2.1
4846 Merging differences between 1.1 and 1.1.2.1 into file1
4847 rcsmerge: warning: conflicts during merge
4849 @asis{}<<<<<<< file1
4850 key $@splitrcskeyword{Revision}: 1.2 $
4852 key $@splitrcskeyword{Revision}: 1.1.2.1 $
4853 @asis{}>>>>>>> 1.1.2.1
4857 What happened was that the merge tried to merge the
4858 differences between 1.1 and 1.1.2.1 into your working
4859 directory. So, since the keyword changed from
4860 @code{Revision: 1.1} to @code{Revision: 1.1.2.1},
4861 @sc{cvs} tried to merge that change into your working
4862 directory, which conflicted with the fact that your
4863 working directory had contained @code{Revision: 1.2}.
4865 Here is what happens if you had used @samp{-kk}:
4869 key $@splitrcskeyword{Revision}: 1.2 $
4871 $ cvs update -kk -j br1
4873 RCS file: /cvsroot/first-dir/file1,v
4874 retrieving revision 1.1
4875 retrieving revision 1.1.2.1
4876 Merging differences between 1.1 and 1.1.2.1 into file1
4878 key $@splitrcskeyword{Revision}$
4882 What is going on here is that revision 1.1 and 1.1.2.1
4883 both expand as plain @code{Revision}, and therefore
4884 merging the changes between them into the working
4885 directory need not change anything. Therefore, there
4888 @strong{WARNING: In versions of @sc{cvs} prior to 1.12.2, there was a
4889 major problem with using @samp{-kk} on merges. Namely, @samp{-kk}
4890 overrode any default keyword expansion mode set in the archive file in
4891 the repository. This could, unfortunately for some users, cause data
4892 corruption in binary files (with a default keyword expansion mode set
4893 to @samp{-kb}). Therefore, when a repository contained binary files,
4894 conflicts had to be dealt with manually rather than using @samp{-kk} in
4897 In @sc{cvs} version 1.12.2 and later, the keyword expansion mode
4898 provided on the command line to any @sc{cvs} command no longer
4899 overrides the @samp{-kb} keyword expansion mode setting for binary
4900 files, though it will still override other default keyword expansion
4901 modes. You can now safely merge using @samp{-kk} to avoid spurious conflicts
4902 on lines containing RCS keywords, even when your repository contains
4905 @c ---------------------------------------------------------------------
4906 @node Recursive behavior
4907 @chapter Recursive behavior
4908 @cindex Recursive (directory descending)
4909 @cindex Directory, descending
4910 @cindex Descending directories
4911 @cindex Subdirectories
4913 Almost all of the subcommands of @sc{cvs} work
4914 recursively when you specify a directory as an
4915 argument. For instance, consider this directory
4924 | (internal @sc{cvs} files)
4933 | | (internal @sc{cvs} files)
4939 | (internal @sc{cvs} files)
4945 If @file{tc} is the current working directory, the
4950 @samp{cvs update testing} is equivalent to
4953 cvs update testing/testpgm.t testing/test2.t
4957 @samp{cvs update testing man} updates all files in the
4961 @samp{cvs update .} or just @samp{cvs update} updates
4962 all files in the @code{tc} directory
4965 If no arguments are given to @code{update} it will
4966 update all files in the current working directory and
4967 all its subdirectories. In other words, @file{.} is a
4968 default argument to @code{update}. This is also true
4969 for most of the @sc{cvs} subcommands, not only the
4970 @code{update} command.
4972 The recursive behavior of the @sc{cvs} subcommands can be
4973 turned off with the @samp{-l} option.
4974 Conversely, the @samp{-R} option can be used to force recursion if
4975 @samp{-l} is specified in @file{~/.cvsrc} (@pxref{~/.cvsrc}).
4978 $ cvs update -l # @r{Don't update files in subdirectories}
4981 @c ---------------------------------------------------------------------
4982 @node Adding and removing
4983 @chapter Adding, removing, and renaming files and directories
4985 In the course of a project, one will often add new
4986 files. Likewise with removing or renaming, or with
4987 directories. The general concept to keep in mind in
4988 all these cases is that instead of making an
4989 irreversible change you want @sc{cvs} to record the
4990 fact that a change has taken place, just as with
4991 modifying an existing file. The exact mechanisms to do
4992 this in @sc{cvs} vary depending on the situation.
4995 * Adding files:: Adding files
4996 * Removing files:: Removing files
4997 * Removing directories:: Removing directories
4998 * Moving files:: Moving and renaming files
4999 * Moving directories:: Moving and renaming directories
5003 @section Adding files to a directory
5004 @cindex Adding files
5006 To add a new file to a directory, follow these steps.
5010 You must have a working copy of the directory.
5011 @xref{Getting the source}.
5014 Create the new file inside your working copy of the directory.
5017 Use @samp{cvs add @var{filename}} to tell @sc{cvs} that you
5018 want to version control the file. If the file contains
5019 binary data, specify @samp{-kb} (@pxref{Binary files}).
5022 Use @samp{cvs commit @var{filename}} to actually check
5023 in the file into the repository. Other developers
5024 cannot see the file until you perform this step.
5027 You can also use the @code{add} command to add a new
5029 @c FIXCVS and/or FIXME: Adding a directory doesn't
5030 @c require the commit step. This probably can be
5031 @c considered a CVS bug, but it is possible we should
5032 @c warn people since this behavior probably won't be
5033 @c changing right away.
5035 Unlike most other commands, the @code{add} command is
5036 not recursive. You have to expcicitly name files and
5037 directories that you wish to add to the repository.
5038 However, each directory will need to be added
5039 separately before you will be able to add new files
5040 to those directories.
5044 $ cp ~/myfile foo/bar/myfile
5045 $ cvs add foo foo/bar
5046 $ cvs add foo/bar/myfile
5049 @cindex add (subcommand)
5050 @deffn Command {cvs add} [@code{-k} kflag] [@code{-m} message] files @dots{}
5052 Schedule @var{files} to be added to the repository.
5053 The files or directories specified with @code{add} must
5054 already exist in the current directory. To add a whole
5055 new directory hierarchy to the source repository (for
5056 example, files received from a third-party vendor), use
5057 the @code{import} command instead. @xref{import}.
5059 The added files are not placed in the source repository
5060 until you use @code{commit} to make the change
5061 permanent. Doing an @code{add} on a file that was
5062 removed with the @code{remove} command will undo the
5063 effect of the @code{remove}, unless a @code{commit}
5064 command intervened. @xref{Removing files}, for an
5067 The @samp{-k} option specifies the default way that
5068 this file will be checked out; for more information see
5069 @ref{Substitution modes}.
5071 @c As noted in BUGS, -m is broken client/server (Nov
5072 @c 96). Also see testsuite log2-* tests.
5073 The @samp{-m} option specifies a description for the
5074 file. This description appears in the history log (if
5075 it is enabled, @pxref{history file}). It will also be
5076 saved in the version history inside the repository when
5077 the file is committed. The @code{log} command displays
5078 this description. The description can be changed using
5079 @samp{admin -t}. @xref{admin}. If you omit the
5080 @samp{-m @var{description}} flag, an empty string will
5081 be used. You will not be prompted for a description.
5084 For example, the following commands add the file
5085 @file{backend.c} to the repository:
5087 @c This example used to specify
5088 @c -m "Optimizer and code generation passes."
5089 @c to the cvs add command, but that doesn't work
5090 @c client/server (see log2 in sanity.sh). Should fix CVS,
5091 @c but also seems strange to document things which
5095 $ cvs commit -m "Early version. Not yet compilable." backend.c
5098 When you add a file it is added only on the branch
5099 which you are working on (@pxref{Branching and merging}). You can
5100 later merge the additions to another branch if you want
5101 (@pxref{Merging adds and removals}).
5102 @c Should we mention that earlier versions of CVS
5103 @c lacked this feature (1.3) or implemented it in a buggy
5104 @c way (well, 1.8 had many bugs in cvs update -j)?
5105 @c Should we mention the bug/limitation regarding a
5106 @c file being a regular file on one branch and a directory
5108 @c FIXME: This needs an example, or several, here or
5109 @c elsewhere, for it to make much sense.
5110 @c Somewhere we need to discuss the aspects of death
5111 @c support which don't involve branching, I guess.
5112 @c Like the ability to re-create a release from a tag.
5114 @c ---------------------------------------------------------------------
5115 @node Removing files
5116 @section Removing files
5117 @cindex Removing files
5118 @cindex Deleting files
5120 @c FIXME: this node wants to be split into several
5121 @c smaller nodes. Could make these children of
5122 @c "Adding and removing", probably (death support could
5123 @c be its own section, for example, as could the
5124 @c various bits about undoing mistakes in adding and
5126 Directories change. New files are added, and old files
5127 disappear. Still, you want to be able to retrieve an
5128 exact copy of old releases.
5130 Here is what you can do to remove a file,
5131 but remain able to retrieve old revisions:
5134 @c FIXME: should probably be saying something about
5135 @c having a working directory in the first place.
5137 Make sure that you have not made any uncommitted
5138 modifications to the file. @xref{Viewing differences},
5139 for one way to do that. You can also use the
5140 @code{status} or @code{update} command. If you remove
5141 the file without committing your changes, you will of
5142 course not be able to retrieve the file as it was
5143 immediately before you deleted it.
5146 Remove the file from your working copy of the directory.
5147 You can for instance use @code{rm}.
5150 Use @samp{cvs remove @var{filename}} to tell @sc{cvs} that
5151 you really want to delete the file.
5154 Use @samp{cvs commit @var{filename}} to actually
5155 perform the removal of the file from the repository.
5158 @c FIXME: Somehow this should be linked in with a more
5159 @c general discussion of death support. I don't know
5160 @c whether we want to use the term "death support" or
5161 @c not (we can perhaps get by without it), but we do
5162 @c need to discuss the "dead" state in "cvs log" and
5163 @c related subjects. The current discussion is
5164 @c scattered around, and not xref'd to each other.
5165 @c FIXME: I think this paragraph wants to be moved
5166 @c later down, at least after the first example.
5167 When you commit the removal of the file, @sc{cvs}
5168 records the fact that the file no longer exists. It is
5169 possible for a file to exist on only some branches and
5170 not on others, or to re-add another file with the same
5171 name later. @sc{cvs} will correctly create or not create
5172 the file, based on the @samp{-r} and @samp{-D} options
5173 specified to @code{checkout} or @code{update}.
5175 @c FIXME: This style seems to clash with how we
5176 @c document things in general.
5177 @cindex Remove (subcommand)
5178 @deffn Command {cvs remove} [options] files @dots{}
5180 Schedule file(s) to be removed from the repository
5181 (files which have not already been removed from the
5182 working directory are not processed). This command
5183 does not actually remove the file from the repository
5184 until you commit the removal. For a full list of
5185 options, see @ref{Invoking CVS}.
5188 Here is an example of removing several files:
5194 cvs remove: Removing .
5195 cvs remove: scheduling a.c for removal
5196 cvs remove: scheduling b.c for removal
5197 cvs remove: use 'cvs commit' to remove these files permanently
5198 $ cvs ci -m "Removed unneeded files"
5199 cvs commit: Examining .
5200 cvs commit: Committing .
5203 As a convenience you can remove the file and @code{cvs
5204 remove} it in one step, by specifying the @samp{-f}
5205 option. For example, the above example could also be
5211 cvs remove: scheduling a.c for removal
5212 cvs remove: scheduling b.c for removal
5213 cvs remove: use 'cvs commit' to remove these files permanently
5214 $ cvs ci -m "Removed unneeded files"
5215 cvs commit: Examining .
5216 cvs commit: Committing .
5219 If you execute @code{remove} for a file, and then
5220 change your mind before you commit, you can undo the
5221 @code{remove} with an @code{add} command.
5223 @c is this worth saying or not? Somehow it seems
5226 since you have removed your copy of file in the working
5227 directory, @sc{cvs} does not necessarily bring back the
5228 contents of the file from right before you executed
5229 @code{remove}; instead it gets the file from the
5233 @c FIXME: what if you change your mind after you commit
5234 @c it? (answer is also "cvs add" but we don't say that...).
5235 @c We need some index entries for thinks like "undoing
5243 cvs remove: scheduling oj.c for removal
5244 cvs remove: use 'cvs commit' to remove this file permanently
5247 cvs add: oj.c, version 1.1.1.1, resurrected
5250 If you realize your mistake before you run the
5251 @code{remove} command you can use @code{update} to
5257 cvs update: warning: oj.c was lost
5261 When you remove a file it is removed only on the branch
5262 which you are working on (@pxref{Branching and merging}). You can
5263 later merge the removals to another branch if you want
5264 (@pxref{Merging adds and removals}).
5266 @node Removing directories
5267 @section Removing directories
5268 @cindex Removing directories
5269 @cindex Directories, removing
5271 In concept removing directories is somewhat similar to
5272 removing files---you want the directory to not exist in
5273 your current working directories, but you also want to
5274 be able to retrieve old releases in which the directory
5277 The way that you remove a directory is to remove all
5278 the files in it. You don't remove the directory
5279 itself; there is no way to do that.
5280 Instead you specify the @samp{-P} option to
5281 @code{cvs update} or @code{cvs checkout},
5282 which will cause @sc{cvs} to remove empty
5283 directories from working directories.
5284 (Note that @code{cvs export} always removes empty directories.)
5286 best way to do this is to always specify @samp{-P}; if
5287 you want an empty directory then put a dummy file (for
5288 example @file{.keepme}) in it to prevent @samp{-P} from
5291 @c I'd try to give a rationale for this, but I'm not
5292 @c sure there is a particularly convincing one. What
5293 @c we would _like_ is for CVS to do a better job of version
5294 @c controlling whether directories exist, to eliminate the
5295 @c need for -P and so that a file can be a directory in
5296 @c one revision and a regular file in another.
5297 Note that @samp{-P} is implied by the @samp{-r} or @samp{-D}
5298 options of @code{checkout}. This way
5299 @sc{cvs} will be able to correctly create the directory
5300 or not depending on whether the particular version you
5301 are checking out contains any files in that directory.
5303 @c ---------------------------------------------------------------------
5305 @section Moving and renaming files
5306 @cindex Moving files
5307 @cindex Renaming files
5308 @cindex Files, moving
5310 Moving files to a different directory or renaming them
5311 is not difficult, but some of the ways in which this
5312 works may be non-obvious. (Moving or renaming a
5313 directory is even harder. @xref{Moving directories}.).
5315 The examples below assume that the file @var{old} is renamed to
5319 * Outside:: The normal way to Rename
5320 * Inside:: A tricky, alternative way
5321 * Rename by copying:: Another tricky, alternative way
5324 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
5326 @subsection The Normal way to Rename
5328 @c More rename issues. Not sure whether these are
5329 @c worth documenting; I'm putting them here because
5330 @c it seems to be as good a place as any to try to
5331 @c set down the issues.
5332 @c * "cvs annotate" will annotate either the new
5333 @c file or the old file; it cannot annotate _each
5334 @c line_ based on whether it was last changed in the
5335 @c new or old file. Unlike "cvs log", where the
5336 @c consequences of having to select either the new
5337 @c or old name seem fairly benign, this may be a
5338 @c real advantage to having CVS know about renames
5339 @c other than as a deletion and an addition.
5341 The normal way to move a file is to copy @var{old} to
5342 @var{new}, and then issue the normal @sc{cvs} commands
5343 to remove @var{old} from the repository, and add
5345 @c The following sentence is not true: one must cd into
5346 @c the directory to run "cvs add".
5347 @c (Both @var{old} and @var{new} could
5348 @c contain relative paths, for example @file{foo/bar.c}).
5351 $ mv @var{old} @var{new}
5352 $ cvs remove @var{old}
5354 $ cvs commit -m "Renamed @var{old} to @var{new}" @var{old} @var{new}
5357 This is the simplest way to move a file, it is not
5358 error-prone, and it preserves the history of what was
5359 done. Note that to access the history of the file you
5360 must specify the old or the new name, depending on what
5361 portion of the history you are accessing. For example,
5362 @code{cvs log @var{old}} will give the log up until the
5365 When @var{new} is committed its revision numbers will
5366 start again, usually at 1.1, so if that bothers you,
5367 use the @samp{-r rev} option to commit. For more
5368 information see @ref{Assigning revisions}.
5370 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
5372 @subsection Moving the history file
5374 This method is more dangerous, since it involves moving
5375 files inside the repository. Read this entire section
5376 before trying it out!
5379 $ cd $CVSROOT/@var{dir}
5380 $ mv @var{old},v @var{new},v
5388 The log of changes is maintained intact.
5391 The revision numbers are not affected.
5399 Old releases cannot easily be fetched from the
5400 repository. (The file will show up as @var{new} even
5401 in revisions from the time before it was renamed).
5404 There is no log information of when the file was renamed.
5407 Nasty things might happen if someone accesses the history file
5408 while you are moving it. Make sure no one else runs any of the @sc{cvs}
5409 commands while you move it.
5412 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
5413 @node Rename by copying
5414 @subsection Copying the history file
5416 This way also involves direct modifications to the
5417 repository. It is safe, but not without drawbacks.
5420 # @r{Copy the @sc{rcs} file inside the repository}
5421 $ cd $CVSROOT/@var{dir}
5422 $ cp @var{old},v @var{new},v
5423 # @r{Remove the old file}
5426 $ cvs remove @var{old}
5427 $ cvs commit @var{old}
5428 # @r{Remove all tags from @var{new}}
5429 $ cvs update @var{new}
5430 $ cvs log @var{new} # @r{Remember the non-branch tag names}
5431 $ cvs tag -d @var{tag1} @var{new}
5432 $ cvs tag -d @var{tag2} @var{new}
5436 By removing the tags you will be able to check out old
5444 @c FIXME: Is this true about -D now that we have death
5445 @c support? See 5B.3 in the FAQ.
5446 Checking out old revisions works correctly, as long as
5447 you use @samp{-r@var{tag}} and not @samp{-D@var{date}}
5448 to retrieve the revisions.
5451 The log of changes is maintained intact.
5454 The revision numbers are not affected.
5462 You cannot easily see the history of the file across the rename.
5465 @c Is this true? I don't see how the revision numbers
5466 @c _could_ start over, when new,v is just old,v with
5467 @c the tags deleted.
5468 @c If there is some need to reinstate this text,
5469 @c it is "usually 1.1", not "1.0" and it needs an
5470 @c xref to Assigning revisions
5472 Unless you use the @samp{-r rev} (@pxref{commit
5473 options}) flag when @var{new} is committed its revision
5474 numbers will start at 1.0 again.
5478 @c ---------------------------------------------------------------------
5479 @node Moving directories
5480 @section Moving and renaming directories
5481 @cindex Moving directories
5482 @cindex Renaming directories
5483 @cindex Directories, moving
5485 The normal way to rename or move a directory is to
5486 rename or move each file within it as described in
5487 @ref{Outside}. Then check out with the @samp{-P}
5488 option, as described in @ref{Removing directories}.
5490 If you really want to hack the repository to rename or
5491 delete a directory in the repository, you can do it
5496 Inform everyone who has a checked out copy of the directory that the
5497 directory will be renamed. They should commit all
5498 their changes, and remove their working copies,
5499 before you take the steps below.
5502 Rename the directory inside the repository.
5505 $ cd $CVSROOT/@var{parent-dir}
5506 $ mv @var{old-dir} @var{new-dir}
5510 Fix the @sc{cvs} administrative files, if necessary (for
5511 instance if you renamed an entire module).
5514 Tell everyone that they can check out again and continue
5519 If someone had a working copy the @sc{cvs} commands will
5520 cease to work for him, until he removes the directory
5521 that disappeared inside the repository.
5523 It is almost always better to move the files in the
5524 directory instead of moving the directory. If you move the
5525 directory you are unlikely to be able to retrieve old
5526 releases correctly, since they probably depend on the
5527 name of the directories.
5529 @c ---------------------------------------------------------------------
5530 @node History browsing
5531 @chapter History browsing
5532 @cindex History browsing
5533 @cindex Traceability
5537 @c This is too long for an introduction (goal is
5538 @c one 20x80 character screen), and also mixes up a
5539 @c variety of issues (parallel development, history,
5540 @c maybe even touches on process control).
5542 @c -- @quote{To lose ones history is to lose ones soul.}
5544 @c -- ///Those who cannot remember the past are condemned to repeat it.
5545 @c -- /// -- George Santayana
5548 @sc{cvs} tries to make it easy for a group of people to work
5549 together. This is done in two ways:
5553 Isolation---You have your own working copy of the
5554 source. You are not affected by modifications made by
5555 others until you decide to incorporate those changes
5556 (via the @code{update} command---@pxref{update}).
5559 Traceability---When something has changed, you can
5560 always see @emph{exactly} what changed.
5563 There are several features of @sc{cvs} that together lead
5568 Each revision of a file has an accompanying log
5572 All commits are optionally logged to a central history
5576 Logging information can be sent to a user-defined
5577 program (@pxref{loginfo}).
5580 @c -- More text here.
5582 This chapter should talk about the history file, the
5583 @code{log} command, the usefulness of ChangeLogs
5584 even when you run @sc{cvs}, and things like that.
5588 @c kind of lame, in a lot of ways the above text inside
5589 @c the @ignore motivates this chapter better
5590 Once you have used @sc{cvs} to store a version control
5591 history---what files have changed when, how, and by
5592 whom, there are a variety of mechanisms for looking
5593 through the history.
5595 @c FIXME: should also be talking about how you look at
5596 @c old revisions (e.g. "cvs update -p -r 1.2 foo.c").
5598 * log messages:: Log messages
5599 * history database:: The history database
5600 * user-defined logging:: User-defined logging
5603 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
5605 @section Log messages
5607 @c FIXME: @xref to place where we talk about how to
5608 @c specify message to commit.
5609 Whenever you commit a file you specify a log message.
5611 @c FIXME: bring the information here, and get rid of or
5612 @c greatly shrink the "log" node.
5613 To look through the log messages which have been
5614 specified for every revision which has been committed,
5615 use the @code{cvs log} command (@pxref{log}).
5617 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
5618 @node history database
5619 @section The history database
5621 @c FIXME: bring the information from the history file
5622 @c and history nodes here. Rewrite it to be motivated
5623 @c better (start out by clearly explaining what gets
5624 @c logged in history, for example).
5625 You can use the history file (@pxref{history file}) to
5626 log various @sc{cvs} actions. To retrieve the
5627 information from the history file, use the @code{cvs
5628 history} command (@pxref{history}).
5630 Note: you can control what is logged to this file by using the
5631 @samp{LogHistory} keyword in the @file{CVSROOT/config} file
5635 @c The history database has many problems:
5636 @c * It is very unclear what field means what. This
5637 @c could be improved greatly by better documentation,
5638 @c but there are still non-orthogonalities (for
5639 @c example, tag does not record the "repository"
5640 @c field but most records do).
5641 @c * Confusion about files, directories, and modules.
5642 @c Some commands record one, some record others.
5643 @c * File removal is not logged. There is an 'R'
5644 @c record type documented, but CVS never uses it.
5645 @c * Tags are only logged for the "cvs rtag" command,
5646 @c not "cvs tag". The fix for this is not completely
5647 @c clear (see above about modules vs. files).
5648 @c * Are there other cases of operations that are not
5649 @c logged? One would hope for all changes to the
5650 @c repository to be logged somehow (particularly
5651 @c operations like tagging, "cvs admin -k", and other
5652 @c operations which do not record a history that one
5653 @c can get with "cvs log"). Operations on the working
5654 @c directory, like export, get, and release, are a
5655 @c second category also covered by the current "cvs
5657 @c * The history file does not record the options given
5658 @c to a command. The most serious manifestation of
5659 @c this is perhaps that it doesn't record whether a command
5660 @c was recursive. It is not clear to me whether one
5661 @c wants to log at a level very close to the command
5662 @c line, as a sort of way of logging each command
5663 @c (more or less), or whether one wants
5664 @c to log more at the level of what was changed (or
5665 @c something in between), but either way the current
5666 @c information has pretty big gaps.
5667 @c * Further details about a tag--like whether it is a
5668 @c branch tag or, if a non-branch tag, which branch it
5669 @c is on. One can find out this information about the
5670 @c tag as it exists _now_, but if the tag has been
5671 @c moved, one doesn't know what it was like at the time
5672 @c the history record was written.
5673 @c * Whether operating on a particular tag, date, or
5674 @c options was implicit (sticky) or explicit.
5676 @c Another item, only somewhat related to the above, is a
5677 @c way to control what is logged in the history file.
5678 @c This is probably the only good way to handle
5679 @c different people having different ideas about
5680 @c information/space tradeoffs.
5682 @c It isn't really clear that it makes sense to try to
5683 @c patch up the history file format as it exists now to
5684 @c include all that stuff. It might be better to
5685 @c design a whole new CVSROOT/nhistory file and "cvs
5686 @c nhistory" command, or some such, or in some other
5687 @c way trying to come up with a clean break from the
5688 @c past, which can address the above concerns. Another
5689 @c open question is how/whether this relates to
5690 @c taginfo/loginfo/etc.
5692 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
5693 @node user-defined logging
5694 @section User-defined logging
5696 @c FIXME: probably should centralize this information
5697 @c here, at least to some extent. Maybe by moving the
5698 @c loginfo, etc., nodes here and replacing
5699 @c the "user-defined logging" node with one node for
5701 You can customize @sc{cvs} to log various kinds of
5702 actions, in whatever manner you choose. These
5703 mechanisms operate by executing a script at various
5704 times. The script might append a message to a file
5705 listing the information and the programmer who created
5706 it, or send mail to a group of developers, or, perhaps,
5707 post a message to a particular newsgroup. To log
5708 commits, use the @file{loginfo} file (@pxref{loginfo}), and
5709 to log tagging operations, use the @file{taginfo} file
5712 @c FIXME: What is difference between doing it in the
5713 @c modules file and using loginfo/taginfo? Why should
5714 @c user use one or the other?
5715 To log commits, checkouts, exports, and tags,
5716 respectively, you can also use the @samp{-i},
5717 @samp{-o}, @samp{-e}, and @samp{-t} options in the
5718 modules file. For a more flexible way of giving
5719 notifications to various users, which requires less in
5720 the way of keeping centralized scripts up to date, use
5721 the @code{cvs watch add} command (@pxref{Getting
5722 Notified}); this command is useful even if you are not
5723 using @code{cvs watch on}.
5725 @c ---------------------------------------------------------------------
5727 @chapter Handling binary files
5728 @cindex Binary files
5730 The most common use for @sc{cvs} is to store text
5731 files. With text files, @sc{cvs} can merge revisions,
5732 display the differences between revisions in a
5733 human-visible fashion, and other such operations.
5734 However, if you are willing to give up a few of these
5735 abilities, @sc{cvs} can store binary files. For
5736 example, one might store a web site in @sc{cvs}
5737 including both text files and binary images.
5740 * Binary why:: More details on issues with binary files
5741 * Binary howto:: How to store them
5745 @section The issues with binary files
5747 While the need to manage binary files may seem obvious
5748 if the files that you customarily work with are binary,
5749 putting them into version control does present some
5752 One basic function of version control is to show the
5753 differences between two revisions. For example, if
5754 someone else checked in a new version of a file, you
5755 may wish to look at what they changed and determine
5756 whether their changes are good. For text files,
5757 @sc{cvs} provides this functionality via the @code{cvs
5758 diff} command. For binary files, it may be possible to
5759 extract the two revisions and then compare them with a
5760 tool external to @sc{cvs} (for example, word processing
5761 software often has such a feature). If there is no
5762 such tool, one must track changes via other mechanisms,
5763 such as urging people to write good log messages, and
5764 hoping that the changes they actually made were the
5765 changes that they intended to make.
5767 Another ability of a version control system is the
5768 ability to merge two revisions. For @sc{cvs} this
5769 happens in two contexts. The first is when users make
5770 changes in separate working directories
5771 (@pxref{Multiple developers}). The second is when one
5772 merges explicitly with the @samp{update -j} command
5773 (@pxref{Branching and merging}).
5776 files, @sc{cvs} can merge changes made independently,
5777 and signal a conflict if the changes conflict. With
5778 binary files, the best that @sc{cvs} can do is present
5779 the two different copies of the file, and leave it to
5780 the user to resolve the conflict. The user may choose
5781 one copy or the other, or may run an external merge
5782 tool which knows about that particular file format, if
5784 Note that having the user merge relies primarily on the
5785 user to not accidentally omit some changes, and thus is
5786 potentially error prone.
5788 If this process is thought to be undesirable, the best
5789 choice may be to avoid merging. To avoid the merges
5790 that result from separate working directories, see the
5791 discussion of reserved checkouts (file locking) in
5792 @ref{Multiple developers}. To avoid the merges
5793 resulting from branches, restrict use of branches.
5796 @section How to store binary files
5798 There are two issues with using @sc{cvs} to store
5799 binary files. The first is that @sc{cvs} by default
5800 converts line endings between the canonical form in
5801 which they are stored in the repository (linefeed
5802 only), and the form appropriate to the operating system
5803 in use on the client (for example, carriage return
5804 followed by line feed for Windows NT).
5806 The second is that a binary file might happen to
5807 contain data which looks like a keyword (@pxref{Keyword
5808 substitution}), so keyword expansion must be turned
5811 @c FIXME: the third is that one can't do merges with
5812 @c binary files. xref to Multiple Developers and the
5813 @c reserved checkout issues.
5815 The @samp{-kb} option available with some @sc{cvs}
5816 commands insures that neither line ending conversion
5817 nor keyword expansion will be done.
5819 Here is an example of how you can create a new file
5820 using the @samp{-kb} flag:
5823 $ echo '$@splitrcskeyword{Id}$' > kotest
5824 $ cvs add -kb -m"A test file" kotest
5825 $ cvs ci -m"First checkin; contains a keyword" kotest
5828 If a file accidentally gets added without @samp{-kb},
5829 one can use the @code{cvs admin} command to recover.
5833 $ echo '$@splitrcskeyword{Id}$' > kotest
5834 $ cvs add -m"A test file" kotest
5835 $ cvs ci -m"First checkin; contains a keyword" kotest
5836 $ cvs admin -kb kotest
5837 $ cvs update -A kotest
5838 # @r{For non-unix systems:}
5839 # @r{Copy in a good copy of the file from outside CVS}
5840 $ cvs commit -m "make it binary" kotest
5843 @c Trying to describe this for both unix and non-unix
5844 @c in the same description is very confusing. Might
5845 @c want to split the two, or just ditch the unix "shortcut"
5846 @c (unixheads don't do much with binary files, anyway).
5847 @c This used to say "(Try the above example, and do a
5848 @c @code{cat kotest} after every command)". But that
5849 @c only really makes sense for the unix case.
5850 When you check in the file @file{kotest} the file is
5851 not preserved as a binary file, because you did not
5852 check it in as a binary file. The @code{cvs
5853 admin -kb} command sets the default keyword
5854 substitution method for this file, but it does not
5855 alter the working copy of the file that you have. If you need to
5856 cope with line endings (that is, you are using
5857 @sc{cvs} on a non-unix system), then you need to
5858 check in a new copy of the file, as shown by the
5859 @code{cvs commit} command above.
5860 On unix, the @code{cvs update -A} command suffices.
5861 @c FIXME: should also describe what the *other users*
5862 @c need to do, if they have checked out copies which
5863 @c have been corrupted by lack of -kb. I think maybe
5864 @c "cvs update -kb" or "cvs
5865 @c update -A" would suffice, although the user who
5866 @c reported this suggested removing the file, manually
5867 @c removing it from CVS/Entries, and then "cvs update"
5868 (Note that you can use @code{cvs log} to determine the default keyword
5869 substitution method for a file and @code{cvs status} to determine
5870 the keyword substitution method for a working copy.)
5872 However, in using @code{cvs admin -k} to change the
5873 keyword expansion, be aware that the keyword expansion
5874 mode is not version controlled. This means that, for
5875 example, that if you have a text file in old releases,
5876 and a binary file with the same name in new releases,
5877 @sc{cvs} provides no way to check out the file in text
5878 or binary mode depending on what version you are
5879 checking out. There is no good workaround for this
5882 You can also set a default for whether @code{cvs add}
5883 and @code{cvs import} treat a file as binary based on
5884 its name; for example you could say that files who
5885 names end in @samp{.exe} are binary. @xref{Wrappers}.
5886 There is currently no way to have @sc{cvs} detect
5887 whether a file is binary based on its contents. The
5888 main difficulty with designing such a feature is that
5889 it is not clear how to distinguish between binary and
5890 non-binary files, and the rules to apply would vary
5891 considerably with the operating system.
5892 @c For example, it would be good on MS-DOS-family OSes
5893 @c for anything containing ^Z to be binary. Having
5894 @c characters with the 8th bit set imply binary is almost
5895 @c surely a bad idea in the context of ISO-8859-* and
5896 @c other such character sets. On VMS or the Mac, we
5897 @c could use the OS's file typing. This is a
5898 @c commonly-desired feature, and something of this sort
5899 @c may make sense. But there are a lot of pitfalls here.
5901 @c Another, probably better, way to tell is to read the
5902 @c file in text mode, write it to a temp file in text
5903 @c mode, and then do a binary mode compare of the two
5904 @c files. If they differ, it is a binary file. This
5905 @c might have problems on VMS (or some other system
5906 @c with several different text modes), but in general
5907 @c should be relatively portable. The only other
5908 @c downside I can think of is that it would be fairly
5909 @c slow, but that is perhaps a small price to pay for
5910 @c not having your files corrupted. Another issue is
5911 @c what happens if you import a text file with bare
5912 @c linefeeds on Windows. Such files will show up on
5913 @c Windows sometimes (I think some native windows
5914 @c programs even write them, on occasion). Perhaps it
5915 @c is reasonable to treat such files as binary; after
5916 @c all it is something of a presumption to assume that
5917 @c the user would want the linefeeds converted to CRLF.
5919 @c ---------------------------------------------------------------------
5920 @node Multiple developers
5921 @chapter Multiple developers
5922 @cindex Multiple developers
5923 @cindex Team of developers
5924 @cindex File locking
5925 @cindex Locking files
5926 @cindex Working copy
5927 @cindex Reserved checkouts
5928 @cindex Unreserved checkouts
5929 @cindex RCS-style locking
5931 When more than one person works on a software project
5932 things often get complicated. Often, two people try to
5933 edit the same file simultaneously. One solution, known
5934 as @dfn{file locking} or @dfn{reserved checkouts}, is
5935 to allow only one person to edit each file at a time.
5936 This is the only solution with some version control
5937 systems, including @sc{rcs} and @sc{sccs}. Currently
5938 the usual way to get reserved checkouts with @sc{cvs}
5939 is the @code{cvs admin -l} command (@pxref{admin
5940 options}). This is not as nicely integrated into
5941 @sc{cvs} as the watch features, described below, but it
5942 seems that most people with a need for reserved
5943 checkouts find it adequate.
5944 @c Or "find it better than worrying about implementing
5945 @c nicely integrated reserved checkouts" or ...?
5947 As of @sc{cvs} version 1.12.10, another technique for getting most of the
5948 effect of reserved checkouts is to enable advisory locks. To enable advisory
5949 locks, have all developers put "edit -c", "commit -c" in their
5950 .cvsrc file, and turn on watches in the repository. This
5951 prevents them from doing a @code{cvs edit} if anyone is
5952 already editting the file. It also may
5953 be possible to use plain watches together with suitable
5954 procedures (not enforced by software), to avoid having
5955 two people edit at the same time.
5957 @c Our unreserved checkout model might not
5958 @c be quite the same as others. For example, I
5959 @c think that some systems will tend to create a branch
5960 @c in the case where CVS prints "up-to-date check failed".
5961 @c It isn't clear to me whether we should try to
5962 @c explore these subtleties; it could easily just
5964 The default model with @sc{cvs} is known as
5965 @dfn{unreserved checkouts}. In this model, developers
5966 can edit their own @dfn{working copy} of a file
5967 simultaneously. The first person that commits his
5968 changes has no automatic way of knowing that another
5969 has started to edit it. Others will get an error
5970 message when they try to commit the file. They must
5971 then use @sc{cvs} commands to bring their working copy
5972 up to date with the repository revision. This process
5973 is almost automatic.
5975 @c FIXME? should probably use the word "watch" here, to
5976 @c tie this into the text below and above.
5977 @sc{cvs} also supports mechanisms which facilitate
5978 various kinds of communication, without actually
5979 enforcing rules like reserved checkouts do.
5981 The rest of this chapter describes how these various
5982 models work, and some of the issues involved in
5983 choosing between them.
5986 Here is a draft reserved checkout design or discussion
5987 of the issues. This seems like as good a place as any
5990 Might want a cvs lock/cvs unlock--in which the names
5991 differ from edit/unedit because the network must be up
5992 for these to work. unedit gives an error if there is a
5993 reserved checkout in place (so that people don't
5994 accidentally leave locks around); unlock gives an error
5995 if one is not in place (this is more arguable; perhaps
5996 it should act like unedit in that case).
5998 On the other hand, might want it so that emacs,
5999 scripts, etc., can get ready to edit a file without
6000 having to know which model is in use. In that case we
6001 would have a "cvs watch lock" (or .cvsrc?) (that is,
6002 three settings, "on", "off", and "lock"). Having cvs
6003 watch lock set would cause a get to record in the CVS
6004 directory which model is in use, and cause "cvs edit"
6005 to change behaviors. We'd want a way to query which
6006 setting is in effect (this would be handy even if it is
6007 only "on" or "off" as presently). If lock is in
6008 effect, then commit would require a lock before
6009 allowing a checkin; chmod wouldn't suffice (might be
6010 debatable--see chmod comment below, in watches--but it
6011 is the way people expect RCS to work and I can't think
6012 of any significant downside. On the other hand, maybe
6013 it isn't worth bothering, because people who are used
6014 to RCS wouldn't think to use chmod anyway).
6016 Implementation: use file attributes or use RCS
6017 locking. The former avoids more dependence on RCS
6018 behaviors we will need to re-implement as we librarify
6019 RCS, and makes it easier to import/export RCS files (in
6020 that context, want to ignore the locker field). But
6021 note that RCS locks are per-branch, which is the
6022 correct behavior (this is also an issue for the "watch
6023 on" features; they should be per-branch too).
6025 Here are a few more random notes about implementation
6026 details, assuming "cvs watch lock" and
6028 CVS/Watched file? Or try to fit this into CVS/Entries somehow?
6029 Cases: (1) file is checked out (unreserved or with watch on) by old
6030 version of @sc{cvs}, now we do something with new one, (2) file is checked
6031 out by new version, now we do something with old one.
6033 Remote protocol would have a "Watched" analogous to "Mode". Of course
6034 it would apply to all Updated-like requests. How do we keep this
6035 setting up to date? I guess that there wants to be a Watched request,
6036 and the server would send a new one if it isn't up to date? (Ugh--hard
6037 to implement and slows down "cvs -q update"--is there an easier way?)
6039 "cvs edit"--checks CVS/Watched, and if watch lock, then sends
6040 "edit-lock" request. Which comes back with a Checked-in with
6041 appropriate Watched (off, on, lock, locked, or some such?), or error
6042 message if already locked.
6044 "cvs commit"--only will commit if off/on/locked. lock is not OK.
6047 note that "cvs edit" must be connected to network if watch lock is in
6050 Talk about what to do if someone has locked a file and you want to
6051 edit that file. (breaking locks, or lack thereof).
6054 One other idea (which could work along with the
6055 existing "cvs admin -l" reserved checkouts, as well as
6058 "cvs editors" could show who has the file locked, if
6064 * File status:: A file can be in several states
6065 * Updating a file:: Bringing a file up-to-date
6066 * Conflicts example:: An informative example
6067 * Informing others:: To cooperate you must inform
6068 * Concurrency:: Simultaneous repository access
6069 * Watches:: Mechanisms to track who is editing files
6070 * Choosing a model:: Reserved or unreserved checkouts?
6073 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
6075 @section File status
6077 @cindex Status of a file
6079 @c Shouldn't this start with an example or something,
6080 @c introducing the unreserved checkout model? Before we
6081 @c dive into listing states?
6082 Based on what operations you have performed on a
6083 checked out file, and what operations others have
6084 performed to that file in the repository, one can
6085 classify a file in a number of states. The states, as
6086 reported by the @code{status} command, are:
6088 @c The order of items is chosen to group logically
6089 @c similar outputs together.
6090 @c People who want alphabetical can use the index...
6094 The file is identical with the latest revision in the
6095 repository for the branch in use.
6096 @c FIXME: should we clarify "in use"? The answer is
6097 @c sticky tags, and trying to distinguish branch sticky
6098 @c tags from non-branch sticky tags seems rather awkward
6100 @c FIXME: What happens with non-branch sticky tags? Is
6101 @c a stuck file "Up-to-date" or "Needs checkout" or what?
6103 @item Locally Modified
6104 @cindex Locally Modified
6105 You have edited the file, and not yet committed your changes.
6108 @cindex Locally Added
6109 You have added the file with @code{add}, and not yet
6110 committed your changes.
6111 @c There are many cases involving the file being
6112 @c added/removed/modified in the working directory, and
6113 @c added/removed/modified in the repository, which we
6114 @c don't try to describe here. I'm not sure that "cvs
6115 @c status" produces a non-confusing output in most of
6118 @item Locally Removed
6119 @cindex Locally Removed
6120 You have removed the file with @code{remove}, and not yet
6121 committed your changes.
6123 @item Needs Checkout
6124 @cindex Needs Checkout
6125 Someone else has committed a newer revision to the
6126 repository. The name is slightly misleading; you will
6127 ordinarily use @code{update} rather than
6128 @code{checkout} to get that newer revision.
6132 @c See also newb-123j0 in sanity.sh (although that case
6133 @c should probably be changed rather than documented).
6134 Like Needs Checkout, but the @sc{cvs} server will send
6135 a patch rather than the entire file. Sending a patch or
6136 sending an entire file accomplishes the same thing.
6140 Someone else has committed a newer revision to the repository, and you
6141 have also made modifications to the file.
6143 @item Unresolved Conflict
6144 @cindex Unresolved Conflict
6145 @c FIXCVS - This file status needs to be changed to some more informative
6146 @c text that distinguishes it more clearly from each of the Locally Added,
6147 @c File had conflicts on merge, and Unknown status types, but an exact and
6148 @c succinct wording escapes me at the moment.
6149 A file with the same name as this new file has been added to the repository
6150 from a second workspace. This file will need to be moved out of the way
6151 to allow an @code{update} to complete.
6153 @item File had conflicts on merge
6154 @cindex File had conflicts on merge
6155 @c is it worth saying that this message was "Unresolved
6156 @c Conflict" in CVS 1.9 and earlier? I'm inclined to
6157 @c think that is unnecessarily confusing to new users.
6158 This is like Locally Modified, except that a previous
6159 @code{update} command gave a conflict. If you have not
6160 already done so, you need to
6161 resolve the conflict as described in @ref{Conflicts example}.
6165 @sc{cvs} doesn't know anything about this file. For
6166 example, you have created a new file and have not run
6169 @c "Entry Invalid" and "Classify Error" are also in the
6170 @c status.c. The latter definitely indicates a CVS bug
6171 @c (should it be worded more like "internal error" so
6172 @c people submit bug reports if they see it?). The former
6173 @c I'm not as sure; I haven't tracked down whether/when it
6174 @c appears in "cvs status" output.
6178 To help clarify the file status, @code{status} also
6179 reports the @code{Working revision} which is the
6180 revision that the file in the working directory derives
6181 from, and the @code{Repository revision} which is the
6182 latest revision in the repository for the branch in
6184 @c FIXME: should we clarify "in use"? The answer is
6185 @c sticky tags, and trying to distinguish branch sticky
6186 @c tags from non-branch sticky tags seems rather awkward
6188 @c FIXME: What happens with non-branch sticky tags?
6189 @c What is the Repository Revision there? See the
6190 @c comment at vn_rcs in cvs.h, which is kind of
6191 @c confused--we really need to document better what this
6193 @c Q: Should we document "New file!" and other such
6194 @c outputs or are they self-explanatory?
6195 @c FIXME: what about the date to the right of "Working
6196 @c revision"? It doesn't appear with client/server and
6197 @c seems unnecessary (redundant with "ls -l") so
6198 @c perhaps it should be removed for non-client/server too?
6199 @c FIXME: Need some examples.
6200 @c FIXME: Working revision can also be something like
6201 @c "-1.3" for a locally removed file. Not at all
6202 @c self-explanatory (and it is possible that CVS should
6203 @c be changed rather than documenting this).
6205 @c Would be nice to have an @example showing output
6206 @c from cvs status, with comments showing the xref
6207 @c where each part of the output is described. This
6208 @c might fit in nicely if it is desirable to split this
6209 @c node in two; one to introduce "cvs status" and one
6210 @c to list each of the states.
6211 The options to @code{status} are listed in
6212 @ref{Invoking CVS}. For information on its @code{Sticky tag}
6213 and @code{Sticky date} output, see @ref{Sticky tags}.
6214 For information on its @code{Sticky options} output,
6215 see the @samp{-k} option in @ref{update options}.
6217 You can think of the @code{status} and @code{update}
6218 commands as somewhat complementary. You use
6219 @code{update} to bring your files up to date, and you
6220 can use @code{status} to give you some idea of what an
6221 @code{update} would do (of course, the state of the
6222 repository might change before you actually run
6223 @code{update}). In fact, if you want a command to
6224 display file status in a more brief format than is
6225 displayed by the @code{status} command, you can invoke
6227 @cindex update, to display file status
6232 The @samp{-n} option means to not actually do the
6233 update, but merely to display statuses; the @samp{-q}
6234 option avoids printing the name of each directory. For
6235 more information on the @code{update} command, and
6236 these options, see @ref{Invoking CVS}.
6238 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
6239 @node Updating a file
6240 @section Bringing a file up to date
6241 @cindex Bringing a file up to date
6242 @cindex Updating a file
6243 @cindex Merging a file
6244 @cindex Update, introduction
6246 When you want to update or merge a file, use the @code{update}
6247 command. For files that are not up to date this is roughly equivalent
6248 to a @code{checkout} command: the newest revision of the file is
6249 extracted from the repository and put in your working directory.
6251 Your modifications to a file are never lost when you
6252 use @code{update}. If no newer revision exists,
6253 running @code{update} has no effect. If you have
6254 edited the file, and a newer revision is available,
6255 @sc{cvs} will merge all changes into your working copy.
6257 For instance, imagine that you checked out revision 1.4 and started
6258 editing it. In the meantime someone else committed revision 1.5, and
6259 shortly after that revision 1.6. If you run @code{update} on the file
6260 now, @sc{cvs} will incorporate all changes between revision 1.4 and 1.6 into
6264 If any of the changes between 1.4 and 1.6 were made too
6265 close to any of the changes you have made, an
6266 @dfn{overlap} occurs. In such cases a warning is
6267 printed, and the resulting file includes both
6268 versions of the lines that overlap, delimited by
6270 @xref{update}, for a complete description of the
6271 @code{update} command.
6273 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
6274 @node Conflicts example
6275 @section Conflicts example
6276 @cindex Merge, an example
6277 @cindex Example of merge
6278 @cindex driver.c (merge example)
6280 Suppose revision 1.4 of @file{driver.c} contains this:
6291 fprintf(stderr, "No code generated.\n");
6292 exit(nerr == 0 ? 0 : 1);
6297 Revision 1.6 of @file{driver.c} contains this:
6308 fprintf(stderr, "tc: No args expected.\n");
6314 fprintf(stderr, "No code generated.\n");
6320 Your working copy of @file{driver.c}, based on revision
6321 1.4, contains this before you run @samp{cvs update}:
6322 @c -- Really include "cvs"?
6335 fprintf(stderr, "No code generated.\n");
6336 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
6341 You run @samp{cvs update}:
6342 @c -- Really include "cvs"?
6345 $ cvs update driver.c
6346 RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v
6347 retrieving revision 1.4
6348 retrieving revision 1.6
6349 Merging differences between 1.4 and 1.6 into driver.c
6350 rcsmerge warning: overlaps during merge
6351 cvs update: conflicts found in driver.c
6356 @cindex Conflicts (merge example)
6357 @sc{cvs} tells you that there were some conflicts.
6358 Your original working file is saved unmodified in
6359 @file{.#driver.c.1.4}. The new version of
6360 @file{driver.c} contains this:
6373 fprintf(stderr, "tc: No args expected.\n");
6379 fprintf(stderr, "No code generated.\n");
6380 @asis{}<<<<<<< driver.c
6381 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
6389 @cindex Markers, conflict
6390 @cindex Conflict markers
6395 Note how all non-overlapping modifications are incorporated in your working
6396 copy, and that the overlapping section is clearly marked with
6397 @samp{<<<<<<<}, @samp{=======} and @samp{>>>>>>>}.
6399 @cindex Resolving a conflict
6400 @cindex Conflict resolution
6401 You resolve the conflict by editing the file, removing the markers and
6402 the erroneous line. Suppose you end up with this file:
6403 @c -- Add xref to the pcl-cvs manual when it talks
6416 fprintf(stderr, "tc: No args expected.\n");
6422 fprintf(stderr, "No code generated.\n");
6423 exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
6428 You can now go ahead and commit this as revision 1.7.
6431 $ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c
6432 Checking in driver.c;
6433 /usr/local/cvsroot/yoyodyne/tc/driver.c,v <-- driver.c
6434 new revision: 1.7; previous revision: 1.6
6438 For your protection, @sc{cvs} will refuse to check in a
6439 file if a conflict occurred and you have not resolved
6440 the conflict. Currently to resolve a conflict, you
6441 must change the timestamp on the file. In previous
6442 versions of @sc{cvs}, you also needed to
6443 insure that the file contains no conflict markers.
6445 your file may legitimately contain conflict markers (that
6446 is, occurrences of @samp{>>>>>>> } at the start of a
6447 line that don't mark a conflict), the current
6448 version of @sc{cvs} will print a warning and proceed to
6450 @c The old behavior was really icky; the only way out
6451 @c was to start hacking on
6452 @c the @code{CVS/Entries} file or other such workarounds.
6454 @c If the timestamp thing isn't considered nice enough,
6455 @c maybe there should be a "cvs resolved" command
6456 @c which clears the conflict indication. For a nice user
6457 @c interface, this should be invoked by an interactive
6458 @c merge tool like emerge rather than by the user
6459 @c directly--such a tool can verify that the user has
6460 @c really dealt with each conflict.
6463 If you use release 1.04 or later of pcl-cvs (a @sc{gnu}
6464 Emacs front-end for @sc{cvs}) you can use an Emacs
6465 package called emerge to help you resolve conflicts.
6466 See the documentation for pcl-cvs.
6468 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
6469 @node Informing others
6470 @section Informing others about commits
6471 @cindex Informing others
6472 @cindex Spreading information
6473 @cindex Mail, automatic mail on commit
6475 It is often useful to inform others when you commit a
6476 new revision of a file. The @samp{-i} option of the
6477 @file{modules} file, or the @file{loginfo} file, can be
6478 used to automate this process. @xref{modules}.
6479 @xref{loginfo}. You can use these features of @sc{cvs}
6480 to, for instance, instruct @sc{cvs} to mail a
6481 message to all developers, or post a message to a local
6483 @c -- More text would be nice here.
6486 @section Several developers simultaneously attempting to run CVS
6488 @cindex Locks, cvs, introduction
6489 @c For a discussion of *why* CVS creates locks, see
6490 @c the comment at the start of src/lock.c
6491 If several developers try to run @sc{cvs} at the same
6492 time, one may get the following message:
6495 [11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo
6498 @cindex #cvs.rfl, removing
6499 @cindex #cvs.wfl, removing
6500 @cindex #cvs.lock, removing
6501 @sc{cvs} will try again every 30 seconds, and either
6502 continue with the operation or print the message again,
6503 if it still needs to wait. If a lock seems to stick
6504 around for an undue amount of time, find the person
6505 holding the lock and ask them about the cvs command
6506 they are running. If they aren't running a cvs
6507 command, look in the repository directory mentioned in
6508 the message and remove files which they own whose names
6509 start with @file{#cvs.rfl},
6510 @file{#cvs.wfl}, or @file{#cvs.lock}.
6512 Note that these locks are to protect @sc{cvs}'s
6513 internal data structures and have no relationship to
6514 the word @dfn{lock} in the sense used by
6515 @sc{rcs}---which refers to reserved checkouts
6516 (@pxref{Multiple developers}).
6518 Any number of people can be reading from a given
6519 repository at a time; only when someone is writing do
6520 the locks prevent other people from reading or writing.
6522 @cindex Atomic transactions, lack of
6523 @cindex Transactions, atomic, lack of
6524 @c the following talks about what one might call commit/update
6526 @c Probably also should say something about
6527 @c commit/commit atomicity, that is, "An update will
6528 @c not get partial versions of more than one commit".
6529 @c CVS currently has this property and I guess we can
6530 @c make it a documented feature.
6531 @c For example one person commits
6532 @c a/one.c and b/four.c and another commits a/two.c and
6533 @c b/three.c. Then an update cannot get the new a/one.c
6534 @c and a/two.c and the old b/four.c and b/three.c.
6535 One might hope for the following property:
6538 If someone commits some changes in one cvs command,
6539 then an update by someone else will either get all the
6540 changes, or none of them.
6544 but @sc{cvs} does @emph{not} have this property. For
6545 example, given the files
6558 cvs ci a/two.c b/three.c
6562 and someone else runs @code{cvs update} at the same
6563 time, the person running @code{update} might get only
6564 the change to @file{b/three.c} and not the change to
6568 @section Mechanisms to track who is editing files
6571 For many groups, use of @sc{cvs} in its default mode is
6572 perfectly satisfactory. Users may sometimes go to
6573 check in a modification only to find that another
6574 modification has intervened, but they deal with it and
6575 proceed with their check in. Other groups prefer to be
6576 able to know who is editing what files, so that if two
6577 people try to edit the same file they can choose to
6578 talk about who is doing what when rather than be
6579 surprised at check in time. The features in this
6580 section allow such coordination, while retaining the
6581 ability of two developers to edit the same file at the
6584 @c Some people might ask why CVS does not enforce the
6585 @c rule on chmod, by requiring a cvs edit before a cvs
6586 @c commit. The main reason is that it could always be
6587 @c circumvented--one could edit the file, and
6588 @c then when ready to check it in, do the cvs edit and put
6589 @c in the new contents and do the cvs commit. One
6590 @c implementation note: if we _do_ want to have cvs commit
6591 @c require a cvs edit, we should store the state on
6592 @c whether the cvs edit has occurred in the working
6593 @c directory, rather than having the server try to keep
6594 @c track of what working directories exist.
6595 @c FIXME: should the above discussion be part of the
6596 @c manual proper, somewhere, not just in a comment?
6597 For maximum benefit developers should use @code{cvs
6598 edit} (not @code{chmod}) to make files read-write to
6599 edit them, and @code{cvs release} (not @code{rm}) to
6600 discard a working directory which is no longer in use,
6601 but @sc{cvs} is not able to enforce this behavior.
6603 If a development team wants stronger enforcement of
6604 watches and all team members are using a @sc{cvs} client version 1.12.10 or
6605 greater to access a @sc{cvs} server version 1.12.10 or greater, they can
6606 enable advisory locks. To enable advisory locks, have all developers
6607 put "edit -c" and "commit -c" into all .cvsrc files,
6608 and make files default to read only by turning on watches
6609 or putting "cvs -r" into all .cvsrc files.
6610 This prevents multiple people from editting a file at
6611 the same time (unless explicitly overriden with @samp{-f}).
6613 @c I'm a little dissatisfied with this presentation,
6614 @c because "watch on"/"edit"/"editors" are one set of
6615 @c functionality, and "watch add"/"watchers" is another
6616 @c which is somewhat orthogonal even though they interact in
6617 @c various ways. But I think it might be
6618 @c confusing to describe them separately (e.g. "watch
6619 @c add" with loginfo). I don't know.
6622 * Setting a watch:: Telling CVS to watch certain files
6623 * Getting Notified:: Telling CVS to notify you
6624 * Editing files:: How to edit a file which is being watched
6625 * Watch information:: Information about who is watching and editing
6626 * Watches Compatibility:: Watches interact poorly with CVS 1.6 or earlier
6629 @node Setting a watch
6630 @subsection Telling CVS to watch certain files
6632 To enable the watch features, you first specify that
6633 certain files are to be watched.
6635 @cindex watch on (subcommand)
6636 @deffn Command {cvs watch on} [@code{-lR}] [@var{files}]@dots{}
6638 @cindex Read-only files, and watches
6639 Specify that developers should run @code{cvs edit}
6640 before editing @var{files}. @sc{cvs} will create working
6641 copies of @var{files} read-only, to remind developers
6642 to run the @code{cvs edit} command before working on
6645 If @var{files} includes the name of a directory, @sc{cvs}
6646 arranges to watch all files added to the corresponding
6647 repository directory, and sets a default for files
6648 added in the future; this allows the user to set
6649 notification policies on a per-directory basis. The
6650 contents of the directory are processed recursively,
6651 unless the @code{-l} option is given.
6652 The @code{-R} option can be used to force recursion if the @code{-l}
6653 option is set in @file{~/.cvsrc} (@pxref{~/.cvsrc}).
6655 If @var{files} is omitted, it defaults to the current directory.
6657 @cindex watch off (subcommand)
6660 @deffn Command {cvs watch off} [@code{-lR}] [@var{files}]@dots{}
6662 Do not create @var{files} read-only on checkout; thus,
6663 developers will not be reminded to use @code{cvs edit}
6664 and @code{cvs unedit}.
6666 @sc{cvs} will check out @var{files}
6667 read-write as usual, unless other permissions override
6668 due to the @code{PreservePermissions} option being
6669 enabled in the @file{config} administrative file
6670 (@pxref{Special Files}, @pxref{config})
6673 The @var{files} and options are processed as for @code{cvs
6678 @node Getting Notified
6679 @subsection Telling CVS to notify you
6681 You can tell @sc{cvs} that you want to receive
6682 notifications about various actions taken on a file.
6683 You can do this without using @code{cvs watch on} for
6684 the file, but generally you will want to use @code{cvs
6685 watch on}, to remind developers to use the @code{cvs edit}
6688 @cindex watch add (subcommand)
6689 @deffn Command {cvs watch add} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{}
6691 Add the current user to the list of people to receive notification of
6692 work done on @var{files}.
6694 The @code{-a} option specifies what kinds of events @sc{cvs} should notify
6695 the user about. @var{action} is one of the following:
6700 Another user has applied the @code{cvs edit} command (described
6701 below) to a watched file.
6704 Another user has committed changes to one of the named @var{files}.
6707 Another user has abandoned editing a file (other than by committing changes).
6708 They can do this in several ways, by:
6713 applying the @code{cvs unedit} command (described below) to the file
6716 applying the @code{cvs release} command (@pxref{release}) to the file's parent directory
6717 (or recursively to a directory more than one level up)
6720 deleting the file and allowing @code{cvs update} to recreate it
6728 None of the above. (This is useful with @code{cvs edit},
6733 The @code{-a} option may appear more than once, or not at all. If
6734 omitted, the action defaults to @code{all}.
6736 The @var{files} and options are processed as for
6737 @code{cvs watch on}.
6742 @cindex watch remove (subcommand)
6743 @deffn Command {cvs watch remove} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{}
6745 Remove a notification request established using @code{cvs watch add};
6746 the arguments are the same. If the @code{-a} option is present, only
6747 watches for the specified actions are removed.
6751 @cindex notify (admin file)
6752 When the conditions exist for notification, @sc{cvs}
6753 calls the @file{notify} administrative file. Edit
6754 @file{notify} as one edits the other administrative
6755 files (@pxref{Intro administrative files}). This
6756 file follows the usual conventions for administrative
6757 files (@pxref{syntax}), where each line is a regular
6758 expression followed by a command to execute. The
6759 command should contain a single occurrence of @samp{%s}
6760 which will be replaced by the user to notify; the rest
6761 of the information regarding the notification will be
6762 supplied to the command on standard input. The
6763 standard thing to put in the @code{notify} file is the
6767 ALL mail %s -s "CVS notification"
6771 This causes users to be notified by electronic mail.
6772 @c FIXME: should it be this hard to set up this
6773 @c behavior (and the result when one fails to do so,
6774 @c silent failure to notify, so non-obvious)? Should
6775 @c CVS give a warning if no line in notify matches (and
6776 @c document the use of "DEFAULT :" for the case where
6777 @c skipping the notification is indeed desired)?
6779 @cindex users (admin file)
6780 Note that if you set this up in the straightforward
6781 way, users receive notifications on the server machine.
6782 One could of course write a @file{notify} script which
6783 directed notifications elsewhere, but to make this
6784 easy, @sc{cvs} allows you to associate a notification
6785 address for each user. To do so create a file
6786 @file{users} in @file{CVSROOT} with a line for each
6787 user in the format @var{user}:@var{value}. Then
6788 instead of passing the name of the user to be notified
6789 to @file{notify}, @sc{cvs} will pass the @var{value}
6790 (normally an email address on some other machine).
6792 @sc{cvs} does not notify you for your own changes.
6793 Currently this check is done based on whether the user
6794 name of the person taking the action which triggers
6795 notification matches the user name of the person
6796 getting notification. In fact, in general, the watches
6797 features only track one edit by each user. It probably
6798 would be more useful if watches tracked each working
6799 directory separately, so this behavior might be worth
6801 @c "behavior might be worth changing" is an effort to
6802 @c point to future directions while also not promising
6803 @c that "they" (as in "why don't they fix CVS to....")
6805 @c one implementation issue is identifying whether a
6806 @c working directory is same or different. Comparing
6807 @c pathnames/hostnames is hopeless, but having the server
6808 @c supply a serial number which the client stores in the
6809 @c CVS directory as a magic cookie should work.
6812 @subsection How to edit a file which is being watched
6814 @cindex Checkout, as term for getting ready to edit
6815 Since a file which is being watched is checked out
6816 read-only, you cannot simply edit it. To make it
6817 read-write, and inform others that you are planning to
6818 edit it, use the @code{cvs edit} command. Some systems
6819 call this a @dfn{checkout}, but @sc{cvs} uses that term
6820 for obtaining a copy of the sources (@pxref{Getting the
6821 source}), an operation which those systems call a
6822 @dfn{get} or a @dfn{fetch}.
6823 @c Issue to think about: should we transition CVS
6824 @c towards the "get" terminology? "cvs get" is already a
6825 @c synonym for "cvs checkout" and that section of the
6826 @c manual refers to "Getting the source". If this is
6827 @c done, needs to be done gingerly (for example, we should
6828 @c still accept "checkout" in .cvsrc files indefinitely
6829 @c even if the CVS's messages are changed from "cvs checkout: "
6831 @c There is a concern about whether "get" is not as
6832 @c good for novices because it is a more general term
6833 @c than "checkout" (and thus arguably harder to assign
6834 @c a technical meaning for).
6836 @cindex edit (subcommand)
6837 @deffn Command {cvs edit} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{}
6839 Prepare to edit the working files @var{files}. @sc{cvs} makes the
6840 @var{files} read-write, and notifies users who have requested
6841 @code{edit} notification for any of @var{files}.
6843 The @code{cvs edit} command accepts the same options as the
6844 @code{cvs watch add} command, and establishes a temporary watch for the
6845 user on @var{files}; @sc{cvs} will remove the watch when @var{files} are
6846 @code{unedit}ed or @code{commit}ted. If the user does not wish to
6847 receive notifications, she should specify @code{-a none}.
6849 The @var{files} and the options are processed as for the @code{cvs
6852 There are two additional options that @code{cvs edit} understands as of
6853 @sc{cvs} client and server versions 1.12.10 but @code{cvs watch} does not.
6854 The first is @code{-c}, which causes @code{cvs edit} to fail if anyone else
6855 is editting the file. This is probably only useful when @samp{edit -c} and
6856 @samp{commit -c} are specified in all developers' @file{.cvsrc} files. This
6857 behavior may be overriden this via the @code{-f} option, which overrides
6858 @code{-c} and allows multiple edits to succeed.
6861 @strong{Caution: If the @code{PreservePermissions}
6862 option is enabled in the repository (@pxref{config}),
6863 @sc{cvs} will not change the permissions on any of the
6864 @var{files}. The reason for this change is to ensure
6865 that using @samp{cvs edit} does not interfere with the
6866 ability to store file permissions in the @sc{cvs}
6872 Normally when you are done with a set of changes, you
6873 use the @code{cvs commit} command, which checks in your
6874 changes and returns the watched files to their usual
6875 read-only state. But if you instead decide to abandon
6876 your changes, or not to make any changes, you can use
6877 the @code{cvs unedit} command.
6879 @cindex unedit (subcommand)
6880 @cindex Abandoning work
6881 @cindex Reverting to repository version
6882 @deffn Command {cvs unedit} [@code{-lR}] [@var{files}]@dots{}
6884 Abandon work on the working files @var{files}, and revert them to the
6885 repository versions on which they are based. @sc{cvs} makes those
6886 @var{files} read-only for which users have requested notification using
6887 @code{cvs watch on}. @sc{cvs} notifies users who have requested @code{unedit}
6888 notification for any of @var{files}.
6890 The @var{files} and options are processed as for the
6891 @code{cvs watch} commands.
6893 If watches are not in use, the @code{unedit} command
6894 probably does not work, and the way to revert to the
6895 repository version is with the command @code{cvs update -C file}
6898 not precisely the same; the latter may also
6899 bring in some changes which have been made in the
6900 repository since the last time you updated.
6901 @c It would be a useful enhancement to CVS to make
6902 @c unedit work in the non-watch case as well.
6905 When using client/server @sc{cvs}, you can use the
6906 @code{cvs edit} and @code{cvs unedit} commands even if
6907 @sc{cvs} is unable to successfully communicate with the
6908 server; the notifications will be sent upon the next
6909 successful @sc{cvs} command.
6911 @node Watch information
6912 @subsection Information about who is watching and editing
6914 @cindex watchers (subcommand)
6915 @deffn Command {cvs watchers} [@code{-lR}] [@var{files}]@dots{}
6917 List the users currently watching changes to @var{files}. The report
6918 includes the files being watched, and the mail address of each watcher.
6920 The @var{files} and options are processed as for the
6921 @code{cvs watch} commands.
6926 @cindex editors (subcommand)
6927 @deffn Command {cvs editors} [@code{-lR}] [@var{files}]@dots{}
6929 List the users currently working on @var{files}. The report
6930 includes the mail address of each user, the time when the user began
6931 working with the file, and the host and path of the working directory
6932 containing the file.
6934 The @var{files} and options are processed as for the
6935 @code{cvs watch} commands.
6939 @node Watches Compatibility
6940 @subsection Using watches with old versions of CVS
6942 @cindex CVS 1.6, and watches
6943 If you use the watch features on a repository, it
6944 creates @file{CVS} directories in the repository and
6945 stores the information about watches in that directory.
6946 If you attempt to use @sc{cvs} 1.6 or earlier with the
6947 repository, you get an error message such as the
6948 following (all on one line):
6951 cvs update: cannot open CVS/Entries for reading:
6952 No such file or directory
6956 and your operation will likely be aborted. To use the
6957 watch features, you must upgrade all copies of @sc{cvs}
6958 which use that repository in local or server mode. If
6959 you cannot upgrade, use the @code{watch off} and
6960 @code{watch remove} commands to remove all watches, and
6961 that will restore the repository to a state which
6962 @sc{cvs} 1.6 can cope with.
6964 @node Choosing a model
6965 @section Choosing between reserved or unreserved checkouts
6966 @cindex Choosing, reserved or unreserved checkouts
6968 Reserved and unreserved checkouts each have pros and
6969 cons. Let it be said that a lot of this is a matter of
6970 opinion or what works given different groups' working
6971 styles, but here is a brief description of some of the
6972 issues. There are many ways to organize a team of
6973 developers. @sc{cvs} does not try to enforce a certain
6974 organization. It is a tool that can be used in several
6977 Reserved checkouts can be very counter-productive. If
6978 two persons want to edit different parts of a file,
6979 there may be no reason to prevent either of them from
6980 doing so. Also, it is common for someone to take out a
6981 lock on a file, because they are planning to edit it,
6982 but then forget to release the lock.
6984 @c "many groups"? specifics? cites to papers on this?
6985 @c some way to weasel-word it a bit more so we don't
6987 People, especially people who are familiar with
6988 reserved checkouts, often wonder how often conflicts
6989 occur if unreserved checkouts are used, and how
6990 difficult they are to resolve. The experience with
6991 many groups is that they occur rarely and usually are
6992 relatively straightforward to resolve.
6994 The rarity of serious conflicts may be surprising, until one realizes
6995 that they occur only when two developers disagree on the proper design
6996 for a given section of code; such a disagreement suggests that the
6997 team has not been communicating properly in the first place. In order
6998 to collaborate under @emph{any} source management regimen, developers
6999 must agree on the general design of the system; given this agreement,
7000 overlapping changes are usually straightforward to merge.
7002 In some cases unreserved checkouts are clearly
7003 inappropriate. If no merge tool exists for the kind of
7004 file you are managing (for example word processor files
7005 or files edited by Computer Aided Design programs), and
7006 it is not desirable to change to a program which uses a
7007 mergeable data format, then resolving conflicts is
7008 going to be unpleasant enough that you generally will
7009 be better off to simply avoid the conflicts instead, by
7010 using reserved checkouts.
7012 The watches features described above in @ref{Watches}
7013 can be considered to be an intermediate model between
7014 reserved checkouts and unreserved checkouts. When you
7015 go to edit a file, it is possible to find out who else
7016 is editing it. And rather than having the system
7017 simply forbid both people editing the file, it can tell
7018 you what the situation is and let you figure out
7019 whether it is a problem in that particular case or not.
7020 Therefore, for some groups watches can be
7021 considered the best of both the reserved checkout and unreserved
7024 As of @sc{cvs} client and server versions 1.12.10, you may also enable
7025 advisory locks by putting @samp{edit -c} and @samp{commit -c} in all
7026 developers' @file{.cvsrc} files. After this is done, @code{cvs edit}
7027 will fail if there are any other editors, and @code{cvs commit} will
7028 fail if the committer has not registered to edit the file via @code{cvs edit}.
7029 This is most effective in conjunction with files checked out read-only by
7030 default, which may be enabled by turning on watches in the repository or by
7031 putting @samp{cvs -r} in all @file{.cvsrc} files.
7034 @c ---------------------------------------------------------------------
7035 @node Revision management
7036 @chapter Revision management
7037 @cindex Revision management
7039 @c -- This chapter could be expanded a lot.
7040 @c -- Experiences are very welcome!
7042 If you have read this far, you probably have a pretty
7043 good grasp on what @sc{cvs} can do for you. This
7044 chapter talks a little about things that you still have
7047 If you are doing development on your own using @sc{cvs}
7048 you could probably skip this chapter. The questions
7049 this chapter takes up become more important when more
7050 than one person is working in a repository.
7053 * When to commit:: Some discussion on the subject
7056 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
7057 @node When to commit
7058 @section When to commit?
7059 @cindex When to commit
7060 @cindex Committing, when to
7063 Your group should decide which policy to use regarding
7064 commits. Several policies are possible, and as your
7065 experience with @sc{cvs} grows you will probably find
7066 out what works for you.
7068 If you commit files too quickly you might commit files
7069 that do not even compile. If your partner updates his
7070 working sources to include your buggy file, he will be
7071 unable to compile the code. On the other hand, other
7072 persons will not be able to benefit from the
7073 improvements you make to the code if you commit very
7074 seldom, and conflicts will probably be more common.
7076 It is common to only commit files after making sure
7077 that they can be compiled. Some sites require that the
7078 files pass a test suite. Policies like this can be
7079 enforced using the commitinfo file
7080 (@pxref{commitinfo}), but you should think twice before
7081 you enforce such a convention. By making the
7082 development environment too controlled it might become
7083 too regimented and thus counter-productive to the real
7084 goal, which is to get software written.
7086 @c ---------------------------------------------------------------------
7087 @node Keyword substitution
7088 @chapter Keyword substitution
7089 @cindex Keyword substitution
7090 @cindex Keyword expansion
7091 @cindex Identifying files
7093 @comment Be careful when editing this chapter.
7094 @comment Remember that this file is kept under
7095 @comment version control, so we must not accidentally
7096 @comment include a valid keyword in the running text.
7098 As long as you edit source files inside a working
7099 directory you can always find out the state of
7100 your files via @samp{cvs status} and @samp{cvs log}.
7101 But as soon as you export the files from your
7102 development environment it becomes harder to identify
7103 which revisions they are.
7105 @sc{cvs} can use a mechanism known as @dfn{keyword
7106 substitution} (or @dfn{keyword expansion}) to help
7107 identifying the files. Embedded strings of the form
7108 @code{$@var{keyword}$} and
7109 @code{$@var{keyword}:@dots{}$} in a file are replaced
7110 with strings of the form
7111 @code{$@var{keyword}:@var{value}$} whenever you obtain
7112 a new revision of the file.
7115 * Keyword list:: Keywords
7116 * Using keywords:: Using keywords
7117 * Avoiding substitution:: Avoiding substitution
7118 * Substitution modes:: Substitution modes
7119 * Configuring keyword expansion:: Configuring keyword expansion
7120 * Log keyword:: Problems with the $@splitrcskeyword{Log}$ keyword.
7123 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
7125 @section Keyword List
7126 @cindex Keyword List
7128 @c FIXME: need some kind of example here I think,
7130 @c "Keyword intro" node. The intro in the "Keyword
7131 @c substitution" node itself seems OK, but to launch
7132 @c into a list of the keywords somehow seems too abrupt.
7134 This is a list of the keywords:
7137 @cindex Author keyword
7138 @item $@splitrcskeyword{Author}$
7139 The login name of the user who checked in the revision.
7141 @cindex CVSHeader keyword
7142 @item $@splitrcskeyword{CVSHeader}$
7143 A standard header (similar to $@splitrcskeyword{Header}$, but with
7144 the CVS root stripped off). It contains the relative
7145 pathname of the @sc{rcs} file to the CVS root, the
7146 revision number, the date (UTC), the author, the state,
7147 and the locker (if locked). Files will normally never
7148 be locked when you use @sc{cvs}.
7150 Note that this keyword has only been recently
7151 introduced to @sc{cvs} and may cause problems with
7152 existing installations if $@splitrcskeyword{CVSHeader}$ is already
7153 in the files for a different purpose. This keyword may
7154 be excluded using the @code{KeywordExpand=eCVSHeader}
7155 in the @file{CVSROOT/config} file.
7156 See @ref{Configuring keyword expansion} for more details.
7158 @cindex Date keyword
7159 @item $@splitrcskeyword{Date}$
7160 The date and time (UTC) the revision was checked in.
7162 @cindex Header keyword
7163 @item $@splitrcskeyword{Header}$
7164 A standard header containing the full pathname of the
7165 @sc{rcs} file, the revision number, the date (UTC), the
7166 author, the state, and the locker (if locked). Files
7167 will normally never be locked when you use @sc{cvs}.
7170 @item $@splitrcskeyword{Id}$
7171 Same as @code{$@splitrcskeyword{Header}$}, except that the @sc{rcs}
7172 filename is without a path.
7174 @cindex Name keyword
7175 @item $@splitrcskeyword{Name}$
7176 Tag name used to check out this file. The keyword is
7177 expanded only if one checks out with an explicit tag
7178 name. For example, when running the command @code{cvs
7179 co -r first}, the keyword expands to @samp{Name: first}.
7181 @cindex Locker keyword
7182 @item $@splitrcskeyword{Locker}$
7183 The login name of the user who locked the revision
7184 (empty if not locked, which is the normal case unless
7185 @code{cvs admin -l} is in use).
7188 @cindex MaxCommentLeaderLength
7189 @cindex UseArchiveCommentLeader
7190 @cindex Log keyword, configuring substitution behavior
7191 @item $@splitrcskeyword{Log}$
7192 The log message supplied during commit, preceded by a
7193 header containing the @sc{rcs} filename, the revision
7194 number, the author, and the date (UTC). Existing log
7195 messages are @emph{not} replaced. Instead, the new log
7196 message is inserted after @code{$@splitrcskeyword{Log}:@dots{}$}.
7197 By default, each new line is prefixed with the same string which
7198 precedes the @code{$@splitrcskeyword{Log}$} keyword, unless it exceeds the
7199 @code{MaxCommentLeaderLength} set in @file{CVSROOT/config}.
7201 For example, if the file contains:
7204 /* Here is what people have been up to:
7206 * $@splitrcskeyword{Log}: frob.c,v $
7207 * Revision 1.1 1997/01/03 14:23:51 joe
7208 * Add the superfrobnicate option
7214 then additional lines which are added when expanding
7215 the @code{$@splitrcskeyword{Log}$} keyword will be preceded by @samp{ * }.
7216 Unlike previous versions of @sc{cvs} and @sc{rcs}, the
7217 @dfn{comment leader} from the @sc{rcs} file is not used.
7218 The @code{$@splitrcskeyword{Log}$} keyword is useful for
7219 accumulating a complete change log in a source file,
7220 but for several reasons it can be problematic.
7222 If the prefix of the @code{$@splitrcskeyword{Log}$} keyword turns out to be
7223 longer than @code{MaxCommentLeaderLength}, CVS will skip expansion of this
7224 keyword unless @code{UseArchiveCommentLeader} is also set in
7225 @file{CVSROOT/config} and a @samp{comment leader} is set in the RCS archive
7226 file, in which case the comment leader will be used instead. For more on
7227 setting the comment leader in the RCS archive file, @xref{admin}. For more
7228 on configuring the default @code{$@splitrcskeyword{Log}$} substitution
7229 behavior, @xref{config}.
7233 @cindex RCSfile keyword
7234 @item $@splitrcskeyword{RCSfile}$
7235 The name of the RCS file without a path.
7237 @cindex Revision keyword
7238 @item $@splitrcskeyword{Revision}$
7239 The revision number assigned to the revision.
7241 @cindex Source keyword
7242 @item $@splitrcskeyword{Source}$
7243 The full pathname of the RCS file.
7245 @cindex State keyword
7246 @item $@splitrcskeyword{State}$
7247 The state assigned to the revision. States can be
7248 assigned with @code{cvs admin -s}---see @ref{admin options}.
7250 @cindex Local keyword
7252 The @code{LocalKeyword} option in the @file{CVSROOT/config} file
7253 may be used to specify a local keyword which is to be
7254 used as an alias for one of the keywords: $@splitrcskeyword{Id}$,
7255 $@splitrcskeyword{Header}$, or $@splitrcskeyword{CVSHeader}$. For
7256 example, if the @file{CVSROOT/config} file contains
7257 a line with @code{LocalKeyword=MYBSD=CVSHeader}, then a
7258 file with the local keyword $@splitrcskeyword{MYBSD}$ will be
7259 expanded as if it were a $@splitrcskeyword{CVSHeader}$ keyword. If
7260 the src/frob.c file contained this keyword, it might
7261 look something like this:
7265 * $@splitrcskeyword{MYBSD}: src/frob.c,v 1.1 2003/05/04 09:27:45 john Exp $
7269 Many repositories make use of a such a ``local
7270 keyword'' feature. An old patch to @sc{cvs} provided
7271 the @code{LocalKeyword} feature using a @code{tag=}
7272 option and called this the ``custom tag'' or ``local
7273 tag'' feature. It was used in conjunction with the
7274 what they called the @code{tagexpand=} option. In
7275 @sc{cvs} this other option is known as the
7276 @code{KeywordExpand} option.
7277 See @ref{Configuring keyword expansion} for more
7280 Examples from popular projects include:
7281 $@splitrcskeyword{FreeBSD}$, $@splitrcskeyword{NetBSD}$,
7282 $@splitrcskeyword{OpenBSD}$, $@splitrcskeyword{XFree86}$,
7283 $@splitrcskeyword{Xorg}$.
7285 The advantage of this is that you can include your
7286 local version information in a file using this local
7287 keyword without disrupting the upstream version
7288 information (which may be a different local keyword or
7289 a standard keyword). Allowing bug reports and the like
7290 to more properly identify the source of the original
7291 bug to the third-party and reducing the number of
7292 conflicts that arise during an import of a new version.
7294 All keyword expansion except the local keyword may be
7295 disabled using the @code{KeywordExpand} option in
7296 the @file{CVSROOT/config} file---see
7297 @ref{Configuring keyword expansion} for more details.
7301 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
7302 @node Using keywords
7303 @section Using keywords
7305 To include a keyword string you simply include the
7306 relevant text string, such as @code{$@splitrcskeyword{Id}$}, inside the
7307 file, and commit the file. @sc{cvs} will automatically (Or,
7308 more accurately, as part of the update run that
7309 automatically happens after a commit.)
7310 expand the string as part of the commit operation.
7312 It is common to embed the @code{$@splitrcskeyword{Id}$} string in
7313 the source files so that it gets passed through to
7314 generated files. For example, if you are managing
7315 computer program source code, you might include a
7316 variable which is initialized to contain that string.
7317 Or some C compilers may provide a @code{#pragma ident}
7318 directive. Or a document management system might
7319 provide a way to pass a string through to generated
7322 @c Would be nice to give an example, but doing this in
7323 @c portable C is not possible and the problem with
7324 @c picking any one language (VMS HELP files, Ada,
7325 @c troff, whatever) is that people use CVS for all
7328 @cindex Ident (shell command)
7329 The @code{ident} command (which is part of the @sc{rcs}
7330 package) can be used to extract keywords and their
7331 values from a file. This can be handy for text files,
7332 but it is even more useful for extracting keywords from
7338 $@splitrcskeyword{Id}: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
7342 $@splitrcskeyword{Id}: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
7345 @cindex What (shell command)
7346 S@sc{ccs} is another popular revision control system.
7347 It has a command, @code{what}, which is very similar to
7348 @code{ident} and used for the same purpose. Many sites
7349 without @sc{rcs} have @sc{sccs}. Since @code{what}
7350 looks for the character sequence @code{@@(#)} it is
7351 easy to include keywords that are detected by either
7352 command. Simply prefix the keyword with the
7353 magic @sc{sccs} phrase, like this:
7356 static char *id="@@(#) $@splitrcskeyword{Id}: ab.c,v 1.5 1993/10/19 14:57:32 ceder Exp $";
7359 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
7360 @node Avoiding substitution
7361 @section Avoiding substitution
7363 Keyword substitution has its disadvantages. Sometimes
7364 you might want the literal text string
7365 @samp{$@splitrcskeyword{Author}$} to appear inside a file without
7366 @sc{cvs} interpreting it as a keyword and expanding it
7367 into something like @samp{$@splitrcskeyword{Author}: ceder $}.
7369 There is unfortunately no way to selectively turn off
7370 keyword substitution. You can use @samp{-ko}
7371 (@pxref{Substitution modes}) to turn off keyword
7372 substitution entirely.
7374 In many cases you can avoid using keywords in
7375 the source, even though they appear in the final
7376 product. For example, the source for this manual
7377 contains @samp{$@@asis@{@}Author$} whenever the text
7378 @samp{$@splitrcskeyword{Author}$} should appear. In @code{nroff}
7379 and @code{troff} you can embed the null-character
7380 @code{\&} inside the keyword for a similar effect.
7382 It is also possible to specify an explicit list of
7383 keywords to include or exclude using the
7384 @code{KeywordExpand} option in the
7385 @file{CVSROOT/config} file--see @ref{Configuring keyword expansion}
7386 for more details. This feature is intended primarily
7387 for use with the @code{LocalKeyword} option--see
7390 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
7391 @node Substitution modes
7392 @section Substitution modes
7393 @cindex Keyword substitution, changing modes
7394 @cindex -k (keyword substitution)
7397 @c FIXME: This could be made more coherent, by expanding it
7398 @c with more examples or something.
7399 Each file has a stored default substitution mode, and
7400 each working directory copy of a file also has a
7401 substitution mode. The former is set by the @samp{-k}
7402 option to @code{cvs add} and @code{cvs admin}; the
7403 latter is set by the @samp{-k} or @samp{-A} options to @code{cvs
7404 checkout} or @code{cvs update}. @code{cvs diff} also
7405 has a @samp{-k} option. For some examples,
7406 see @ref{Binary files}, and @ref{Merging and keywords}.
7407 @c The fact that -A is overloaded to mean both reset
7408 @c sticky options and reset sticky tags/dates is
7409 @c somewhat questionable. Perhaps there should be
7410 @c separate options to reset sticky options (e.g. -k
7411 @c A") and tags/dates (someone suggested -r HEAD could
7412 @c do this instead of setting a sticky tag of "HEAD"
7413 @c as in the status quo but I haven't thought much
7414 @c about that idea. Of course -r .reset or something
7415 @c could be coined if this needs to be a new option).
7416 @c On the other hand, having -A mean "get things back
7417 @c into the state after a fresh checkout" has a certain
7418 @c appeal, and maybe there is no sufficient reason for
7419 @c creeping featurism in this area.
7421 The modes available are:
7425 Generate keyword strings using the default form, e.g.
7426 @code{$@splitrcskeyword{Revision}: 5.7 $} for the @code{Revision}
7430 Like @samp{-kkv}, except that a locker's name is always
7431 inserted if the given revision is currently locked.
7432 The locker's name is only relevant if @code{cvs admin
7436 Generate only keyword names in keyword strings; omit
7437 their values. For example, for the @code{Revision}
7438 keyword, generate the string @code{$@splitrcskeyword{Revision}$}
7439 instead of @code{$@splitrcskeyword{Revision}: 5.7 $}. This option
7440 is useful to ignore differences due to keyword
7441 substitution when comparing different revisions of a
7442 file (@pxref{Merging and keywords}).
7445 Generate the old keyword string, present in the working
7446 file just before it was checked in. For example, for
7447 the @code{Revision} keyword, generate the string
7448 @code{$@splitrcskeyword{Revision}: 1.1 $} instead of
7449 @code{$@splitrcskeyword{Revision}: 5.7 $} if that is how the
7450 string appeared when the file was checked in.
7453 Like @samp{-ko}, but also inhibit conversion of line
7454 endings between the canonical form in which they are
7455 stored in the repository (linefeed only), and the form
7456 appropriate to the operating system in use on the
7457 client. For systems, like unix, which use linefeed
7458 only to terminate lines, this is very similar to
7459 @samp{-ko}. For more information on binary files, see
7460 @ref{Binary files}. In @sc{cvs} version 1.12.2 and later
7461 @samp{-kb}, as set by @code{cvs add}, @code{cvs admin}, or
7462 @code{cvs import} may not be overridden by a @samp{-k} option
7463 specified on the command line.
7466 Generate only keyword values for keyword strings. For
7467 example, for the @code{Revision} keyword, generate the string
7468 @code{5.7} instead of @code{$@splitrcskeyword{Revision}: 5.7 $}.
7469 This can help generate files in programming languages
7470 where it is hard to strip keyword delimiters like
7471 @code{$@splitrcskeyword{Revision}: $} from a string. However,
7472 further keyword substitution cannot be performed once
7473 the keyword names are removed, so this option should be
7476 One often would like to use @samp{-kv} with @code{cvs
7477 export}---@pxref{export}. But be aware that doesn't
7478 handle an export containing binary files correctly.
7482 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
7483 @node Configuring keyword expansion
7484 @section Configuring Keyword Expansion
7485 @cindex Configuring keyword expansion
7487 In a repository that includes third-party software on
7488 vendor branches, it is sometimes helpful to configure
7489 CVS to use a local keyword instead of the standard
7490 $@splitrcskeyword{Id}$ or $@splitrcskeyword{Header}$ keywords. Examples from
7491 real projects include $@splitrcskeyword{Xorg}$, $@splitrcskeyword{XFree86}$,
7492 $@splitrcskeyword{FreeBSD}$, $@splitrcskeyword{NetBSD}$,
7493 $@splitrcskeyword{OpenBSD}$, and even $@splitrcskeyword{dotat}$.
7494 The advantage of this is that
7495 you can include your local version information in a
7496 file using this local keyword (sometimes called a
7497 ``custom tag'' or a ``local tag'') without disrupting
7498 the upstream version information (which may be a
7499 different local keyword or a standard keyword). In
7500 these cases, it is typically desirable to disable the
7501 expansion of all keywords except the configured local
7504 The @code{KeywordExpand} option in the
7505 @file{CVSROOT/config} file is intended to allow for the
7506 either the explicit exclusion of a keyword or list of
7507 keywords, or for the explicit inclusion of a keyword or
7508 a list of keywords. This list may include the
7509 @code{LocalKeyword} that has been configured.
7511 The @code{KeywordExpand} option is followed by
7512 @code{=} and the next character may either be @code{i}
7513 to start an inclusion list or @code{e} to start an
7514 exclusion list. If the following lines were added to
7515 the @file{CVSROOT/config} file:
7518 # Add a "MyBSD" keyword and restrict keyword
7520 LocalKeyword=MyBSD=CVSHeader
7521 KeywordExpand=iMyBSD
7524 then only the $@splitrcskeyword{MyBSD}$ keyword would be expanded.
7525 A list may be used. The this example:
7528 # Add a "MyBSD" keyword and restrict keyword
7529 # expansion to the MyBSD, Name and Date keywords.
7530 LocalKeyword=MyBSD=CVSHeader
7531 KeywordExpand=iMyBSD,Name,Date
7534 would allow $@splitrcskeyword{MyBSD}$, $@splitrcskeyword{Name}$, and
7535 $@splitrcskeyword{Date}$ to be expanded.
7537 It is also possible to configure an exclusion list
7538 using the following:
7541 # Do not expand the non-RCS keyword CVSHeader
7542 KeywordExpand=eCVSHeader
7545 This allows @sc{cvs} to ignore the recently introduced
7546 $@splitrcskeyword{CVSHeader}$ keyword and retain all of the
7547 others. The exclusion entry could also contain the
7548 standard RCS keyword list, but this could be confusing
7549 to users that expect RCS keywords to be expanded, so
7550 care should be taken to properly set user expectations
7551 for a repository that is configured in that manner.
7553 If there is a desire to not have any RCS keywords
7554 expanded and not use the @code{-ko} flags everywhere,
7555 an administrator may disable all keyword expansion
7556 using the @file{CVSROOT/config} line:
7559 # Do not expand any RCS keywords
7563 this could be confusing to users that expect RCS
7564 keywords like $@splitrcskeyword{Id}$ to be expanded properly,
7565 so care should be taken to properly set user
7566 expectations for a repository so configured.
7568 It should be noted that a patch to provide both the
7569 @code{KeywordExpand} and @code{LocalKeyword} features
7570 has been around a long time. However, that patch
7571 implemented these features using @code{tag=} and
7572 @code{tagexpand=} keywords and those keywords are NOT
7575 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
7577 @section Problems with the $@splitrcskeyword{Log}$ keyword.
7579 The @code{$@splitrcskeyword{Log}$} keyword is somewhat
7580 controversial. As long as you are working on your
7581 development system the information is easily accessible
7582 even if you do not use the @code{$@splitrcskeyword{Log}$}
7583 keyword---just do a @code{cvs log}. Once you export
7584 the file the history information might be useless
7587 A more serious concern is that @sc{cvs} is not good at
7588 handling @code{$@splitrcskeyword{Log}$} entries when a branch is
7589 merged onto the main trunk. Conflicts often result
7590 from the merging operation.
7591 @c Might want to check whether the CVS implementation
7592 @c of RCS_merge has this problem the same way rcsmerge
7593 @c does. I would assume so....
7595 People also tend to "fix" the log entries in the file
7596 (correcting spelling mistakes and maybe even factual
7597 errors). If that is done the information from
7598 @code{cvs log} will not be consistent with the
7599 information inside the file. This may or may not be a
7600 problem in real life.
7602 It has been suggested that the @code{$@splitrcskeyword{Log}$}
7603 keyword should be inserted @emph{last} in the file, and
7604 not in the files header, if it is to be used at all.
7605 That way the long list of change messages will not
7606 interfere with everyday source file browsing.
7608 @c ---------------------------------------------------------------------
7609 @node Tracking sources
7610 @chapter Tracking third-party sources
7611 @cindex Third-party sources
7612 @cindex Tracking sources
7614 @c FIXME: Need discussion of added and removed files.
7615 @c FIXME: This doesn't really adequately introduce the
7616 @c concepts of "vendor" and "you". They don't *have*
7617 @c to be separate organizations or separate people.
7618 @c We want a description which is somewhat more based on
7619 @c the technical issues of which sources go where, but
7620 @c also with enough examples of how this relates to
7621 @c relationships like customer-supplier, developer-QA,
7622 @c maintainer-contributor, or whatever, to make it
7624 If you modify a program to better fit your site, you
7625 probably want to include your modifications when the next
7626 release of the program arrives. @sc{cvs} can help you with
7630 @cindex Vendor branch
7631 @cindex Branch, vendor-
7632 In the terminology used in @sc{cvs}, the supplier of the
7633 program is called a @dfn{vendor}. The unmodified
7634 distribution from the vendor is checked in on its own
7635 branch, the @dfn{vendor branch}. @sc{cvs} reserves branch
7638 When you modify the source and commit it, your revision
7639 will end up on the main trunk. When a new release is
7640 made by the vendor, you commit it on the vendor branch
7641 and copy the modifications onto the main trunk.
7643 Use the @code{import} command to create and update
7644 the vendor branch. When you import a new file,
7645 (usually) the vendor branch is made the `head' revision, so
7646 anyone that checks out a copy of the file gets that
7647 revision. When a local modification is committed it is
7648 placed on the main trunk, and made the `head'
7652 * First import:: Importing for the first time
7653 * Update imports:: Updating with the import command
7654 * Reverting local changes:: Reverting to the latest vendor release
7655 * Binary files in imports:: Binary files require special handling
7656 * Keywords in imports:: Keyword substitution might be undesirable
7657 * Multiple vendor branches:: What if you get sources from several places?
7660 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
7662 @section Importing for the first time
7663 @cindex Importing modules
7665 @c Should mention naming conventions for vendor tags,
7666 @c release tags, and perhaps directory names.
7667 Use the @code{import} command to check in the sources
7668 for the first time. When you use the @code{import}
7669 command to track third-party sources, the @dfn{vendor
7670 tag} and @dfn{release tags} are useful. The
7671 @dfn{vendor tag} is a symbolic name for the branch
7672 (which is always 1.1.1, unless you use the @samp{-b
7673 @var{branch}} flag---see @ref{Multiple vendor branches}.). The
7674 @dfn{release tags} are symbolic names for a particular
7675 release, such as @samp{FSF_0_04}.
7677 @c I'm not completely sure this belongs here. But
7678 @c we need to say it _somewhere_ reasonably obvious; it
7679 @c is a common misconception among people first learning CVS
7680 Note that @code{import} does @emph{not} change the
7681 directory in which you invoke it. In particular, it
7682 does not set up that directory as a @sc{cvs} working
7683 directory; if you want to work with the sources import
7684 them first and then check them out into a different
7685 directory (@pxref{Getting the source}).
7687 @cindex wdiff (import example)
7688 Suppose you have the sources to a program called
7689 @code{wdiff} in a directory @file{wdiff-0.04},
7690 and are going to make private modifications that you
7691 want to be able to use even when new releases are made
7692 in the future. You start by importing the source to
7697 $ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04
7700 The vendor tag is named @samp{FSF_DIST} in the above
7701 example, and the only release tag assigned is
7703 @c FIXME: Need to say where fsf/wdiff comes from.
7705 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
7706 @node Update imports
7707 @section Updating with the import command
7709 When a new release of the source arrives, you import it into the
7710 repository with the same @code{import} command that you used to set up
7711 the repository in the first place. The only difference is that you
7712 specify a different release tag this time:
7715 $ tar xfz wdiff-0.05.tar.gz
7717 $ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF_DIST WDIFF_0_05
7720 @strong{WARNING: If you use a release tag that already exists in one of the
7721 repository archives, files removed by an import may not be detected.}
7723 For files that have not been modified locally, the newly created
7724 revision becomes the head revision. If you have made local
7725 changes, @code{import} will warn you that you must merge the changes
7726 into the main trunk, and tell you to use @samp{checkout -j} to do so:
7728 @c FIXME: why "wdiff" here and "fsf/wdiff" in the
7729 @c "import"? I think the assumption is that one has
7730 @c "wdiff fsf/wdiff" or some such in modules, but it
7731 @c would be better to not use modules in this example.
7733 $ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff
7737 The above command will check out the latest revision of
7738 @samp{wdiff}, merging the changes made on the vendor branch @samp{FSF_DIST}
7739 since yesterday into the working copy. If any conflicts arise during
7740 the merge they should be resolved in the normal way (@pxref{Conflicts
7741 example}). Then, the modified files may be committed.
7743 However, it is much better to use the two release tags rather than using
7744 a date on the branch as suggested above:
7747 $ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff
7751 The reason this is better is that
7752 using a date, as suggested above, assumes that you do
7753 not import more than one release of a product per day.
7754 More importantly, using the release tags allows @sc{cvs} to detect files
7755 that were removed between the two vendor releases and mark them for
7756 removal. Since @code{import} has no way to detect removed files, you
7757 should do a merge like this even if @code{import} doesn't tell you to.
7759 @node Reverting local changes
7760 @section Reverting to the latest vendor release
7762 You can also revert local changes completely and return
7763 to the latest vendor release by changing the `head'
7764 revision back to the vendor branch on all files. For
7765 example, if you have a checked-out copy of the sources
7766 in @file{~/work.d/wdiff}, and you want to revert to the
7767 vendor's version for all the files in that directory,
7772 $ cvs admin -bFSF_DIST .
7776 You must specify the @samp{-bFSF_DIST} without any space
7777 after the @samp{-b}. @xref{admin options}.
7779 @node Binary files in imports
7780 @section How to handle binary files with cvs import
7782 Use the @samp{-k} wrapper option to tell import which
7783 files are binary. @xref{Wrappers}.
7785 @node Keywords in imports
7786 @section How to handle keyword substitution with cvs import
7788 The sources which you are importing may contain
7789 keywords (@pxref{Keyword substitution}). For example,
7790 the vendor may use @sc{cvs} or some other system
7791 which uses similar keyword expansion syntax. If you
7792 just import the files in the default fashion, then
7793 the keyword expansions supplied by the vendor will
7794 be replaced by keyword expansions supplied by your
7795 own copy of @sc{cvs}. It may be more convenient to
7796 maintain the expansions supplied by the vendor, so
7797 that this information can supply information about
7798 the sources that you imported from the vendor.
7800 To maintain the keyword expansions supplied by the
7801 vendor, supply the @samp{-ko} option to @code{cvs
7802 import} the first time you import the file.
7803 This will turn off keyword expansion
7804 for that file entirely, so if you want to be more
7805 selective you'll have to think about what you want
7806 and use the @samp{-k} option to @code{cvs update} or
7807 @code{cvs admin} as appropriate.
7808 @c Supplying -ko to import if the file already existed
7809 @c has no effect. Not clear to me whether it should
7812 @node Multiple vendor branches
7813 @section Multiple vendor branches
7815 All the examples so far assume that there is only one
7816 vendor from which you are getting sources. In some
7817 situations you might get sources from a variety of
7818 places. For example, suppose that you are dealing with
7819 a project where many different people and teams are
7820 modifying the software. There are a variety of ways to
7821 handle this, but in some cases you have a bunch of
7822 source trees lying around and what you want to do more
7823 than anything else is just to all put them in @sc{cvs} so
7824 that you at least have them in one place.
7826 For handling situations in which there may be more than
7827 one vendor, you may specify the @samp{-b} option to
7828 @code{cvs import}. It takes as an argument the vendor
7829 branch to import to. The default is @samp{-b 1.1.1}.
7831 For example, suppose that there are two teams, the red
7832 team and the blue team, that are sending you sources.
7833 You want to import the red team's efforts to branch
7834 1.1.1 and use the vendor tag RED. You want to import
7835 the blue team's efforts to branch 1.1.3 and use the
7836 vendor tag BLUE. So the commands you might use are:
7839 $ cvs import dir RED RED_1-0
7840 $ cvs import -b 1.1.3 dir BLUE BLUE_1-5
7843 Note that if your vendor tag does not match your
7844 @samp{-b} option, @sc{cvs} will not detect this case! For
7848 $ cvs import -b 1.1.3 dir RED RED_1-0
7852 Be careful; this kind of mismatch is sure to sow
7853 confusion or worse. I can't think of a useful purpose
7854 for the ability to specify a mismatch here, but if you
7855 discover such a use, don't. @sc{cvs} is likely to make this
7856 an error in some future release.
7858 @c Probably should say more about the semantics of
7859 @c multiple branches. What about the default branch?
7860 @c What about joining (perhaps not as useful with
7861 @c multiple branches, or perhaps it is. Either way
7862 @c should be mentioned).
7864 @c I'm not sure about the best location for this. In
7865 @c one sense, it might belong right after we've introduced
7866 @c CVS's basic version control model, because people need
7867 @c to figure out builds right away. The current location
7868 @c is based on the theory that it kind of akin to the
7869 @c "Revision management" section.
7871 @chapter How your build system interacts with CVS
7875 As mentioned in the introduction, @sc{cvs} does not
7876 contain software for building your software from source
7877 code. This section describes how various aspects of
7878 your build system might interact with @sc{cvs}.
7880 @c Is there a way to discuss this without reference to
7881 @c tools other than CVS? I'm not sure there is; I
7882 @c wouldn't think that people who learn CVS first would
7883 @c even have this concern.
7884 One common question, especially from people who are
7885 accustomed to @sc{rcs}, is how to make their build get
7886 an up to date copy of the sources. The answer to this
7887 with @sc{cvs} is two-fold. First of all, since
7888 @sc{cvs} itself can recurse through directories, there
7889 is no need to modify your @file{Makefile} (or whatever
7890 configuration file your build tool uses) to make sure
7891 each file is up to date. Instead, just use two
7892 commands, first @code{cvs -q update} and then
7893 @code{make} or whatever the command is to invoke your
7894 build tool. Secondly, you do not necessarily
7895 @emph{want} to get a copy of a change someone else made
7896 until you have finished your own work. One suggested
7897 approach is to first update your sources, then
7898 implement, build and
7899 test the change you were thinking of, and then commit
7900 your sources (updating first if necessary). By
7901 periodically (in between changes, using the approach
7902 just described) updating your entire tree, you ensure
7903 that your sources are sufficiently up to date.
7905 @cindex Bill of materials
7906 One common need is to record which versions of which
7907 source files went into a particular build. This kind
7908 of functionality is sometimes called @dfn{bill of
7909 materials} or something similar. The best way to do
7910 this with @sc{cvs} is to use the @code{tag} command to
7911 record which versions went into a given build
7914 Using @sc{cvs} in the most straightforward manner
7915 possible, each developer will have a copy of the entire
7916 source tree which is used in a particular build. If
7917 the source tree is small, or if developers are
7918 geographically dispersed, this is the preferred
7919 solution. In fact one approach for larger projects is
7920 to break a project down into smaller
7921 @c I say subsystem instead of module because they may or
7922 @c may not use the modules file.
7923 separately-compiled subsystems, and arrange a way of
7924 releasing them internally so that each developer need
7925 check out only those subsystems which they are
7926 actively working on.
7928 Another approach is to set up a structure which allows
7929 developers to have their own copies of some files, and
7930 for other files to access source files from a central
7931 location. Many people have come up with some such a
7932 @c two such people are paul@sander.cupertino.ca.us (for
7933 @c a previous employer)
7934 @c and gtornblo@senet.abb.se (spicm and related tools),
7935 @c but as far as I know
7936 @c no one has nicely packaged or released such a system (or
7937 @c instructions for constructing one).
7938 system using features such as the symbolic link feature
7939 found in many operating systems, or the @code{VPATH}
7940 feature found in many versions of @code{make}. One build
7941 tool which is designed to help with this kind of thing
7943 @code{ftp://ftp.cs.colorado.edu/pub/distribs/odin}).
7944 @c Should we be saying more about Odin? Or how you use
7945 @c it with CVS? Also, the Prime Time Freeware for Unix
7946 @c disk (see http://www.ptf.com/) has Odin (with a nice
7947 @c paragraph summarizing it on the web), so that might be a
7948 @c semi-"official" place to point people.
7950 @c Of course, many non-CVS systems have this kind of
7951 @c functionality, for example OSF's ODE
7952 @c (http://www.osf.org/ode/) or mk
7953 @c (http://www.grin.net/~pzi/mk-3.18.4.docs/mk_toc.html
7954 @c He has changed providers in the past; a search engine search
7955 @c for "Peter Ziobrzynski" probably won't get too many
7956 @c spurious hits :-). A more stable URL might be
7957 @c ftp://ftp.uu.net/pub/cmvc/mk). But I'm not sure
7958 @c there is any point in mentioning them here unless they
7959 @c can work with CVS.
7961 @c ---------------------------------------------------------------------
7963 @chapter Special Files
7965 @cindex Special files
7966 @cindex Device nodes
7967 @cindex Ownership, saving in CVS
7968 @cindex Permissions, saving in CVS
7970 @cindex Symbolic links
7972 In normal circumstances, @sc{cvs} works only with regular
7973 files. Every file in a project is assumed to be
7974 persistent; it must be possible to open, read and close
7975 them; and so on. @sc{cvs} also ignores file permissions and
7976 ownerships, leaving such issues to be resolved by the
7977 developer at installation time. In other words, it is
7978 not possible to "check in" a device into a repository;
7979 if the device file cannot be opened, @sc{cvs} will refuse to
7980 handle it. Files also lose their ownerships and
7981 permissions during repository transactions.
7984 If the configuration variable @code{PreservePermissions}
7985 (@pxref{config}) is set in the repository, @sc{cvs} will
7986 save the following file characteristics in the
7990 @item user and group ownership
7992 @item major and minor device numbers
7993 @item symbolic links
7994 @item hard link structure
7997 Using the @code{PreservePermissions} option affects the
7998 behavior of @sc{cvs} in several ways. First, some of the
7999 new operations supported by @sc{cvs} are not accessible to
8000 all users. In particular, file ownership and special
8001 file characteristics may only be changed by the
8002 superuser. When the @code{PreservePermissions}
8003 configuration variable is set, therefore, users will
8004 have to be `root' in order to perform @sc{cvs} operations.
8006 When @code{PreservePermissions} is in use, some @sc{cvs}
8007 operations (such as @samp{cvs status}) will not
8008 recognize a file's hard link structure, and so will
8009 emit spurious warnings about mismatching hard links.
8010 The reason is that @sc{cvs}'s internal structure does not
8011 make it easy for these operations to collect all the
8012 necessary data about hard links, so they check for file
8013 conflicts with inaccurate data.
8015 A more subtle difference is that @sc{cvs} considers a file
8016 to have changed only if its contents have changed
8017 (specifically, if the modification time of the working
8018 file does not match that of the repository's file).
8019 Therefore, if only the permissions, ownership or hard
8020 linkage have changed, or if a device's major or minor
8021 numbers have changed, @sc{cvs} will not notice. In order to
8022 commit such a change to the repository, you must force
8023 the commit with @samp{cvs commit -f}. This also means
8024 that if a file's permissions have changed and the
8025 repository file is newer than the working copy,
8026 performing @samp{cvs update} will silently change the
8027 permissions on the working copy.
8029 Changing hard links in a @sc{cvs} repository is particularly
8030 delicate. Suppose that file @file{foo} is linked to
8031 file @file{old}, but is later relinked to file
8032 @file{new}. You can wind up in the unusual situation
8033 where, although @file{foo}, @file{old} and @file{new}
8034 have all had their underlying link patterns changed,
8035 only @file{foo} and @file{new} have been modified, so
8036 @file{old} is not considered a candidate for checking
8037 in. It can be very easy to produce inconsistent
8038 results this way. Therefore, we recommend that when it
8039 is important to save hard links in a repository, the
8040 prudent course of action is to @code{touch} any file
8041 whose linkage or status has changed since the last
8042 checkin. Indeed, it may be wise to @code{touch *}
8043 before each commit in a directory with complex hard
8046 It is worth noting that only regular files may
8047 be merged, for reasons that hopefully are obvious. If
8048 @samp{cvs update} or @samp{cvs checkout -j} attempts to
8049 merge a symbolic link with a regular file, or two
8050 device files for different kinds of devices, @sc{cvs} will
8051 report a conflict and refuse to perform the merge. At
8052 the same time, @samp{cvs diff} will not report any
8053 differences between these files, since no meaningful
8054 textual comparisons can be made on files which contain
8057 The @code{PreservePermissions} features do not work
8058 with client/server @sc{cvs}. Another limitation is
8059 that hard links must be to other files within the same
8060 directory; hard links across directories are not
8064 @c ---------------------------------------------------------------------
8065 @c ----- START MAN 1 -----
8067 @appendix Guide to CVS commands
8069 This appendix describes the overall structure of
8070 @sc{cvs} commands, and describes some commands in
8071 detail (others are described elsewhere; for a quick
8072 reference to @sc{cvs} commands, @pxref{Invoking CVS}).
8073 @c The idea is that we want to move the commands which
8074 @c are described here into the main body of the manual,
8075 @c in the process reorganizing the manual to be
8076 @c organized around what the user wants to do, not
8077 @c organized around CVS commands.
8079 @c Note that many users do expect a manual which is
8080 @c organized by command. At least some users do.
8081 @c One good addition to the "organized by command"
8082 @c section (if any) would be "see also" links.
8083 @c The awk manual might be a good example; it has a
8084 @c reference manual which is more verbose than Invoking
8085 @c CVS but probably somewhat less verbose than CVS
8089 * Structure:: Overall structure of CVS commands
8090 * Exit status:: Indicating CVS's success or failure
8091 * ~/.cvsrc:: Default options with the ~/.cvsrc file
8092 * Global options:: Options you give to the left of cvs_command
8093 * Common options:: Options you give to the right of cvs_command
8094 * Date input formats:: Acceptable formats for date specifications
8095 * admin:: Administration
8096 * annotate:: What revision modified each line of a file?
8097 * checkout:: Checkout sources for editing
8098 * commit:: Check files into the repository
8099 * diff:: Show differences between revisions
8100 * export:: Export sources from CVS, similar to checkout
8101 * history:: Show status of files and users
8102 * import:: Import sources into CVS, using vendor branches
8103 * log:: Show log messages for files
8104 * ls & rls:: List files in the repository
8105 * rdiff:: 'patch' format diffs between releases
8106 * release:: Indicate that a directory is no longer in use
8107 * update:: Bring work tree in sync with repository
8110 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
8112 @appendixsec Overall structure of CVS commands
8114 @cindex CVS command structure
8115 @cindex Command structure
8116 @cindex Format of CVS commands
8118 The overall format of all @sc{cvs} commands is:
8121 cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ]
8126 The name of the @sc{cvs} program.
8129 Some options that affect all sub-commands of @sc{cvs}. These are
8133 One of several different sub-commands. Some of the commands have
8134 aliases that can be used instead; those aliases are noted in the
8135 reference manual for that command. There are only two situations
8136 where you may omit @samp{cvs_command}: @samp{cvs -H} elicits a
8137 list of available commands, and @samp{cvs -v} displays version
8138 information on @sc{cvs} itself.
8140 @item command_options
8141 Options that are specific for the command.
8144 Arguments to the commands.
8147 There is unfortunately some confusion between
8148 @code{cvs_options} and @code{command_options}.
8149 When given as a @code{cvs_option}, some options only
8150 affect some of the commands. When given as a
8151 @code{command_option} it may have a different meaning, and
8152 be accepted by more commands. In other words, do not
8153 take the above categorization too seriously. Look at
8154 the documentation instead.
8157 @appendixsec CVS's exit status
8158 @cindex Exit status, of CVS
8160 @sc{cvs} can indicate to the calling environment whether it
8161 succeeded or failed by setting its @dfn{exit status}.
8162 The exact way of testing the exit status will vary from
8163 one operating system to another. For example in a unix
8164 shell script the @samp{$?} variable will be 0 if the
8165 last command returned a successful exit status, or
8166 greater than 0 if the exit status indicated failure.
8168 If @sc{cvs} is successful, it returns a successful status;
8169 if there is an error, it prints an error message and
8170 returns a failure status. The one exception to this is
8171 the @code{cvs diff} command. It will return a
8172 successful status if it found no differences, or a
8173 failure status if there were differences or if there
8174 was an error. Because this behavior provides no good
8175 way to detect errors, in the future it is possible that
8176 @code{cvs diff} will be changed to behave like the
8177 other @sc{cvs} commands.
8178 @c It might seem like checking whether cvs -q diff
8179 @c produces empty or non-empty output can tell whether
8180 @c there were differences or not. But it seems like
8181 @c there are cases with output but no differences
8182 @c (testsuite basica-8b). It is not clear to me how
8183 @c useful it is for a script to be able to check
8184 @c whether there were differences.
8185 @c FIXCVS? In previous versions of CVS, cvs diff
8186 @c returned 0 for no differences, 1 for differences, or
8187 @c 2 for errors. Is this behavior worth trying to
8188 @c bring back (but what does it mean for VMS?)?
8190 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
8192 @appendixsec Default options and the ~/.cvsrc file
8194 @cindex Option defaults
8196 There are some @code{command_options} that are used so
8197 often that you might have set up an alias or some other
8198 means to make sure you always specify that option. One
8199 example (the one that drove the implementation of the
8200 @file{.cvsrc} support, actually) is that many people find the
8201 default output of the @samp{diff} command to be very
8202 hard to read, and that either context diffs or unidiffs
8203 are much easier to understand.
8205 The @file{~/.cvsrc} file is a way that you can add
8206 default options to @code{cvs_commands} within cvs,
8207 instead of relying on aliases or other shell scripts.
8209 The format of the @file{~/.cvsrc} file is simple. The
8210 file is searched for a line that begins with the same
8211 name as the @code{cvs_command} being executed. If a
8212 match is found, then the remainder of the line is split
8213 up (at whitespace characters) into separate options and
8214 added to the command arguments @emph{before} any
8215 options from the command line.
8217 If a command has two names (e.g., @code{checkout} and
8218 @code{co}), the official name, not necessarily the one
8219 used on the command line, will be used to match against
8220 the file. So if this is the contents of the user's
8221 @file{~/.cvsrc} file:
8233 the command @samp{cvs checkout foo} would have the
8234 @samp{-P} option added to the arguments, as well as
8237 With the example file above, the output from @samp{cvs
8238 diff foobar} will be in unidiff format. @samp{cvs diff
8239 -c foobar} will provide context diffs, as usual.
8240 Getting "old" format diffs would be slightly more
8241 complicated, because @code{diff} doesn't have an option
8242 to specify use of the "old" format, so you would need
8243 @samp{cvs -f diff foobar}.
8245 In place of the command name you can use @code{cvs} to
8246 specify global options (@pxref{Global options}). For
8247 example the following line in @file{.cvsrc}
8254 causes @sc{cvs} to use compression level 6.
8256 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
8257 @node Global options
8258 @appendixsec Global options
8259 @cindex Options, global
8260 @cindex Global options
8261 @cindex Left-hand options
8263 The available @samp{cvs_options} (that are given to the
8264 left of @samp{cvs_command}) are:
8267 @item --allow-root=@var{rootdir}
8268 May be invoked multiple times to specify one legal @sc{cvsroot} directory with
8269 each invocation. Also causes CVS to preparse the configuration file for each
8270 specified root, which can be useful when configuring write proxies, See
8271 @ref{Password authentication server} & @ref{Write proxies}.
8273 @cindex Authentication, stream
8274 @cindex Stream authentication
8276 Authenticate all communication between the client and
8277 the server. Only has an effect on the @sc{cvs} client.
8278 As of this writing, this is only implemented when using
8279 a GSSAPI connection (@pxref{GSSAPI authenticated}).
8280 Authentication prevents certain sorts of attacks
8281 involving hijacking the active @sc{tcp} connection.
8282 Enabling authentication does not enable encryption.
8284 @cindex RCSBIN, overriding
8285 @cindex Overriding RCSBIN
8286 @item -b @var{bindir}
8287 In @sc{cvs} 1.9.18 and older, this specified that
8288 @sc{rcs} programs are in the @var{bindir} directory.
8289 Current versions of @sc{cvs} do not run @sc{rcs}
8290 programs; for compatibility this option is accepted,
8291 but it does nothing.
8293 @cindex TMPDIR, overriding
8294 @cindex Overriding TMPDIR
8295 @item -T @var{tempdir}
8296 Use @var{tempdir} as the directory where temporary files are
8297 located. Overrides the setting of the @code{$TMPDIR} environment
8298 variable and any precompiled directory. This parameter should be
8299 specified as an absolute pathname.
8300 (When running client/server, @samp{-T} affects only the local process;
8301 specifying @samp{-T} for the client has no effect on the server and
8304 @cindex CVSROOT, overriding
8305 @cindex Overriding CVSROOT
8306 @item -d @var{cvs_root_directory}
8307 Use @var{cvs_root_directory} as the root directory
8308 pathname of the repository. Overrides the setting of
8309 the @code{$CVSROOT} environment variable. @xref{Repository}.
8311 @cindex EDITOR, overriding
8312 @cindex Overriding EDITOR
8313 @item -e @var{editor}
8314 Use @var{editor} to enter revision log information. Overrides the
8315 setting of the @code{$CVSEDITOR} and @code{$EDITOR}
8316 environment variables. For more information, see
8317 @ref{Committing your changes}.
8320 Do not read the @file{~/.cvsrc} file. This
8321 option is most often used because of the
8322 non-orthogonality of the @sc{cvs} option set. For
8323 example, the @samp{cvs log} option @samp{-N} (turn off
8324 display of tag names) does not have a corresponding
8325 option to turn the display on. So if you have
8326 @samp{-N} in the @file{~/.cvsrc} entry for @samp{log},
8327 you may need to use @samp{-f} to show the tag names.
8331 Display usage information about the specified @samp{cvs_command}
8332 (but do not actually execute the command). If you don't specify
8333 a command name, @samp{cvs -H} displays overall help for
8334 @sc{cvs}, including a list of other help options.
8335 @c It seems to me it is better to document it this way
8336 @c rather than trying to update this documentation
8337 @c every time that we add a --help-foo option. But
8338 @c perhaps that is confusing...
8340 @cindex Read-only repository mode
8342 Turns on read-only repository mode. This allows one to check out from a
8343 read-only repository, such as within an anoncvs server, or from a @sc{cd-rom}
8346 Same effect as if the @code{CVSREADONLYFS} environment
8347 variable is set. Using @samp{-R} can also considerably
8348 speed up checkouts over NFS.
8350 @cindex Read-only mode
8352 Do not change any files. Attempt to execute the
8353 @samp{cvs_command}, but only to issue reports; do not remove,
8354 update, or merge any existing files, or create any new files.
8356 Note that @sc{cvs} will not necessarily produce exactly
8357 the same output as without @samp{-n}. In some cases
8358 the output will be the same, but in other cases
8359 @sc{cvs} will skip some of the processing that would
8360 have been required to produce the exact same output.
8363 Cause the command to be really quiet; the command will only
8364 generate output for serious problems.
8367 Cause the command to be somewhat quiet; informational messages,
8368 such as reports of recursion through subdirectories, are
8371 @cindex Read-only files, and -r
8373 Make new working files read-only. Same effect
8374 as if the @code{$CVSREAD} environment variable is set
8375 (@pxref{Environment variables}). The default is to
8376 make working files writable, unless watches are on
8379 @item -s @var{variable}=@var{value}
8380 Set a user variable (@pxref{Variables}).
8384 Trace program execution; display messages showing the steps of
8385 @sc{cvs} activity. Particularly useful with @samp{-n} to explore the
8386 potential impact of an unfamiliar command.
8390 Display version and copyright information for @sc{cvs}.
8392 @cindex CVSREAD, overriding
8393 @cindex Overriding CVSREAD
8395 Make new working files read-write. Overrides the
8396 setting of the @code{$CVSREAD} environment variable.
8397 Files are created read-write by default, unless @code{$CVSREAD} is
8398 set or @samp{-r} is given.
8399 @c Note that -w only overrides -r and CVSREAD; it has
8400 @c no effect on files which are readonly because of
8401 @c "cvs watch on". My guess is that is the way it
8402 @c should be (or should "cvs -w get" on a watched file
8403 @c be the same as a get and a cvs edit?), but I'm not
8404 @c completely sure whether to document it this way.
8408 Encrypt all communication between the client and the
8409 server. Only has an effect on the @sc{cvs} client. As
8410 of this writing, this is only implemented when using a
8411 GSSAPI connection (@pxref{GSSAPI authenticated}) or a
8412 Kerberos connection (@pxref{Kerberos authenticated}).
8413 Enabling encryption implies that message traffic is
8414 also authenticated. Encryption support is not
8415 available by default; it must be enabled using a
8416 special configure option, @file{--enable-encryption},
8417 when you build @sc{cvs}.
8419 @item -z @var{gzip-level}
8422 Set the compression level.
8423 Valid levels are 1 (high speed, low compression) to
8424 9 (low speed, high compression), or 0 to disable
8425 compression (the default).
8426 Only has an effect on the @sc{cvs} client.
8430 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
8431 @node Common options
8432 @appendixsec Common command options
8433 @cindex Common options
8434 @cindex Right-hand options
8436 This section describes the @samp{command_options} that
8437 are available across several @sc{cvs} commands. These
8438 options are always given to the right of
8439 @samp{cvs_command}. Not all
8440 commands support all of these options; each option is
8441 only supported for commands where it makes sense.
8442 However, when a command has one of these options you
8443 can almost always count on the same behavior of the
8444 option as in other commands. (Other command options,
8445 which are listed with the individual commands, may have
8446 different behavior from one @sc{cvs} command to the other).
8448 @strong{Note: the @samp{history} command is an exception; it supports
8449 many options that conflict even with these standard options.}
8454 @cindex Specifying dates
8455 @item -D @var{date_spec}
8456 Use the most recent revision no later than @var{date_spec}.
8457 @var{date_spec} is a single argument, a date description
8458 specifying a date in the past.
8460 The specification is @dfn{sticky} when you use it to make a
8461 private copy of a source file; that is, when you get a working
8462 file using @samp{-D}, @sc{cvs} records the date you specified, so that
8463 further updates in the same directory will use the same date
8464 (for more information on sticky tags/dates, @pxref{Sticky tags}).
8466 @samp{-D} is available with the @code{annotate}, @code{checkout},
8467 @code{diff}, @code{export}, @code{history}, @code{ls},
8468 @code{rdiff}, @code{rls}, @code{rtag}, @code{tag}, and @code{update} commands.
8469 (The @code{history} command uses this option in a
8470 slightly different way; @pxref{history options}).
8472 For a complete description of the date formats accepted by @sc{cvs},
8473 @ref{Date input formats}.
8474 @c What other formats should we accept? I don't want
8475 @c to start accepting a whole mess of non-standard
8476 @c new formats (there are a lot which are in wide use in
8477 @c one context or another), but practicality does
8478 @c dictate some level of flexibility.
8479 @c * POSIX.2 (e.g. touch, ls output, date) and other
8480 @c POSIX and/or de facto unix standards (e.g. at). The
8481 @c practice here is too inconsistent to be of any use.
8482 @c * VMS dates. This is not a formal standard, but
8483 @c there is a published specification (see SYS$ASCTIM
8484 @c and SYS$BINTIM in the _VMS System Services Reference
8485 @c Manual_), it is implemented consistently in VMS
8486 @c utilities, and VMS users will expect CVS running on
8487 @c VMS to support this format (and if we're going to do
8488 @c that, better to make CVS support it on all
8489 @c platforms. Maybe).
8491 @c One more note: In output, CVS should consistently
8492 @c use one date format, and that format should be one that
8493 @c it accepts in input as well. The former isn't
8494 @c really true (see survey below), and I'm not
8495 @c sure that either of those formats is accepted in
8499 @c current 1996/01/02 13:45:31
8500 @c Internet 02 Jan 1996 13:45:31 UT
8501 @c ISO 1996-01-02 13:45:31
8503 @c current 02-Jan-96
8504 @c Internet-like 02 Jan 96
8507 @c current Tue Jun 11 02:54:53 1996
8508 @c Internet [Tue,] 11 Jun 1996 02:54:53
8509 @c ISO 1996-06-11 02:54:53
8510 @c note: date possibly should be omitted entirely for
8513 @c current Tue Jun 11 02:54:53 1996 GMT
8515 @c current 06/11 02:54 +0000
8517 @c There is a good chance the proper solution has to
8518 @c involve at least some level of letting the user
8519 @c decide which format (with the default being the
8520 @c formats CVS has always used; changing these might be
8521 @c _very_ disruptive since scripts may very well be
8524 @c Another random bit of prior art concerning dates is
8525 @c the strptime function which takes templates such as
8526 @c "%m/%d/%y", and apparent a variant of getdate()
8527 @c which also honors them. See
8528 @c X/Open CAE Specification, System Interfaces and
8529 @c Headers Issue 4, Version 2 (September 1994), in the
8530 @c entry for getdate() on page 231
8532 Remember to quote the argument to the @samp{-D}
8533 flag so that your shell doesn't interpret spaces as
8534 argument separators. A command using the @samp{-D}
8535 flag can look like this:
8538 $ cvs diff -D "1 hour ago" cvs.texinfo
8541 @cindex Forcing a tag match
8543 When you specify a particular date or tag to @sc{cvs} commands, they
8544 normally ignore files that do not contain the tag (or did not
8545 exist prior to the date) that you specified. Use the @samp{-f} option
8546 if you want files retrieved even when there is no match for the
8547 tag or date. (The most recent revision of the file
8550 Note that even with @samp{-f}, a tag that you specify
8551 must exist (that is, in some file, not necessary in
8552 every file). This is so that @sc{cvs} will continue to
8553 give an error if you mistype a tag name.
8556 @samp{-f} is available with these commands:
8557 @code{annotate}, @code{checkout}, @code{export},
8558 @code{rdiff}, @code{rtag}, and @code{update}.
8560 @strong{WARNING: The @code{commit} and @code{remove}
8561 commands also have a
8562 @samp{-f} option, but it has a different behavior for
8563 those commands. See @ref{commit options}, and
8564 @ref{Removing files}.}
8566 @item -k @var{kflag}
8567 Override the default processing of RCS keywords other than
8568 @samp{-kb}. @xref{Keyword substitution}, for the meaning of
8569 @var{kflag}. Used with the @code{checkout} and @code{update}
8570 commands, your @var{kflag} specification is
8571 @dfn{sticky}; that is, when you use this option
8572 with a @code{checkout} or @code{update} command,
8573 @sc{cvs} associates your selected @var{kflag} with any files
8574 it operates on, and continues to use that @var{kflag} with future
8575 commands on the same files until you specify otherwise.
8577 The @samp{-k} option is available with the @code{add},
8578 @code{checkout}, @code{diff}, @code{export}, @code{import} and
8579 @code{update} commands.
8581 @strong{WARNING: Prior to CVS version 1.12.2, the @samp{-k} flag
8582 overrode the @samp{-kb} indication for a binary file. This could
8583 sometimes corrupt binary files. @xref{Merging and keywords}, for
8587 Local; run only in current working directory, rather than
8588 recursing through subdirectories.
8590 Available with the following commands: @code{annotate}, @code{checkout},
8591 @code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export},
8592 @code{log}, @code{rdiff}, @code{remove}, @code{rtag},
8593 @code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch},
8594 and @code{watchers}.
8596 @cindex Editor, avoiding invocation of
8597 @cindex Avoiding editor invocation
8598 @item -m @var{message}
8599 Use @var{message} as log information, instead of
8602 Available with the following commands: @code{add},
8603 @code{commit} and @code{import}.
8606 Do not run any tag program. (A program can be
8607 specified to run in the modules
8608 database (@pxref{modules}); this option bypasses it).
8610 @strong{Note: this is not the same as the @samp{cvs -n}
8611 program option, which you can specify to the left of a cvs command!}
8613 Available with the @code{checkout}, @code{commit}, @code{export},
8614 and @code{rtag} commands.
8617 Prune empty directories. See @ref{Removing directories}.
8620 Pipe the files retrieved from the repository to standard output,
8621 rather than writing them in the current directory. Available
8622 with the @code{checkout} and @code{update} commands.
8625 Process directories recursively. This is the default for all @sc{cvs}
8626 commands, with the exception of @code{ls} & @code{rls}.
8628 Available with the following commands: @code{annotate}, @code{checkout},
8629 @code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export},
8630 @code{ls}, @code{rdiff}, @code{remove}, @code{rls}, @code{rtag},
8631 @code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch},
8632 and @code{watchers}.
8635 @cindex HEAD, special tag
8636 @cindex BASE, special tag
8637 Use the revision specified by the @var{tag} argument instead of the
8638 default @dfn{head} revision. As well as arbitrary tags defined
8639 with the @code{tag} or @code{rtag} command, two special tags are
8640 always available: @samp{HEAD} refers to the most recent version
8641 available in the repository, and @samp{BASE} refers to the
8642 revision you last checked out into the current working directory.
8644 @c FIXME: What does HEAD really mean? I believe that
8645 @c the current answer is the head of the default branch
8646 @c for all cvs commands except diff. For diff, it
8647 @c seems to be (a) the head of the trunk (or the default
8648 @c branch?) if there is no sticky tag, (b) the head of the
8649 @c branch for the sticky tag, if there is a sticky tag.
8650 @c (b) is ugly as it differs
8651 @c from what HEAD means for other commands, but people
8652 @c and/or scripts are quite possibly used to it.
8653 @c See "head" tests in sanity.sh.
8654 @c Probably the best fix is to introduce two new
8655 @c special tags, ".thead" for the head of the trunk,
8656 @c and ".bhead" for the head of the current branch.
8657 @c Then deprecate HEAD. This has the advantage of
8658 @c not surprising people with a change to HEAD, and a
8659 @c side benefit of also phasing out the poorly-named
8660 @c HEAD (see discussion of reserved tag names in node
8661 @c "Tags"). Of course, .thead and .bhead should be
8662 @c carefully implemented (with the implementation the
8663 @c same for "diff" as for everyone else), test cases
8664 @c written (similar to the ones in "head"), new tests
8665 @c cases written for things like default branches, &c.
8667 The tag specification is sticky when you use this
8669 with @code{checkout} or @code{update} to make your own
8670 copy of a file: @sc{cvs} remembers the tag and continues to use it on
8671 future update commands, until you specify otherwise (for more information
8672 on sticky tags/dates, @pxref{Sticky tags}).
8674 The tag can be either a symbolic or numeric tag, as
8675 described in @ref{Tags}, or the name of a branch, as
8676 described in @ref{Branching and merging}.
8678 Specifying the @samp{-q} global option along with the
8679 @samp{-r} command option is often useful, to suppress
8680 the warning messages when the @sc{rcs} file
8681 does not contain the specified tag.
8683 @strong{Note: this is not the same as the overall @samp{cvs -r} option,
8684 which you can specify to the left of a @sc{cvs} command!}
8686 @samp{-r} is available with the @code{annotate}, @code{checkout},
8687 @code{commit}, @code{diff}, @code{history}, @code{export}, @code{rdiff},
8688 @code{rtag}, and @code{update} commands.
8691 Specify file names that should be filtered. You can
8692 use this option repeatedly. The spec can be a file
8693 name pattern of the same type that you can specify in
8694 the @file{.cvswrappers} file.
8695 Available with the following commands: @code{import},
8700 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
8701 @include getdate-cvs.texi
8703 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
8705 @appendixsec admin---Administration
8706 @cindex Admin (subcommand)
8710 Requires: repository, working directory.
8712 Changes: repository.
8717 This is the @sc{cvs} interface to assorted
8718 administrative facilities. Some of them have
8719 questionable usefulness for @sc{cvs} but exist for
8720 historical purposes. Some of the questionable options
8721 are likely to disappear in the future. This command
8722 @emph{does} work recursively, so extreme care should be
8726 @cindex UserAdminOptions, in CVSROOT/config
8727 On unix, if there is a group named @code{cvsadmin},
8728 only members of that group can run @code{cvs admin}
8729 commands, except for those specified using the
8730 @code{UserAdminOptions} configuration option in the
8731 @file{CVSROOT/config} file. Options specified using
8732 @code{UserAdminOptions} can be run by any user. See
8733 @ref{config} for more on @code{UserAdminOptions}.
8735 The @code{cvsadmin} group should exist on the server,
8736 or any system running the non-client/server @sc{cvs}.
8737 To disallow @code{cvs admin} for all users, create a
8738 group with no users in it. On NT, the @code{cvsadmin}
8739 feature does not exist and all users
8740 can run @code{cvs admin}.
8743 * admin options:: admin options
8746 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8748 @appendixsubsec admin options
8750 Some of these options have questionable usefulness for
8751 @sc{cvs} but exist for historical purposes. Some even
8752 make it impossible to use @sc{cvs} until you undo the
8756 @item -A@var{oldfile}
8757 Might not work together with @sc{cvs}. Append the
8758 access list of @var{oldfile} to the access list of the
8761 @item -a@var{logins}
8762 Might not work together with @sc{cvs}. Append the
8763 login names appearing in the comma-separated list
8764 @var{logins} to the access list of the @sc{rcs} file.
8767 Set the default branch to @var{rev}. In @sc{cvs}, you
8768 normally do not manipulate default branches; sticky
8769 tags (@pxref{Sticky tags}) are a better way to decide
8770 which branch you want to work on. There is one reason
8771 to run @code{cvs admin -b}: to revert to the vendor's
8772 version when using vendor branches (@pxref{Reverting
8774 There can be no space between @samp{-b} and its argument.
8775 @c Hmm, we don't document the usage where rev is
8776 @c omitted. Maybe that usage can/should be deprecated
8777 @c (and replaced with -bHEAD or something?) (so we can toss
8778 @c the optional argument). Note that -bHEAD does not
8779 @c work, as of 17 Sep 1997, but probably will once "cvs
8780 @c admin" is internal to CVS.
8782 @cindex Comment leader
8783 @item -c@var{string}
8784 Sets the comment leader to @var{string}. The comment
8785 leader is not used by current versions of @sc{cvs} or
8786 @sc{rcs} 5.7. Therefore, you can almost surely not
8787 worry about it. @xref{Keyword substitution}.
8789 @item -e[@var{logins}]
8790 Might not work together with @sc{cvs}. Erase the login
8791 names appearing in the comma-separated list
8792 @var{logins} from the access list of the RCS file. If
8793 @var{logins} is omitted, erase the entire access list.
8794 There can be no space between @samp{-e} and its argument.
8797 Run interactively, even if the standard input is not a
8798 terminal. This option does not work with the
8799 client/server @sc{cvs} and is likely to disappear in
8800 a future release of @sc{cvs}.
8803 Useless with @sc{cvs}. This creates and initializes a
8804 new @sc{rcs} file, without depositing a revision. With
8805 @sc{cvs}, add files with the @code{cvs add} command
8806 (@pxref{Adding files}).
8809 Set the default keyword
8810 substitution to @var{subst}. @xref{Keyword
8811 substitution}. Giving an explicit @samp{-k} option to
8812 @code{cvs update}, @code{cvs export}, or @code{cvs
8813 checkout} overrides this default.
8816 Lock the revision with number @var{rev}. If a branch
8817 is given, lock the latest revision on that branch. If
8818 @var{rev} is omitted, lock the latest revision on the
8819 default branch. There can be no space between
8820 @samp{-l} and its argument.
8822 This can be used in conjunction with the
8823 @file{rcslock.pl} script in the @file{contrib}
8824 directory of the @sc{cvs} source distribution to
8825 provide reserved checkouts (where only one user can be
8826 editing a given file at a time). See the comments in
8827 that file for details (and see the @file{README} file
8828 in that directory for disclaimers about the unsupported
8829 nature of contrib). According to comments in that
8830 file, locking must set to strict (which is the default).
8833 Set locking to strict. Strict locking means that the
8834 owner of an RCS file is not exempt from locking for
8835 checkin. For use with @sc{cvs}, strict locking must be
8836 set; see the discussion under the @samp{-l} option above.
8838 @cindex Changing a log message
8839 @cindex Replacing a log message
8840 @cindex Correcting a log message
8841 @cindex Fixing a log message
8842 @cindex Log message, correcting
8843 @item -m@var{rev}:@var{msg}
8844 Replace the log message of revision @var{rev} with
8847 @c The rcs -M option, to suppress sending mail, has never been
8848 @c documented as a cvs admin option.
8850 @item -N@var{name}[:[@var{rev}]]
8851 Act like @samp{-n}, except override any previous
8852 assignment of @var{name}. For use with magic branches,
8853 see @ref{Magic branch numbers}.
8855 @item -n@var{name}[:[@var{rev}]]
8856 Associate the symbolic name @var{name} with the branch
8857 or revision @var{rev}. It is normally better to use
8858 @samp{cvs tag} or @samp{cvs rtag} instead. Delete the
8859 symbolic name if both @samp{:} and @var{rev} are
8860 omitted; otherwise, print an error message if
8861 @var{name} is already associated with another number.
8862 If @var{rev} is symbolic, it is expanded before
8863 association. A @var{rev} consisting of a branch number
8864 followed by a @samp{.} stands for the current latest
8865 revision in the branch. A @samp{:} with an empty
8866 @var{rev} stands for the current latest revision on the
8867 default branch, normally the trunk. For example,
8868 @samp{cvs admin -n@var{name}:} associates @var{name} with the
8869 current latest revision of all the RCS files;
8870 this contrasts with @samp{cvs admin -n@var{name}:$} which
8871 associates @var{name} with the revision numbers
8872 extracted from keyword strings in the corresponding
8875 @cindex Deleting revisions
8876 @cindex Outdating revisions
8877 @cindex Saving space
8879 Deletes (@dfn{outdates}) the revisions given by
8882 Note that this command can be quite dangerous unless
8883 you know @emph{exactly} what you are doing (for example
8884 see the warnings below about how the
8885 @var{rev1}:@var{rev2} syntax is confusing).
8887 If you are short on disc this option might help you.
8888 But think twice before using it---there is no way short
8889 of restoring the latest backup to undo this command!
8890 If you delete different revisions than you planned,
8891 either due to carelessness or (heaven forbid) a @sc{cvs}
8892 bug, there is no opportunity to correct the error
8893 before the revisions are deleted. It probably would be
8894 a good idea to experiment on a copy of the repository
8897 Specify @var{range} in one of the following ways:
8900 @item @var{rev1}::@var{rev2}
8901 Collapse all revisions between rev1 and rev2, so that
8902 @sc{cvs} only stores the differences associated with going
8903 from rev1 to rev2, not intermediate steps. For
8904 example, after @samp{-o 1.3::1.5} one can retrieve
8905 revision 1.3, revision 1.5, or the differences to get
8906 from 1.3 to 1.5, but not the revision 1.4, or the
8907 differences between 1.3 and 1.4. Other examples:
8908 @samp{-o 1.3::1.4} and @samp{-o 1.3::1.3} have no
8909 effect, because there are no intermediate revisions to
8913 Collapse revisions between the beginning of the branch
8914 containing @var{rev} and @var{rev} itself. The
8915 branchpoint and @var{rev} are left intact. For
8916 example, @samp{-o ::1.3.2.6} deletes revision 1.3.2.1,
8917 revision 1.3.2.5, and everything in between, but leaves
8918 1.3 and 1.3.2.6 intact.
8921 Collapse revisions between @var{rev} and the end of the
8922 branch containing @var{rev}. Revision @var{rev} is
8923 left intact but the head revision is deleted.
8926 Delete the revision @var{rev}. For example, @samp{-o
8927 1.3} is equivalent to @samp{-o 1.2::1.4}.
8929 @item @var{rev1}:@var{rev2}
8930 Delete the revisions from @var{rev1} to @var{rev2},
8931 inclusive, on the same branch. One will not be able to
8932 retrieve @var{rev1} or @var{rev2} or any of the
8933 revisions in between. For example, the command
8934 @samp{cvs admin -oR_1_01:R_1_02 .} is rarely useful.
8935 It means to delete revisions up to, and including, the
8936 tag R_1_02. But beware! If there are files that have not
8937 changed between R_1_02 and R_1_03 the file will have
8938 @emph{the same} numerical revision number assigned to
8939 the tags R_1_02 and R_1_03. So not only will it be
8940 impossible to retrieve R_1_02; R_1_03 will also have to
8941 be restored from the tapes! In most cases you want to
8942 specify @var{rev1}::@var{rev2} instead.
8945 Delete revisions from the beginning of the
8946 branch containing @var{rev} up to and including
8950 Delete revisions from revision @var{rev}, including
8951 @var{rev} itself, to the end of the branch containing
8955 None of the revisions to be deleted may have
8958 If any of the revisions to be deleted have symbolic
8959 names, and one specifies one of the @samp{::} syntaxes,
8960 then @sc{cvs} will give an error and not delete any
8961 revisions. If you really want to delete both the
8962 symbolic names and the revisions, first delete the
8963 symbolic names with @code{cvs tag -d}, then run
8964 @code{cvs admin -o}. If one specifies the
8965 non-@samp{::} syntaxes, then @sc{cvs} will delete the
8966 revisions but leave the symbolic names pointing to
8967 nonexistent revisions. This behavior is preserved for
8968 compatibility with previous versions of @sc{cvs}, but
8969 because it isn't very useful, in the future it may
8970 change to be like the @samp{::} case.
8972 Due to the way @sc{cvs} handles branches @var{rev}
8973 cannot be specified symbolically if it is a branch.
8974 @xref{Magic branch numbers}, for an explanation.
8975 @c FIXME: is this still true? I suspect not.
8977 Make sure that no-one has checked out a copy of the
8978 revision you outdate. Strange things will happen if he
8979 starts to edit it and tries to check it back in. For
8980 this reason, this option is not a good way to take back
8981 a bogus commit; commit a new revision undoing the bogus
8982 change instead (@pxref{Merging two revisions}).
8985 Run quietly; do not print diagnostics.
8987 @item -s@var{state}[:@var{rev}]
8988 Useful with @sc{cvs}. Set the state attribute of the
8989 revision @var{rev} to @var{state}. If @var{rev} is a
8990 branch number, assume the latest revision on that
8991 branch. If @var{rev} is omitted, assume the latest
8992 revision on the default branch. Any identifier is
8993 acceptable for @var{state}. A useful set of states is
8994 @samp{Exp} (for experimental), @samp{Stab} (for
8995 stable), and @samp{Rel} (for released). By default,
8996 the state of a new revision is set to @samp{Exp} when
8997 it is created. The state is visible in the output from
8998 @var{cvs log} (@pxref{log}), and in the
8999 @samp{$@splitrcskeyword{Log}$} and @samp{$@splitrcskeyword{State}$} keywords
9000 (@pxref{Keyword substitution}). Note that @sc{cvs}
9001 uses the @code{dead} state for its own purposes; to
9002 take a file to or from the @code{dead} state use
9003 commands like @code{cvs remove} and @code{cvs add}, not
9004 @code{cvs admin -s}.
9006 @item -t[@var{file}]
9007 Useful with @sc{cvs}. Write descriptive text from the
9008 contents of the named @var{file} into the RCS file,
9009 deleting the existing text. The @var{file} pathname
9010 may not begin with @samp{-}. The descriptive text can be seen in the
9011 output from @samp{cvs log} (@pxref{log}).
9012 There can be no space between @samp{-t} and its argument.
9014 If @var{file} is omitted,
9015 obtain the text from standard input, terminated by
9016 end-of-file or by a line containing @samp{.} by itself.
9017 Prompt for the text if interaction is possible; see
9020 @item -t-@var{string}
9021 Similar to @samp{-t@var{file}}. Write descriptive text
9022 from the @var{string} into the @sc{rcs} file, deleting
9024 There can be no space between @samp{-t} and its argument.
9026 @c The rcs -T option, do not update last-mod time for
9027 @c minor changes, has never been documented as a
9028 @c cvs admin option.
9031 Set locking to non-strict. Non-strict locking means
9032 that the owner of a file need not lock a revision for
9033 checkin. For use with @sc{cvs}, strict locking must be
9034 set; see the discussion under the @samp{-l} option
9038 See the option @samp{-l} above, for a discussion of
9039 using this option with @sc{cvs}. Unlock the revision
9040 with number @var{rev}. If a branch is given, unlock
9041 the latest revision on that branch. If @var{rev} is
9042 omitted, remove the latest lock held by the caller.
9043 Normally, only the locker of a revision may unlock it;
9044 somebody else unlocking a revision breaks the lock.
9045 This causes the original locker to be sent a @code{commit}
9046 notification (@pxref{Getting Notified}).
9047 There can be no space between @samp{-u} and its argument.
9050 In previous versions of @sc{cvs}, this option meant to
9051 write an @sc{rcs} file which would be acceptable to
9052 @sc{rcs} version @var{n}, but it is now obsolete and
9053 specifying it will produce an error.
9054 @c Note that -V without an argument has never been
9055 @c documented as a cvs admin option.
9057 @item -x@var{suffixes}
9058 In previous versions of @sc{cvs}, this was documented
9059 as a way of specifying the names of the @sc{rcs}
9060 files. However, @sc{cvs} has always required that the
9061 @sc{rcs} files used by @sc{cvs} end in @samp{,v}, so
9062 this option has never done anything useful.
9064 @c The rcs -z option, to specify the timezone, has
9065 @c never been documented as a cvs admin option.
9068 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
9070 @appendixsec annotate---What revision modified each line of a file?
9071 @cindex annotate (subcommand)
9075 Synopsis: annotate [options] files@dots{}
9077 Requires: repository.
9082 For each file in @var{files}, print the head revision
9083 of the trunk, together with information on the last
9084 modification for each line.
9087 * annotate options:: annotate options
9088 * annotate example:: annotate example
9091 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9092 @node annotate options
9093 @appendixsubsec annotate options
9095 These standard options are supported by @code{annotate}
9096 (@pxref{Common options}, for a complete description of
9101 Local directory only, no recursion.
9104 Process directories recursively.
9107 Use head revision if tag/date not found.
9110 Annotate binary files.
9112 @item -r @var{revision}
9113 Annotate file as of specified revision/tag.
9116 Annotate file as of specified date.
9119 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9120 @node annotate example
9121 @appendixsubsec annotate example
9126 $ cvs annotate ssfile
9127 Annotations for ssfile
9129 1.1 (mary 27-Mar-96): ssfile line 1
9130 1.2 (joe 28-Mar-96): ssfile line 2
9133 The file @file{ssfile} currently contains two lines.
9134 The @code{ssfile line 1} line was checked in by
9135 @code{mary} on March 27. Then, on March 28, @code{joe}
9136 added a line @code{ssfile line 2}, without modifying
9137 the @code{ssfile line 1} line. This report doesn't
9138 tell you anything about lines which have been deleted
9139 or replaced; you need to use @code{cvs diff} for that
9142 The options to @code{cvs annotate} are listed in
9143 @ref{Invoking CVS}, and can be used to select the files
9144 and revisions to annotate. The options are described
9145 in more detail there and in @ref{Common options}.
9147 @c FIXME: maybe an example using the options? Just
9148 @c what it means to select a revision might be worth a
9149 @c few words of explanation ("you want to see who
9150 @c changed this line *before* 1.4"...).
9152 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
9154 @appendixsec checkout---Check out sources for editing
9155 @cindex checkout (subcommand)
9156 @cindex co (subcommand)
9160 Synopsis: checkout [options] modules@dots{}
9162 Requires: repository.
9164 Changes: working directory.
9169 Create or update a working directory containing copies of the
9170 source files specified by @var{modules}. You must execute
9171 @code{checkout} before using most of the other @sc{cvs}
9172 commands, since most of them operate on your working
9175 The @var{modules} are either
9176 symbolic names for some
9177 collection of source directories and files, or paths to
9178 directories or files in the repository. The symbolic
9179 names are defined in the @samp{modules} file.
9181 @c Needs an example, particularly of the non-"modules"
9182 @c case but probably of both.
9184 @c FIXME: this seems like a very odd place to introduce
9185 @c people to how CVS works. The bit about unreserved
9186 @c checkouts is also misleading as it depends on how
9187 @c things are set up.
9188 Depending on the modules you specify, @code{checkout} may
9189 recursively create directories and populate them with
9190 the appropriate source files. You can then edit these
9191 source files at any time (regardless of whether other
9192 software developers are editing their own copies of the
9193 sources); update them to include new changes applied by
9194 others to the source repository; or commit your work as
9195 a permanent change to the source repository.
9197 Note that @code{checkout} is used to create
9198 directories. The top-level directory created is always
9199 added to the directory where @code{checkout} is
9200 invoked, and usually has the same name as the specified
9201 module. In the case of a module alias, the created
9202 sub-directory may have a different name, but you can be
9203 sure that it will be a sub-directory, and that
9204 @code{checkout} will show the relative path leading to
9205 each file as it is extracted into your private work
9206 area (unless you specify the @samp{-Q} global option).
9208 The files created by @code{checkout} are created
9209 read-write, unless the @samp{-r} option to @sc{cvs}
9210 (@pxref{Global options}) is specified, the
9211 @code{CVSREAD} environment variable is specified
9212 (@pxref{Environment variables}), or a watch is in
9213 effect for that file (@pxref{Watches}).
9215 Note that running @code{checkout} on a directory that was already
9216 built by a prior @code{checkout} is also permitted.
9217 This is similar to specifying the @samp{-d} option
9218 to the @code{update} command in the sense that new
9219 directories that have been created in the repository
9220 will appear in your work area.
9221 However, @code{checkout} takes a module name whereas
9222 @code{update} takes a directory name. Also
9223 to use @code{checkout} this way it must be run from the
9224 top level directory (where you originally ran
9225 @code{checkout} from), so before you run
9226 @code{checkout} to update an existing directory, don't
9227 forget to change your directory to the top level
9230 For the output produced by the @code{checkout} command
9231 see @ref{update output}.
9234 * checkout options:: checkout options
9235 * checkout examples:: checkout examples
9238 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9239 @node checkout options
9240 @appendixsubsec checkout options
9242 These standard options are supported by @code{checkout}
9243 (@pxref{Common options}, for a complete description of
9248 Use the most recent revision no later than @var{date}.
9249 This option is sticky, and implies @samp{-P}. See
9250 @ref{Sticky tags}, for more information on sticky tags/dates.
9253 Only useful with the @samp{-D @var{date}} or @samp{-r
9254 @var{tag}} flags. If no matching revision is found,
9255 retrieve the most recent revision (instead of ignoring
9258 @item -k @var{kflag}
9259 Process keywords according to @var{kflag}. See
9260 @ref{Keyword substitution}.
9261 This option is sticky; future updates of
9262 this file in this working directory will use the same
9263 @var{kflag}. The @code{status} command can be viewed
9264 to see the sticky options. See @ref{Invoking CVS}, for
9265 more information on the @code{status} command.
9268 Local; run only in current working directory.
9271 Do not run any checkout program (as specified
9272 with the @samp{-o} option in the modules file;
9276 Prune empty directories. See @ref{Moving directories}.
9279 Pipe files to the standard output.
9282 Checkout directories recursively. This option is on by default.
9285 Use revision @var{tag}. This option is sticky, and implies @samp{-P}.
9286 See @ref{Sticky tags}, for more information on sticky tags/dates.
9289 In addition to those, you can use these special command
9290 options with @code{checkout}:
9294 Reset any sticky tags, dates, or @samp{-k} options.
9295 See @ref{Sticky tags}, for more information on sticky tags/dates.
9298 Copy the module file, sorted, to the standard output,
9299 instead of creating or modifying any files or
9300 directories in your working directory.
9303 Create a directory called @var{dir} for the working
9304 files, instead of using the module name. In general,
9305 using this flag is equivalent to using @samp{mkdir
9306 @var{dir}; cd @var{dir}} followed by the checkout
9307 command without the @samp{-d} flag.
9309 There is an important exception, however. It is very
9310 convenient when checking out a single item to have the
9311 output appear in a directory that doesn't contain empty
9312 intermediate directories. In this case @emph{only},
9313 @sc{cvs} tries to ``shorten'' pathnames to avoid those empty
9316 For example, given a module @samp{foo} that contains
9317 the file @samp{bar.c}, the command @samp{cvs co -d dir
9318 foo} will create directory @samp{dir} and place
9319 @samp{bar.c} inside. Similarly, given a module
9320 @samp{bar} which has subdirectory @samp{baz} wherein
9321 there is a file @samp{quux.c}, the command @samp{cvs co
9322 -d dir bar/baz} will create directory @samp{dir} and
9323 place @samp{quux.c} inside.
9325 Using the @samp{-N} flag will defeat this behavior.
9326 Given the same module definitions above, @samp{cvs co
9327 -N -d dir foo} will create directories @samp{dir/foo}
9328 and place @samp{bar.c} inside, while @samp{cvs co -N -d
9329 dir bar/baz} will create directories @samp{dir/bar/baz}
9330 and place @samp{quux.c} inside.
9333 With two @samp{-j} options, merge changes from the
9334 revision specified with the first @samp{-j} option to
9335 the revision specified with the second @samp{j} option,
9336 into the working directory.
9338 With one @samp{-j} option, merge changes from the
9339 ancestor revision to the revision specified with the
9340 @samp{-j} option, into the working directory. The
9341 ancestor revision is the common ancestor of the
9342 revision which the working directory is based on, and
9343 the revision specified in the @samp{-j} option.
9345 In addition, each -j option can contain an optional
9346 date specification which, when used with branches, can
9347 limit the chosen revision to one within a specific
9348 date. An optional date is specified by adding a colon
9350 @samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}.
9352 @xref{Branching and merging}.
9355 Only useful together with @samp{-d @var{dir}}. With
9356 this option, @sc{cvs} will not ``shorten'' module paths
9357 in your working directory when you check out a single
9358 module. See the @samp{-d} flag for examples and a
9362 Like @samp{-c}, but include the status of all modules,
9363 and sort it by the status string. @xref{modules}, for
9364 info about the @samp{-s} option that is used inside the
9365 modules file to set the module status.
9368 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9369 @node checkout examples
9370 @appendixsubsec checkout examples
9372 Get a copy of the module @samp{tc}:
9378 Get a copy of the module @samp{tc} as it looked one day
9382 $ cvs checkout -D yesterday tc
9385 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
9387 @appendixsec commit---Check files into the repository
9388 @cindex commit (subcommand)
9392 Synopsis: commit [-lnRf] [-m 'log_message' |
9393 -F file] [-r revision] [files@dots{}]
9395 Requires: working directory, repository.
9397 Changes: repository.
9402 Use @code{commit} when you want to incorporate changes
9403 from your working source files into the source
9406 If you don't specify particular files to commit, all of
9407 the files in your working current directory are
9408 examined. @code{commit} is careful to change in the
9409 repository only those files that you have really
9410 changed. By default (or if you explicitly specify the
9411 @samp{-R} option), files in subdirectories are also
9412 examined and committed if they have changed; you can
9413 use the @samp{-l} option to limit @code{commit} to the
9414 current directory only.
9416 @code{commit} verifies that the selected files are up
9417 to date with the current revisions in the source
9418 repository; it will notify you, and exit without
9419 committing, if any of the specified files must be made
9420 current first with @code{update} (@pxref{update}).
9421 @code{commit} does not call the @code{update} command
9422 for you, but rather leaves that for you to do when the
9425 When all is well, an editor is invoked to allow you to
9426 enter a log message that will be written to one or more
9427 logging programs (@pxref{modules}, and @pxref{loginfo})
9428 and placed in the @sc{rcs} file inside the
9429 repository. This log message can be retrieved with the
9430 @code{log} command; see @ref{log}. You can specify the
9431 log message on the command line with the @samp{-m
9432 @var{message}} option, and thus avoid the editor invocation,
9433 or use the @samp{-F @var{file}} option to specify
9434 that the argument file contains the log message.
9437 * commit options:: commit options
9438 * commit examples:: commit examples
9441 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9442 @node commit options
9443 @appendixsubsec commit options
9445 These standard options are supported by @code{commit}
9446 (@pxref{Common options}, for a complete description of
9451 Local; run only in current working directory.
9454 Commit directories recursively. This is on by default.
9456 @item -r @var{revision}
9457 Commit to @var{revision}. @var{revision} must be
9458 either a branch, or a revision on the main trunk that
9459 is higher than any existing revision number
9460 (@pxref{Assigning revisions}). You
9461 cannot commit to a specific revision on a branch.
9462 @c FIXME: Need xref for branch case.
9465 @code{commit} also supports these options:
9469 Refuse to commit files unless the user has registered a valid edit on the
9470 file via @code{cvs edit}. This is most useful when @samp{commit -c}
9471 and @samp{edit -c} have been placed in all @file{.cvsrc} files.
9472 A commit can be forced anyways by either regestering an edit retroactively
9473 via @code{cvs edit} (no changes to the file will be lost) or using the
9474 @code{-f} option to commit. Support for @code{commit -c} requires both
9475 client and a server versions 1.12.10 or greater.
9478 Read the log message from @var{file}, instead
9479 of invoking an editor.
9482 Note that this is not the standard behavior of
9483 the @samp{-f} option as defined in @ref{Common options}.
9485 Force @sc{cvs} to commit a new revision even if you haven't
9486 made any changes to the file. As of @sc{cvs} version 1.12.10,
9487 it also causes the @code{-c} option to be ignored. If the current revision
9488 of @var{file} is 1.7, then the following two commands
9492 $ cvs commit -f @var{file}
9493 $ cvs commit -r 1.8 @var{file}
9496 @c This is odd, but it's how CVS has worked for some
9498 The @samp{-f} option disables recursion (i.e., it
9499 implies @samp{-l}). To force @sc{cvs} to commit a new
9500 revision for all files in all subdirectories, you must
9503 @item -m @var{message}
9504 Use @var{message} as the log message, instead of
9509 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9510 @node commit examples
9511 @appendixsubsec commit examples
9513 @c FIXME: this material wants to be somewhere
9514 @c in "Branching and merging".
9516 @appendixsubsubsec Committing to a branch
9518 You can commit to a branch revision (one that has an
9519 even number of dots) with the @samp{-r} option. To
9520 create a branch revision, use the @samp{-b} option
9521 of the @code{rtag} or @code{tag} commands
9522 (@pxref{Branching and merging}). Then, either @code{checkout} or
9523 @code{update} can be used to base your sources on the
9524 newly created branch. From that point on, all
9525 @code{commit} changes made within these working sources
9526 will be automatically added to a branch revision,
9527 thereby not disturbing main-line development in any
9528 way. For example, if you had to create a patch to the
9529 1.2 version of the product, even though the 2.0 version
9530 is already under development, you might do:
9533 $ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module
9534 $ cvs checkout -r FCS1_2_Patch product_module
9541 This works automatically since the @samp{-r} option is
9544 @appendixsubsubsec Creating the branch after editing
9546 Say you have been working on some extremely
9547 experimental software, based on whatever revision you
9548 happened to checkout last week. If others in your
9549 group would like to work on this software with you, but
9550 without disturbing main-line development, you could
9551 commit your change to a new branch. Others can then
9552 checkout your experimental stuff and utilize the full
9553 benefit of @sc{cvs} conflict resolution. The scenario might
9556 @c FIXME: Should we be recommending tagging the branchpoint?
9558 [[ hacked sources are present ]]
9560 $ cvs update -r EXPR1
9564 The @code{update} command will make the @samp{-r
9565 EXPR1} option sticky on all files. Note that your
9566 changes to the files will never be removed by the
9567 @code{update} command. The @code{commit} will
9568 automatically commit to the correct branch, because the
9569 @samp{-r} is sticky. You could also do like this:
9571 @c FIXME: Should we be recommending tagging the branchpoint?
9573 [[ hacked sources are present ]]
9575 $ cvs commit -r EXPR1
9579 but then, only those files that were changed by you
9580 will have the @samp{-r EXPR1} sticky flag. If you hack
9581 away, and commit without specifying the @samp{-r EXPR1}
9582 flag, some files may accidentally end up on the main
9585 To work with you on the experimental change, others
9589 $ cvs checkout -r EXPR1 whatever_module
9592 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
9594 @appendixsec diff---Show differences between revisions
9595 @cindex diff (subcommand)
9599 Synopsis: diff [-lR] [-k kflag] [format_options] [[-r rev1 | -D date1] [-r rev2 | -D date2]] [files@dots{}]
9601 Requires: working directory, repository.
9606 The @code{diff} command is used to compare different
9607 revisions of files. The default action is to compare
9608 your working files with the revisions they were based
9609 on, and report any differences that are found.
9611 If any file names are given, only those files are
9612 compared. If any directories are given, all files
9613 under them will be compared.
9615 The exit status for diff is different than for other
9616 @sc{cvs} commands; for details @ref{Exit status}.
9619 * diff options:: diff options
9620 * diff examples:: diff examples
9623 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9625 @appendixsubsec diff options
9627 These standard options are supported by @code{diff}
9628 (@pxref{Common options}, for a complete description of
9633 Use the most recent revision no later than @var{date}.
9634 See @samp{-r} for how this affects the comparison.
9636 @item -k @var{kflag}
9637 Process keywords according to @var{kflag}. See
9638 @ref{Keyword substitution}.
9641 Local; run only in current working directory.
9644 Examine directories recursively. This option is on by
9648 Compare with revision @var{tag}. Zero, one or two
9649 @samp{-r} options can be present. With no @samp{-r}
9650 option, the working file will be compared with the
9651 revision it was based on. With one @samp{-r}, that
9652 revision will be compared to your current working file.
9653 With two @samp{-r} options those two revisions will be
9654 compared (and your working file will not affect the
9655 outcome in any way).
9656 @c We should be a lot more explicit, with examples,
9657 @c about the difference between "cvs diff" and "cvs
9658 @c diff -r HEAD". This often confuses new users.
9660 One or both @samp{-r} options can be replaced by a
9661 @samp{-D @var{date}} option, described above.
9664 @c Conceptually, this is a disaster. There are 3
9665 @c zillion diff formats that we support via the diff
9666 @c library. It is not obvious to me that we should
9667 @c document them all. Maybe just the most common ones
9668 @c like -c and -u, and think about phasing out the
9670 @c FIXCVS: also should be a way to specify an external
9671 @c diff program (which can be different for different
9672 @c file types) and pass through
9673 @c arbitrary options, so that the user can do
9674 @c "--pass=-Z --pass=foo" or something even if CVS
9675 @c doesn't know about the "-Z foo" option to diff.
9676 @c This would fit nicely with deprecating/eliminating
9677 @c the obscure options of the diff library, because it
9678 @c would let people specify an external GNU diff if
9679 @c they are into that sort of thing.
9680 The following options specify the format of the
9681 output. They have the same meaning as in GNU diff.
9682 Most options have two equivalent names, one of which is a single letter
9683 preceded by @samp{-}, and the other of which is a long name preceded by
9688 Show @var{lines} (an integer) lines of context. This option does not
9689 specify an output format by itself; it has no effect unless it is
9690 combined with @samp{-c} or @samp{-u}. This option is obsolete. For proper
9691 operation, @code{patch} typically needs at least two lines of context.
9694 Treat all files as text and compare them line-by-line, even if they
9695 do not seem to be text.
9698 Ignore trailing white space and consider all other sequences of one or
9699 more white space characters to be equivalent.
9702 Ignore changes that just insert or delete blank lines.
9705 Read and write data in binary mode.
9708 Report only whether the files differ, not the details of the
9712 Use the context output format.
9714 @item -C @var{lines}
9715 @itemx --context@r{[}=@var{lines}@r{]}
9716 Use the context output format, showing @var{lines} (an integer) lines of
9717 context, or three if @var{lines} is not given.
9718 For proper operation, @code{patch} typically needs at least two lines of
9721 @item --changed-group-format=@var{format}
9722 Use @var{format} to output a line group containing differing lines from
9723 both files in if-then-else format. @xref{Line group formats}.
9726 Change the algorithm to perhaps find a smaller set of changes. This makes
9727 @code{diff} slower (sometimes much slower).
9731 Make output that is a valid @code{ed} script.
9734 Expand tabs to spaces in the output, to preserve the alignment of tabs
9738 Make output that looks vaguely like an @code{ed} script but has changes
9739 in the order they appear in the file.
9741 @item -F @var{regexp}
9742 In context and unified format, for each hunk of differences, show some
9743 of the last preceding line that matches @var{regexp}.
9746 Make output that looks vaguely like an @code{ed} script but has changes
9747 in the order they appear in the file.
9750 Use heuristics to speed handling of large files that have numerous
9751 scattered small changes.
9753 @item --horizon-lines=@var{lines}
9754 Do not discard the last @var{lines} lines of the common prefix
9755 and the first @var{lines} lines of the common suffix.
9758 Ignore changes in case; consider upper- and lower-case letters
9761 @item -I @var{regexp}
9762 Ignore changes that just insert or delete lines that match @var{regexp}.
9764 @item --ifdef=@var{name}
9765 Make merged if-then-else output using @var{name}.
9767 @item --ignore-all-space
9768 Ignore white space when comparing lines.
9770 @item --ignore-blank-lines
9771 Ignore changes that just insert or delete blank lines.
9774 Ignore changes in case; consider upper- and lower-case to be the same.
9776 @item --ignore-matching-lines=@var{regexp}
9777 Ignore changes that just insert or delete lines that match @var{regexp}.
9779 @item --ignore-space-change
9780 Ignore trailing white space and consider all other sequences of one or
9781 more white space characters to be equivalent.
9784 Output a tab rather than a space before the text of a line in normal or
9785 context format. This causes the alignment of tabs in the line to look
9788 @item -L @var{label}
9789 Use @var{label} instead of the file name in the context format
9790 and unified format headers.
9792 @item --label=@var{label}
9793 Use @var{label} instead of the file name in the context format
9794 and unified format headers.
9797 Print only the left column of two common lines in side by side format.
9799 @item --line-format=@var{format}
9800 Use @var{format} to output all input lines in if-then-else format.
9801 @xref{Line formats}.
9804 Change the algorithm to perhaps find a smaller set of changes. This
9805 makes @code{diff} slower (sometimes much slower).
9808 Output RCS-format diffs; like @samp{-f} except that each command
9809 specifies the number of lines affected.
9813 In directory comparison, if a file is found in only one directory,
9814 treat it as present but empty in the other directory.
9816 @item --new-group-format=@var{format}
9817 Use @var{format} to output a group of lines taken from just the second
9818 file in if-then-else format. @xref{Line group formats}.
9820 @item --new-line-format=@var{format}
9821 Use @var{format} to output a line taken from just the second file in
9822 if-then-else format. @xref{Line formats}.
9824 @item --old-group-format=@var{format}
9825 Use @var{format} to output a group of lines taken from just the first
9826 file in if-then-else format. @xref{Line group formats}.
9828 @item --old-line-format=@var{format}
9829 Use @var{format} to output a line taken from just the first file in
9830 if-then-else format. @xref{Line formats}.
9833 Show which C function each change is in.
9836 Output RCS-format diffs; like @samp{-f} except that each command
9837 specifies the number of lines affected.
9839 @item --report-identical-files
9841 Report when two files are the same.
9843 @item --show-c-function
9844 Show which C function each change is in.
9846 @item --show-function-line=@var{regexp}
9847 In context and unified format, for each hunk of differences, show some
9848 of the last preceding line that matches @var{regexp}.
9850 @item --side-by-side
9851 Use the side by side output format.
9853 @item --speed-large-files
9854 Use heuristics to speed handling of large files that have numerous
9855 scattered small changes.
9857 @item --suppress-common-lines
9858 Do not print common lines in side by side format.
9861 Expand tabs to spaces in the output, to preserve the alignment of tabs
9865 Output a tab rather than a space before the text of a line in normal or
9866 context format. This causes the alignment of tabs in the line to look
9870 Treat all files as text and compare them line-by-line, even if they
9871 do not appear to be text.
9874 Use the unified output format.
9876 @item --unchanged-group-format=@var{format}
9877 Use @var{format} to output a group of common lines taken from both files
9878 in if-then-else format. @xref{Line group formats}.
9880 @item --unchanged-line-format=@var{format}
9881 Use @var{format} to output a line common to both files in if-then-else
9882 format. @xref{Line formats}.
9884 @item -U @var{lines}
9885 @itemx --unified@r{[}=@var{lines}@r{]}
9886 Use the unified output format, showing @var{lines} (an integer) lines of
9887 context, or three if @var{lines} is not given.
9888 For proper operation, @code{patch} typically needs at least two lines of
9892 Ignore white space when comparing lines.
9894 @item -W @var{columns}
9895 @itemx --width=@var{columns}
9896 Use an output width of @var{columns} in side by side format.
9899 Use the side by side output format.
9903 * Line group formats:: Line group formats
9904 * Line formats:: Line formats
9907 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9908 @node Line group formats
9909 @appendixsubsubsec Line group formats
9911 Line group formats let you specify formats suitable for many
9912 applications that allow if-then-else input, including programming
9913 languages and text formatting languages. A line group format specifies
9914 the output format for a contiguous group of similar lines.
9916 For example, the following command compares the TeX file @file{myfile}
9917 with the original version from the repository,
9918 and outputs a merged file in which old regions are
9919 surrounded by @samp{\begin@{em@}}-@samp{\end@{em@}} lines, and new
9920 regions are surrounded by @samp{\begin@{bf@}}-@samp{\end@{bf@}} lines.
9924 --old-group-format='\begin@{em@}
9927 --new-group-format='\begin@{bf@}
9933 The following command is equivalent to the above example, but it is a
9934 little more verbose, because it spells out the default line group formats.
9938 --old-group-format='\begin@{em@}
9941 --new-group-format='\begin@{bf@}
9944 --unchanged-group-format='%=' \
9945 --changed-group-format='\begin@{em@}
9953 Here is a more advanced example, which outputs a diff listing with
9954 headers containing line numbers in a ``plain English'' style.
9958 --unchanged-group-format='' \
9959 --old-group-format='-------- %dn line%(n=1?:s) deleted at %df:
9961 --new-group-format='-------- %dN line%(N=1?:s) added after %de:
9963 --changed-group-format='-------- %dn line%(n=1?:s) changed at %df:
9969 To specify a line group format, use one of the options
9970 listed below. You can specify up to four line group formats, one for
9971 each kind of line group. You should quote @var{format}, because it
9972 typically contains shell metacharacters.
9975 @item --old-group-format=@var{format}
9976 These line groups are hunks containing only lines from the first file.
9977 The default old group format is the same as the changed group format if
9978 it is specified; otherwise it is a format that outputs the line group as-is.
9980 @item --new-group-format=@var{format}
9981 These line groups are hunks containing only lines from the second
9982 file. The default new group format is same as the changed group
9983 format if it is specified; otherwise it is a format that outputs the
9986 @item --changed-group-format=@var{format}
9987 These line groups are hunks containing lines from both files. The
9988 default changed group format is the concatenation of the old and new
9991 @item --unchanged-group-format=@var{format}
9992 These line groups contain lines common to both files. The default
9993 unchanged group format is a format that outputs the line group as-is.
9996 In a line group format, ordinary characters represent themselves;
9997 conversion specifications start with @samp{%} and have one of the
10002 stands for the lines from the first file, including the trailing newline.
10003 Each line is formatted according to the old line format (@pxref{Line formats}).
10006 stands for the lines from the second file, including the trailing newline.
10007 Each line is formatted according to the new line format.
10010 stands for the lines common to both files, including the trailing newline.
10011 Each line is formatted according to the unchanged line format.
10014 stands for @samp{%}.
10017 where @var{C} is a single character, stands for @var{C}.
10018 @var{C} may not be a backslash or an apostrophe.
10019 For example, @samp{%c':'} stands for a colon, even inside
10020 the then-part of an if-then-else format, which a colon would
10021 normally terminate.
10024 where @var{O} is a string of 1, 2, or 3 octal digits,
10025 stands for the character with octal code @var{O}.
10026 For example, @samp{%c'\0'} stands for a null character.
10028 @item @var{F}@var{n}
10029 where @var{F} is a @code{printf} conversion specification and @var{n} is one
10030 of the following letters, stands for @var{n}'s value formatted with @var{F}.
10034 The line number of the line just before the group in the old file.
10037 The line number of the first line in the group in the old file;
10038 equals @var{e} + 1.
10041 The line number of the last line in the group in the old file.
10044 The line number of the line just after the group in the old file;
10045 equals @var{l} + 1.
10048 The number of lines in the group in the old file; equals @var{l} - @var{f} + 1.
10050 @item E, F, L, M, N
10051 Likewise, for lines in the new file.
10055 The @code{printf} conversion specification can be @samp{%d},
10056 @samp{%o}, @samp{%x}, or @samp{%X}, specifying decimal, octal,
10057 lower case hexadecimal, or upper case hexadecimal output
10058 respectively. After the @samp{%} the following options can appear in
10059 sequence: a @samp{-} specifying left-justification; an integer
10060 specifying the minimum field width; and a period followed by an
10061 optional integer specifying the minimum number of digits.
10062 For example, @samp{%5dN} prints the number of new lines in the group
10063 in a field of width 5 characters, using the @code{printf} format @code{"%5d"}.
10065 @item (@var{A}=@var{B}?@var{T}:@var{E})
10066 If @var{A} equals @var{B} then @var{T} else @var{E}.
10067 @var{A} and @var{B} are each either a decimal constant
10068 or a single letter interpreted as above.
10069 This format spec is equivalent to @var{T} if
10070 @var{A}'s value equals @var{B}'s; otherwise it is equivalent to @var{E}.
10072 For example, @samp{%(N=0?no:%dN) line%(N=1?:s)} is equivalent to
10073 @samp{no lines} if @var{N} (the number of lines in the group in the
10074 new file) is 0, to @samp{1 line} if @var{N} is 1, and to @samp{%dN lines}
10078 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10080 @appendixsubsubsec Line formats
10082 Line formats control how each line taken from an input file is
10083 output as part of a line group in if-then-else format.
10085 For example, the following command outputs text with a one-column
10086 change indicator to the left of the text. The first column of output
10087 is @samp{-} for deleted lines, @samp{|} for added lines, and a space
10088 for unchanged lines. The formats contain newline characters where
10089 newlines are desired on output.
10093 --old-line-format='-%l
10095 --new-line-format='|%l
10097 --unchanged-line-format=' %l
10102 To specify a line format, use one of the following options. You should
10103 quote @var{format}, since it often contains shell metacharacters.
10106 @item --old-line-format=@var{format}
10107 formats lines just from the first file.
10109 @item --new-line-format=@var{format}
10110 formats lines just from the second file.
10112 @item --unchanged-line-format=@var{format}
10113 formats lines common to both files.
10115 @item --line-format=@var{format}
10116 formats all lines; in effect, it sets all three above options simultaneously.
10119 In a line format, ordinary characters represent themselves;
10120 conversion specifications start with @samp{%} and have one of the
10125 stands for the contents of the line, not counting its trailing
10126 newline (if any). This format ignores whether the line is incomplete.
10129 stands for the contents of the line, including its trailing newline
10130 (if any). If a line is incomplete, this format preserves its
10134 stands for @samp{%}.
10137 where @var{C} is a single character, stands for @var{C}.
10138 @var{C} may not be a backslash or an apostrophe.
10139 For example, @samp{%c':'} stands for a colon.
10142 where @var{O} is a string of 1, 2, or 3 octal digits,
10143 stands for the character with octal code @var{O}.
10144 For example, @samp{%c'\0'} stands for a null character.
10147 where @var{F} is a @code{printf} conversion specification,
10148 stands for the line number formatted with @var{F}.
10149 For example, @samp{%.5dn} prints the line number using the
10150 @code{printf} format @code{"%.5d"}. @xref{Line group formats}, for
10151 more about printf conversion specifications.
10155 The default line format is @samp{%l} followed by a newline character.
10157 If the input contains tab characters and it is important that they line
10158 up on output, you should ensure that @samp{%l} or @samp{%L} in a line
10159 format is just after a tab stop (e.g.@: by preceding @samp{%l} or
10160 @samp{%L} with a tab character), or you should use the @samp{-t} or
10161 @samp{--expand-tabs} option.
10163 Taken together, the line and line group formats let you specify many
10164 different formats. For example, the following command uses a format
10165 similar to @code{diff}'s normal format. You can tailor this command
10166 to get fine control over @code{diff}'s output.
10170 --old-line-format='< %l
10172 --new-line-format='> %l
10174 --old-group-format='%df%(f=l?:,%dl)d%dE
10176 --new-group-format='%dea%dF%(F=L?:,%dL)
10178 --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL)
10181 --unchanged-group-format='' \
10185 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10186 @node diff examples
10187 @appendixsubsec diff examples
10189 The following line produces a Unidiff (@samp{-u} flag)
10190 between revision 1.14 and 1.19 of
10191 @file{backend.c}. Due to the @samp{-kk} flag no
10192 keywords are substituted, so differences that only depend
10193 on keyword substitution are ignored.
10196 $ cvs diff -kk -u -r 1.14 -r 1.19 backend.c
10199 Suppose the experimental branch EXPR1 was based on a
10200 set of files tagged RELEASE_1_0. To see what has
10201 happened on that branch, the following can be used:
10204 $ cvs diff -r RELEASE_1_0 -r EXPR1
10207 A command like this can be used to produce a context
10208 diff between two releases:
10211 $ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs
10214 If you are maintaining ChangeLogs, a command like the following
10215 just before you commit your changes may help you write
10216 the ChangeLog entry. All local modifications that have
10217 not yet been committed will be printed.
10220 $ cvs diff -u | less
10223 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
10225 @appendixsec export---Export sources from CVS, similar to checkout
10226 @cindex export (subcommand)
10230 Synopsis: export [-flNnR] [-r rev|-D date] [-k subst] [-d dir] module@dots{}
10232 Requires: repository.
10234 Changes: current directory.
10237 This command is a variant of @code{checkout}; use it
10238 when you want a copy of the source for module without
10239 the @sc{cvs} administrative directories. For example, you
10240 might use @code{export} to prepare source for shipment
10241 off-site. This command requires that you specify a
10242 date or tag (with @samp{-D} or @samp{-r}), so that you
10243 can count on reproducing the source you ship to others
10244 (and thus it always prunes empty directories).
10246 One often would like to use @samp{-kv} with @code{cvs
10247 export}. This causes any keywords to be
10248 expanded such that an import done at some other site
10249 will not lose the keyword revision information. But be
10250 aware that doesn't handle an export containing binary
10251 files correctly. Also be aware that after having used
10252 @samp{-kv}, one can no longer use the @code{ident}
10253 command (which is part of the @sc{rcs} suite---see
10254 ident(1)) which looks for keyword strings. If
10255 you want to be able to use @code{ident} you must not
10259 * export options:: export options
10262 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10263 @node export options
10264 @appendixsubsec export options
10266 These standard options are supported by @code{export}
10267 (@pxref{Common options}, for a complete description of
10271 @item -D @var{date}
10272 Use the most recent revision no later than @var{date}.
10275 If no matching revision is found, retrieve the most
10276 recent revision (instead of ignoring the file).
10279 Local; run only in current working directory.
10282 Do not run any checkout program.
10285 Export directories recursively. This is on by default.
10288 Use revision @var{tag}.
10291 In addition, these options (that are common to
10292 @code{checkout} and @code{export}) are also supported:
10296 Create a directory called @var{dir} for the working
10297 files, instead of using the module name.
10298 @xref{checkout options}, for complete details on how
10299 @sc{cvs} handles this flag.
10301 @item -k @var{subst}
10302 Set keyword expansion mode (@pxref{Substitution modes}).
10305 Only useful together with @samp{-d @var{dir}}.
10306 @xref{checkout options}, for complete details on how
10307 @sc{cvs} handles this flag.
10311 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10312 @c @node export examples
10313 @appendixsubsec export examples
10315 Contributed examples are gratefully accepted.
10316 @c -- Examples here!!
10319 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
10321 @appendixsec history---Show status of files and users
10322 @cindex history (subcommand)
10326 Synopsis: history [-report] [-flags] [-options args] [files@dots{}]
10328 Requires: the file @file{$CVSROOT/CVSROOT/history}
10333 @sc{cvs} can keep a history file that tracks each use of the
10334 @code{checkout}, @code{commit}, @code{rtag},
10335 @code{update}, and @code{release} commands. You can
10336 use @code{history} to display this information in
10339 Logging must be enabled by creating the file
10340 @file{$CVSROOT/CVSROOT/history}.
10342 @strong{Note: @code{history} uses @samp{-f}, @samp{-l},
10343 @samp{-n}, and @samp{-p} in ways that conflict with the
10344 normal use inside @sc{cvs} (@pxref{Common options}).}
10347 * history options:: history options
10350 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10351 @node history options
10352 @appendixsubsec history options
10354 Several options (shown above as @samp{-report}) control what
10355 kind of report is generated:
10359 Report on each time commit was used (i.e., each time
10360 the repository was modified).
10363 Everything (all record types). Equivalent to
10364 specifying @samp{-x} with all record types. Of course,
10365 @samp{-e} will also include record types which are
10366 added in a future version of @sc{cvs}; if you are
10367 writing a script which can only handle certain record
10368 types, you'll want to specify @samp{-x}.
10370 @item -m @var{module}
10371 Report on a particular module. (You can meaningfully
10372 use @samp{-m} more than once on the command line.)
10375 Report on checked-out modules. This is the default report type.
10378 Report on all tags.
10380 @item -x @var{type}
10381 Extract a particular set of record types @var{type} from the @sc{cvs}
10382 history. The types are indicated by single letters,
10383 which you may specify in combination.
10385 Certain commands have a single record type:
10399 One of five record types may result from an update:
10403 A merge was necessary but collisions were
10404 detected (requiring manual merging).
10406 A merge was necessary and it succeeded.
10408 A working file was copied from the repository.
10410 A working file was patched to match the repository.
10412 The working copy of a file was deleted during
10413 update (because it was gone from the repository).
10417 One of three record types results from commit:
10421 A file was added for the first time.
10423 A file was modified.
10425 A file was removed.
10429 The options shown as @samp{-flags} constrain or expand
10430 the report without requiring option arguments:
10434 Show data for all users (the default is to show data
10435 only for the user executing @code{history}).
10438 Show last modification only.
10441 Show only the records for modifications done from the
10442 same working directory where @code{history} is
10446 The options shown as @samp{-options @var{args}} constrain the report
10447 based on an argument:
10451 Show data back to a record containing the string
10452 @var{str} in either the module name, the file name, or
10453 the repository path.
10455 @item -D @var{date}
10456 Show data since @var{date}. This is slightly different
10457 from the normal use of @samp{-D @var{date}}, which
10458 selects the newest revision older than @var{date}.
10460 @item -f @var{file}
10461 Show data for a particular file
10462 (you can specify several @samp{-f} options on the same command line).
10463 This is equivalent to specifying the file on the command line.
10465 @item -n @var{module}
10466 Show data for a particular module
10467 (you can specify several @samp{-n} options on the same command line).
10469 @item -p @var{repository}
10470 Show data for a particular source repository (you
10471 can specify several @samp{-p} options on the same command
10475 Show records referring to revisions since the revision
10476 or tag named @var{rev} appears in individual @sc{rcs}
10477 files. Each @sc{rcs} file is searched for the revision or
10481 Show records since tag @var{tag} was last added to the
10482 history file. This differs from the @samp{-r} flag
10483 above in that it reads only the history file, not the
10484 @sc{rcs} files, and is much faster.
10486 @item -u @var{name}
10487 Show records for user @var{name}.
10489 @item -z @var{timezone}
10490 Show times in the selected records using the specified
10491 time zone instead of UTC.
10495 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10496 @c @node history examples
10497 @appendixsubsec history examples
10499 Contributed examples will gratefully be accepted.
10500 @c -- Examples here!
10503 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
10505 @appendixsec import---Import sources into CVS, using vendor branches
10506 @cindex import (subcommand)
10508 @c FIXME: This node is way too long for one which has subnodes.
10512 Synopsis: import [-options] repository vendortag releasetag@dots{}
10514 Requires: Repository, source distribution directory.
10516 Changes: repository.
10519 Use @code{import} to incorporate an entire source
10520 distribution from an outside source (e.g., a source
10521 vendor) into your source repository directory. You can
10522 use this command both for initial creation of a
10523 repository, and for wholesale updates to the module
10524 from the outside source. @xref{Tracking sources}, for
10525 a discussion on this subject.
10527 The @var{repository} argument gives a directory name
10528 (or a path to a directory) under the @sc{cvs} root directory
10529 for repositories; if the directory did not exist,
10532 When you use import for updates to source that has been
10533 modified in your source repository (since a prior
10534 import), it will notify you of any files that conflict
10535 in the two branches of development; use @samp{checkout
10536 -j} to reconcile the differences, as import instructs
10539 If @sc{cvs} decides a file should be ignored
10540 (@pxref{cvsignore}), it does not import it and prints
10541 @samp{I } followed by the filename (@pxref{import output}, for a
10542 complete description of the output).
10544 If the file @file{$CVSROOT/CVSROOT/cvswrappers} exists,
10545 any file whose names match the specifications in that
10546 file will be treated as packages and the appropriate
10547 filtering will be performed on the file/directory
10548 before being imported. @xref{Wrappers}.
10550 The outside source is saved in a first-level
10551 branch, by default 1.1.1. Updates are leaves of this
10552 branch; for example, files from the first imported
10553 collection of source will be revision 1.1.1.1, then
10554 files from the first imported update will be revision
10555 1.1.1.2, and so on.
10557 At least three arguments are required.
10558 @var{repository} is needed to identify the collection
10559 of source. @var{vendortag} is a tag for the entire
10560 branch (e.g., for 1.1.1). You must also specify at
10561 least one @var{releasetag} to uniquely identify the files at
10562 the leaves created each time you execute @code{import}. The
10563 @var{releasetag} should be new, not previously existing in the
10564 repository file, and uniquely identify the imported release,
10566 @c I'm not completely sure this belongs here. But
10567 @c we need to say it _somewhere_ reasonably obvious; it
10568 @c is a common misconception among people first learning CVS
10569 Note that @code{import} does @emph{not} change the
10570 directory in which you invoke it. In particular, it
10571 does not set up that directory as a @sc{cvs} working
10572 directory; if you want to work with the sources import
10573 them first and then check them out into a different
10574 directory (@pxref{Getting the source}).
10577 * import options:: import options
10578 * import output:: import output
10579 * import examples:: import examples
10582 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10583 @node import options
10584 @appendixsubsec import options
10586 This standard option is supported by @code{import}
10587 (@pxref{Common options}, for a complete description):
10590 @item -m @var{message}
10591 Use @var{message} as log information, instead of
10592 invoking an editor.
10595 There are the following additional special options.
10598 @item -b @var{branch}
10599 See @ref{Multiple vendor branches}.
10601 @item -k @var{subst}
10602 Indicate the keyword expansion mode desired. This
10603 setting will apply to all files created during the
10604 import, but not to any files that previously existed in
10605 the repository. See @ref{Substitution modes}, for a
10606 list of valid @samp{-k} settings.
10608 @item -I @var{name}
10609 Specify file names that should be ignored during
10610 import. You can use this option repeatedly. To avoid
10611 ignoring any files at all (even those ignored by
10612 default), specify `-I !'.
10614 @var{name} can be a file name pattern of the same type
10615 that you can specify in the @file{.cvsignore} file.
10617 @c -- Is this really true?
10619 @item -W @var{spec}
10620 Specify file names that should be filtered during
10621 import. You can use this option repeatedly.
10623 @var{spec} can be a file name pattern of the same type
10624 that you can specify in the @file{.cvswrappers}
10625 file. @xref{Wrappers}.
10628 Modify the algorithm used by @sc{cvs} when importing new files
10629 so that new files do not immediately appear on the main trunk.
10631 Specifically, this flag causes @sc{cvs} to mark new files as
10632 if they were deleted on the main trunk, by taking the following
10633 steps for each file in addition to those normally taken on import:
10634 creating a new revision on the main trunk indicating that
10635 the new file is @code{dead}, resetting the new file's default branch,
10636 and placing the file in the Attic (@pxref{Attic}) directory.
10638 Use of this option can be forced on a repository-wide basis
10639 by setting the @samp{ImportNewFilesToVendorBranchOnly} option in
10640 CVSROOT/config (@pxref{config}).
10643 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10644 @node import output
10645 @appendixsubsec import output
10647 @code{import} keeps you informed of its progress by printing a line
10648 for each file, preceded by one character indicating the status of the file:
10652 The file already exists in the repository and has not been locally
10653 modified; a new revision has been created (if necessary).
10656 The file is a new file which has been added to the repository.
10659 The file already exists in the repository but has been locally modified;
10660 you will have to merge the changes.
10663 The file is being ignored (@pxref{cvsignore}).
10665 @cindex Symbolic link, importing
10666 @cindex Link, symbolic, importing
10667 @c FIXME: also (somewhere else) probably
10668 @c should be documenting what happens if you "cvs add"
10669 @c a symbolic link. Also maybe what happens if
10670 @c you manually create symbolic links within the
10671 @c repository (? - not sure why we'd want to suggest
10674 The file is a symbolic link; @code{cvs import} ignores symbolic links.
10675 People periodically suggest that this behavior should
10676 be changed, but if there is a consensus on what it
10677 should be changed to, it is not apparent.
10678 (Various options in the @file{modules} file can be used
10679 to recreate symbolic links on checkout, update, etc.;
10683 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10684 @node import examples
10685 @appendixsubsec import examples
10687 See @ref{Tracking sources}, and @ref{From files}.
10689 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
10691 @appendixsec log---Print out log information for files
10692 @cindex log (subcommand)
10696 Synopsis: log [options] [files@dots{}]
10698 Requires: repository, working directory.
10703 Display log information for files. @code{log} used to
10704 call the @sc{rcs} utility @code{rlog}. Although this
10705 is no longer true in the current sources, this history
10706 determines the format of the output and the options,
10707 which are not quite in the style of the other @sc{cvs}
10710 @cindex Timezone, in output
10711 @cindex Zone, time, in output
10712 The output includes the location of the @sc{rcs} file,
10713 the @dfn{head} revision (the latest revision on the
10714 trunk), all symbolic names (tags) and some other
10715 things. For each revision, the revision number, the
10717 author, the number of lines added/deleted and the log
10718 message are printed. All dates are displayed in local
10719 time at the client. This is typically specified in the
10720 @code{$TZ} environment variable, which can be set to
10721 govern how @code{log} displays dates.
10723 @strong{Note: @code{log} uses @samp{-R} in a way that conflicts
10724 with the normal use inside @sc{cvs} (@pxref{Common options}).}
10727 * log options:: log options
10728 * log examples:: log examples
10731 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10733 @appendixsubsec log options
10735 By default, @code{log} prints all information that is
10736 available. All other options restrict the output.
10740 Print information about the revisions on the default
10741 branch, normally the highest branch on the trunk.
10743 @item -d @var{dates}
10744 Print information about revisions with a checkin
10745 date/time in the range given by the
10746 semicolon-separated list of dates. The date formats
10747 accepted are those accepted by the @samp{-D} option to
10748 many other @sc{cvs} commands (@pxref{Common options}).
10749 Dates can be combined into ranges as follows:
10751 @c Should we be thinking about accepting ISO8601
10752 @c ranges? For example "1972-09-10/1972-09-12".
10754 @item @var{d1}<@var{d2}
10755 @itemx @var{d2}>@var{d1}
10756 Select the revisions that were deposited between
10757 @var{d1} and @var{d2}.
10761 Select all revisions dated @var{d} or earlier.
10765 Select all revisions dated @var{d} or later.
10768 Select the single, latest revision dated @var{d} or
10772 The @samp{>} or @samp{<} characters may be followed by
10773 @samp{=} to indicate an inclusive range rather than an
10776 Note that the separator is a semicolon (;).
10779 Print only the name of the @sc{rcs} file, name
10780 of the file in the working directory, head,
10781 default branch, access list, locks, symbolic names, and
10785 Local; run only in current working directory. (Default
10786 is to run recursively).
10789 Do not print the list of tags for this file. This
10790 option can be very useful when your site uses a lot of
10791 tags, so rather than "more"'ing over 3 pages of tag
10792 information, the log information is presented without
10796 Print only the name of the @sc{rcs} file.
10798 @c Note that using a bare revision (in addition to not
10799 @c being explicitly documented here) is potentially
10800 @c confusing; it shows the log message to get from the
10801 @c previous revision to that revision. "-r1.3 -r1.6"
10802 @c (equivalent to "-r1.3,1.6") is even worse; it
10803 @c prints the messages to get from 1.2 to 1.3 and 1.5
10804 @c to 1.6. By analogy with "cvs diff", users might
10805 @c expect that it is more like specifying a range.
10806 @c It is not 100% clear to me how much of this should
10807 @c be documented (for example, multiple -r options
10808 @c perhaps could/should be deprecated given the false
10809 @c analogy with "cvs diff").
10810 @c In general, this section should be rewritten to talk
10811 @c about messages to get from revision rev1 to rev2,
10812 @c rather than messages for revision rev2 (that is, the
10813 @c messages are associated with a change not a static
10814 @c revision and failing to make this distinction causes
10815 @c much confusion).
10816 @item -r@var{revisions}
10817 Print information about revisions given in the
10818 comma-separated list @var{revisions} of revisions and
10819 ranges. The following table explains the available
10823 @item @var{rev1}:@var{rev2}
10824 Revisions @var{rev1} to @var{rev2} (which must be on
10827 @item @var{rev1}::@var{rev2}
10828 The same, but excluding @var{rev1}.
10832 Revisions from the beginning of the branch up to
10833 and including @var{rev}.
10836 Revisions starting with @var{rev} to the end of the
10837 branch containing @var{rev}.
10840 Revisions starting just after @var{rev} to the end of the
10841 branch containing @var{rev}.
10844 An argument that is a branch means all revisions on
10847 @item @var{branch1}:@var{branch2}
10848 @itemx @var{branch1}::@var{branch2}
10849 A range of branches means all revisions
10850 on the branches in that range.
10852 @item @var{branch}.
10853 The latest revision in @var{branch}.
10856 A bare @samp{-r} with no revisions means the latest
10857 revision on the default branch, normally the trunk.
10858 There can be no space between the @samp{-r} option and
10862 Suppress the header if no revisions are selected.
10864 @item -s @var{states}
10865 Print information about revisions whose state
10866 attributes match one of the states given in the
10867 comma-separated list @var{states}.
10870 Print the same as @samp{-h}, plus the descriptive text.
10872 @item -w@var{logins}
10873 Print information about revisions checked in by users
10874 with login names appearing in the comma-separated list
10875 @var{logins}. If @var{logins} is omitted, the user's
10876 login is assumed. There can be no space between the
10877 @samp{-w} option and its argument.
10880 @code{log} prints the intersection of the revisions
10881 selected with the options @samp{-d}, @samp{-s}, and
10882 @samp{-w}, intersected with the union of the revisions
10883 selected by @samp{-b} and @samp{-r}.
10885 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10887 @appendixsubsec log examples
10889 @cindex Timezone, in output
10890 @cindex Zone, time, in output
10891 Since @code{log} shows dates in local time,
10892 you might want to see them in Coordinated Universal Time (UTC) or
10893 some other timezone.
10894 To do this you can set your @code{$TZ} environment
10895 variable before invoking @sc{cvs}:
10898 $ TZ=UTC cvs log foo.c
10899 $ TZ=EST cvs log bar.c
10902 (If you are using a @code{csh}-style shell, like @code{tcsh},
10903 you would need to prefix the examples above with @code{env}.)
10905 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
10907 @appendixsec ls & rls
10908 @cindex ls (subcommand)
10909 @cindex rls (subcommand)
10913 ls [-e | -l] [-RP] [-r revision] [-D date] [path@dots{}]
10915 Requires: repository for @code{rls}, repository & working directory for
10920 Synonym: @code{dir} & @code{list} are synonyms for @code{ls} and @code{rdir}
10921 & @code{rlist} are synonyms for @code{rls}.
10924 The @code{ls} and @code{rls} commands are used to list
10925 files and directories in the repository.
10927 By default @code{ls} lists the files and directories
10928 that belong in your working directory, what would be
10929 there after an @code{update}.
10931 By default @code{rls} lists the files and directories
10932 on the tip of the trunk in the topmost directory of the
10935 Both commands accept an optional list of file and
10936 directory names, relative to the working directory for
10937 @code{ls} and the topmost directory of the repository
10938 for @code{rls}. Neither is recursive by default.
10941 * ls & rls options:: ls & rls options
10942 * rls examples: rls examples
10945 @node ls & rls options
10946 @appendixsubsec ls & rls options
10948 These standard options are supported by @code{ls} & @code{rls}:
10952 Show dead revisions (with tag when specified).
10955 Display in CVS/Entries format. This format is meant to remain easily parsable
10959 Display all details.
10962 Don't list contents of empty directories when recursing.
10967 @item -r @var{revision}
10968 Show files with revision or tag.
10970 @item -D @var{date}
10971 Show files from date.
10974 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10976 @appendixsubsec rls examples
10980 cvs rls: Listing module: `.'
10987 cvs rls: Listing module: `CVSROOT'
11001 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
11003 @appendixsec rdiff---'patch' format diffs between releases
11004 @cindex rdiff (subcommand)
11008 rdiff [-flags] [-V vn] [-r t|-D d [-r t2|-D d2]] modules@dots{}
11010 Requires: repository.
11017 Builds a Larry Wall format patch(1) file between two
11018 releases, that can be fed directly into the @code{patch}
11019 program to bring an old release up-to-date with the new
11020 release. (This is one of the few @sc{cvs} commands that
11021 operates directly from the repository, and doesn't
11022 require a prior checkout.) The diff output is sent to
11023 the standard output device.
11025 You can specify (using the standard @samp{-r} and
11026 @samp{-D} options) any combination of one or two
11027 revisions or dates. If only one revision or date is
11028 specified, the patch file reflects differences between
11029 that revision or date and the current head revisions in
11032 Note that if the software release affected is contained
11033 in more than one directory, then it may be necessary to
11034 specify the @samp{-p} option to the @code{patch} command when
11035 patching the old sources, so that @code{patch} is able to find
11036 the files that are located in other directories.
11039 * rdiff options:: rdiff options
11040 * rdiff examples:: rdiff examples
11043 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11044 @node rdiff options
11045 @appendixsubsec rdiff options
11047 These standard options are supported by @code{rdiff}
11048 (@pxref{Common options}, for a complete description of
11052 @item -D @var{date}
11053 Use the most recent revision no later than @var{date}.
11056 If no matching revision is found, retrieve the most
11057 recent revision (instead of ignoring the file).
11060 Local; don't descend subdirectories.
11063 Examine directories recursively. This option is on by default.
11066 Use revision @var{tag}.
11069 In addition to the above, these options are available:
11073 Use the context diff format. This is the default format.
11076 Create a summary change report instead of a patch. The
11077 summary includes information about files that were
11078 changed or added between the releases. It is sent to
11079 the standard output device. This is useful for finding
11080 out, for example, which files have changed between two
11081 dates or revisions.
11084 A diff of the top two revisions is sent to the standard
11085 output device. This is most useful for seeing what the
11086 last change to a file was.
11089 Use the unidiff format for the context diffs.
11090 Remember that old versions
11091 of the @code{patch} program can't handle the unidiff
11092 format, so if you plan to post this patch to the net
11093 you should probably not use @samp{-u}.
11096 Expand keywords according to the rules current in
11097 @sc{rcs} version @var{vn} (the expansion format changed with
11098 @sc{rcs} version 5). Note that this option is no
11099 longer accepted. @sc{cvs} will always expand keywords the
11100 way that @sc{rcs} version 5 does.
11103 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11104 @node rdiff examples
11105 @appendixsubsec rdiff examples
11107 Suppose you receive mail from @t{foo@@example.net} asking for an
11108 update from release 1.2 to 1.4 of the tc compiler. You
11109 have no such patches on hand, but with @sc{cvs} that can
11110 easily be fixed with a command such as this:
11113 $ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \
11114 $$ Mail -s 'The patches you asked for' foo@@example.net
11117 Suppose you have made release 1.3, and forked a branch
11118 called @samp{R_1_3fix} for bug fixes. @samp{R_1_3_1}
11119 corresponds to release 1.3.1, which was made some time
11120 ago. Now, you want to see how much development has been
11121 done on the branch. This command can be used:
11124 $ cvs patch -s -r R_1_3_1 -r R_1_3fix module-name
11125 cvs rdiff: Diffing module-name
11126 File ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6
11127 File foo.c,v changed from revision 1.52.2.3 to 1.52.2.4
11128 File bar.h,v changed from revision 1.29.2.1 to 1.2
11131 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
11133 @appendixsec release---Indicate that a Module is no longer in use
11134 @cindex release (subcommand)
11138 release [-d] directories@dots{}
11140 Requires: Working directory.
11142 Changes: Working directory, history log.
11145 This command is meant to safely cancel the effect of
11146 @samp{cvs checkout}. Since @sc{cvs} doesn't lock files, it
11147 isn't strictly necessary to use this command. You can
11148 always simply delete your working directory, if you
11149 like; but you risk losing changes you may have
11150 forgotten, and you leave no trace in the @sc{cvs} history
11151 file (@pxref{history file}) that you've abandoned your
11154 Use @samp{cvs release} to avoid these problems. This
11155 command checks that no uncommitted changes are
11156 present; that you are executing it from immediately
11157 above a @sc{cvs} working directory; and that the repository
11158 recorded for your files is the same as the repository
11159 defined in the module database.
11161 If all these conditions are true, @samp{cvs release}
11162 leaves a record of its execution (attesting to your
11163 intentionally abandoning your checkout) in the @sc{cvs}
11167 * release options:: release options
11168 * release output:: release output
11169 * release examples:: release examples
11172 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11173 @node release options
11174 @appendixsubsec release options
11176 The @code{release} command supports one command option:
11180 Delete your working copy of the file if the release
11181 succeeds. If this flag is not given your files will
11182 remain in your working directory.
11184 @strong{WARNING: The @code{release} command deletes
11185 all directories and files recursively. This
11186 has the very serious side-effect that any directory
11187 that you have created inside your checked-out sources,
11188 and not added to the repository (using the @code{add}
11189 command; @pxref{Adding files}) will be silently deleted---even
11190 if it is non-empty!}
11193 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11194 @node release output
11195 @appendixsubsec release output
11197 Before @code{release} releases your sources it will
11198 print a one-line message for any file that is not
11203 @itemx P @var{file}
11204 There exists a newer revision of this file in the
11205 repository, and you have not modified your local copy
11206 of the file (@samp{U} and @samp{P} mean the same thing).
11209 The file has been added to your private copy of the
11210 sources, but has not yet been committed to the
11211 repository. If you delete your copy of the sources
11212 this file will be lost.
11215 The file has been removed from your private copy of the
11216 sources, but has not yet been removed from the
11217 repository, since you have not yet committed the
11218 removal. @xref{commit}.
11221 The file is modified in your working directory. There
11222 might also be a newer revision inside the repository.
11225 @var{file} is in your working directory, but does not
11226 correspond to anything in the source repository, and is
11227 not in the list of files for @sc{cvs} to ignore (see the
11228 description of the @samp{-I} option, and
11229 @pxref{cvsignore}). If you remove your working
11230 sources, this file will be lost.
11233 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11234 @node release examples
11235 @appendixsubsec release examples
11237 Release the @file{tc} directory, and delete your local working copy
11241 $ cd .. # @r{You must stand immediately above the}
11242 # @r{sources when you issue @samp{cvs release}.}
11243 $ cvs release -d tc
11244 You have [0] altered files in this repository.
11245 Are you sure you want to release (and delete) directory `tc': y
11249 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
11251 @appendixsec update---Bring work tree in sync with repository
11252 @cindex update (subcommand)
11256 update [-ACdflPpR] [-I name] [-j rev [-j rev]] [-k kflag] [-r tag|-D date] [-W spec] files@dots{}
11258 Requires: repository, working directory.
11260 Changes: working directory.
11263 After you've run checkout to create your private copy
11264 of source from the common repository, other developers
11265 will continue changing the central source. From time
11266 to time, when it is convenient in your development
11267 process, you can use the @code{update} command from
11268 within your working directory to reconcile your work
11269 with any revisions applied to the source repository
11270 since your last checkout or update. Without the @code{-C}
11271 option, @code{update} will also merge any differences
11272 between the local copy of files and their base revisions
11273 into any destination revisions specified with @code{-r},
11274 @code{-D}, or @code{-A}.
11277 * update options:: update options
11278 * update output:: update output
11281 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11282 @node update options
11283 @appendixsubsec update options
11285 These standard options are available with @code{update}
11286 (@pxref{Common options}, for a complete description of
11291 Use the most recent revision no later than @var{date}.
11292 This option is sticky, and implies @samp{-P}.
11293 See @ref{Sticky tags}, for more information on sticky tags/dates.
11296 Only useful with the @samp{-D @var{date}} or @samp{-r
11297 @var{tag}} flags. If no matching revision is found,
11298 retrieve the most recent revision (instead of ignoring
11301 @item -k @var{kflag}
11302 Process keywords according to @var{kflag}. See
11303 @ref{Keyword substitution}.
11304 This option is sticky; future updates of
11305 this file in this working directory will use the same
11306 @var{kflag}. The @code{status} command can be viewed
11307 to see the sticky options. See @ref{Invoking CVS}, for
11308 more information on the @code{status} command.
11311 Local; run only in current working directory. @xref{Recursive behavior}.
11314 Prune empty directories. See @ref{Moving directories}.
11317 Pipe files to the standard output.
11320 Update directories recursively (default). @xref{Recursive
11324 Retrieve revision/tag @var{rev}. This option is sticky,
11325 and implies @samp{-P}.
11326 See @ref{Sticky tags}, for more information on sticky tags/dates.
11330 These special options are also available with
11335 Reset any sticky tags, dates, or @samp{-k} options.
11336 See @ref{Sticky tags}, for more information on sticky tags/dates.
11339 Overwrite locally modified files with clean copies from
11340 the repository (the modified file is saved in
11341 @file{.#@var{file}.@var{revision}}, however).
11344 Create any directories that exist in the repository if
11345 they're missing from the working directory. Normally,
11346 @code{update} acts only on directories and files that
11347 were already enrolled in your working directory.
11349 This is useful for updating directories that were
11350 created in the repository since the initial checkout;
11351 but it has an unfortunate side effect. If you
11352 deliberately avoided certain directories in the
11353 repository when you created your working directory
11354 (either through use of a module name or by listing
11355 explicitly the files and directories you wanted on the
11356 command line), then updating with @samp{-d} will create
11357 those directories, which may not be what you want.
11359 @item -I @var{name}
11360 Ignore files whose names match @var{name} (in your
11361 working directory) during the update. You can specify
11362 @samp{-I} more than once on the command line to specify
11363 several files to ignore. Use @samp{-I !} to avoid
11364 ignoring any files at all. @xref{cvsignore}, for other
11365 ways to make @sc{cvs} ignore some files.
11368 Specify file names that should be filtered during
11369 update. You can use this option repeatedly.
11371 @var{spec} can be a file name pattern of the same type
11372 that you can specify in the @file{.cvswrappers}
11373 file. @xref{Wrappers}.
11375 @item -j@var{revision}
11376 With two @samp{-j} options, merge changes from the
11377 revision specified with the first @samp{-j} option to
11378 the revision specified with the second @samp{j} option,
11379 into the working directory.
11381 With one @samp{-j} option, merge changes from the
11382 ancestor revision to the revision specified with the
11383 @samp{-j} option, into the working directory. The
11384 ancestor revision is the common ancestor of the
11385 revision which the working directory is based on, and
11386 the revision specified in the @samp{-j} option.
11388 Note that using a single @samp{-j @var{tagname}} option rather than
11389 @samp{-j @var{branchname}} to merge changes from a branch will
11390 often not remove files which were removed on the branch.
11391 @xref{Merging adds and removals}, for more.
11393 In addition, each @samp{-j} option can contain an optional
11394 date specification which, when used with branches, can
11395 limit the chosen revision to one within a specific
11396 date. An optional date is specified by adding a colon
11398 @samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}.
11400 @xref{Branching and merging}.
11404 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11405 @node update output
11406 @appendixsubsec update output
11408 @code{update} and @code{checkout} keep you informed of
11409 their progress by printing a line for each file, preceded
11410 by one character indicating the status of the file:
11414 The file was brought up to date with respect to the
11415 repository. This is done for any file that exists in
11416 the repository but not in your source, and for files
11417 that you haven't changed but are not the most recent
11418 versions available in the repository.
11421 Like @samp{U}, but the @sc{cvs} server sends a patch instead of an entire
11422 file. This accomplishes the same thing as @samp{U} using less bandwidth.
11425 The file has been added to your private copy of the
11426 sources, and will be added to the source repository
11427 when you run @code{commit} on the file. This is a
11428 reminder to you that the file needs to be committed.
11431 The file has been removed from your private copy of the
11432 sources, and will be removed from the source repository
11433 when you run @code{commit} on the file. This is a
11434 reminder to you that the file needs to be committed.
11437 The file is modified in your working directory.
11439 @samp{M} can indicate one of two states for a file
11440 you're working on: either there were no modifications
11441 to the same file in the repository, so that your file
11442 remains as you last saw it; or there were modifications
11443 in the repository as well as in your copy, but they
11444 were merged successfully, without conflict, in your
11447 @sc{cvs} will print some messages if it merges your work,
11448 and a backup copy of your working file (as it looked
11449 before you ran @code{update}) will be made. The exact
11450 name of that file is printed while @code{update} runs.
11454 @cindex __ files (VMS)
11455 A conflict was detected while trying to merge your
11456 changes to @var{file} with changes from the source
11457 repository. @var{file} (the copy in your working
11458 directory) is now the result of attempting to merge
11459 the two revisions; an unmodified copy of your file
11460 is also in your working directory, with the name
11461 @file{.#@var{file}.@var{revision}} where @var{revision}
11462 is the revision that your modified file started
11463 from. Resolve the conflict as described in
11464 @ref{Conflicts example}.
11465 @c "some systems" as in out-of-the-box OSes? Not as
11466 @c far as I know. We need to advise sysadmins as well
11467 @c as users how to set up this kind of purge, if that is
11469 @c We also might want to think about cleaner solutions,
11470 @c like having CVS remove the .# file once the conflict
11471 @c has been resolved or something like that.
11472 (Note that some systems automatically purge
11473 files that begin with @file{.#} if they have not been
11474 accessed for a few days. If you intend to keep a copy
11475 of your original file, it is a very good idea to rename
11476 it.) Under @sc{vms}, the file name starts with
11477 @file{__} rather than @file{.#}.
11480 @var{file} is in your working directory, but does not
11481 correspond to anything in the source repository, and is
11482 not in the list of files for @sc{cvs} to ignore (see the
11483 description of the @samp{-I} option, and
11484 @pxref{cvsignore}).
11487 @c ----- END MAN 1 -----
11488 @c ---------------------------------------------------------------------
11490 @appendix Quick reference to CVS commands
11491 @cindex Command reference
11492 @cindex Reference, commands
11493 @cindex Invoking CVS
11495 This appendix describes how to invoke @sc{cvs}, with
11496 references to where each command or feature is
11497 described in detail. For other references run the
11498 @code{cvs --help} command, or see @ref{Index}.
11500 A @sc{cvs} command looks like:
11503 cvs [ @var{global_options} ] @var{command} [ @var{command_options} ] [ @var{command_args} ]
11509 @item --allow-root=@var{rootdir}
11510 Specify legal @sc{cvsroot} directory (server only) (not
11511 in @sc{cvs} 1.9 and older). See @ref{Password
11512 authentication server}.
11515 Authenticate all communication (client only) (not in @sc{cvs}
11516 1.9 and older). See @ref{Global options}.
11519 Specify RCS location (@sc{cvs} 1.9 and older). See
11520 @ref{Global options}.
11522 @item -d @var{root}
11523 Specify the @sc{cvsroot}. See @ref{Repository}.
11525 @item -e @var{editor}
11526 Edit messages with @var{editor}. See @ref{Committing
11530 Do not read the @file{~/.cvsrc} file. See @ref{Global
11535 Print a help message. See @ref{Global options}.
11538 Do not change any files. See @ref{Global options}.
11541 Be really quiet. See @ref{Global options}.
11544 Be somewhat quiet. See @ref{Global options}.
11547 Make new working files read-only. See @ref{Global options}.
11549 @item -s @var{variable}=@var{value}
11550 Set a user variable. See @ref{Variables}.
11552 @item -T @var{tempdir}
11553 Put temporary files in @var{tempdir}. See @ref{Global
11557 Trace @sc{cvs} execution. See @ref{Global options}.
11561 Display version and copyright information for @sc{cvs}.
11564 Make new working files read-write. See @ref{Global
11568 Encrypt all communication (client only).
11569 See @ref{Global options}.
11571 @item -z @var{gzip-level}
11572 @cindex Compression
11574 Set the compression level (client only).
11575 See @ref{Global options}.
11578 Keyword expansion modes (@pxref{Substitution modes}):
11581 -kkv $@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp $
11582 -kkvl $@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
11583 -kk $@splitrcskeyword{Id}$
11584 -kv file1,v 1.1 1993/12/09 03:21:13 joe Exp
11585 -ko @i{no expansion}
11586 -kb @i{no expansion, file is binary}
11589 Keywords (@pxref{Keyword list}):
11592 $@splitrcskeyword{Author}: joe $
11593 $@splitrcskeyword{Date}: 1993/12/09 03:21:13 $
11594 $@splitrcskeyword{CVSHeader}: files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
11595 $@splitrcskeyword{Header}: /home/files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
11596 $@splitrcskeyword{Id}: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
11597 $@splitrcskeyword{Locker}: harry $
11598 $@splitrcskeyword{Name}: snapshot_1_14 $
11599 $@splitrcskeyword{RCSfile}: file1,v $
11600 $@splitrcskeyword{Revision}: 1.1 $
11601 $@splitrcskeyword{Source}: /home/files/file1,v $
11602 $@splitrcskeyword{State}: Exp $
11603 $@splitrcskeyword{Log}: file1,v $
11604 Revision 1.1 1993/12/09 03:30:17 joe
11609 @c The idea behind this table is that we want each item
11610 @c to be a sentence or two at most. Preferably a
11613 @c In some cases refs to "foo options" are just to get
11614 @c this thing written quickly, not because the "foo
11615 @c options" node is really the best place to point.
11616 Commands, command options, and command arguments:
11619 @c ------------------------------------------------------------
11620 @item add [@var{options}] [@var{files}@dots{}]
11621 Add a new file/directory. See @ref{Adding files}.
11624 @item -k @var{kflag}
11625 Set keyword expansion.
11628 Set file description.
11631 @c ------------------------------------------------------------
11632 @item admin [@var{options}] [@var{files}@dots{}]
11633 Administration of history files in the repository. See
11635 @c This list omits those options which are not
11636 @c documented as being useful with CVS. That might be
11640 @item -b[@var{rev}]
11641 Set default branch. See @ref{Reverting local changes}.
11643 @item -c@var{string}
11644 Set comment leader.
11646 @item -k@var{subst}
11647 Set keyword substitution. See @ref{Keyword
11650 @item -l[@var{rev}]
11651 Lock revision @var{rev}, or latest revision.
11653 @item -m@var{rev}:@var{msg}
11654 Replace the log message of revision @var{rev} with
11657 @item -o@var{range}
11658 Delete revisions from the repository. See
11659 @ref{admin options}.
11662 Run quietly; do not print diagnostics.
11664 @item -s@var{state}[:@var{rev}]
11667 @c Does not work for client/server CVS
11669 Set file description from standard input.
11672 Set file description from @var{file}.
11674 @item -t-@var{string}
11675 Set file description to @var{string}.
11677 @item -u[@var{rev}]
11678 Unlock revision @var{rev}, or latest revision.
11681 @c ------------------------------------------------------------
11682 @item annotate [@var{options}] [@var{files}@dots{}]
11683 Show last revision where each line was modified. See
11687 @item -D @var{date}
11688 Annotate the most recent revision no later than
11689 @var{date}. See @ref{Common options}.
11692 Force annotation of binary files. (Without this option,
11693 binary files are skipped with a message.)
11696 Use head revision if tag/date not found. See
11697 @ref{Common options}.
11700 Local; run only in current working directory. @xref{Recursive behavior}.
11703 Operate recursively (default). @xref{Recursive
11707 Annotate revision @var{tag}. See @ref{Common options}.
11710 @c ------------------------------------------------------------
11711 @item checkout [@var{options}] @var{modules}@dots{}
11712 Get a copy of the sources. See @ref{checkout}.
11716 Reset any sticky tags/date/options. See @ref{Sticky
11717 tags} and @ref{Keyword substitution}.
11720 Output the module database. See @ref{checkout options}.
11722 @item -D @var{date}
11723 Check out revisions as of @var{date} (is sticky). See
11724 @ref{Common options}.
11727 Check out into @var{dir}. See @ref{checkout options}.
11730 Use head revision if tag/date not found. See
11731 @ref{Common options}.
11733 @c Probably want to use rev1/rev2 style like for diff
11734 @c -r. Here and in on-line help.
11736 Merge in changes. See @ref{checkout options}.
11738 @item -k @var{kflag}
11739 Use @var{kflag} keyword expansion. See
11740 @ref{Substitution modes}.
11743 Local; run only in current working directory. @xref{Recursive behavior}.
11746 Don't ``shorten'' module paths if -d specified. See
11747 @ref{checkout options}.
11750 Do not run module program (if any). See @ref{checkout options}.
11753 Prune empty directories. See @ref{Moving directories}.
11756 Check out files to standard output (avoids
11757 stickiness). See @ref{checkout options}.
11760 Operate recursively (default). @xref{Recursive
11764 Checkout revision @var{tag} (is sticky). See @ref{Common options}.
11767 Like -c, but include module status. See @ref{checkout options}.
11770 @c ------------------------------------------------------------
11771 @item commit [@var{options}] [@var{files}@dots{}]
11772 Check changes into the repository. See @ref{commit}.
11776 Check for valid edits before committing. Requires a @sc{cvs} client and server
11777 both version 1.12.10 or greater.
11779 @item -F @var{file}
11780 Read log message from @var{file}. See @ref{commit options}.
11783 @c What is this "disables recursion"? It is from the
11784 @c on-line help; is it documented in this manual?
11785 Force the file to be committed; disables recursion.
11786 See @ref{commit options}.
11789 Local; run only in current working directory. See @ref{Recursive behavior}.
11792 Use @var{msg} as log message. See @ref{commit options}.
11795 Do not run module program (if any). See @ref{commit options}.
11798 Operate recursively (default). @xref{Recursive
11802 Commit to @var{rev}. See @ref{commit options}.
11803 @c FIXME: should be dragging over text from
11804 @c commit options, especially if it can be cleaned up
11805 @c and made concise enough.
11808 @c ------------------------------------------------------------
11809 @item diff [@var{options}] [@var{files}@dots{}]
11810 Show differences between revisions. See @ref{diff}.
11811 In addition to the options shown below, accepts a wide
11812 variety of options to control output style, for example
11813 @samp{-c} for context diffs.
11816 @item -D @var{date1}
11817 Diff revision for date against working file. See
11818 @ref{diff options}.
11820 @item -D @var{date2}
11821 Diff @var{rev1}/@var{date1} against @var{date2}. See
11822 @ref{diff options}.
11825 Local; run only in current working directory. See @ref{Recursive behavior}.
11828 Include diffs for added and removed files. See
11829 @ref{diff options}.
11832 Operate recursively (default). @xref{Recursive
11835 @item -r @var{rev1}
11836 Diff revision for @var{rev1} against working file. See
11837 @ref{diff options}.
11839 @item -r @var{rev2}
11840 Diff @var{rev1}/@var{date1} against @var{rev2}. See @ref{diff options}.
11843 @c ------------------------------------------------------------
11844 @item edit [@var{options}] [@var{files}@dots{}]
11845 Get ready to edit a watched file. See @ref{Editing files}.
11848 @item -a @var{actions}
11849 Specify actions for temporary watch, where
11850 @var{actions} is @code{edit}, @code{unedit},
11851 @code{commit}, @code{all}, or @code{none}. See
11852 @ref{Editing files}.
11855 Check edits: Edit fails if someone else is already editting the file.
11856 Requires a @sc{cvs} client and server both of version 1.12.10 or greater.
11859 Force edit; ignore other edits. Added in CVS 1.12.10.
11862 Local; run only in current working directory. See @ref{Recursive behavior}.
11865 Operate recursively (default). @xref{Recursive
11869 @c ------------------------------------------------------------
11870 @item editors [@var{options}] [@var{files}@dots{}]
11871 See who is editing a watched file. See @ref{Watch information}.
11875 Local; run only in current working directory. See @ref{Recursive behavior}.
11878 Operate recursively (default). @xref{Recursive
11882 @c ------------------------------------------------------------
11883 @item export [@var{options}] @var{modules}@dots{}
11884 Export files from @sc{cvs}. See @ref{export}.
11887 @item -D @var{date}
11888 Check out revisions as of @var{date}. See
11889 @ref{Common options}.
11892 Check out into @var{dir}. See @ref{export options}.
11895 Use head revision if tag/date not found. See
11896 @ref{Common options}.
11898 @item -k @var{kflag}
11899 Use @var{kflag} keyword expansion. See
11900 @ref{Substitution modes}.
11903 Local; run only in current working directory. @xref{Recursive behavior}.
11906 Don't ``shorten'' module paths if -d specified. See
11907 @ref{export options}.
11910 Do not run module program (if any). See @ref{export options}.
11913 Operate recursively (default). @xref{Recursive
11917 Checkout revision @var{tag}. See @ref{Common options}.
11920 @c ------------------------------------------------------------
11921 @item history [@var{options}] [@var{files}@dots{}]
11922 Show repository access history. See @ref{history}.
11926 All users (default is self). See @ref{history options}.
11929 Back to record with @var{str} in module/file/repos
11930 field. See @ref{history options}.
11933 Report on committed (modified) files. See @ref{history options}.
11935 @item -D @var{date}
11936 Since @var{date}. See @ref{history options}.
11939 Report on all record types. See @ref{history options}.
11942 Last modified (committed or modified report). See @ref{history options}.
11944 @item -m @var{module}
11945 Report on @var{module} (repeatable). See @ref{history options}.
11947 @item -n @var{module}
11948 In @var{module}. See @ref{history options}.
11951 Report on checked out modules. See @ref{history options}.
11953 @item -p @var{repository}
11954 In @var{repository}. See @ref{history options}.
11957 Since revision @var{rev}. See @ref{history options}.
11960 @c What the @#$@# is a TAG? Same as a tag? This
11961 @c wording is also in the online-line help.
11962 Produce report on all TAGs. See @ref{history options}.
11965 Since tag record placed in history file (by anyone).
11966 See @ref{history options}.
11968 @item -u @var{user}
11969 For user @var{user} (repeatable). See @ref{history options}.
11972 Working directory must match. See @ref{history options}.
11974 @item -x @var{types}
11975 Report on @var{types}, one or more of
11976 @code{TOEFWUPCGMAR}. See @ref{history options}.
11978 @item -z @var{zone}
11979 Output for time zone @var{zone}. See @ref{history options}.
11982 @c ------------------------------------------------------------
11983 @item import [@var{options}] @var{repository} @var{vendor-tag} @var{release-tags}@dots{}
11984 Import files into @sc{cvs}, using vendor branches. See
11989 Import to vendor branch @var{bra}. See
11990 @ref{Multiple vendor branches}.
11993 Use the file's modification time as the time of
11994 import. See @ref{import options}.
11996 @item -k @var{kflag}
11997 Set default keyword substitution mode. See
11998 @ref{import options}.
12001 Use @var{msg} for log message. See
12002 @ref{import options}.
12005 More files to ignore (! to reset). See
12006 @ref{import options}.
12008 @item -W @var{spec}
12009 More wrappers. See @ref{import options}.
12012 @c ------------------------------------------------------------
12014 Create a @sc{cvs} repository if it doesn't exist. See
12015 @ref{Creating a repository}.
12017 @c ------------------------------------------------------------
12019 Kerberos authenticated server.
12020 See @ref{Kerberos authenticated}.
12022 @c ------------------------------------------------------------
12023 @item log [@var{options}] [@var{files}@dots{}]
12024 Print out history information for files. See @ref{log}.
12028 Only list revisions on the default branch. See @ref{log options}.
12030 @item -d @var{dates}
12031 Specify dates (@var{d1}<@var{d2} for range, @var{d} for
12032 latest before). See @ref{log options}.
12035 Only print header. See @ref{log options}.
12038 Local; run only in current working directory. See @ref{Recursive behavior}.
12041 Do not list tags. See @ref{log options}.
12044 Only print name of RCS file. See @ref{log options}.
12047 Only list revisions @var{revs}. See @ref{log options}.
12049 @item -s @var{states}
12050 Only list revisions with specified states. See @ref{log options}.
12053 Only print header and descriptive text. See @ref{log
12056 @item -w@var{logins}
12057 Only list revisions checked in by specified logins. See @ref{log options}.
12060 @c ------------------------------------------------------------
12062 Prompt for password for authenticating server. See
12063 @ref{Password authentication client}.
12065 @c ------------------------------------------------------------
12067 Remove stored password for authenticating server. See
12068 @ref{Password authentication client}.
12070 @c ------------------------------------------------------------
12072 Password authenticated server.
12073 See @ref{Password authentication server}.
12075 @c ------------------------------------------------------------
12076 @item rannotate [@var{options}] [@var{modules}@dots{}]
12077 Show last revision where each line was modified. See
12081 @item -D @var{date}
12082 Annotate the most recent revision no later than
12083 @var{date}. See @ref{Common options}.
12086 Force annotation of binary files. (Without this option,
12087 binary files are skipped with a message.)
12090 Use head revision if tag/date not found. See
12091 @ref{Common options}.
12094 Local; run only in current working directory. @xref{Recursive behavior}.
12097 Operate recursively (default). @xref{Recursive behavior}.
12100 Annotate revision @var{tag}. See @ref{Common options}.
12103 @c ------------------------------------------------------------
12104 @item rdiff [@var{options}] @var{modules}@dots{}
12105 Show differences between releases. See @ref{rdiff}.
12109 Context diff output format (default). See @ref{rdiff options}.
12111 @item -D @var{date}
12112 Select revisions based on @var{date}. See @ref{Common options}.
12115 Use head revision if tag/date not found. See
12116 @ref{Common options}.
12119 Local; run only in current working directory. See @ref{Recursive behavior}.
12122 Operate recursively (default). @xref{Recursive
12126 Select revisions based on @var{rev}. See @ref{Common options}.
12129 Short patch - one liner per file. See @ref{rdiff options}.
12132 Top two diffs - last change made to the file. See
12133 @ref{diff options}.
12136 Unidiff output format. See @ref{rdiff options}.
12138 @item -V @var{vers}
12139 Use RCS Version @var{vers} for keyword expansion (obsolete). See
12140 @ref{rdiff options}.
12143 @c ------------------------------------------------------------
12144 @item release [@var{options}] @var{directory}
12145 Indicate that a directory is no longer in use. See
12150 Delete the given directory. See @ref{release options}.
12153 @c ------------------------------------------------------------
12154 @item remove [@var{options}] [@var{files}@dots{}]
12155 Remove an entry from the repository. See @ref{Removing files}.
12159 Delete the file before removing it. See @ref{Removing files}.
12162 Local; run only in current working directory. See @ref{Recursive behavior}.
12165 Operate recursively (default). @xref{Recursive
12169 @c ------------------------------------------------------------
12170 @item rlog [@var{options}] [@var{files}@dots{}]
12171 Print out history information for modules. See @ref{log}.
12175 Only list revisions on the default branch. See @ref{log options}.
12177 @item -d @var{dates}
12178 Specify dates (@var{d1}<@var{d2} for range, @var{d} for
12179 latest before). See @ref{log options}.
12182 Only print header. See @ref{log options}.
12185 Local; run only in current working directory. See @ref{Recursive behavior}.
12188 Do not list tags. See @ref{log options}.
12191 Only print name of RCS file. See @ref{log options}.
12194 Only list revisions @var{revs}. See @ref{log options}.
12196 @item -s @var{states}
12197 Only list revisions with specified states. See @ref{log options}.
12200 Only print header and descriptive text. See @ref{log options}.
12202 @item -w@var{logins}
12203 Only list revisions checked in by specified logins. See @ref{log options}.
12206 @c ------------------------------------------------------------
12207 @item rtag [@var{options}] @var{tag} @var{modules}@dots{}
12208 Add a symbolic tag to a module.
12209 See @ref{Revisions} and @ref{Branching and merging}.
12213 Clear tag from removed files that would not otherwise
12214 be tagged. See @ref{Tagging add/remove}.
12217 Create a branch named @var{tag}. See @ref{Branching and merging}.
12220 Used in conjunction with -F or -d, enables movement and deletion of
12221 branch tags. Use with extreme caution.
12223 @item -D @var{date}
12224 Tag revisions as of @var{date}. See @ref{Tagging by date/tag}.
12227 Delete @var{tag}. See @ref{Modifying tags}.
12230 Move @var{tag} if it already exists. See @ref{Modifying tags}.
12233 Force a head revision match if tag/date not found.
12234 See @ref{Tagging by date/tag}.
12237 Local; run only in current working directory. See @ref{Recursive behavior}.
12240 No execution of tag program. See @ref{Common options}.
12243 Operate recursively (default). @xref{Recursive
12247 Tag existing tag @var{rev}. See @ref{Tagging by date/tag}.
12250 @c ------------------------------------------------------------
12252 Rsh server. See @ref{Connecting via rsh}.
12254 @c ------------------------------------------------------------
12255 @item status [@var{options}] @var{files}@dots{}
12256 Display status information in a working directory. See
12261 Local; run only in current working directory. See @ref{Recursive behavior}.
12264 Operate recursively (default). @xref{Recursive
12268 Include tag information for file. See @ref{Tags}.
12271 @c ------------------------------------------------------------
12272 @item tag [@var{options}] @var{tag} [@var{files}@dots{}]
12273 Add a symbolic tag to checked out version of files.
12274 See @ref{Revisions} and @ref{Branching and merging}.
12278 Create a branch named @var{tag}. See @ref{Branching and merging}.
12281 Check that working files are unmodified. See
12282 @ref{Tagging the working directory}.
12284 @item -D @var{date}
12285 Tag revisions as of @var{date}. See @ref{Tagging by date/tag}.
12288 Delete @var{tag}. See @ref{Modifying tags}.
12291 Move @var{tag} if it already exists. See @ref{Modifying tags}.
12294 Force a head revision match if tag/date not found.
12295 See @ref{Tagging by date/tag}.
12298 Local; run only in current working directory. See @ref{Recursive behavior}.
12301 Operate recursively (default). @xref{Recursive
12305 Tag existing tag @var{rev}. See @ref{Tagging by date/tag}.
12308 @c ------------------------------------------------------------
12309 @item unedit [@var{options}] [@var{files}@dots{}]
12310 Undo an edit command. See @ref{Editing files}.
12314 Local; run only in current working directory. See @ref{Recursive behavior}.
12317 Operate recursively (default). @xref{Recursive behavior}.
12320 @c ------------------------------------------------------------
12321 @item update [@var{options}] [@var{files}@dots{}]
12322 Bring work tree in sync with repository. See
12327 Reset any sticky tags/date/options. See @ref{Sticky
12328 tags} and @ref{Keyword substitution}.
12331 Overwrite locally modified files with clean copies from
12332 the repository (the modified file is saved in
12333 @file{.#@var{file}.@var{revision}}, however).
12335 @item -D @var{date}
12336 Check out revisions as of @var{date} (is sticky). See
12337 @ref{Common options}.
12340 Create directories. See @ref{update options}.
12343 Use head revision if tag/date not found. See
12344 @ref{Common options}.
12347 More files to ignore (! to reset). See
12348 @ref{import options}.
12350 @c Probably want to use rev1/rev2 style like for diff
12351 @c -r. Here and in on-line help.
12353 Merge in changes. See @ref{update options}.
12355 @item -k @var{kflag}
12356 Use @var{kflag} keyword expansion. See
12357 @ref{Substitution modes}.
12360 Local; run only in current working directory. @xref{Recursive behavior}.
12363 Prune empty directories. See @ref{Moving directories}.
12366 Check out files to standard output (avoids
12367 stickiness). See @ref{update options}.
12370 Operate recursively (default). @xref{Recursive
12374 Checkout revision @var{tag} (is sticky). See @ref{Common options}.
12376 @item -W @var{spec}
12377 More wrappers. See @ref{import options}.
12380 @c ------------------------------------------------------------
12382 @cindex version (subcommand)
12384 Display the version of @sc{cvs} being used. If the repository
12385 is remote, display both the client and server versions.
12387 @c ------------------------------------------------------------
12388 @item watch [on|off|add|remove] [@var{options}] [@var{files}@dots{}]
12390 on/off: turn on/off read-only checkouts of files. See
12391 @ref{Setting a watch}.
12393 add/remove: add or remove notification on actions. See
12394 @ref{Getting Notified}.
12397 @item -a @var{actions}
12398 Specify actions for temporary watch, where
12399 @var{actions} is @code{edit}, @code{unedit},
12400 @code{commit}, @code{all}, or @code{none}. See
12401 @ref{Editing files}.
12404 Local; run only in current working directory. See @ref{Recursive behavior}.
12407 Operate recursively (default). @xref{Recursive
12411 @c ------------------------------------------------------------
12412 @item watchers [@var{options}] [@var{files}@dots{}]
12413 See who is watching a file. See @ref{Watch information}.
12417 Local; run only in current working directory. See @ref{Recursive behavior}.
12420 Operate recursively (default). @xref{Recursive
12426 @c ---------------------------------------------------------------------
12427 @node Administrative files
12428 @appendix Reference manual for Administrative files
12429 @cindex Administrative files (reference)
12430 @cindex Files, reference manual
12431 @cindex Reference manual (files)
12432 @cindex CVSROOT (file)
12434 Inside the repository, in the directory
12435 @file{$CVSROOT/CVSROOT}, there are a number of
12436 supportive files for @sc{cvs}. You can use @sc{cvs} in a limited
12437 fashion without any of them, but if they are set up
12438 properly they can help make life easier. For a
12439 discussion of how to edit them, see @ref{Intro
12440 administrative files}.
12442 The most important of these files is the @file{modules}
12443 file, which defines the modules inside the repository.
12446 * modules:: Defining modules
12447 * Wrappers:: Specify binary-ness based on file name
12448 * script hooks:: Launch scripts in response to server events
12449 * rcsinfo:: Templates for the log messages
12450 * cvsignore:: Ignoring files via cvsignore
12451 * checkoutlist:: Adding your own administrative files
12452 * history file:: History information
12453 * Variables:: Various variables are expanded
12454 * config:: Miscellaneous CVS configuration
12457 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
12459 @appendixsec The modules file
12460 @cindex Modules (admin file)
12461 @cindex Defining modules (reference manual)
12463 The @file{modules} file records your definitions of
12464 names for collections of source code. @sc{cvs} will
12465 use these definitions if you use @sc{cvs} to update the
12466 modules file (use normal commands like @code{add},
12467 @code{commit}, etc).
12469 The @file{modules} file may contain blank lines and
12470 comments (lines beginning with @samp{#}) as well as
12471 module definitions. Long lines can be continued on the
12472 next line by specifying a backslash (@samp{\}) as the
12473 last character on the line.
12475 There are three basic types of modules: alias modules,
12476 regular modules, and ampersand modules. The difference
12477 between them is the way that they map files in the
12478 repository to files in the working directory. In all
12479 of the following examples, the top-level repository
12480 contains a directory called @file{first-dir}, which
12481 contains two files, @file{file1} and @file{file2}, and a
12482 directory @file{sdir}. @file{first-dir/sdir} contains
12483 a file @file{sfile}.
12485 @c FIXME: should test all the examples in this section.
12488 * Alias modules:: The simplest kind of module
12489 * Regular modules::
12490 * Ampersand modules::
12491 * Excluding directories:: Excluding directories from a module
12492 * Module options:: Regular and ampersand modules can take options
12493 * Module program options:: How the modules ``program options'' programs
12497 @node Alias modules
12498 @appendixsubsec Alias modules
12499 @cindex Alias modules
12500 @cindex -a, in modules file
12502 Alias modules are the simplest kind of module:
12505 @item @var{mname} -a @var{aliases}@dots{}
12506 This represents the simplest way of defining a module
12507 @var{mname}. The @samp{-a} flags the definition as a
12508 simple alias: @sc{cvs} will treat any use of @var{mname} (as
12509 a command argument) as if the list of names
12510 @var{aliases} had been specified instead.
12511 @var{aliases} may contain either other module names or
12512 paths. When you use paths in aliases, @code{checkout}
12513 creates all intermediate directories in the working
12514 directory, just as if the path had been specified
12515 explicitly in the @sc{cvs} arguments.
12518 For example, if the modules file contains:
12521 amodule -a first-dir
12525 then the following two commands are equivalent:
12533 and they each would provide output such as:
12536 cvs checkout: Updating first-dir
12539 cvs checkout: Updating first-dir/sdir
12540 U first-dir/sdir/sfile
12543 @node Regular modules
12544 @appendixsubsec Regular modules
12545 @cindex Regular modules
12548 @item @var{mname} [ options ] @var{dir} [ @var{files}@dots{} ]
12549 In the simplest case, this form of module definition
12550 reduces to @samp{@var{mname} @var{dir}}. This defines
12551 all the files in directory @var{dir} as module mname.
12552 @var{dir} is a relative path (from @code{$CVSROOT}) to a
12553 directory of source in the source repository. In this
12554 case, on checkout, a single directory called
12555 @var{mname} is created as a working directory; no
12556 intermediate directory levels are used by default, even
12557 if @var{dir} was a path involving several directory
12561 For example, if a module is defined by:
12564 regmodule first-dir
12568 then regmodule will contain the files from first-dir:
12572 cvs checkout: Updating regmodule
12575 cvs checkout: Updating regmodule/sdir
12576 U regmodule/sdir/sfile
12580 By explicitly specifying files in the module definition
12581 after @var{dir}, you can select particular files from
12582 directory @var{dir}. Here is
12586 regfiles first-dir/sdir sfile
12590 With this definition, getting the regfiles module
12591 will create a single working directory
12592 @file{regfiles} containing the file listed, which
12593 comes from a directory deeper
12594 in the @sc{cvs} source repository:
12602 @node Ampersand modules
12603 @appendixsubsec Ampersand modules
12604 @cindex Ampersand modules
12605 @cindex &, in modules file
12607 A module definition can refer to other modules by
12608 including @samp{&@var{module}} in its definition.
12610 @var{mname} [ options ] @var{&module}@dots{}
12613 Then getting the module creates a subdirectory for each such
12614 module, in the directory containing the module. For
12615 example, if modules contains
12618 ampermod &first-dir
12622 then a checkout will create an @code{ampermod} directory
12623 which contains a directory called @code{first-dir},
12624 which in turns contains all the directories and files
12625 which live there. For example, the command
12632 will create the following files:
12635 ampermod/first-dir/file1
12636 ampermod/first-dir/file2
12637 ampermod/first-dir/sdir/sfile
12640 There is one quirk/bug: the messages that @sc{cvs}
12641 prints omit the @file{ampermod}, and thus do not
12642 correctly display the location to which it is checking
12647 cvs checkout: Updating first-dir
12650 cvs checkout: Updating first-dir/sdir
12651 U first-dir/sdir/sfile
12655 Do not rely on this buggy behavior; it may get fixed in
12656 a future release of @sc{cvs}.
12658 @c FIXCVS: What happens if regular and & modules are
12659 @c combined, as in "ampermodule first-dir &second-dir"?
12660 @c When I tried it, it seemed to just ignore the
12661 @c "first-dir". I think perhaps it should be an error
12662 @c (but this needs further investigation).
12663 @c In addition to discussing what each one does, we
12664 @c should put in a few words about why you would use one or
12665 @c the other in various situations.
12667 @node Excluding directories
12668 @appendixsubsec Excluding directories
12669 @cindex Excluding directories, in modules file
12670 @cindex !, in modules file
12672 An alias module may exclude particular directories from
12673 other modules by using an exclamation mark (@samp{!})
12674 before the name of each directory to be excluded.
12676 For example, if the modules file contains:
12679 exmodule -a !first-dir/sdir first-dir
12683 then checking out the module @samp{exmodule} will check
12684 out everything in @samp{first-dir} except any files in
12685 the subdirectory @samp{first-dir/sdir}.
12686 @c Note that the "!first-dir/sdir" sometimes must be listed
12687 @c before "first-dir". That seems like a probable bug, in which
12688 @c case perhaps it should be fixed (to allow either
12689 @c order) rather than documented. See modules4 in testsuite.
12691 @node Module options
12692 @appendixsubsec Module options
12693 @cindex Options, in modules file
12695 Either regular modules or ampersand modules can contain
12696 options, which supply additional information concerning
12700 @cindex -d, in modules file
12701 @item -d @var{name}
12702 Name the working directory something other than the
12704 @c FIXME: Needs a bunch of examples, analogous to the
12705 @c examples for alias, regular, and ampersand modules
12706 @c which show where the files go without -d.
12708 @cindex Export program
12709 @cindex -e, in modules file
12710 @item -e @var{prog}
12711 Specify a program @var{prog} to run whenever files in a
12712 module are exported. @var{prog} runs with a single
12713 argument, the module name.
12714 @c FIXME: Is it run on server? client?
12716 @cindex Checkout program
12717 @cindex -o, in modules file
12718 @item -o @var{prog}
12719 Specify a program @var{prog} to run whenever files in a
12720 module are checked out. @var{prog} runs with a single
12721 argument, the module name. See @ref{Module program options} for
12722 information on how @var{prog} is called.
12723 @c FIXME: Is it run on server? client?
12725 @cindex Status of a module
12726 @cindex Module status
12727 @cindex -s, in modules file
12728 @item -s @var{status}
12729 Assign a status to the module. When the module file is
12730 printed with @samp{cvs checkout -s} the modules are
12731 sorted according to primarily module status, and
12732 secondarily according to the module name. This option
12733 has no other meaning. You can use this option for
12734 several things besides status: for instance, list the
12735 person that is responsible for this module.
12737 @cindex Tag program
12738 @cindex -t, in modules file
12739 @item -t @var{prog}
12740 Specify a program @var{prog} to run whenever files in a
12741 module are tagged with @code{rtag}. @var{prog} runs
12742 with two arguments: the module name and the symbolic
12743 tag specified to @code{rtag}. It is not run
12744 when @code{tag} is executed. Generally you will find
12745 that the @file{taginfo} file is a better solution (@pxref{taginfo}).
12746 @c FIXME: Is it run on server? client?
12747 @c Problems with -t include:
12748 @c * It is run after the tag not before
12749 @c * It doesn't get passed all the information that
12750 @c taginfo does ("mov", &c).
12751 @c * It only is run for rtag, not tag.
12754 You should also see @pxref{Module program options} about how the
12755 ``program options'' programs are run.
12757 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
12759 @node Module program options
12760 @appendixsubsec How the modules file ``program options'' programs are run
12761 @cindex Modules file program options
12762 @cindex -t, in modules file
12763 @cindex -o, in modules file
12764 @cindex -e, in modules file
12767 For checkout, rtag, and export, the program is server-based, and as such the
12768 following applies:-
12770 If using remote access methods (pserver, ext, etc.),
12771 @sc{cvs} will execute this program on the server from a temporary
12772 directory. The path is searched for this program.
12774 If using ``local access'' (on a local or remote NFS file system, i.e.
12775 repository set just to a path),
12776 the program will be executed from the newly checked-out tree, if
12777 found there, or alternatively searched for in the path if not.
12779 The programs are all run after the operation has effectively
12783 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
12785 @appendixsec The cvswrappers file
12786 @cindex cvswrappers (admin file)
12787 @cindex CVSWRAPPERS, environment variable
12790 @c FIXME: need some better way of separating this out
12791 @c by functionality. -m is
12792 @c one feature, and -k is a another. And this discussion
12793 @c should be better motivated (e.g. start with the
12794 @c problems, then explain how the feature solves it).
12796 Wrappers refers to a @sc{cvs} feature which lets you
12797 control certain settings based on the name of the file
12798 which is being operated on. The settings are @samp{-k}
12799 for binary files, and @samp{-m} for nonmergeable text
12802 The @samp{-m} option
12803 specifies the merge methodology that should be used when
12804 a non-binary file is updated. @code{MERGE} means the usual
12805 @sc{cvs} behavior: try to merge the files. @code{COPY}
12806 means that @code{cvs update} will refuse to merge
12807 files, as it also does for files specified as binary
12808 with @samp{-kb} (but if the file is specified as
12809 binary, there is no need to specify @samp{-m 'COPY'}).
12810 @sc{cvs} will provide the user with the
12811 two versions of the files, and require the user using
12812 mechanisms outside @sc{cvs}, to insert any necessary
12815 @strong{WARNING: do not use @code{COPY} with
12816 @sc{cvs} 1.9 or earlier - such versions of @sc{cvs} will
12817 copy one version of your file over the other, wiping
12818 out the previous contents.}
12819 @c Ordinarily we don't document the behavior of old
12820 @c versions. But this one is so dangerous, I think we
12821 @c must. I almost renamed it to -m 'NOMERGE' so we
12822 @c could say "never use -m 'COPY'".
12823 The @samp{-m} wrapper option only affects behavior when
12824 merging is done on update; it does not affect how files
12825 are stored. See @ref{Binary files}, for more on
12828 The basic format of the file @file{cvswrappers} is:
12830 @c FIXME: @example is all wrong for this. Use @deffn or
12831 @c something more sensible.
12833 wildcard [option value][option value]...
12835 where option is one of
12836 -m update methodology value: MERGE or COPY
12837 -k keyword expansion value: expansion mode
12839 and value is a single-quote delimited value.
12844 *.nib -f 'unwrap %s' -t 'wrap %s %s' -m 'COPY'
12845 *.c -t 'indent %s %s'
12847 @c When does the filter need to be an absolute pathname
12848 @c and when will something like the above work? I
12849 @c suspect it relates to the PATH of the server (which
12850 @c in turn depends on all kinds of stuff, e.g. inetd
12851 @c for pserver). I'm not sure whether/where to discuss
12853 @c FIXME: What do the %s's stand for?
12856 The above example of a @file{cvswrappers} file
12857 states that all files/directories that end with a @code{.nib}
12858 should be filtered with the @file{wrap} program before
12859 checking the file into the repository. The file should
12860 be filtered though the @file{unwrap} program when the
12861 file is checked out of the repository. The
12862 @file{cvswrappers} file also states that a @code{COPY}
12863 methodology should be used when updating the files in
12864 the repository (that is, no merging should be performed).
12866 @c What pitfalls arise when using indent this way? Is
12867 @c it a winning thing to do? Would be nice to at least
12868 @c hint at those issues; we want our examples to tell
12869 @c how to solve problems, not just to say that cvs can
12870 @c do certain things.
12871 The last example line says that all files that end with
12872 @code{.c} should be filtered with @file{indent}
12873 before being checked into the repository. Unlike the previous
12874 example, no filtering of the @code{.c} file is done when
12875 it is checked out of the repository.
12877 The @code{-t} filter is called with two arguments,
12878 the first is the name of the file/directory to filter
12879 and the second is the pathname to where the resulting
12880 filtered file should be placed.
12883 The @code{-f} filter is called with one argument,
12884 which is the name of the file to filter from. The end
12885 result of this filter will be a file in the users directory
12886 that they can work on as they normally would.
12888 Note that the @samp{-t}/@samp{-f} features do not
12889 conveniently handle one portion of @sc{cvs}'s operation:
12890 determining when files are modified. @sc{cvs} will still
12891 want a file (or directory) to exist, and it will use
12892 its modification time to determine whether a file is
12893 modified. If @sc{cvs} erroneously thinks a file is
12894 unmodified (for example, a directory is unchanged but
12895 one of the files within it is changed), you can force
12896 it to check in the file anyway by specifying the
12897 @samp{-f} option to @code{cvs commit} (@pxref{commit
12899 @c This is, of course, a serious design flaw in -t/-f.
12900 @c Probably the whole functionality needs to be
12901 @c redesigned (starting from requirements) to fix this.
12904 @c FIXME: We don't document -W or point to where it is
12905 @c documented. Or .cvswrappers.
12906 For example, the following command imports a
12907 directory, treating files whose name ends in
12908 @samp{.exe} as binary:
12911 cvs import -I ! -W "*.exe -k 'b'" first-dir vendortag reltag
12914 @c Another good example, would be storing files
12915 @c (e.g. binary files) compressed in the repository.
12916 @c ::::::::::::::::::
12918 @c ::::::::::::::::::
12920 @c *.t[0-9][0-9] -f 'gunzipcp %s' -t 'gzipcp %s %s' -m 'COPY'
12922 @c ::::::::::::::::::
12924 @c ::::::::::::::::::
12926 @c [ -f $1 ] || exit 1
12927 @c zcat $1 > /tmp/.#$1.$$
12928 @c mv /tmp/.#$1.$$ $1
12930 @c ::::::::::::::::::
12932 @c ::::::::::::::::::
12934 @c DIRNAME=`echo $1 | sed -e "s|/.*/||g"`
12935 @c if [ ! -d $DIRNAME ] ; then
12936 @c DIRNAME=`echo $1 | sed -e "s|.*/||g"`
12938 @c gzip -c $DIRNAME > $2
12939 @c One catch--"cvs diff" will not invoke the wrappers
12940 @c (probably a CVS bug, although I haven't thought it out).
12942 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
12944 @appendixsec The scripting hooks
12947 @c Somewhere there needs to be a more "how-to" guide to writing these.
12948 @c One particular issue that people sometimes are worried about is performance,
12949 @c and the impact of writing in perl or sh or ____. Performance comparisons
12950 @c should probably remain outside the scope of this document, but at least
12951 @c _that_ much could be referenced, perhaps with links to other sources.
12953 Script hooks are used to launch external programs at various points during
12954 the execution of @sc{cvs} commands. These hooks can be used to prevent certain
12955 actions, log them, and/or maintain anything else you deem practical.
12958 * syntax:: The common syntax
12960 * commit files:: The commit support files (commitinfo,
12961 verifymsg, loginfo)
12962 * commitinfo:: Pre-commit checking
12963 * verifymsg:: How are log messages evaluated?
12964 * loginfo:: Where should log messages be sent?
12966 * postadmin:: Logging admin commands
12967 * taginfo:: Verifying/Logging tags
12968 * posttag:: Logging tags
12969 * postwatch:: Logging watch commands
12971 * preproxy:: Launch a script on a secondary server prior
12972 to becoming a write proxy
12973 * postproxy:: Launch a script on a secondary server after
12974 completing proxy operations
12977 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
12979 @appendixsubsec The common syntax
12980 @cindex Info files (syntax)
12981 @cindex Syntax of info files
12982 @cindex Common syntax of info files
12984 @c FIXME: having this so totally separate from the
12985 @c Variables node is rather bogus.
12987 The administrative files such as @file{commitinfo},
12988 @file{loginfo}, @file{rcsinfo}, @file{verifymsg}, etc.,
12989 all have a common format. The purpose of the files are
12990 described later on. The common syntax is described
12993 @cindex Regular expression syntax
12994 Each line contains the following:
12997 @cindex @samp{ALL} keyword, in lieu of regular expressions in script hooks
12998 @cindex @samp{DEFAULT} keyword, in lieu of regular expressions in script hooks
13000 A regular expression or the literal string @samp{DEFAULT}. Some script hooks
13001 also support the literal string @samp{ALL}. Other than the @samp{ALL} and
13002 @samp{DEFAULT} keywords, this is a basic regular expression in the syntax used
13003 by GNU emacs. See the descriptions of the individual script hooks for
13004 information on whether the @samp{ALL} keyword is supported
13005 (@pxref{script hooks}).
13006 @c FIXME: What we probably should be saying is "POSIX Basic
13007 @c Regular Expression with the following extensions (`\('
13009 @c rather than define it with reference to emacs.
13010 @c The reference to emacs is not strictly speaking
13011 @c true, as we don't support \=, \s, or \S. Also it isn't
13012 @c clear we should document and/or promise to continue to
13013 @c support all the obscure emacs extensions like \<.
13014 @c Also need to better cite (or include) full
13015 @c documentation for the syntax.
13016 @c Also see comment in configure.in about what happens to the
13017 @c syntax if we pick up a system-supplied regexp matcher.
13020 A whitespace separator---one or more spaces and/or tabs.
13023 A file name or command-line template.
13027 Blank lines are ignored. Lines that start with the
13028 character @samp{#} are treated as comments. Long lines
13029 unfortunately can @emph{not} be broken in two parts in
13032 The first regular expression that matches the current
13033 directory name in the repository or the first line containing @samp{DEFAULT}
13034 in lieu of a regular expression is used and all lines containing @samp{ALL} is
13035 used for the hooks which support the @samp{ALL} keyword. The rest of the line
13036 is used as a file name or command-line template as appropriate. See the
13037 descriptions of the individual script hooks for information on whether the
13038 @samp{ALL} keyword is supported (@pxref{script hooks}).
13040 @cindex format strings
13041 @cindex format strings, common syntax
13042 @cindex Info files, common syntax, format strings
13043 @cindex Common syntax of info files, format strings
13045 @emph{Note: The following information on format strings is valid
13046 as long as the line @code{UseNewInfoFmtStrings=yes} appears in
13047 your repository's config file (@pxref{config}). Otherwise,
13048 default format strings may be appended to the command line and
13049 the @samp{loginfo} file, especially, can exhibit slightly
13050 different behavior. For more information,
13051 @xref{Updating Commit Files}.}
13053 In the cases where the second segment of the matched line is a
13054 command line template (e.g. @file{commitinfo}, @file{loginfo},
13055 & @file{verifymsg}), the command line template may contain format
13056 strings which will be replaced with specific values before the
13058 @c FIXCVS then FIXME - it really would make sense to allow %r & maybe even %p
13059 @c to be used in rcsinfo to construct a path, but I haven't
13062 Format strings can represent a single variable or one or more
13063 attributes of a list variable. An example of a list variable
13064 would be the list available to scripts hung on the loginfo hooks
13065 - the list of files which were just committed. In the case of
13066 loginfo, three attributes are available for each list item: file
13067 name, precommit version, and postcommit version.
13069 Format strings consist of a @samp{%} character followed by an optional
13070 @samp{@{} (required in the multiple list attribute case), a
13071 single format character representing a variable or a single attribute of
13072 list elements or multiple format characters representing attributes of
13073 list elements, and a closing @samp{@}} when the open bracket was present.
13075 @emph{Flat format strings}, or single format characters which get replaced
13076 with a single value, will generate a single argument
13077 to the called script, regardless of whether the replacement variable contains
13078 white space or other special characters.
13080 @emph{List attributes} will generate an argument for each attribute
13081 requested for each list item. For example, @samp{%@{sVv@}}
13082 in a @file{loginfo} command template will generate three
13083 arguments (file name, precommit version, postcommit version,
13084 ...) for each file committed. As in the flat format string
13085 case, each attribute will be passed in as a single argument
13086 regardless of whether it contains white space or other
13087 special characters.
13089 @samp{%%} will be replaced with a literal @samp{%}.
13091 The format strings available to all script hooks are:
13095 The canonical name of the command being executed. For instance, in the case of
13096 a hook run from @code{cvs up}, @sc{cvs} would replace @samp{%c} with the string
13097 @samp{update} and, in the case of a hook run from @code{cvs ci}, @sc{cvs} would
13098 replace @samp{%c} with the string @samp{commit}.
13100 The null, or empty, string.
13102 The name of the directory being operated on within the repository.
13104 The name of the repository (the path portion of @code{$CVSROOT}).
13106 On a server, the name of the referrer, if any. The referrer is the CVSROOT the
13107 client reports it used to contact a server which then referred it to this
13108 server. Should usually be set on a primary server with a write proxy setup.
13111 Other format strings are file specific. See the docs on the
13112 particular script hooks for more information
13113 (@pxref{script hooks}).
13115 As an example, the following line in a @file{loginfo} file would
13116 match only the directory @file{module} and any subdirectories of
13120 ^module\(/\|$\) (echo; echo %p; echo %@{sVv@}; cat) >>$CVSROOT/CVSROOT/commitlog
13123 Using this same line and assuming a commit of new revisions
13124 1.5.4.4 and 1.27.4.1 based on old revisions 1.5.4.3 and 1.27,
13125 respectively, of file1 and file2 in module, something like the
13126 following log message should be appended to commitlog:
13131 file1 1.5.4.3 1.5.4.4 file2 1.27 1.27.4.1
13132 Update of /cvsroot/module
13133 In directory localhost.localdomain:/home/jrandom/work/module
13140 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13142 @appendixsubsec The commit support files
13143 @cindex Commits, administrative support files
13144 @cindex commit files, see Info files
13146 The @samp{-i} flag in the @file{modules} file can be
13147 used to run a certain program whenever files are
13148 committed (@pxref{modules}). The files described in
13149 this section provide other, more flexible, ways to run
13150 programs whenever something is committed.
13152 There are three kinds of programs that can be run on
13153 commit. They are specified in files in the repository,
13154 as described below. The following table summarizes the
13155 file names and the purpose of the corresponding
13160 The program is responsible for checking that the commit
13161 is allowed. If it exits with a non-zero exit status
13162 the commit will be aborted. @xref{commitinfo}.
13165 The specified program is used to evaluate the log message,
13166 and possibly verify that it contains all required
13167 fields. This is most useful in combination with the
13168 @file{rcsinfo} file, which can hold a log message
13169 template (@pxref{rcsinfo}). @xref{verifymsg}.
13172 The specified program is called when the commit is
13173 complete. It receives the log message and some
13174 additional information and can store the log message in
13175 a file, or mail it to appropriate persons, or maybe
13176 post it to a local newsgroup, or@dots{} Your
13177 imagination is the limit! @xref{loginfo}.
13181 * Updating Commit Files:: Updating legacy repositories to stop using
13182 deprecated command line template formats
13185 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13186 @node Updating Commit Files
13187 @appendixsubsubsec Updating legacy repositories to stop using deprecated command line template formats
13188 @cindex Info files (syntax), updating legacy repositories
13189 @cindex Syntax of info files, updating legacy repositories
13190 @cindex Common syntax of info files, updating legacy repositories
13191 New repositories are created set to use the new format strings by default, so
13192 if you are creating a new repository, you shouldn't have to worry about this
13195 If you are attempting to maintain a legacy repository which was
13196 making use of the @file{commitinfo}, @file{editinfo}, @file{verifymsg},
13197 @file{loginfo}, and/or @file{taginfo} script hooks, you should have no
13198 immediate problems with using the current @sc{cvs} executable, but your users
13199 will probably start to see deprecation warnings.
13201 The reason for this is that all of the script hooks have been updated to
13202 use a new command line parser that extensibly supports multiple
13203 @file{loginfo} & @file{notify} style format strings (@pxref{syntax})
13204 and this support is not completely compatible with the old style format
13207 The quick upgrade method is to stick a @samp{1} after each format string
13208 in your old @file{loginfo} file. For example:
13211 DEFAULT (echo ""; id; echo %@{sVv@}; date; cat) >> $CVSROOT/CVSROOT/commitlog
13217 DEFAULT (echo ""; id; echo %1@{sVv@}; date; cat) >> $CVSROOT/CVSROOT/commitlog
13220 If you were counting on the fact that only the first @samp{%} in the line was
13221 replaced as a format string, you may also have to double up any further
13222 percent signs on the line.
13224 If you did this all at once and checked it in, everything should still be
13227 Now add the following line to your config file (@pxref{config}):
13229 UseNewInfoFmtStrings=yes
13232 Everything should still be running properly, but your users will probably
13233 start seeing new deprecation warnings.
13235 Dealing with the deprecation warnings now generated by @file{commitinfo},
13236 @file{editinfo}, @file{verifymsg}, and @file{taginfo} should be easy. Simply
13237 specify what are currently implicit arguments explicitly. This means appending
13238 the following strings to each active command line template in each file:
13245 @samp{ %t %o %p %@{sv@}}
13250 If you don't desire that any of the newly available information be passed to
13251 the scripts hanging off of these hooks, no further modifications to these
13252 files should be necessary to insure current and future compatibility with
13253 @sc{cvs}'s format strings.
13255 Fixing @file{loginfo} could be a little tougher. The old style
13256 @file{loginfo} format strings caused a single space and comma separated
13257 argument to be passed in in place of the format string. This is what will
13258 continue to be generated due to the deprecated @samp{1} you inserted into
13259 the format strings.
13261 Since the new format separates each individual item and passes it into the
13262 script as a separate argument (for a good reason - arguments containing commas
13263 and/or white space are now parsable), to remove the deprecated @samp{1} from
13264 your @file{loginfo} command line templates, you will most likely have to
13265 rewrite any scripts called by the hook to handle the new argument format.
13267 Also note that the way @samp{%} followed by unrecognized characters and by
13268 @samp{@{@}} was treated in past versions of CVS is not strictly adhered to as
13269 there were bugs in the old versions. Specifically, @samp{%@{@}} would eat the
13270 next character and unrecognized strings resolved only to the empty string,
13271 which was counter to what was stated in the documentation. This version will
13272 do what the documentation said it should have (if you were using only some
13273 combination of @samp{%@{sVv@}}, e.g. @samp{%@{sVv@}}, @samp{%@{sV@}}, or
13274 @samp{%v}, you should have no troubles).
13276 On the bright side, you should have plenty of time to do this before all
13277 support for the old format strings is removed from @sc{cvs}, so you can just
13278 put up with the deprecation warnings for awhile if you like.
13280 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
13282 @appendixsubsec Commitinfo
13283 @cindex @file{commitinfo}
13284 @cindex Commits, precommit verification of
13285 @cindex commitinfo (admin file)
13286 @cindex Info files, commitinfo
13287 @cindex Info files, precommit verification of commits
13289 The @file{commitinfo} file defines programs to execute
13290 whenever @samp{cvs commit} is about to execute. These
13291 programs are used for pre-commit checking to verify
13292 that the modified, added and removed files are really
13293 ready to be committed. This could be used, for
13294 instance, to verify that the changed files conform to
13295 to your site's standards for coding practice.
13297 The @file{commitinfo} file has the standard form for script hooks
13298 (@pxref{script hooks}), where each line is a regular expression followed by a
13299 command to execute. It supports only the DEFAULT keywords.
13301 @cindex format strings, commitinfo admin file
13302 In addition to the common format strings (@pxref{syntax}),
13303 @file{commitinfo} supports:
13307 a list of the names of files to be committed
13310 @cindex commitinfo (admin file), updating legacy repositories
13311 @cindex compatibility notes, commitinfo admin file
13312 Currently, if no format strings are specified, a default
13313 string of @samp{ %r/%p %@{s@}} will be appended to the command
13314 line template before replacement is performed, but this
13315 feature is deprecated. It is simply in place so that legacy
13316 repositories will remain compatible with the new @sc{cvs} application.
13317 For information on updating, @pxref{Updating Commit Files}.
13319 @cindex Exit status, of commitinfo
13320 @cindex commitinfo (admin file), exit status
13321 The first line with a regular expression matching the
13322 directory within the repository will be used. If the
13323 command returns a non-zero exit status the commit will
13325 @c FIXME: need example(s) of what "directory within the
13326 @c repository" means.
13328 @cindex @file{commitinfo}, working directory
13329 @cindex @file{commitinfo}, command environment
13330 The command will be run in the root of the workspace
13331 containing the new versions of any files the user would like
13332 to modify (commit), @emph{or in a copy of the workspace on
13333 the server (@pxref{Remote repositories})}. If a file is
13334 being removed, there will be no copy of the file under the
13335 current directory. If a file is being added, there will be
13336 no corresponding archive file in the repository unless the
13337 file is being resurrected.
13339 Note that both the repository directory and the corresponding
13340 Attic (@pxref{Attic}) directory may need to be checked to
13341 locate the archive file corresponding to any given file being
13342 committed. Much of the information about the specific commit
13343 request being made, including the destination branch, commit
13344 message, and command line options specified, is not available
13347 @c FIXME: should discuss using commitinfo to control
13348 @c who has checkin access to what (e.g. Joe can check into
13349 @c directories a, b, and c, and Mary can check into
13350 @c directories b, c, and d--note this case cannot be
13351 @c conveniently handled with unix groups). Of course,
13352 @c adding a new set of features to CVS might be a more
13353 @c natural way to fix this problem than telling people to
13355 @c FIXME: Should make some reference, especially in
13356 @c the context of controlling who has access, to the fact
13357 @c that commitinfo can be circumvented. Perhaps
13358 @c mention SETXID (but has it been carefully examined
13359 @c for holes?). This fits in with the discussion of
13360 @c general CVS security in "Password authentication
13361 @c security" (the bit which is not pserver-specific).
13363 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
13365 @appendixsubsec Verifying log messages
13366 @cindex @file{verifymsg} (admin file)
13367 @cindex Log message, verifying
13368 @cindex logging, commits
13370 Once you have entered a log message, you can evaluate
13371 that message to check for specific content, such as
13372 a bug ID. Use the @file{verifymsg} file to
13373 specify a program that is used to verify the log message.
13374 This program could be a simple script that checks
13375 that the entered message contains the required fields.
13377 The @file{verifymsg} file is often most useful together
13378 with the @file{rcsinfo} file, which can be used to
13379 specify a log message template (@pxref{rcsinfo}).
13381 The @file{verifymsg} file has the standard form for script hooks
13382 (@pxref{script hooks}), where each line is a regular expression followed by a
13383 command to execute. It supports only the DEFAULT keywords.
13385 @cindex format strings, verifymsg admin file
13386 In addition to the common format strings (@pxref{syntax}),
13387 @file{verifymsg} supports:
13391 the full path to the file containing the log message to be verified
13394 @cindex verifymsg (admin/commit file), updating legacy repositories
13395 @cindex compatibility notes, verifymsg admin file
13396 Currently, if no format strings are specified, a default
13397 string of @samp{ %l} will be appended to the command
13398 line template before replacement is performed, but this
13399 feature is deprecated. It is simply in place so that legacy
13400 repositories will remain compatible with the new @sc{cvs} application.
13401 For information on updating, @pxref{Updating Commit Files}.
13403 One thing that should be noted is that the @samp{ALL}
13404 keyword is not supported. If more than one matching
13405 line is found, the first one is used. This can be
13406 useful for specifying a default verification script in a
13407 directory, and then overriding it in a subdirectory.
13409 @cindex Exit status, of @file{verifymsg}
13410 If the verification script exits with a non-zero exit status,
13411 the commit is aborted.
13413 @cindex @file{verifymsg}, changing the log message
13414 In the default configuration, CVS allows the
13415 verification script to change the log message. This is
13416 controlled via the RereadLogAfterVerify CVSROOT/config
13419 When @samp{RereadLogAfterVerify=always} or
13420 @samp{RereadLogAfterVerify=stat}, the log message will
13421 either always be reread after the verification script
13422 is run or reread only if the log message file status
13425 @xref{config}, for more on CVSROOT/config options.
13427 It is NOT a good idea for a @file{verifymsg} script to
13428 interact directly with the user in the various
13429 client/server methods. For the @code{pserver} method,
13430 there is no protocol support for communicating between
13431 @file{verifymsg} and the client on the remote end. For the
13432 @code{ext} and @code{server} methods, it is possible
13433 for CVS to become confused by the characters going
13434 along the same channel as the CVS protocol
13435 messages. See @ref{Remote repositories}, for more
13436 information on client/server setups. In addition, at the time
13437 the @file{verifymsg} script runs, the CVS
13438 server has locks in place in the repository. If control is
13439 returned to the user here then other users may be stuck waiting
13440 for access to the repository.
13442 This option can be useful if you find yourself using an
13443 rcstemplate that needs to be modified to remove empty
13444 elements or to fill in default values. It can also be
13445 useful if the rcstemplate has changed in the repository
13446 and the CVS/Template was not updated, but is able to be
13447 adapted to the new format by the verification script
13448 that is run by @file{verifymsg}.
13450 An example of an update might be to change all
13451 occurrences of 'BugId:' to be 'DefectId:' (which can be
13452 useful if the rcstemplate has recently been changed and
13453 there are still checked-out user trees with cached
13454 copies in the CVS/Template file of the older version).
13456 Another example of an update might be to delete a line
13457 that contains 'BugID: none' from the log message after
13458 validation of that value as being allowed is made.
13461 * verifymsg example:: Verifymsg example
13464 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13465 @node verifymsg example
13466 @appendixsubsubsec Verifying log messages
13467 @cindex verifymsg, example
13468 The following is a little silly example of a
13469 @file{verifymsg} file, together with the corresponding
13470 @file{rcsinfo} file, the log message template and a
13471 verification script. We begin with the log message template.
13472 We want to always record a bug-id number on the first
13473 line of the log message. The rest of log message is
13474 free text. The following template is found in the file
13475 @file{/usr/cvssupport/tc.template}.
13481 The script @file{/usr/cvssupport/bugid.verify} is used to
13482 evaluate the log message.
13487 # bugid.verify filename
13489 # Verify that the log message contains a valid bugid
13490 # on the first line.
13492 if sed 1q < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then
13494 elif sed 1q < $1 | grep '^BugId:[ ]*none$' > /dev/null; then
13495 # It is okay to allow commits with 'BugId: none',
13496 # but do not put that text into the real log message.
13497 grep -v '^BugId:[ ]*none$' > $1.rewrite
13501 echo "No BugId found."
13506 The @file{verifymsg} file contains this line:
13509 ^tc /usr/cvssupport/bugid.verify %l
13512 The @file{rcsinfo} file contains this line:
13515 ^tc /usr/cvssupport/tc.template
13518 The @file{config} file contains this line:
13521 RereadLogAfterVerify=always
13526 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
13528 @appendixsubsec Loginfo
13529 @cindex loginfo (admin file)
13530 @cindex logging, commits
13531 @cindex Storing log messages
13532 @cindex Mailing log messages
13533 @cindex Distributing log messages
13534 @cindex Log messages
13536 The @file{loginfo} file is used to control where log information is sent after
13537 versioned changes are made to repository archive files and after directories
13538 are added ot the repository. @ref{posttag} for how to log tagging
13539 information and @ref{postadmin} for how to log changes due to the @code{admin}
13542 The @file{loginfo} file has the standard form for script hooks
13543 (@pxref{script hooks}), where each line is a regular expression followed by a
13544 command to execute. It supports the ALL and DEFAULT keywords.
13546 Any specified scripts are called:
13550 Once per directory, immediately after a successfully completing the commit of
13551 all files within that directory.
13553 Once per import, immediately after completion of all write operations.
13555 Immediately after the successful @code{add} of a directory.
13558 Any script called via @file{loginfo} will be fed the log information on its
13559 standard input. Note that the filter program @strong{must} read @strong{all}
13560 of the log information from its standard input or @sc{cvs} may fail with a
13561 broken pipe signal.
13563 @cindex format strings, loginfo admin file
13564 In addition to the common format strings (@pxref{syntax}),
13565 @file{loginfo} supports:
13569 File attributes, where:
13574 old version number (pre-checkin)
13576 new version number (post-checkin)
13580 For example, some valid format strings are @samp{%%},
13581 @samp{%s}, @samp{%@{s@}}, and @samp{%@{sVv@}}.
13583 @cindex loginfo (admin file), updating legacy repositories
13584 @cindex compatibility notes, loginfo admin file
13585 Currently, if @samp{UseNewInfoFmtStrings} is not set in the @file{config}
13586 administration file (@pxref{config}), the format strings will be substituted
13587 as they were in past versions of @sc{cvs}, but this feature is deprecated.
13588 It is simply in place so that legacy repositories will remain compatible with
13589 the new @sc{cvs} application. For information on updating,
13590 please see @ref{Updating Commit Files}.
13592 As an example, if @samp{/u/src/master/yoyodyne/tc} is the repository, @samp{%p}
13593 and @samp{%@{sVv@}} are the format strings, and three files (@t{ChangeLog},
13594 @t{Makefile}, @t{foo.c}) were modified, the output might be:
13597 yoyodyne/tc ChangeLog 1.1 1.2 Makefile 1.3 1.4 foo.c 1.12 1.13
13600 Note: when @sc{cvs} is accessing a remote repository,
13601 @file{loginfo} will be run on the @emph{remote}
13602 (i.e., server) side, not the client side (@pxref{Remote
13606 * loginfo example:: Loginfo example
13607 * Keeping a checked out copy:: Updating a tree on every checkin
13610 @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13611 @node loginfo example
13612 @appendixsubsubsec Loginfo example
13614 The following @file{loginfo} file, together with the
13615 tiny shell-script below, appends all log messages
13616 to the file @file{$CVSROOT/CVSROOT/commitlog},
13617 and any commits to the administrative files (inside
13618 the @file{CVSROOT} directory) are also logged in
13619 @file{/usr/adm/cvsroot-log}.
13620 Commits to the @file{prog1} directory are mailed to @t{ceder}.
13622 @c FIXME: is it a CVS feature or bug that only the
13623 @c first matching line is used? It is documented
13624 @c above, but is it useful? For example, if we wanted
13625 @c to run both "cvs-log" and "Mail" for the CVSROOT
13626 @c directory, it is kind of awkward if
13627 @c only the first matching line is used.
13629 ALL /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog $USER
13630 ^CVSROOT\(/\|$\) /usr/local/bin/cvs-log /usr/adm/cvsroot-log $USER
13631 ^prog1\(/\|$\) Mail -s "%p %s" ceder
13634 The shell-script @file{/usr/local/bin/cvs-log} looks
13639 (echo "------------------------------------------------------";
13648 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
13649 @node Keeping a checked out copy
13650 @appendixsubsubsec Keeping a checked out copy
13652 @c What other index entries? It seems like
13653 @c people might want to use a lot of different
13654 @c words for this functionality.
13655 @cindex Keeping a checked out copy
13656 @cindex Checked out copy, keeping
13657 @cindex Web pages, maintaining with CVS
13659 It is often useful to maintain a directory tree which
13660 contains files which correspond to the latest version
13661 in the repository. For example, other developers might
13662 want to refer to the latest sources without having to
13663 check them out, or you might be maintaining a web site
13664 with @sc{cvs} and want every checkin to cause the files
13665 used by the web server to be updated.
13666 @c Can we offer more details on the web example? Or
13667 @c point the user at how to figure it out? This text
13668 @c strikes me as sufficient for someone who already has
13669 @c some idea of what we mean but not enough for the naive
13670 @c user/sysadmin to understand it and set it up.
13672 The way to do this is by having loginfo invoke
13673 @code{cvs update}. Doing so in the naive way will
13674 cause a problem with locks, so the @code{cvs update}
13675 must be run in the background.
13676 @c Should we try to describe the problem with locks?
13677 @c It seems like a digression for someone who just
13678 @c wants to know how to make it work.
13679 @c Another choice which might work for a single file
13680 @c is to use "cvs -n update -p" which doesn't take
13681 @c out locks (I think) but I don't see many advantages
13682 @c of that and we might as well document something which
13683 @c works for multiple files.
13684 Here is an example for unix (this should all be on one line):
13687 ^cyclic-pages\(/\|$\) (date; cat; (sleep 2; cd /u/www/local-docs;
13688 cvs -q update -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1
13691 This will cause checkins to repository directory @code{cyclic-pages}
13692 and its subdirectories to update the checked
13693 out tree in @file{/u/www/local-docs}.
13694 @c More info on some of the details? The "sleep 2" is
13695 @c so if we are lucky the lock will be gone by the time
13696 @c we start and we can wait 2 seconds instead of 30.
13700 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
13702 @appendixsubsec Logging admin commands
13703 @cindex postadmin (admin file)
13704 @cindex script hook, postadmin
13705 @cindex Admin commands, logging
13707 The @file{postadmin} file defines programs to execute after an @code{admin}
13708 command modifies files. The @file{postadmin} file has the standard form
13709 for script hooks (@pxref{script hooks}), where each line is a regular
13710 expression followed by a command to execute. It supports the ALL and DEFAULT
13713 @cindex format strings, postadmin admin file
13714 The @file{postadmin} file supports no format strings other than the common
13715 ones (@pxref{syntax}),
13719 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
13721 @appendixsubsec Taginfo
13722 @cindex taginfo (admin file)
13723 @cindex script hook, taginfo
13724 @cindex Tags, logging
13725 @cindex Tags, verifying
13726 The @file{taginfo} file defines programs to execute
13727 when someone executes a @code{tag} or @code{rtag}
13728 command. The @file{taginfo} file has the standard form
13729 for script hooks (@pxref{script hooks}), where each line
13730 is a regular expression followed by a command to execute.
13731 It supports the ALL and DEFAULT keywords.
13733 @cindex format strings, taginfo admin file
13734 In addition to the common format strings (@pxref{syntax}),
13735 @file{taginfo} supports:
13739 tag type (@code{T} for branch, @code{N} for not-branch, or @code{?} for
13740 unknown, as during delete operations)
13742 operation (@code{add} for @code{tag}, @code{mov} for @code{tag -F}, or
13743 @code{del} for @code{tag -d})
13747 file attributes, where:
13752 old version number (for a move or delete operation)
13754 new version number (for an add or move operation)
13758 For example, some valid format strings are @samp{%%}, @samp{%p}, @samp{%t},
13759 @samp{%s}, @samp{%@{s@}}, and @samp{%@{sVv@}}.
13761 @cindex taginfo (admin file), updating legacy repositories
13762 @cindex compatibility notes, taginfo admin file
13763 Currently, if no format strings are specified, a default
13764 string of @samp{ %t %o %p %@{sv@}} will be appended to the command
13765 line template before replacement is performed, but this
13766 feature is deprecated. It is simply in place so that legacy
13767 repositories will remain compatible with the new @sc{cvs} application.
13768 For information on updating, @pxref{Updating Commit Files}.
13770 @cindex Exit status, of taginfo admin file
13771 @cindex taginfo (admin file), exit status
13772 A non-zero exit of the filter program will cause the tag to be
13775 Here is an example of using @file{taginfo} to log @code{tag} and @code{rtag}
13776 commands. In the @file{taginfo} file put:
13779 ALL /usr/local/cvsroot/CVSROOT/loggit %t %b %o %p %@{sVv@}
13783 Where @file{/usr/local/cvsroot/CVSROOT/loggit} contains the
13788 echo "$@@" >>/home/kingdon/cvsroot/CVSROOT/taglog
13793 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
13795 @appendixsubsec Logging tags
13796 @cindex posttag (admin file)
13797 @cindex script hook, posttag
13798 @cindex Tags, logging
13800 The @file{posttag} file defines programs to execute after a @code{tag} or
13801 @code{rtag} command modifies files. The @file{posttag} file has the standard
13802 form for script hooks (@pxref{script hooks}), where each line is a regular
13803 expression followed by a command to execute. It supports the ALL and DEFAULT
13806 @cindex format strings, posttag admin file
13807 The @file{posttag} admin file supports the same format strings as the
13808 @file{taginfo} file (@pxref{taginfo}),
13812 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
13814 @appendixsubsec Logging watch commands
13815 @cindex postwatch (admin file)
13816 @cindex script hook, postwatch
13817 @cindex Watch family of commands, logging
13819 The @file{postwatch} file defines programs to execute after any command (for
13820 instance, @code{watch}, @code{edit}, @code{unedit}, or @code{commit}) modifies
13821 any @file{CVS/fileattr} file in the repository (@pxref{Watches}). The
13822 @file{postwatch} file has the standard form for script hooks
13823 (@pxref{script hooks}), where each line is a regular expression followed by a
13824 command to execute. It supports the ALL and DEFAULT keywords.
13826 @cindex format strings, postwatch admin file
13827 The @file{postwatch} file supports no format strings other than the common
13828 ones (@pxref{syntax}), but it is worth noting that the @code{%c} format string
13829 may not be replaced as you might expect. Client runs of @code{edit} and
13830 @code{unedit} can sometimes skip contacting the @sc{cvs} server and cache the
13831 notification of the file attribute change to be sent the next time the client
13832 contacts the server for whatever other reason,
13836 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
13838 @appendixsubsec Launch a Script before Proxying
13839 @cindex preproxy (admin file)
13840 @cindex script hook, preproxy
13841 @cindex Write proxy, verifying
13842 @cindex Write proxy, logging
13844 The @file{preproxy} file defines programs to execute after a secondary
13845 server receives a write request from a client, just before it starts up the
13846 primary server and becomes a write proxy. This hook could be used to
13847 dial a modem, launch an SSH tunnel, establish a VPN, or anything else that
13848 might be necessary to do before contacting the primary server.
13850 @file{preproxy} scripts are called once, at the time of the write request, with
13851 the repository argument (if requested) set from the topmost directory sent by
13854 The @file{preproxy} file has the standard form
13855 for script hooks (@pxref{script hooks}), where each line is a regular
13856 expression followed by a command to execute. It supports the ALL and DEFAULT
13859 @cindex format strings, preproxy admin file
13860 In addition to the common format strings, the @file{preproxy} file supports the
13861 following format string:
13865 the CVSROOT string which specifies the primary server
13870 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
13872 @appendixsubsec Launch a Script after Proxying
13873 @cindex postproxy (admin file)
13874 @cindex script hook, postproxy
13875 @cindex Write proxy, logging
13876 @cindex Write proxy, pull updates
13877 @cindex secondary server, pull updates
13879 The @file{postproxy} file defines programs to execute after a secondary
13880 server notes that the connection to the primary server has shut down and before
13881 it releases the client by shutting down the connection to the client.
13882 This could hook could be used to
13883 disconnect a modem, an SSH tunnel, a VPN, or anything else that
13884 might be necessary to do after contacting the primary server. This hook should
13885 also be used to pull updates from the primary server before allowing the client
13886 which did the write to disconnect since otherwise the client's next read
13887 request may generate error messages and fail upon encountering an out of date
13888 repository on the secondary server.
13890 @file{postproxy} scripts are called once per directory.
13892 The @file{postproxy} file has the standard form
13893 for script hooks (@pxref{script hooks}), where each line is a regular
13894 expression followed by a command to execute. It supports the ALL and DEFAULT
13897 @cindex format strings, postproxy admin file
13898 In addition to the common format strings, the @file{postproxy} file supports
13899 the following format string:
13903 the CVSROOT string which specifies the primary server
13908 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
13910 @appendixsec Rcsinfo
13911 @cindex rcsinfo (admin file)
13912 @cindex Form for log message
13913 @cindex Log message template
13914 @cindex Template for log message
13915 @cindex logging, commits
13917 The @file{rcsinfo} file can be used to specify a form to
13918 edit when filling out the commit log. The
13919 @file{rcsinfo} file has a syntax similar to the
13920 @file{verifymsg}, @file{commitinfo} and @file{loginfo}
13921 files. @xref{syntax}. Unlike the other files the second
13922 part is @emph{not} a command-line template. Instead,
13923 the part after the regular expression should be a full pathname to
13924 a file containing the log message template.
13926 If the repository name does not match any of the
13927 regular expressions in this file, the @samp{DEFAULT}
13928 line is used, if it is specified.
13930 All occurrences of the name @samp{ALL} appearing as a
13931 regular expression are used in addition to the first
13932 matching regular expression or @samp{DEFAULT}.
13934 @c FIXME: should be offering advice, somewhere around
13935 @c here, about where to put the template file. The
13936 @c verifymsg example uses /usr/cvssupport but doesn't
13937 @c say anything about what that directory is for or
13938 @c whether it is hardwired into CVS or who creates
13939 @c it or anything. In particular we should say
13940 @c how to version control the template file. A
13941 @c probably better answer than the /usr/cvssupport
13942 @c stuff is to use checkoutlist (with xref to the
13943 @c checkoutlist doc).
13944 @c Also I am starting to see a connection between
13945 @c this and the Keeping a checked out copy node.
13946 @c Probably want to say something about that.
13947 The log message template will be used as a default log
13948 message. If you specify a log message with @samp{cvs
13949 commit -m @var{message}} or @samp{cvs commit -f
13950 @var{file}} that log message will override the
13953 @xref{verifymsg}, for an example @file{rcsinfo}
13956 When @sc{cvs} is accessing a remote repository,
13957 the contents of @file{rcsinfo} at the time a directory
13958 is first checked out will specify a template. This
13959 template will be updated on all @samp{cvs update}
13960 commands. It will also be added to new directories
13961 added with a @samp{cvs add new-directory} command.
13962 In versions of @sc{cvs} prior to version 1.12, the
13963 @file{CVS/Template} file was not updated. If the
13964 @sc{cvs} server is at version 1.12 or higher an older
13965 client may be used and the @file{CVS/Template} will
13966 be updated from the server.
13970 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
13972 @appendixsec Ignoring files via cvsignore
13973 @cindex cvsignore (admin file), global
13974 @cindex Global cvsignore
13975 @cindex Ignoring files
13976 @c -- This chapter should maybe be moved to the
13977 @c tutorial part of the manual?
13979 There are certain file names that frequently occur
13980 inside your working copy, but that you don't want to
13981 put under @sc{cvs} control. Examples are all the object
13982 files that you get while you compile your sources.
13983 Normally, when you run @samp{cvs update}, it prints a
13984 line for each file it encounters that it doesn't know
13985 about (@pxref{update output}).
13987 @sc{cvs} has a list of files (or sh(1) file name patterns)
13988 that it should ignore while running @code{update},
13989 @code{import} and @code{release}.
13990 @c -- Are those the only three commands affected?
13991 This list is constructed in the following way.
13995 The list is initialized to include certain file name
13996 patterns: names associated with @sc{cvs}
13997 administration, or with other common source control
13998 systems; common names for patch files, object files,
13999 archive files, and editor backup files; and other names
14000 that are usually artifacts of assorted utilities.
14001 Currently, the default list of ignored file name
14004 @cindex Ignored files
14005 @cindex Automatically ignored files
14007 RCS SCCS CVS CVS.adm
14010 .make.state .nse_depinfo
14011 *~ #* .#* ,* _$* *$
14012 *.old *.bak *.BAK *.orig *.rej .del-*
14013 *.a *.olb *.o *.obj *.so *.exe
14019 The per-repository list in
14020 @file{$CVSROOT/CVSROOT/cvsignore} is appended to
14021 the list, if that file exists.
14024 The per-user list in @file{.cvsignore} in your home
14025 directory is appended to the list, if it exists.
14028 Any entries in the environment variable
14029 @code{$CVSIGNORE} is appended to the list.
14032 Any @samp{-I} options given to @sc{cvs} is appended.
14035 As @sc{cvs} traverses through your directories, the contents
14036 of any @file{.cvsignore} will be appended to the list.
14037 The patterns found in @file{.cvsignore} are only valid
14038 for the directory that contains them, not for
14039 any sub-directories.
14042 In any of the 5 places listed above, a single
14043 exclamation mark (@samp{!}) clears the ignore list.
14044 This can be used if you want to store any file which
14045 normally is ignored by @sc{cvs}.
14047 Specifying @samp{-I !} to @code{cvs import} will import
14048 everything, which is generally what you want to do if
14049 you are importing files from a pristine distribution or
14050 any other source which is known to not contain any
14051 extraneous files. However, looking at the rules above
14052 you will see there is a fly in the ointment; if the
14053 distribution contains any @file{.cvsignore} files, then
14054 the patterns from those files will be processed even if
14055 @samp{-I !} is specified. The only workaround is to
14056 remove the @file{.cvsignore} files in order to do the
14057 import. Because this is awkward, in the future
14058 @samp{-I !} might be modified to override
14059 @file{.cvsignore} files in each directory.
14061 Note that the syntax of the ignore files consists of a
14062 series of lines, each of which contains a space
14063 separated list of filenames. This offers no clean way
14064 to specify filenames which contain spaces, but you can
14065 use a workaround like @file{foo?bar} to match a file
14066 named @file{foo bar} (it also matches @file{fooxbar}
14067 and the like). Also note that there is currently no
14068 way to specify comments.
14069 @c FIXCVS? I don't _like_ this syntax at all, but
14070 @c changing it raises all the usual compatibility
14071 @c issues and I'm also not sure what to change it to.
14074 @appendixsec The checkoutlist file
14075 @cindex checkoutlist
14077 It may be helpful to use @sc{cvs} to maintain your own
14078 files in the @file{CVSROOT} directory. For example,
14079 suppose that you have a script @file{logcommit.pl}
14080 which you run by including the following line in the
14081 @file{commitinfo} administrative file:
14084 ALL $CVSROOT/CVSROOT/logcommit.pl %r/%p %s
14087 To maintain @file{logcommit.pl} with @sc{cvs} you would
14088 add the following line to the @file{checkoutlist}
14089 administrative file:
14095 The format of @file{checkoutlist} is one line for each
14096 file that you want to maintain using @sc{cvs}, giving
14097 the name of the file, followed optionally by more whitespace
14098 and any error message that should print if the file cannot be
14099 checked out into CVSROOT after a commit:
14102 logcommit.pl Could not update CVSROOT/logcommit.pl.
14105 After setting up @file{checkoutlist} in this fashion,
14106 the files listed there will function just like
14107 @sc{cvs}'s built-in administrative files. For example,
14108 when checking in one of the files you should get a
14112 cvs commit: Rebuilding administrative file database
14116 and the checked out copy in the @file{CVSROOT}
14117 directory should be updated.
14119 Note that listing @file{passwd} (@pxref{Password
14120 authentication server}) in @file{checkoutlist} is not
14121 recommended for security reasons.
14123 For information about keeping a checkout out copy in a
14124 more general context than the one provided by
14125 @file{checkoutlist}, see @ref{Keeping a checked out
14128 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
14130 @appendixsec The history file
14131 @cindex History file
14132 @cindex Log information, saving
14134 The file @file{$CVSROOT/CVSROOT/history} is used
14135 to log information for the @code{history} command
14136 (@pxref{history}). This file must be created to turn
14137 on logging. This is done automatically if the
14138 @code{cvs init} command is used to set up the
14139 repository (@pxref{Creating a repository}).
14141 The file format of the @file{history} file is
14142 documented only in comments in the @sc{cvs} source
14143 code, but generally programs should use the @code{cvs
14144 history} command to access it anyway, in case the
14145 format changes with future releases of @sc{cvs}.
14148 @appendixsec Expansions in administrative files
14149 @cindex Internal variables
14152 Sometimes in writing an administrative file, you might
14153 want the file to be able to know various things based
14154 on environment @sc{cvs} is running in. There are
14155 several mechanisms to do that.
14157 To find the home directory of the user running @sc{cvs}
14158 (from the @code{HOME} environment variable), use
14159 @samp{~} followed by @samp{/} or the end of the line.
14160 Likewise for the home directory of @var{user}, use
14161 @samp{~@var{user}}. These variables are expanded on
14162 the server machine, and don't get any reasonable
14163 expansion if pserver (@pxref{Password authenticated})
14164 is in use; therefore user variables (see below) may be
14165 a better choice to customize behavior based on the user
14167 @c Based on these limitations, should we deprecate ~?
14168 @c What is it good for? Are people using it?
14170 One may want to know about various pieces of
14171 information internal to @sc{cvs}. A @sc{cvs} internal
14172 variable has the syntax @code{$@{@var{variable}@}},
14173 where @var{variable} starts with a letter and consists
14174 of alphanumeric characters and @samp{_}. If the
14175 character following @var{variable} is a
14176 non-alphanumeric character other than @samp{_}, the
14177 @samp{@{} and @samp{@}} can be omitted. The @sc{cvs}
14178 internal variables are:
14182 @cindex CVSROOT, internal variable
14183 This is the absolute path to the current @sc{cvs} root directory.
14184 @xref{Repository}, for a description of the various
14185 ways to specify this, but note that the internal
14186 variable contains just the directory and not any
14187 of the access method information.
14190 @cindex RCSBIN, internal variable
14191 In @sc{cvs} 1.9.18 and older, this specified the
14192 directory where @sc{cvs} was looking for @sc{rcs}
14193 programs. Because @sc{cvs} no longer runs @sc{rcs}
14194 programs, specifying this internal variable is now an
14198 @cindex CVSEDITOR, internal variable
14200 @cindex EDITOR, internal variable
14202 @cindex VISUAL, internal variable
14203 These all expand to the same value, which is the editor
14204 that @sc{cvs} is using. @xref{Global options}, for how
14208 @cindex USER, internal variable
14209 Username of the user running @sc{cvs} (on the @sc{cvs}
14211 When using pserver, this is the user specified in the repository
14212 specification which need not be the same as the username the
14213 server is running as (@pxref{Password authentication server}).
14214 Do not confuse this with the environment variable of the same name.
14217 If you want to pass a value to the administrative files
14218 which the user who is running @sc{cvs} can specify,
14219 use a user variable.
14220 @cindex User variables
14221 To expand a user variable, the
14222 administrative file contains
14223 @code{$@{=@var{variable}@}}. To set a user variable,
14224 specify the global option @samp{-s} to @sc{cvs}, with
14225 argument @code{@var{variable}=@var{value}}. It may be
14226 particularly useful to specify this option via
14227 @file{.cvsrc} (@pxref{~/.cvsrc}).
14229 For example, if you want the administrative file to
14230 refer to a test directory you might create a user
14231 variable @code{TESTDIR}. Then if @sc{cvs} is invoked
14235 cvs -s TESTDIR=/work/local/tests
14240 administrative file contains @code{sh
14241 $@{=TESTDIR@}/runtests}, then that string is expanded
14242 to @code{sh /work/local/tests/runtests}.
14244 All other strings containing @samp{$} are reserved;
14245 there is no way to quote a @samp{$} character so that
14246 @samp{$} represents itself.
14248 Environment variables passed to administrative files are:
14251 @cindex environment variables, passed to administrative files
14254 @cindex CVS_USER, environment variable
14255 The @sc{cvs}-specific username provided by the user, if it
14256 can be provided (currently just for the pserver access
14257 method), and to the empty string otherwise. (@code{CVS_USER}
14258 and @code{USER} may differ when @file{$CVSROOT/CVSROOT/passwd}
14259 is used to map @sc{cvs} usernames to system usernames.)
14262 @cindex LOGNAME, environment variable
14263 The username of the system user.
14266 @cindex USER, environment variable
14267 Same as @code{LOGNAME}.
14268 Do not confuse this with the internal variable of the same name.
14272 @appendixsec The CVSROOT/config configuration file
14274 @cindex config, in CVSROOT
14275 @cindex CVSROOT/config
14277 The administrative file @file{config} contains various
14278 miscellaneous settings which affect the behavior of
14279 @sc{cvs}. The syntax is slightly different from the
14280 other administrative files. Variables are not
14281 expanded. Lines which start with @samp{#} are
14282 considered comments.
14283 @c FIXME: where do we define comments for the other
14284 @c administrative files.
14285 Other lines consist of a keyword, @samp{=}, and a
14286 value. Note that this syntax is very strict.
14287 Extraneous spaces or tabs are not permitted.
14288 @c See comments in parseinfo.c:parse_config for more
14289 @c discussion of this strictness.
14291 Currently defined keywords are:
14294 @cindex RCSBIN, in CVSROOT/config
14295 @item RCSBIN=@var{bindir}
14296 For @sc{cvs} 1.9.12 through 1.9.18, this setting told
14297 @sc{cvs} to look for @sc{rcs} programs in the
14298 @var{bindir} directory. Current versions of @sc{cvs}
14299 do not run @sc{rcs} programs; for compatibility this
14300 setting is accepted, but it does nothing.
14302 @cindex SystemAuth, in CVSROOT/config
14303 @item SystemAuth=@var{value}
14304 If @var{value} is @samp{yes}, then pserver should check
14305 for users in the system's user database if not found in
14306 @file{CVSROOT/passwd}. If it is @samp{no}, then all
14307 pserver users must exist in @file{CVSROOT/passwd}.
14308 The default is @samp{yes}. For more on pserver, see
14309 @ref{Password authenticated}.
14311 @cindex LocalKeyword, in CVSROOT/config
14312 @item LocalKeyword=@var{value}
14313 Specify a local alias for a standard keyword.
14314 For example, @samp{LocalKeyword=MYCVS=CVSHeader}.
14315 For more on local keywords, see @ref{Keyword substitution}.
14317 @cindex KeywordExpand, in CVSROOT/config
14318 @item KeywordExpand=@var{value}
14319 Specify @samp{i} followed by a list of keywords to be expanded
14320 (for example, @samp{KeywordExpand=iMYCVS,Name,Date}),
14321 or @samp{e} followed by a list of keywords not to be expanded
14322 (for example, @samp{KeywordExpand=eCVSHeader}).
14323 For more on keyword expansion, see @ref{Configuring keyword expansion}.
14326 @cindex PreservePermissions, in CVSROOT/config
14327 @item PreservePermissions=@var{value}
14328 Enable support for saving special device files,
14329 symbolic links, file permissions and ownerships in the
14330 repository. The default value is @samp{no}.
14331 @xref{Special Files}, for the full implications of using
14335 @cindex TopLevelAdmin, in CVSROOT/config
14336 @item TopLevelAdmin=@var{value}
14337 Modify the @samp{checkout} command to create a
14338 @samp{CVS} directory at the top level of the new
14339 working directory, in addition to @samp{CVS}
14340 directories created within checked-out directories.
14341 The default value is @samp{no}.
14343 This option is useful if you find yourself performing
14344 many commands at the top level of your working
14345 directory, rather than in one of the checked out
14346 subdirectories. The @file{CVS} directory created there
14347 will mean you don't have to specify @code{CVSROOT} for
14348 each command. It also provides a place for the
14349 @file{CVS/Template} file (@pxref{Working directory
14352 @cindex LockDir, in CVSROOT/config
14353 @item LockDir=@var{directory}
14354 Put @sc{cvs} lock files in @var{directory} rather than
14355 directly in the repository. This is useful if you want
14356 to let users read from the repository while giving them
14357 write access only to @var{directory}, not to the
14359 It can also be used to put the locks on a very fast
14360 in-memory file system to speed up locking and unlocking
14362 You need to create @var{directory}, but
14363 @sc{cvs} will create subdirectories of @var{directory} as it
14364 needs them. For information on @sc{cvs} locks, see
14367 @c Mention this in Compatibility section?
14368 Before enabling the LockDir option, make sure that you
14369 have tracked down and removed any copies of @sc{cvs} 1.9 or
14370 older. Such versions neither support LockDir, nor will
14371 give an error indicating that they don't support it.
14372 The result, if this is allowed to happen, is that some
14373 @sc{cvs} users will put the locks one place, and others will
14374 put them another place, and therefore the repository
14375 could become corrupted. @sc{cvs} 1.10 does not support
14376 LockDir but it will print a warning if run on a
14377 repository with LockDir enabled.
14379 @cindex LogHistory, in CVSROOT/config
14380 @item LogHistory=@var{value}
14381 Control what is logged to the @file{CVSROOT/history} file (@pxref{history}).
14382 Default of @samp{TOEFWUPCGMAR} (or simply @samp{all}) will log
14383 all transactions. Any subset of the default is
14384 legal. (For example, to only log transactions that modify the
14385 @file{*,v} files, use @samp{LogHistory=TMAR}.)
14387 @cindex RereadLogAfterVerify, in CVSROOT/config
14388 @cindex @file{verifymsg}, changing the log message
14389 @item RereadLogAfterVerify=@var{value}
14390 Modify the @samp{commit} command such that CVS will reread the
14391 log message after running the program specified by @file{verifymsg}.
14392 @var{value} may be one of @samp{yes} or @samp{always}, indicating that
14393 the log message should always be reread; @samp{no}
14394 or @samp{never}, indicating that it should never be
14395 reread; or @var{value} may be @samp{stat}, indicating
14396 that the file should be checked with the file system
14397 @samp{stat()} function to see if it has changed (see warning below)
14398 before rereading. The default value is @samp{always}.
14400 @strong{Note: the `stat' mode can cause CVS to pause for up to
14401 one extra second per directory committed. This can be less IO and
14402 CPU intensive but is not recommended for use with large repositories}
14404 @xref{verifymsg}, for more information on how verifymsg
14407 @cindex UserAdminOptions, in CVSROOT/config
14408 @item UserAdminOptions=@var{value}
14409 Control what options will be allowed with the @code{cvs admin}
14410 command (@pxref{admin}) for users not in the @code{cvsadmin} group.
14411 The @var{value} string is a list of single character options
14412 which should be allowed. If a user who is not a member of the
14413 @code{cvsadmin} group tries to execute any @code{cvs admin}
14414 option which is not listed they will will receive an error message
14415 reporting that the option is restricted.
14417 If no @code{cvsadmin} group exists on the server, @sc{cvs} will
14418 ignore the @code{UserAdminOptions} keyword (@pxref{admin}).
14420 When not specified, @code{UserAdminOptions} defaults to
14421 @samp{k}. In other words, it defaults to allowing
14422 users outside of the @code{cvsadmin} group to use the
14423 @code{cvs admin} command only to change the default keyword
14424 expansion mode for files.
14426 As an example, to restrict users not in the @code{cvsadmin}
14427 group to using @code{cvs admin} to change the default keyword
14428 substitution mode, lock revisions, unlock revisions, and
14429 replace the log message, use @samp{UserAdminOptions=klum}.
14431 @cindex format strings, config admin file
14432 @cindex config (admin file), updating legacy repositories
14433 @cindex compatibility notes, config admin file
14434 @cindex UseNewInfoFmtStrings, in CVSROOT/config
14435 @item UseNewInfoFmtStrings=@var{value}
14436 Specify whether @sc{cvs} should support the new or old command line
14437 template model for the commit support files (@pxref{commit files}).
14438 This configuration variable began life in deprecation and is only here
14439 in order to give people time to update legacy repositories to use the new
14440 format string syntax before support for the old syntax is removed. For
14441 information on updating your repository to support the new model,
14442 please see @ref{Updating Commit Files}.
14444 @emph{Note that new repositories (created with the @code{cvs init} command)
14445 will have this value set to @samp{yes}, but the default value is @samp{no}.}
14447 @cindex import, config admin file
14448 @cindex config (admin file), import
14449 @cindex ImportNewFilesToVendorBranchOnly, in CVSROOT/config
14450 @item ImportNewFilesToVendorBranchOnly=@var{value}
14451 Specify whether @code{cvs import} should always behave as if the
14452 @samp{-X} flag was specified on the command line.
14453 @var{value} may be either @samp{yes} or @samp{no}. If set to @samp{yes},
14454 all uses of @code{cvs import} on the repository will behave as if the
14455 @samp{-X} flag was set. The default value is @samp{no}.
14457 @cindex PrimaryServer, in CVSROOT/config
14458 @cindex Primary server
14459 @cindex Secondary server
14460 @cindex proxy, write
14461 @cindex write proxy
14462 @item PrimaryServer=@var{CVSROOT}
14463 When specified, and the repository specified by @var{CVSROOT} is not the one
14464 currently being accessed, then the server will turn itself into a transparent
14465 proxy to @var{CVSROOT} for write requests. The @var{hostname} configured as
14466 part of @var{CVSROOT} must resolve to the same string returned by the
14467 @command{uname} command on the primary server for this to work. Host name
14468 resolution is performed via some combination of @command{named}, a broken out
14469 line from @file{/etc/hosts}, and the Network Information Service (NIS or YP),
14470 depending on the configuration of the particular system.
14472 Only the @samp{:ext:} method is
14473 currently supported for primaries (actually, @samp{:fork:} is supported as
14474 well, but only for testing - if you find another use for accessing a primary
14475 via the @samp{:fork:} method, please send a note to @email{bug-cvs@@gnu.org}
14476 about it). See @ref{Write proxies} for more on configuring and using write
14479 @cindex MaxCommentLeaderLength, in CVSROOT/config
14480 @cindex Log keyword, configuring substitution behavior
14481 @item MaxCommentLeaderLength=@var{length}
14482 Set to some length, in bytes, where a trailing @samp{k}, @samp{M}, @samp{G},
14483 or @samp{T} causes the preceding nubmer to be interpreted as kilobytes,
14484 megabytes, gigabytes, or terrabytes, respectively, will cause
14485 @code{$@splitrcskeyword{Log}$} keywords (@pxref{Keyword substitution}), with
14486 more than @var{length} bytes preceding it on a line to be ignored (or to fall
14487 back on the comment leader set in the RCS archive file - see
14488 @code{UseArchiveCommentLeader} below). Defaults to 20 bytes to allow checkouts
14489 to proceed normally when they include binary files containing
14490 @code{$@splitrcskeyword{Log}$} keywords and which users have neglected to mark
14493 @cindex UseArchiveCommentLeader, in CVSROOT/config
14494 @cindex Log keyword, configuring substitution behavior
14495 @item UseArchiveCommentLeader=@var{value}
14496 Set to @code{true}, if the text preceding a @code{$@splitrcskeyword{Log}$}
14497 keyword is found to exceed @code{MaxCommentLeaderLength} bytes, then the
14498 comment leader set in the RCS archive file (@pxref{admin}), if any, will be
14499 used instead. If there is no comment leader set in the archive file or
14500 @var{value} is set to @samp{false}, then the keyword will not be expanded
14501 (@pxref{Keyword list}). To force the comment leader in the RCS archive file to
14502 be used exclusively (and @code{$@splitrcskeyword{Log}$} expansion skipped in
14503 files where the comment leader has not been set in the archive file), set
14504 @var{value} and set @code{MaxCommentLeaderLength} to @code{0}.
14509 @c ---------------------------------------------------------------------
14510 @node Environment variables
14511 @appendix All environment variables which affect CVS
14512 @cindex Environment variables
14513 @cindex Reference manual for variables
14515 This is a complete list of all environment variables
14516 that affect @sc{cvs}.
14519 @cindex CVSIGNORE, environment variable
14521 A whitespace-separated list of file name patterns that
14522 @sc{cvs} should ignore. @xref{cvsignore}.
14524 @cindex CVSWRAPPERS, environment variable
14526 A whitespace-separated list of file name patterns that
14527 @sc{cvs} should treat as wrappers. @xref{Wrappers}.
14529 @cindex CVSREAD, environment variable
14530 @cindex Read-only files, and CVSREAD
14532 If this is set, @code{checkout} and @code{update} will
14533 try hard to make the files in your working directory
14534 read-only. When this is not set, the default behavior
14535 is to permit modification of your working files.
14537 @cindex CVSREADONLYFS, environment variable
14538 @item $CVSREADONLYFS
14539 Turns on read-only repository mode. This allows one to
14540 check out from a read-only repository, such as within
14541 an anoncvs server, or from a @sc{cd-rom} repository.
14543 It has the same effect as if the @samp{-R} command-line
14544 option is used. This can also allow the use of
14545 read-only NFS repositories.
14548 Controls permissions of files in the repository. See
14549 @ref{File permissions}.
14552 Should contain the full pathname to the root of the @sc{cvs}
14553 source repository (where the @sc{rcs} files are
14554 kept). This information must be available to @sc{cvs} for
14555 most commands to execute; if @code{$CVSROOT} is not set,
14556 or if you wish to override it for one invocation, you
14557 can supply it on the command line: @samp{cvs -d cvsroot
14558 cvs_command@dots{}} Once you have checked out a working
14559 directory, @sc{cvs} stores the appropriate root (in
14560 the file @file{CVS/Root}), so normally you only need to
14561 worry about this when initially checking out a working
14565 @cindex CVSEDITOR, environment variable
14567 @cindex EDITOR, environment variable
14569 @cindex VISUAL, environment variable
14570 Specifies the program to use for recording log messages
14571 during commit. @code{$CVSEDITOR} overrides
14572 @code{$EDITOR}, which overrides @code{$VISUAL}.
14573 See @ref{Committing your changes} for more or
14574 @ref{Global options} for alternative ways of specifying a
14577 @cindex PATH, environment variable
14579 If @code{$RCSBIN} is not set, and no path is compiled
14580 into @sc{cvs}, it will use @code{$PATH} to try to find all
14583 @cindex HOME, environment variable
14585 @cindex HOMEPATH, environment variable
14587 @cindex HOMEDRIVE, environment variable
14589 Used to locate the directory where the @file{.cvsrc}
14590 file, and other such files, are searched. On Unix, @sc{cvs}
14591 just checks for @code{HOME}. On Windows NT, the system will
14592 set @code{HOMEDRIVE}, for example to @samp{d:} and @code{HOMEPATH},
14593 for example to @file{\joe}. On Windows 95, you'll
14594 probably need to set @code{HOMEDRIVE} and @code{HOMEPATH} yourself.
14595 @c We are being vague about whether HOME works on
14596 @c Windows; see long comment in windows-NT/filesubr.c.
14598 @cindex CVS_RSH, environment variable
14600 Specifies the external program which @sc{cvs} connects with,
14601 when @code{:ext:} access method is specified.
14602 @pxref{Connecting via rsh}.
14605 Used in client-server mode when accessing a remote
14606 repository using @sc{rsh}. It specifies the name of
14607 the program to start on the server side (and any
14608 necessary arguments) when accessing a remote repository
14609 using the @code{:ext:}, @code{:fork:}, or @code{:server:} access methods.
14610 The default value for @code{:ext:} and @code{:server:} is @code{cvs};
14611 the default value for @code{:fork:} is the name used to run the client.
14612 @pxref{Connecting via rsh}
14614 @item $CVS_PASSFILE
14615 Used in client-server mode when accessing the @code{cvs
14616 login server}. Default value is @file{$HOME/.cvspass}.
14617 @pxref{Password authentication client}
14619 @cindex CVS_CLIENT_PORT
14620 @item $CVS_CLIENT_PORT
14621 Used in client-server mode to set the port to use when accessing the server
14622 via Kerberos, GSSAPI, or @sc{cvs}'s password authentication protocol
14623 if the port is not specified in the CVSROOT.
14624 @pxref{Remote repositories}
14626 @cindex CVS_PROXY_PORT
14627 @item $CVS_PROXY_PORT
14628 Used in client-server mode to set the port to use when accessing a server
14629 via a web proxy, if the port is not specified in the CVSROOT. Works with
14630 GSSAPI, and the password authentication protocol.
14631 @pxref{Remote repositories}
14633 @cindex CVS_RCMD_PORT, environment variable
14634 @item $CVS_RCMD_PORT
14635 Used in client-server mode. If set, specifies the port
14636 number to be used when accessing the @sc{rcmd} demon on
14637 the server side. (Currently not used for Unix clients).
14639 @cindex CVS_CLIENT_LOG, environment variable
14640 @item $CVS_CLIENT_LOG
14641 Used for debugging only in client-server
14642 mode. If set, everything sent to the server is logged
14643 into @file{@code{$CVS_CLIENT_LOG}.in} and everything
14644 sent from the server is logged into
14645 @file{@code{$CVS_CLIENT_LOG}.out}.
14647 @cindex CVS_SERVER_SLEEP, environment variable
14648 @item $CVS_SERVER_SLEEP
14649 Used only for debugging the server side in
14650 client-server mode. If set, delays the start of the
14651 server child process the specified amount of
14652 seconds so that you can attach to it with a debugger.
14654 @cindex CVS_IGNORE_REMOTE_ROOT, environment variable
14655 @item $CVS_IGNORE_REMOTE_ROOT
14656 For @sc{cvs} 1.10 and older, setting this variable
14657 prevents @sc{cvs} from overwriting the @file{CVS/Root}
14658 file when the @samp{-d} global option is specified.
14659 Later versions of @sc{cvs} do not rewrite
14660 @file{CVS/Root}, so @code{CVS_IGNORE_REMOTE_ROOT} has no
14663 @cindex CVS_LOCAL_BRANCH_NUM, environment variable
14664 @item $CVS_LOCAL_BRANCH_NUM
14665 Setting this variable allows some control over the
14666 branch number that is assigned. This is specifically to
14667 support the local commit feature of CVSup. If one sets
14668 @code{CVS_LOCAL_BRANCH_NUM} to (say) 1000 then branches
14669 the local repository, the revision numbers will look
14670 like 1.66.1000.xx. There is almost a dead-set certainty
14671 that there will be no conflicts with version numbers.
14673 @cindex COMSPEC, environment variable
14675 Used under OS/2 only. It specifies the name of the
14676 command interpreter and defaults to @sc{cmd.exe}.
14678 @cindex TMPDIR, environment variable
14680 @cindex TMP, environment variable
14682 @cindex TEMP, environment variable
14684 @cindex Temporary files, location of
14685 @c This is quite nuts. We don't talk about tempnam
14686 @c or mkstemp which we sometimes use. The discussion
14687 @c of "Global options" is semi-incoherent.
14688 @c I'm not even sure those are the only inaccuracies.
14689 @c Furthermore, the conventions are
14690 @c pretty crazy and they should be simplified.
14691 Directory in which temporary files are located.
14692 The @sc{cvs} server uses
14693 @code{TMPDIR}. @xref{Global options}, for a
14694 description of how to specify this.
14695 Some parts of @sc{cvs} will always use @file{/tmp} (via
14696 the @code{tmpnam} function provided by the system).
14698 On Windows NT, @code{TMP} is used (via the @code{_tempnam}
14699 function provided by the system).
14701 The @code{patch} program which is used by the @sc{cvs}
14702 client uses @code{TMPDIR}, and if it is not set, uses
14703 @file{/tmp} (at least with GNU patch 2.1). Note that
14704 if your server and client are both running @sc{cvs}
14705 1.9.10 or later, @sc{cvs} will not invoke an external
14706 @code{patch} program.
14708 @cindex CVS_PID, environment variable
14710 This is the process identification (aka pid) number of
14711 the @sc{cvs} process. It is often useful in the
14712 programs and/or scripts specified by the
14713 @file{commitinfo}, @file{verifymsg}, @file{loginfo}
14717 @node Compatibility
14718 @appendix Compatibility between CVS Versions
14720 @cindex CVS, versions of
14721 @cindex Versions, of CVS
14722 @cindex Compatibility, between CVS versions
14723 @c We don't mention versions older than CVS 1.3
14724 @c on the theory that it would clutter it up for the vast
14725 @c majority of people, who don't have anything that old.
14727 The repository format is compatible going back to
14728 @sc{cvs} 1.3. But see @ref{Watches Compatibility}, if
14729 you have copies of @sc{cvs} 1.6 or older and you want
14730 to use the optional developer communication features.
14731 @c If you "cvs rm" and commit using 1.3, then you'll
14732 @c want to run "rcs -sdead <file,v>" on each of the
14733 @c files in the Attic if you then want 1.5 and
14734 @c later to recognize those files as dead (I think the
14735 @c symptom if this is not done is that files reappear
14736 @c in joins). (Wait: the above will work but really to
14737 @c be strictly correct we should suggest checking
14738 @c in a new revision rather than just changing the
14739 @c state of the head revision, shouldn't we?).
14740 @c The old convert.sh script was for this, but it never
14741 @c did get updated to reflect use of the RCS "dead"
14743 @c Note: this is tricky to document without confusing
14744 @c people--need to carefully say what CVS version we
14745 @c are talking about and keep in mind the distinction
14747 @c repository created with 1.3 and on which one now
14748 @c uses 1.5+, and a repository on which one wants to
14749 @c use both versions side by side (e.g. during a
14750 @c transition period).
14751 @c Wait, can't CVS just detect the case in which a file
14752 @c is in the Attic but the head revision is not dead?
14753 @c Not sure whether this should produce a warning or
14754 @c something, and probably needs further thought, but
14755 @c it would appear that the situation can be detected.
14757 @c We might want to separate out the 1.3 compatibility
14758 @c section (for repository & working directory) from the
14759 @c rest--that might help avoid confusing people who
14760 @c are upgrading (for example) from 1.6 to 1.8.
14762 @c A minor incompatibility is if a current version of CVS
14763 @c puts "Nfoo" into CVS/Tag, then CVS 1.9 or older will
14764 @c see this as if there is no tag. Seems to me this is
14765 @c too obscure to mention.
14767 The working directory format is compatible going back
14768 to @sc{cvs} 1.5. It did change between @sc{cvs} 1.3
14769 and @sc{cvs} 1.5. If you run @sc{cvs} 1.5 or newer on
14770 a working directory checked out with @sc{cvs} 1.3,
14771 @sc{cvs} will convert it, but to go back to @sc{cvs}
14772 1.3 you need to check out a new working directory with
14775 The remote protocol is interoperable going back to @sc{cvs} 1.5, but no
14776 further (1.5 was the first official release with the remote protocol,
14777 but some older versions might still be floating around). In many
14778 cases you need to upgrade both the client and the server to take
14779 advantage of new features and bug fixes, however.
14781 @c Perhaps should be saying something here about the
14782 @c "D" lines in Entries (written by CVS 1.9; 1.8 and
14783 @c older don't use them). These are supposed to be
14784 @c compatible in both directions, but I'm not sure
14785 @c they quite are 100%. One common gripe is if you
14786 @c "rm -r" a directory and 1.9 gets confused, as it
14787 @c still sees it in Entries. That one is fixed in
14788 @c (say) 1.9.6. Someone else reported problems with
14789 @c starting with a directory which was checked out with
14790 @c an old version, and then using a new version, and
14791 @c some "D" lines appeared, but not for every
14792 @c directory, causing some directories to be skipped.
14793 @c They weren't sure how to reproduce this, though.
14795 @c ---------------------------------------------------------------------
14796 @node Troubleshooting
14797 @appendix Troubleshooting
14799 If you are having trouble with @sc{cvs}, this appendix
14800 may help. If there is a particular error message which
14801 you are seeing, then you can look up the message
14802 alphabetically. If not, you can look through the
14803 section on other problems to see if your problem is
14807 * Error messages:: Partial list of CVS errors
14808 * Connection:: Trouble making a connection to a CVS server
14809 * Other problems:: Problems not readily listed by error message
14813 @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
14814 @c @node Bad administrative files
14815 @appendixsec Bad administrative files
14817 @c -- Give hints on how to fix them
14820 @node Error messages
14821 @appendixsec Partial list of error messages
14823 Here is a partial list of error messages that you may
14824 see from @sc{cvs}. It is not a complete list---@sc{cvs}
14825 is capable of printing many, many error messages, often
14826 with parts of them supplied by the operating system,
14827 but the intention is to list the common and/or
14828 potentially confusing error messages.
14830 The messages are alphabetical, but introductory text
14831 such as @samp{cvs update: } is not considered in
14834 In some cases the list includes messages printed by old
14835 versions of @sc{cvs} (partly because users may not be
14836 sure which version of @sc{cvs} they are using at any
14837 particular moment).
14838 @c If we want to start retiring messages, perhaps we
14839 @c should pick a cutoff version (for example, no more
14840 @c messages which are specific to versions before 1.9)
14841 @c and then move the old messages to an "old messages"
14842 @c node rather than deleting them completely.
14845 @c FIXME: What is the correct way to format a multiline
14846 @c error message here? Maybe @table is the wrong
14847 @c choice? Texinfo gurus?
14848 @item @var{file}:@var{line}: Assertion '@var{text}' failed
14849 The exact format of this message may vary depending on
14850 your system. It indicates a bug in @sc{cvs}, which can
14851 be handled as described in @ref{BUGS}.
14853 @item cvs @var{command}: authorization failed: server @var{host} rejected access
14854 This is a generic response when trying to connect to a
14855 pserver server which chooses not to provide a
14856 specific reason for denying authorization. Check that
14857 the username and password specified are correct and
14858 that the @code{CVSROOT} specified is allowed by @samp{--allow-root}
14859 in @file{inetd.conf}. See @ref{Password authenticated}.
14861 @item cvs @var{command}: conflict: removed @var{file} was modified by second party
14862 This message indicates that you removed a file, and
14863 someone else modified it. To resolve the conflict,
14864 first run @samp{cvs add @var{file}}. If desired, look
14865 at the other party's modification to decide whether you
14866 still want to remove it. If you don't want to remove
14867 it, stop here. If you do want to remove it, proceed
14868 with @samp{cvs remove @var{file}} and commit your
14870 @c Tests conflicts2-142b* in sanity.sh test for this.
14872 @item cannot change permissions on temporary directory
14874 Operation not permitted
14876 This message has been happening in a non-reproducible,
14877 occasional way when we run the client/server testsuite,
14878 both on Red Hat Linux 3.0.3 and 4.1. We haven't been
14879 able to figure out what causes it, nor is it known
14880 whether it is specific to Linux (or even to this
14881 particular machine!). If the problem does occur on
14882 other unices, @samp{Operation not permitted} would be
14883 likely to read @samp{Not owner} or whatever the system
14884 in question uses for the unix @code{EPERM} error. If
14885 you have any information to add, please let us know as
14886 described in @ref{BUGS}. If you experience this error
14887 while using @sc{cvs}, retrying the operation which
14888 produced it should work fine.
14889 @c This has been seen in a variety of tests, including
14890 @c multibranch-2, multibranch-5, and basic1-24-rm-rm,
14891 @c so it doesn't seem particularly specific to any one
14894 @item cvs [server aborted]: Cannot check out files into the repository itself
14895 The obvious cause for this message (especially for
14896 non-client/server @sc{cvs}) is that the @sc{cvs} root
14897 is, for example, @file{/usr/local/cvsroot} and you try
14898 to check out files when you are in a subdirectory, such
14899 as @file{/usr/local/cvsroot/test}. However, there is a
14900 more subtle cause, which is that the temporary
14901 directory on the server is set to a subdirectory of the
14902 root (which is also not allowed). If this is the
14903 problem, set the temporary directory to somewhere else,
14904 for example @file{/var/tmp}; see @code{TMPDIR} in
14905 @ref{Environment variables}, for how to set the
14906 temporary directory.
14908 @item cannot commit files as 'root'
14909 See @samp{'root' is not allowed to commit files}.
14911 @c For one example see basica-1a10 in the testsuite
14912 @c For another example, "cvs co ." on NT; see comment
14913 @c at windows-NT/filesubr.c (expand_wild).
14914 @c For another example, "cvs co foo/bar" where foo exists.
14915 @item cannot open CVS/Entries for reading: No such file or directory
14916 This generally indicates a @sc{cvs} internal error, and
14917 can be handled as with other @sc{cvs} bugs
14918 (@pxref{BUGS}). Usually there is a workaround---the
14919 exact nature of which would depend on the situation but
14920 which hopefully could be figured out.
14922 @c This is more obscure than it might sound; it only
14923 @c happens if you run "cvs init" from a directory which
14924 @c contains a CVS/Root file at the start.
14925 @item cvs [init aborted]: cannot open CVS/Root: No such file or directory
14926 This message is harmless. Provided it is not
14927 accompanied by other errors, the operation has
14928 completed successfully. This message should not occur
14929 with current versions of @sc{cvs}, but it is documented
14930 here for the benefit of @sc{cvs} 1.9 and older.
14932 @item cvs server: cannot open /root/.cvsignore: Permission denied
14933 @itemx cvs [server aborted]: can't chdir(/root): Permission denied
14934 See @ref{Connection}.
14936 @item cvs [checkout aborted]: cannot rename file @var{file} to CVS/,,@var{file}: Invalid argument
14937 This message has been reported as intermittently
14938 happening with @sc{cvs} 1.9 on Solaris 2.5. The cause is
14939 unknown; if you know more about what causes it, let us
14940 know as described in @ref{BUGS}.
14942 @item cvs [@var{command} aborted]: cannot start server via rcmd
14943 This, unfortunately, is a rather nonspecific error
14944 message which @sc{cvs} 1.9 will print if you are
14945 running the @sc{cvs} client and it is having trouble
14946 connecting to the server. Current versions of @sc{cvs}
14947 should print a much more specific error message. If
14948 you get this message when you didn't mean to run the
14949 client at all, you probably forgot to specify
14950 @code{:local:}, as described in @ref{Repository}.
14952 @item ci: @var{file},v: bad diff output line: Binary files - and /tmp/T2a22651 differ
14953 @sc{cvs} 1.9 and older will print this message
14954 when trying to check in a binary file if
14955 @sc{rcs} is not correctly installed. Re-read the
14956 instructions that came with your @sc{rcs} distribution
14957 and the @sc{install} file in the @sc{cvs}
14958 distribution. Alternately, upgrade to a current
14959 version of @sc{cvs}, which checks in files itself
14960 rather than via @sc{rcs}.
14962 @item cvs checkout: could not check out @var{file}
14963 With @sc{cvs} 1.9, this can mean that the @code{co} program
14964 (part of @sc{rcs}) returned a failure. It should be
14965 preceded by another error message, however it has been
14966 observed without another error message and the cause is
14967 not well-understood. With the current version of @sc{cvs},
14968 which does not run @code{co}, if this message occurs
14969 without another error message, it is definitely a @sc{cvs}
14970 bug (@pxref{BUGS}).
14971 @c My current suspicion is that the RCS in the rcs (not
14972 @c cvs/winnt/rcs57nt.zip) directory on the _Practical_
14973 @c CD is bad (remains to be confirmed).
14974 @c There is also a report of something which looks
14975 @c very similar on SGI, Irix 5.2, so I dunno.
14977 @item cvs [login aborted]: could not find out home directory
14978 This means that you need to set the environment
14979 variables that @sc{cvs} uses to locate your home directory.
14980 See the discussion of @code{HOME}, @code{HOMEDRIVE}, and @code{HOMEPATH} in
14981 @ref{Environment variables}.
14983 @item cvs update: could not merge revision @var{rev} of @var{file}: No such file or directory
14984 @sc{cvs} 1.9 and older will print this message if there was
14985 a problem finding the @code{rcsmerge} program. Make
14986 sure that it is in your @code{PATH}, or upgrade to a
14987 current version of @sc{cvs}, which does not require
14988 an external @code{rcsmerge} program.
14990 @item cvs [update aborted]: could not patch @var{file}: No such file or directory
14991 This means that there was a problem finding the
14992 @code{patch} program. Make sure that it is in your
14993 @code{PATH}. Note that despite appearances the message
14994 is @emph{not} referring to whether it can find @var{file}.
14995 If both the client and the server are running a current
14996 version of @sc{cvs}, then there is no need for an
14997 external patch program and you should not see this
14998 message. But if either client or server is running
14999 @sc{cvs} 1.9, then you need @code{patch}.
15001 @item cvs update: could not patch @var{file}; will refetch
15002 This means that for whatever reason the client was
15003 unable to apply a patch that the server sent. The
15004 message is nothing to be concerned about, because
15005 inability to apply the patch only slows things down and
15006 has no effect on what @sc{cvs} does.
15007 @c xref to update output. Or File status?
15008 @c Or some place else that
15009 @c explains this whole "patch"/P/Needs Patch thing?
15011 @item dying gasps from @var{server} unexpected
15012 There is a known bug in the server for @sc{cvs} 1.9.18
15013 and older which can cause this. For me, this was
15014 reproducible if I used the @samp{-t} global option. It
15015 was fixed by Andy Piper's 14 Nov 1997 change to
15016 src/filesubr.c, if anyone is curious.
15017 If you see the message,
15018 you probably can just retry the operation which failed,
15019 or if you have discovered information concerning its
15020 cause, please let us know as described in @ref{BUGS}.
15022 @item end of file from server (consult above messages if any)
15023 The most common cause for this message is if you are
15024 using an external @code{rsh} program and it exited with
15025 an error. In this case the @code{rsh} program should
15026 have printed a message, which will appear before the
15027 above message. For more information on setting up a
15028 @sc{cvs} client and server, see @ref{Remote repositories}.
15030 @item cvs [update aborted]: EOF in key in RCS file @var{file},v
15031 @itemx cvs [checkout aborted]: EOF while looking for end of string in RCS file @var{file},v
15032 This means that there is a syntax error in the given
15033 @sc{rcs} file. Note that this might be true even if @sc{rcs} can
15034 read the file OK; @sc{cvs} does more error checking of
15035 errors in the RCS file. That is why you may see this
15036 message when upgrading from @sc{cvs} 1.9 to @sc{cvs}
15037 1.10. The likely cause for the original corruption is
15038 hardware, the operating system, or the like. Of
15039 course, if you find a case in which @sc{cvs} seems to
15040 corrupting the file, by all means report it,
15042 There are quite a few variations of this error message,
15043 depending on exactly where in the @sc{rcs} file @sc{cvs}
15044 finds the syntax error.
15047 @item cvs commit: Executing 'mkmodules'
15048 This means that your repository is set up for a version
15049 of @sc{cvs} prior to @sc{cvs} 1.8. When using @sc{cvs}
15050 1.8 or later, the above message will be preceded by
15053 cvs commit: Rebuilding administrative file database
15056 If you see both messages, the database is being rebuilt
15057 twice, which is unnecessary but harmless. If you wish
15058 to avoid the duplication, and you have no versions of
15059 @sc{cvs} 1.7 or earlier in use, remove @code{-i mkmodules}
15060 every place it appears in your @code{modules}
15061 file. For more information on the @code{modules} file,
15064 @c This message comes from "co", and I believe is
15065 @c possible only with older versions of CVS which call
15066 @c co. The problem with being able to create the bogus
15067 @c RCS file still exists, though (and I think maybe
15068 @c there is a different symptom(s) now).
15069 @c FIXME: Would be nice to have a more exact wording
15070 @c for this message.
15071 @item missing author
15072 Typically this can happen if you created an RCS file
15073 with your username set to empty. @sc{cvs} will, bogusly,
15074 create an illegal RCS file with no value for the author
15075 field. The solution is to make sure your username is
15076 set to a non-empty value and re-create the RCS file.
15077 @c "make sure your username is set" is complicated in
15078 @c and of itself, as there are the environment
15079 @c variables the system login name, &c, and it depends
15080 @c on the version of CVS.
15082 @item cvs [checkout aborted]: no such tag @var{tag}
15083 This message means that @sc{cvs} isn't familiar with
15084 the tag @var{tag}. Usually the root cause is that you have
15085 mistyped a tag name. Ocassionally this can also occur because the
15086 users creating tags do not have permissions to write to the
15087 @file{CVSROOT/val-tags} file (@pxref{File permissions}, for more).
15089 Prior to @sc{cvs} version 1.12.10, there were a few relatively
15090 obscure cases where a given tag could be created in an archive
15091 file in the repository but @sc{cvs} would require the user to
15092 @c Search sanity.sh for "no such tag" to see some of
15093 @c the relatively obscure cases.
15094 try a few other @sc{cvs} commands involving that tag
15095 until one was found whch caused @sc{cvs} to update
15096 @cindex CVSROOT/val-tags file, forcing tags into
15097 @cindex val-tags file, forcing tags into
15098 the @file{val-tags} file, at which point the originally failing command
15099 would begin to work. This same method can be used to repair a @file{val-tags}
15100 file that becomes out of date due to the permissions problem mentioned above.
15101 This updating is only required once per tag - once a tag is listed in
15102 @file{val-tags}, it stays there.
15104 Note that using @samp{tag -f} to not require tag matches did not and
15105 does not override this check (@pxref{Common options}).
15107 @item *PANIC* administration files missing
15108 This typically means that there is a directory named
15109 @sc{cvs} but it does not contain the administrative files
15110 which @sc{cvs} puts in a CVS directory. If the problem is
15111 that you created a CVS directory via some mechanism
15112 other than @sc{cvs}, then the answer is simple, use a name
15113 other than @sc{cvs}. If not, it indicates a @sc{cvs} bug
15116 @item rcs error: Unknown option: -x,v/
15117 This message will be followed by a usage message for
15118 @sc{rcs}. It means that you have an old version of
15119 @sc{rcs} (probably supplied with your operating
15120 system), as well as an old version of @sc{cvs}.
15121 @sc{cvs} 1.9.18 and earlier only work with @sc{rcs} version 5 and
15122 later; current versions of @sc{cvs} do not run @sc{rcs} programs.
15123 @c For more information on installing @sc{cvs}, see
15124 @c (FIXME: where? it depends on whether you are
15125 @c getting binaries or sources or what).
15126 @c The message can also say "ci error" or something
15127 @c instead of "rcs error", I suspect.
15129 @item cvs [server aborted]: received broken pipe signal
15130 This message can be caused by a loginfo program that fails to
15131 read all of the log information from its standard input.
15132 If you find it happening in any other circumstances,
15133 please let us know as described in @ref{BUGS}.
15135 @item 'root' is not allowed to commit files
15136 When committing a permanent change, @sc{cvs} makes a log entry of
15137 who committed the change. If you are committing the change logged
15138 in as "root" (not under "su" or other root-priv giving program),
15139 @sc{cvs} cannot determine who is actually making the change.
15140 As such, by default, @sc{cvs} disallows changes to be committed by users
15141 logged in as "root". (You can disable this option by passing the
15142 @code{--enable-rootcommit} option to @file{configure} and recompiling @sc{cvs}.
15143 On some systems this means editing the appropriate @file{config.h} file
15144 before building @sc{cvs}.)
15146 @item Too many arguments!
15147 This message is typically printed by the @file{log.pl}
15148 script which is in the @file{contrib} directory in the
15149 @sc{cvs} source distribution. In some versions of
15150 @sc{cvs}, @file{log.pl} has been part of the default
15151 @sc{cvs} installation. The @file{log.pl} script gets
15152 called from the @file{loginfo} administrative file.
15153 Check that the arguments passed in @file{loginfo} match
15154 what your version of @file{log.pl} expects. In
15155 particular, the @file{log.pl} from @sc{cvs} 1.3 and
15156 older expects the log file as an argument whereas the
15157 @file{log.pl} from @sc{cvs} 1.5 and newer expects the
15158 log file to be specified with a @samp{-f} option. Of
15159 course, if you don't need @file{log.pl} you can just
15160 comment it out of @file{loginfo}.
15162 @item cvs [update aborted]: unexpected EOF reading @var{file},v
15163 See @samp{EOF in key in RCS file}.
15165 @item cvs [login aborted]: unrecognized auth response from @var{server}
15166 This message typically means that the server is not set
15167 up properly. For example, if @file{inetd.conf} points
15168 to a nonexistent cvs executable. To debug it further,
15169 find the log file which inetd writes
15170 (@file{/var/log/messages} or whatever inetd uses on
15171 your system). For details, see @ref{Connection}, and
15172 @ref{Password authentication server}.
15174 @item cvs commit: Up-to-date check failed for `@var{file}'
15175 This means that someone else has committed a change to
15176 that file since the last time that you did a @code{cvs
15177 update}. So before proceeding with your @code{cvs
15178 commit} you need to @code{cvs update}. @sc{cvs} will merge
15179 the changes that you made and the changes that the
15180 other person made. If it does not detect any conflicts
15181 it will report @samp{M @var{file}} and you are ready
15182 to @code{cvs commit}. If it detects conflicts it will
15183 print a message saying so, will report @samp{C @var{file}},
15184 and you need to manually resolve the
15185 conflict. For more details on this process see
15186 @ref{Conflicts example}.
15188 @item Usage: diff3 [-exEX3 [-i | -m] [-L label1 -L label3]] file1 file2 file3
15190 Only one of [exEX3] allowed
15192 This indicates a problem with the installation of
15193 @code{diff3} and @code{rcsmerge}. Specifically
15194 @code{rcsmerge} was compiled to look for GNU diff3, but
15195 it is finding unix diff3 instead. The exact text of
15196 the message will vary depending on the system. The
15197 simplest solution is to upgrade to a current version of
15198 @sc{cvs}, which does not rely on external
15199 @code{rcsmerge} or @code{diff3} programs.
15201 @item warning: unrecognized response `@var{text}' from cvs server
15202 If @var{text} contains a valid response (such as
15203 @samp{ok}) followed by an extra carriage return
15204 character (on many systems this will cause the second
15205 part of the message to overwrite the first part), then
15206 it probably means that you are using the @samp{:ext:}
15207 access method with a version of rsh, such as most
15208 non-unix rsh versions, which does not by default
15209 provide a transparent data stream. In such cases you
15210 probably want to try @samp{:server:} instead of
15211 @samp{:ext:}. If @var{text} is something else, this
15212 may signify a problem with your @sc{cvs} server.
15213 Double-check your installation against the instructions
15214 for setting up the @sc{cvs} server.
15215 @c FIXCVS: should be printing CR as \r or \015 or some
15218 @item cvs commit: [@var{time}] waiting for @var{user}'s lock in @var{directory}
15219 This is a normal message, not an error. See
15220 @ref{Concurrency}, for more details.
15222 @item cvs commit: warning: editor session failed
15223 @cindex Exit status, of editor
15224 This means that the editor which @sc{cvs} is using exits with a nonzero
15225 exit status. Some versions of vi will do this even when there was not
15226 a problem editing the file. If so, point the
15227 @code{CVSEDITOR} environment variable to a small script
15236 @item cvs [server aborted]: Secondary out of sync with primary!
15238 This usually means that the version of @sc{cvs} running on a secondary server
15239 and a primary server (@pxref{Write proxies}) are not the same. This will not
15240 occur if the client support redirection.
15242 It is not the version number that is significant here, but the list of
15243 supported requests that the servers provide to the client. Thus, if the
15244 secondary was compiled with GSSAPI support and the primary was not, then the
15245 list of supported requests provided by the two servers will be different and
15246 the secondary will not work as a transparent proxy to the primary. Conversely,
15247 one server could be version 1.12.10 and the other version 1.12.11 if they both
15248 provided the same list of valid requests to the client.
15250 @c "warning: foo was lost" and "no longer pertinent" (both normal).
15251 @c Would be nice to write these up--they are
15252 @c potentially confusing for the new user.
15256 @appendixsec Trouble making a connection to a CVS server
15258 This section concerns what to do if you are having
15259 trouble making a connection to a @sc{cvs} server. If
15260 you are running the @sc{cvs} command line client
15261 running on Windows, first upgrade the client to
15262 @sc{cvs} 1.9.12 or later. The error reporting in
15263 earlier versions provided much less information about
15264 what the problem was. If the client is non-Windows,
15265 @sc{cvs} 1.9 should be fine.
15267 If the error messages are not sufficient to track down
15268 the problem, the next steps depend largely on which
15269 access method you are using.
15272 @cindex :ext:, troubleshooting
15274 Try running the rsh program from the command line. For
15275 example: "rsh servername cvs -v" should print @sc{cvs}
15276 version information. If this doesn't work, you need to
15277 fix it before you can worry about @sc{cvs} problems.
15279 @cindex :server:, troubleshooting
15281 You don't need a command line rsh program to use this
15282 access method, but if you have an rsh program around,
15283 it may be useful as a debugging tool. Follow the
15284 directions given for :ext:.
15286 @cindex :pserver:, troubleshooting
15288 Errors along the lines of "connection refused" typically indicate
15289 that inetd isn't even listening for connections on port 2401
15290 whereas errors like "connection reset by peer",
15291 "received broken pipe signal", "recv() from server: EOF",
15292 or "end of file from server"
15293 typically indicate that inetd is listening for
15294 connections but is unable to start @sc{cvs} (this is frequently
15295 caused by having an incorrect path in @file{inetd.conf}
15296 or by firewall software rejecting the connection).
15297 "unrecognized auth response" errors are caused by a bad command
15298 line in @file{inetd.conf}, typically an invalid option or forgetting
15299 to put the @samp{pserver} command at the end of the line.
15300 Another less common problem is invisible control characters that
15301 your editor "helpfully" added without you noticing.
15303 One good debugging tool is to "telnet servername
15304 2401". After connecting, send any text (for example
15305 "foo" followed by return). If @sc{cvs} is working
15306 correctly, it will respond with
15309 cvs [pserver aborted]: bad auth protocol start: foo
15312 If instead you get:
15315 Usage: cvs [cvs-options] command [command-options-and-arguments]
15320 then you're missing the @samp{pserver} command at the end of the
15321 line in @file{inetd.conf}; check to make sure that the entire command
15322 is on one line and that it's complete.
15324 Likewise, if you get something like:
15327 Unknown command: `pserved'
15330 add Add a new file/directory to the repository
15335 then you've misspelled @samp{pserver} in some way. If it isn't
15336 obvious, check for invisible control characters (particularly
15337 carriage returns) in @file{inetd.conf}.
15339 If it fails to work at all, then make sure inetd is working
15340 right. Change the invocation in @file{inetd.conf} to run the
15341 echo program instead of cvs. For example:
15344 2401 stream tcp nowait root /bin/echo echo hello
15347 After making that change and instructing inetd to
15348 re-read its configuration file, "telnet servername
15349 2401" should show you the text hello and then the
15350 server should close the connection. If this doesn't
15351 work, you need to fix it before you can worry about
15354 On AIX systems, the system will often have its own
15355 program trying to use port 2401. This is AIX's problem
15356 in the sense that port 2401 is registered for use with
15357 @sc{cvs}. I hear that there is an AIX patch available
15358 to address this problem.
15360 Another good debugging tool is the @samp{-d}
15361 (debugging) option to inetd. Consult your system
15362 documentation for more information.
15364 If you seem to be connecting but get errors like:
15367 cvs server: cannot open /root/.cvsignore: Permission denied
15368 cvs [server aborted]: can't chdir(/root): Permission denied
15372 then you probably haven't specified @samp{-f} in @file{inetd.conf}.
15373 (In releases prior to @sc{cvs} 1.11.1, this problem can be caused by
15374 your system setting the @code{$HOME} environment variable
15375 for programs being run by inetd. In this case, you can either
15376 have inetd run a shell script that unsets @code{$HOME} and then runs
15377 @sc{cvs}, or you can use @code{env} to run @sc{cvs} with a pristine
15380 If you can connect successfully for a while but then can't,
15381 you've probably hit inetd's rate limit.
15382 (If inetd receives too many requests for the same service
15383 in a short period of time, it assumes that something is wrong
15384 and temporarily disables the service.)
15385 Check your inetd documentation to find out how to adjust the
15386 rate limit (some versions of inetd have a single rate limit,
15387 others allow you to set the limit for each service separately.)
15390 @node Other problems
15391 @appendixsec Other common problems
15393 Here is a list of problems which do not fit into the
15394 above categories. They are in no particular order.
15398 On Windows, if there is a 30 second or so delay when
15399 you run a @sc{cvs} command, it may mean that you have
15400 your home directory set to @file{C:/}, for example (see
15401 @code{HOMEDRIVE} and @code{HOMEPATH} in
15402 @ref{Environment variables}). @sc{cvs} expects the home
15403 directory to not end in a slash, for example @file{C:}
15405 @c FIXCVS: CVS should at least detect this and print an
15406 @c error, presumably.
15409 If you are running @sc{cvs} 1.9.18 or older, and
15410 @code{cvs update} finds a conflict and tries to
15411 merge, as described in @ref{Conflicts example}, but
15412 doesn't tell you there were conflicts, then you may
15413 have an old version of @sc{rcs}. The easiest solution
15414 probably is to upgrade to a current version of
15415 @sc{cvs}, which does not rely on external @sc{rcs}
15419 @c ---------------------------------------------------------------------
15423 @cindex Contributors (manual)
15424 @cindex Credits (manual)
15425 Roland Pesch, then of Cygnus Support <@t{roland@@wrs.com}>
15426 wrote the manual pages which were distributed with
15427 @sc{cvs} 1.3. Much of their text was copied into this
15428 manual. He also read an early draft
15429 of this manual and contributed many ideas and
15432 The mailing-list @code{info-cvs} is sometimes
15433 informative. I have included information from postings
15434 made by the following persons:
15435 David G. Grubbs <@t{dgg@@think.com}>.
15437 Some text has been extracted from the man pages for
15440 The @sc{cvs} @sc{faq} by David G. Grubbs has provided
15441 useful material. The @sc{faq} is no longer maintained,
15442 however, and this manual is about the closest thing there
15443 is to a successor (with respect to documenting how to
15444 use @sc{cvs}, at least).
15446 In addition, the following persons have helped by
15447 telling me about mistakes I've made:
15450 Roxanne Brunskill <@t{rbrunski@@datap.ca}>,
15451 Kathy Dyer <@t{dyer@@phoenix.ocf.llnl.gov}>,
15452 Karl Pingle <@t{pingle@@acuson.com}>,
15453 Thomas A Peterson <@t{tap@@src.honeywell.com}>,
15454 Inge Wallin <@t{ingwa@@signum.se}>,
15455 Dirk Koschuetzki <@t{koschuet@@fmi.uni-passau.de}>
15456 and Michael Brown <@t{brown@@wi.extrel.com}>.
15459 The list of contributors here is not comprehensive; for a more
15460 complete list of who has contributed to this manual see
15461 the file @file{doc/ChangeLog} in the @sc{cvs} source
15464 @c ---------------------------------------------------------------------
15466 @appendix Dealing with bugs in CVS or this manual
15468 @cindex Bugs in this manual or CVS
15469 Neither @sc{cvs} nor this manual is perfect, and they
15470 probably never will be. If you are having trouble
15471 using @sc{cvs}, or think you have found a bug, there
15472 are a number of things you can do about it. Note that
15473 if the manual is unclear, that can be considered a bug
15474 in the manual, so these problems are often worth doing
15475 something about as well as problems with @sc{cvs} itself.
15477 @cindex Reporting bugs
15478 @cindex Bugs, reporting
15479 @cindex Errors, reporting
15482 If you want someone to help you and fix bugs that you
15483 report, there are companies which will do that for a
15484 fee. One such company is:
15487 @cindex Support, getting CVS support
15491 Harrisburg, PA 17104-1657
15493 Email: info@@ximbiot.com
15494 Phone: (717) 579-6168
15495 Fax: (717) 234-3125
15496 @url{http://ximbiot.com/}
15501 If you got @sc{cvs} through a distributor, such as an
15502 operating system vendor or a vendor of freeware
15503 @sc{cd-rom}s, you may wish to see whether the
15504 distributor provides support. Often, they will provide
15505 no support or minimal support, but this may vary from
15506 distributor to distributor.
15509 If you have the skills and time to do so, you may wish
15510 to fix the bug yourself. If you wish to submit your
15511 fix for inclusion in future releases of @sc{cvs}, see
15512 the file @sc{hacking} in the @sc{cvs} source
15513 distribution. It contains much more information on the
15514 process of submitting fixes.
15517 There may be resources on the net which can help. Two
15518 good places to start are:
15521 @url{http://www.cvshome.org}
15524 If you are so inspired, increasing the information
15525 available on the net is likely to be appreciated. For
15526 example, before the standard @sc{cvs} distribution
15527 worked on Windows 95, there was a web page with some
15528 explanation and patches for running @sc{cvs} on Windows
15529 95, and various people helped out by mentioning this
15530 page on mailing lists or newsgroups when the subject
15534 It is also possible to report bugs to @email{bug-cvs@@gnu.org}.
15535 Note that someone may or may not want to do anything
15536 with your bug report---if you need a solution consider
15537 one of the options mentioned above. People probably do
15538 want to hear about bugs which are particularly severe
15539 in consequences and/or easy to fix, however. You can
15540 also increase your odds by being as clear as possible
15541 about the exact nature of the bug and any other
15542 relevant information. The way to report bugs is to
15543 send email to @email{bug-cvs@@gnu.org}. Note
15544 that submissions to @email{bug-cvs@@gnu.org} may be distributed
15545 under the terms of the @sc{gnu} Public License, so if
15546 you don't like this, don't submit them. There is
15547 usually no justification for sending mail directly to
15548 one of the @sc{cvs} maintainers rather than to
15549 @email{bug-cvs@@gnu.org}; those maintainers who want to hear
15550 about such bug reports read @email{bug-cvs@@gnu.org}. Also note
15551 that sending a bug report to other mailing lists or
15552 newsgroups is @emph{not} a substitute for sending it to
15553 @email{bug-cvs@@gnu.org}. It is fine to discuss @sc{cvs} bugs on
15554 whatever forum you prefer, but there are not
15555 necessarily any maintainers reading bug reports sent
15556 anywhere except @email{bug-cvs@@gnu.org}.
15559 @cindex Known bugs in this manual or CVS
15560 People often ask if there is a list of known bugs or
15561 whether a particular bug is a known one. The file
15562 @sc{bugs} in the @sc{cvs} source distribution is one
15563 list of known bugs, but it doesn't necessarily try to
15564 be comprehensive. Perhaps there will never be a
15565 comprehensive, detailed list of known bugs.
15567 @c ---------------------------------------------------------------------