File: cvs.passfirst

package info (click to toggle)
texi2html 1.82%2Bdfsg1-7
links: PTS, VCS
area: main
in suites: bookworm, forky, sid, trixie
size: 35,264 kB
sloc: perl: 15,901; xml: 6,075; sh: 3,977; makefile: 501
file content (14330 lines) | stat: -rw-r--r-- 742,953 bytes
parent folder | download | duplicates (6)
cvs.texi(,2) @comment Documentation for CVS.
cvs.texi(,3) @setfilename cvs.info
cvs.texi(,38) 
cvs.texi(,39) @comment This file is part of the CVS distribution.
cvs.texi(,40) 
cvs.texi(,41) @comment CVS is free software; you can redistribute it and/or modify
cvs.texi(,42) @comment it under the terms of the GNU General Public License as published by
cvs.texi(,43) @comment the Free Software Foundation; either version 2, or (at your option)
cvs.texi(,44) @comment any later version.
cvs.texi(,45) 
cvs.texi(,46) @comment CVS is distributed in the hope that it will be useful,
cvs.texi(,47) @comment but WITHOUT ANY WARRANTY; without even the implied warranty of
cvs.texi(,48) @comment MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
cvs.texi(,49) @comment GNU General Public License for more details.
cvs.texi(,50) 
cvs.texi(,51) @c See ../README for A4 vs. US letter size.
cvs.texi(,52) @c When we provided A4 postscript, and people tried to
cvs.texi(,53) @c print it on US letter, the usual complaint was that the
cvs.texi(,54) @c page numbers would get cut off.
cvs.texi(,55) @c If one prints US letter on A4, reportedly there is
cvs.texi(,56) @c some extra space at the top and/or bottom, and the side
cvs.texi(,57) @c margins are a bit narrow, but no text is lost.
cvs.texi(,58) @c
cvs.texi(,59) @c See
cvs.texi(,60) @c http://www.ft.uni-erlangen.de/~mskuhn/iso-paper.html
cvs.texi(,61) @c for more on paper sizes.  Insuring that margins are
cvs.texi(,62) @c big enough to print on either A4 or US letter does
cvs.texi(,63) @c indeed seem to be the usual approach (RFC2346).
cvs.texi(,64) 
cvs.texi(,65) @c This document seems to get overfull hboxes with some
cvs.texi(,66) @c frequency (probably because the tendency is to
cvs.texi(,67) @c sanity-check it with "make info" and run TeX less
cvs.texi(,68) @c often).  The big ugly boxes just seem to add insult
cvs.texi(,69) @c to injury, and I'm not aware of them helping to fix
cvs.texi(,70) @c the overfull hboxes at all.
cvs.texi(,71) @finalout
cvs.texi(,72) 
version.texi(,1) @set UPDATED 28 March 2002
version.texi(,2) @set UPDATED-MONTH March 2002
version.texi(,3) @set EDITION 4.2
version.texi(,4) @set VERSION 4.2
cvs.texi(,74) @settitle CVS---Concurrent Versions System v4.2
cvs.texi(,75) @setchapternewpage odd
cvs.texi(,76) 
cvs.texi(,77) @c -- TODO list:
cvs.texi(,78) @c -- Fix all lines that match "^@c -- "
cvs.texi(,79) @c -- Also places marked with FIXME should be manual
cvs.texi(,80) @c problems (as opposed to FIXCVS for CVS problems).
cvs.texi(,81) 
cvs.texi(,82) @c @splitrcskeyword{} is used to avoid keyword expansion.  It is replaced by
cvs.texi(,83) @c @asis when generating info and dvi, and by <i></i> in the generated html,
cvs.texi(,84) @c such that keywords are not expanded in the generated html. 
cvs.texi(,90) 
cvs.texi(,96) 
cvs.texi(,97) @dircategory GNU Packages
cvs.texi(,101) @dircategory Individual utilities
cvs.texi(,105) 
cvs.texi(,106) @comment The titlepage section does not appear in the Info file.
cvs.texi(,127) 
cvs.texi(,128) @comment ================================================================
cvs.texi(,129) @comment                   The real text starts here
cvs.texi(,130) @comment ================================================================
cvs.texi(,131) 
cvs.texi(,133) @c ---------------------------------------------------------------------
cvs.texi(,134) @node    Top
cvs.texi(,135) @top
cvs.texi(,136) 
cvs.texi(,137) This info manual describes how to use and administer
cvs.texi(,138) @sc{cvs} version 4.2.
cvs.texi(,140) 
cvs.texi(,144) 
cvs.texi(,145) @c This menu is pretty long.  Not sure how easily that
cvs.texi(,146) @c can be fixed (no brilliant ideas right away)...
cvs.texi(,147) @menu
cvs.texi(,148) * Overview::                    An introduction to CVS
cvs.texi(,149) * Repository::                  Where all your sources are stored
cvs.texi(,150) * Starting a new project::      Starting a project with CVS
cvs.texi(,151) * Revisions::                   Numeric and symbolic names for revisions
cvs.texi(,152) * Branching and merging::       Diverging/rejoining branches of development
cvs.texi(,153) * Recursive behavior::          CVS descends directories
cvs.texi(,154) * Adding and removing::         Adding/removing/renaming files/directories
cvs.texi(,155) * History browsing::            Viewing the history of files in various ways
cvs.texi(,156) 
cvs.texi(,157) CVS and the Real World.
cvs.texi(,158) -----------------------
cvs.texi(,159) * Binary files::                CVS can handle binary files
cvs.texi(,160) * Multiple developers::         How CVS helps a group of developers
cvs.texi(,161) * Revision management::         Policy questions for revision management
cvs.texi(,162) * Keyword substitution::        CVS can include the revision inside the file
cvs.texi(,163) * Tracking sources::            Tracking third-party sources
cvs.texi(,164) * Builds::                      Issues related to CVS and builds
cvs.texi(,165) * Special Files::		Devices, links and other non-regular files
cvs.texi(,166) 
cvs.texi(,167) References.
cvs.texi(,168) -----------
cvs.texi(,169) * CVS commands::                CVS commands share some things
cvs.texi(,170) * Invoking CVS::                Quick reference to CVS commands
cvs.texi(,171) * Administrative files::        Reference manual for the Administrative files
cvs.texi(,172) * Environment variables::       All environment variables which affect CVS
cvs.texi(,173) * Compatibility::               Upgrading CVS versions
cvs.texi(,174) * Troubleshooting::             Some tips when nothing works
cvs.texi(,175) * Credits::                     Some of the contributors to this manual
cvs.texi(,176) * BUGS::                        Dealing with bugs in CVS or this manual
cvs.texi(,177) * Index::                       Index
cvs.texi(,178) @end menu
cvs.texi(,179) 
cvs.texi(,180) @c ---------------------------------------------------------------------
cvs.texi(,181) @node Overview
cvs.texi(,182) @chapter Overview
cvs.texi(,183) @cindex Overview
cvs.texi(,184) 
cvs.texi(,185) This chapter is for people who have never used
cvs.texi(,186) @sc{cvs}, and perhaps have never used version control
cvs.texi(,187) software before.
cvs.texi(,188) 
cvs.texi(,189) If you are already familiar with @sc{cvs} and are just
cvs.texi(,190) trying to learn a particular feature or remember a
cvs.texi(,191) certain command, you can probably skip everything here.
cvs.texi(,192) 
cvs.texi(,193) @menu
cvs.texi(,194) * What is CVS?::                What you can do with @sc{cvs}
cvs.texi(,195) * What is CVS not?::            Problems @sc{cvs} doesn't try to solve
cvs.texi(,196) * A sample session::            A tour of basic @sc{cvs} usage
cvs.texi(,197) @end menu
cvs.texi(,198) 
cvs.texi(,199) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,200) @node What is CVS?
cvs.texi(,201) @section What is CVS?
cvs.texi(,202) @cindex What is CVS?
cvs.texi(,203) @cindex Introduction to CVS
cvs.texi(,204) @cindex CVS, introduction to
cvs.texi(,205) 
cvs.texi(,206) @sc{cvs} is a version control system.  Using it, you can
cvs.texi(,207) record the history of your source files.
cvs.texi(,208) 
cvs.texi(,209) @c -- ///
cvs.texi(,210) @c -- ///Those who cannot remember the past are condemned to repeat it.
cvs.texi(,211) @c -- ///               -- George Santayana
cvs.texi(,212) @c -- //////
cvs.texi(,213) 
cvs.texi(,214) @c -- Insert history  quote here!
cvs.texi(,215) For example, bugs sometimes creep in when
cvs.texi(,216) software is modified, and you might not detect the bug
cvs.texi(,217) until a long time after you make the modification.
cvs.texi(,218) With @sc{cvs}, you can easily retrieve old versions to see
cvs.texi(,219) exactly which change caused the bug.  This can
cvs.texi(,220) sometimes be a big help.
cvs.texi(,221) 
cvs.texi(,222) You could of course save every version of every file
cvs.texi(,223) you have ever created.  This would
cvs.texi(,224) however waste an enormous amount of disk space.  @sc{cvs}
cvs.texi(,225) stores all the versions of a file in a single file in a
cvs.texi(,226) clever way that only stores the differences between
cvs.texi(,227) versions.
cvs.texi(,228) 
cvs.texi(,229) @sc{cvs} also helps you if you are part of a group of people working
cvs.texi(,230) on the same project.  It is all too easy to overwrite
cvs.texi(,231) each others' changes unless you are extremely careful.
cvs.texi(,232) Some editors, like @sc{gnu} Emacs, try to make sure that
cvs.texi(,233) the same file is never modified by two people at the
cvs.texi(,234) same time.  Unfortunately, if someone is using another
cvs.texi(,235) editor, that safeguard will not work.  @sc{cvs} solves this problem
cvs.texi(,236) by insulating the different developers from each other.  Every
cvs.texi(,237) developer works in his own directory, and @sc{cvs} merges
cvs.texi(,238) the work when each developer is done.
cvs.texi(,239) 
cvs.texi(,240) @cindex History of CVS
cvs.texi(,241) @cindex CVS, history of
cvs.texi(,242) @cindex Credits (CVS program)
cvs.texi(,243) @cindex Contributors (CVS program)
cvs.texi(,244) @sc{cvs} started out as a bunch of shell scripts written by
cvs.texi(,245) Dick Grune, posted to the newsgroup
cvs.texi(,246) @code{comp.sources.unix} in the volume 6
cvs.texi(,247) release of July, 1986.  While no actual code from
cvs.texi(,248) these shell scripts is present in the current version
cvs.texi(,249) of @sc{cvs} much of the @sc{cvs} conflict resolution algorithms
cvs.texi(,250) come from them.
cvs.texi(,251) 
cvs.texi(,252) In April, 1989, Brian Berliner designed and coded @sc{cvs}.
cvs.texi(,253) Jeff Polk later helped Brian with the design of the @sc{cvs}
cvs.texi(,254) module and vendor branch support.
cvs.texi(,255) 
cvs.texi(,256) @cindex Source, getting CVS source
cvs.texi(,257) You can get @sc{cvs} in a variety of ways, including
cvs.texi(,258) free download from the internet.  For more information
cvs.texi(,259) on downloading @sc{cvs} and other @sc{cvs} topics, see:
cvs.texi(,260) 
cvs.texi(,261) @example
cvs.texi(,262) http://www.cvshome.org/
cvs.texi(,263) http://www.loria.fr/~molli/cvs-index.html
cvs.texi(,264) @end example
cvs.texi(,265) 
cvs.texi(,266) @cindex Mailing list
cvs.texi(,267) @cindex List, mailing list
cvs.texi(,268) @cindex Newsgroups
cvs.texi(,269) There is a mailing list, known as @w{@code{info-cvs}},
cvs.texi(,270) devoted to @sc{cvs}.  To subscribe or
cvs.texi(,271) unsubscribe
cvs.texi(,272) write to
cvs.texi(,273) @w{@code{info-cvs-request@@gnu.org}}.
cvs.texi(,274) If you prefer a usenet group, the right
cvs.texi(,275) group is @code{comp.software.config-mgmt} which is for
cvs.texi(,276) @sc{cvs} discussions (along with other configuration
cvs.texi(,277) management systems).  In the future, it might be
cvs.texi(,278) possible to create a
cvs.texi(,279) @code{comp.software.config-mgmt.cvs}, but probably only
cvs.texi(,280) if there is sufficient @sc{cvs} traffic on
cvs.texi(,281) @code{comp.software.config-mgmt}.
cvs.texi(,282) @c Other random data is that past attempts to create a
cvs.texi(,283) @c gnu.* group have failed (the relevant authorities
cvs.texi(,284) @c say they'll do it, but don't), and that tale was very
cvs.texi(,285) @c skeptical of comp.software.config-mgmt.cvs when the
cvs.texi(,286) @c subject came up around 1995 or so (for one
cvs.texi(,287) @c thing, because creating it would be a "reorg" which
cvs.texi(,288) @c would need to take a more comprehensive look at the
cvs.texi(,289) @c whole comp.software.config-mgmt.* hierarchy).
cvs.texi(,290) 
cvs.texi(,291) You can also subscribe to the @code{bug-cvs} mailing list,
cvs.texi(,292) described in more detail in @ref{BUGS}.  To subscribe
cvs.texi(,293) send mail to @code{bug-cvs-request@@gnu.org}.
cvs.texi(,294) 
cvs.texi(,295) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,296) @node What is CVS not?
cvs.texi(,297) @section What is CVS not?
cvs.texi(,298) @cindex What is CVS not?
cvs.texi(,299) 
cvs.texi(,300) @sc{cvs} can do a lot of things for you, but it does
cvs.texi(,301) not try to be everything for everyone.
cvs.texi(,302) 
cvs.texi(,303) @table @asis
cvs.texi(,304) @item @sc{cvs} is not a build system.
cvs.texi(,305) 
cvs.texi(,306) Though the structure of your repository and modules
cvs.texi(,307) file interact with your build system
cvs.texi(,308) (e.g. @file{Makefile}s), they are essentially
cvs.texi(,309) independent.
cvs.texi(,310) 
cvs.texi(,311) @sc{cvs} does not dictate how you build anything.  It
cvs.texi(,312) merely stores files for retrieval in a tree structure
cvs.texi(,313) you devise.
cvs.texi(,314) 
cvs.texi(,315) @sc{cvs} does not dictate how to use disk space in the
cvs.texi(,316) checked out working directories.  If you write your
cvs.texi(,317) @file{Makefile}s or scripts in every directory so they
cvs.texi(,318) have to know the relative positions of everything else,
cvs.texi(,319) you wind up requiring the entire repository to be
cvs.texi(,320) checked out.
cvs.texi(,321) 
cvs.texi(,322) If you modularize your work, and construct a build
cvs.texi(,323) system that will share files (via links, mounts,
cvs.texi(,324) @code{VPATH} in @file{Makefile}s, etc.), you can
cvs.texi(,325) arrange your disk usage however you like.
cvs.texi(,326) 
cvs.texi(,327) But you have to remember that @emph{any} such system is
cvs.texi(,328) a lot of work to construct and maintain.  @sc{cvs} does
cvs.texi(,329) not address the issues involved.
cvs.texi(,330) 
cvs.texi(,331) Of course, you should place the tools created to
cvs.texi(,332) support such a build system (scripts, @file{Makefile}s,
cvs.texi(,333) etc) under @sc{cvs}.
cvs.texi(,334) 
cvs.texi(,335) Figuring out what files need to be rebuilt when
cvs.texi(,336) something changes is, again, something to be handled
cvs.texi(,337) outside the scope of @sc{cvs}.  One traditional
cvs.texi(,338) approach is to use @code{make} for building, and use
cvs.texi(,339) some automated tool for generating the dependencies which
cvs.texi(,340) @code{make} uses.
cvs.texi(,341) 
cvs.texi(,342) See @ref{Builds}, for more information on doing builds
cvs.texi(,343) in conjunction with @sc{cvs}.
cvs.texi(,344) 
cvs.texi(,345) @item @sc{cvs} is not a substitute for management.
cvs.texi(,346) 
cvs.texi(,347) Your managers and project leaders are expected to talk
cvs.texi(,348) to you frequently enough to make certain you are aware
cvs.texi(,349) of schedules, merge points, branch names and release
cvs.texi(,350) dates.  If they don't, @sc{cvs} can't help.
cvs.texi(,351) 
cvs.texi(,352) @sc{cvs} is an instrument for making sources dance to
cvs.texi(,353) your tune.  But you are the piper and the composer.  No
cvs.texi(,354) instrument plays itself or writes its own music.
cvs.texi(,355) 
cvs.texi(,356) @item @sc{cvs} is not a substitute for developer communication.
cvs.texi(,357) 
cvs.texi(,358) When faced with conflicts within a single file, most
cvs.texi(,359) developers manage to resolve them without too much
cvs.texi(,360) effort.  But a more general definition of ``conflict''
cvs.texi(,361) includes problems too difficult to solve without
cvs.texi(,362) communication between developers.
cvs.texi(,363) 
cvs.texi(,364) @sc{cvs} cannot determine when simultaneous changes
cvs.texi(,365) within a single file, or across a whole collection of
cvs.texi(,366) files, will logically conflict with one another.  Its
cvs.texi(,367) concept of a @dfn{conflict} is purely textual, arising
cvs.texi(,368) when two changes to the same base file are near enough
cvs.texi(,369) to spook the merge (i.e. @code{diff3}) command.
cvs.texi(,370) 
cvs.texi(,371) @sc{cvs} does not claim to help at all in figuring out
cvs.texi(,372) non-textual or distributed conflicts in program logic.
cvs.texi(,373) 
cvs.texi(,374) For example: Say you change the arguments to function
cvs.texi(,375) @code{X} defined in file @file{A}.  At the same time,
cvs.texi(,376) someone edits file @file{B}, adding new calls to
cvs.texi(,377) function @code{X} using the old arguments.  You are
cvs.texi(,378) outside the realm of @sc{cvs}'s competence.
cvs.texi(,379) 
cvs.texi(,380) Acquire the habit of reading specs and talking to your
cvs.texi(,381) peers.
cvs.texi(,382) 
cvs.texi(,383) 
cvs.texi(,384) @item @sc{cvs} does not have change control
cvs.texi(,385) 
cvs.texi(,386) Change control refers to a number of things.  First of
cvs.texi(,387) all it can mean @dfn{bug-tracking}, that is being able
cvs.texi(,388) to keep a database of reported bugs and the status of
cvs.texi(,389) each one (is it fixed?  in what release?  has the bug
cvs.texi(,390) submitter agreed that it is fixed?).  For interfacing
cvs.texi(,391) @sc{cvs} to an external bug-tracking system, see the
cvs.texi(,392) @file{rcsinfo} and @file{verifymsg} files
cvs.texi(,393) (@pxref{Administrative files}).
cvs.texi(,394) 
cvs.texi(,395) Another aspect of change control is keeping track of
cvs.texi(,396) the fact that changes to several files were in fact
cvs.texi(,397) changed together as one logical change.  If you check
cvs.texi(,398) in several files in a single @code{cvs commit}
cvs.texi(,399) operation, @sc{cvs} then forgets that those files were
cvs.texi(,400) checked in together, and the fact that they have the
cvs.texi(,401) same log message is the only thing tying them
cvs.texi(,402) together.  Keeping a @sc{gnu} style @file{ChangeLog}
cvs.texi(,403) can help somewhat.
cvs.texi(,404) @c FIXME: should have an xref to a section which talks
cvs.texi(,405) @c more about keeping ChangeLog's with CVS, but that
cvs.texi(,406) @c section hasn't been written yet.
cvs.texi(,407) 
cvs.texi(,408) Another aspect of change control, in some systems, is
cvs.texi(,409) the ability to keep track of the status of each
cvs.texi(,410) change.  Some changes have been written by a developer,
cvs.texi(,411) others have been reviewed by a second developer, and so
cvs.texi(,412) on.  Generally, the way to do this with @sc{cvs} is to
cvs.texi(,413) generate a diff (using @code{cvs diff} or @code{diff})
cvs.texi(,414) and email it to someone who can then apply it using the
cvs.texi(,415) @code{patch} utility.  This is very flexible, but
cvs.texi(,416) depends on mechanisms outside @sc{cvs} to make sure
cvs.texi(,417) nothing falls through the cracks.
cvs.texi(,418) 
cvs.texi(,419) @item @sc{cvs} is not an automated testing program
cvs.texi(,420) 
cvs.texi(,421) It should be possible to enforce mandatory use of a
cvs.texi(,422) testsuite using the @code{commitinfo} file.  I haven't
cvs.texi(,423) heard a lot about projects trying to do that or whether
cvs.texi(,424) there are subtle gotchas, however.
cvs.texi(,425) 
cvs.texi(,426) @item @sc{cvs} does not have a builtin process model
cvs.texi(,427) 
cvs.texi(,428) Some systems provide ways to ensure that changes or
cvs.texi(,429) releases go through various steps, with various
cvs.texi(,430) approvals as needed.  Generally, one can accomplish
cvs.texi(,431) this with @sc{cvs} but it might be a little more work.
cvs.texi(,432) In some cases you'll want to use the @file{commitinfo},
cvs.texi(,433) @file{loginfo}, @file{rcsinfo}, or @file{verifymsg}
cvs.texi(,434) files, to require that certain steps be performed
cvs.texi(,435) before cvs will allow a checkin.  Also consider whether
cvs.texi(,436) features such as branches and tags can be used to
cvs.texi(,437) perform tasks such as doing work in a development tree
cvs.texi(,438) and then merging certain changes over to a stable tree
cvs.texi(,439) only once they have been proven.
cvs.texi(,440) @end table
cvs.texi(,441) 
cvs.texi(,442) @c ---------------------------------------------------------------------
cvs.texi(,443) @node A sample session
cvs.texi(,444) @section A sample session
cvs.texi(,445) @cindex Example of a work-session
cvs.texi(,446) @cindex Getting started
cvs.texi(,447) @cindex Work-session, example of
cvs.texi(,448) @cindex tc, Trivial Compiler (example)
cvs.texi(,449) @cindex Trivial Compiler (example)
cvs.texi(,450) 
cvs.texi(,451) @c I think an example is a pretty good way to start.  But
cvs.texi(,452) @c somewhere in here, maybe after the sample session,
cvs.texi(,453) @c we need something which is kind of
cvs.texi(,454) @c a "roadmap" which is more directed at sketching out
cvs.texi(,455) @c the functionality of CVS and pointing people to
cvs.texi(,456) @c various other parts of the manual.  As it stands now
cvs.texi(,457) @c people who read in order get dumped right into all
cvs.texi(,458) @c manner of hair regarding remote repositories,
cvs.texi(,459) @c creating a repository, etc.
cvs.texi(,460) @c
cvs.texi(,461) @c The following was in the old Basic concepts node.  I don't
cvs.texi(,462) @c know how good a job it does at introducing modules,
cvs.texi(,463) @c or whether they need to be introduced so soon, but
cvs.texi(,464) @c something of this sort might go into some
cvs.texi(,465) @c introductory material somewhere.
cvs.texi(,474) 
cvs.texi(,475) As a way of introducing @sc{cvs}, we'll go through a
cvs.texi(,476) typical work-session using @sc{cvs}.  The first thing
cvs.texi(,477) to understand is that @sc{cvs} stores all files in a
cvs.texi(,478) centralized @dfn{repository} (@pxref{Repository}); this
cvs.texi(,479) section assumes that a repository is set up.
cvs.texi(,480) @c I'm not sure that the sentence concerning the
cvs.texi(,481) @c repository quite tells the user what they need to
cvs.texi(,482) @c know at this point.  Might need to expand on "centralized"
cvs.texi(,483) @c slightly (maybe not here, maybe further down in the example?)
cvs.texi(,484) 
cvs.texi(,485) Suppose you are working on a simple compiler.  The source
cvs.texi(,486) consists of a handful of C files and a @file{Makefile}.
cvs.texi(,487) The compiler is called @samp{tc} (Trivial Compiler),
cvs.texi(,488) and the repository is set up so that there is a module
cvs.texi(,489) called @samp{tc}.
cvs.texi(,490) 
cvs.texi(,491) @menu
cvs.texi(,492) * Getting the source::          Creating a workspace
cvs.texi(,493) * Committing your changes::     Making your work available to others
cvs.texi(,494) * Cleaning up::                 Cleaning up
cvs.texi(,495) * Viewing differences::         Viewing differences
cvs.texi(,496) @end menu
cvs.texi(,497) 
cvs.texi(,498) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,499) @node Getting the source
cvs.texi(,500) @subsection Getting the source
cvs.texi(,501) @cindex Getting the source
cvs.texi(,502) @cindex Checking out source
cvs.texi(,503) @cindex Fetching source
cvs.texi(,504) @cindex Source, getting from CVS
cvs.texi(,505) @cindex Checkout, example
cvs.texi(,506) 
cvs.texi(,507) The first thing you must do is to get your own working copy of the
cvs.texi(,508) source for @samp{tc}.  For this, you use the @code{checkout} command:
cvs.texi(,509) 
cvs.texi(,510) @example
cvs.texi(,511) $ cvs checkout tc
cvs.texi(,512) @end example
cvs.texi(,513) 
cvs.texi(,514) @noindent
cvs.texi(,515) This will create a new directory called @file{tc} and populate it with
cvs.texi(,516) the source files.
cvs.texi(,517) 
cvs.texi(,518) @example
cvs.texi(,519) $ cd tc
cvs.texi(,520) $ ls
cvs.texi(,521) CVS         Makefile    backend.c   driver.c    frontend.c  parser.c
cvs.texi(,522) @end example
cvs.texi(,523) 
cvs.texi(,524) The @file{CVS} directory is used internally by
cvs.texi(,525) @sc{cvs}.  Normally, you should not modify or remove
cvs.texi(,526) any of the files in it.
cvs.texi(,527) 
cvs.texi(,528) You start your favorite editor, hack away at @file{backend.c}, and a couple
cvs.texi(,529) of hours later you have added an optimization pass to the compiler.
cvs.texi(,530) A note to @sc{rcs} and @sc{sccs} users: There is no need to lock the files that
cvs.texi(,531) you want to edit.  @xref{Multiple developers}, for an explanation.
cvs.texi(,532) 
cvs.texi(,533) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,534) @node Committing your changes
cvs.texi(,535) @subsection Committing your changes
cvs.texi(,536) @cindex Committing changes to files
cvs.texi(,537) @cindex Log message entry
cvs.texi(,538) 
cvs.texi(,539) When you have checked that the compiler is still compilable you decide
cvs.texi(,540) to make a new version of @file{backend.c}.  This will
cvs.texi(,541) store your new @file{backend.c} in the repository and
cvs.texi(,542) make it available to anyone else who is using that same
cvs.texi(,543) repository.
cvs.texi(,544) 
cvs.texi(,545) @example
cvs.texi(,546) $ cvs commit backend.c
cvs.texi(,547) @end example
cvs.texi(,548) 
cvs.texi(,549) @noindent
cvs.texi(,550) @sc{cvs} starts an editor, to allow you to enter a log
cvs.texi(,551) message.  You type in ``Added an optimization pass.'',
cvs.texi(,552) save the temporary file, and exit the editor.
cvs.texi(,553) 
cvs.texi(,554) @cindex CVSEDITOR, environment variable
cvs.texi(,555) @cindex EDITOR, environment variable
cvs.texi(,556) The environment variable @code{$CVSEDITOR} determines
cvs.texi(,557) which editor is started.  If @code{$CVSEDITOR} is not
cvs.texi(,558) set, then if the environment variable @code{$EDITOR} is
cvs.texi(,559) set, it will be used. If both @code{$CVSEDITOR} and
cvs.texi(,560) @code{$EDITOR} are not set then there is a default
cvs.texi(,561) which will vary with your operating system, for example
cvs.texi(,562) @code{vi} for unix or @code{notepad} for Windows
cvs.texi(,563) NT/95.
cvs.texi(,564) 
cvs.texi(,565) @cindex VISUAL, environment variable
cvs.texi(,566) In addition, @sc{cvs} checks the @code{$VISUAL} environment
cvs.texi(,567) variable.  Opinions vary on whether this behavior is desirable and
cvs.texi(,568) whether future releases of @sc{cvs} should check @code{$VISUAL} or
cvs.texi(,569) ignore it.  You will be OK either way if you make sure that
cvs.texi(,570) @code{$VISUAL} is either unset or set to the same thing as
cvs.texi(,571) @code{$EDITOR}.
cvs.texi(,572) 
cvs.texi(,573) @c This probably should go into some new node
cvs.texi(,574) @c containing detailed info on the editor, rather than
cvs.texi(,575) @c the intro.  In fact, perhaps some of the stuff with
cvs.texi(,576) @c CVSEDITOR and -m and so on should too.
cvs.texi(,577) When @sc{cvs} starts the editor, it includes a list of
cvs.texi(,578) files which are modified.  For the @sc{cvs} client,
cvs.texi(,579) this list is based on comparing the modification time
cvs.texi(,580) of the file against the modification time that the file
cvs.texi(,581) had when it was last gotten or updated.  Therefore, if
cvs.texi(,582) a file's modification time has changed but its contents
cvs.texi(,583) have not, it will show up as modified.  The simplest
cvs.texi(,584) way to handle this is simply not to worry about it---if
cvs.texi(,585) you proceed with the commit @sc{cvs} will detect that
cvs.texi(,586) the contents are not modified and treat it as an
cvs.texi(,587) unmodified file.  The next @code{update} will clue
cvs.texi(,588) @sc{cvs} in to the fact that the file is unmodified,
cvs.texi(,589) and it will reset its stored timestamp so that the file
cvs.texi(,590) will not show up in future editor sessions.
cvs.texi(,591) @c FIXCVS: Might be nice if "commit" and other commands
cvs.texi(,592) @c would reset that timestamp too, but currently commit
cvs.texi(,593) @c doesn't.
cvs.texi(,594) @c FIXME: Need to talk more about the process of
cvs.texi(,595) @c prompting for the log message.  Like show an example
cvs.texi(,596) @c of what it pops up in the editor, for example.  Also
cvs.texi(,597) @c a discussion of how to get the "a)bort, c)ontinue,
cvs.texi(,598) @c e)dit" prompt and what to do with it.  Might also
cvs.texi(,599) @c work in the suggestion that if you want a diff, you
cvs.texi(,600) @c should make it before running commit (someone
cvs.texi(,601) @c suggested that the diff pop up in the editor.  I'm
cvs.texi(,602) @c not sure that is better than telling people to run
cvs.texi(,603) @c "cvs diff" first if that is what they want, but if
cvs.texi(,604) @c we want to tell people that, the manual possibly
cvs.texi(,605) @c should say it).
cvs.texi(,606) 
cvs.texi(,607) If you want to avoid
cvs.texi(,608) starting an editor you can specify the log message on
cvs.texi(,609) the command line using the @samp{-m} flag instead, like
cvs.texi(,610) this:
cvs.texi(,611) 
cvs.texi(,612) @example
cvs.texi(,613) $ cvs commit -m "Added an optimization pass" backend.c
cvs.texi(,614) @end example
cvs.texi(,615) 
cvs.texi(,616) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,617) @node Cleaning up
cvs.texi(,618) @subsection Cleaning up
cvs.texi(,619) @cindex Cleaning up
cvs.texi(,620) @cindex Working copy, removing
cvs.texi(,621) @cindex Removing your working copy
cvs.texi(,622) @cindex Releasing your working copy
cvs.texi(,623) 
cvs.texi(,624) Before you turn to other tasks you decide to remove your working copy of
cvs.texi(,625) tc.  One acceptable way to do that is of course
cvs.texi(,626) 
cvs.texi(,627) @example
cvs.texi(,628) $ cd ..
cvs.texi(,629) $ rm -r tc
cvs.texi(,630) @end example
cvs.texi(,631) 
cvs.texi(,632) @noindent
cvs.texi(,633) but a better way is to use the @code{release} command (@pxref{release}):
cvs.texi(,634) 
cvs.texi(,635) @example
cvs.texi(,636) $ cd ..
cvs.texi(,637) $ cvs release -d tc
cvs.texi(,638) M driver.c
cvs.texi(,639) ? tc
cvs.texi(,640) You have [1] altered files in this repository.
cvs.texi(,641) Are you sure you want to release (and delete) directory `tc': n
cvs.texi(,642) ** `release' aborted by user choice.
cvs.texi(,643) @end example
cvs.texi(,644) 
cvs.texi(,645) The @code{release} command checks that all your modifications have been
cvs.texi(,646) committed.  If history logging is enabled it also makes a note in the
cvs.texi(,647) history file.  @xref{history file}.
cvs.texi(,648) 
cvs.texi(,649) When you use the @samp{-d} flag with @code{release}, it
cvs.texi(,650) also removes your working copy.
cvs.texi(,651) 
cvs.texi(,652) In the example above, the @code{release} command wrote a couple of lines
cvs.texi(,653) of output.  @samp{? tc} means that the file @file{tc} is unknown to @sc{cvs}.
cvs.texi(,654) That is nothing to worry about: @file{tc} is the executable compiler,
cvs.texi(,655) and it should not be stored in the repository.  @xref{cvsignore},
cvs.texi(,656) for information about how to make that warning go away.
cvs.texi(,657) @xref{release output}, for a complete explanation of
cvs.texi(,658) all possible output from @code{release}.
cvs.texi(,659) 
cvs.texi(,660) @samp{M driver.c} is more serious.  It means that the
cvs.texi(,661) file @file{driver.c} has been modified since it was
cvs.texi(,662) checked out.
cvs.texi(,663) 
cvs.texi(,664) The @code{release} command always finishes by telling
cvs.texi(,665) you how many modified files you have in your working
cvs.texi(,666) copy of the sources, and then asks you for confirmation
cvs.texi(,667) before deleting any files or making any note in the
cvs.texi(,668) history file.
cvs.texi(,669) 
cvs.texi(,670) You decide to play it safe and answer @kbd{n @key{RET}}
cvs.texi(,671) when @code{release} asks for confirmation.
cvs.texi(,672) 
cvs.texi(,673) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,674) @node Viewing differences
cvs.texi(,675) @subsection Viewing differences
cvs.texi(,676) @cindex Viewing differences
cvs.texi(,677) @cindex Diff
cvs.texi(,678) 
cvs.texi(,679) You do not remember modifying @file{driver.c}, so you want to see what
cvs.texi(,680) has happened to that file.
cvs.texi(,681) 
cvs.texi(,682) @example
cvs.texi(,683) $ cd tc
cvs.texi(,684) $ cvs diff driver.c
cvs.texi(,685) @end example
cvs.texi(,686) 
cvs.texi(,687) This command runs @code{diff} to compare the version of @file{driver.c}
cvs.texi(,688) that you checked out with your working copy.  When you see the output
cvs.texi(,689) you remember that you added a command line option that enabled the
cvs.texi(,690) optimization pass.  You check it in, and release the module.
cvs.texi(,691) @c FIXME: we haven't yet defined the term "check in".
cvs.texi(,692) 
cvs.texi(,693) @example
cvs.texi(,694) $ cvs commit -m "Added an optimization pass" driver.c
cvs.texi(,695) Checking in driver.c;
cvs.texi(,696) /usr/local/cvsroot/tc/driver.c,v  <--  driver.c
cvs.texi(,697) new revision: 1.2; previous revision: 1.1
cvs.texi(,698) done
cvs.texi(,699) $ cd ..
cvs.texi(,700) $ cvs release -d tc
cvs.texi(,701) ? tc
cvs.texi(,702) You have [0] altered files in this repository.
cvs.texi(,703) Are you sure you want to release (and delete) directory `tc': y
cvs.texi(,704) @end example
cvs.texi(,705) 
cvs.texi(,706) @c ---------------------------------------------------------------------
cvs.texi(,707) @node Repository
cvs.texi(,708) @chapter The Repository
cvs.texi(,709) @cindex Repository (intro)
cvs.texi(,710) @cindex Repository, example
cvs.texi(,711) @cindex Layout of repository
cvs.texi(,712) @cindex Typical repository
cvs.texi(,713) @cindex /usr/local/cvsroot, as example repository
cvs.texi(,714) @cindex cvsroot
cvs.texi(,715) 
cvs.texi(,716) The @sc{cvs} @dfn{repository} stores a complete copy of
cvs.texi(,717) all the files and directories which are under version
cvs.texi(,718) control.
cvs.texi(,719) 
cvs.texi(,720) Normally, you never access any of the files in the
cvs.texi(,721) repository directly.  Instead, you use @sc{cvs}
cvs.texi(,722) commands to get your own copy of the files into a
cvs.texi(,723) @dfn{working directory}, and then
cvs.texi(,724) work on that copy.  When you've finished a set of
cvs.texi(,725) changes, you check (or @dfn{commit}) them back into the
cvs.texi(,726) repository.  The repository then contains the changes
cvs.texi(,727) which you have made, as well as recording exactly what
cvs.texi(,728) you changed, when you changed it, and other such
cvs.texi(,729) information.  Note that the repository is not a
cvs.texi(,730) subdirectory of the working directory, or vice versa;
cvs.texi(,731) they should be in separate locations.
cvs.texi(,732) @c Need some example, e.g. repository
cvs.texi(,733) @c /usr/local/cvsroot; working directory
cvs.texi(,734) @c /home/joe/sources.  But this node is too long
cvs.texi(,735) @c as it is; need a little reorganization...
cvs.texi(,736) 
cvs.texi(,737) @cindex :local:, setting up
cvs.texi(,738) @sc{cvs} can access a repository by a variety of
cvs.texi(,739) means.  It might be on the local computer, or it might
cvs.texi(,740) be on a computer across the room or across the world.
cvs.texi(,741) To distinguish various ways to access a repository, the
cvs.texi(,742) repository name can start with an @dfn{access method}.
cvs.texi(,743) For example, the access method @code{:local:} means to
cvs.texi(,744) access a repository directory, so the repository
cvs.texi(,745) @code{:local:/usr/local/cvsroot} means that the
cvs.texi(,746) repository is in @file{/usr/local/cvsroot} on the
cvs.texi(,747) computer running @sc{cvs}.  For information on other
cvs.texi(,748) access methods, see @ref{Remote repositories}.
cvs.texi(,749) 
cvs.texi(,750) @c Can se say this more concisely?  Like by passing
cvs.texi(,751) @c more of the buck to the Remote repositories node?
cvs.texi(,752) If the access method is omitted, then if the repository
cvs.texi(,753) starts with @samp{/}, then @code{:local:} is
cvs.texi(,754) assumed.  If it does not start with @samp{/} then either
cvs.texi(,755) @code{:ext:} or @code{:server:} is assumed.  For
cvs.texi(,756) example, if you have a local repository in
cvs.texi(,757) @file{/usr/local/cvsroot}, you can use
cvs.texi(,758) @code{/usr/local/cvsroot} instead of
cvs.texi(,759) @code{:local:/usr/local/cvsroot}.  But if (under
cvs.texi(,760) Windows NT, for example) your local repository is
cvs.texi(,761) @file{c:\src\cvsroot}, then you must specify the access
cvs.texi(,762) method, as in @code{:local:c:/src/cvsroot}.
cvs.texi(,763) 
cvs.texi(,764) @c This might appear to go in Repository storage, but
cvs.texi(,765) @c actually it is describing something which is quite
cvs.texi(,766) @c user-visible, when you do a "cvs co CVSROOT".  This
cvs.texi(,767) @c isn't necessary the perfect place for that, though.
cvs.texi(,768) The repository is split in two parts.  @file{$CVSROOT/CVSROOT} contains
cvs.texi(,769) administrative files for @sc{cvs}.  The other directories contain the actual
cvs.texi(,770) user-defined modules.
cvs.texi(,771) 
cvs.texi(,772) @menu
cvs.texi(,773) * Specifying a repository::     Telling CVS where your repository is
cvs.texi(,774) * Repository storage::          The structure of the repository
cvs.texi(,775) * Working directory storage::   The structure of working directories
cvs.texi(,776) * Intro administrative files::  Defining modules
cvs.texi(,777) * Multiple repositories::       Multiple repositories
cvs.texi(,778) * Creating a repository::       Creating a repository
cvs.texi(,779) * Backing up::                  Backing up a repository
cvs.texi(,780) * Moving a repository::         Moving a repository
cvs.texi(,781) * Remote repositories::         Accessing repositories on remote machines
cvs.texi(,782) * Read-only access::            Granting read-only access to the repository
cvs.texi(,783) * Server temporary directory::  The server creates temporary directories
cvs.texi(,784) @end menu
cvs.texi(,785) 
cvs.texi(,786) @node Specifying a repository
cvs.texi(,787) @section Telling CVS where your repository is
cvs.texi(,788) 
cvs.texi(,789) There are several ways to tell @sc{cvs}
cvs.texi(,790) where to find the repository.  You can name the
cvs.texi(,791) repository on the command line explicitly, with the
cvs.texi(,792) @code{-d} (for "directory") option:
cvs.texi(,793) 
cvs.texi(,794) @example
cvs.texi(,795) cvs -d /usr/local/cvsroot checkout yoyodyne/tc
cvs.texi(,796) @end example
cvs.texi(,797) 
cvs.texi(,798) @cindex .profile, setting CVSROOT in
cvs.texi(,799) @cindex .cshrc, setting CVSROOT in
cvs.texi(,800) @cindex .tcshrc, setting CVSROOT in
cvs.texi(,801) @cindex .bashrc, setting CVSROOT in
cvs.texi(,802) @cindex CVSROOT, environment variable
cvs.texi(,803)         Or you can set the @code{$CVSROOT} environment
cvs.texi(,804) variable to an absolute path to the root of the
cvs.texi(,805) repository, @file{/usr/local/cvsroot} in this example.
cvs.texi(,806) To set @code{$CVSROOT}, @code{csh} and @code{tcsh}
cvs.texi(,807) users should have this line in their @file{.cshrc} or
cvs.texi(,808) @file{.tcshrc} files:
cvs.texi(,809) 
cvs.texi(,810) @example
cvs.texi(,811) setenv CVSROOT /usr/local/cvsroot
cvs.texi(,812) @end example
cvs.texi(,813) 
cvs.texi(,814) @noindent
cvs.texi(,815) @code{sh} and @code{bash} users should instead have these lines in their
cvs.texi(,816) @file{.profile} or @file{.bashrc}:
cvs.texi(,817) 
cvs.texi(,818) @example
cvs.texi(,819) CVSROOT=/usr/local/cvsroot
cvs.texi(,820) export CVSROOT
cvs.texi(,821) @end example
cvs.texi(,822) 
cvs.texi(,823) @cindex Root file, in CVS directory
cvs.texi(,824) @cindex CVS/Root file
cvs.texi(,825)         A repository specified with @code{-d} will
cvs.texi(,826) override the @code{$CVSROOT} environment variable.
cvs.texi(,827) Once you've checked a working copy out from the
cvs.texi(,828) repository, it will remember where its repository is
cvs.texi(,829) (the information is recorded in the
cvs.texi(,830) @file{CVS/Root} file in the working copy).
cvs.texi(,831) 
cvs.texi(,832) The @code{-d} option and the @file{CVS/Root} file both
cvs.texi(,833) override the @code{$CVSROOT} environment variable.  If
cvs.texi(,834) @code{-d} option differs from @file{CVS/Root}, the
cvs.texi(,835) former is used.  Of course, for proper operation they
cvs.texi(,836) should be two ways of referring to the same repository.
cvs.texi(,837) 
cvs.texi(,838) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,839) @node Repository storage
cvs.texi(,840) @section How data is stored in the repository
cvs.texi(,841) @cindex Repository, how data is stored
cvs.texi(,842) 
cvs.texi(,843) For most purposes it isn't important @emph{how}
cvs.texi(,844) @sc{cvs} stores information in the repository.  In
cvs.texi(,845) fact, the format has changed in the past, and is likely
cvs.texi(,846) to change in the future.  Since in almost all cases one
cvs.texi(,847) accesses the repository via @sc{cvs} commands, such
cvs.texi(,848) changes need not be disruptive.
cvs.texi(,849) 
cvs.texi(,850) However, in some cases it may be necessary to
cvs.texi(,851) understand how @sc{cvs} stores data in the repository,
cvs.texi(,852) for example you might need to track down @sc{cvs} locks
cvs.texi(,853) (@pxref{Concurrency}) or you might need to deal with
cvs.texi(,854) the file permissions appropriate for the repository.
cvs.texi(,855) 
cvs.texi(,856) @menu
cvs.texi(,857) * Repository files::            What files are stored in the repository
cvs.texi(,858) * File permissions::            File permissions
cvs.texi(,859) * Windows permissions::         Issues specific to Windows
cvs.texi(,860) * Attic::                       Some files are stored in the Attic
cvs.texi(,861) * CVS in repository::           Additional information in CVS directory
cvs.texi(,862) * Locks::                       CVS locks control concurrent accesses
cvs.texi(,863) * CVSROOT storage::             A few things about CVSROOT are different
cvs.texi(,864) @end menu
cvs.texi(,865) 
cvs.texi(,866) @node Repository files
cvs.texi(,867) @subsection Where files are stored within the repository
cvs.texi(,868) 
cvs.texi(,869) @c @cindex Filenames, legal
cvs.texi(,870) @c @cindex Legal filenames
cvs.texi(,871) @c Somewhere we need to say something about legitimate
cvs.texi(,872) @c characters in filenames in working directory and
cvs.texi(,873) @c repository.  Not "/" (not even on non-unix).  And
cvs.texi(,874) @c here is a specific set of issues:
cvs.texi(,875) @c 	Files starting with a - are handled inconsistently. They can not
cvs.texi(,876) @c   be added to a repository with an add command, because it they are
cvs.texi(,877) @c   interpreted as a switch. They can appear in a repository if they are
cvs.texi(,878) @c   part of a tree that is imported. They can not be removed from the tree
cvs.texi(,879) @c   once they are there.
cvs.texi(,880) @c Note that "--" *is* supported (as a
cvs.texi(,881) @c consequence of using GNU getopt).  Should document
cvs.texi(,882) @c this somewhere ("Common options"?).  The other usual technique,
cvs.texi(,883) @c "./-foo", isn't as effective, at least for "cvs add"
cvs.texi(,884) @c which doesn't support pathnames containing "/".
cvs.texi(,885) 
cvs.texi(,886) The overall structure of the repository is a directory
cvs.texi(,887) tree corresponding to the directories in the working
cvs.texi(,888) directory.  For example, supposing the repository is in
cvs.texi(,889) 
cvs.texi(,890) @example
cvs.texi(,891) /usr/local/cvsroot
cvs.texi(,892) @end example
cvs.texi(,893) 
cvs.texi(,894) @noindent
cvs.texi(,895) here is a possible directory tree (showing only the
cvs.texi(,896) directories):
cvs.texi(,897) 
cvs.texi(,898) @example
cvs.texi(,899) @t{/usr}
cvs.texi(,900)  |
cvs.texi(,901)  +--@t{local}
cvs.texi(,902)  |   |
cvs.texi(,903)  |   +--@t{cvsroot}
cvs.texi(,904)  |   |    |
cvs.texi(,905)  |   |    +--@t{CVSROOT}
cvs.texi(,906)           |      (administrative files)
cvs.texi(,907)           |
cvs.texi(,908)           +--@t{gnu}
cvs.texi(,909)           |   |
cvs.texi(,910)           |   +--@t{diff}
cvs.texi(,911)           |   |   (source code to @sc{gnu} diff)
cvs.texi(,912)           |   |
cvs.texi(,913)           |   +--@t{rcs}
cvs.texi(,914)           |   |   (source code to @sc{rcs})
cvs.texi(,915)           |   |
cvs.texi(,916)           |   +--@t{cvs}
cvs.texi(,917)           |       (source code to @sc{cvs})
cvs.texi(,918)           |
cvs.texi(,919)           +--@t{yoyodyne}
cvs.texi(,920)               |
cvs.texi(,921)               +--@t{tc}
cvs.texi(,922)               |    |
cvs.texi(,923)               |    +--@t{man}
cvs.texi(,924)               |    |
cvs.texi(,925)               |    +--@t{testing}
cvs.texi(,926)               |
cvs.texi(,927)               +--(other Yoyodyne software)
cvs.texi(,928) @end example
cvs.texi(,929) 
cvs.texi(,930) With the directories are @dfn{history files} for each file
cvs.texi(,931) under version control.  The name of the history file is
cvs.texi(,932) the name of the corresponding file with @samp{,v}
cvs.texi(,933) appended to the end.  Here is what the repository for
cvs.texi(,934) the @file{yoyodyne/tc} directory might look like:
cvs.texi(,935) @c FIXME: Should also mention CVS (CVSREP)
cvs.texi(,936) @c FIXME? Should we introduce Attic with an xref to
cvs.texi(,937) @c Attic?  Not sure whether that is a good idea or not.
cvs.texi(,938) @example
cvs.texi(,939)   @code{$CVSROOT}
cvs.texi(,940)     |
cvs.texi(,941)     +--@t{yoyodyne}
cvs.texi(,942)     |   |
cvs.texi(,943)     |   +--@t{tc}
cvs.texi(,944)     |   |   |
cvs.texi(,945)             +--@t{Makefile,v}
cvs.texi(,946)             +--@t{backend.c,v}
cvs.texi(,947)             +--@t{driver.c,v}
cvs.texi(,948)             +--@t{frontend.c,v}
cvs.texi(,949)             +--@t{parser.c,v}
cvs.texi(,950)             +--@t{man}
cvs.texi(,951)             |    |
cvs.texi(,952)             |    +--@t{tc.1,v}
cvs.texi(,953)             |
cvs.texi(,954)             +--@t{testing}
cvs.texi(,955)                  |
cvs.texi(,956)                  +--@t{testpgm.t,v}
cvs.texi(,957)                  +--@t{test2.t,v}
cvs.texi(,958) @end example
cvs.texi(,959) 
cvs.texi(,960) @cindex History files
cvs.texi(,961) @cindex RCS history files
cvs.texi(,962) @c The first sentence, about what history files
cvs.texi(,963) @c contain, is kind of redundant with our intro to what the
cvs.texi(,964) @c repository does in node Repository....
cvs.texi(,965) The history files contain, among other things, enough
cvs.texi(,966) information to recreate any revision of the file, a log
cvs.texi(,967) of all commit messages and the user-name of the person
cvs.texi(,968) who committed the revision.  The history files are
cvs.texi(,969) known as @dfn{RCS files}, because the first program to
cvs.texi(,970) store files in that format was a version control system
cvs.texi(,971) known as @sc{rcs}.  For a full
cvs.texi(,972) description of the file format, see the @code{man} page
cvs.texi(,973) @cite{rcsfile(5)}, distributed with @sc{rcs}, or the
cvs.texi(,974) file @file{doc/RCSFILES} in the @sc{cvs} source
cvs.texi(,975) distribution.  This
cvs.texi(,976) file format has become very common---many systems other
cvs.texi(,977) than @sc{cvs} or @sc{rcs} can at least import history
cvs.texi(,978) files in this format.
cvs.texi(,979) @c FIXME: Think about including documentation for this
cvs.texi(,980) @c rather than citing it?  In the long run, getting
cvs.texi(,981) @c this to be a standard (not sure if we can cope with
cvs.texi(,982) @c a standards process as formal as IEEE/ANSI/ISO/etc,
cvs.texi(,983) @c though...) is the way to go, so maybe citing is
cvs.texi(,984) @c better.
cvs.texi(,985) 
cvs.texi(,986) The @sc{rcs} files used in @sc{cvs} differ in a few
cvs.texi(,987) ways from the standard format.  The biggest difference
cvs.texi(,988) is magic branches; for more information see @ref{Magic
cvs.texi(,989) branch numbers}.  Also in @sc{cvs} the valid tag names
cvs.texi(,990) are a subset of what @sc{rcs} accepts; for @sc{cvs}'s
cvs.texi(,991) rules see @ref{Tags}.
cvs.texi(,992) 
cvs.texi(,993) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,994) @node File permissions
cvs.texi(,995) @subsection File permissions
cvs.texi(,996) @c -- Move this to @node Creating a repository or similar
cvs.texi(,997) @cindex Security, file permissions in repository
cvs.texi(,998) @cindex File permissions, general
cvs.texi(,999) @cindex Permissions, general
cvs.texi(,1000) @c FIXME: we need to somehow reflect "permissions in
cvs.texi(,1001) @c repository" versus "permissions in working
cvs.texi(,1002) @c directory" in the index entries.
cvs.texi(,1003) @cindex Group
cvs.texi(,1004) @cindex Read-only files, in repository
cvs.texi(,1005) All @samp{,v} files are created read-only, and you
cvs.texi(,1006) should not change the permission of those files.  The
cvs.texi(,1007) directories inside the repository should be writable by
cvs.texi(,1008) the persons that have permission to modify the files in
cvs.texi(,1009) each directory.  This normally means that you must
cvs.texi(,1010) create a UNIX group (see group(5)) consisting of the
cvs.texi(,1011) persons that are to edit the files in a project, and
cvs.texi(,1012) set up the repository so that it is that group that
cvs.texi(,1013) owns the directory.
cvs.texi(,1014) (On some systems, you also need to set the set-group-ID-on-execution bit
cvs.texi(,1015) on the repository directories (see chmod(1)) so that newly-created files
cvs.texi(,1016) and directories get the group-ID of the parent directory rather than
cvs.texi(,1017) that of the current process.)
cvs.texi(,1018) 
cvs.texi(,1019) @c See also comment in commitinfo node regarding cases
cvs.texi(,1020) @c which are really awkward with unix groups.
cvs.texi(,1021) 
cvs.texi(,1022) This means that you can only control access to files on
cvs.texi(,1023) a per-directory basis.
cvs.texi(,1024) 
cvs.texi(,1025) Note that users must also have write access to check
cvs.texi(,1026) out files, because @sc{cvs} needs to create lock files
cvs.texi(,1027) (@pxref{Concurrency}).  You can use LockDir in CVSROOT/config
cvs.texi(,1028) to put the lock files somewhere other than in the repository
cvs.texi(,1029) if you want to allow read-only access to some directories
cvs.texi(,1030) (@pxref{config}).
cvs.texi(,1031) 
cvs.texi(,1032) @c CVS seems to use CVSUMASK in picking permissions for
cvs.texi(,1033) @c val-tags, but maybe we should say more about this.
cvs.texi(,1034) @c Like val-tags gets created by someone who doesn't
cvs.texi(,1035) @c have CVSUMASK set right?
cvs.texi(,1036) Also note that users must have write access to the
cvs.texi(,1037) @file{CVSROOT/val-tags} file.  @sc{cvs} uses it to keep
cvs.texi(,1038) track of what tags are valid tag names (it is sometimes
cvs.texi(,1039) updated when tags are used, as well as when they are
cvs.texi(,1040) created).
cvs.texi(,1041) 
cvs.texi(,1042) Each @sc{rcs} file will be owned by the user who last
cvs.texi(,1043) checked it in.  This has little significance; what
cvs.texi(,1044) really matters is who owns the directories.
cvs.texi(,1045) 
cvs.texi(,1046) @cindex CVSUMASK, environment variable
cvs.texi(,1047) @cindex Umask, for repository files
cvs.texi(,1048) @sc{cvs} tries to set up reasonable file permissions
cvs.texi(,1049) for new directories that are added inside the tree, but
cvs.texi(,1050) you must fix the permissions manually when a new
cvs.texi(,1051) directory should have different permissions than its
cvs.texi(,1052) parent directory.  If you set the @code{CVSUMASK}
cvs.texi(,1053) environment variable that will control the file
cvs.texi(,1054) permissions which @sc{cvs} uses in creating directories
cvs.texi(,1055) and/or files in the repository.  @code{CVSUMASK} does
cvs.texi(,1056) not affect the file permissions in the working
cvs.texi(,1057) directory; such files have the permissions which are
cvs.texi(,1058) typical for newly created files, except that sometimes
cvs.texi(,1059) @sc{cvs} creates them read-only (see the sections on
cvs.texi(,1060) watches, @ref{Setting a watch}; -r, @ref{Global
cvs.texi(,1061) options}; or @code{CVSREAD}, @ref{Environment variables}).
cvs.texi(,1062) @c FIXME: Need more discussion of which
cvs.texi(,1063) @c group should own the file in the repository.
cvs.texi(,1064) @c Include a somewhat detailed example of the usual
cvs.texi(,1065) @c case where CVSUMASK is 007, the developers are all
cvs.texi(,1066) @c in a group, and that group owns stuff in the
cvs.texi(,1067) @c repository.  Need to talk about group ownership of
cvs.texi(,1068) @c newly-created directories/files (on some unices,
cvs.texi(,1069) @c such as SunOS4, setting the setgid bit on the
cvs.texi(,1070) @c directories will make files inherit the directory's
cvs.texi(,1071) @c group.  On other unices, your mileage may vary.  I
cvs.texi(,1072) @c can't remember what POSIX says about this, if
cvs.texi(,1073) @c anything).
cvs.texi(,1074) 
cvs.texi(,1075) Note that using the client/server @sc{cvs}
cvs.texi(,1076) (@pxref{Remote repositories}), there is no good way to
cvs.texi(,1077) set @code{CVSUMASK}; the setting on the client machine
cvs.texi(,1078) has no effect.  If you are connecting with @code{rsh}, you
cvs.texi(,1079) can set @code{CVSUMASK} in @file{.bashrc} or @file{.cshrc}, as
cvs.texi(,1080) described in the documentation for your operating
cvs.texi(,1081) system.  This behavior might change in future versions
cvs.texi(,1082) of @sc{cvs}; do not rely on the setting of
cvs.texi(,1083) @code{CVSUMASK} on the client having no effect.
cvs.texi(,1084) @c FIXME: need to explain what a umask is or cite
cvs.texi(,1085) @c someplace which does.
cvs.texi(,1086) @c
cvs.texi(,1087) @c There is also a larger (largely separate) issue
cvs.texi(,1088) @c about the meaning of CVSUMASK in a non-unix context.
cvs.texi(,1089) @c For example, whether there is
cvs.texi(,1090) @c an equivalent which fits better into other
cvs.texi(,1091) @c protection schemes like POSIX.6, VMS, &c.
cvs.texi(,1092) @c
cvs.texi(,1093) @c FIXME: Need one place which discusses this
cvs.texi(,1094) @c read-only files thing.  Why would one use -r or
cvs.texi(,1095) @c CVSREAD?  Why would one use watches?  How do they
cvs.texi(,1096) @c interact?
cvs.texi(,1097) @c
cvs.texi(,1098) @c FIXME: We need to state
cvs.texi(,1099) @c whether using CVSUMASK removes the need for manually
cvs.texi(,1100) @c fixing permissions (in fact, if we are going to mention
cvs.texi(,1101) @c manually fixing permission, we better document a lot
cvs.texi(,1102) @c better just what we mean by "fix").
cvs.texi(,1103) 
cvs.texi(,1104) Using pserver, you will generally need stricter
cvs.texi(,1105) permissions on the @sc{cvsroot} directory and
cvs.texi(,1106) directories above it in the tree; see @ref{Password
cvs.texi(,1107) authentication security}.
cvs.texi(,1108) 
cvs.texi(,1109) @cindex Setuid
cvs.texi(,1110) @cindex Setgid
cvs.texi(,1111) @cindex Security, setuid
cvs.texi(,1112) @cindex Installed images (VMS)
cvs.texi(,1113) Some operating systems have features which allow a
cvs.texi(,1114) particular program to run with the ability to perform
cvs.texi(,1115) operations which the caller of the program could not.
cvs.texi(,1116) For example, the set user ID (setuid) or set group ID
cvs.texi(,1117) (setgid) features of unix or the installed image
cvs.texi(,1118) feature of VMS.  @sc{cvs} was not written to use such
cvs.texi(,1119) features and therefore attempting to install @sc{cvs} in
cvs.texi(,1120) this fashion will provide protection against only
cvs.texi(,1121) accidental lapses; anyone who is trying to circumvent
cvs.texi(,1122) the measure will be able to do so, and depending on how
cvs.texi(,1123) you have set it up may gain access to more than just
cvs.texi(,1124) @sc{cvs}.  You may wish to instead consider pserver.  It
cvs.texi(,1125) shares some of the same attributes, in terms of
cvs.texi(,1126) possibly providing a false sense of security or opening
cvs.texi(,1127) security holes wider than the ones you are trying to
cvs.texi(,1128) fix, so read the documentation on pserver security
cvs.texi(,1129) carefully if you are considering this option
cvs.texi(,1130) (@ref{Password authentication security}).
cvs.texi(,1131) 
cvs.texi(,1132) @node Windows permissions
cvs.texi(,1133) @subsection File Permission issues specific to Windows
cvs.texi(,1134) @cindex Windows, and permissions
cvs.texi(,1135) @cindex File permissions, Windows-specific
cvs.texi(,1136) @cindex Permissions, Windows-specific
cvs.texi(,1137) 
cvs.texi(,1138) Some file permission issues are specific to Windows
cvs.texi(,1139) operating systems (Windows 95, Windows NT, and
cvs.texi(,1140) presumably future operating systems in this family.
cvs.texi(,1141) Some of the following might apply to OS/2 but I'm not
cvs.texi(,1142) sure).
cvs.texi(,1143) 
cvs.texi(,1144) If you are using local @sc{cvs} and the repository is on a
cvs.texi(,1145) networked file system which is served by the Samba SMB
cvs.texi(,1146) server, some people have reported problems with
cvs.texi(,1147) permissions.  Enabling WRITE=YES in the samba
cvs.texi(,1148) configuration is said to fix/workaround it.
cvs.texi(,1149) Disclaimer: I haven't investigated enough to know the
cvs.texi(,1150) implications of enabling that option, nor do I know
cvs.texi(,1151) whether there is something which @sc{cvs} could be doing
cvs.texi(,1152) differently in order to avoid the problem.  If you find
cvs.texi(,1153) something out, please let us know as described in
cvs.texi(,1154) @ref{BUGS}.
cvs.texi(,1155) 
cvs.texi(,1156) @node Attic
cvs.texi(,1157) @subsection The attic
cvs.texi(,1158) @cindex Attic
cvs.texi(,1159) 
cvs.texi(,1160) You will notice that sometimes @sc{cvs} stores an
cvs.texi(,1161) @sc{rcs} file in the @code{Attic}.  For example, if the
cvs.texi(,1162) @sc{cvsroot} is @file{/usr/local/cvsroot} and we are
cvs.texi(,1163) talking about the file @file{backend.c} in the
cvs.texi(,1164) directory @file{yoyodyne/tc}, then the file normally
cvs.texi(,1165) would be in
cvs.texi(,1166) 
cvs.texi(,1167) @example
cvs.texi(,1168) /usr/local/cvsroot/yoyodyne/tc/backend.c,v
cvs.texi(,1169) @end example
cvs.texi(,1170) 
cvs.texi(,1171) @noindent
cvs.texi(,1172) but if it goes in the attic, it would be in
cvs.texi(,1173) 
cvs.texi(,1174) @example
cvs.texi(,1175) /usr/local/cvsroot/yoyodyne/tc/Attic/backend.c,v
cvs.texi(,1176) @end example
cvs.texi(,1177) 
cvs.texi(,1178) @noindent
cvs.texi(,1179) @cindex Dead state
cvs.texi(,1180) instead.  It should not matter from a user point of
cvs.texi(,1181) view whether a file is in the attic; @sc{cvs} keeps
cvs.texi(,1182) track of this and looks in the attic when it needs to.
cvs.texi(,1183) But in case you want to know, the rule is that the RCS
cvs.texi(,1184) file is stored in the attic if and only if the head
cvs.texi(,1185) revision on the trunk has state @code{dead}.  A
cvs.texi(,1186) @code{dead} state means that file has been removed, or
cvs.texi(,1187) never added, for that revision.  For example, if you
cvs.texi(,1188) add a file on a branch, it will have a trunk revision
cvs.texi(,1189) in @code{dead} state, and a branch revision in a
cvs.texi(,1190) non-@code{dead} state.
cvs.texi(,1191) @c Probably should have some more concrete examples
cvs.texi(,1192) @c here, or somewhere (not sure exactly how we should
cvs.texi(,1193) @c arrange the discussion of the dead state, versus
cvs.texi(,1194) @c discussion of the attic).
cvs.texi(,1195) 
cvs.texi(,1196) @node CVS in repository
cvs.texi(,1197) @subsection The CVS directory in the repository
cvs.texi(,1198) @cindex CVS directory, in repository
cvs.texi(,1199) 
cvs.texi(,1200) The @file{CVS} directory in each repository directory
cvs.texi(,1201) contains information such as file attributes (in a file
cvs.texi(,1202) called @file{CVS/fileattr}.  In the
cvs.texi(,1203) future additional files may be added to this directory,
cvs.texi(,1204) so implementations should silently ignore additional
cvs.texi(,1205) files.
cvs.texi(,1206) 
cvs.texi(,1207) This behavior is implemented only by @sc{cvs} 1.7 and
cvs.texi(,1208) later; for details see @ref{Watches Compatibility}.
cvs.texi(,1209) 
cvs.texi(,1210) The format of the fileattr file is a series of entries
cvs.texi(,1211) of the following form (where @samp{@{} and @samp{@}}
cvs.texi(,1212) means the text between the braces can be repeated zero
cvs.texi(,1213) or more times):
cvs.texi(,1214) 
cvs.texi(,1215) @var{ent-type} @var{filename} <tab> @var{attrname} = @var{attrval}
cvs.texi(,1216)   @{; @var{attrname} = @var{attrval}@} <linefeed>
cvs.texi(,1217) 
cvs.texi(,1218) @var{ent-type} is @samp{F} for a file, in which case the entry specifies the
cvs.texi(,1219) attributes for that file.
cvs.texi(,1220) 
cvs.texi(,1221) @var{ent-type} is @samp{D},
cvs.texi(,1222) and @var{filename} empty, to specify default attributes
cvs.texi(,1223) to be used for newly added files.
cvs.texi(,1224) 
cvs.texi(,1225) Other @var{ent-type} are reserved for future expansion.  @sc{cvs} 1.9 and older
cvs.texi(,1226) will delete them any time it writes file attributes.
cvs.texi(,1227) @sc{cvs} 1.10 and later will preserve them.
cvs.texi(,1228) 
cvs.texi(,1229) Note that the order of the lines is not significant;
cvs.texi(,1230) a program writing the fileattr file may
cvs.texi(,1231) rearrange them at its convenience.
cvs.texi(,1232) 
cvs.texi(,1233) There is currently no way of quoting tabs or linefeeds in the
cvs.texi(,1234) filename, @samp{=} in @var{attrname},
cvs.texi(,1235) @samp{;} in @var{attrval}, etc.  Note: some implementations also
cvs.texi(,1236) don't handle a NUL character in any of the fields, but
cvs.texi(,1237) implementations are encouraged to allow it.
cvs.texi(,1238) 
cvs.texi(,1239) By convention, @var{attrname} starting with @samp{_} is for an attribute given
cvs.texi(,1240) special meaning by @sc{cvs}; other @var{attrname}s are for user-defined attributes
cvs.texi(,1241) (or will be, once implementations start supporting user-defined attributes).
cvs.texi(,1242) 
cvs.texi(,1243) Builtin attributes:
cvs.texi(,1244) 
cvs.texi(,1245) @table @code
cvs.texi(,1246) @item _watched
cvs.texi(,1247) Present means the file is watched and should be checked out
cvs.texi(,1248) read-only.
cvs.texi(,1249) 
cvs.texi(,1250) @item _watchers
cvs.texi(,1251) Users with watches for this file.  Value is
cvs.texi(,1252) @var{watcher} > @var{type} @{ , @var{watcher} > @var{type} @}
cvs.texi(,1253) where @var{watcher} is a username, and @var{type}
cvs.texi(,1254) is zero or more of edit,unedit,commit separated by
cvs.texi(,1255) @samp{+} (that is, nothing if none; there is no "none" or "all" keyword).
cvs.texi(,1256) 
cvs.texi(,1257) @item _editors
cvs.texi(,1258) Users editing this file.  Value is
cvs.texi(,1259) @var{editor} > @var{val} @{ , @var{editor} > @var{val} @}
cvs.texi(,1260) where @var{editor} is a username, and @var{val} is
cvs.texi(,1261) @var{time}+@var{hostname}+@var{pathname}, where
cvs.texi(,1262) @var{time} is when the @code{cvs edit} command (or
cvs.texi(,1263) equivalent) happened,
cvs.texi(,1264) and @var{hostname} and @var{pathname} are for the working directory.
cvs.texi(,1265) @end table
cvs.texi(,1266) 
cvs.texi(,1267) Example:
cvs.texi(,1268) 
cvs.texi(,1269) @c FIXME: sanity.sh should contain a similar test case
cvs.texi(,1270) @c so we can compare this example from something from
cvs.texi(,1271) @c Real Life(TM).  See cvsclient.texi (under Notify) for more
cvs.texi(,1272) @c discussion of the date format of _editors.
cvs.texi(,1273) @example
cvs.texi(,1274) Ffile1 _watched=;_watchers=joe>edit,mary>commit
cvs.texi(,1275) Ffile2 _watched=;_editors=sue>8 Jan 1975+workstn1+/home/sue/cvs
cvs.texi(,1276) D _watched=
cvs.texi(,1277) @end example
cvs.texi(,1278) 
cvs.texi(,1279) @noindent
cvs.texi(,1280) means that the file @file{file1} should be checked out
cvs.texi(,1281) read-only.  Furthermore, joe is watching for edits and
cvs.texi(,1282) mary is watching for commits.  The file @file{file2}
cvs.texi(,1283) should be checked out read-only; sue started editing it
cvs.texi(,1284) on 8 Jan 1975 in the directory @file{/home/sue/cvs} on
cvs.texi(,1285) the machine @code{workstn1}.  Future files which are
cvs.texi(,1286) added should be checked out read-only.  To represent
cvs.texi(,1287) this example here, we have shown a space after
cvs.texi(,1288) @samp{D}, @samp{Ffile1}, and @samp{Ffile2}, but in fact
cvs.texi(,1289) there must be a single tab character there and no spaces.
cvs.texi(,1290) 
cvs.texi(,1291) @node Locks
cvs.texi(,1292) @subsection CVS locks in the repository
cvs.texi(,1293) 
cvs.texi(,1294) @cindex #cvs.rfl, technical details
cvs.texi(,1295) @cindex #cvs.wfl, technical details
cvs.texi(,1296) @cindex #cvs.lock, technical details
cvs.texi(,1297) @cindex Locks, cvs, technical details
cvs.texi(,1298) For an introduction to @sc{cvs} locks focusing on
cvs.texi(,1299) user-visible behavior, see @ref{Concurrency}.  The
cvs.texi(,1300) following section is aimed at people who are writing
cvs.texi(,1301) tools which want to access a @sc{cvs} repository without
cvs.texi(,1302) interfering with other tools accessing the same
cvs.texi(,1303) repository.  If you find yourself confused by concepts
cvs.texi(,1304) described here, like @dfn{read lock}, @dfn{write lock},
cvs.texi(,1305) and @dfn{deadlock}, you might consult the literature on
cvs.texi(,1306) operating systems or databases.
cvs.texi(,1307) 
cvs.texi(,1308) @cindex #cvs.tfl
cvs.texi(,1309) Any file in the repository with a name starting
cvs.texi(,1310) with @file{#cvs.rfl.} is a read lock.  Any file in
cvs.texi(,1311) the repository with a name starting with
cvs.texi(,1312) @file{#cvs.wfl} is a write lock.  Old versions of @sc{cvs}
cvs.texi(,1313) (before @sc{cvs} 1.5) also created files with names starting
cvs.texi(,1314) with @file{#cvs.tfl}, but they are not discussed here.
cvs.texi(,1315) The directory @file{#cvs.lock} serves as a master
cvs.texi(,1316) lock.  That is, one must obtain this lock first before
cvs.texi(,1317) creating any of the other locks.
cvs.texi(,1318) 
cvs.texi(,1319) To obtain a readlock, first create the @file{#cvs.lock}
cvs.texi(,1320) directory.  This operation must be atomic (which should
cvs.texi(,1321) be true for creating a directory under most operating
cvs.texi(,1322) systems).  If it fails because the directory already
cvs.texi(,1323) existed, wait for a while and try again.  After
cvs.texi(,1324) obtaining the @file{#cvs.lock} lock, create a file
cvs.texi(,1325) whose name is @file{#cvs.rfl.} followed by information
cvs.texi(,1326) of your choice (for example, hostname and process
cvs.texi(,1327) identification number).  Then remove the
cvs.texi(,1328) @file{#cvs.lock} directory to release the master lock.
cvs.texi(,1329) Then proceed with reading the repository.  When you are
cvs.texi(,1330) done, remove the @file{#cvs.rfl} file to release the
cvs.texi(,1331) read lock.
cvs.texi(,1332) 
cvs.texi(,1333) To obtain a writelock, first create the
cvs.texi(,1334) @file{#cvs.lock} directory, as with a readlock.  Then
cvs.texi(,1335) check that there are no files whose names start with
cvs.texi(,1336) @file{#cvs.rfl.}.  If there are, remove
cvs.texi(,1337) @file{#cvs.lock}, wait for a while, and try again.  If
cvs.texi(,1338) there are no readers, then create a file whose name is
cvs.texi(,1339) @file{#cvs.wfl} followed by information of your choice
cvs.texi(,1340) (for example, hostname and process identification
cvs.texi(,1341) number).  Hang on to the @file{#cvs.lock} lock.  Proceed
cvs.texi(,1342) with writing the repository.  When you are done, first
cvs.texi(,1343) remove the @file{#cvs.wfl} file and then the
cvs.texi(,1344) @file{#cvs.lock} directory. Note that unlike the
cvs.texi(,1345) @file{#cvs.rfl} file, the @file{#cvs.wfl} file is just
cvs.texi(,1346) informational; it has no effect on the locking operation
cvs.texi(,1347) beyond what is provided by holding on to the
cvs.texi(,1348) @file{#cvs.lock} lock itself.
cvs.texi(,1349) 
cvs.texi(,1350) Note that each lock (writelock or readlock) only locks
cvs.texi(,1351) a single directory in the repository, including
cvs.texi(,1352) @file{Attic} and @file{CVS} but not including
cvs.texi(,1353) subdirectories which represent other directories under
cvs.texi(,1354) version control.  To lock an entire tree, you need to
cvs.texi(,1355) lock each directory (note that if you fail to obtain
cvs.texi(,1356) any lock you need, you must release the whole tree
cvs.texi(,1357) before waiting and trying again, to avoid deadlocks).
cvs.texi(,1358) 
cvs.texi(,1359) Note also that @sc{cvs} expects writelocks to control
cvs.texi(,1360) access to individual @file{foo,v} files.  @sc{rcs} has
cvs.texi(,1361) a scheme where the @file{,foo,} file serves as a lock,
cvs.texi(,1362) but @sc{cvs} does not implement it and so taking out a
cvs.texi(,1363) @sc{cvs} writelock is recommended.  See the comments at
cvs.texi(,1364) rcs_internal_lockfile in the @sc{cvs} source code for
cvs.texi(,1365) further discussion/rationale.
cvs.texi(,1366) 
cvs.texi(,1367) @node CVSROOT storage
cvs.texi(,1368) @subsection How files are stored in the CVSROOT directory
cvs.texi(,1369) @cindex CVSROOT, storage of files
cvs.texi(,1370) 
cvs.texi(,1371) The @file{$CVSROOT/CVSROOT} directory contains the
cvs.texi(,1372) various administrative files.  In some ways this
cvs.texi(,1373) directory is just like any other directory in the
cvs.texi(,1374) repository; it contains @sc{rcs} files whose names end
cvs.texi(,1375) in @samp{,v}, and many of the @sc{cvs} commands operate
cvs.texi(,1376) on it the same way.  However, there are a few
cvs.texi(,1377) differences.
cvs.texi(,1378) 
cvs.texi(,1379) For each administrative file, in addition to the
cvs.texi(,1380) @sc{rcs} file, there is also a checked out copy of the
cvs.texi(,1381) file.  For example, there is an @sc{rcs} file
cvs.texi(,1382) @file{loginfo,v} and a file @file{loginfo} which
cvs.texi(,1383) contains the latest revision contained in
cvs.texi(,1384) @file{loginfo,v}.  When you check in an administrative
cvs.texi(,1385) file, @sc{cvs} should print
cvs.texi(,1386) 
cvs.texi(,1387) @example
cvs.texi(,1388) cvs commit: Rebuilding administrative file database
cvs.texi(,1389) @end example
cvs.texi(,1390) 
cvs.texi(,1391) @noindent
cvs.texi(,1392) and update the checked out copy in
cvs.texi(,1393) @file{$CVSROOT/CVSROOT}.  If it does not, there is
cvs.texi(,1394) something wrong (@pxref{BUGS}).  To add your own files
cvs.texi(,1395) to the files to be updated in this fashion, you can add
cvs.texi(,1396) them to the @file{checkoutlist} administrative file
cvs.texi(,1397) (@pxref{checkoutlist}).
cvs.texi(,1398) 
cvs.texi(,1399) @cindex modules.db
cvs.texi(,1400) @cindex modules.pag
cvs.texi(,1401) @cindex modules.dir
cvs.texi(,1402) By default, the @file{modules} file behaves as
cvs.texi(,1403) described above.  If the modules file is very large,
cvs.texi(,1404) storing it as a flat text file may make looking up
cvs.texi(,1405) modules slow (I'm not sure whether this is as much of a
cvs.texi(,1406) concern now as when @sc{cvs} first evolved this
cvs.texi(,1407) feature; I haven't seen benchmarks).  Therefore, by
cvs.texi(,1408) making appropriate edits to the @sc{cvs} source code
cvs.texi(,1409) one can store the modules file in a database which
cvs.texi(,1410) implements the @code{ndbm} interface, such as Berkeley
cvs.texi(,1411) db or GDBM.  If this option is in use, then the modules
cvs.texi(,1412) database will be stored in the files @file{modules.db},
cvs.texi(,1413) @file{modules.pag}, and/or @file{modules.dir}.
cvs.texi(,1414) @c I think fileattr also will use the database stuff.
cvs.texi(,1415) @c Anything else?
cvs.texi(,1416) 
cvs.texi(,1417) For information on the meaning of the various
cvs.texi(,1418) administrative files, see @ref{Administrative files}.
cvs.texi(,1419) 
cvs.texi(,1420) @node Working directory storage
cvs.texi(,1421) @section How data is stored in the working directory
cvs.texi(,1422) 
cvs.texi(,1423) @c FIXME: Somewhere we should discuss timestamps (test
cvs.texi(,1424) @c case "stamps" in sanity.sh).  But not here.  Maybe
cvs.texi(,1425) @c in some kind of "working directory" chapter which
cvs.texi(,1426) @c would encompass the "Builds" one?  But I'm not sure
cvs.texi(,1427) @c whether that is a good organization (is it based on
cvs.texi(,1428) @c what the user wants to do?).
cvs.texi(,1429) 
cvs.texi(,1430) @cindex CVS directory, in working directory
cvs.texi(,1431) While we are discussing @sc{cvs} internals which may
cvs.texi(,1432) become visible from time to time, we might as well talk
cvs.texi(,1433) about what @sc{cvs} puts in the @file{CVS} directories
cvs.texi(,1434) in the working directories.  As with the repository,
cvs.texi(,1435) @sc{cvs} handles this information and one can usually
cvs.texi(,1436) access it via @sc{cvs} commands.  But in some cases it
cvs.texi(,1437) may be useful to look at it, and other programs, such
cvs.texi(,1438) as the @code{jCVS} graphical user interface or the
cvs.texi(,1439) @code{VC} package for emacs, may need to look at it.
cvs.texi(,1440) Such programs should follow the recommendations in this
cvs.texi(,1441) section if they hope to be able to work with other
cvs.texi(,1442) programs which use those files, including future
cvs.texi(,1443) versions of the programs just mentioned and the
cvs.texi(,1444) command-line @sc{cvs} client.
cvs.texi(,1445) 
cvs.texi(,1446) The @file{CVS} directory contains several files.
cvs.texi(,1447) Programs which are reading this directory should
cvs.texi(,1448) silently ignore files which are in the directory but
cvs.texi(,1449) which are not documented here, to allow for future
cvs.texi(,1450) expansion.
cvs.texi(,1451) 
cvs.texi(,1452) The files are stored according to the text file
cvs.texi(,1453) convention for the system in question.  This means that
cvs.texi(,1454) working directories are not portable between systems
cvs.texi(,1455) with differing conventions for storing text files.
cvs.texi(,1456) This is intentional, on the theory that the files being
cvs.texi(,1457) managed by @sc{cvs} probably will not be portable between
cvs.texi(,1458) such systems either.
cvs.texi(,1459) 
cvs.texi(,1460) @table @file
cvs.texi(,1461) @item Root
cvs.texi(,1462) This file contains the current @sc{cvs} root, as
cvs.texi(,1463) described in @ref{Specifying a repository}.
cvs.texi(,1464) 
cvs.texi(,1465) @cindex Repository file, in CVS directory
cvs.texi(,1466) @cindex CVS/Repository file
cvs.texi(,1467) @item Repository
cvs.texi(,1468) This file contains the directory within the repository
cvs.texi(,1469) which the current directory corresponds with.  It can
cvs.texi(,1470) be either an absolute pathname or a relative pathname;
cvs.texi(,1471) @sc{cvs} has had the ability to read either format
cvs.texi(,1472) since at least version 1.3 or so.  The relative
cvs.texi(,1473) pathname is relative to the root, and is the more
cvs.texi(,1474) sensible approach, but the absolute pathname is quite
cvs.texi(,1475) common and implementations should accept either.  For
cvs.texi(,1476) example, after the command
cvs.texi(,1477) 
cvs.texi(,1478) @example
cvs.texi(,1479) cvs -d :local:/usr/local/cvsroot checkout yoyodyne/tc
cvs.texi(,1480) @end example
cvs.texi(,1481) 
cvs.texi(,1482) @noindent
cvs.texi(,1483) @file{Root} will contain
cvs.texi(,1484) 
cvs.texi(,1485) @example
cvs.texi(,1486) :local:/usr/local/cvsroot
cvs.texi(,1487) @end example
cvs.texi(,1488) 
cvs.texi(,1489) @noindent
cvs.texi(,1490) and @file{Repository} will contain either
cvs.texi(,1491) 
cvs.texi(,1492) @example
cvs.texi(,1493) /usr/local/cvsroot/yoyodyne/tc
cvs.texi(,1494) @end example
cvs.texi(,1495) 
cvs.texi(,1496) @noindent
cvs.texi(,1497) or
cvs.texi(,1498) 
cvs.texi(,1499) @example
cvs.texi(,1500) yoyodyne/tc
cvs.texi(,1501) @end example
cvs.texi(,1502) 
cvs.texi(,1503) If the particular working directory does not correspond
cvs.texi(,1504) to a directory in the repository, then @file{Repository}
cvs.texi(,1505) should contain @file{CVSROOT/Emptydir}.
cvs.texi(,1506) @cindex Emptydir, in CVSROOT directory
cvs.texi(,1507) @cindex CVSROOT/Emptydir directory
cvs.texi(,1508) 
cvs.texi(,1509) @cindex Entries file, in CVS directory
cvs.texi(,1510) @cindex CVS/Entries file
cvs.texi(,1511) @item Entries
cvs.texi(,1512) This file lists the files and directories in the
cvs.texi(,1513) working directory.
cvs.texi(,1514) The first character of each line indicates what sort of
cvs.texi(,1515) line it is.  If the character is unrecognized, programs
cvs.texi(,1516) reading the file should silently skip that line, to
cvs.texi(,1517) allow for future expansion.
cvs.texi(,1518) 
cvs.texi(,1519) If the first character is @samp{/}, then the format is:
cvs.texi(,1520) 
cvs.texi(,1521) @example
cvs.texi(,1522) /@var{name}/@var{revision}/@var{timestamp}[+@var{conflict}]/@var{options}/@var{tagdate}
cvs.texi(,1523) @end example
cvs.texi(,1524) 
cvs.texi(,1525) @noindent
cvs.texi(,1526) where @samp{[} and @samp{]} are not part of the entry,
cvs.texi(,1527) but instead indicate that the @samp{+} and conflict
cvs.texi(,1528) marker are optional.  @var{name} is the name of the
cvs.texi(,1529) file within the directory.  @var{revision} is the
cvs.texi(,1530) revision that the file in the working derives from, or
cvs.texi(,1531) @samp{0} for an added file, or @samp{-} followed by a
cvs.texi(,1532) revision for a removed file.  @var{timestamp} is the
cvs.texi(,1533) timestamp of the file at the time that @sc{cvs} created
cvs.texi(,1534) it; if the timestamp differs with the actual
cvs.texi(,1535) modification time of the file it means the file has
cvs.texi(,1536) been modified.  It is stored in
cvs.texi(,1537) the format used by the ISO C asctime() function (for
cvs.texi(,1538) example, @samp{Sun Apr  7 01:29:26 1996}).  One may
cvs.texi(,1539) write a string which is not in that format, for
cvs.texi(,1540) example, @samp{Result of merge}, to indicate that the
cvs.texi(,1541) file should always be considered to be modified.  This
cvs.texi(,1542) is not a special case; to see whether a file is
cvs.texi(,1543) modified a program should take the timestamp of the file
cvs.texi(,1544) and simply do a string compare with @var{timestamp}.
cvs.texi(,1545) If there was a conflict, @var{conflict} can be set to
cvs.texi(,1546) the modification time of the file after the file has been
cvs.texi(,1547) written with conflict markers (@pxref{Conflicts example}).
cvs.texi(,1548) Thus if @var{conflict} is subsequently the same as the actual
cvs.texi(,1549) modification time of the file it means that the user
cvs.texi(,1550) has obviously not resolved the conflict.  @var{options}
cvs.texi(,1551) contains sticky options (for example @samp{-kb} for a
cvs.texi(,1552) binary file).  @var{tagdate} contains @samp{T} followed
cvs.texi(,1553) by a tag name, or @samp{D} for a date, followed by a
cvs.texi(,1554) sticky tag or date.  Note that if @var{timestamp}
cvs.texi(,1555) contains a pair of timestamps separated by a space,
cvs.texi(,1556) rather than a single timestamp, you are dealing with a
cvs.texi(,1557) version of @sc{cvs} earlier than @sc{cvs} 1.5 (not
cvs.texi(,1558) documented here).
cvs.texi(,1559) 
cvs.texi(,1560) The timezone on the timestamp in CVS/Entries (local or
cvs.texi(,1561) universal) should be the same as the operating system
cvs.texi(,1562) stores for the timestamp of the file itself.  For
cvs.texi(,1563) example, on Unix the file's timestamp is in universal
cvs.texi(,1564) time (UT), so the timestamp in CVS/Entries should be
cvs.texi(,1565) too.  On @sc{vms}, the file's timestamp is in local
cvs.texi(,1566) time, so @sc{cvs} on @sc{vms} should use local time.
cvs.texi(,1567) This rule is so that files do not appear to be modified
cvs.texi(,1568) merely because the timezone changed (for example, to or
cvs.texi(,1569) from summer time).
cvs.texi(,1570) @c See comments and calls to gmtime() and friends in
cvs.texi(,1571) @c src/vers_ts.c (function time_stamp).
cvs.texi(,1572) 
cvs.texi(,1573) If the first character of a line in @file{Entries} is
cvs.texi(,1574) @samp{D}, then it indicates a subdirectory.  @samp{D}
cvs.texi(,1575) on a line all by itself indicates that the program
cvs.texi(,1576) which wrote the @file{Entries} file does record
cvs.texi(,1577) subdirectories (therefore, if there is such a line and
cvs.texi(,1578) no other lines beginning with @samp{D}, one knows there
cvs.texi(,1579) are no subdirectories).  Otherwise, the line looks
cvs.texi(,1580) like:
cvs.texi(,1581) 
cvs.texi(,1582) @example
cvs.texi(,1583) D/@var{name}/@var{filler1}/@var{filler2}/@var{filler3}/@var{filler4}
cvs.texi(,1584) @end example
cvs.texi(,1585) 
cvs.texi(,1586) @noindent
cvs.texi(,1587) where @var{name} is the name of the subdirectory, and
cvs.texi(,1588) all the @var{filler} fields should be silently ignored,
cvs.texi(,1589) for future expansion.  Programs which modify
cvs.texi(,1590) @code{Entries} files should preserve these fields.
cvs.texi(,1591) 
cvs.texi(,1592) The lines in the @file{Entries} file can be in any order.
cvs.texi(,1593) 
cvs.texi(,1594) @cindex Entries.Log file, in CVS directory
cvs.texi(,1595) @cindex CVS/Entries.Log file
cvs.texi(,1596) @item Entries.Log
cvs.texi(,1597) This file does not record any information beyond that
cvs.texi(,1598) in @file{Entries}, but it does provide a way to update
cvs.texi(,1599) the information without having to rewrite the entire
cvs.texi(,1600) @file{Entries} file, including the ability to preserve
cvs.texi(,1601) the information even if the program writing
cvs.texi(,1602) @file{Entries} and @file{Entries.Log} abruptly aborts.
cvs.texi(,1603) Programs which are reading the @file{Entries} file
cvs.texi(,1604) should also check for @file{Entries.Log}.  If the latter
cvs.texi(,1605) exists, they should read @file{Entries} and then apply
cvs.texi(,1606) the changes mentioned in @file{Entries.Log}.  After
cvs.texi(,1607) applying the changes, the recommended practice is to
cvs.texi(,1608) rewrite @file{Entries} and then delete @file{Entries.Log}.
cvs.texi(,1609) The format of a line in @file{Entries.Log} is a single
cvs.texi(,1610) character command followed by a space followed by a
cvs.texi(,1611) line in the format specified for a line in
cvs.texi(,1612) @file{Entries}.  The single character command is
cvs.texi(,1613) @samp{A} to indicate that the entry is being added,
cvs.texi(,1614) @samp{R} to indicate that the entry is being removed,
cvs.texi(,1615) or any other character to indicate that the entire line
cvs.texi(,1616) in @file{Entries.Log} should be silently ignored (for
cvs.texi(,1617) future expansion).  If the second character of the line
cvs.texi(,1618) in @file{Entries.Log} is not a space, then it was
cvs.texi(,1619) written by an older version of @sc{cvs} (not documented
cvs.texi(,1620) here).
cvs.texi(,1621) 
cvs.texi(,1622) Programs which are writing rather than reading can
cvs.texi(,1623) safely ignore @file{Entries.Log} if they so choose.
cvs.texi(,1624) 
cvs.texi(,1625) @cindex Entries.Backup file, in CVS directory
cvs.texi(,1626) @cindex CVS/Entries.Backup file
cvs.texi(,1627) @item Entries.Backup
cvs.texi(,1628) This is a temporary file.  Recommended usage is to
cvs.texi(,1629) write a new entries file to @file{Entries.Backup}, and
cvs.texi(,1630) then to rename it (atomically, where possible) to @file{Entries}.
cvs.texi(,1631) 
cvs.texi(,1632) @cindex Entries.Static file, in CVS directory
cvs.texi(,1633) @cindex CVS/Entries.Static file
cvs.texi(,1634) @item Entries.Static
cvs.texi(,1635) The only relevant thing about this file is whether it
cvs.texi(,1636) exists or not.  If it exists, then it means that only
cvs.texi(,1637) part of a directory was gotten and @sc{cvs} will
cvs.texi(,1638) not create additional files in that directory.  To
cvs.texi(,1639) clear it, use the @code{update} command with the
cvs.texi(,1640) @samp{-d} option, which will get the additional files
cvs.texi(,1641) and remove @file{Entries.Static}.
cvs.texi(,1642) @c FIXME: This needs to be better documented, in places
cvs.texi(,1643) @c other than Working Directory Storage.
cvs.texi(,1644) @c FIXCVS: The fact that this setting exists needs to
cvs.texi(,1645) @c be more visible to the user.  For example "cvs
cvs.texi(,1646) @c status foo", in the case where the file would be
cvs.texi(,1647) @c gotten except for Entries.Static, might say
cvs.texi(,1648) @c something to distinguish this from other cases.
cvs.texi(,1649) @c One thing that periodically gets suggested is to
cvs.texi(,1650) @c have "cvs update" print something when it skips
cvs.texi(,1651) @c files due to Entries.Static, but IMHO that kind of
cvs.texi(,1652) @c noise pretty much makes the Entries.Static feature
cvs.texi(,1653) @c useless.
cvs.texi(,1654) 
cvs.texi(,1655) @cindex Tag file, in CVS directory
cvs.texi(,1656) @cindex CVS/Tag file
cvs.texi(,1657) @cindex Sticky tags/dates, per-directory
cvs.texi(,1658) @cindex Per-directory sticky tags/dates
cvs.texi(,1659) @item Tag
cvs.texi(,1660) This file contains per-directory sticky tags or dates.
cvs.texi(,1661) The first character is @samp{T} for a branch tag,
cvs.texi(,1662) @samp{N} for a non-branch tag, or @samp{D} for a date,
cvs.texi(,1663) or another character to mean the file should be
cvs.texi(,1664) silently ignored, for future expansion.  This character
cvs.texi(,1665) is followed by the tag or date.  Note that
cvs.texi(,1666) per-directory sticky tags or dates are used for things
cvs.texi(,1667) like applying to files which are newly added; they
cvs.texi(,1668) might not be the same as the sticky tags or dates on
cvs.texi(,1669) individual files.  For general information on sticky
cvs.texi(,1670) tags and dates, see @ref{Sticky tags}.
cvs.texi(,1671) @c FIXME: This needs to be much better documented,
cvs.texi(,1672) @c preferably not in the context of "working directory
cvs.texi(,1673) @c storage".
cvs.texi(,1674) @c FIXME: The Sticky tags node needs to discuss, or xref to
cvs.texi(,1675) @c someplace which discusses, per-directory sticky
cvs.texi(,1676) @c tags and the distinction with per-file sticky tags.
cvs.texi(,1677) 
cvs.texi(,1678) @cindex Notify file, in CVS directory
cvs.texi(,1679) @cindex CVS/Notify file
cvs.texi(,1680) @item Notify
cvs.texi(,1681) This file stores notifications (for example, for
cvs.texi(,1682) @code{edit} or @code{unedit}) which have not yet been
cvs.texi(,1683) sent to the server.  Its format is not yet documented
cvs.texi(,1684) here.
cvs.texi(,1685) 
cvs.texi(,1686) @cindex Notify.tmp file, in CVS directory
cvs.texi(,1687) @cindex CVS/Notify.tmp file
cvs.texi(,1688) @item Notify.tmp
cvs.texi(,1689) This file is to @file{Notify} as @file{Entries.Backup}
cvs.texi(,1690) is to @file{Entries}.  That is, to write @file{Notify},
cvs.texi(,1691) first write the new contents to @file{Notify.tmp} and
cvs.texi(,1692) then (atomically where possible), rename it to
cvs.texi(,1693) @file{Notify}.
cvs.texi(,1694) 
cvs.texi(,1695) @cindex Base directory, in CVS directory
cvs.texi(,1696) @cindex CVS/Base directory
cvs.texi(,1697) @item Base
cvs.texi(,1698) If watches are in use, then an @code{edit} command
cvs.texi(,1699) stores the original copy of the file in the @file{Base}
cvs.texi(,1700) directory.  This allows the @code{unedit} command to
cvs.texi(,1701) operate even if it is unable to communicate with the
cvs.texi(,1702) server.
cvs.texi(,1703) 
cvs.texi(,1704) @cindex Baserev file, in CVS directory
cvs.texi(,1705) @cindex CVS/Baserev file
cvs.texi(,1706) @item Baserev
cvs.texi(,1707) The file lists the revision for each of the files in
cvs.texi(,1708) the @file{Base} directory.  The format is:
cvs.texi(,1709) 
cvs.texi(,1710) @example
cvs.texi(,1711) B@var{name}/@var{rev}/@var{expansion}
cvs.texi(,1712) @end example
cvs.texi(,1713) 
cvs.texi(,1714) @noindent
cvs.texi(,1715) where @var{expansion} should be ignored, to allow for
cvs.texi(,1716) future expansion.
cvs.texi(,1717) 
cvs.texi(,1718) @cindex Baserev.tmp file, in CVS directory
cvs.texi(,1719) @cindex CVS/Baserev.tmp file
cvs.texi(,1720) @item Baserev.tmp
cvs.texi(,1721) This file is to @file{Baserev} as @file{Entries.Backup}
cvs.texi(,1722) is to @file{Entries}.  That is, to write @file{Baserev},
cvs.texi(,1723) first write the new contents to @file{Baserev.tmp} and
cvs.texi(,1724) then (atomically where possible), rename it to
cvs.texi(,1725) @file{Baserev}.
cvs.texi(,1726) 
cvs.texi(,1727) @cindex Template file, in CVS directory
cvs.texi(,1728) @cindex CVS/Template file
cvs.texi(,1729) @item Template
cvs.texi(,1730) This file contains the template specified by the
cvs.texi(,1731) @file{rcsinfo} file (@pxref{rcsinfo}).  It is only used
cvs.texi(,1732) by the client; the non-client/server @sc{cvs} consults
cvs.texi(,1733) @file{rcsinfo} directly.
cvs.texi(,1734) @end table
cvs.texi(,1735) 
cvs.texi(,1736) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,1737) @node Intro administrative files
cvs.texi(,1738) @section The administrative files
cvs.texi(,1739) @cindex Administrative files (intro)
cvs.texi(,1740) @cindex Modules file
cvs.texi(,1741) @cindex CVSROOT, module name
cvs.texi(,1742) @cindex Defining modules (intro)
cvs.texi(,1743) 
cvs.texi(,1744) @c FIXME: this node should be reorganized into "general
cvs.texi(,1745) @c information about admin files" and put the "editing
cvs.texi(,1746) @c admin files" stuff up front rather than jumping into
cvs.texi(,1747) @c the details of modules right away.  Then the
cvs.texi(,1748) @c Administrative files node can go away, the information
cvs.texi(,1749) @c on each admin file distributed to a place appropriate
cvs.texi(,1750) @c to its function, and this node can contain a table
cvs.texi(,1751) @c listing each file and a @ref to its detailed description.
cvs.texi(,1752) 
cvs.texi(,1753) The directory @file{$CVSROOT/CVSROOT} contains some @dfn{administrative
cvs.texi(,1754) files}.  @xref{Administrative files}, for a complete description.
cvs.texi(,1755) You can use @sc{cvs} without any of these files, but
cvs.texi(,1756) some commands work better when at least the
cvs.texi(,1757) @file{modules} file is properly set up.
cvs.texi(,1758) 
cvs.texi(,1759) The most important of these files is the @file{modules}
cvs.texi(,1760) file.  It defines all modules in the repository.  This
cvs.texi(,1761) is a sample @file{modules} file.
cvs.texi(,1762) 
cvs.texi(,1763) @c FIXME: The CVSROOT line is a goofy example now that
cvs.texi(,1764) @c mkmodules doesn't exist.
cvs.texi(,1765) @example
cvs.texi(,1766) CVSROOT         CVSROOT
cvs.texi(,1767) modules         CVSROOT modules
cvs.texi(,1768) cvs             gnu/cvs
cvs.texi(,1769) rcs             gnu/rcs
cvs.texi(,1770) diff            gnu/diff
cvs.texi(,1771) tc              yoyodyne/tc
cvs.texi(,1772) @end example
cvs.texi(,1773) 
cvs.texi(,1774) The @file{modules} file is line oriented.  In its
cvs.texi(,1775) simplest form each line contains the name of the
cvs.texi(,1776) module, whitespace, and the directory where the module
cvs.texi(,1777) resides.  The directory is a path relative to
cvs.texi(,1778) @code{$CVSROOT}.  The last four lines in the example
cvs.texi(,1779) above are examples of such lines.
cvs.texi(,1780) 
cvs.texi(,1781) @c FIXME: might want to introduce the concept of options in modules file
cvs.texi(,1782) @c (the old example which was here, -i mkmodules, is obsolete).
cvs.texi(,1783) 
cvs.texi(,1784) The line that defines the module called @samp{modules}
cvs.texi(,1785) uses features that are not explained here.
cvs.texi(,1786) @xref{modules}, for a full explanation of all the
cvs.texi(,1787) available features.
cvs.texi(,1788) 
cvs.texi(,1789) @c FIXME: subsection without node is bogus
cvs.texi(,1790) @subsection Editing administrative files
cvs.texi(,1791) @cindex Editing administrative files
cvs.texi(,1792) @cindex Administrative files, editing them
cvs.texi(,1793) 
cvs.texi(,1794) You edit the administrative files in the same way that you would edit
cvs.texi(,1795) any other module.  Use @samp{cvs checkout CVSROOT} to get a working
cvs.texi(,1796) copy, edit it, and commit your changes in the normal way.
cvs.texi(,1797) 
cvs.texi(,1798) It is possible to commit an erroneous administrative
cvs.texi(,1799) file.  You can often fix the error and check in a new
cvs.texi(,1800) revision, but sometimes a particularly bad error in the
cvs.texi(,1801) administrative file makes it impossible to commit new
cvs.texi(,1802) revisions.
cvs.texi(,1803) @c @xref{Bad administrative files} for a hint
cvs.texi(,1804) @c about how to solve such situations.
cvs.texi(,1805) @c -- administrative file checking--
cvs.texi(,1806) 
cvs.texi(,1807) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,1808) @node Multiple repositories
cvs.texi(,1809) @section Multiple repositories
cvs.texi(,1810) @cindex Multiple repositories
cvs.texi(,1811) @cindex Repositories, multiple
cvs.texi(,1812) @cindex Many repositories
cvs.texi(,1813) @cindex Parallel repositories
cvs.texi(,1814) @cindex Disjoint repositories
cvs.texi(,1815) @cindex CVSROOT, multiple repositories
cvs.texi(,1816) 
cvs.texi(,1817) In some situations it is a good idea to have more than
cvs.texi(,1818) one repository, for instance if you have two
cvs.texi(,1819) development groups that work on separate projects
cvs.texi(,1820) without sharing any code.  All you have to do to have
cvs.texi(,1821) several repositories is to specify the appropriate
cvs.texi(,1822) repository, using the @code{CVSROOT} environment
cvs.texi(,1823) variable, the @samp{-d} option to @sc{cvs}, or (once
cvs.texi(,1824) you have checked out a working directory) by simply
cvs.texi(,1825) allowing @sc{cvs} to use the repository that was used
cvs.texi(,1826) to check out the working directory
cvs.texi(,1827) (@pxref{Specifying a repository}).
cvs.texi(,1828) 
cvs.texi(,1829) The big advantage of having multiple repositories is
cvs.texi(,1830) that they can reside on different servers.  With @sc{cvs}
cvs.texi(,1831) version 1.10, a single command cannot recurse into
cvs.texi(,1832) directories from different repositories.  With development
cvs.texi(,1833) versions of @sc{cvs}, you can check out code from multiple
cvs.texi(,1834) servers into your working directory.  @sc{cvs} will
cvs.texi(,1835) recurse and handle all the details of making
cvs.texi(,1836) connections to as many server machines as necessary to
cvs.texi(,1837) perform the requested command.  Here is an example of
cvs.texi(,1838) how to set up a working directory:
cvs.texi(,1839) 
cvs.texi(,1840) @example
cvs.texi(,1841) cvs -d server1:/cvs co dir1
cvs.texi(,1842) cd dir1
cvs.texi(,1843) cvs -d server2:/root co sdir
cvs.texi(,1844) cvs update
cvs.texi(,1845) @end example
cvs.texi(,1846) 
cvs.texi(,1847) The @code{cvs co} commands set up the working
cvs.texi(,1848) directory, and then the @code{cvs update} command will
cvs.texi(,1849) contact server2, to update the dir1/sdir subdirectory,
cvs.texi(,1850) and server1, to update everything else.
cvs.texi(,1851) 
cvs.texi(,1852) @c FIXME: Does the FAQ have more about this?  I have a
cvs.texi(,1853) @c dim recollection, but I'm too lazy to check right now.
cvs.texi(,1854) 
cvs.texi(,1855) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,1856) @node Creating a repository
cvs.texi(,1857) @section Creating a repository
cvs.texi(,1858) 
cvs.texi(,1859) @cindex Repository, setting up
cvs.texi(,1860) @cindex Creating a repository
cvs.texi(,1861) @cindex Setting up a repository
cvs.texi(,1862) 
cvs.texi(,1863) To set up a @sc{cvs} repository, first choose the
cvs.texi(,1864) machine and disk on which you want to store the
cvs.texi(,1865) revision history of the source files.  CPU and memory
cvs.texi(,1866) requirements are modest, so most machines should be
cvs.texi(,1867) adequate.  For details see @ref{Server requirements}.
cvs.texi(,1868) @c Possible that we should be providing a quick rule of
cvs.texi(,1869) @c thumb, like the 32M memory for the server.  That
cvs.texi(,1870) @c might increase the number of people who are happy
cvs.texi(,1871) @c with the answer, without following the xref.
cvs.texi(,1872) 
cvs.texi(,1873) To estimate disk space
cvs.texi(,1874) requirements, if you are importing RCS files from
cvs.texi(,1875) another system, the size of those files is the
cvs.texi(,1876) approximate initial size of your repository, or if you
cvs.texi(,1877) are starting without any version history, a rule of
cvs.texi(,1878) thumb is to allow for the server approximately three
cvs.texi(,1879) times the size of the code to be under @sc{cvs} for the
cvs.texi(,1880) repository (you will eventually outgrow this, but not
cvs.texi(,1881) for a while).  On the machines on which the developers
cvs.texi(,1882) will be working, you'll want disk space for
cvs.texi(,1883) approximately one working directory for each developer
cvs.texi(,1884) (either the entire tree or a portion of it, depending
cvs.texi(,1885) on what each developer uses).
cvs.texi(,1886) 
cvs.texi(,1887) The repository should be accessible
cvs.texi(,1888) (directly or via a networked file system) from all
cvs.texi(,1889) machines which want to use @sc{cvs} in server or local
cvs.texi(,1890) mode; the client machines need not have any access to
cvs.texi(,1891) it other than via the @sc{cvs} protocol.  It is not
cvs.texi(,1892) possible to use @sc{cvs} to read from a repository
cvs.texi(,1893) which one only has read access to; @sc{cvs} needs to be
cvs.texi(,1894) able to create lock files (@pxref{Concurrency}).
cvs.texi(,1895) 
cvs.texi(,1896) @cindex init (subcommand)
cvs.texi(,1897) To create a repository, run the @code{cvs init}
cvs.texi(,1898) command.  It will set up an empty repository in the
cvs.texi(,1899) @sc{cvs} root specified in the usual way
cvs.texi(,1900) (@pxref{Repository}).  For example,
cvs.texi(,1901) 
cvs.texi(,1902) @example
cvs.texi(,1903) cvs -d /usr/local/cvsroot init
cvs.texi(,1904) @end example
cvs.texi(,1905) 
cvs.texi(,1906) @code{cvs init} is careful to never overwrite any
cvs.texi(,1907) existing files in the repository, so no harm is done if
cvs.texi(,1908) you run @code{cvs init} on an already set-up
cvs.texi(,1909) repository.
cvs.texi(,1910) 
cvs.texi(,1911) @code{cvs init} will enable history logging; if you
cvs.texi(,1912) don't want that, remove the history file after running
cvs.texi(,1913) @code{cvs init}.  @xref{history file}.
cvs.texi(,1914) 
cvs.texi(,1915) @node Backing up
cvs.texi(,1916) @section Backing up a repository
cvs.texi(,1917) @cindex Repository, backing up
cvs.texi(,1918) @cindex Backing up, repository
cvs.texi(,1919) 
cvs.texi(,1920) There is nothing particularly magical about the files
cvs.texi(,1921) in the repository; for the most part it is possible to
cvs.texi(,1922) back them up just like any other files.  However, there
cvs.texi(,1923) are a few issues to consider.
cvs.texi(,1924) 
cvs.texi(,1925) @cindex Locks, cvs, and backups
cvs.texi(,1926) @cindex #cvs.rfl, and backups
cvs.texi(,1927) The first is that to be paranoid, one should either not
cvs.texi(,1928) use @sc{cvs} during the backup, or have the backup
cvs.texi(,1929) program lock @sc{cvs} while doing the backup.  To not
cvs.texi(,1930) use @sc{cvs}, you might forbid logins to machines which
cvs.texi(,1931) can access the repository, turn off your @sc{cvs}
cvs.texi(,1932) server, or similar mechanisms.  The details would
cvs.texi(,1933) depend on your operating system and how you have
cvs.texi(,1934) @sc{cvs} set up.  To lock @sc{cvs}, you would create
cvs.texi(,1935) @file{#cvs.rfl} locks in each repository directory.
cvs.texi(,1936) See @ref{Concurrency}, for more on @sc{cvs} locks.
cvs.texi(,1937) Having said all this, if you just back up without any
cvs.texi(,1938) of these precautions, the results are unlikely to be
cvs.texi(,1939) particularly dire.  Restoring from backup, the
cvs.texi(,1940) repository might be in an inconsistent state, but this
cvs.texi(,1941) would not be particularly hard to fix manually.
cvs.texi(,1942) 
cvs.texi(,1943) When you restore a repository from backup, assuming
cvs.texi(,1944) that changes in the repository were made after the time
cvs.texi(,1945) of the backup, working directories which were not
cvs.texi(,1946) affected by the failure may refer to revisions which no
cvs.texi(,1947) longer exist in the repository.  Trying to run @sc{cvs}
cvs.texi(,1948) in such directories will typically produce an error
cvs.texi(,1949) message.  One way to get those changes back into the
cvs.texi(,1950) repository is as follows:
cvs.texi(,1951) 
cvs.texi(,1952) @itemize @bullet
cvs.texi(,1953) @item
cvs.texi(,1954) Get a new working directory.
cvs.texi(,1955) 
cvs.texi(,1956) @item
cvs.texi(,1957) Copy the files from the working directory from before
cvs.texi(,1958) the failure over to the new working directory (do not
cvs.texi(,1959) copy the contents of the @file{CVS} directories, of
cvs.texi(,1960) course).
cvs.texi(,1961) 
cvs.texi(,1962) @item
cvs.texi(,1963) Working in the new working directory, use commands such
cvs.texi(,1964) as @code{cvs update} and @code{cvs diff} to figure out
cvs.texi(,1965) what has changed, and then when you are ready, commit
cvs.texi(,1966) the changes into the repository.
cvs.texi(,1967) @end itemize
cvs.texi(,1968) 
cvs.texi(,1969) @node Moving a repository
cvs.texi(,1970) @section Moving a repository
cvs.texi(,1971) @cindex Repository, moving
cvs.texi(,1972) @cindex Moving a repository
cvs.texi(,1973) @cindex Copying a repository
cvs.texi(,1974) 
cvs.texi(,1975) Just as backing up the files in the repository is
cvs.texi(,1976) pretty much like backing up any other files, if you
cvs.texi(,1977) need to move a repository from one place to another it
cvs.texi(,1978) is also pretty much like just moving any other
cvs.texi(,1979) collection of files.
cvs.texi(,1980) 
cvs.texi(,1981) The main thing to consider is that working directories
cvs.texi(,1982) point to the repository.  The simplest way to deal with
cvs.texi(,1983) a moved repository is to just get a fresh working
cvs.texi(,1984) directory after the move.  Of course, you'll want to
cvs.texi(,1985) make sure that the old working directory had been
cvs.texi(,1986) checked in before the move, or you figured out some
cvs.texi(,1987) other way to make sure that you don't lose any
cvs.texi(,1988) changes.  If you really do want to reuse the existing
cvs.texi(,1989) working directory, it should be possible with manual
cvs.texi(,1990) surgery on the @file{CVS/Repository} files.  You can
cvs.texi(,1991) see @ref{Working directory storage}, for information on
cvs.texi(,1992) the @file{CVS/Repository} and @file{CVS/Root} files, but
cvs.texi(,1993) unless you are sure you want to bother, it probably
cvs.texi(,1994) isn't worth it.
cvs.texi(,1995) @c FIXME: Surgery on CVS/Repository should be avoided
cvs.texi(,1996) @c by making RELATIVE_REPOS the default.
cvs.texi(,1997) @c FIXME-maybe: might want some documented way to
cvs.texi(,1998) @c change the CVS/Root files in some particular tree.
cvs.texi(,1999) @c But then again, I don't know, maybe just having
cvs.texi(,2000) @c people do this in perl/shell/&c isn't so bad...
cvs.texi(,2001) 
cvs.texi(,2002) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,2003) @node Remote repositories
cvs.texi(,2004) @section Remote repositories
cvs.texi(,2005) @cindex Repositories, remote
cvs.texi(,2006) @cindex Remote repositories
cvs.texi(,2007) @cindex Client/Server Operation
cvs.texi(,2008) @cindex Server, CVS
cvs.texi(,2009) @cindex Remote repositories, port specification
cvs.texi(,2010) @cindex Repositories, remote, port specification
cvs.texi(,2011) @cindex Client/Server Operation, port specification
cvs.texi(,2012) @cindex pserver (client/server connection method), port specification
cvs.texi(,2013) @cindex kserver (client/server connection method), port specification
cvs.texi(,2014) @cindex gserver (client/server connection method), port specification
cvs.texi(,2015) @cindex port, specifying for remote repositories
cvs.texi(,2016) 
cvs.texi(,2017)         Your working copy of the sources can be on a
cvs.texi(,2018) different machine than the repository.  Using @sc{cvs}
cvs.texi(,2019) in this manner is known as @dfn{client/server}
cvs.texi(,2020) operation.  You run @sc{cvs} on a machine which can
cvs.texi(,2021) mount your working directory, known as the
cvs.texi(,2022) @dfn{client}, and tell it to communicate to a machine
cvs.texi(,2023) which can mount the repository, known as the
cvs.texi(,2024) @dfn{server}.  Generally, using a remote
cvs.texi(,2025) repository is just like using a local one, except that
cvs.texi(,2026) the format of the repository name is:
cvs.texi(,2027) 
cvs.texi(,2028) @example
cvs.texi(,2029) [:@var{method}:][[@var{user}][:@var{password}]@@]@var{hostname}[:[@var{port}]]/path/to/repository
cvs.texi(,2030) @end example
cvs.texi(,2031) 
cvs.texi(,2032) Specifying a password in the repository name is not recommended during
cvs.texi(,2033) checkout, since this will cause @sc{cvs} to store a cleartext copy of the
cvs.texi(,2034) password in each created directory.  @code{cvs login} first instead
cvs.texi(,2035) (@pxref{Password authentication client}).
cvs.texi(,2036) 
cvs.texi(,2037) The details of exactly what needs to be set up depend
cvs.texi(,2038) on how you are connecting to the server.
cvs.texi(,2039) 
cvs.texi(,2040) If @var{method} is not specified, and the repository
cvs.texi(,2041) name contains @samp{:}, then the default is @code{ext}
cvs.texi(,2042) or @code{server}, depending on your platform; both are
cvs.texi(,2043) described in @ref{Connecting via rsh}.
cvs.texi(,2044) @c Should we try to explain which platforms are which?
cvs.texi(,2045) @c Platforms like unix and VMS, which only allow
cvs.texi(,2046) @c privileged programs to bind to sockets <1024 lose on
cvs.texi(,2047) @c :server:
cvs.texi(,2048) @c Platforms like Mac and VMS, whose rsh program is
cvs.texi(,2049) @c unusable or nonexistent, lose on :ext:
cvs.texi(,2050) @c Platforms like OS/2 and NT probably could plausibly
cvs.texi(,2051) @c default either way (modulo -b troubles).
cvs.texi(,2052) 
cvs.texi(,2053) @c FIXME: We need to have a better way of explaining
cvs.texi(,2054) @c what method to use.  This presentation totally
cvs.texi(,2055) @c obscures the fact that :ext: and CVS_RSH is the way to
cvs.texi(,2056) @c use SSH, for example.  Plus it incorrectly implies
cvs.texi(,2057) @c that you need an @code{rsh} binary on the client to use
cvs.texi(,2058) @c :server:.
cvs.texi(,2059) @c Also note that rsh not pserver is the right choice if you want
cvs.texi(,2060) @c users to be able to create their own repositories
cvs.texi(,2061) @c (because of the --allow-root related issues).
cvs.texi(,2062) @menu
cvs.texi(,2063) * Server requirements::         Memory and other resources for servers
cvs.texi(,2064) * Connecting via rsh::          Using the @code{rsh} program to connect
cvs.texi(,2065) * Password authenticated::      Direct connections using passwords
cvs.texi(,2066) * GSSAPI authenticated::        Direct connections using GSSAPI
cvs.texi(,2067) * Kerberos authenticated::      Direct connections with kerberos
cvs.texi(,2068) * Connecting via fork::         Using a forked @code{cvs server} to connect
cvs.texi(,2069) @end menu
cvs.texi(,2070) 
cvs.texi(,2071) @node Server requirements
cvs.texi(,2072) @subsection Server requirements
cvs.texi(,2073) 
cvs.texi(,2074) The quick answer to what sort of machine is suitable as
cvs.texi(,2075) a server is that requirements are modest---a server
cvs.texi(,2076) with 32M of memory or even less can handle a fairly
cvs.texi(,2077) large source tree with a fair amount of activity.
cvs.texi(,2078) @c Say something about CPU speed too?  I'm even less sure
cvs.texi(,2079) @c what to say on that subject...
cvs.texi(,2080) 
cvs.texi(,2081) The real answer, of course, is more complicated.
cvs.texi(,2082) Estimating the known areas of large memory consumption
cvs.texi(,2083) should be sufficient to estimate memory requirements.
cvs.texi(,2084) There are two such areas documented here; other memory
cvs.texi(,2085) consumption should be small by comparison (if you find
cvs.texi(,2086) that is not the case, let us know, as described in
cvs.texi(,2087) @ref{BUGS}, so we can update this documentation).
cvs.texi(,2088) 
cvs.texi(,2089) The first area of big memory consumption is large
cvs.texi(,2090) checkouts, when using the @sc{cvs} server.  The server
cvs.texi(,2091) consists of two processes for each client that it is
cvs.texi(,2092) serving.  Memory consumption on the child process
cvs.texi(,2093) should remain fairly small.  Memory consumption on the
cvs.texi(,2094) parent process, particularly if the network connection
cvs.texi(,2095) to the client is slow, can be expected to grow to
cvs.texi(,2096) slightly more than the size of the sources in a single
cvs.texi(,2097) directory, or two megabytes, whichever is larger.
cvs.texi(,2098) @c "two megabytes" of course is SERVER_HI_WATER.  But
cvs.texi(,2099) @c we don't mention that here because we are
cvs.texi(,2100) @c documenting the default configuration of CVS.  If it
cvs.texi(,2101) @c is a "standard" thing to change that value, it
cvs.texi(,2102) @c should be some kind of run-time configuration.
cvs.texi(,2103) @c
cvs.texi(,2104) @c See cvsclient.texi for more on the design decision
cvs.texi(,2105) @c to not have locks in place while waiting for the
cvs.texi(,2106) @c client, which is what results in memory consumption
cvs.texi(,2107) @c as high as this.
cvs.texi(,2108) 
cvs.texi(,2109) Multiplying the size of each @sc{cvs} server by the
cvs.texi(,2110) number of servers which you expect to have active at
cvs.texi(,2111) one time should give an idea of memory requirements for
cvs.texi(,2112) the server.  For the most part, the memory consumed by
cvs.texi(,2113) the parent process probably can be swap space rather
cvs.texi(,2114) than physical memory.
cvs.texi(,2115) @c Has anyone verified that notion about swap space?
cvs.texi(,2116) @c I say it based pretty much on guessing that the
cvs.texi(,2117) @c ->text of the struct buffer_data only gets accessed
cvs.texi(,2118) @c in a first in, first out fashion, but I haven't
cvs.texi(,2119) @c looked very closely.
cvs.texi(,2120) 
cvs.texi(,2121) @c What about disk usage in /tmp on the server?  I think that
cvs.texi(,2122) @c it can be substantial, but I haven't looked at this
cvs.texi(,2123) @c again and tried to figure it out ("cvs import" is
cvs.texi(,2124) @c probably the worst case...).
cvs.texi(,2125) 
cvs.texi(,2126) The second area of large memory consumption is
cvs.texi(,2127) @code{diff}, when checking in large files.  This is
cvs.texi(,2128) required even for binary files.  The rule of thumb is
cvs.texi(,2129) to allow about ten times the size of the largest file
cvs.texi(,2130) you will want to check in, although five times may be
cvs.texi(,2131) adequate.  For example, if you want to check in a file
cvs.texi(,2132) which is 10 megabytes, you should have 100 megabytes of
cvs.texi(,2133) memory on the machine doing the checkin (the server
cvs.texi(,2134) machine for client/server, or the machine running
cvs.texi(,2135) @sc{cvs} for non-client/server).  This can be swap
cvs.texi(,2136) space rather than physical memory.  Because the memory
cvs.texi(,2137) is only required briefly, there is no particular need
cvs.texi(,2138) to allow memory for more than one such checkin at a
cvs.texi(,2139) time.
cvs.texi(,2140) @c The 5-10 times rule of thumb is from Paul Eggert for
cvs.texi(,2141) @c GNU diff.  I don't think it is in the GNU diff
cvs.texi(,2142) @c manual or anyplace like that.
cvs.texi(,2143) @c
cvs.texi(,2144) @c Probably we could be saying more about
cvs.texi(,2145) @c non-client/server CVS.
cvs.texi(,2146) @c I would guess for non-client/server CVS in an NFS
cvs.texi(,2147) @c environment the biggest issues are the network and
cvs.texi(,2148) @c the NFS server.
cvs.texi(,2149) 
cvs.texi(,2150) Resource consumption for the client is even more
cvs.texi(,2151) modest---any machine with enough capacity to run the
cvs.texi(,2152) operating system in question should have little
cvs.texi(,2153) trouble.
cvs.texi(,2154) @c Is that true?  I think the client still wants to
cvs.texi(,2155) @c (bogusly) store entire files in memory at times.
cvs.texi(,2156) 
cvs.texi(,2157) For information on disk space requirements, see
cvs.texi(,2158) @ref{Creating a repository}.
cvs.texi(,2159) 
cvs.texi(,2160) @node Connecting via rsh
cvs.texi(,2161) @subsection Connecting with rsh
cvs.texi(,2162) 
cvs.texi(,2163) @cindex rsh
cvs.texi(,2164) @sc{cvs} uses the @samp{rsh} protocol to perform these
cvs.texi(,2165) operations, so the remote user host needs to have a
cvs.texi(,2166) @file{.rhosts} file which grants access to the local
cvs.texi(,2167) user. Note that the program that @sc{cvs} uses for this
cvs.texi(,2168) purpose may be specified using the @file{--with-rsh}
cvs.texi(,2169) flag to configure.
cvs.texi(,2170) 
cvs.texi(,2171) For example, suppose you are the user @samp{mozart} on
cvs.texi(,2172) the local machine @samp{toe.example.com}, and the
cvs.texi(,2173) server machine is @samp{faun.example.org}.  On
cvs.texi(,2174) faun, put the following line into the file
cvs.texi(,2175) @file{.rhosts} in @samp{bach}'s home directory:
cvs.texi(,2176) 
cvs.texi(,2177) @example
cvs.texi(,2178) toe.example.com  mozart
cvs.texi(,2179) @end example
cvs.texi(,2180) 
cvs.texi(,2181) @noindent
cvs.texi(,2182) Then test that @samp{rsh} is working with
cvs.texi(,2183) 
cvs.texi(,2184) @example
cvs.texi(,2185) rsh -l bach faun.example.org 'echo $PATH'
cvs.texi(,2186) @end example
cvs.texi(,2187) 
cvs.texi(,2188) @cindex CVS_SERVER, environment variable
cvs.texi(,2189) Next you have to make sure that @code{rsh} will be able
cvs.texi(,2190) to find the server.  Make sure that the path which
cvs.texi(,2191) @code{rsh} printed in the above example includes the
cvs.texi(,2192) directory containing a program named @code{cvs} which
cvs.texi(,2193) is the server.  You need to set the path in
cvs.texi(,2194) @file{.bashrc}, @file{.cshrc}, etc., not @file{.login}
cvs.texi(,2195) or @file{.profile}.  Alternately, you can set the
cvs.texi(,2196) environment variable @code{CVS_SERVER} on the client
cvs.texi(,2197) machine to the filename of the server you want to use,
cvs.texi(,2198) for example @file{/usr/local/bin/cvs-1.6}.
cvs.texi(,2199) @c FIXME: there should be a way to specify the
cvs.texi(,2200) @c program in CVSROOT, not CVS_SERVER, so that one can use
cvs.texi(,2201) @c different ones for different roots.  e.g. ":server;cvs=cvs-1.6:"
cvs.texi(,2202) @c instead of ":server:".
cvs.texi(,2203) 
cvs.texi(,2204) There is no need to edit @file{inetd.conf} or start a
cvs.texi(,2205) @sc{cvs} server daemon.
cvs.texi(,2206) 
cvs.texi(,2207) @cindex :server:, setting up
cvs.texi(,2208) @cindex :ext:, setting up
cvs.texi(,2209) @cindex Kerberos, using kerberized rsh
cvs.texi(,2210) @cindex SSH (rsh replacement)
cvs.texi(,2211) @cindex rsh replacements (Kerberized, SSH, &c)
cvs.texi(,2212) There are two access methods that you use in @code{CVSROOT}
cvs.texi(,2213) for rsh.  @code{:server:} specifies an internal rsh
cvs.texi(,2214) client, which is supported only by some @sc{cvs} ports.
cvs.texi(,2215) @code{:ext:} specifies an external rsh program.  By
cvs.texi(,2216) default this is @code{rsh} (unless otherwise specified
cvs.texi(,2217) by the @file{--with-rsh} flag to configure) but you may set the
cvs.texi(,2218) @code{CVS_RSH} environment variable to invoke another
cvs.texi(,2219) program which can access the remote server (for
cvs.texi(,2220) example, @code{remsh} on HP-UX 9 because @code{rsh} is
cvs.texi(,2221) something different).  It must be a program which can
cvs.texi(,2222) transmit data to and from the server without modifying
cvs.texi(,2223) it; for example the Windows NT @code{rsh} is not
cvs.texi(,2224) suitable since it by default translates between CRLF
cvs.texi(,2225) and LF.  The OS/2 @sc{cvs} port has a hack to pass @samp{-b}
cvs.texi(,2226) to @code{rsh} to get around this, but since this could
cvs.texi(,2227) potentially cause problems for programs other than the
cvs.texi(,2228) standard @code{rsh}, it may change in the future.  If
cvs.texi(,2229) you set @code{CVS_RSH} to @code{SSH} or some other rsh
cvs.texi(,2230) replacement, the instructions in the rest of this
cvs.texi(,2231) section concerning @file{.rhosts} and so on are likely
cvs.texi(,2232) to be inapplicable; consult the documentation for your rsh
cvs.texi(,2233) replacement.
cvs.texi(,2234) @c FIXME: there should be a way to specify the
cvs.texi(,2235) @c program in CVSROOT, not CVS_RSH, so that one can use
cvs.texi(,2236) @c different ones for different roots.  e.g. ":ext;rsh=remsh:"
cvs.texi(,2237) @c instead of ":ext:".
cvs.texi(,2238) @c See also the comment in src/client.c for rationale
cvs.texi(,2239) @c concerning "rsh" being the default and never
cvs.texi(,2240) @c "remsh".
cvs.texi(,2241) 
cvs.texi(,2242) Continuing our example, supposing you want to access
cvs.texi(,2243) the module @file{foo} in the repository
cvs.texi(,2244) @file{/usr/local/cvsroot/}, on machine
cvs.texi(,2245) @file{faun.example.org}, you are ready to go:
cvs.texi(,2246) 
cvs.texi(,2247) @example
cvs.texi(,2248) cvs -d :ext:bach@@faun.example.org:/usr/local/cvsroot checkout foo
cvs.texi(,2249) @end example
cvs.texi(,2250) 
cvs.texi(,2251) @noindent
cvs.texi(,2252) (The @file{bach@@} can be omitted if the username is
cvs.texi(,2253) the same on both the local and remote hosts.)
cvs.texi(,2254) 
cvs.texi(,2255) @c Should we mention "rsh host echo hi" and "rsh host
cvs.texi(,2256) @c cat" (the latter followed by typing text and ^D)
cvs.texi(,2257) @c as troubleshooting techniques?  Probably yes
cvs.texi(,2258) @c (people tend to have trouble setting this up),
cvs.texi(,2259) @c but this kind of thing can be hard to spell out.
cvs.texi(,2260) 
cvs.texi(,2261) @node Password authenticated
cvs.texi(,2262) @subsection Direct connection with password authentication
cvs.texi(,2263) 
cvs.texi(,2264) The @sc{cvs} client can also connect to the server
cvs.texi(,2265) using a password protocol.  This is particularly useful
cvs.texi(,2266) if using @code{rsh} is not feasible (for example,
cvs.texi(,2267) the server is behind a firewall), and Kerberos also is
cvs.texi(,2268) not available.
cvs.texi(,2269) 
cvs.texi(,2270)         To use this method, it is necessary to make
cvs.texi(,2271) some adjustments on both the server and client sides.
cvs.texi(,2272) 
cvs.texi(,2273) @menu
cvs.texi(,2274) * Password authentication server::     Setting up the server
cvs.texi(,2275) * Password authentication client::     Using the client
cvs.texi(,2276) * Password authentication security::   What this method does and does not do
cvs.texi(,2277) @end menu
cvs.texi(,2278) 
cvs.texi(,2279) @node Password authentication server
cvs.texi(,2280) @subsubsection Setting up the server for password authentication
cvs.texi(,2281) 
cvs.texi(,2282) First of all, you probably want to tighten the
cvs.texi(,2283) permissions on the @file{$CVSROOT} and
cvs.texi(,2284) @file{$CVSROOT/CVSROOT} directories.  See @ref{Password
cvs.texi(,2285) authentication security}, for more details.
cvs.texi(,2286) 
cvs.texi(,2287) @cindex pserver (subcommand)
cvs.texi(,2288) @cindex Remote repositories, port specification
cvs.texi(,2289) @cindex Repositories, remote, port specification
cvs.texi(,2290) @cindex Client/Server Operation, port specification
cvs.texi(,2291) @cindex pserver (client/server connection method), port specification
cvs.texi(,2292) @cindex kserver (client/server connection method), port specification
cvs.texi(,2293) @cindex gserver (client/server connection method), port specification
cvs.texi(,2294) @cindex port, specifying for remote repositories
cvs.texi(,2295) @cindex Password server, setting up
cvs.texi(,2296) @cindex Authenticating server, setting up
cvs.texi(,2297) @cindex inetd, configuring for pserver
cvs.texi(,2298) @cindex xinetd, configuring for pserver
cvs.texi(,2299) @c FIXME: this isn't quite right regarding port
cvs.texi(,2300) @c numbers; CVS looks up "cvspserver" in
cvs.texi(,2301) @c /etc/services (on unix, but what about non-unix?).
cvs.texi(,2302) On the server side, the file @file{/etc/inetd.conf}
cvs.texi(,2303) needs to be edited so @code{inetd} knows to run the
cvs.texi(,2304) command @code{cvs pserver} when it receives a
cvs.texi(,2305) connection on the right port.  By default, the port
cvs.texi(,2306) number is 2401; it would be different if your client
cvs.texi(,2307) were compiled with @code{CVS_AUTH_PORT} defined to
cvs.texi(,2308) something else, though.  This can also be specified in the CVSROOT variable
cvs.texi(,2309) (@pxref{Remote repositories}) or overridden with the CVS_CLIENT_PORT
cvs.texi(,2310) environment variable (@pxref{Environment variables}).
cvs.texi(,2311) 
cvs.texi(,2312)         If your @code{inetd} allows raw port numbers in
cvs.texi(,2313) @file{/etc/inetd.conf}, then the following (all on a
cvs.texi(,2314) single line in @file{inetd.conf}) should be sufficient:
cvs.texi(,2315) 
cvs.texi(,2316) @example
cvs.texi(,2317) 2401  stream  tcp  nowait  root  /usr/local/bin/cvs
cvs.texi(,2318) cvs -f --allow-root=/usr/cvsroot pserver
cvs.texi(,2319) @end example
cvs.texi(,2320) 
cvs.texi(,2321) @noindent
cvs.texi(,2322) (You could also use the
cvs.texi(,2323) @samp{-T} option to specify a temporary directory.)
cvs.texi(,2324) 
cvs.texi(,2325) The @samp{--allow-root} option specifies the allowable
cvs.texi(,2326) @sc{cvsroot} directory.  Clients which attempt to use a
cvs.texi(,2327) different @sc{cvsroot} directory will not be allowed to
cvs.texi(,2328) connect.  If there is more than one @sc{cvsroot}
cvs.texi(,2329) directory which you want to allow, repeat the option.
cvs.texi(,2330) (Unfortunately, many versions of @code{inetd} have very small
cvs.texi(,2331) limits on the number of arguments and/or the total length
cvs.texi(,2332) of the command.  The usual solution to this problem is
cvs.texi(,2333) to have @code{inetd} run a shell script which then invokes
cvs.texi(,2334) @sc{cvs} with the necessary arguments.)
cvs.texi(,2335) 
cvs.texi(,2336)         If your @code{inetd} wants a symbolic service
cvs.texi(,2337) name instead of a raw port number, then put this in
cvs.texi(,2338) @file{/etc/services}:
cvs.texi(,2339) 
cvs.texi(,2340) @example
cvs.texi(,2341) cvspserver      2401/tcp
cvs.texi(,2342) @end example
cvs.texi(,2343) 
cvs.texi(,2344) @noindent
cvs.texi(,2345) and put @code{cvspserver} instead of @code{2401} in @file{inetd.conf}.
cvs.texi(,2346) 
cvs.texi(,2347) If your system uses @code{xinetd} instead of @code{inetd},
cvs.texi(,2348) the procedure is slightly different.
cvs.texi(,2349) Create a file called @file{/etc/xinetd.d/cvspserver} containing the following:
cvs.texi(,2350) 
cvs.texi(,2351) @example
cvs.texi(,2352) service cvspserver
cvs.texi(,2353) @{
cvs.texi(,2354)    port        = 2401
cvs.texi(,2355)    socket_type = stream
cvs.texi(,2356)    protocol    = tcp
cvs.texi(,2357)    wait        = no
cvs.texi(,2358)    user        = root
cvs.texi(,2359)    passenv     = PATH
cvs.texi(,2360)    server      = /usr/local/bin/cvs
cvs.texi(,2361)    server_args = -f --allow-root=/usr/cvsroot pserver
cvs.texi(,2362) @}
cvs.texi(,2363) @end example
cvs.texi(,2364) 
cvs.texi(,2365) @noindent
cvs.texi(,2366) (If @code{cvspserver} is defined in @file{/etc/services}, you can omit
cvs.texi(,2367) the @code{port} line.)
cvs.texi(,2368) 
cvs.texi(,2369)         Once the above is taken care of, restart your
cvs.texi(,2370) @code{inetd}, or do whatever is necessary to force it
cvs.texi(,2371) to reread its initialization files.
cvs.texi(,2372) 
cvs.texi(,2373) If you are having trouble setting this up, see
cvs.texi(,2374) @ref{Connection}.
cvs.texi(,2375) 
cvs.texi(,2376) @cindex CVS passwd file
cvs.texi(,2377) @cindex passwd (admin file)
cvs.texi(,2378) Because the client stores and transmits passwords in
cvs.texi(,2379) cleartext (almost---see @ref{Password authentication
cvs.texi(,2380) security}, for details), a separate @sc{cvs} password
cvs.texi(,2381) file is generally used, so people don't compromise
cvs.texi(,2382) their regular passwords when they access the
cvs.texi(,2383) repository.  This file is
cvs.texi(,2384) @file{$CVSROOT/CVSROOT/passwd} (@pxref{Intro
cvs.texi(,2385) administrative files}).  It uses a colon-separated
cvs.texi(,2386) format, similar to @file{/etc/passwd} on Unix systems,
cvs.texi(,2387) except that it has fewer fields: @sc{cvs} username,
cvs.texi(,2388) optional password, and an optional system username for
cvs.texi(,2389) @sc{cvs} to run as if authentication succeeds.  Here is
cvs.texi(,2390) an example @file{passwd} file with five entries:
cvs.texi(,2391) 
cvs.texi(,2392) @example
cvs.texi(,2393) anonymous:
cvs.texi(,2394) bach:ULtgRLXo7NRxs
cvs.texi(,2395) spwang:1sOp854gDF3DY
cvs.texi(,2396) melissa:tGX1fS8sun6rY:pubcvs
cvs.texi(,2397) qproj:XR4EZcEs0szik:pubcvs
cvs.texi(,2398) @end example
cvs.texi(,2399) 
cvs.texi(,2400) @noindent
cvs.texi(,2401) (The passwords are encrypted according to the standard
cvs.texi(,2402) Unix @code{crypt()} function, so it is possible to
cvs.texi(,2403) paste in passwords directly from regular Unix
cvs.texi(,2404) @file{/etc/passwd} files.)
cvs.texi(,2405) 
cvs.texi(,2406) The first line in the example will grant access to any
cvs.texi(,2407) @sc{cvs} client attempting to authenticate as user
cvs.texi(,2408) @code{anonymous}, no matter what password they use,
cvs.texi(,2409) including an empty password.  (This is typical for
cvs.texi(,2410) sites granting anonymous read-only access; for
cvs.texi(,2411) information on how to do the "read-only" part, see
cvs.texi(,2412) @ref{Read-only access}.)
cvs.texi(,2413) 
cvs.texi(,2414) The second and third lines will grant access to
cvs.texi(,2415) @code{bach} and @code{spwang} if they supply their
cvs.texi(,2416) respective plaintext passwords.
cvs.texi(,2417) 
cvs.texi(,2418) @cindex User aliases
cvs.texi(,2419) The fourth line will grant access to @code{melissa}, if
cvs.texi(,2420) she supplies the correct password, but her @sc{cvs}
cvs.texi(,2421) operations will actually run on the server side under
cvs.texi(,2422) the system user @code{pubcvs}.  Thus, there need not be
cvs.texi(,2423) any system user named @code{melissa}, but there
cvs.texi(,2424) @emph{must} be one named @code{pubcvs}.
cvs.texi(,2425) 
cvs.texi(,2426) The fifth line shows that system user identities can be
cvs.texi(,2427) shared: any client who successfully authenticates as
cvs.texi(,2428) @code{qproj} will actually run as @code{pubcvs}, just
cvs.texi(,2429) as @code{melissa} does.  That way you could create a
cvs.texi(,2430) single, shared system user for each project in your
cvs.texi(,2431) repository, and give each developer their own line in
cvs.texi(,2432) the @file{$CVSROOT/CVSROOT/passwd} file.  The @sc{cvs}
cvs.texi(,2433) username on each line would be different, but the
cvs.texi(,2434) system username would be the same.  The reason to have
cvs.texi(,2435) different @sc{cvs} usernames is that @sc{cvs} will log their
cvs.texi(,2436) actions under those names: when @code{melissa} commits
cvs.texi(,2437) a change to a project, the checkin is recorded in the
cvs.texi(,2438) project's history under the name @code{melissa}, not
cvs.texi(,2439) @code{pubcvs}.  And the reason to have them share a
cvs.texi(,2440) system username is so that you can arrange permissions
cvs.texi(,2441) in the relevant area of the repository such that only
cvs.texi(,2442) that account has write-permission there.
cvs.texi(,2443) 
cvs.texi(,2444) If the system-user field is present, all
cvs.texi(,2445) password-authenticated @sc{cvs} commands run as that
cvs.texi(,2446) user; if no system user is specified, @sc{cvs} simply
cvs.texi(,2447) takes the @sc{cvs} username as the system username and
cvs.texi(,2448) runs commands as that user.  In either case, if there
cvs.texi(,2449) is no such user on the system, then the @sc{cvs}
cvs.texi(,2450) operation will fail (regardless of whether the client
cvs.texi(,2451) supplied a valid password).
cvs.texi(,2452) 
cvs.texi(,2453) The password and system-user fields can both be omitted
cvs.texi(,2454) (and if the system-user field is omitted, then also
cvs.texi(,2455) omit the colon that would have separated it from the
cvs.texi(,2456) encrypted password).  For example, this would be a
cvs.texi(,2457) valid @file{$CVSROOT/CVSROOT/passwd} file:
cvs.texi(,2458) 
cvs.texi(,2459) @example
cvs.texi(,2460) anonymous::pubcvs
cvs.texi(,2461) fish:rKa5jzULzmhOo:kfogel
cvs.texi(,2462) sussman:1sOp854gDF3DY
cvs.texi(,2463) @end example
cvs.texi(,2464) 
cvs.texi(,2465) @noindent
cvs.texi(,2466) When the password field is omitted or empty, then the
cvs.texi(,2467) client's authentication attempt will succeed with any
cvs.texi(,2468) password, including the empty string.  However, the
cvs.texi(,2469) colon after the @sc{cvs} username is always necessary,
cvs.texi(,2470) even if the password is empty.
cvs.texi(,2471) 
cvs.texi(,2472) @sc{cvs} can also fall back to use system authentication.
cvs.texi(,2473) When authenticating a password, the server first checks
cvs.texi(,2474) for the user in the @file{$CVSROOT/CVSROOT/passwd}
cvs.texi(,2475) file.  If it finds the user, it will use that entry for
cvs.texi(,2476) authentication as described above.  But if it does not
cvs.texi(,2477) find the user, or if the @sc{cvs} @file{passwd} file
cvs.texi(,2478) does not exist, then the server can try to authenticate
cvs.texi(,2479) the username and password using the operating system's
cvs.texi(,2480) user-lookup routines (this "fallback" behavior can be
cvs.texi(,2481) disabled by setting @code{SystemAuth=no} in the
cvs.texi(,2482) @sc{cvs} @file{config} file, @pxref{config}).
cvs.texi(,2483) 
cvs.texi(,2484) The default fallback behaviour is to look in 
cvs.texi(,2485) @file{/etc/passwd} for this system password unless your
cvs.texi(,2486) system has PAM (Pluggable Authentication Modules)
cvs.texi(,2487) and your @sc{cvs} server executable was configured to
cvs.texi(,2488) use it at compile time (using @code{./configure --enable-pam} - see the
cvs.texi(,2489) INSTALL file for more).  In this case, PAM will be consulted instead.
cvs.texi(,2490) This means that @sc{cvs} can be configured to use any password
cvs.texi(,2491) authentication source PAM can be configured to use (possibilities
cvs.texi(,2492) include a simple UNIX password, NIS, LDAP, and others) in its
cvs.texi(,2493) global configuration file (usually @file{/etc/pam.conf}
cvs.texi(,2494) or possibly @file{/etc/pam.d/cvs}).  See your PAM documentation
cvs.texi(,2495) for more details on PAM configuration.
cvs.texi(,2496) 
cvs.texi(,2497) Note that PAM is an experimental feature in @sc{cvs} and feedback is
cvs.texi(,2498) encouraged.  Please send a mail to one of the @sc{cvs} mailing lists
cvs.texi(,2499) (@code{info-cvs@@gnu.org} or @code{bug-cvs@@gnu.org}) if you use the 
cvs.texi(,2500) @sc{cvs} PAM support.
cvs.texi(,2501) 
cvs.texi(,2502) @strong{WARNING: Using PAM gives the system administrator much more 
cvs.texi(,2503) flexibility about how @sc{cvs} users are authenticated but 
cvs.texi(,2504) no more security than other methods.  See below for more.} 
cvs.texi(,2505) 
cvs.texi(,2506) CVS needs an "auth" and "account" module in the 
cvs.texi(,2507) PAM configuration file. A typical PAM configuration 
cvs.texi(,2508) would therefore have the following lines 
cvs.texi(,2509) in @file{/etc/pam.conf} to emulate the standard @sc{cvs} 
cvs.texi(,2510) system @file{/etc/passwd} authentication:
cvs.texi(,2511) 
cvs.texi(,2512) @example
cvs.texi(,2513) cvs	auth	    required	pam_unix.so
cvs.texi(,2514) cvs	account	    required	pam_unix.so
cvs.texi(,2515) @end example
cvs.texi(,2516) 
cvs.texi(,2517) The the equivalent @file{/etc/pam.d/cvs} would contain
cvs.texi(,2518) 
cvs.texi(,2519) @example
cvs.texi(,2520) auth	    required	pam_unix.so
cvs.texi(,2521) account	    required	pam_unix.so
cvs.texi(,2522) @end example
cvs.texi(,2523) 
cvs.texi(,2524) Some systems require a full path to the module so that
cvs.texi(,2525) @file{pam_unix.so} (Linux) would become something like 
cvs.texi(,2526) @file{/usr/lib/security/$ISA/pam_unix.so.1} (Sun Solaris).
cvs.texi(,2527) See the @file{contrib/pam} subdirectory of the @sc{cvs}
cvs.texi(,2528) source distribution for further example configurations.
cvs.texi(,2529) 
cvs.texi(,2530) The PAM service name given above as "cvs" is just
cvs.texi(,2531) the service name in the default configuration amd can be
cvs.texi(,2532) set using
cvs.texi(,2533) @code{./configure --with-hardcoded-pam-service-name=<pam-service-name>}
cvs.texi(,2534) before compiling.  @sc{cvs} can also be configured to use whatever
cvs.texi(,2535) name it is invoked as as its PAM service name using
cvs.texi(,2536) @code{./configure --without-hardcoded-pam-service-name}, but this
cvs.texi(,2537) feature should not be used if you may not have control of the name
cvs.texi(,2538) @sc{cvs} will be invoked as.
cvs.texi(,2539) 
cvs.texi(,2540) Be aware, also, that falling back to system
cvs.texi(,2541) authentication might be a security risk: @sc{cvs}
cvs.texi(,2542) operations would then be authenticated with that user's
cvs.texi(,2543) regular login password, and the password flies across
cvs.texi(,2544) the network in plaintext.  See @ref{Password
cvs.texi(,2545) authentication security} for more on this.
cvs.texi(,2546) This may be more of a problem with PAM authentication
cvs.texi(,2547) because it is likely that the source of the system 
cvs.texi(,2548) password is some central authentication service like
cvs.texi(,2549) LDAP which is also used to authenticate other services.
cvs.texi(,2550) 
cvs.texi(,2551) On the other hand, PAM makes it very easy to change your password
cvs.texi(,2552) regularly.  If they are given the option of a one-password system for
cvs.texi(,2553) all of their activities, users are often more willing to change their
cvs.texi(,2554) password on a regular basis.
cvs.texi(,2555) 
cvs.texi(,2556) In the non-PAM configuration where the password is stored in the
cvs.texi(,2557) @file{CVSROOT/passwd} file, it is difficult to change passwords on a
cvs.texi(,2558) regular basis since only administrative users (or in some cases
cvs.texi(,2559) processes that act as an administrative user) are typicaly given
cvs.texi(,2560) access to modify this file.  Either there needs to be some
cvs.texi(,2561) hand-crafted web page or set-uid program to update the file, or the
cvs.texi(,2562) update needs to be done by submitting a request to an administrator to
cvs.texi(,2563) perform the duty by hand.  In the first case, having to remember to
cvs.texi(,2564) update a separate password on a periodic basis can be difficult.  In
cvs.texi(,2565) the second case, the manual nature of the change will typically mean
cvs.texi(,2566) that the password will not be changed unless it is absolutely
cvs.texi(,2567) necessary.
cvs.texi(,2568) 
cvs.texi(,2569) Note that PAM administrators should probably avoid configuring
cvs.texi(,2570) one-time-passwords (OTP) for @sc{cvs} authentication/authorization.  If
cvs.texi(,2571) OTPs are desired, the administrator may wish to encourage the use of
cvs.texi(,2572) one of the other Client/Server access methods.  See the section on
cvs.texi(,2573) @pxref{Remote repositories} for a list of other methods.
cvs.texi(,2574) 
cvs.texi(,2575) Right now, the only way to put a password in the
cvs.texi(,2576) @sc{cvs} @file{passwd} file is to paste it there from
cvs.texi(,2577) somewhere else.  Someday, there may be a @code{cvs
cvs.texi(,2578) passwd} command.
cvs.texi(,2579) 
cvs.texi(,2580) Unlike many of the files in @file{$CVSROOT/CVSROOT}, it
cvs.texi(,2581) is normal to edit the @file{passwd} file in-place,
cvs.texi(,2582) rather than via @sc{cvs}.  This is because of the
cvs.texi(,2583) possible security risks of having the @file{passwd}
cvs.texi(,2584) file checked out to people's working copies.  If you do
cvs.texi(,2585) want to include the @file{passwd} file in checkouts of
cvs.texi(,2586) @file{$CVSROOT/CVSROOT}, see @ref{checkoutlist}.
cvs.texi(,2587) 
cvs.texi(,2588) @c We might also suggest using the @code{htpasswd} command
cvs.texi(,2589) @c from freely available web servers as well, but that
cvs.texi(,2590) @c would open up a can of worms in that the users next
cvs.texi(,2591) @c questions are likely to be "where do I get it?" and
cvs.texi(,2592) @c "how do I use it?"
cvs.texi(,2593) @c Also note that htpasswd, at least the version I had,
cvs.texi(,2594) @c likes to clobber the third field.
cvs.texi(,2595) 
cvs.texi(,2596) @node Password authentication client
cvs.texi(,2597) @subsubsection Using the client with password authentication
cvs.texi(,2598) @cindex Login (subcommand)
cvs.texi(,2599) @cindex Password client, using
cvs.texi(,2600) @cindex Authenticated client, using
cvs.texi(,2601) @cindex :pserver:, setting up
cvs.texi(,2602) To run a @sc{cvs} command on a remote repository via
cvs.texi(,2603) the password-authenticating server, one specifies the
cvs.texi(,2604) @code{pserver} protocol, optional username, repository host, an
cvs.texi(,2605) optional port number, and path to the repository.  For example:
cvs.texi(,2606) 
cvs.texi(,2607) @example
cvs.texi(,2608) cvs -d :pserver:faun.example.org:/usr/local/cvsroot checkout someproj
cvs.texi(,2609) @end example
cvs.texi(,2610) 
cvs.texi(,2611) @noindent
cvs.texi(,2612) or
cvs.texi(,2613) 
cvs.texi(,2614) @example
cvs.texi(,2615) CVSROOT=:pserver:bach@@faun.example.org:2401/usr/local/cvsroot
cvs.texi(,2616) cvs checkout someproj
cvs.texi(,2617) @end example
cvs.texi(,2618) 
cvs.texi(,2619) However, unless you're connecting to a public-access
cvs.texi(,2620) repository (i.e., one where that username doesn't
cvs.texi(,2621) require a password), you'll need to supply a password or @dfn{log in} first.
cvs.texi(,2622) Logging in verifies your password with the repository and stores it in a file.
cvs.texi(,2623) It's done with the @code{login} command, which will
cvs.texi(,2624) prompt you interactively for the password if you didn't supply one as part of
cvs.texi(,2625) @var{$CVSROOT}:
cvs.texi(,2626) 
cvs.texi(,2627) @example
cvs.texi(,2628) cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot login
cvs.texi(,2629) CVS password:
cvs.texi(,2630) @end example
cvs.texi(,2631) 
cvs.texi(,2632) @noindent
cvs.texi(,2633) or
cvs.texi(,2634) 
cvs.texi(,2635) @example
cvs.texi(,2636) cvs -d :pserver:bach:p4ss30rd@@faun.example.org:/usr/local/cvsroot login
cvs.texi(,2637) @end example
cvs.texi(,2638) 
cvs.texi(,2639) After you enter the password, @sc{cvs} verifies it with
cvs.texi(,2640) the server.  If the verification succeeds, then that
cvs.texi(,2641) combination of username, host, repository, and password
cvs.texi(,2642) is permanently recorded, so future transactions with
cvs.texi(,2643) that repository won't require you to run @code{cvs
cvs.texi(,2644) login}.  (If verification fails, @sc{cvs} will exit
cvs.texi(,2645) complaining that the password was incorrect, and
cvs.texi(,2646) nothing will be recorded.)
cvs.texi(,2647) 
cvs.texi(,2648) The records are stored, by default, in the file
cvs.texi(,2649) @file{$HOME/.cvspass}.  That file's format is
cvs.texi(,2650) human-readable, and to a degree human-editable, but
cvs.texi(,2651) note that the passwords are not stored in
cvs.texi(,2652) cleartext---they are trivially encoded to protect them
cvs.texi(,2653) from "innocent" compromise (i.e., inadvertent viewing
cvs.texi(,2654) by a system administrator or other non-malicious
cvs.texi(,2655) person).
cvs.texi(,2656) 
cvs.texi(,2657) @cindex CVS_PASSFILE, environment variable
cvs.texi(,2658) You can change the default location of this file by
cvs.texi(,2659) setting the @code{CVS_PASSFILE} environment variable.
cvs.texi(,2660) If you use this variable, make sure you set it
cvs.texi(,2661) @emph{before} @code{cvs login} is run.  If you were to
cvs.texi(,2662) set it after running @code{cvs login}, then later
cvs.texi(,2663) @sc{cvs} commands would be unable to look up the
cvs.texi(,2664) password for transmission to the server.
cvs.texi(,2665)   
cvs.texi(,2666) Once you have logged in, all @sc{cvs} commands using
cvs.texi(,2667) that remote repository and username will authenticate
cvs.texi(,2668) with the stored password.  So, for example
cvs.texi(,2669)   
cvs.texi(,2670) @example
cvs.texi(,2671) cvs -d :pserver:bach@@faun.example.org:/usr/local/cvsroot checkout foo
cvs.texi(,2672) @end example
cvs.texi(,2673) 
cvs.texi(,2674) @noindent
cvs.texi(,2675) should just work (unless the password changes on the
cvs.texi(,2676) server side, in which case you'll have to re-run
cvs.texi(,2677) @code{cvs login}).
cvs.texi(,2678) 
cvs.texi(,2679) Note that if the @samp{:pserver:} were not present in
cvs.texi(,2680) the repository specification, @sc{cvs} would assume it
cvs.texi(,2681) should use @code{rsh} to connect with the server
cvs.texi(,2682) instead (@pxref{Connecting via rsh}).
cvs.texi(,2683) 
cvs.texi(,2684) Of course, once you have a working copy checked out and
cvs.texi(,2685) are running @sc{cvs} commands from within it, there is
cvs.texi(,2686) no longer any need to specify the repository
cvs.texi(,2687) explicitly, because @sc{cvs} can deduce the repository
cvs.texi(,2688) from the working copy's @file{CVS} subdirectory.
cvs.texi(,2689) 
cvs.texi(,2690) @c FIXME: seems to me this needs somewhat more
cvs.texi(,2691) @c explanation.
cvs.texi(,2692) @cindex Logout (subcommand)
cvs.texi(,2693) The password for a given remote repository can be
cvs.texi(,2694) removed from the @code{CVS_PASSFILE} by using the
cvs.texi(,2695) @code{cvs logout} command.
cvs.texi(,2696) 
cvs.texi(,2697) @node Password authentication security
cvs.texi(,2698) @subsubsection Security considerations with password authentication
cvs.texi(,2699) 
cvs.texi(,2700) @cindex Security, of pserver
cvs.texi(,2701) The passwords are stored on the client side in a
cvs.texi(,2702) trivial encoding of the cleartext, and transmitted in
cvs.texi(,2703) the same encoding.  The encoding is done only to
cvs.texi(,2704) prevent inadvertent password compromises (i.e., a
cvs.texi(,2705) system administrator accidentally looking at the file),
cvs.texi(,2706) and will not prevent even a naive attacker from gaining
cvs.texi(,2707) the password.
cvs.texi(,2708) 
cvs.texi(,2709) @c FIXME: The bit about "access to the repository
cvs.texi(,2710) @c implies general access to the system is *not* specific
cvs.texi(,2711) @c to pserver; it applies to kerberos and SSH and
cvs.texi(,2712) @c everything else too.  Should reorganize the
cvs.texi(,2713) @c documentation to make this clear.
cvs.texi(,2714) The separate @sc{cvs} password file (@pxref{Password
cvs.texi(,2715) authentication server}) allows people
cvs.texi(,2716) to use a different password for repository access than
cvs.texi(,2717) for login access.  On the other hand, once a user has
cvs.texi(,2718) non-read-only
cvs.texi(,2719) access to the repository, she can execute programs on
cvs.texi(,2720) the server system through a variety of means.  Thus, repository
cvs.texi(,2721) access implies fairly broad system access as well.  It
cvs.texi(,2722) might be possible to modify @sc{cvs} to prevent that,
cvs.texi(,2723) but no one has done so as of this writing.
cvs.texi(,2724) @c OpenBSD uses chroot() and copies the repository to
cvs.texi(,2725) @c provide anonymous read-only access (for details see
cvs.texi(,2726) @c http://www.openbsd.org/anoncvs.shar).  While this
cvs.texi(,2727) @c closes the most obvious holes, I'm not sure it
cvs.texi(,2728) @c closes enough holes to recommend it (plus it is
cvs.texi(,2729) @c *very* easy to accidentally screw up a setup of this
cvs.texi(,2730) @c type).
cvs.texi(,2731) 
cvs.texi(,2732) Note that because the @file{$CVSROOT/CVSROOT} directory
cvs.texi(,2733) contains @file{passwd} and other files which are used
cvs.texi(,2734) to check security, you must control the permissions on
cvs.texi(,2735) this directory as tightly as the permissions on
cvs.texi(,2736) @file{/etc}.  The same applies to the @file{$CVSROOT}
cvs.texi(,2737) directory itself and any directory
cvs.texi(,2738) above it in the tree.  Anyone who has write access to
cvs.texi(,2739) such a directory will have the ability to become any
cvs.texi(,2740) user on the system.  Note that these permissions are
cvs.texi(,2741) typically tighter than you would use if you are not
cvs.texi(,2742) using pserver.
cvs.texi(,2743) @c TODO: Would be really nice to document/implement a
cvs.texi(,2744) @c scheme where the CVS server can run as some non-root
cvs.texi(,2745) @c user, e.g. "cvs".  CVSROOT/passwd would contain a
cvs.texi(,2746) @c bunch of entries of the form foo:xxx:cvs (or the "cvs"
cvs.texi(,2747) @c would be implicit).  This would greatly reduce
cvs.texi(,2748) @c security risks such as those hinted at in the
cvs.texi(,2749) @c previous paragraph.  I think minor changes to CVS
cvs.texi(,2750) @c might be required but mostly this would just need
cvs.texi(,2751) @c someone who wants to play with it, document it, &c.
cvs.texi(,2752) 
cvs.texi(,2753) In summary, anyone who gets the password gets
cvs.texi(,2754) repository access (which may imply some measure of general system
cvs.texi(,2755) access as well).  The password is available to anyone
cvs.texi(,2756) who can sniff network packets or read a protected
cvs.texi(,2757) (i.e., user read-only) file.  If you want real
cvs.texi(,2758) security, get Kerberos.
cvs.texi(,2759) 
cvs.texi(,2760) @node GSSAPI authenticated
cvs.texi(,2761) @subsection Direct connection with GSSAPI
cvs.texi(,2762) 
cvs.texi(,2763) @cindex GSSAPI
cvs.texi(,2764) @cindex Security, GSSAPI
cvs.texi(,2765) @cindex :gserver:, setting up
cvs.texi(,2766) @cindex Kerberos, using :gserver:
cvs.texi(,2767) GSSAPI is a generic interface to network security
cvs.texi(,2768) systems such as Kerberos 5.
cvs.texi(,2769) If you have a working GSSAPI library, you can have
cvs.texi(,2770) @sc{cvs} connect via a direct @sc{tcp} connection,
cvs.texi(,2771) authenticating with GSSAPI.
cvs.texi(,2772) 
cvs.texi(,2773) To do this, @sc{cvs} needs to be compiled with GSSAPI
cvs.texi(,2774) support; when configuring @sc{cvs} it tries to detect
cvs.texi(,2775) whether GSSAPI libraries using kerberos version 5 are
cvs.texi(,2776) present.  You can also use the @file{--with-gssapi}
cvs.texi(,2777) flag to configure.
cvs.texi(,2778) 
cvs.texi(,2779) The connection is authenticated using GSSAPI, but the
cvs.texi(,2780) message stream is @emph{not} authenticated by default.
cvs.texi(,2781) You must use the @code{-a} global option to request
cvs.texi(,2782) stream authentication.
cvs.texi(,2783) 
cvs.texi(,2784) The data transmitted is @emph{not} encrypted by
cvs.texi(,2785) default.  Encryption support must be compiled into both
cvs.texi(,2786) the client and the server; use the
cvs.texi(,2787) @file{--enable-encrypt} configure option to turn it on.
cvs.texi(,2788) You must then use the @code{-x} global option to
cvs.texi(,2789) request encryption.
cvs.texi(,2790) 
cvs.texi(,2791) GSSAPI connections are handled on the server side by
cvs.texi(,2792) the same server which handles the password
cvs.texi(,2793) authentication server; see @ref{Password authentication
cvs.texi(,2794) server}.  If you are using a GSSAPI mechanism such as
cvs.texi(,2795) Kerberos which provides for strong authentication, you
cvs.texi(,2796) will probably want to disable the ability to
cvs.texi(,2797) authenticate via cleartext passwords.  To do so, create
cvs.texi(,2798) an empty @file{CVSROOT/passwd} password file, and set
cvs.texi(,2799) @code{SystemAuth=no} in the config file
cvs.texi(,2800) (@pxref{config}).
cvs.texi(,2801) 
cvs.texi(,2802) The GSSAPI server uses a principal name of
cvs.texi(,2803) cvs/@var{hostname}, where @var{hostname} is the
cvs.texi(,2804) canonical name of the server host.  You will have to
cvs.texi(,2805) set this up as required by your GSSAPI mechanism.
cvs.texi(,2806) 
cvs.texi(,2807) To connect using GSSAPI, use @samp{:gserver:}.  For
cvs.texi(,2808) example,
cvs.texi(,2809) 
cvs.texi(,2810) @example
cvs.texi(,2811) cvs -d :gserver:faun.example.org:/usr/local/cvsroot checkout foo
cvs.texi(,2812) @end example
cvs.texi(,2813) 
cvs.texi(,2814) @node Kerberos authenticated
cvs.texi(,2815) @subsection Direct connection with kerberos
cvs.texi(,2816) 
cvs.texi(,2817) @cindex Kerberos, using :kserver:
cvs.texi(,2818) @cindex Security, kerberos
cvs.texi(,2819) @cindex :kserver:, setting up
cvs.texi(,2820) The easiest way to use kerberos is to use the kerberos
cvs.texi(,2821) @code{rsh}, as described in @ref{Connecting via rsh}.
cvs.texi(,2822) The main disadvantage of using rsh is that all the data
cvs.texi(,2823) needs to pass through additional programs, so it may be
cvs.texi(,2824) slower.  So if you have kerberos installed you can
cvs.texi(,2825) connect via a direct @sc{tcp} connection,
cvs.texi(,2826) authenticating with kerberos.
cvs.texi(,2827) 
cvs.texi(,2828) This section concerns the kerberos network security
cvs.texi(,2829) system, version 4.  Kerberos version 5 is supported via
cvs.texi(,2830) the GSSAPI generic network security interface, as
cvs.texi(,2831) described in the previous section.
cvs.texi(,2832) 
cvs.texi(,2833) To do this, @sc{cvs} needs to be compiled with kerberos
cvs.texi(,2834) support; when configuring @sc{cvs} it tries to detect
cvs.texi(,2835) whether kerberos is present or you can use the
cvs.texi(,2836) @file{--with-krb4} flag to configure.
cvs.texi(,2837) 
cvs.texi(,2838) The data transmitted is @emph{not} encrypted by
cvs.texi(,2839) default.  Encryption support must be compiled into both
cvs.texi(,2840) the client and server; use the
cvs.texi(,2841) @file{--enable-encryption} configure option to turn it
cvs.texi(,2842) on.  You must then use the @code{-x} global option to
cvs.texi(,2843) request encryption.
cvs.texi(,2844) 
cvs.texi(,2845) @cindex CVS_CLIENT_PORT
cvs.texi(,2846) You need to edit @file{inetd.conf} on the server
cvs.texi(,2847) machine to run @code{cvs kserver}.  The client uses
cvs.texi(,2848) port 1999 by default; if you want to use another port
cvs.texi(,2849) specify it in the @code{CVSROOT} (@pxref{Remote repositories})
cvs.texi(,2850) or the @code{CVS_CLIENT_PORT} environment variable
cvs.texi(,2851) (@pxref{Environment variables}) on the client.
cvs.texi(,2852) 
cvs.texi(,2853) @cindex kinit
cvs.texi(,2854) When you want to use @sc{cvs}, get a ticket in the
cvs.texi(,2855) usual way (generally @code{kinit}); it must be a ticket
cvs.texi(,2856) which allows you to log into the server machine.  Then
cvs.texi(,2857) you are ready to go:
cvs.texi(,2858) 
cvs.texi(,2859) @example
cvs.texi(,2860) cvs -d :kserver:faun.example.org:/usr/local/cvsroot checkout foo
cvs.texi(,2861) @end example
cvs.texi(,2862) 
cvs.texi(,2863) Previous versions of @sc{cvs} would fall back to a
cvs.texi(,2864) connection via rsh; this version will not do so.
cvs.texi(,2865) 
cvs.texi(,2866) @node Connecting via fork
cvs.texi(,2867) @subsection Connecting with fork
cvs.texi(,2868) 
cvs.texi(,2869) @cindex fork, access method
cvs.texi(,2870) @cindex :fork:, setting up
cvs.texi(,2871) This access method allows you to connect to a
cvs.texi(,2872) repository on your local disk via the remote protocol.
cvs.texi(,2873) In other words it does pretty much the same thing as
cvs.texi(,2874) @code{:local:}, but various quirks, bugs and the like are
cvs.texi(,2875) those of the remote @sc{cvs} rather than the local
cvs.texi(,2876) @sc{cvs}.
cvs.texi(,2877) 
cvs.texi(,2878) For day-to-day operations you might prefer either
cvs.texi(,2879) @code{:local:} or @code{:fork:}, depending on your
cvs.texi(,2880) preferences.  Of course @code{:fork:} comes in
cvs.texi(,2881) particularly handy in testing or
cvs.texi(,2882) debugging @code{cvs} and the remote protocol.
cvs.texi(,2883) Specifically, we avoid all of the network-related
cvs.texi(,2884) setup/configuration, timeouts, and authentication
cvs.texi(,2885) inherent in the other remote access methods but still
cvs.texi(,2886) create a connection which uses the remote protocol.
cvs.texi(,2887) 
cvs.texi(,2888) To connect using the @code{fork} method, use
cvs.texi(,2889) @samp{:fork:} and the pathname to your local
cvs.texi(,2890) repository.  For example:
cvs.texi(,2891) 
cvs.texi(,2892) @example
cvs.texi(,2893) cvs -d :fork:/usr/local/cvsroot checkout foo
cvs.texi(,2894) @end example
cvs.texi(,2895) 
cvs.texi(,2896) @cindex CVS_SERVER, and :fork:
cvs.texi(,2897) As with @code{:ext:}, the server is called @samp{cvs}
cvs.texi(,2898) by default, or the value of the @code{CVS_SERVER}
cvs.texi(,2899) environment variable.
cvs.texi(,2900) 
cvs.texi(,2901) @c ---------------------------------------------------------------------
cvs.texi(,2902) @node Read-only access
cvs.texi(,2903) @section Read-only repository access
cvs.texi(,2904) @cindex Read-only repository access
cvs.texi(,2905) @cindex readers (admin file)
cvs.texi(,2906) @cindex writers (admin file)
cvs.texi(,2907) 
cvs.texi(,2908)         It is possible to grant read-only repository
cvs.texi(,2909) access to people using the password-authenticated
cvs.texi(,2910) server (@pxref{Password authenticated}).  (The
cvs.texi(,2911) other access methods do not have explicit support for
cvs.texi(,2912) read-only users because those methods all assume login
cvs.texi(,2913) access to the repository machine anyway, and therefore
cvs.texi(,2914) the user can do whatever local file permissions allow
cvs.texi(,2915) her to do.)
cvs.texi(,2916) 
cvs.texi(,2917)         A user who has read-only access can do only
cvs.texi(,2918) those @sc{cvs} operations which do not modify the
cvs.texi(,2919) repository, except for certain ``administrative'' files
cvs.texi(,2920) (such as lock files and the history file).  It may be
cvs.texi(,2921) desirable to use this feature in conjunction with
cvs.texi(,2922) user-aliasing (@pxref{Password authentication server}).
cvs.texi(,2923) 
cvs.texi(,2924) Unlike with previous versions of @sc{cvs}, read-only
cvs.texi(,2925) users should be able merely to read the repository, and
cvs.texi(,2926) not to execute programs on the server or otherwise gain
cvs.texi(,2927) unexpected levels of access.  Or to be more accurate,
cvs.texi(,2928) the @emph{known} holes have been plugged.  Because this
cvs.texi(,2929) feature is new and has not received a comprehensive
cvs.texi(,2930) security audit, you should use whatever level of
cvs.texi(,2931) caution seems warranted given your attitude concerning
cvs.texi(,2932) security.
cvs.texi(,2933) 
cvs.texi(,2934)         There are two ways to specify read-only access
cvs.texi(,2935) for a user: by inclusion, and by exclusion.
cvs.texi(,2936) 
cvs.texi(,2937)         "Inclusion" means listing that user
cvs.texi(,2938) specifically in the @file{$CVSROOT/CVSROOT/readers}
cvs.texi(,2939) file, which is simply a newline-separated list of
cvs.texi(,2940) users.  Here is a sample @file{readers} file:
cvs.texi(,2941) 
cvs.texi(,2942) @example
cvs.texi(,2943) melissa
cvs.texi(,2944) splotnik
cvs.texi(,2945) jrandom
cvs.texi(,2946) @end example
cvs.texi(,2947) 
cvs.texi(,2948) @noindent
cvs.texi(,2949)         (Don't forget the newline after the last user.)
cvs.texi(,2950) 
cvs.texi(,2951)         "Exclusion" means explicitly listing everyone
cvs.texi(,2952) who has @emph{write} access---if the file
cvs.texi(,2953) 
cvs.texi(,2954) @example
cvs.texi(,2955) $CVSROOT/CVSROOT/writers
cvs.texi(,2956) @end example
cvs.texi(,2957) 
cvs.texi(,2958) @noindent
cvs.texi(,2959) exists, then only
cvs.texi(,2960) those users listed in it have write access, and
cvs.texi(,2961) everyone else has read-only access (of course, even the
cvs.texi(,2962) read-only users still need to be listed in the
cvs.texi(,2963) @sc{cvs} @file{passwd} file).  The
cvs.texi(,2964) @file{writers} file has the same format as the
cvs.texi(,2965) @file{readers} file.
cvs.texi(,2966) 
cvs.texi(,2967)         Note: if your @sc{cvs} @file{passwd}
cvs.texi(,2968) file maps cvs users onto system users (@pxref{Password
cvs.texi(,2969) authentication server}), make sure you deny or grant
cvs.texi(,2970) read-only access using the @emph{cvs} usernames, not
cvs.texi(,2971) the system usernames.  That is, the @file{readers} and
cvs.texi(,2972) @file{writers} files contain cvs usernames, which may
cvs.texi(,2973) or may not be the same as system usernames.
cvs.texi(,2974) 
cvs.texi(,2975)         Here is a complete description of the server's
cvs.texi(,2976) behavior in deciding whether to grant read-only or
cvs.texi(,2977) read-write access:
cvs.texi(,2978) 
cvs.texi(,2979)         If @file{readers} exists, and this user is
cvs.texi(,2980) listed in it, then she gets read-only access.  Or if
cvs.texi(,2981) @file{writers} exists, and this user is NOT listed in
cvs.texi(,2982) it, then she also gets read-only access (this is true
cvs.texi(,2983) even if @file{readers} exists but she is not listed
cvs.texi(,2984) there).  Otherwise, she gets full read-write access.
cvs.texi(,2985) 
cvs.texi(,2986)         Of course there is a conflict if the user is
cvs.texi(,2987) listed in both files.  This is resolved in the more
cvs.texi(,2988) conservative way, it being better to protect the
cvs.texi(,2989) repository too much than too little: such a user gets
cvs.texi(,2990) read-only access.
cvs.texi(,2991) 
cvs.texi(,2992) @node Server temporary directory
cvs.texi(,2993) @section Temporary directories for the server
cvs.texi(,2994) @cindex Temporary directories, and server
cvs.texi(,2995) @cindex Server, temporary directories
cvs.texi(,2996) 
cvs.texi(,2997) While running, the @sc{cvs} server creates temporary
cvs.texi(,2998) directories.  They are named
cvs.texi(,2999) 
cvs.texi(,3000) @example
cvs.texi(,3001) cvs-serv@var{pid}
cvs.texi(,3002) @end example
cvs.texi(,3003) 
cvs.texi(,3004) @noindent
cvs.texi(,3005) where @var{pid} is the process identification number of
cvs.texi(,3006) the server.
cvs.texi(,3007) They are located in the directory specified by 
cvs.texi(,3008) the @samp{-T} global option (@pxref{Global options}), 
cvs.texi(,3009) the @code{TMPDIR} environment variable (@pxref{Environment variables}), 
cvs.texi(,3010) or, failing that, @file{/tmp}.
cvs.texi(,3011) 
cvs.texi(,3012) In most cases the server will remove the temporary
cvs.texi(,3013) directory when it is done, whether it finishes normally
cvs.texi(,3014) or abnormally.  However, there are a few cases in which
cvs.texi(,3015) the server does not or cannot remove the temporary
cvs.texi(,3016) directory, for example:
cvs.texi(,3017) 
cvs.texi(,3018) @itemize @bullet
cvs.texi(,3019) @item
cvs.texi(,3020) If the server aborts due to an internal server error,
cvs.texi(,3021) it may preserve the directory to aid in debugging
cvs.texi(,3022) 
cvs.texi(,3023) @item
cvs.texi(,3024) If the server is killed in a way that it has no way of
cvs.texi(,3025) cleaning up (most notably, @samp{kill -KILL} on unix).
cvs.texi(,3026) 
cvs.texi(,3027) @item
cvs.texi(,3028) If the system shuts down without an orderly shutdown,
cvs.texi(,3029) which tells the server to clean up.
cvs.texi(,3030) @end itemize
cvs.texi(,3031) 
cvs.texi(,3032) In cases such as this, you will need to manually remove
cvs.texi(,3033) the @file{cvs-serv@var{pid}} directories.  As long as
cvs.texi(,3034) there is no server running with process identification
cvs.texi(,3035) number @var{pid}, it is safe to do so.
cvs.texi(,3036) 
cvs.texi(,3037) @c ---------------------------------------------------------------------
cvs.texi(,3038) @node Starting a new project
cvs.texi(,3039) @chapter Starting a project with CVS
cvs.texi(,3040) @cindex Starting a project with CVS
cvs.texi(,3041) @cindex Creating a project
cvs.texi(,3042) 
cvs.texi(,3043) @comment --moduledb--
cvs.texi(,3044) Because renaming files and moving them between
cvs.texi(,3045) directories is somewhat inconvenient, the first thing
cvs.texi(,3046) you do when you start a new project should be to think
cvs.texi(,3047) through your file organization.  It is not impossible
cvs.texi(,3048) to rename or move files, but it does increase the
cvs.texi(,3049) potential for confusion and @sc{cvs} does have some
cvs.texi(,3050) quirks particularly in the area of renaming
cvs.texi(,3051) directories.  @xref{Moving files}.
cvs.texi(,3052) 
cvs.texi(,3053) What to do next depends on the situation at hand.
cvs.texi(,3054) 
cvs.texi(,3055) @menu
cvs.texi(,3056) * Setting up the files::        Getting the files into the repository
cvs.texi(,3057) * Defining the module::         How to make a module of the files
cvs.texi(,3058) @end menu
cvs.texi(,3059) @c -- File permissions!
cvs.texi(,3060) 
cvs.texi(,3061) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,3062) @node Setting up the files
cvs.texi(,3063) @section Setting up the files
cvs.texi(,3064) 
cvs.texi(,3065) The first step is to create the files inside the repository.  This can
cvs.texi(,3066) be done in a couple of different ways.
cvs.texi(,3067) 
cvs.texi(,3068) @c -- The contributed scripts
cvs.texi(,3069) @menu
cvs.texi(,3070) * From files::                  This method is useful with old projects
cvs.texi(,3071)                                 where files already exists.
cvs.texi(,3072) * From other version control systems::  Old projects where you want to
cvs.texi(,3073)                                         preserve history from another system.
cvs.texi(,3074) * From scratch::                Creating a directory tree from scratch.
cvs.texi(,3075) @end menu
cvs.texi(,3076) 
cvs.texi(,3077) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,3078) @node From files
cvs.texi(,3079) @subsection Creating a directory tree from a number of files
cvs.texi(,3080) @cindex Importing files
cvs.texi(,3081) 
cvs.texi(,3082) When you begin using @sc{cvs}, you will probably already have several
cvs.texi(,3083) projects that can be
cvs.texi(,3084) put under @sc{cvs} control.  In these cases the easiest way is to use the
cvs.texi(,3085) @code{import} command.  An example is probably the easiest way to
cvs.texi(,3086) explain how to use it.  If the files you want to install in
cvs.texi(,3087) @sc{cvs} reside in @file{@var{wdir}}, and you want them to appear in the
cvs.texi(,3088) repository as @file{$CVSROOT/yoyodyne/@var{rdir}}, you can do this:
cvs.texi(,3089) 
cvs.texi(,3090) @example
cvs.texi(,3091) $ cd @var{wdir}
cvs.texi(,3092) $ cvs import -m "Imported sources" yoyodyne/@var{rdir} yoyo start
cvs.texi(,3093) @end example
cvs.texi(,3094) 
cvs.texi(,3095) Unless you supply a log message with the @samp{-m}
cvs.texi(,3096) flag, @sc{cvs} starts an editor and prompts for a
cvs.texi(,3097) message.  The string @samp{yoyo} is a @dfn{vendor tag},
cvs.texi(,3098) and @samp{start} is a @dfn{release tag}.  They may fill
cvs.texi(,3099) no purpose in this context, but since @sc{cvs} requires
cvs.texi(,3100) them they must be present.  @xref{Tracking sources}, for
cvs.texi(,3101) more information about them.
cvs.texi(,3102) 
cvs.texi(,3103) You can now verify that it worked, and remove your
cvs.texi(,3104) original source directory.
cvs.texi(,3105) @c FIXME: Need to say more about "verify that it
cvs.texi(,3106) @c worked".  What should the user look for in the output
cvs.texi(,3107) @c from "diff -r"?
cvs.texi(,3108) 
cvs.texi(,3109) @example
cvs.texi(,3110) $ cd ..
cvs.texi(,3111) $ cvs checkout yoyodyne/@var{rdir}       # @r{Explanation below}
cvs.texi(,3112) $ diff -r @var{wdir} yoyodyne/@var{rdir}
cvs.texi(,3113) $ rm -r @var{wdir}
cvs.texi(,3114) @end example
cvs.texi(,3115) 
cvs.texi(,3116) @noindent
cvs.texi(,3117) Erasing the original sources is a good idea, to make sure that you do
cvs.texi(,3118) not accidentally edit them in @var{wdir}, bypassing @sc{cvs}.
cvs.texi(,3119) Of course, it would be wise to make sure that you have
cvs.texi(,3120) a backup of the sources before you remove them.
cvs.texi(,3121) 
cvs.texi(,3122) The @code{checkout} command can either take a module
cvs.texi(,3123) name as argument (as it has done in all previous
cvs.texi(,3124) examples) or a path name relative to @code{$CVSROOT},
cvs.texi(,3125) as it did in the example above.
cvs.texi(,3126) 
cvs.texi(,3127) It is a good idea to check that the permissions
cvs.texi(,3128) @sc{cvs} sets on the directories inside @code{$CVSROOT}
cvs.texi(,3129) are reasonable, and that they belong to the proper
cvs.texi(,3130) groups.  @xref{File permissions}.
cvs.texi(,3131) 
cvs.texi(,3132) If some of the files you want to import are binary, you
cvs.texi(,3133) may want to use the wrappers features to specify which
cvs.texi(,3134) files are binary and which are not.  @xref{Wrappers}.
cvs.texi(,3135) 
cvs.texi(,3136) @c The node name is too long, but I am having trouble
cvs.texi(,3137) @c thinking of something more concise.
cvs.texi(,3138) @node From other version control systems
cvs.texi(,3139) @subsection Creating Files From Other Version Control Systems
cvs.texi(,3140) @cindex Importing files, from other version control systems
cvs.texi(,3141) 
cvs.texi(,3142) If you have a project which you are maintaining with
cvs.texi(,3143) another version control system, such as @sc{rcs}, you
cvs.texi(,3144) may wish to put the files from that project into
cvs.texi(,3145) @sc{cvs}, and preserve the revision history of the
cvs.texi(,3146) files.
cvs.texi(,3147) 
cvs.texi(,3148) @table @asis
cvs.texi(,3149) @cindex RCS, importing files from
cvs.texi(,3150) @item From RCS
cvs.texi(,3151) If you have been using @sc{rcs}, find the @sc{rcs}
cvs.texi(,3152) files---usually a file named @file{foo.c} will have its
cvs.texi(,3153) @sc{rcs} file in @file{RCS/foo.c,v} (but it could be
cvs.texi(,3154) other places; consult the @sc{rcs} documentation for
cvs.texi(,3155) details).  Then create the appropriate directories in
cvs.texi(,3156) @sc{cvs} if they do not already exist.  Then copy the
cvs.texi(,3157) files into the appropriate directories in the @sc{cvs}
cvs.texi(,3158) repository (the name in the repository must be the name
cvs.texi(,3159) of the source file with @samp{,v} added; the files go
cvs.texi(,3160) directly in the appropriate directory of the repository,
cvs.texi(,3161) not in an @file{RCS} subdirectory).  This is one of the
cvs.texi(,3162) few times when it is a good idea to access the @sc{cvs}
cvs.texi(,3163) repository directly, rather than using @sc{cvs}
cvs.texi(,3164) commands.  Then you are ready to check out a new
cvs.texi(,3165) working directory.
cvs.texi(,3166) @c Someday there probably should be a "cvs import -t
cvs.texi(,3167) @c rcs" or some such.  It could even create magic
cvs.texi(,3168) @c branches.  It could also do something about the case
cvs.texi(,3169) @c where the RCS file had a (non-magic) "0" branch.
cvs.texi(,3170) 
cvs.texi(,3171) The @sc{rcs} file should not be locked when you move it
cvs.texi(,3172) into @sc{cvs}; if it is, @sc{cvs} will have trouble
cvs.texi(,3173) letting you operate on it.
cvs.texi(,3174) @c What is the easiest way to unlock your files if you
cvs.texi(,3175) @c have them locked?  Especially if you have a lot of them?
cvs.texi(,3176) @c This is a CVS bug/misfeature; importing RCS files
cvs.texi(,3177) @c should ignore whether they are locked and leave them in
cvs.texi(,3178) @c an unlocked state.  Yet another reason for a separate
cvs.texi(,3179) @c "import RCS file" command.
cvs.texi(,3180) 
cvs.texi(,3181) @c How many is "many"? Or do they just import RCS files?
cvs.texi(,3182) @item From another version control system
cvs.texi(,3183) Many version control systems have the ability to export
cvs.texi(,3184) @sc{rcs} files in the standard format.  If yours does,
cvs.texi(,3185) export the @sc{rcs} files and then follow the above
cvs.texi(,3186) instructions.
cvs.texi(,3187) 
cvs.texi(,3188) Failing that, probably your best bet is to write a
cvs.texi(,3189) script that will check out the files one revision at a
cvs.texi(,3190) time using the command line interface to the other
cvs.texi(,3191) system, and then check the revisions into @sc{cvs}.
cvs.texi(,3192) The @file{sccs2rcs} script mentioned below may be a
cvs.texi(,3193) useful example to follow.
cvs.texi(,3194) 
cvs.texi(,3195) @cindex SCCS, importing files from
cvs.texi(,3196) @item From SCCS
cvs.texi(,3197) There is a script in the @file{contrib} directory of
cvs.texi(,3198) the @sc{cvs} source distribution called @file{sccs2rcs}
cvs.texi(,3199) which converts @sc{sccs} files to @sc{rcs} files.
cvs.texi(,3200) Note: you must run it on a machine which has both
cvs.texi(,3201) @sc{sccs} and @sc{rcs} installed, and like everything
cvs.texi(,3202) else in contrib it is unsupported (your mileage may
cvs.texi(,3203) vary).
cvs.texi(,3204) 
cvs.texi(,3205) @cindex PVCS, importing files from
cvs.texi(,3206) @item From PVCS
cvs.texi(,3207) There is a script in the @file{contrib} directory of
cvs.texi(,3208) the @sc{cvs} source distribution called @file{pvcs_to_rcs}
cvs.texi(,3209) which converts @sc{pvcs} archives to @sc{rcs} files.
cvs.texi(,3210) You must run it on a machine which has both
cvs.texi(,3211) @sc{pvcs} and @sc{rcs} installed, and like everything
cvs.texi(,3212) else in contrib it is unsupported (your mileage may
cvs.texi(,3213) vary).  See the comments in the script for details.
cvs.texi(,3214) @end table
cvs.texi(,3215) @c CMZ and/or PATCHY were systems that were used in the
cvs.texi(,3216) @c high energy physics community (especially for
cvs.texi(,3217) @c CERNLIB).  CERN has replaced them with CVS, but the
cvs.texi(,3218) @c CAR format seems to live on as a way to submit
cvs.texi(,3219) @c changes.  There is a program car2cvs which converts
cvs.texi(,3220) @c but I'm not sure where one gets a copy.
cvs.texi(,3221) @c Not sure it is worth mentioning here, since it would
cvs.texi(,3222) @c appear to affect only one particular community.
cvs.texi(,3223) @c Best page for more information is:
cvs.texi(,3224) @c http://wwwcn1.cern.ch/asd/cvs/index.html
cvs.texi(,3225) @c See also:
cvs.texi(,3226) @c http://ecponion.cern.ch/ecpsa/cernlib.html
cvs.texi(,3227) 
cvs.texi(,3228) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,3229) @node From scratch
cvs.texi(,3230) @subsection Creating a directory tree from scratch
cvs.texi(,3231) 
cvs.texi(,3232) @c Also/instead should be documenting
cvs.texi(,3233) @c $ cvs co -l .
cvs.texi(,3234) @c $ mkdir tc
cvs.texi(,3235) @c $ cvs add tc
cvs.texi(,3236) @c $ cd tc
cvs.texi(,3237) @c $ mkdir man
cvs.texi(,3238) @c $ cvs add man
cvs.texi(,3239) @c etc.
cvs.texi(,3240) @c Using import to create the directories only is
cvs.texi(,3241) @c probably a somewhat confusing concept.
cvs.texi(,3242) For a new project, the easiest thing to do is probably
cvs.texi(,3243) to create an empty directory structure, like this:
cvs.texi(,3244) 
cvs.texi(,3245) @example
cvs.texi(,3246) $ mkdir tc
cvs.texi(,3247) $ mkdir tc/man
cvs.texi(,3248) $ mkdir tc/testing
cvs.texi(,3249) @end example
cvs.texi(,3250) 
cvs.texi(,3251) After that, you use the @code{import} command to create
cvs.texi(,3252) the corresponding (empty) directory structure inside
cvs.texi(,3253) the repository:
cvs.texi(,3254) 
cvs.texi(,3255) @example
cvs.texi(,3256) $ cd tc
cvs.texi(,3257) $ cvs import -m "Created directory structure" yoyodyne/@var{dir} yoyo start
cvs.texi(,3258) @end example
cvs.texi(,3259) 
cvs.texi(,3260) Then, use @code{add} to add files (and new directories)
cvs.texi(,3261) as they appear.
cvs.texi(,3262) 
cvs.texi(,3263) Check that the permissions @sc{cvs} sets on the
cvs.texi(,3264) directories inside @code{$CVSROOT} are reasonable.
cvs.texi(,3265) 
cvs.texi(,3266) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,3267) @node Defining the module
cvs.texi(,3268) @section Defining the module
cvs.texi(,3269) @cindex Defining a module
cvs.texi(,3270) @cindex Editing the modules file
cvs.texi(,3271) @cindex Module, defining
cvs.texi(,3272) @cindex Modules file, changing
cvs.texi(,3273) 
cvs.texi(,3274) The next step is to define the module in the
cvs.texi(,3275) @file{modules} file.  This is not strictly necessary,
cvs.texi(,3276) but modules can be convenient in grouping together
cvs.texi(,3277) related files and directories.
cvs.texi(,3278) 
cvs.texi(,3279) In simple cases these steps are sufficient to define a module.
cvs.texi(,3280) 
cvs.texi(,3281) @enumerate
cvs.texi(,3282) @item
cvs.texi(,3283) Get a working copy of the modules file.
cvs.texi(,3284) 
cvs.texi(,3285) @example
cvs.texi(,3286) $ cvs checkout CVSROOT/modules
cvs.texi(,3287) $ cd CVSROOT
cvs.texi(,3288) @end example
cvs.texi(,3289) 
cvs.texi(,3290) @item
cvs.texi(,3291) Edit the file and insert a line that defines the module.  @xref{Intro
cvs.texi(,3292) administrative files}, for an introduction.  @xref{modules}, for a full
cvs.texi(,3293) description of the modules file.  You can use the
cvs.texi(,3294) following line to define the module @samp{tc}:
cvs.texi(,3295) 
cvs.texi(,3296) @example
cvs.texi(,3297) tc   yoyodyne/tc
cvs.texi(,3298) @end example
cvs.texi(,3299) 
cvs.texi(,3300) @item
cvs.texi(,3301) Commit your changes to the modules file.
cvs.texi(,3302) 
cvs.texi(,3303) @example
cvs.texi(,3304) $ cvs commit -m "Added the tc module." modules
cvs.texi(,3305) @end example
cvs.texi(,3306) 
cvs.texi(,3307) @item
cvs.texi(,3308) Release the modules module.
cvs.texi(,3309) 
cvs.texi(,3310) @example
cvs.texi(,3311) $ cd ..
cvs.texi(,3312) $ cvs release -d CVSROOT
cvs.texi(,3313) @end example
cvs.texi(,3314) @end enumerate
cvs.texi(,3315) 
cvs.texi(,3316) @c ---------------------------------------------------------------------
cvs.texi(,3317) @node Revisions
cvs.texi(,3318) @chapter Revisions
cvs.texi(,3319) 
cvs.texi(,3320) For many uses of @sc{cvs}, one doesn't need to worry
cvs.texi(,3321) too much about revision numbers; @sc{cvs} assigns
cvs.texi(,3322) numbers such as @code{1.1}, @code{1.2}, and so on, and
cvs.texi(,3323) that is all one needs to know.  However, some people
cvs.texi(,3324) prefer to have more knowledge and control concerning
cvs.texi(,3325) how @sc{cvs} assigns revision numbers.
cvs.texi(,3326) 
cvs.texi(,3327) If one wants to keep track of a set of revisions
cvs.texi(,3328) involving more than one file, such as which revisions
cvs.texi(,3329) went into a particular release, one uses a @dfn{tag},
cvs.texi(,3330) which is a symbolic revision which can be assigned to a
cvs.texi(,3331) numeric revision in each file.
cvs.texi(,3332) 
cvs.texi(,3333) @menu
cvs.texi(,3334) * Revision numbers::            The meaning of a revision number
cvs.texi(,3335) * Versions revisions releases::  Terminology used in this manual
cvs.texi(,3336) * Assigning revisions::         Assigning revisions
cvs.texi(,3337) * Tags::                        Tags--Symbolic revisions
cvs.texi(,3338) * Tagging the working directory::  The cvs tag command
cvs.texi(,3339) * Tagging by date/tag::         The cvs rtag command
cvs.texi(,3340) * Modifying tags::              Adding, renaming, and deleting tags
cvs.texi(,3341) * Tagging add/remove::          Tags with adding and removing files
cvs.texi(,3342) * Sticky tags::                 Certain tags are persistent
cvs.texi(,3343) @end menu
cvs.texi(,3344) 
cvs.texi(,3345) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,3346) @node Revision numbers
cvs.texi(,3347) @section Revision numbers
cvs.texi(,3348) @cindex Revision numbers
cvs.texi(,3349) @cindex Revision tree
cvs.texi(,3350) @cindex Linear development
cvs.texi(,3351) @cindex Number, revision-
cvs.texi(,3352) @cindex Decimal revision number
cvs.texi(,3353) @cindex Branch number
cvs.texi(,3354) @cindex Number, branch
cvs.texi(,3355) 
cvs.texi(,3356) Each version of a file has a unique @dfn{revision
cvs.texi(,3357) number}.  Revision numbers look like @samp{1.1},
cvs.texi(,3358) @samp{1.2}, @samp{1.3.2.2} or even @samp{1.3.2.2.4.5}.
cvs.texi(,3359) A revision number always has an even number of
cvs.texi(,3360) period-separated decimal integers.  By default revision
cvs.texi(,3361) 1.1 is the first revision of a file.  Each successive
cvs.texi(,3362) revision is given a new number by increasing the
cvs.texi(,3363) rightmost number by one.  The following figure displays
cvs.texi(,3364) a few revisions, with newer revisions to the right.
cvs.texi(,3365) 
cvs.texi(,3366) @example
cvs.texi(,3367)        +-----+    +-----+    +-----+    +-----+    +-----+
cvs.texi(,3368)        ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
cvs.texi(,3369)        +-----+    +-----+    +-----+    +-----+    +-----+
cvs.texi(,3370) @end example
cvs.texi(,3371) 
cvs.texi(,3372) It is also possible to end up with numbers containing
cvs.texi(,3373) more than one period, for example @samp{1.3.2.2}.  Such
cvs.texi(,3374) revisions represent revisions on branches
cvs.texi(,3375) (@pxref{Branching and merging}); such revision numbers
cvs.texi(,3376) are explained in detail in @ref{Branches and
cvs.texi(,3377) revisions}.
cvs.texi(,3378) 
cvs.texi(,3379) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,3380) @node Versions revisions releases
cvs.texi(,3381) @section Versions, revisions and releases
cvs.texi(,3382) @cindex Revisions, versions and releases
cvs.texi(,3383) @cindex Versions, revisions and releases
cvs.texi(,3384) @cindex Releases, revisions and versions
cvs.texi(,3385) 
cvs.texi(,3386) A file can have several versions, as described above.
cvs.texi(,3387) Likewise, a software product can have several versions.
cvs.texi(,3388) A software product is often given a version number such
cvs.texi(,3389) as @samp{4.1.1}.
cvs.texi(,3390) 
cvs.texi(,3391) Versions in the first sense are called @dfn{revisions}
cvs.texi(,3392) in this document, and versions in the second sense are
cvs.texi(,3393) called @dfn{releases}.  To avoid confusion, the word
cvs.texi(,3394) @dfn{version} is almost never used in this document.
cvs.texi(,3395) 
cvs.texi(,3396) @node Assigning revisions
cvs.texi(,3397) @section Assigning revisions
cvs.texi(,3398) 
cvs.texi(,3399) @c We avoid the "major revision" terminology.  It seems
cvs.texi(,3400) @c like jargon.  Hopefully "first number" is clear enough.
cvs.texi(,3401) @c
cvs.texi(,3402) @c Well, in the context of software release numbers,
cvs.texi(,3403) @c "major" and "minor" release or version numbers are
cvs.texi(,3404) @c documented in at least the GNU Coding Standards, but I'm
cvs.texi(,3405) @c still not sure I find that a valid reason to apply the
cvs.texi(,3406) @c terminology to RCS revision numbers.  "First", "Second",
cvs.texi(,3407) @c "subsequent", and so on is almost surely clearer,
cvs.texi(,3408) @c especially to a novice reader. -DRP
cvs.texi(,3409) By default, @sc{cvs} will assign numeric revisions by
cvs.texi(,3410) leaving the first number the same and incrementing the
cvs.texi(,3411) second number.  For example, @code{1.1}, @code{1.2},
cvs.texi(,3412) @code{1.3}, etc.
cvs.texi(,3413) 
cvs.texi(,3414) When adding a new file, the second number will always
cvs.texi(,3415) be one and the first number will equal the highest
cvs.texi(,3416) first number of any file in that directory.  For
cvs.texi(,3417) example, the current directory contains files whose
cvs.texi(,3418) highest numbered revisions are @code{1.7}, @code{3.1},
cvs.texi(,3419) and @code{4.12}, then an added file will be given the
cvs.texi(,3420) numeric revision @code{4.1}.
cvs.texi(,3421) 
cvs.texi(,3422) @c This is sort of redundant with something we said a
cvs.texi(,3423) @c while ago.  Somewhere we need a better way of
cvs.texi(,3424) @c introducing how the first number can be anything
cvs.texi(,3425) @c except "1", perhaps.  Also I don't think this
cvs.texi(,3426) @c presentation is clear on why we are discussing releases
cvs.texi(,3427) @c and first numbers of numeric revisions in the same
cvs.texi(,3428) @c breath.
cvs.texi(,3429) Normally there is no reason to care
cvs.texi(,3430) about the revision numbers---it is easier to treat them
cvs.texi(,3431) as internal numbers that @sc{cvs} maintains, and tags
cvs.texi(,3432) provide a better way to distinguish between things like
cvs.texi(,3433) release 1 versus release 2 of your product
cvs.texi(,3434) (@pxref{Tags}).  However, if you want to set the
cvs.texi(,3435) numeric revisions, the @samp{-r} option to @code{cvs
cvs.texi(,3436) commit} can do that.  The @samp{-r} option implies the
cvs.texi(,3437) @samp{-f} option, in the sense that it causes the
cvs.texi(,3438) files to be committed even if they are not modified.
cvs.texi(,3439) 
cvs.texi(,3440) For example, to bring all your files up to
cvs.texi(,3441) revision 3.0 (including those that haven't changed),
cvs.texi(,3442) you might invoke:
cvs.texi(,3443) 
cvs.texi(,3444) @example
cvs.texi(,3445) $ cvs commit -r 3.0
cvs.texi(,3446) @end example
cvs.texi(,3447) 
cvs.texi(,3448) Note that the number you specify with @samp{-r} must be
cvs.texi(,3449) larger than any existing revision number.  That is, if
cvs.texi(,3450) revision 3.0 exists, you cannot @samp{cvs commit
cvs.texi(,3451) -r 1.3}.  If you want to maintain several releases in
cvs.texi(,3452) parallel, you need to use a branch (@pxref{Branching and merging}).
cvs.texi(,3453) 
cvs.texi(,3454) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,3455) @node Tags
cvs.texi(,3456) @section Tags--Symbolic revisions
cvs.texi(,3457) @cindex Tags
cvs.texi(,3458) 
cvs.texi(,3459) The revision numbers live a life of their own.  They
cvs.texi(,3460) need not have anything at all to do with the release
cvs.texi(,3461) numbers of your software product.  Depending
cvs.texi(,3462) on how you use @sc{cvs} the revision numbers might change several times
cvs.texi(,3463) between two releases.  As an example, some of the
cvs.texi(,3464) source files that make up @sc{rcs} 5.6 have the following
cvs.texi(,3465) revision numbers:
cvs.texi(,3466) @cindex RCS revision numbers
cvs.texi(,3467) 
cvs.texi(,3468) @example
cvs.texi(,3469) ci.c            5.21
cvs.texi(,3470) co.c            5.9
cvs.texi(,3471) ident.c         5.3
cvs.texi(,3472) rcs.c           5.12
cvs.texi(,3473) rcsbase.h       5.11
cvs.texi(,3474) rcsdiff.c       5.10
cvs.texi(,3475) rcsedit.c       5.11
cvs.texi(,3476) rcsfcmp.c       5.9
cvs.texi(,3477) rcsgen.c        5.10
cvs.texi(,3478) rcslex.c        5.11
cvs.texi(,3479) rcsmap.c        5.2
cvs.texi(,3480) rcsutil.c       5.10
cvs.texi(,3481) @end example
cvs.texi(,3482) 
cvs.texi(,3483) @cindex tag (subcommand), introduction
cvs.texi(,3484) @cindex Tags, symbolic name
cvs.texi(,3485) @cindex Symbolic name (tag)
cvs.texi(,3486) @cindex Name, symbolic (tag)
cvs.texi(,3487) @cindex HEAD, as reserved tag name
cvs.texi(,3488) @cindex BASE, as reserved tag name
cvs.texi(,3489) You can use the @code{tag} command to give a symbolic name to a
cvs.texi(,3490) certain revision of a file.  You can use the @samp{-v} flag to the
cvs.texi(,3491) @code{status} command to see all tags that a file has, and
cvs.texi(,3492) which revision numbers they represent.  Tag names must
cvs.texi(,3493) start with an uppercase or lowercase letter and can
cvs.texi(,3494) contain uppercase and lowercase letters, digits,
cvs.texi(,3495) @samp{-}, and @samp{_}.  The two tag names @code{BASE}
cvs.texi(,3496) and @code{HEAD} are reserved for use by @sc{cvs}.  It
cvs.texi(,3497) is expected that future names which are special to
cvs.texi(,3498) @sc{cvs} will be specially named, for example by
cvs.texi(,3499) starting with @samp{.}, rather than being named analogously to
cvs.texi(,3500) @code{BASE} and @code{HEAD}, to avoid conflicts with
cvs.texi(,3501) actual tag names.
cvs.texi(,3502) @c Including a character such as % or = has also been
cvs.texi(,3503) @c suggested as the naming convention for future
cvs.texi(,3504) @c special tag names.  Starting with . is nice because
cvs.texi(,3505) @c that is not a legal tag name as far as RCS is concerned.
cvs.texi(,3506) @c FIXME: CVS actually accepts quite a few characters
cvs.texi(,3507) @c in tag names, not just the ones documented above
cvs.texi(,3508) @c (see RCS_check_tag).  RCS
cvs.texi(,3509) @c defines legitimate tag names by listing illegal
cvs.texi(,3510) @c characters rather than legal ones.  CVS is said to lose its
cvs.texi(,3511) @c mind if you try to use "/" (try making such a tag sticky
cvs.texi(,3512) @c and using "cvs status" client/server--see remote
cvs.texi(,3513) @c protocol format for entries line for probable cause).
cvs.texi(,3514) @c TODO: The testsuite
cvs.texi(,3515) @c should test for whatever are documented above as
cvs.texi(,3516) @c officially-OK tag names, and CVS should at least reject
cvs.texi(,3517) @c characters that won't work, like "/".
cvs.texi(,3518) 
cvs.texi(,3519) You'll want to choose some convention for naming tags,
cvs.texi(,3520) based on information such as the name of the program
cvs.texi(,3521) and the version number of the release.  For example,
cvs.texi(,3522) one might take the name of the program, immediately
cvs.texi(,3523) followed by the version number with @samp{.} changed to
cvs.texi(,3524) @samp{-}, so that @sc{cvs} 1.9 would be tagged with the name
cvs.texi(,3525) @code{cvs1-9}.  If you choose a consistent convention,
cvs.texi(,3526) then you won't constantly be guessing whether a tag is
cvs.texi(,3527) @code{cvs-1-9} or @code{cvs1_9} or what.  You might
cvs.texi(,3528) even want to consider enforcing your convention in the
cvs.texi(,3529) taginfo file (@pxref{user-defined logging}).
cvs.texi(,3530) @c Might be nice to say more about using taginfo this
cvs.texi(,3531) @c way, like giving an example, or pointing out any particular
cvs.texi(,3532) @c issues which arise.
cvs.texi(,3533) 
cvs.texi(,3534) @cindex Adding a tag
cvs.texi(,3535) @cindex Tags, example
cvs.texi(,3536) The following example shows how you can add a tag to a
cvs.texi(,3537) file.  The commands must be issued inside your working
cvs.texi(,3538) directory.  That is, you should issue the
cvs.texi(,3539) command in the directory where @file{backend.c}
cvs.texi(,3540) resides.
cvs.texi(,3541) 
cvs.texi(,3542) @example
cvs.texi(,3543) $ cvs tag rel-0-4 backend.c
cvs.texi(,3544) T backend.c
cvs.texi(,3545) $ cvs status -v backend.c
cvs.texi(,3546) ===================================================================
cvs.texi(,3547) File: backend.c         Status: Up-to-date
cvs.texi(,3548) 
cvs.texi(,3549)     Version:            1.4     Tue Dec  1 14:39:01 1992
cvs.texi(,3550)     RCS Version:        1.4     /u/cvsroot/yoyodyne/tc/backend.c,v
cvs.texi(,3551)     Sticky Tag:         (none)
cvs.texi(,3552)     Sticky Date:        (none)
cvs.texi(,3553)     Sticky Options:     (none)
cvs.texi(,3554) 
cvs.texi(,3555)     Existing Tags:
cvs.texi(,3556)         rel-0-4                     (revision: 1.4)
cvs.texi(,3557) 
cvs.texi(,3558) @end example
cvs.texi(,3559) 
cvs.texi(,3560) For a complete summary of the syntax of @code{cvs tag},
cvs.texi(,3561) including the various options, see @ref{Invoking CVS}.
cvs.texi(,3562) 
cvs.texi(,3563) There is seldom reason to tag a file in isolation.  A more common use is
cvs.texi(,3564) to tag all the files that constitute a module with the same tag at
cvs.texi(,3565) strategic points in the development life-cycle, such as when a release
cvs.texi(,3566) is made.
cvs.texi(,3567) 
cvs.texi(,3568) @example
cvs.texi(,3569) $ cvs tag rel-1-0 .
cvs.texi(,3570) cvs tag: Tagging .
cvs.texi(,3571) T Makefile
cvs.texi(,3572) T backend.c
cvs.texi(,3573) T driver.c
cvs.texi(,3574) T frontend.c
cvs.texi(,3575) T parser.c
cvs.texi(,3576) @end example
cvs.texi(,3577) 
cvs.texi(,3578) @noindent
cvs.texi(,3579) (When you give @sc{cvs} a directory as argument, it generally applies the
cvs.texi(,3580) operation to all the files in that directory, and (recursively), to any
cvs.texi(,3581) subdirectories that it may contain.  @xref{Recursive behavior}.)
cvs.texi(,3582) 
cvs.texi(,3583) @cindex Retrieving an old revision using tags
cvs.texi(,3584) @cindex Tags, retrieving old revisions
cvs.texi(,3585) The @code{checkout} command has a flag, @samp{-r}, that lets you check out
cvs.texi(,3586) a certain revision of a module.  This flag makes it easy to
cvs.texi(,3587) retrieve the sources that make up release 1.0 of the module @samp{tc} at
cvs.texi(,3588) any time in the future:
cvs.texi(,3589) 
cvs.texi(,3590) @example
cvs.texi(,3591) $ cvs checkout -r rel-1-0 tc
cvs.texi(,3592) @end example
cvs.texi(,3593) 
cvs.texi(,3594) @noindent
cvs.texi(,3595) This is useful, for instance, if someone claims that there is a bug in
cvs.texi(,3596) that release, but you cannot find the bug in the current working copy.
cvs.texi(,3597) 
cvs.texi(,3598) You can also check out a module as it was at any given date.
cvs.texi(,3599) @xref{checkout options}.  When specifying @samp{-r} to
cvs.texi(,3600) any of these commands, you will need beware of sticky
cvs.texi(,3601) tags; see @ref{Sticky tags}.
cvs.texi(,3602) 
cvs.texi(,3603) When you tag more than one file with the same tag you
cvs.texi(,3604) can think about the tag as "a curve drawn through a
cvs.texi(,3605) matrix of filename vs. revision number."  Say we have 5
cvs.texi(,3606) files with the following revisions:
cvs.texi(,3607) 
cvs.texi(,3608) @example
cvs.texi(,3609) @group
cvs.texi(,3610)         file1   file2   file3   file4   file5
cvs.texi(,3611) 
cvs.texi(,3612)         1.1     1.1     1.1     1.1  /--1.1*      <-*-  TAG
cvs.texi(,3613)         1.2*-   1.2     1.2    -1.2*-
cvs.texi(,3614)         1.3  \- 1.3*-   1.3   / 1.3
cvs.texi(,3615)         1.4          \  1.4  /  1.4
cvs.texi(,3616)                       \-1.5*-   1.5
cvs.texi(,3617)                         1.6
cvs.texi(,3618) @end group
cvs.texi(,3619) @end example
cvs.texi(,3620) 
cvs.texi(,3621) At some time in the past, the @code{*} versions were tagged.
cvs.texi(,3622) You can think of the tag as a handle attached to the curve
cvs.texi(,3623) drawn through the tagged revisions.  When you pull on
cvs.texi(,3624) the handle, you get all the tagged revisions.  Another
cvs.texi(,3625) way to look at it is that you "sight" through a set of
cvs.texi(,3626) revisions that is "flat" along the tagged revisions,
cvs.texi(,3627) like this:
cvs.texi(,3628) 
cvs.texi(,3629) @example
cvs.texi(,3630) @group
cvs.texi(,3631)         file1   file2   file3   file4   file5
cvs.texi(,3632) 
cvs.texi(,3633)                         1.1
cvs.texi(,3634)                         1.2
cvs.texi(,3635)                 1.1     1.3                       _
cvs.texi(,3636)         1.1     1.2     1.4     1.1              /
cvs.texi(,3637)         1.2*----1.3*----1.5*----1.2*----1.1     (--- <--- Look here
cvs.texi(,3638)         1.3             1.6     1.3              \_
cvs.texi(,3639)         1.4                     1.4
cvs.texi(,3640)                                 1.5
cvs.texi(,3641) @end group
cvs.texi(,3642) @end example
cvs.texi(,3643) 
cvs.texi(,3644) @node Tagging the working directory
cvs.texi(,3645) @section Specifying what to tag from the working directory
cvs.texi(,3646) 
cvs.texi(,3647) @cindex tag (subcommand)
cvs.texi(,3648) The example in the previous section demonstrates one of
cvs.texi(,3649) the most common ways to choose which revisions to tag.
cvs.texi(,3650) Namely, running the @code{cvs tag} command without
cvs.texi(,3651) arguments causes @sc{cvs} to select the revisions which
cvs.texi(,3652) are checked out in the current working directory.  For
cvs.texi(,3653) example, if the copy of @file{backend.c} in working
cvs.texi(,3654) directory was checked out from revision 1.4, then
cvs.texi(,3655) @sc{cvs} will tag revision 1.4.  Note that the tag is
cvs.texi(,3656) applied immediately to revision 1.4 in the repository;
cvs.texi(,3657) tagging is not like modifying a file, or other
cvs.texi(,3658) operations in which one first modifies the working
cvs.texi(,3659) directory and then runs @code{cvs commit} to transfer
cvs.texi(,3660) that modification to the repository.
cvs.texi(,3661) 
cvs.texi(,3662) One potentially surprising aspect of the fact that
cvs.texi(,3663) @code{cvs tag} operates on the repository is that you
cvs.texi(,3664) are tagging the checked-in revisions, which may differ
cvs.texi(,3665) from locally modified files in your working directory.
cvs.texi(,3666) If you want to avoid doing this by mistake, specify the
cvs.texi(,3667) @samp{-c} option to @code{cvs tag}.  If there are any
cvs.texi(,3668) locally modified files, @sc{cvs} will abort with an
cvs.texi(,3669) error before it tags any files:
cvs.texi(,3670) 
cvs.texi(,3671) @example
cvs.texi(,3672) $ cvs tag -c rel-0-4
cvs.texi(,3673) cvs tag: backend.c is locally modified
cvs.texi(,3674) cvs [tag aborted]: correct the above errors first!
cvs.texi(,3675) @end example
cvs.texi(,3676) 
cvs.texi(,3677) @node Tagging by date/tag
cvs.texi(,3678) @section Specifying what to tag by date or revision
cvs.texi(,3679) @cindex rtag (subcommand)
cvs.texi(,3680) 
cvs.texi(,3681) The @code{cvs rtag} command tags the repository as of a
cvs.texi(,3682) certain date or time (or can be used to tag the latest
cvs.texi(,3683) revision).  @code{rtag} works directly on the
cvs.texi(,3684) repository contents (it requires no prior checkout and
cvs.texi(,3685) does not look for a working directory).
cvs.texi(,3686) 
cvs.texi(,3687) The following options specify which date or revision to
cvs.texi(,3688) tag.  See @ref{Common options}, for a complete
cvs.texi(,3689) description of them.
cvs.texi(,3690) 
cvs.texi(,3691) @table @code
cvs.texi(,3692) @item -D @var{date}
cvs.texi(,3693) Tag the most recent revision no later than @var{date}.
cvs.texi(,3694) 
cvs.texi(,3695) @item -f
cvs.texi(,3696) Only useful with the @samp{-D @var{date}} or @samp{-r @var{tag}}
cvs.texi(,3697) flags.  If no matching revision is found, use the most
cvs.texi(,3698) recent revision (instead of ignoring the file).
cvs.texi(,3699) 
cvs.texi(,3700) @item -r @var{tag}
cvs.texi(,3701) Only tag those files that contain existing tag @var{tag}.
cvs.texi(,3702) @end table
cvs.texi(,3703) 
cvs.texi(,3704) The @code{cvs tag} command also allows one to specify
cvs.texi(,3705) files by revision or date, using the same @samp{-r},
cvs.texi(,3706) @samp{-D}, and @samp{-f} options.  However, this
cvs.texi(,3707) feature is probably not what you want.  The reason is
cvs.texi(,3708) that @code{cvs tag} chooses which files to tag based on
cvs.texi(,3709) the files that exist in the working directory, rather
cvs.texi(,3710) than the files which existed as of the given tag/date.
cvs.texi(,3711) Therefore, you are generally better off using @code{cvs
cvs.texi(,3712) rtag}.  The exceptions might be cases like:
cvs.texi(,3713) 
cvs.texi(,3714) @example
cvs.texi(,3715) cvs tag -r 1.4 stable backend.c
cvs.texi(,3716) @end example
cvs.texi(,3717) 
cvs.texi(,3718) @node Modifying tags
cvs.texi(,3719) @section Deleting, moving, and renaming tags
cvs.texi(,3720) 
cvs.texi(,3721) @c Also see:
cvs.texi(,3722) @c  "How do I move or rename a magic branch tag?"
cvs.texi(,3723) @c in the FAQ (I think the issues it talks about still
cvs.texi(,3724) @c apply, but this could use some sanity.sh work).
cvs.texi(,3725) 
cvs.texi(,3726) Normally one does not modify tags.  They exist in order
cvs.texi(,3727) to record the history of the repository and so deleting
cvs.texi(,3728) them or changing their meaning would, generally, not be
cvs.texi(,3729) what you want.
cvs.texi(,3730) 
cvs.texi(,3731) However, there might be cases in which one uses a tag
cvs.texi(,3732) temporarily or accidentally puts one in the wrong
cvs.texi(,3733) place.  Therefore, one might delete, move, or rename a
cvs.texi(,3734) tag.
cvs.texi(,3735) 
cvs.texi(,3736) @noindent
cvs.texi(,3737) @strong{WARNING: the commands in this section are
cvs.texi(,3738) dangerous; they permanently discard historical
cvs.texi(,3739) information and it can be difficult or impossible to
cvs.texi(,3740) recover from errors.  If you are a @sc{cvs}
cvs.texi(,3741) administrator, you may consider restricting these
cvs.texi(,3742) commands with taginfo (@pxref{user-defined logging}).}
cvs.texi(,3743) 
cvs.texi(,3744) @cindex Deleting tags
cvs.texi(,3745) @cindex Deleting branch tags
cvs.texi(,3746) @cindex Removing tags
cvs.texi(,3747) @cindex Removing branch tags
cvs.texi(,3748) @cindex Tags, deleting
cvs.texi(,3749) @cindex Branch tags, deleting
cvs.texi(,3750) To delete a tag, specify the @samp{-d} option to either
cvs.texi(,3751) @code{cvs tag} or @code{cvs rtag}.  For example:
cvs.texi(,3752) 
cvs.texi(,3753) @example
cvs.texi(,3754) cvs rtag -d rel-0-4 tc
cvs.texi(,3755) @end example
cvs.texi(,3756) 
cvs.texi(,3757) @noindent
cvs.texi(,3758) deletes the non-branch tag @code{rel-0-4} from the module @code{tc}.
cvs.texi(,3759) In the event that branch tags are encountered within the repository
cvs.texi(,3760) with the given name, a warning message will be issued and the branch 
cvs.texi(,3761) tag will not be deleted.  If you are absolutely certain you know what
cvs.texi(,3762) you are doing, the @code{-B} option may be specified to allow deletion
cvs.texi(,3763) of branch tags.  In that case, any non-branch tags encountered will
cvs.texi(,3764) trigger warnings and will not be deleted.
cvs.texi(,3765) 
cvs.texi(,3766) @noindent
cvs.texi(,3767) @strong{WARNING: Moving branch tags is very dangerous!  If you think
cvs.texi(,3768) you need the @code{-B} option, think again and ask your @sc{cvs}
cvs.texi(,3769) administrator about it (if that isn't you).  There is almost certainly
cvs.texi(,3770) another way to accomplish what you want to accomplish.}
cvs.texi(,3771) 
cvs.texi(,3772) @cindex Moving tags
cvs.texi(,3773) @cindex Moving branch tags
cvs.texi(,3774) @cindex Tags, moving
cvs.texi(,3775) @cindex Branch tags, moving
cvs.texi(,3776) When we say @dfn{move} a tag, we mean to make the same
cvs.texi(,3777) name point to different revisions.  For example, the
cvs.texi(,3778) @code{stable} tag may currently point to revision 1.4
cvs.texi(,3779) of @file{backend.c} and perhaps we want to make it
cvs.texi(,3780) point to revision 1.6.  To move a non-branch tag, specify the
cvs.texi(,3781) @samp{-F} option to either @code{cvs tag} or @code{cvs
cvs.texi(,3782) rtag}.  For example, the task just mentioned might be
cvs.texi(,3783) accomplished as:
cvs.texi(,3784) 
cvs.texi(,3785) @example
cvs.texi(,3786) cvs tag -r 1.6 -F stable backend.c
cvs.texi(,3787) @end example
cvs.texi(,3788) 
cvs.texi(,3789) @noindent
cvs.texi(,3790) If any branch tags are encountered in the repository 
cvs.texi(,3791) with the given name, a warning is issued and the branch
cvs.texi(,3792) tag is not disturbed.  If you are absolutely certain you
cvs.texi(,3793) wish to move the branch tag, the @code{-B} option may be specified.
cvs.texi(,3794) In that case, non-branch tags encountered with the given
cvs.texi(,3795) name are ignored with a warning message.
cvs.texi(,3796) 
cvs.texi(,3797) @noindent
cvs.texi(,3798) @strong{WARNING: Moving branch tags is very dangerous!  If you think you
cvs.texi(,3799) need the @code{-B} option, think again and ask your @sc{cvs}
cvs.texi(,3800) administrator about it (if that isn't you).  There is almost certainly
cvs.texi(,3801) another way to accomplish what you want to accomplish.}
cvs.texi(,3802) 
cvs.texi(,3803) @cindex Renaming tags
cvs.texi(,3804) @cindex Tags, renaming
cvs.texi(,3805) When we say @dfn{rename} a tag, we mean to make a
cvs.texi(,3806) different name point to the same revisions as the old
cvs.texi(,3807) tag.  For example, one may have misspelled the tag name
cvs.texi(,3808) and want to correct it (hopefully before others are
cvs.texi(,3809) relying on the old spelling).  To rename a tag, first
cvs.texi(,3810) create a new tag using the @samp{-r} option to
cvs.texi(,3811) @code{cvs rtag}, and then delete the old name.  (Caution:
cvs.texi(,3812) this method will not work with branch tags.) 
cvs.texi(,3813) This leaves the new tag on exactly the 
cvs.texi(,3814) same files as the old tag.  For example:
cvs.texi(,3815) 
cvs.texi(,3816) @example
cvs.texi(,3817) cvs rtag -r old-name-0-4 rel-0-4 tc
cvs.texi(,3818) cvs rtag -d old-name-0-4 tc
cvs.texi(,3819) @end example
cvs.texi(,3820) 
cvs.texi(,3821) @node Tagging add/remove
cvs.texi(,3822) @section Tagging and adding and removing files
cvs.texi(,3823) 
cvs.texi(,3824) The subject of exactly how tagging interacts with
cvs.texi(,3825) adding and removing files is somewhat obscure; for the
cvs.texi(,3826) most part @sc{cvs} will keep track of whether files
cvs.texi(,3827) exist or not without too much fussing.  By default,
cvs.texi(,3828) tags are applied to only files which have a revision
cvs.texi(,3829) corresponding to what is being tagged.  Files which did
cvs.texi(,3830) not exist yet, or which were already removed, simply
cvs.texi(,3831) omit the tag, and @sc{cvs} knows to treat the absence
cvs.texi(,3832) of a tag as meaning that the file didn't exist as of
cvs.texi(,3833) that tag.
cvs.texi(,3834) 
cvs.texi(,3835) However, this can lose a small amount of information.
cvs.texi(,3836) For example, suppose a file was added and then removed.
cvs.texi(,3837) Then, if the tag is missing for that file, there is no
cvs.texi(,3838) way to know whether the tag refers to the time before
cvs.texi(,3839) the file was added, or the time after it was removed.
cvs.texi(,3840) If you specify the @samp{-r} option to @code{cvs rtag},
cvs.texi(,3841) then @sc{cvs} tags the files which have been removed,
cvs.texi(,3842) and thereby avoids this problem.  For example, one
cvs.texi(,3843) might specify @code{-r HEAD} to tag the head.
cvs.texi(,3844) 
cvs.texi(,3845) On the subject of adding and removing files, the
cvs.texi(,3846) @code{cvs rtag} command has a @samp{-a} option which
cvs.texi(,3847) means to clear the tag from removed files that would
cvs.texi(,3848) not otherwise be tagged.  For example, one might
cvs.texi(,3849) specify this option in conjunction with @samp{-F} when
cvs.texi(,3850) moving a tag.  If one moved a tag without @samp{-a},
cvs.texi(,3851) then the tag in the removed files might still refer to
cvs.texi(,3852) the old revision, rather than reflecting the fact that
cvs.texi(,3853) the file had been removed.  I don't think this is
cvs.texi(,3854) necessary if @samp{-r} is specified, as noted above.
cvs.texi(,3855) 
cvs.texi(,3856) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,3857) @node Sticky tags
cvs.texi(,3858) @section Sticky tags
cvs.texi(,3859) @cindex Sticky tags
cvs.texi(,3860) @cindex Tags, sticky
cvs.texi(,3861) 
cvs.texi(,3862) @c A somewhat related issue is per-directory sticky
cvs.texi(,3863) @c tags (see comment at CVS/Tag in node Working
cvs.texi(,3864) @c directory storage); we probably want to say
cvs.texi(,3865) @c something like "you can set a sticky tag for only
cvs.texi(,3866) @c some files, but you don't want to" or some such.
cvs.texi(,3867) 
cvs.texi(,3868) Sometimes a working copy's revision has extra data
cvs.texi(,3869) associated with it, for example it might be on a branch
cvs.texi(,3870) (@pxref{Branching and merging}), or restricted to
cvs.texi(,3871) versions prior to a certain date by @samp{checkout -D}
cvs.texi(,3872) or @samp{update -D}.  Because this data persists --
cvs.texi(,3873) that is, it applies to subsequent commands in the
cvs.texi(,3874) working copy -- we refer to it as @dfn{sticky}.
cvs.texi(,3875) 
cvs.texi(,3876) Most of the time, stickiness is an obscure aspect of
cvs.texi(,3877) @sc{cvs} that you don't need to think about.  However,
cvs.texi(,3878) even if you don't want to use the feature, you may need
cvs.texi(,3879) to know @emph{something} about sticky tags (for
cvs.texi(,3880) example, how to avoid them!).
cvs.texi(,3881) 
cvs.texi(,3882) You can use the @code{status} command to see if any
cvs.texi(,3883) sticky tags or dates are set:
cvs.texi(,3884) 
cvs.texi(,3885) @example
cvs.texi(,3886) $ cvs status driver.c
cvs.texi(,3887) ===================================================================
cvs.texi(,3888) File: driver.c          Status: Up-to-date
cvs.texi(,3889) 
cvs.texi(,3890)     Version:            1.7.2.1 Sat Dec  5 19:35:03 1992
cvs.texi(,3891)     RCS Version:        1.7.2.1 /u/cvsroot/yoyodyne/tc/driver.c,v
cvs.texi(,3892)     Sticky Tag:         rel-1-0-patches (branch: 1.7.2)
cvs.texi(,3893)     Sticky Date:        (none)
cvs.texi(,3894)     Sticky Options:     (none)
cvs.texi(,3895) 
cvs.texi(,3896) @end example
cvs.texi(,3897) 
cvs.texi(,3898) @cindex Resetting sticky tags
cvs.texi(,3899) @cindex Sticky tags, resetting
cvs.texi(,3900) @cindex Deleting sticky tags
cvs.texi(,3901) The sticky tags will remain on your working files until
cvs.texi(,3902) you delete them with @samp{cvs update -A}.  The
cvs.texi(,3903) @samp{-A} option merges local changes into the version of the
cvs.texi(,3904) file from the head of the trunk, removing any sticky tags,
cvs.texi(,3905) dates, or options.  See @ref{update} for more on the operation
cvs.texi(,3906) of @code{cvs update}.
cvs.texi(,3907) 
cvs.texi(,3908) @cindex Sticky date
cvs.texi(,3909) The most common use of sticky tags is to identify which
cvs.texi(,3910) branch one is working on, as described in
cvs.texi(,3911) @ref{Accessing branches}.  However, non-branch
cvs.texi(,3912) sticky tags have uses as well.  For example,
cvs.texi(,3913) suppose that you want to avoid updating your working
cvs.texi(,3914) directory, to isolate yourself from possibly
cvs.texi(,3915) destabilizing changes other people are making.  You
cvs.texi(,3916) can, of course, just refrain from running @code{cvs
cvs.texi(,3917) update}.  But if you want to avoid updating only a
cvs.texi(,3918) portion of a larger tree, then sticky tags can help.
cvs.texi(,3919) If you check out a certain revision (such as 1.4) it
cvs.texi(,3920) will become sticky.  Subsequent @code{cvs update}
cvs.texi(,3921) commands will
cvs.texi(,3922) not retrieve the latest revision until you reset the
cvs.texi(,3923) tag with @code{cvs update -A}.  Likewise, use of the
cvs.texi(,3924) @samp{-D} option to @code{update} or @code{checkout}
cvs.texi(,3925) sets a @dfn{sticky date}, which, similarly, causes that
cvs.texi(,3926) date to be used for future retrievals.
cvs.texi(,3927) 
cvs.texi(,3928) People often want to retrieve an old version of
cvs.texi(,3929) a file without setting a sticky tag.  This can
cvs.texi(,3930) be done with the @samp{-p} option to @code{checkout} or
cvs.texi(,3931) @code{update}, which sends the contents of the file to
cvs.texi(,3932) standard output.  For example:
cvs.texi(,3933) @example
cvs.texi(,3934) $ cvs update -p -r 1.1 file1 >file1
cvs.texi(,3935) ===================================================================
cvs.texi(,3936) Checking out file1
cvs.texi(,3937) RCS:  /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v
cvs.texi(,3938) VERS: 1.1
cvs.texi(,3939) ***************
cvs.texi(,3940) $
cvs.texi(,3941) @end example
cvs.texi(,3942) 
cvs.texi(,3943) However, this isn't the easiest way, if you are asking
cvs.texi(,3944) how to undo a previous checkin (in this example, put
cvs.texi(,3945) @file{file1} back to the way it was as of revision
cvs.texi(,3946) 1.1).  In that case you are better off using the
cvs.texi(,3947) @samp{-j} option to @code{update}; for further
cvs.texi(,3948) discussion see @ref{Merging two revisions}.
cvs.texi(,3949) 
cvs.texi(,3950) @c ---------------------------------------------------------------------
cvs.texi(,3951) @node Branching and merging
cvs.texi(,3952) @chapter Branching and merging
cvs.texi(,3953) @cindex Branching
cvs.texi(,3954) @cindex Merging
cvs.texi(,3955) @cindex Copying changes
cvs.texi(,3956) @cindex Main trunk and branches
cvs.texi(,3957) @cindex Revision tree, making branches
cvs.texi(,3958) @cindex Branches, copying changes between
cvs.texi(,3959) @cindex Changes, copying between branches
cvs.texi(,3960) @cindex Modifications, copying between branches
cvs.texi(,3961) 
cvs.texi(,3962) @sc{cvs} allows you to isolate changes onto a separate
cvs.texi(,3963) line of development, known as a @dfn{branch}.  When you
cvs.texi(,3964) change files on a branch, those changes do not appear
cvs.texi(,3965) on the main trunk or other branches.
cvs.texi(,3966) 
cvs.texi(,3967) Later you can move changes from one branch to another
cvs.texi(,3968) branch (or the main trunk) by @dfn{merging}.  Merging
cvs.texi(,3969) involves first running @code{cvs update -j}, to merge
cvs.texi(,3970) the changes into the working directory.
cvs.texi(,3971) You can then commit that revision, and thus effectively
cvs.texi(,3972) copy the changes onto another branch.
cvs.texi(,3973) 
cvs.texi(,3974) @menu
cvs.texi(,3975) * Branches motivation::         What branches are good for
cvs.texi(,3976) * Creating a branch::           Creating a branch
cvs.texi(,3977) * Accessing branches::          Checking out and updating branches
cvs.texi(,3978) * Branches and revisions::      Branches are reflected in revision numbers
cvs.texi(,3979) * Magic branch numbers::        Magic branch numbers
cvs.texi(,3980) * Merging a branch::            Merging an entire branch
cvs.texi(,3981) * Merging more than once::      Merging from a branch several times
cvs.texi(,3982) * Merging two revisions::       Merging differences between two revisions
cvs.texi(,3983) * Merging adds and removals::   What if files are added or removed?
cvs.texi(,3984) * Merging and keywords::        Avoiding conflicts due to keyword substitution
cvs.texi(,3985) @end menu
cvs.texi(,3986) 
cvs.texi(,3987) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,3988) @node Branches motivation
cvs.texi(,3989) @section What branches are good for
cvs.texi(,3990) @cindex Branches motivation
cvs.texi(,3991) @cindex What branches are good for
cvs.texi(,3992) @cindex Motivation for branches
cvs.texi(,3993) 
cvs.texi(,3994) @c FIXME: this node mentions one way to use branches,
cvs.texi(,3995) @c but it is by no means the only way.  For example,
cvs.texi(,3996) @c the technique of committing a new feature on a branch,
cvs.texi(,3997) @c until it is ready for the main trunk.  The whole
cvs.texi(,3998) @c thing is generally speaking more akin to the
cvs.texi(,3999) @c "Revision management" node although it isn't clear to
cvs.texi(,4000) @c me whether policy matters should be centralized or
cvs.texi(,4001) @c distributed throughout the relevant sections.
cvs.texi(,4002) Suppose that release 1.0 of tc has been made.  You are continuing to
cvs.texi(,4003) develop tc, planning to create release 1.1 in a couple of months.  After a
cvs.texi(,4004) while your customers start to complain about a fatal bug.  You check
cvs.texi(,4005) out release 1.0 (@pxref{Tags}) and find the bug
cvs.texi(,4006) (which turns out to have a trivial fix).  However, the current revision
cvs.texi(,4007) of the sources are in a state of flux and are not expected to be stable
cvs.texi(,4008) for at least another month.  There is no way to make a
cvs.texi(,4009) bugfix release based on the newest sources.
cvs.texi(,4010) 
cvs.texi(,4011) The thing to do in a situation like this is to create a @dfn{branch} on
cvs.texi(,4012) the revision trees for all the files that make up
cvs.texi(,4013) release 1.0 of tc.  You can then make
cvs.texi(,4014) modifications to the branch without disturbing the main trunk.  When the
cvs.texi(,4015) modifications are finished you can elect to either incorporate them on
cvs.texi(,4016) the main trunk, or leave them on the branch.
cvs.texi(,4017) 
cvs.texi(,4018) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,4019) @node Creating a branch
cvs.texi(,4020) @section Creating a branch
cvs.texi(,4021) @cindex Creating a branch
cvs.texi(,4022) @cindex Branch, creating a
cvs.texi(,4023) @cindex tag (subcommand), creating a branch using
cvs.texi(,4024) @cindex rtag (subcommand), creating a branch using
cvs.texi(,4025) 
cvs.texi(,4026) You can create a branch with @code{tag -b}; for
cvs.texi(,4027) example, assuming you're in a working copy:
cvs.texi(,4028) 
cvs.texi(,4029) @example
cvs.texi(,4030) $ cvs tag -b rel-1-0-patches
cvs.texi(,4031) @end example
cvs.texi(,4032) 
cvs.texi(,4033) @c FIXME: we should be more explicit about the value of
cvs.texi(,4034) @c having a tag on the branchpoint.  For example
cvs.texi(,4035) @c "cvs tag rel-1-0-patches-branchpoint" before
cvs.texi(,4036) @c the "cvs tag -b".  This points out that
cvs.texi(,4037) @c rel-1-0-patches is a pretty awkward name for
cvs.texi(,4038) @c this example (more so than for the rtag example
cvs.texi(,4039) @c below).
cvs.texi(,4040) 
cvs.texi(,4041) This splits off a branch based on the current revisions
cvs.texi(,4042) in the working copy, assigning that branch the name
cvs.texi(,4043) @samp{rel-1-0-patches}.
cvs.texi(,4044) 
cvs.texi(,4045) It is important to understand that branches get created
cvs.texi(,4046) in the repository, not in the working copy.  Creating a
cvs.texi(,4047) branch based on current revisions, as the above example
cvs.texi(,4048) does, will @emph{not} automatically switch the working
cvs.texi(,4049) copy to be on the new branch.  For information on how
cvs.texi(,4050) to do that, see @ref{Accessing branches}.
cvs.texi(,4051) 
cvs.texi(,4052) You can also create a branch without reference to any
cvs.texi(,4053) working copy, by using @code{rtag}:
cvs.texi(,4054) 
cvs.texi(,4055) @example
cvs.texi(,4056) $ cvs rtag -b -r rel-1-0 rel-1-0-patches tc
cvs.texi(,4057) @end example
cvs.texi(,4058) 
cvs.texi(,4059) @samp{-r rel-1-0} says that this branch should be
cvs.texi(,4060) rooted at the revision that
cvs.texi(,4061) corresponds to the tag @samp{rel-1-0}.  It need not
cvs.texi(,4062) be the most recent revision -- it's often useful to
cvs.texi(,4063) split a branch off an old revision (for example, when
cvs.texi(,4064) fixing a bug in a past release otherwise known to be
cvs.texi(,4065) stable).
cvs.texi(,4066) 
cvs.texi(,4067) As with @samp{tag}, the @samp{-b} flag tells
cvs.texi(,4068) @code{rtag} to create a branch (rather than just a
cvs.texi(,4069) symbolic revision name).  Note that the numeric
cvs.texi(,4070) revision number that matches @samp{rel-1-0} will
cvs.texi(,4071) probably be different from file to file.
cvs.texi(,4072) 
cvs.texi(,4073) So, the full effect of the command is to create a new
cvs.texi(,4074) branch -- named @samp{rel-1-0-patches} -- in module
cvs.texi(,4075) @samp{tc}, rooted in the revision tree at the point tagged
cvs.texi(,4076) by @samp{rel-1-0}.
cvs.texi(,4077) 
cvs.texi(,4078) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,4079) @node Accessing branches
cvs.texi(,4080) @section Accessing branches
cvs.texi(,4081) @cindex Check out a branch
cvs.texi(,4082) @cindex Retrieve a branch
cvs.texi(,4083) @cindex Access a branch
cvs.texi(,4084) @cindex Identifying a branch
cvs.texi(,4085) @cindex Branch, check out
cvs.texi(,4086) @cindex Branch, retrieving
cvs.texi(,4087) @cindex Branch, accessing
cvs.texi(,4088) @cindex Branch, identifying
cvs.texi(,4089) 
cvs.texi(,4090) You can retrieve a branch in one of two ways: by
cvs.texi(,4091) checking it out fresh from the repository, or by
cvs.texi(,4092) switching an existing working copy over to the branch.
cvs.texi(,4093) 
cvs.texi(,4094) To check out a branch from the repository, invoke
cvs.texi(,4095) @samp{checkout} with the @samp{-r} flag, followed by
cvs.texi(,4096) the tag name of the branch (@pxref{Creating a branch}):
cvs.texi(,4097) 
cvs.texi(,4098) @example
cvs.texi(,4099) $ cvs checkout -r rel-1-0-patches tc
cvs.texi(,4100) @end example
cvs.texi(,4101) 
cvs.texi(,4102) Or, if you already have a working copy, you can switch
cvs.texi(,4103) it to a given branch with @samp{update -r}:
cvs.texi(,4104) 
cvs.texi(,4105) @example
cvs.texi(,4106) $ cvs update -r rel-1-0-patches tc
cvs.texi(,4107) @end example
cvs.texi(,4108) 
cvs.texi(,4109) @noindent
cvs.texi(,4110) or equivalently:
cvs.texi(,4111) 
cvs.texi(,4112) @example
cvs.texi(,4113) $ cd tc
cvs.texi(,4114) $ cvs update -r rel-1-0-patches
cvs.texi(,4115) @end example
cvs.texi(,4116) 
cvs.texi(,4117) It does not matter if the working copy was originally
cvs.texi(,4118) on the main trunk or on some other branch -- the above
cvs.texi(,4119) command will switch it to the named branch.  And
cvs.texi(,4120) similarly to a regular @samp{update} command,
cvs.texi(,4121) @samp{update -r} merges any changes you have made,
cvs.texi(,4122) notifying you of conflicts where they occur.
cvs.texi(,4123) 
cvs.texi(,4124) Once you have a working copy tied to a particular
cvs.texi(,4125) branch, it remains there until you tell it otherwise.
cvs.texi(,4126) This means that changes checked in from the working
cvs.texi(,4127) copy will add new revisions on that branch, while
cvs.texi(,4128) leaving the main trunk and other branches unaffected.
cvs.texi(,4129) 
cvs.texi(,4130) @cindex Branches, sticky
cvs.texi(,4131) To find out what branch a working copy is on, you can
cvs.texi(,4132) use the @samp{status} command.  In its output, look for
cvs.texi(,4133) the field named @samp{Sticky tag} (@pxref{Sticky tags})
cvs.texi(,4134) -- that's @sc{cvs}'s way of telling you the branch, if
cvs.texi(,4135) any, of the current working files:
cvs.texi(,4136) 
cvs.texi(,4137) @example
cvs.texi(,4138) $ cvs status -v driver.c backend.c
cvs.texi(,4139) ===================================================================
cvs.texi(,4140) File: driver.c          Status: Up-to-date
cvs.texi(,4141) 
cvs.texi(,4142)     Version:            1.7     Sat Dec  5 18:25:54 1992
cvs.texi(,4143)     RCS Version:        1.7     /u/cvsroot/yoyodyne/tc/driver.c,v
cvs.texi(,4144)     Sticky Tag:         rel-1-0-patches (branch: 1.7.2)
cvs.texi(,4145)     Sticky Date:        (none)
cvs.texi(,4146)     Sticky Options:     (none)
cvs.texi(,4147) 
cvs.texi(,4148)     Existing Tags:
cvs.texi(,4149)         rel-1-0-patches             (branch: 1.7.2)
cvs.texi(,4150)         rel-1-0                     (revision: 1.7)
cvs.texi(,4151) 
cvs.texi(,4152) ===================================================================
cvs.texi(,4153) File: backend.c         Status: Up-to-date
cvs.texi(,4154) 
cvs.texi(,4155)     Version:            1.4     Tue Dec  1 14:39:01 1992
cvs.texi(,4156)     RCS Version:        1.4     /u/cvsroot/yoyodyne/tc/backend.c,v
cvs.texi(,4157)     Sticky Tag:         rel-1-0-patches (branch: 1.4.2)
cvs.texi(,4158)     Sticky Date:        (none)
cvs.texi(,4159)     Sticky Options:     (none)
cvs.texi(,4160) 
cvs.texi(,4161)     Existing Tags:
cvs.texi(,4162)         rel-1-0-patches             (branch: 1.4.2)
cvs.texi(,4163)         rel-1-0                     (revision: 1.4)
cvs.texi(,4164)         rel-0-4                     (revision: 1.4)
cvs.texi(,4165) 
cvs.texi(,4166) @end example
cvs.texi(,4167) 
cvs.texi(,4168) Don't be confused by the fact that the branch numbers
cvs.texi(,4169) for each file are different (@samp{1.7.2} and
cvs.texi(,4170) @samp{1.4.2} respectively).  The branch tag is the
cvs.texi(,4171) same, @samp{rel-1-0-patches}, and the files are
cvs.texi(,4172) indeed on the same branch.  The numbers simply reflect
cvs.texi(,4173) the point in each file's revision history at which the
cvs.texi(,4174) branch was made.  In the above example, one can deduce
cvs.texi(,4175) that @samp{driver.c} had been through more changes than
cvs.texi(,4176) @samp{backend.c} before this branch was created.
cvs.texi(,4177) 
cvs.texi(,4178) See @ref{Branches and revisions} for details about how
cvs.texi(,4179) branch numbers are constructed.
cvs.texi(,4180) 
cvs.texi(,4181) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,4182) @node Branches and revisions
cvs.texi(,4183) @section Branches and revisions
cvs.texi(,4184) @cindex Branch number
cvs.texi(,4185) @cindex Number, branch
cvs.texi(,4186) @cindex Revision numbers (branches)
cvs.texi(,4187) 
cvs.texi(,4188) Ordinarily, a file's revision history is a linear
cvs.texi(,4189) series of increments (@pxref{Revision numbers}):
cvs.texi(,4190) 
cvs.texi(,4191) @example
cvs.texi(,4192)        +-----+    +-----+    +-----+    +-----+    +-----+
cvs.texi(,4193)        ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
cvs.texi(,4194)        +-----+    +-----+    +-----+    +-----+    +-----+
cvs.texi(,4195) @end example
cvs.texi(,4196) 
cvs.texi(,4197) However, @sc{cvs} is not limited to linear development.  The
cvs.texi(,4198) @dfn{revision tree} can be split into @dfn{branches},
cvs.texi(,4199) where each branch is a self-maintained line of
cvs.texi(,4200) development.  Changes made on one branch can easily be
cvs.texi(,4201) moved back to the main trunk.
cvs.texi(,4202) 
cvs.texi(,4203) Each branch has a @dfn{branch number}, consisting of an
cvs.texi(,4204) odd number of period-separated decimal integers.  The
cvs.texi(,4205) branch number is created by appending an integer to the
cvs.texi(,4206) revision number where the corresponding branch forked
cvs.texi(,4207) off.  Having branch numbers allows more than one branch
cvs.texi(,4208) to be forked off from a certain revision.
cvs.texi(,4209) 
cvs.texi(,4210) @need 3500
cvs.texi(,4211) All revisions on a branch have revision numbers formed
cvs.texi(,4212) by appending an ordinal number to the branch number.
cvs.texi(,4213) The following figure illustrates branching with an
cvs.texi(,4214) example.
cvs.texi(,4215) 
cvs.texi(,4216) @example
cvs.texi(,4217) @c This example used to have a 1.2.2.4 revision, which
cvs.texi(,4218) @c might help clarify that development can continue on
cvs.texi(,4219) @c 1.2.2.  Might be worth reinstating if it can be done
cvs.texi(,4220) @c without overfull hboxes.
cvs.texi(,4221) @group
cvs.texi(,4222)                                                       +-------------+
cvs.texi(,4223)                            Branch 1.2.2.3.2 ->        ! 1.2.2.3.2.1 !
cvs.texi(,4224)                                                     / +-------------+
cvs.texi(,4225)                                                    /
cvs.texi(,4226)                                                   /
cvs.texi(,4227)                  +---------+    +---------+    +---------+
cvs.texi(,4228) Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
cvs.texi(,4229)                / +---------+    +---------+    +---------+
cvs.texi(,4230)               /
cvs.texi(,4231)              /
cvs.texi(,4232) +-----+    +-----+    +-----+    +-----+    +-----+
cvs.texi(,4233) ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !  <- The main trunk
cvs.texi(,4234) +-----+    +-----+    +-----+    +-----+    +-----+
cvs.texi(,4235)                 !
cvs.texi(,4236)                 !
cvs.texi(,4237)                 !   +---------+    +---------+    +---------+
cvs.texi(,4238) Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 !
cvs.texi(,4239)                     +---------+    +---------+    +---------+
cvs.texi(,4240) 
cvs.texi(,4241) @end group
cvs.texi(,4242) @end example
cvs.texi(,4243) 
cvs.texi(,4244) @c --   However, at least for me the figure is not enough.  I suggest more
cvs.texi(,4245) @c --   text to accompany it.  "A picture is worth a thousand words", so you
cvs.texi(,4246) @c --   have to make sure the reader notices the couple of hundred words
cvs.texi(,4247) @c --   *you* had in mind more than the others!
cvs.texi(,4248) 
cvs.texi(,4249) @c --   Why an even number of segments?  This section implies that this is
cvs.texi(,4250) @c --   how the main trunk is distinguished from branch roots, but you never
cvs.texi(,4251) @c --   explicitly say that this is the purpose of the [by itself rather
cvs.texi(,4252) @c --   surprising] restriction to an even number of segments.
cvs.texi(,4253) 
cvs.texi(,4254) The exact details of how the branch number is
cvs.texi(,4255) constructed is not something you normally need to be
cvs.texi(,4256) concerned about, but here is how it works: When
cvs.texi(,4257) @sc{cvs} creates a branch number it picks the first
cvs.texi(,4258) unused even integer, starting with 2.  So when you want
cvs.texi(,4259) to create a branch from revision 6.4 it will be
cvs.texi(,4260) numbered 6.4.2.  All branch numbers ending in a zero
cvs.texi(,4261) (such as 6.4.0) are used internally by @sc{cvs}
cvs.texi(,4262) (@pxref{Magic branch numbers}).  The branch 1.1.1 has a
cvs.texi(,4263) special meaning.  @xref{Tracking sources}.
cvs.texi(,4264) 
cvs.texi(,4265) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,4266) @node Magic branch numbers
cvs.texi(,4267) @section Magic branch numbers
cvs.texi(,4268) 
cvs.texi(,4269) @c Want xref to here from "log"?
cvs.texi(,4270) 
cvs.texi(,4271) This section describes a @sc{cvs} feature called
cvs.texi(,4272) @dfn{magic branches}.  For most purposes, you need not
cvs.texi(,4273) worry about magic branches; @sc{cvs} handles them for
cvs.texi(,4274) you.  However, they are visible to you in certain
cvs.texi(,4275) circumstances, so it may be useful to have some idea of
cvs.texi(,4276) how it works.
cvs.texi(,4277) 
cvs.texi(,4278) Externally, branch numbers consist of an odd number of
cvs.texi(,4279) dot-separated decimal integers.  @xref{Revision
cvs.texi(,4280) numbers}.  That is not the whole truth, however.  For
cvs.texi(,4281) efficiency reasons @sc{cvs} sometimes inserts an extra 0
cvs.texi(,4282) in the second rightmost position (1.2.4 becomes
cvs.texi(,4283) 1.2.0.4, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so
cvs.texi(,4284) on).
cvs.texi(,4285) 
cvs.texi(,4286) @sc{cvs} does a pretty good job at hiding these so
cvs.texi(,4287) called magic branches, but in a few places the hiding
cvs.texi(,4288) is incomplete:
cvs.texi(,4289) 
cvs.texi(,4290) @itemize @bullet
cvs.texi(,4303) @item
cvs.texi(,4304) The magic branch number appears in the output from
cvs.texi(,4305) @code{cvs log}.
cvs.texi(,4306) @c What output should appear instead?
cvs.texi(,4307) 
cvs.texi(,4308) @item
cvs.texi(,4309) You cannot specify a symbolic branch name to @code{cvs
cvs.texi(,4310) admin}.
cvs.texi(,4311) 
cvs.texi(,4312) @end itemize
cvs.texi(,4313) 
cvs.texi(,4314) @c Can CVS do this automatically the first time
cvs.texi(,4315) @c you check something in to that branch?  Should
cvs.texi(,4316) @c it?
cvs.texi(,4317) You can use the @code{admin} command to reassign a
cvs.texi(,4318) symbolic name to a branch the way @sc{rcs} expects it
cvs.texi(,4319) to be.  If @code{R4patches} is assigned to the branch
cvs.texi(,4320) 1.4.2 (magic branch number 1.4.0.2) in file
cvs.texi(,4321) @file{numbers.c} you can do this:
cvs.texi(,4322) 
cvs.texi(,4323) @example
cvs.texi(,4324) $ cvs admin -NR4patches:1.4.2 numbers.c
cvs.texi(,4325) @end example
cvs.texi(,4326) 
cvs.texi(,4327) It only works if at least one revision is already
cvs.texi(,4328) committed on the branch.  Be very careful so that you
cvs.texi(,4329) do not assign the tag to the wrong number.  (There is
cvs.texi(,4330) no way to see how the tag was assigned yesterday).
cvs.texi(,4331) 
cvs.texi(,4332) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,4333) @node Merging a branch
cvs.texi(,4334) @section Merging an entire branch
cvs.texi(,4335) @cindex Merging a branch
cvs.texi(,4336) @cindex -j (merging branches)
cvs.texi(,4337) 
cvs.texi(,4338) You can merge changes made on a branch into your working copy by giving
cvs.texi(,4339) the @samp{-j @var{branchname}} flag to the @code{update} subcommand.  With one
cvs.texi(,4340) @samp{-j @var{branchname}} option it merges the changes made between the
cvs.texi(,4341) greatest common ancestor (GCA) of the branch and the destination revision (in
cvs.texi(,4342) the simple case below the GCA is the point where the branch forked) and the
cvs.texi(,4343) newest revision on that branch into your working copy.
cvs.texi(,4344) 
cvs.texi(,4345) @cindex Join
cvs.texi(,4346) The @samp{-j} stands for ``join''.
cvs.texi(,4347) 
cvs.texi(,4348) @cindex Branch merge example
cvs.texi(,4349) @cindex Example, branch merge
cvs.texi(,4350) @cindex Merge, branch example
cvs.texi(,4351) Consider this revision tree:
cvs.texi(,4352) 
cvs.texi(,4353) @example
cvs.texi(,4354) +-----+    +-----+    +-----+    +-----+
cvs.texi(,4355) ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !      <- The main trunk
cvs.texi(,4356) +-----+    +-----+    +-----+    +-----+
cvs.texi(,4357)                 !
cvs.texi(,4358)                 !
cvs.texi(,4359)                 !   +---------+    +---------+
cvs.texi(,4360) Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
cvs.texi(,4361)                     +---------+    +---------+
cvs.texi(,4362) @end example
cvs.texi(,4363) 
cvs.texi(,4364) @noindent
cvs.texi(,4365) The branch 1.2.2 has been given the tag (symbolic name) @samp{R1fix}.  The
cvs.texi(,4366) following example assumes that the module @samp{mod} contains only one
cvs.texi(,4367) file, @file{m.c}.
cvs.texi(,4368) 
cvs.texi(,4369) @example
cvs.texi(,4370) $ cvs checkout mod               # @r{Retrieve the latest revision, 1.4}
cvs.texi(,4371) 
cvs.texi(,4372) $ cvs update -j R1fix m.c        # @r{Merge all changes made on the branch,}
cvs.texi(,4373)                                  # @r{i.e. the changes between revision 1.2}
cvs.texi(,4374)                                  # @r{and 1.2.2.2, into your working copy}
cvs.texi(,4375)                                  # @r{of the file.}
cvs.texi(,4376) 
cvs.texi(,4377) $ cvs commit -m "Included R1fix" # @r{Create revision 1.5.}
cvs.texi(,4378) @end example
cvs.texi(,4379) 
cvs.texi(,4380) A conflict can result from a merge operation.  If that
cvs.texi(,4381) happens, you should resolve it before committing the
cvs.texi(,4382) new revision.  @xref{Conflicts example}.
cvs.texi(,4383) 
cvs.texi(,4384) If your source files contain keywords (@pxref{Keyword substitution}),
cvs.texi(,4385) you might be getting more conflicts than strictly necessary.  See
cvs.texi(,4386) @ref{Merging and keywords}, for information on how to avoid this.
cvs.texi(,4387) 
cvs.texi(,4388) The @code{checkout} command also supports the @samp{-j @var{branchname}} flag.  The
cvs.texi(,4389) same effect as above could be achieved with this:
cvs.texi(,4390) 
cvs.texi(,4391) @example
cvs.texi(,4392) $ cvs checkout -j R1fix mod
cvs.texi(,4393) $ cvs commit -m "Included R1fix"
cvs.texi(,4394) @end example
cvs.texi(,4395) 
cvs.texi(,4396) It should be noted that @code{update -j @var{tagname}} will also work but may
cvs.texi(,4397) not produce the desired result.  @xref{Merging adds and removals}, for more.
cvs.texi(,4398) 
cvs.texi(,4399) @node Merging more than once
cvs.texi(,4400) @section Merging from a branch several times
cvs.texi(,4401) 
cvs.texi(,4402) Continuing our example, the revision tree now looks
cvs.texi(,4403) like this:
cvs.texi(,4404) 
cvs.texi(,4405) @example
cvs.texi(,4406) +-----+    +-----+    +-----+    +-----+    +-----+
cvs.texi(,4407) ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !   <- The main trunk
cvs.texi(,4408) +-----+    +-----+    +-----+    +-----+    +-----+
cvs.texi(,4409)                 !                           *
cvs.texi(,4410)                 !                          *
cvs.texi(,4411)                 !   +---------+    +---------+
cvs.texi(,4412) Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
cvs.texi(,4413)                     +---------+    +---------+
cvs.texi(,4414) @end example
cvs.texi(,4415) 
cvs.texi(,4416) @noindent
cvs.texi(,4417) where the starred line represents the merge from the
cvs.texi(,4418) @samp{R1fix} branch to the main trunk, as just
cvs.texi(,4419) discussed.
cvs.texi(,4420) 
cvs.texi(,4421) Now suppose that development continues on the
cvs.texi(,4422) @samp{R1fix} branch:
cvs.texi(,4423) 
cvs.texi(,4424) @example
cvs.texi(,4425) +-----+    +-----+    +-----+    +-----+    +-----+
cvs.texi(,4426) ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !   <- The main trunk
cvs.texi(,4427) +-----+    +-----+    +-----+    +-----+    +-----+
cvs.texi(,4428)                 !                           *
cvs.texi(,4429)                 !                          *
cvs.texi(,4430)                 !   +---------+    +---------+    +---------+
cvs.texi(,4431) Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
cvs.texi(,4432)                     +---------+    +---------+    +---------+
cvs.texi(,4433) @end example
cvs.texi(,4434) 
cvs.texi(,4435) @noindent
cvs.texi(,4436) and then you want to merge those new changes onto the
cvs.texi(,4437) main trunk.  If you just use the @code{cvs update -j
cvs.texi(,4438) R1fix m.c} command again, @sc{cvs} will attempt to
cvs.texi(,4439) merge again the changes which you have already merged,
cvs.texi(,4440) which can have undesirable side effects.
cvs.texi(,4441) 
cvs.texi(,4442) So instead you need to specify that you only want to
cvs.texi(,4443) merge the changes on the branch which have not yet been
cvs.texi(,4444) merged into the trunk.  To do that you specify two
cvs.texi(,4445) @samp{-j} options, and @sc{cvs} merges the changes from
cvs.texi(,4446) the first revision to the second revision.  For
cvs.texi(,4447) example, in this case the simplest way would be
cvs.texi(,4448) 
cvs.texi(,4449) @example
cvs.texi(,4450) cvs update -j 1.2.2.2 -j R1fix m.c    # @r{Merge changes from 1.2.2.2 to the}
cvs.texi(,4451)                                       # @r{head of the R1fix branch}
cvs.texi(,4452) @end example
cvs.texi(,4453) 
cvs.texi(,4454) The problem with this is that you need to specify the
cvs.texi(,4455) 1.2.2.2 revision manually.  A slightly better approach
cvs.texi(,4456) might be to use the date the last merge was done:
cvs.texi(,4457) 
cvs.texi(,4458) @example
cvs.texi(,4459) cvs update -j R1fix:yesterday -j R1fix m.c
cvs.texi(,4460) @end example
cvs.texi(,4461) 
cvs.texi(,4462) Better yet, tag the R1fix branch after every merge into
cvs.texi(,4463) the trunk, and then use that tag for subsequent merges:
cvs.texi(,4464) 
cvs.texi(,4465) @example
cvs.texi(,4466) cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c
cvs.texi(,4467) @end example
cvs.texi(,4468) 
cvs.texi(,4469) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,4470) @node Merging two revisions
cvs.texi(,4471) @section Merging differences between any two revisions
cvs.texi(,4472) @cindex Merging two revisions
cvs.texi(,4473) @cindex Revisions, merging differences between
cvs.texi(,4474) @cindex Differences, merging
cvs.texi(,4475) 
cvs.texi(,4476) With two @samp{-j @var{revision}} flags, the @code{update}
cvs.texi(,4477) (and @code{checkout}) command can merge the differences
cvs.texi(,4478) between any two revisions into your working file.
cvs.texi(,4479) 
cvs.texi(,4480) @cindex Undoing a change
cvs.texi(,4481) @cindex Removing a change
cvs.texi(,4482) @example
cvs.texi(,4483) $ cvs update -j 1.5 -j 1.3 backend.c
cvs.texi(,4484) @end example
cvs.texi(,4485) 
cvs.texi(,4486) @noindent
cvs.texi(,4487) will undo all changes made between revision
cvs.texi(,4488) 1.3 and 1.5.  Note the order of the revisions!
cvs.texi(,4489) 
cvs.texi(,4490) If you try to use this option when operating on
cvs.texi(,4491) multiple files, remember that the numeric revisions will
cvs.texi(,4492) probably be very different between the various files.
cvs.texi(,4493) You almost always use symbolic
cvs.texi(,4494) tags rather than revision numbers when operating on
cvs.texi(,4495) multiple files.
cvs.texi(,4496) 
cvs.texi(,4497) @cindex Restoring old version of removed file
cvs.texi(,4498) @cindex Resurrecting old version of dead file
cvs.texi(,4499) Specifying two @samp{-j} options can also undo file
cvs.texi(,4500) removals or additions.  For example, suppose you have
cvs.texi(,4501) a file
cvs.texi(,4502) named @file{file1} which existed as revision 1.1, and
cvs.texi(,4503) you then removed it (thus adding a dead revision 1.2).
cvs.texi(,4504) Now suppose you want to add it again, with the same
cvs.texi(,4505) contents it had previously.  Here is how to do it:
cvs.texi(,4506) 
cvs.texi(,4507) @example
cvs.texi(,4508) $ cvs update -j 1.2 -j 1.1 file1
cvs.texi(,4509) U file1
cvs.texi(,4510) $ cvs commit -m test
cvs.texi(,4511) Checking in file1;
cvs.texi(,4512) /tmp/cvs-sanity/cvsroot/first-dir/file1,v  <--  file1
cvs.texi(,4513) new revision: 1.3; previous revision: 1.2
cvs.texi(,4514) done
cvs.texi(,4515) $
cvs.texi(,4516) @end example
cvs.texi(,4517) 
cvs.texi(,4518) @node Merging adds and removals
cvs.texi(,4519) @section Merging can add or remove files
cvs.texi(,4520) 
cvs.texi(,4521) If the changes which you are merging involve removing
cvs.texi(,4522) or adding some files, @code{update -j} will reflect
cvs.texi(,4523) such additions or removals.
cvs.texi(,4524) 
cvs.texi(,4525) @c FIXME: This example needs a lot more explanation.
cvs.texi(,4526) @c We also need other examples for some of the other
cvs.texi(,4527) @c cases (not all--there are too many--as long as we present a
cvs.texi(,4528) @c coherent general principle).
cvs.texi(,4529) For example:
cvs.texi(,4530) @example
cvs.texi(,4531) cvs update -A
cvs.texi(,4532) touch a b c
cvs.texi(,4533) cvs add a b c ; cvs ci -m "added" a b c
cvs.texi(,4534) cvs tag -b branchtag
cvs.texi(,4535) cvs update -r branchtag
cvs.texi(,4536) touch d ; cvs add d
cvs.texi(,4537) rm a ; cvs rm a
cvs.texi(,4538) cvs ci -m "added d, removed a"
cvs.texi(,4539) cvs update -A
cvs.texi(,4540) cvs update -jbranchtag
cvs.texi(,4541) @end example
cvs.texi(,4542) 
cvs.texi(,4543) After these commands are executed and a @samp{cvs commit} is done,
cvs.texi(,4544) file @file{a} will be removed and file @file{d} added in the main branch.
cvs.texi(,4545) @c (which was determined by trying it)
cvs.texi(,4546) 
cvs.texi(,4547) Note that using a single static tag (@samp{-j @var{tagname}})
cvs.texi(,4548) rather than a dynamic tag (@samp{-j @var{branchname}}) to merge
cvs.texi(,4549) changes from a branch will usually not remove files which were removed on the
cvs.texi(,4550) branch since @sc{cvs} does not automatically add static tags to dead revisions.
cvs.texi(,4551) The exception to this rule occurs when
cvs.texi(,4552) a static tag has been attached to a dead revision manually.  Use the branch tag
cvs.texi(,4553) to merge all changes from the branch or use two static tags as merge endpoints
cvs.texi(,4554) to be sure that all intended changes are propagated in the merge.
cvs.texi(,4555) 
cvs.texi(,4556) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,4557) @node Merging and keywords
cvs.texi(,4558) @section Merging and keywords
cvs.texi(,4559) @cindex Merging, and keyword substitution
cvs.texi(,4560) @cindex Keyword substitution, and merging
cvs.texi(,4561) @cindex -j (merging branches), and keyword substitution
cvs.texi(,4562) @cindex -kk, to avoid conflicts during a merge
cvs.texi(,4563) 
cvs.texi(,4564) If you merge files containing keywords (@pxref{Keyword
cvs.texi(,4565) substitution}), you will normally get numerous
cvs.texi(,4566) conflicts during the merge, because the keywords are
cvs.texi(,4567) expanded differently in the revisions which you are
cvs.texi(,4568) merging.
cvs.texi(,4569) 
cvs.texi(,4570) Therefore, you will often want to specify the
cvs.texi(,4571) @samp{-kk} (@pxref{Substitution modes}) switch to the
cvs.texi(,4572) merge command line.  By substituting just the name of
cvs.texi(,4573) the keyword, not the expanded value of that keyword,
cvs.texi(,4574) this option ensures that the revisions which you are
cvs.texi(,4575) merging will be the same as each other, and avoid
cvs.texi(,4576) spurious conflicts.
cvs.texi(,4577) 
cvs.texi(,4578) For example, suppose you have a file like this:
cvs.texi(,4579) 
cvs.texi(,4580) @example
cvs.texi(,4581)        +---------+
cvs.texi(,4582)       _! 1.1.2.1 !   <-  br1
cvs.texi(,4583)      / +---------+
cvs.texi(,4584)     /
cvs.texi(,4585)    /
cvs.texi(,4586) +-----+    +-----+
cvs.texi(,4587) ! 1.1 !----! 1.2 !
cvs.texi(,4588) +-----+    +-----+
cvs.texi(,4589) @end example
cvs.texi(,4590) 
cvs.texi(,4591) @noindent
cvs.texi(,4592) and your working directory is currently on the trunk
cvs.texi(,4593) (revision 1.2).  Then you might get the following
cvs.texi(,4594) results from a merge:
cvs.texi(,4595) 
cvs.texi(,4596) @example
cvs.texi(,4597) $ cat file1
cvs.texi(splitrcskeyword,4598) key $@i{}Revision: 1.2 $
cvs.texi(,4599) . . .
cvs.texi(,4600) $ cvs update -j br1
cvs.texi(,4601) U file1
cvs.texi(,4602) RCS file: /cvsroot/first-dir/file1,v
cvs.texi(,4603) retrieving revision 1.1
cvs.texi(,4604) retrieving revision 1.1.2.1
cvs.texi(,4605) Merging differences between 1.1 and 1.1.2.1 into file1
cvs.texi(,4606) rcsmerge: warning: conflicts during merge
cvs.texi(,4607) $ cat file1
cvs.texi(,4608) @asis{}<<<<<<< file1
cvs.texi(splitrcskeyword,4609) key $@i{}Revision: 1.2 $
cvs.texi(,4610) @asis{}=======
cvs.texi(splitrcskeyword,4611) key $@i{}Revision: 1.1.2.1 $
cvs.texi(,4612) @asis{}>>>>>>> 1.1.2.1
cvs.texi(,4613) . . .
cvs.texi(,4614) @end example
cvs.texi(,4615) 
cvs.texi(,4616) What happened was that the merge tried to merge the
cvs.texi(,4617) differences between 1.1 and 1.1.2.1 into your working
cvs.texi(,4618) directory.  So, since the keyword changed from
cvs.texi(,4619) @code{Revision: 1.1} to @code{Revision: 1.1.2.1},
cvs.texi(,4620) @sc{cvs} tried to merge that change into your working
cvs.texi(,4621) directory, which conflicted with the fact that your
cvs.texi(,4622) working directory had contained @code{Revision: 1.2}.
cvs.texi(,4623) 
cvs.texi(,4624) Here is what happens if you had used @samp{-kk}:
cvs.texi(,4625) 
cvs.texi(,4626) @example
cvs.texi(,4627) $ cat file1
cvs.texi(splitrcskeyword,4628) key $@i{}Revision: 1.2 $
cvs.texi(,4629) . . .
cvs.texi(,4630) $ cvs update -kk -j br1
cvs.texi(,4631) U file1
cvs.texi(,4632) RCS file: /cvsroot/first-dir/file1,v
cvs.texi(,4633) retrieving revision 1.1
cvs.texi(,4634) retrieving revision 1.1.2.1
cvs.texi(,4635) Merging differences between 1.1 and 1.1.2.1 into file1
cvs.texi(,4636) $ cat file1
cvs.texi(splitrcskeyword,4637) key $@i{}Revision$
cvs.texi(,4638) . . .
cvs.texi(,4639) @end example
cvs.texi(,4640) 
cvs.texi(,4641) What is going on here is that revision 1.1 and 1.1.2.1
cvs.texi(,4642) both expand as plain @code{Revision}, and therefore
cvs.texi(,4643) merging the changes between them into the working
cvs.texi(,4644) directory need not change anything.  Therefore, there
cvs.texi(,4645) is no conflict.
cvs.texi(,4646) 
cvs.texi(,4647) @strong{WARNING: In versions of @sc{cvs} prior to 1.12.2, there was a
cvs.texi(,4648) major problem with using @samp{-kk} on merges.  Namely, @samp{-kk}
cvs.texi(,4649) overrode any default keyword expansion mode set in the archive file in
cvs.texi(,4650) the repository.  This could, unfortunately for some users, cause data
cvs.texi(,4651) corruption in binary files (with a default keyword expansion mode set
cvs.texi(,4652) to @samp{-kb}).  Therefore, when a repository contained binary files,
cvs.texi(,4653) conflicts had to be dealt with manually rather than using @samp{-kk} in
cvs.texi(,4654) a merge command.}
cvs.texi(,4655) 
cvs.texi(,4656) In @sc{cvs} version 1.12.2 and later, the keyword expansion mode
cvs.texi(,4657) provided on the command line to any @sc{cvs} command no longer
cvs.texi(,4658) overrides the @samp{-kb} keyword expansion mode setting for binary
cvs.texi(,4659) files, though it will still override other default keyword expansion
cvs.texi(,4660) modes.  You can now safely merge using @samp{-kk} to avoid spurious conflicts
cvs.texi(,4661) on lines containing RCS keywords, even when your repository contains
cvs.texi(,4662) binary files.
cvs.texi(,4663) 
cvs.texi(,4664) @c ---------------------------------------------------------------------
cvs.texi(,4665) @node Recursive behavior
cvs.texi(,4666) @chapter Recursive behavior
cvs.texi(,4667) @cindex Recursive (directory descending)
cvs.texi(,4668) @cindex Directory, descending
cvs.texi(,4669) @cindex Descending directories
cvs.texi(,4670) @cindex Subdirectories
cvs.texi(,4671) 
cvs.texi(,4672) Almost all of the subcommands of @sc{cvs} work
cvs.texi(,4673) recursively when you specify a directory as an
cvs.texi(,4674) argument.  For instance, consider this directory
cvs.texi(,4675) structure:
cvs.texi(,4676) 
cvs.texi(,4677) @example
cvs.texi(,4678)       @code{$HOME}
cvs.texi(,4679)         |
cvs.texi(,4680)         +--@t{tc}
cvs.texi(,4681)         |   |
cvs.texi(,4682)             +--@t{CVS}
cvs.texi(,4683)             |      (internal @sc{cvs} files)
cvs.texi(,4684)             +--@t{Makefile}
cvs.texi(,4685)             +--@t{backend.c}
cvs.texi(,4686)             +--@t{driver.c}
cvs.texi(,4687)             +--@t{frontend.c}
cvs.texi(,4688)             +--@t{parser.c}
cvs.texi(,4689)             +--@t{man}
cvs.texi(,4690)             |    |
cvs.texi(,4691)             |    +--@t{CVS}
cvs.texi(,4692)             |    |  (internal @sc{cvs} files)
cvs.texi(,4693)             |    +--@t{tc.1}
cvs.texi(,4694)             |
cvs.texi(,4695)             +--@t{testing}
cvs.texi(,4696)                  |
cvs.texi(,4697)                  +--@t{CVS}
cvs.texi(,4698)                  |  (internal @sc{cvs} files)
cvs.texi(,4699)                  +--@t{testpgm.t}
cvs.texi(,4700)                  +--@t{test2.t}
cvs.texi(,4701) @end example
cvs.texi(,4702) 
cvs.texi(,4703) @noindent
cvs.texi(,4704) If @file{tc} is the current working directory, the
cvs.texi(,4705) following is true:
cvs.texi(,4706) 
cvs.texi(,4707) @itemize @bullet
cvs.texi(,4708) @item
cvs.texi(,4709) @samp{cvs update testing} is equivalent to
cvs.texi(,4710) 
cvs.texi(,4711) @example
cvs.texi(,4712) cvs update testing/testpgm.t testing/test2.t
cvs.texi(,4713) @end example
cvs.texi(,4714) 
cvs.texi(,4715) @item
cvs.texi(,4716) @samp{cvs update testing man} updates all files in the
cvs.texi(,4717) subdirectories
cvs.texi(,4718) 
cvs.texi(,4719) @item
cvs.texi(,4720) @samp{cvs update .} or just @samp{cvs update} updates
cvs.texi(,4721) all files in the @code{tc} directory
cvs.texi(,4722) @end itemize
cvs.texi(,4723) 
cvs.texi(,4724) If no arguments are given to @code{update} it will
cvs.texi(,4725) update all files in the current working directory and
cvs.texi(,4726) all its subdirectories.  In other words, @file{.} is a
cvs.texi(,4727) default argument to @code{update}.  This is also true
cvs.texi(,4728) for most of the @sc{cvs} subcommands, not only the
cvs.texi(,4729) @code{update} command.
cvs.texi(,4730) 
cvs.texi(,4731) The recursive behavior of the @sc{cvs} subcommands can be
cvs.texi(,4732) turned off with the @samp{-l} option.
cvs.texi(,4733) Conversely, the @samp{-R} option can be used to force recursion if
cvs.texi(,4734) @samp{-l} is specified in @file{~/.cvsrc} (@pxref{~/.cvsrc}).
cvs.texi(,4735) 
cvs.texi(,4736) @example
cvs.texi(,4737) $ cvs update -l         # @r{Don't update files in subdirectories}
cvs.texi(,4738) @end example
cvs.texi(,4739) 
cvs.texi(,4740) @c ---------------------------------------------------------------------
cvs.texi(,4741) @node Adding and removing
cvs.texi(,4742) @chapter Adding, removing, and renaming files and directories
cvs.texi(,4743) 
cvs.texi(,4744) In the course of a project, one will often add new
cvs.texi(,4745) files.  Likewise with removing or renaming, or with
cvs.texi(,4746) directories.  The general concept to keep in mind in
cvs.texi(,4747) all these cases is that instead of making an
cvs.texi(,4748) irreversible change you want @sc{cvs} to record the
cvs.texi(,4749) fact that a change has taken place, just as with
cvs.texi(,4750) modifying an existing file.  The exact mechanisms to do
cvs.texi(,4751) this in @sc{cvs} vary depending on the situation.
cvs.texi(,4752) 
cvs.texi(,4753) @menu
cvs.texi(,4754) * Adding files::                Adding files
cvs.texi(,4755) * Removing files::              Removing files
cvs.texi(,4756) * Removing directories::        Removing directories
cvs.texi(,4757) * Moving files::                Moving and renaming files
cvs.texi(,4758) * Moving directories::          Moving and renaming directories
cvs.texi(,4759) @end menu
cvs.texi(,4760) 
cvs.texi(,4761) @node Adding files
cvs.texi(,4762) @section Adding files to a directory
cvs.texi(,4763) @cindex Adding files
cvs.texi(,4764) 
cvs.texi(,4765) To add a new file to a directory, follow these steps.
cvs.texi(,4766) 
cvs.texi(,4767) @itemize @bullet
cvs.texi(,4768) @item
cvs.texi(,4769) You must have a working copy of the directory.
cvs.texi(,4770) @xref{Getting the source}.
cvs.texi(,4771) 
cvs.texi(,4772) @item
cvs.texi(,4773) Create the new file inside your working copy of the directory.
cvs.texi(,4774) 
cvs.texi(,4775) @item
cvs.texi(,4776) Use @samp{cvs add @var{filename}} to tell @sc{cvs} that you
cvs.texi(,4777) want to version control the file.  If the file contains
cvs.texi(,4778) binary data, specify @samp{-kb} (@pxref{Binary files}).
cvs.texi(,4779) 
cvs.texi(,4780) @item
cvs.texi(,4781) Use @samp{cvs commit @var{filename}} to actually check
cvs.texi(,4782) in the file into the repository.  Other developers
cvs.texi(,4783) cannot see the file until you perform this step.
cvs.texi(,4784) @end itemize
cvs.texi(,4785) 
cvs.texi(,4786) You can also use the @code{add} command to add a new
cvs.texi(,4787) directory.
cvs.texi(,4788) @c FIXCVS and/or FIXME: Adding a directory doesn't
cvs.texi(,4789) @c require the commit step.  This probably can be
cvs.texi(,4790) @c considered a CVS bug, but it is possible we should
cvs.texi(,4791) @c warn people since this behavior probably won't be
cvs.texi(,4792) @c changing right away.
cvs.texi(,4793) 
cvs.texi(,4794) Unlike most other commands, the @code{add} command is
cvs.texi(,4795) not recursive.  You cannot even type @samp{cvs add
cvs.texi(,4796) foo/bar}!  Instead, you have to
cvs.texi(,4797) @c FIXCVS: This is, of course, not a feature.  It is
cvs.texi(,4798) @c just that no one has gotten around to fixing "cvs add
cvs.texi(,4799) @c foo/bar".
cvs.texi(,4800) 
cvs.texi(,4801) @example
cvs.texi(,4802) $ cd foo
cvs.texi(,4803) $ cvs add bar
cvs.texi(,4804) @end example
cvs.texi(,4805) 
cvs.texi(,4806) @cindex add (subcommand)
cvs.texi(,4807) @deffn Command {cvs add} [@code{-k} kflag] [@code{-m} message] files @dots{}
cvs.texi(,4808) 
cvs.texi(,4809) Schedule @var{files} to be added to the repository.
cvs.texi(,4810) The files or directories specified with @code{add} must
cvs.texi(,4811) already exist in the current directory.  To add a whole
cvs.texi(,4812) new directory hierarchy to the source repository (for
cvs.texi(,4813) example, files received from a third-party vendor), use
cvs.texi(,4814) the @code{import} command instead.  @xref{import}.
cvs.texi(,4815) 
cvs.texi(,4816) The added files are not placed in the source repository
cvs.texi(,4817) until you use @code{commit} to make the change
cvs.texi(,4818) permanent.  Doing an @code{add} on a file that was
cvs.texi(,4819) removed with the @code{remove} command will undo the
cvs.texi(,4820) effect of the @code{remove}, unless a @code{commit}
cvs.texi(,4821) command intervened.  @xref{Removing files}, for an
cvs.texi(,4822) example.
cvs.texi(,4823) 
cvs.texi(,4824) The @samp{-k} option specifies the default way that
cvs.texi(,4825) this file will be checked out; for more information see
cvs.texi(,4826) @ref{Substitution modes}.
cvs.texi(,4827) 
cvs.texi(,4828) @c As noted in BUGS, -m is broken client/server (Nov
cvs.texi(,4829) @c 96).  Also see testsuite log2-* tests.
cvs.texi(,4830) The @samp{-m} option specifies a description for the
cvs.texi(,4831) file.  This description appears in the history log (if
cvs.texi(,4832) it is enabled, @pxref{history file}).  It will also be
cvs.texi(,4833) saved in the version history inside the repository when
cvs.texi(,4834) the file is committed.  The @code{log} command displays
cvs.texi(,4835) this description.  The description can be changed using
cvs.texi(,4836) @samp{admin -t}.  @xref{admin}.  If you omit the
cvs.texi(,4837) @samp{-m @var{description}} flag, an empty string will
cvs.texi(,4838) be used.  You will not be prompted for a description.
cvs.texi(,4839) @end deffn
cvs.texi(,4840) 
cvs.texi(,4841) For example, the following commands add the file
cvs.texi(,4842) @file{backend.c} to the repository:
cvs.texi(,4843) 
cvs.texi(,4844) @c This example used to specify
cvs.texi(,4845) @c     -m "Optimizer and code generation passes."
cvs.texi(,4846) @c to the cvs add command, but that doesn't work
cvs.texi(,4847) @c client/server (see log2 in sanity.sh).  Should fix CVS,
cvs.texi(,4848) @c but also seems strange to document things which
cvs.texi(,4849) @c don't work...
cvs.texi(,4850) @example
cvs.texi(,4851) $ cvs add backend.c
cvs.texi(,4852) $ cvs commit -m "Early version. Not yet compilable." backend.c
cvs.texi(,4853) @end example
cvs.texi(,4854) 
cvs.texi(,4855) When you add a file it is added only on the branch
cvs.texi(,4856) which you are working on (@pxref{Branching and merging}).  You can
cvs.texi(,4857) later merge the additions to another branch if you want
cvs.texi(,4858) (@pxref{Merging adds and removals}).
cvs.texi(,4859) @c Should we mention that earlier versions of CVS
cvs.texi(,4860) @c lacked this feature (1.3) or implemented it in a buggy
cvs.texi(,4861) @c way (well, 1.8 had many bugs in cvs update -j)?
cvs.texi(,4862) @c Should we mention the bug/limitation regarding a
cvs.texi(,4863) @c file being a regular file on one branch and a directory
cvs.texi(,4864) @c on another?
cvs.texi(,4865) @c FIXME: This needs an example, or several, here or
cvs.texi(,4866) @c elsewhere, for it to make much sense.
cvs.texi(,4867) @c Somewhere we need to discuss the aspects of death
cvs.texi(,4868) @c support which don't involve branching, I guess.
cvs.texi(,4869) @c Like the ability to re-create a release from a tag.
cvs.texi(,4870) 
cvs.texi(,4871) @c ---------------------------------------------------------------------
cvs.texi(,4872) @node Removing files
cvs.texi(,4873) @section Removing files
cvs.texi(,4874) @cindex Removing files
cvs.texi(,4875) @cindex Deleting files
cvs.texi(,4876) 
cvs.texi(,4877) @c FIXME: this node wants to be split into several
cvs.texi(,4878) @c smaller nodes.  Could make these children of
cvs.texi(,4879) @c "Adding and removing", probably (death support could
cvs.texi(,4880) @c be its own section, for example, as could the
cvs.texi(,4881) @c various bits about undoing mistakes in adding and
cvs.texi(,4882) @c removing).
cvs.texi(,4883) Directories change.  New files are added, and old files
cvs.texi(,4884) disappear.  Still, you want to be able to retrieve an
cvs.texi(,4885) exact copy of old releases.
cvs.texi(,4886) 
cvs.texi(,4887) Here is what you can do to remove a file,
cvs.texi(,4888) but remain able to retrieve old revisions:
cvs.texi(,4889) 
cvs.texi(,4890) @itemize @bullet
cvs.texi(,4891) @c FIXME: should probably be saying something about
cvs.texi(,4892) @c having a working directory in the first place.
cvs.texi(,4893) @item
cvs.texi(,4894) Make sure that you have not made any uncommitted
cvs.texi(,4895) modifications to the file.  @xref{Viewing differences},
cvs.texi(,4896) for one way to do that.  You can also use the
cvs.texi(,4897) @code{status} or @code{update} command.  If you remove
cvs.texi(,4898) the file without committing your changes, you will of
cvs.texi(,4899) course not be able to retrieve the file as it was
cvs.texi(,4900) immediately before you deleted it.
cvs.texi(,4901) 
cvs.texi(,4902) @item
cvs.texi(,4903) Remove the file from your working copy of the directory.
cvs.texi(,4904) You can for instance use @code{rm}.
cvs.texi(,4905) 
cvs.texi(,4906) @item
cvs.texi(,4907) Use @samp{cvs remove @var{filename}} to tell @sc{cvs} that
cvs.texi(,4908) you really want to delete the file.
cvs.texi(,4909) 
cvs.texi(,4910) @item
cvs.texi(,4911) Use @samp{cvs commit @var{filename}} to actually
cvs.texi(,4912) perform the removal of the file from the repository.
cvs.texi(,4913) @end itemize
cvs.texi(,4914) 
cvs.texi(,4915) @c FIXME: Somehow this should be linked in with a more
cvs.texi(,4916) @c general discussion of death support.  I don't know
cvs.texi(,4917) @c whether we want to use the term "death support" or
cvs.texi(,4918) @c not (we can perhaps get by without it), but we do
cvs.texi(,4919) @c need to discuss the "dead" state in "cvs log" and
cvs.texi(,4920) @c related subjects.  The current discussion is
cvs.texi(,4921) @c scattered around, and not xref'd to each other.
cvs.texi(,4922) @c FIXME: I think this paragraph wants to be moved
cvs.texi(,4923) @c later down, at least after the first example.
cvs.texi(,4924) When you commit the removal of the file, @sc{cvs}
cvs.texi(,4925) records the fact that the file no longer exists.  It is
cvs.texi(,4926) possible for a file to exist on only some branches and
cvs.texi(,4927) not on others, or to re-add another file with the same
cvs.texi(,4928) name later.  @sc{cvs} will correctly create or not create
cvs.texi(,4929) the file, based on the @samp{-r} and @samp{-D} options
cvs.texi(,4930) specified to @code{checkout} or @code{update}.
cvs.texi(,4931) 
cvs.texi(,4932) @c FIXME: This style seems to clash with how we
cvs.texi(,4933) @c document things in general.
cvs.texi(,4934) @cindex Remove (subcommand)
cvs.texi(,4935) @deffn Command {cvs remove} [options] files @dots{}
cvs.texi(,4936) 
cvs.texi(,4937) Schedule file(s) to be removed from the repository
cvs.texi(,4938) (files which have not already been removed from the
cvs.texi(,4939) working directory are not processed).  This command
cvs.texi(,4940) does not actually remove the file from the repository
cvs.texi(,4941) until you commit the removal.  For a full list of
cvs.texi(,4942) options, see @ref{Invoking CVS}.
cvs.texi(,4943) @end deffn
cvs.texi(,4944) 
cvs.texi(,4945) Here is an example of removing several files:
cvs.texi(,4946) 
cvs.texi(,4947) @example
cvs.texi(,4948) $ cd test
cvs.texi(,4949) $ rm *.c
cvs.texi(,4950) $ cvs remove
cvs.texi(,4951) cvs remove: Removing .
cvs.texi(,4952) cvs remove: scheduling a.c for removal
cvs.texi(,4953) cvs remove: scheduling b.c for removal
cvs.texi(,4954) cvs remove: use 'cvs commit' to remove these files permanently
cvs.texi(,4955) $ cvs ci -m "Removed unneeded files"
cvs.texi(,4956) cvs commit: Examining .
cvs.texi(,4957) cvs commit: Committing .
cvs.texi(,4958) @end example
cvs.texi(,4959) 
cvs.texi(,4960) As a convenience you can remove the file and @code{cvs
cvs.texi(,4961) remove} it in one step, by specifying the @samp{-f}
cvs.texi(,4962) option.  For example, the above example could also be
cvs.texi(,4963) done like this:
cvs.texi(,4964) 
cvs.texi(,4965) @example
cvs.texi(,4966) $ cd test
cvs.texi(,4967) $ cvs remove -f *.c
cvs.texi(,4968) cvs remove: scheduling a.c for removal
cvs.texi(,4969) cvs remove: scheduling b.c for removal
cvs.texi(,4970) cvs remove: use 'cvs commit' to remove these files permanently
cvs.texi(,4971) $ cvs ci -m "Removed unneeded files"
cvs.texi(,4972) cvs commit: Examining .
cvs.texi(,4973) cvs commit: Committing .
cvs.texi(,4974) @end example
cvs.texi(,4975) 
cvs.texi(,4976) If you execute @code{remove} for a file, and then
cvs.texi(,4977) change your mind before you commit, you can undo the
cvs.texi(,4978) @code{remove} with an @code{add} command.
cvs.texi(,4989) 
cvs.texi(,4990) @c FIXME: what if you change your mind after you commit
cvs.texi(,4991) @c it?  (answer is also "cvs add" but we don't say that...).
cvs.texi(,4992) @c We need some index entries for thinks like "undoing
cvs.texi(,4993) @c removal" too.
cvs.texi(,4994) 
cvs.texi(,4995) @example
cvs.texi(,4996) $ ls
cvs.texi(,4997) CVS   ja.h  oj.c
cvs.texi(,4998) $ rm oj.c
cvs.texi(,4999) $ cvs remove oj.c
cvs.texi(,5000) cvs remove: scheduling oj.c for removal
cvs.texi(,5001) cvs remove: use 'cvs commit' to remove this file permanently
cvs.texi(,5002) $ cvs add oj.c
cvs.texi(,5003) U oj.c
cvs.texi(,5004) cvs add: oj.c, version 1.1.1.1, resurrected
cvs.texi(,5005) @end example
cvs.texi(,5006) 
cvs.texi(,5007) If you realize your mistake before you run the
cvs.texi(,5008) @code{remove} command you can use @code{update} to
cvs.texi(,5009) resurrect the file:
cvs.texi(,5010) 
cvs.texi(,5011) @example
cvs.texi(,5012) $ rm oj.c
cvs.texi(,5013) $ cvs update oj.c
cvs.texi(,5014) cvs update: warning: oj.c was lost
cvs.texi(,5015) U oj.c
cvs.texi(,5016) @end example
cvs.texi(,5017) 
cvs.texi(,5018) When you remove a file it is removed only on the branch
cvs.texi(,5019) which you are working on (@pxref{Branching and merging}).  You can
cvs.texi(,5020) later merge the removals to another branch if you want
cvs.texi(,5021) (@pxref{Merging adds and removals}).
cvs.texi(,5022) 
cvs.texi(,5023) @node Removing directories
cvs.texi(,5024) @section Removing directories
cvs.texi(,5025) @cindex Removing directories
cvs.texi(,5026) @cindex Directories, removing
cvs.texi(,5027) 
cvs.texi(,5028) In concept removing directories is somewhat similar to
cvs.texi(,5029) removing files---you want the directory to not exist in
cvs.texi(,5030) your current working directories, but you also want to
cvs.texi(,5031) be able to retrieve old releases in which the directory
cvs.texi(,5032) existed.
cvs.texi(,5033) 
cvs.texi(,5034) The way that you remove a directory is to remove all
cvs.texi(,5035) the files in it.  You don't remove the directory
cvs.texi(,5036) itself; there is no way to do that.
cvs.texi(,5037) Instead you specify the @samp{-P} option to
cvs.texi(,5038) @code{cvs update} or @code{cvs checkout},
cvs.texi(,5039) which will cause @sc{cvs} to remove empty
cvs.texi(,5040) directories from working directories.
cvs.texi(,5041) (Note that @code{cvs export} always removes empty directories.)
cvs.texi(,5042) Probably the
cvs.texi(,5043) best way to do this is to always specify @samp{-P}; if
cvs.texi(,5044) you want an empty directory then put a dummy file (for
cvs.texi(,5045) example @file{.keepme}) in it to prevent @samp{-P} from
cvs.texi(,5046) removing it.
cvs.texi(,5047) 
cvs.texi(,5048) @c I'd try to give a rationale for this, but I'm not
cvs.texi(,5049) @c sure there is a particularly convincing one.  What
cvs.texi(,5050) @c we would _like_ is for CVS to do a better job of version
cvs.texi(,5051) @c controlling whether directories exist, to eliminate the
cvs.texi(,5052) @c need for -P and so that a file can be a directory in
cvs.texi(,5053) @c one revision and a regular file in another.
cvs.texi(,5054) Note that @samp{-P} is implied by the @samp{-r} or @samp{-D}
cvs.texi(,5055) options of @code{checkout}.  This way
cvs.texi(,5056) @sc{cvs} will be able to correctly create the directory
cvs.texi(,5057) or not depending on whether the particular version you
cvs.texi(,5058) are checking out contains any files in that directory.
cvs.texi(,5059) 
cvs.texi(,5060) @c ---------------------------------------------------------------------
cvs.texi(,5061) @node Moving files
cvs.texi(,5062) @section Moving and renaming files
cvs.texi(,5063) @cindex Moving files
cvs.texi(,5064) @cindex Renaming files
cvs.texi(,5065) @cindex Files, moving
cvs.texi(,5066) 
cvs.texi(,5067) Moving files to a different directory or renaming them
cvs.texi(,5068) is not difficult, but some of the ways in which this
cvs.texi(,5069) works may be non-obvious.  (Moving or renaming a
cvs.texi(,5070) directory is even harder.  @xref{Moving directories}.).
cvs.texi(,5071) 
cvs.texi(,5072) The examples below assume that the file @var{old} is renamed to
cvs.texi(,5073) @var{new}.
cvs.texi(,5074) 
cvs.texi(,5075) @menu
cvs.texi(,5076) * Outside::                     The normal way to Rename
cvs.texi(,5077) * Inside::                      A tricky, alternative way
cvs.texi(,5078) * Rename by copying::           Another tricky, alternative way
cvs.texi(,5079) @end menu
cvs.texi(,5080) 
cvs.texi(,5081) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,5082) @node Outside
cvs.texi(,5083) @subsection The Normal way to Rename
cvs.texi(,5084) 
cvs.texi(,5085) @c More rename issues.  Not sure whether these are
cvs.texi(,5086) @c worth documenting; I'm putting them here because
cvs.texi(,5087) @c it seems to be as good a place as any to try to
cvs.texi(,5088) @c set down the issues.
cvs.texi(,5089) @c * "cvs annotate" will annotate either the new
cvs.texi(,5090) @c file or the old file; it cannot annotate _each
cvs.texi(,5091) @c line_ based on whether it was last changed in the
cvs.texi(,5092) @c new or old file.  Unlike "cvs log", where the
cvs.texi(,5093) @c consequences of having to select either the new
cvs.texi(,5094) @c or old name seem fairly benign, this may be a
cvs.texi(,5095) @c real advantage to having CVS know about renames
cvs.texi(,5096) @c other than as a deletion and an addition.
cvs.texi(,5097) 
cvs.texi(,5098) The normal way to move a file is to copy @var{old} to
cvs.texi(,5099) @var{new}, and then issue the normal @sc{cvs} commands
cvs.texi(,5100) to remove @var{old} from the repository, and add
cvs.texi(,5101) @var{new} to it.
cvs.texi(,5102) @c The following sentence is not true: one must cd into
cvs.texi(,5103) @c the directory to run "cvs add".
cvs.texi(,5104) @c  (Both @var{old} and @var{new} could
cvs.texi(,5105) @c contain relative paths, for example @file{foo/bar.c}).
cvs.texi(,5106) 
cvs.texi(,5107) @example
cvs.texi(,5108) $ mv @var{old} @var{new}
cvs.texi(,5109) $ cvs remove @var{old}
cvs.texi(,5110) $ cvs add @var{new}
cvs.texi(,5111) $ cvs commit -m "Renamed @var{old} to @var{new}" @var{old} @var{new}
cvs.texi(,5112) @end example
cvs.texi(,5113) 
cvs.texi(,5114) This is the simplest way to move a file, it is not
cvs.texi(,5115) error-prone, and it preserves the history of what was
cvs.texi(,5116) done.  Note that to access the history of the file you
cvs.texi(,5117) must specify the old or the new name, depending on what
cvs.texi(,5118) portion of the history you are accessing.  For example,
cvs.texi(,5119) @code{cvs log @var{old}} will give the log up until the
cvs.texi(,5120) time of the rename.
cvs.texi(,5121) 
cvs.texi(,5122) When @var{new} is committed its revision numbers will
cvs.texi(,5123) start again, usually at 1.1, so if that bothers you,
cvs.texi(,5124) use the @samp{-r rev} option to commit.  For more
cvs.texi(,5125) information see @ref{Assigning revisions}.
cvs.texi(,5126) 
cvs.texi(,5127) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,5128) @node Inside
cvs.texi(,5129) @subsection Moving the history file
cvs.texi(,5130) 
cvs.texi(,5131) This method is more dangerous, since it involves moving
cvs.texi(,5132) files inside the repository.  Read this entire section
cvs.texi(,5133) before trying it out!
cvs.texi(,5134) 
cvs.texi(,5135) @example
cvs.texi(,5136) $ cd $CVSROOT/@var{dir}
cvs.texi(,5137) $ mv @var{old},v @var{new},v
cvs.texi(,5138) @end example
cvs.texi(,5139) 
cvs.texi(,5140) @noindent
cvs.texi(,5141) Advantages:
cvs.texi(,5142) 
cvs.texi(,5143) @itemize @bullet
cvs.texi(,5144) @item
cvs.texi(,5145) The log of changes is maintained intact.
cvs.texi(,5146) 
cvs.texi(,5147) @item
cvs.texi(,5148) The revision numbers are not affected.
cvs.texi(,5149) @end itemize
cvs.texi(,5150) 
cvs.texi(,5151) @noindent
cvs.texi(,5152) Disadvantages:
cvs.texi(,5153) 
cvs.texi(,5154) @itemize @bullet
cvs.texi(,5155) @item
cvs.texi(,5156) Old releases cannot easily be fetched from the
cvs.texi(,5157) repository.  (The file will show up as @var{new} even
cvs.texi(,5158) in revisions from the time before it was renamed).
cvs.texi(,5159) 
cvs.texi(,5160) @item
cvs.texi(,5161) There is no log information of when the file was renamed.
cvs.texi(,5162) 
cvs.texi(,5163) @item
cvs.texi(,5164) Nasty things might happen if someone accesses the history file
cvs.texi(,5165) while you are moving it.  Make sure no one else runs any of the @sc{cvs}
cvs.texi(,5166) commands while you move it.
cvs.texi(,5167) @end itemize
cvs.texi(,5168) 
cvs.texi(,5169) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,5170) @node Rename by copying
cvs.texi(,5171) @subsection Copying the history file
cvs.texi(,5172) 
cvs.texi(,5173) This way also involves direct modifications to the
cvs.texi(,5174) repository.  It is safe, but not without drawbacks.
cvs.texi(,5175) 
cvs.texi(,5176) @example
cvs.texi(,5177) # @r{Copy the @sc{rcs} file inside the repository}
cvs.texi(,5178) $ cd $CVSROOT/@var{dir}
cvs.texi(,5179) $ cp @var{old},v @var{new},v
cvs.texi(,5180) # @r{Remove the old file}
cvs.texi(,5181) $ cd ~/@var{dir}
cvs.texi(,5182) $ rm @var{old}
cvs.texi(,5183) $ cvs remove @var{old}
cvs.texi(,5184) $ cvs commit @var{old}
cvs.texi(,5185) # @r{Remove all tags from @var{new}}
cvs.texi(,5186) $ cvs update @var{new}
cvs.texi(,5187) $ cvs log @var{new}             # @r{Remember the non-branch tag names}
cvs.texi(,5188) $ cvs tag -d @var{tag1} @var{new}
cvs.texi(,5189) $ cvs tag -d @var{tag2} @var{new}
cvs.texi(,5190) @dots{}
cvs.texi(,5191) @end example
cvs.texi(,5192) 
cvs.texi(,5193) By removing the tags you will be able to check out old
cvs.texi(,5194) revisions.
cvs.texi(,5195) 
cvs.texi(,5196) @noindent
cvs.texi(,5197) Advantages:
cvs.texi(,5198) 
cvs.texi(,5199) @itemize @bullet
cvs.texi(,5200) @item
cvs.texi(,5201) @c FIXME: Is this true about -D now that we have death
cvs.texi(,5202) @c support?  See 5B.3 in the FAQ.
cvs.texi(,5203) Checking out old revisions works correctly, as long as
cvs.texi(,5204) you use @samp{-r@var{tag}} and not @samp{-D@var{date}}
cvs.texi(,5205) to retrieve the revisions.
cvs.texi(,5206) 
cvs.texi(,5207) @item
cvs.texi(,5208) The log of changes is maintained intact.
cvs.texi(,5209) 
cvs.texi(,5210) @item
cvs.texi(,5211) The revision numbers are not affected.
cvs.texi(,5212) @end itemize
cvs.texi(,5213) 
cvs.texi(,5214) @noindent
cvs.texi(,5215) Disadvantages:
cvs.texi(,5216) 
cvs.texi(,5217) @itemize @bullet
cvs.texi(,5218) @item
cvs.texi(,5219) You cannot easily see the history of the file across the rename.
cvs.texi(,5220) 
cvs.texi(,5233) @end itemize
cvs.texi(,5234) 
cvs.texi(,5235) @c ---------------------------------------------------------------------
cvs.texi(,5236) @node Moving directories
cvs.texi(,5237) @section Moving and renaming directories
cvs.texi(,5238) @cindex Moving directories
cvs.texi(,5239) @cindex Renaming directories
cvs.texi(,5240) @cindex Directories, moving
cvs.texi(,5241) 
cvs.texi(,5242) The normal way to rename or move a directory is to
cvs.texi(,5243) rename or move each file within it as described in
cvs.texi(,5244) @ref{Outside}.  Then check out with the @samp{-P}
cvs.texi(,5245) option, as described in @ref{Removing directories}.
cvs.texi(,5246) 
cvs.texi(,5247) If you really want to hack the repository to rename or
cvs.texi(,5248) delete a directory in the repository, you can do it
cvs.texi(,5249) like this:
cvs.texi(,5250) 
cvs.texi(,5251) @enumerate
cvs.texi(,5252) @item
cvs.texi(,5253) Inform everyone who has a checked out copy of the directory that the
cvs.texi(,5254) directory will be renamed.  They should commit all
cvs.texi(,5255) their changes, and remove their working copies,
cvs.texi(,5256) before you take the steps below.
cvs.texi(,5257) 
cvs.texi(,5258) @item
cvs.texi(,5259) Rename the directory inside the repository.
cvs.texi(,5260) 
cvs.texi(,5261) @example
cvs.texi(,5262) $ cd $CVSROOT/@var{parent-dir}
cvs.texi(,5263) $ mv @var{old-dir} @var{new-dir}
cvs.texi(,5264) @end example
cvs.texi(,5265) 
cvs.texi(,5266) @item
cvs.texi(,5267) Fix the @sc{cvs} administrative files, if necessary (for
cvs.texi(,5268) instance if you renamed an entire module).
cvs.texi(,5269) 
cvs.texi(,5270) @item
cvs.texi(,5271) Tell everyone that they can check out again and continue
cvs.texi(,5272) working.
cvs.texi(,5273) 
cvs.texi(,5274) @end enumerate
cvs.texi(,5275) 
cvs.texi(,5276) If someone had a working copy the @sc{cvs} commands will
cvs.texi(,5277) cease to work for him, until he removes the directory
cvs.texi(,5278) that disappeared inside the repository.
cvs.texi(,5279) 
cvs.texi(,5280) It is almost always better to move the files in the
cvs.texi(,5281) directory instead of moving the directory.  If you move the
cvs.texi(,5282) directory you are unlikely to be able to retrieve old
cvs.texi(,5283) releases correctly, since they probably depend on the
cvs.texi(,5284) name of the directories.
cvs.texi(,5285) 
cvs.texi(,5286) @c ---------------------------------------------------------------------
cvs.texi(,5287) @node History browsing
cvs.texi(,5288) @chapter History browsing
cvs.texi(,5289) @cindex History browsing
cvs.texi(,5290) @cindex Traceability
cvs.texi(,5291) @cindex Isolation
cvs.texi(,5292) 
cvs.texi(,5344) 
cvs.texi(,5345) @c kind of lame, in a lot of ways the above text inside
cvs.texi(,5346) @c the @ignore motivates this chapter better
cvs.texi(,5347) Once you have used @sc{cvs} to store a version control
cvs.texi(,5348) history---what files have changed when, how, and by
cvs.texi(,5349) whom, there are a variety of mechanisms for looking
cvs.texi(,5350) through the history.
cvs.texi(,5351) 
cvs.texi(,5352) @c FIXME: should also be talking about how you look at
cvs.texi(,5353) @c old revisions (e.g. "cvs update -p -r 1.2 foo.c").
cvs.texi(,5354) @menu
cvs.texi(,5355) * log messages::                Log messages
cvs.texi(,5356) * history database::            The history database
cvs.texi(,5357) * user-defined logging::        User-defined logging
cvs.texi(,5358) * annotate::                    What revision modified each line of a file?
cvs.texi(,5359) @end menu
cvs.texi(,5360) 
cvs.texi(,5361) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,5362) @node log messages
cvs.texi(,5363) @section Log messages
cvs.texi(,5364) 
cvs.texi(,5365) @c FIXME: @xref to place where we talk about how to
cvs.texi(,5366) @c specify message to commit.
cvs.texi(,5367) Whenever you commit a file you specify a log message.
cvs.texi(,5368) 
cvs.texi(,5369) @c FIXME: bring the information here, and get rid of or
cvs.texi(,5370) @c greatly shrink the "log" node.
cvs.texi(,5371) To look through the log messages which have been
cvs.texi(,5372) specified for every revision which has been committed,
cvs.texi(,5373) use the @code{cvs log} command (@pxref{log}).
cvs.texi(,5374) 
cvs.texi(,5375) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,5376) @node history database
cvs.texi(,5377) @section The history database
cvs.texi(,5378) 
cvs.texi(,5379) @c FIXME: bring the information from the history file
cvs.texi(,5380) @c and history nodes here.  Rewrite it to be motivated
cvs.texi(,5381) @c better (start out by clearly explaining what gets
cvs.texi(,5382) @c logged in history, for example).
cvs.texi(,5383) You can use the history file (@pxref{history file}) to
cvs.texi(,5384) log various @sc{cvs} actions.  To retrieve the
cvs.texi(,5385) information from the history file, use the @code{cvs
cvs.texi(,5386) history} command (@pxref{history}).
cvs.texi(,5387) 
cvs.texi(,5388) Note: you can control what is logged to this file by using the
cvs.texi(,5389) @samp{LogHistory} keyword in the @file{CVSROOT/config} file
cvs.texi(,5390) (@pxref{config}).
cvs.texi(,5391) 
cvs.texi(,5392) @c
cvs.texi(,5393) @c The history database has many problems:
cvs.texi(,5394) @c * It is very unclear what field means what.  This
cvs.texi(,5395) @c could be improved greatly by better documentation,
cvs.texi(,5396) @c but there are still non-orthogonalities (for
cvs.texi(,5397) @c example, tag does not record the "repository"
cvs.texi(,5398) @c field but most records do).
cvs.texi(,5399) @c * Confusion about files, directories, and modules.
cvs.texi(,5400) @c Some commands record one, some record others.
cvs.texi(,5401) @c * File removal is not logged.  There is an 'R'
cvs.texi(,5402) @c record type documented, but CVS never uses it.
cvs.texi(,5403) @c * Tags are only logged for the "cvs rtag" command,
cvs.texi(,5404) @c not "cvs tag".  The fix for this is not completely
cvs.texi(,5405) @c clear (see above about modules vs. files).
cvs.texi(,5406) @c * Are there other cases of operations that are not
cvs.texi(,5407) @c logged?  One would hope for all changes to the
cvs.texi(,5408) @c repository to be logged somehow (particularly
cvs.texi(,5409) @c operations like tagging, "cvs admin -k", and other
cvs.texi(,5410) @c operations which do not record a history that one
cvs.texi(,5411) @c can get with "cvs log").  Operations on the working
cvs.texi(,5412) @c directory, like export, get, and release, are a
cvs.texi(,5413) @c second category also covered by the current "cvs
cvs.texi(,5414) @c history".
cvs.texi(,5415) @c * The history file does not record the options given
cvs.texi(,5416) @c to a command.  The most serious manifestation of
cvs.texi(,5417) @c this is perhaps that it doesn't record whether a command
cvs.texi(,5418) @c was recursive.  It is not clear to me whether one
cvs.texi(,5419) @c wants to log at a level very close to the command
cvs.texi(,5420) @c line, as a sort of way of logging each command
cvs.texi(,5421) @c (more or less), or whether one wants
cvs.texi(,5422) @c to log more at the level of what was changed (or
cvs.texi(,5423) @c something in between), but either way the current
cvs.texi(,5424) @c information has pretty big gaps.
cvs.texi(,5425) @c * Further details about a tag--like whether it is a
cvs.texi(,5426) @c branch tag or, if a non-branch tag, which branch it
cvs.texi(,5427) @c is on.  One can find out this information about the
cvs.texi(,5428) @c tag as it exists _now_, but if the tag has been
cvs.texi(,5429) @c moved, one doesn't know what it was like at the time
cvs.texi(,5430) @c the history record was written.
cvs.texi(,5431) @c * Whether operating on a particular tag, date, or
cvs.texi(,5432) @c options was implicit (sticky) or explicit.
cvs.texi(,5433) @c
cvs.texi(,5434) @c Another item, only somewhat related to the above, is a
cvs.texi(,5435) @c way to control what is logged in the history file.
cvs.texi(,5436) @c This is probably the only good way to handle
cvs.texi(,5437) @c different people having different ideas about
cvs.texi(,5438) @c information/space tradeoffs.
cvs.texi(,5439) @c
cvs.texi(,5440) @c It isn't really clear that it makes sense to try to
cvs.texi(,5441) @c patch up the history file format as it exists now to
cvs.texi(,5442) @c include all that stuff.  It might be better to
cvs.texi(,5443) @c design a whole new CVSROOT/nhistory file and "cvs
cvs.texi(,5444) @c nhistory" command, or some such, or in some other
cvs.texi(,5445) @c way trying to come up with a clean break from the
cvs.texi(,5446) @c past, which can address the above concerns.  Another
cvs.texi(,5447) @c open question is how/whether this relates to
cvs.texi(,5448) @c taginfo/loginfo/etc.
cvs.texi(,5449) 
cvs.texi(,5450) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,5451) @node user-defined logging
cvs.texi(,5452) @section User-defined logging
cvs.texi(,5453) 
cvs.texi(,5454) @c FIXME: should probably also mention the fact the -l
cvs.texi(,5455) @c global option can disable most of the mechanisms
cvs.texi(,5456) @c discussed here (why?  What is the -l global option for?).
cvs.texi(,5457) @c
cvs.texi(,5458) @c FIXME: probably should centralize this information
cvs.texi(,5459) @c here, at least to some extent.  Maybe by moving the
cvs.texi(,5460) @c loginfo, etc., nodes here and replacing
cvs.texi(,5461) @c the "user-defined logging" node with one node for
cvs.texi(,5462) @c each method.
cvs.texi(,5463) You can customize @sc{cvs} to log various kinds of
cvs.texi(,5464) actions, in whatever manner you choose.  These
cvs.texi(,5465) mechanisms operate by executing a script at various
cvs.texi(,5466) times.  The script might append a message to a file
cvs.texi(,5467) listing the information and the programmer who created
cvs.texi(,5468) it, or send mail to a group of developers, or, perhaps,
cvs.texi(,5469) post a message to a particular newsgroup.  To log
cvs.texi(,5470) commits, use the @file{loginfo} file (@pxref{loginfo}).
cvs.texi(,5471) @c FIXME: What is difference between doing it in the
cvs.texi(,5472) @c modules file and using loginfo/taginfo?  Why should
cvs.texi(,5473) @c user use one or the other?
cvs.texi(,5474) To log commits, checkouts, exports, and tags,
cvs.texi(,5475) respectively, you can also use the @samp{-i},
cvs.texi(,5476) @samp{-o}, @samp{-e}, and @samp{-t} options in the
cvs.texi(,5477) modules file.  For a more flexible way of giving
cvs.texi(,5478) notifications to various users, which requires less in
cvs.texi(,5479) the way of keeping centralized scripts up to date, use
cvs.texi(,5480) the @code{cvs watch add} command (@pxref{Getting
cvs.texi(,5481) Notified}); this command is useful even if you are not
cvs.texi(,5482) using @code{cvs watch on}.
cvs.texi(,5483) 
cvs.texi(,5484) @cindex taginfo
cvs.texi(,5485) @cindex Exit status, of taginfo
cvs.texi(,5486) The @file{taginfo} file defines programs to execute
cvs.texi(,5487) when someone executes a @code{tag} or @code{rtag}
cvs.texi(,5488) command.  The @file{taginfo} file has the standard form
cvs.texi(,5489) for administrative files (@pxref{Administrative
cvs.texi(,5490) files}), where each line is a regular expression
cvs.texi(,5491) followed by a command to execute.  The arguments passed
cvs.texi(,5492) to the command are, in order, the @var{tagname},
cvs.texi(,5493) @var{operation} (@code{add} for @code{tag},
cvs.texi(,5494) @code{mov} for @code{tag -F}, and @code{del} for
cvs.texi(,5495) @code{tag -d}), @var{repository}, and any remaining are
cvs.texi(,5496) pairs of @var{filename} @var{revision}.  A non-zero
cvs.texi(,5497) exit of the filter program will cause the tag to be
cvs.texi(,5498) aborted.
cvs.texi(,5499) 
cvs.texi(,5500) Here is an example of using taginfo to log tag and rtag
cvs.texi(,5501) commands.  In the taginfo file put:
cvs.texi(,5502) 
cvs.texi(,5503) @example
cvs.texi(,5504) ALL /usr/local/cvsroot/CVSROOT/loggit
cvs.texi(,5505) @end example
cvs.texi(,5506) 
cvs.texi(,5507) @noindent
cvs.texi(,5508) Where @file{/usr/local/cvsroot/CVSROOT/loggit} contains the
cvs.texi(,5509) following script:
cvs.texi(,5510) 
cvs.texi(,5511) @example
cvs.texi(,5512) #!/bin/sh
cvs.texi(,5513) echo "$@@" >>/home/kingdon/cvsroot/CVSROOT/taglog
cvs.texi(,5514) @end example
cvs.texi(,5515) 
cvs.texi(,5516) @node annotate
cvs.texi(,5517) @section Annotate command
cvs.texi(,5518) @cindex annotate (subcommand)
cvs.texi(,5519) 
cvs.texi(,5520) @deffn Command {cvs annotate} [@code{-FflR}] [@code{-r rev}|@code{-D date}] files @dots{}
cvs.texi(,5521) 
cvs.texi(,5522) For each file in @var{files}, print the head revision
cvs.texi(,5523) of the trunk, together with information on the last
cvs.texi(,5524) modification for each line.  For example:
cvs.texi(,5525) 
cvs.texi(,5526) @example
cvs.texi(,5527) $ cvs annotate ssfile
cvs.texi(,5528) Annotations for ssfile
cvs.texi(,5529) ***************
cvs.texi(,5530) 1.1          (mary     27-Mar-96): ssfile line 1
cvs.texi(,5531) 1.2          (joe      28-Mar-96): ssfile line 2
cvs.texi(,5532) @end example
cvs.texi(,5533) 
cvs.texi(,5534) The file @file{ssfile} currently contains two lines.
cvs.texi(,5535) The @code{ssfile line 1} line was checked in by
cvs.texi(,5536) @code{mary} on March 27.  Then, on March 28, @code{joe}
cvs.texi(,5537) added a line @code{ssfile line 2}, without modifying
cvs.texi(,5538) the @code{ssfile line 1} line.  This report doesn't
cvs.texi(,5539) tell you anything about lines which have been deleted
cvs.texi(,5540) or replaced; you need to use @code{cvs diff} for that
cvs.texi(,5541) (@pxref{diff}).
cvs.texi(,5542) 
cvs.texi(,5543) @end deffn
cvs.texi(,5544) 
cvs.texi(,5545) The options to @code{cvs annotate} are listed in
cvs.texi(,5546) @ref{Invoking CVS}, and can be used to select the files
cvs.texi(,5547) and revisions to annotate.  The options are described
cvs.texi(,5548) in more detail there and in @ref{Common options}.
cvs.texi(,5549) 
cvs.texi(,5550) @c FIXME: maybe an example using the options?  Just
cvs.texi(,5551) @c what it means to select a revision might be worth a
cvs.texi(,5552) @c few words of explanation ("you want to see who
cvs.texi(,5553) @c changed this line *before* 1.4"...).
cvs.texi(,5554) 
cvs.texi(,5555) @c ---------------------------------------------------------------------
cvs.texi(,5556) @node Binary files
cvs.texi(,5557) @chapter Handling binary files
cvs.texi(,5558) @cindex Binary files
cvs.texi(,5559) 
cvs.texi(,5560) The most common use for @sc{cvs} is to store text
cvs.texi(,5561) files.  With text files, @sc{cvs} can merge revisions,
cvs.texi(,5562) display the differences between revisions in a
cvs.texi(,5563) human-visible fashion, and other such operations.
cvs.texi(,5564) However, if you are willing to give up a few of these
cvs.texi(,5565) abilities, @sc{cvs} can store binary files.  For
cvs.texi(,5566) example, one might store a web site in @sc{cvs}
cvs.texi(,5567) including both text files and binary images.
cvs.texi(,5568) 
cvs.texi(,5569) @menu
cvs.texi(,5570) * Binary why::     More details on issues with binary files
cvs.texi(,5571) * Binary howto::   How to store them
cvs.texi(,5572) @end menu
cvs.texi(,5573) 
cvs.texi(,5574) @node Binary why
cvs.texi(,5575) @section The issues with binary files
cvs.texi(,5576) 
cvs.texi(,5577) While the need to manage binary files may seem obvious
cvs.texi(,5578) if the files that you customarily work with are binary,
cvs.texi(,5579) putting them into version control does present some
cvs.texi(,5580) additional issues.
cvs.texi(,5581) 
cvs.texi(,5582) One basic function of version control is to show the
cvs.texi(,5583) differences between two revisions.  For example, if
cvs.texi(,5584) someone else checked in a new version of a file, you
cvs.texi(,5585) may wish to look at what they changed and determine
cvs.texi(,5586) whether their changes are good.  For text files,
cvs.texi(,5587) @sc{cvs} provides this functionality via the @code{cvs
cvs.texi(,5588) diff} command.  For binary files, it may be possible to
cvs.texi(,5589) extract the two revisions and then compare them with a
cvs.texi(,5590) tool external to @sc{cvs} (for example, word processing
cvs.texi(,5591) software often has such a feature).  If there is no
cvs.texi(,5592) such tool, one must track changes via other mechanisms,
cvs.texi(,5593) such as urging people to write good log messages, and
cvs.texi(,5594) hoping that the changes they actually made were the
cvs.texi(,5595) changes that they intended to make.
cvs.texi(,5596) 
cvs.texi(,5597) Another ability of a version control system is the
cvs.texi(,5598) ability to merge two revisions.  For @sc{cvs} this
cvs.texi(,5599) happens in two contexts.  The first is when users make
cvs.texi(,5600) changes in separate working directories
cvs.texi(,5601) (@pxref{Multiple developers}).  The second is when one
cvs.texi(,5602) merges explicitly with the @samp{update -j} command
cvs.texi(,5603) (@pxref{Branching and merging}).
cvs.texi(,5604) 
cvs.texi(,5605) In the case of text
cvs.texi(,5606) files, @sc{cvs} can merge changes made independently,
cvs.texi(,5607) and signal a conflict if the changes conflict.  With
cvs.texi(,5608) binary files, the best that @sc{cvs} can do is present
cvs.texi(,5609) the two different copies of the file, and leave it to
cvs.texi(,5610) the user to resolve the conflict.  The user may choose
cvs.texi(,5611) one copy or the other, or may run an external merge
cvs.texi(,5612) tool which knows about that particular file format, if
cvs.texi(,5613) one exists.
cvs.texi(,5614) Note that having the user merge relies primarily on the
cvs.texi(,5615) user to not accidentally omit some changes, and thus is
cvs.texi(,5616) potentially error prone.
cvs.texi(,5617) 
cvs.texi(,5618) If this process is thought to be undesirable, the best
cvs.texi(,5619) choice may be to avoid merging.  To avoid the merges
cvs.texi(,5620) that result from separate working directories, see the
cvs.texi(,5621) discussion of reserved checkouts (file locking) in
cvs.texi(,5622) @ref{Multiple developers}.  To avoid the merges
cvs.texi(,5623) resulting from branches, restrict use of branches.
cvs.texi(,5624) 
cvs.texi(,5625) @node Binary howto
cvs.texi(,5626) @section How to store binary files
cvs.texi(,5627) 
cvs.texi(,5628) There are two issues with using @sc{cvs} to store
cvs.texi(,5629) binary files.  The first is that @sc{cvs} by default
cvs.texi(,5630) converts line endings between the canonical form in
cvs.texi(,5631) which they are stored in the repository (linefeed
cvs.texi(,5632) only), and the form appropriate to the operating system
cvs.texi(,5633) in use on the client (for example, carriage return
cvs.texi(,5634) followed by line feed for Windows NT).
cvs.texi(,5635) 
cvs.texi(,5636) The second is that a binary file might happen to
cvs.texi(,5637) contain data which looks like a keyword (@pxref{Keyword
cvs.texi(,5638) substitution}), so keyword expansion must be turned
cvs.texi(,5639) off.
cvs.texi(,5640) 
cvs.texi(,5641) @c FIXME: the third is that one can't do merges with
cvs.texi(,5642) @c binary files.  xref to Multiple Developers and the
cvs.texi(,5643) @c reserved checkout issues.
cvs.texi(,5644) 
cvs.texi(,5645) The @samp{-kb} option available with some @sc{cvs}
cvs.texi(,5646) commands insures that neither line ending conversion
cvs.texi(,5647) nor keyword expansion will be done.
cvs.texi(,5648) 
cvs.texi(,5649) Here is an example of how you can create a new file
cvs.texi(,5650) using the @samp{-kb} flag:
cvs.texi(,5651) 
cvs.texi(,5652) @example
cvs.texi(splitrcskeyword,5653) $ echo '$@i{}Id$' > kotest
cvs.texi(,5654) $ cvs add -kb -m"A test file" kotest
cvs.texi(,5655) $ cvs ci -m"First checkin; contains a keyword" kotest
cvs.texi(,5656) @end example
cvs.texi(,5657) 
cvs.texi(,5658) If a file accidentally gets added without @samp{-kb},
cvs.texi(,5659) one can use the @code{cvs admin} command to recover.
cvs.texi(,5660) For example:
cvs.texi(,5661) 
cvs.texi(,5662) @example
cvs.texi(splitrcskeyword,5663) $ echo '$@i{}Id$' > kotest
cvs.texi(,5664) $ cvs add -m"A test file" kotest
cvs.texi(,5665) $ cvs ci -m"First checkin; contains a keyword" kotest
cvs.texi(,5666) $ cvs admin -kb kotest
cvs.texi(,5667) $ cvs update -A kotest
cvs.texi(,5668) # @r{For non-unix systems:}
cvs.texi(,5669) # @r{Copy in a good copy of the file from outside CVS}
cvs.texi(,5670) $ cvs commit -m "make it binary" kotest
cvs.texi(,5671) @end example
cvs.texi(,5672) 
cvs.texi(,5673) @c Trying to describe this for both unix and non-unix
cvs.texi(,5674) @c in the same description is very confusing.  Might
cvs.texi(,5675) @c want to split the two, or just ditch the unix "shortcut"
cvs.texi(,5676) @c (unixheads don't do much with binary files, anyway).
cvs.texi(,5677) @c This used to say "(Try the above example, and do a
cvs.texi(,5678) @c @code{cat kotest} after every command)".  But that
cvs.texi(,5679) @c only really makes sense for the unix case.
cvs.texi(,5680) When you check in the file @file{kotest} the file is
cvs.texi(,5681) not preserved as a binary file, because you did not
cvs.texi(,5682) check it in as a binary file.  The @code{cvs
cvs.texi(,5683) admin -kb} command sets the default keyword
cvs.texi(,5684) substitution method for this file, but it does not
cvs.texi(,5685) alter the working copy of the file that you have.  If you need to
cvs.texi(,5686) cope with line endings (that is, you are using
cvs.texi(,5687) @sc{cvs} on a non-unix system), then you need to
cvs.texi(,5688) check in a new copy of the file, as shown by the
cvs.texi(,5689) @code{cvs commit} command above.
cvs.texi(,5690) On unix, the @code{cvs update -A} command suffices.
cvs.texi(,5691) @c FIXME: should also describe what the *other users*
cvs.texi(,5692) @c need to do, if they have checked out copies which
cvs.texi(,5693) @c have been corrupted by lack of -kb.  I think maybe
cvs.texi(,5694) @c "cvs update -kb" or "cvs
cvs.texi(,5695) @c update -A" would suffice, although the user who
cvs.texi(,5696) @c reported this suggested removing the file, manually
cvs.texi(,5697) @c removing it from CVS/Entries, and then "cvs update"
cvs.texi(,5698) (Note that you can use @code{cvs log} to determine the default keyword
cvs.texi(,5699) substitution method for a file and @code{cvs status} to determine
cvs.texi(,5700) the keyword substitution method for a working copy.)
cvs.texi(,5701) 
cvs.texi(,5702) However, in using @code{cvs admin -k} to change the
cvs.texi(,5703) keyword expansion, be aware that the keyword expansion
cvs.texi(,5704) mode is not version controlled.  This means that, for
cvs.texi(,5705) example, that if you have a text file in old releases,
cvs.texi(,5706) and a binary file with the same name in new releases,
cvs.texi(,5707) @sc{cvs} provides no way to check out the file in text
cvs.texi(,5708) or binary mode depending on what version you are
cvs.texi(,5709) checking out.  There is no good workaround for this
cvs.texi(,5710) problem.
cvs.texi(,5711) 
cvs.texi(,5712) You can also set a default for whether @code{cvs add}
cvs.texi(,5713) and @code{cvs import} treat a file as binary based on
cvs.texi(,5714) its name; for example you could say that files who
cvs.texi(,5715) names end in @samp{.exe} are binary.  @xref{Wrappers}.
cvs.texi(,5716) There is currently no way to have @sc{cvs} detect
cvs.texi(,5717) whether a file is binary based on its contents.  The
cvs.texi(,5718) main difficulty with designing such a feature is that
cvs.texi(,5719) it is not clear how to distinguish between binary and
cvs.texi(,5720) non-binary files, and the rules to apply would vary
cvs.texi(,5721) considerably with the operating system.
cvs.texi(,5722) @c For example, it would be good on MS-DOS-family OSes
cvs.texi(,5723) @c for anything containing ^Z to be binary.  Having
cvs.texi(,5724) @c characters with the 8th bit set imply binary is almost
cvs.texi(,5725) @c surely a bad idea in the context of ISO-8859-* and
cvs.texi(,5726) @c other such character sets.  On VMS or the Mac, we
cvs.texi(,5727) @c could use the OS's file typing.  This is a
cvs.texi(,5728) @c commonly-desired feature, and something of this sort
cvs.texi(,5729) @c may make sense.  But there are a lot of pitfalls here.
cvs.texi(,5730) @c
cvs.texi(,5731) @c Another, probably better, way to tell is to read the
cvs.texi(,5732) @c file in text mode, write it to a temp file in text
cvs.texi(,5733) @c mode, and then do a binary mode compare of the two
cvs.texi(,5734) @c files.  If they differ, it is a binary file.  This
cvs.texi(,5735) @c might have problems on VMS (or some other system
cvs.texi(,5736) @c with several different text modes), but in general
cvs.texi(,5737) @c should be relatively portable.  The only other
cvs.texi(,5738) @c downside I can think of is that it would be fairly
cvs.texi(,5739) @c slow, but that is perhaps a small price to pay for
cvs.texi(,5740) @c not having your files corrupted.  Another issue is
cvs.texi(,5741) @c what happens if you import a text file with bare
cvs.texi(,5742) @c linefeeds on Windows.  Such files will show up on
cvs.texi(,5743) @c Windows sometimes (I think some native windows
cvs.texi(,5744) @c programs even write them, on occasion).  Perhaps it
cvs.texi(,5745) @c is reasonable to treat such files as binary; after
cvs.texi(,5746) @c all it is something of a presumption to assume that
cvs.texi(,5747) @c the user would want the linefeeds converted to CRLF.
cvs.texi(,5748) 
cvs.texi(,5749) @c ---------------------------------------------------------------------
cvs.texi(,5750) @node Multiple developers
cvs.texi(,5751) @chapter Multiple developers
cvs.texi(,5752) @cindex Multiple developers
cvs.texi(,5753) @cindex Team of developers
cvs.texi(,5754) @cindex File locking
cvs.texi(,5755) @cindex Locking files
cvs.texi(,5756) @cindex Working copy
cvs.texi(,5757) @cindex Reserved checkouts
cvs.texi(,5758) @cindex Unreserved checkouts
cvs.texi(,5759) @cindex RCS-style locking
cvs.texi(,5760) 
cvs.texi(,5761) When more than one person works on a software project
cvs.texi(,5762) things often get complicated.  Often, two people try to
cvs.texi(,5763) edit the same file simultaneously.  One solution, known
cvs.texi(,5764) as @dfn{file locking} or @dfn{reserved checkouts}, is
cvs.texi(,5765) to allow only one person to edit each file at a time.
cvs.texi(,5766) This is the only solution with some version control
cvs.texi(,5767) systems, including @sc{rcs} and @sc{sccs}.  Currently
cvs.texi(,5768) the usual way to get reserved checkouts with @sc{cvs}
cvs.texi(,5769) is the @code{cvs admin -l} command (@pxref{admin
cvs.texi(,5770) options}).  This is not as nicely integrated into
cvs.texi(,5771) @sc{cvs} as the watch features, described below, but it
cvs.texi(,5772) seems that most people with a need for reserved
cvs.texi(,5773) checkouts find it adequate.
cvs.texi(,5774) @c Or "find it better than worrying about implementing
cvs.texi(,5775) @c nicely integrated reserved checkouts" or ...?
cvs.texi(,5776) It also may be possible to use the watches
cvs.texi(,5777) features described below, together with suitable
cvs.texi(,5778) procedures (not enforced by software), to avoid having
cvs.texi(,5779) two people edit at the same time.
cvs.texi(,5780) 
cvs.texi(,5781) @c Our unreserved checkout model might not
cvs.texi(,5782) @c be quite the same as others.  For example, I
cvs.texi(,5783) @c think that some systems will tend to create a branch
cvs.texi(,5784) @c in the case where CVS prints "up-to-date check failed".
cvs.texi(,5785) @c It isn't clear to me whether we should try to
cvs.texi(,5786) @c explore these subtleties; it could easily just
cvs.texi(,5787) @c confuse people.
cvs.texi(,5788) The default model with @sc{cvs} is known as
cvs.texi(,5789) @dfn{unreserved checkouts}.  In this model, developers
cvs.texi(,5790) can edit their own @dfn{working copy} of a file
cvs.texi(,5791) simultaneously.  The first person that commits his
cvs.texi(,5792) changes has no automatic way of knowing that another
cvs.texi(,5793) has started to edit it.  Others will get an error
cvs.texi(,5794) message when they try to commit the file.  They must
cvs.texi(,5795) then use @sc{cvs} commands to bring their working copy
cvs.texi(,5796) up to date with the repository revision.  This process
cvs.texi(,5797) is almost automatic.
cvs.texi(,5798) 
cvs.texi(,5799) @c FIXME? should probably use the word "watch" here, to
cvs.texi(,5800) @c tie this into the text below and above.
cvs.texi(,5801) @sc{cvs} also supports mechanisms which facilitate
cvs.texi(,5802) various kinds of communication, without actually
cvs.texi(,5803) enforcing rules like reserved checkouts do.
cvs.texi(,5804) 
cvs.texi(,5805) The rest of this chapter describes how these various
cvs.texi(,5806) models work, and some of the issues involved in
cvs.texi(,5807) choosing between them.
cvs.texi(,5808) 
cvs.texi(,5886) 
cvs.texi(,5887) @menu
cvs.texi(,5888) * File status::                 A file can be in several states
cvs.texi(,5889) * Updating a file::             Bringing a file up-to-date
cvs.texi(,5890) * Conflicts example::           An informative example
cvs.texi(,5891) * Informing others::            To cooperate you must inform
cvs.texi(,5892) * Concurrency::                 Simultaneous repository access
cvs.texi(,5893) * Watches::                     Mechanisms to track who is editing files
cvs.texi(,5894) * Choosing a model::            Reserved or unreserved checkouts?
cvs.texi(,5895) @end menu
cvs.texi(,5896) 
cvs.texi(,5897) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,5898) @node File status
cvs.texi(,5899) @section File status
cvs.texi(,5900) @cindex File status
cvs.texi(,5901) @cindex Status of a file
cvs.texi(,5902) 
cvs.texi(,5903) @c Shouldn't this start with an example or something,
cvs.texi(,5904) @c introducing the unreserved checkout model?  Before we
cvs.texi(,5905) @c dive into listing states?
cvs.texi(,5906) Based on what operations you have performed on a
cvs.texi(,5907) checked out file, and what operations others have
cvs.texi(,5908) performed to that file in the repository, one can
cvs.texi(,5909) classify a file in a number of states.  The states, as
cvs.texi(,5910) reported by the @code{status} command, are:
cvs.texi(,5911) 
cvs.texi(,5912) @c The order of items is chosen to group logically
cvs.texi(,5913) @c similar outputs together.
cvs.texi(,5914) @c People who want alphabetical can use the index...
cvs.texi(,5915) @table @asis
cvs.texi(,5916) @cindex Up-to-date
cvs.texi(,5917) @item Up-to-date
cvs.texi(,5918) The file is identical with the latest revision in the
cvs.texi(,5919) repository for the branch in use.
cvs.texi(,5920) @c FIXME: should we clarify "in use"?  The answer is
cvs.texi(,5921) @c sticky tags, and trying to distinguish branch sticky
cvs.texi(,5922) @c tags from non-branch sticky tags seems rather awkward
cvs.texi(,5923) @c here.
cvs.texi(,5924) @c FIXME: What happens with non-branch sticky tags?  Is
cvs.texi(,5925) @c a stuck file "Up-to-date" or "Needs checkout" or what?
cvs.texi(,5926) 
cvs.texi(,5927) @item Locally Modified
cvs.texi(,5928) @cindex Locally Modified
cvs.texi(,5929) You have edited the file, and not yet committed your changes.
cvs.texi(,5930) 
cvs.texi(,5931) @item Locally Added
cvs.texi(,5932) @cindex Locally Added
cvs.texi(,5933) You have added the file with @code{add}, and not yet
cvs.texi(,5934) committed your changes.
cvs.texi(,5935) @c There are many cases involving the file being
cvs.texi(,5936) @c added/removed/modified in the working directory, and
cvs.texi(,5937) @c added/removed/modified in the repository, which we
cvs.texi(,5938) @c don't try to describe here.  I'm not sure that "cvs
cvs.texi(,5939) @c status" produces a non-confusing output in most of
cvs.texi(,5940) @c those cases.
cvs.texi(,5941) 
cvs.texi(,5942) @item Locally Removed
cvs.texi(,5943) @cindex Locally Removed
cvs.texi(,5944) You have removed the file with @code{remove}, and not yet
cvs.texi(,5945) committed your changes.
cvs.texi(,5946) 
cvs.texi(,5947) @item Needs Checkout
cvs.texi(,5948) @cindex Needs Checkout
cvs.texi(,5949) Someone else has committed a newer revision to the
cvs.texi(,5950) repository.  The name is slightly misleading; you will
cvs.texi(,5951) ordinarily use @code{update} rather than
cvs.texi(,5952) @code{checkout} to get that newer revision.
cvs.texi(,5953) 
cvs.texi(,5954) @item Needs Patch
cvs.texi(,5955) @cindex Needs Patch
cvs.texi(,5956) @c See also newb-123j0 in sanity.sh (although that case
cvs.texi(,5957) @c should probably be changed rather than documented).
cvs.texi(,5958) Like Needs Checkout, but the @sc{cvs} server will send
cvs.texi(,5959) a patch rather than the entire file.  Sending a patch or
cvs.texi(,5960) sending an entire file accomplishes the same thing.
cvs.texi(,5961) 
cvs.texi(,5962) @item Needs Merge
cvs.texi(,5963) @cindex Needs Merge
cvs.texi(,5964) Someone else has committed a newer revision to the repository, and you
cvs.texi(,5965) have also made modifications to the file.
cvs.texi(,5966) 
cvs.texi(,5967) @item Unresolved Conflict
cvs.texi(,5968) @cindex Unresolved Conflict
cvs.texi(,5969) @c FIXCVS - This file status needs to be changed to some more informative
cvs.texi(,5970) @c text that distinguishes it more clearly from each of the Locally Added,
cvs.texi(,5971) @c File had conflicts on merge, and Unknown status types, but an exact and
cvs.texi(,5972) @c succinct wording escapes me at the moment.
cvs.texi(,5973) A file with the same name as this new file has been added to the repository
cvs.texi(,5974) from a second workspace.  This file will need to be moved out of the way
cvs.texi(,5975) to allow an @code{update} to complete.
cvs.texi(,5976) 
cvs.texi(,5977) @item File had conflicts on merge
cvs.texi(,5978) @cindex File had conflicts on merge
cvs.texi(,5979) @c is it worth saying that this message was "Unresolved
cvs.texi(,5980) @c Conflict" in CVS 1.9 and earlier?  I'm inclined to
cvs.texi(,5981) @c think that is unnecessarily confusing to new users.
cvs.texi(,5982) This is like Locally Modified, except that a previous
cvs.texi(,5983) @code{update} command gave a conflict.  If you have not
cvs.texi(,5984) already done so, you need to
cvs.texi(,5985) resolve the conflict as described in @ref{Conflicts example}.
cvs.texi(,5986) 
cvs.texi(,5987) @item Unknown
cvs.texi(,5988) @cindex Unknown
cvs.texi(,5989) @sc{cvs} doesn't know anything about this file.  For
cvs.texi(,5990) example, you have created a new file and have not run
cvs.texi(,5991) @code{add}.
cvs.texi(,5992) @c
cvs.texi(,5993) @c "Entry Invalid" and "Classify Error" are also in the
cvs.texi(,5994) @c status.c.  The latter definitely indicates a CVS bug
cvs.texi(,5995) @c (should it be worded more like "internal error" so
cvs.texi(,5996) @c people submit bug reports if they see it?).  The former
cvs.texi(,5997) @c I'm not as sure; I haven't tracked down whether/when it
cvs.texi(,5998) @c appears in "cvs status" output.
cvs.texi(,5999) 
cvs.texi(,6000) @end table
cvs.texi(,6001) 
cvs.texi(,6002) To help clarify the file status, @code{status} also
cvs.texi(,6003) reports the @code{Working revision} which is the
cvs.texi(,6004) revision that the file in the working directory derives
cvs.texi(,6005) from, and the @code{Repository revision} which is the
cvs.texi(,6006) latest revision in the repository for the branch in
cvs.texi(,6007) use.
cvs.texi(,6008) @c FIXME: should we clarify "in use"?  The answer is
cvs.texi(,6009) @c sticky tags, and trying to distinguish branch sticky
cvs.texi(,6010) @c tags from non-branch sticky tags seems rather awkward
cvs.texi(,6011) @c here.
cvs.texi(,6012) @c FIXME: What happens with non-branch sticky tags?
cvs.texi(,6013) @c What is the Repository Revision there?  See the
cvs.texi(,6014) @c comment at vn_rcs in cvs.h, which is kind of
cvs.texi(,6015) @c confused--we really need to document better what this
cvs.texi(,6016) @c field contains.
cvs.texi(,6017) @c Q: Should we document "New file!" and other such
cvs.texi(,6018) @c outputs or are they self-explanatory?
cvs.texi(,6019) @c FIXME: what about the date to the right of "Working
cvs.texi(,6020) @c revision"?  It doesn't appear with client/server and
cvs.texi(,6021) @c seems unnecessary (redundant with "ls -l") so
cvs.texi(,6022) @c perhaps it should be removed for non-client/server too?
cvs.texi(,6023) @c FIXME: Need some examples.
cvs.texi(,6024) @c FIXME: Working revision can also be something like
cvs.texi(,6025) @c "-1.3" for a locally removed file.  Not at all
cvs.texi(,6026) @c self-explanatory (and it is possible that CVS should
cvs.texi(,6027) @c be changed rather than documenting this).
cvs.texi(,6028) 
cvs.texi(,6029) @c Would be nice to have an @example showing output
cvs.texi(,6030) @c from cvs status, with comments showing the xref
cvs.texi(,6031) @c where each part of the output is described.  This
cvs.texi(,6032) @c might fit in nicely if it is desirable to split this
cvs.texi(,6033) @c node in two; one to introduce "cvs status" and one
cvs.texi(,6034) @c to list each of the states.
cvs.texi(,6035) The options to @code{status} are listed in
cvs.texi(,6036) @ref{Invoking CVS}.  For information on its @code{Sticky tag}
cvs.texi(,6037) and @code{Sticky date} output, see @ref{Sticky tags}.
cvs.texi(,6038) For information on its @code{Sticky options} output,
cvs.texi(,6039) see the @samp{-k} option in @ref{update options}.
cvs.texi(,6040) 
cvs.texi(,6041) You can think of the @code{status} and @code{update}
cvs.texi(,6042) commands as somewhat complementary.  You use
cvs.texi(,6043) @code{update} to bring your files up to date, and you
cvs.texi(,6044) can use @code{status} to give you some idea of what an
cvs.texi(,6045) @code{update} would do (of course, the state of the
cvs.texi(,6046) repository might change before you actually run
cvs.texi(,6047) @code{update}).  In fact, if you want a command to
cvs.texi(,6048) display file status in a more brief format than is
cvs.texi(,6049) displayed by the @code{status} command, you can invoke
cvs.texi(,6050) 
cvs.texi(,6051) @cindex update, to display file status
cvs.texi(,6052) @example
cvs.texi(,6053) $ cvs -n -q update
cvs.texi(,6054) @end example
cvs.texi(,6055) 
cvs.texi(,6056) The @samp{-n} option means to not actually do the
cvs.texi(,6057) update, but merely to display statuses; the @samp{-q}
cvs.texi(,6058) option avoids printing the name of each directory.  For
cvs.texi(,6059) more information on the @code{update} command, and
cvs.texi(,6060) these options, see @ref{Invoking CVS}.
cvs.texi(,6061) 
cvs.texi(,6062) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,6063) @node Updating a file
cvs.texi(,6064) @section Bringing a file up to date
cvs.texi(,6065) @cindex Bringing a file up to date
cvs.texi(,6066) @cindex Updating a file
cvs.texi(,6067) @cindex Merging a file
cvs.texi(,6068) @cindex Update, introduction
cvs.texi(,6069) 
cvs.texi(,6070) When you want to update or merge a file, use the @code{update}
cvs.texi(,6071) command.  For files that are not up to date this is roughly equivalent
cvs.texi(,6072) to a @code{checkout} command: the newest revision of the file is
cvs.texi(,6073) extracted from the repository and put in your working directory.
cvs.texi(,6074) 
cvs.texi(,6075) Your modifications to a file are never lost when you
cvs.texi(,6076) use @code{update}.  If no newer revision exists,
cvs.texi(,6077) running @code{update} has no effect.  If you have
cvs.texi(,6078) edited the file, and a newer revision is available,
cvs.texi(,6079) @sc{cvs} will merge all changes into your working copy.
cvs.texi(,6080) 
cvs.texi(,6081) For instance, imagine that you checked out revision 1.4 and started
cvs.texi(,6082) editing it.  In the meantime someone else committed revision 1.5, and
cvs.texi(,6083) shortly after that revision 1.6.  If you run @code{update} on the file
cvs.texi(,6084) now, @sc{cvs} will incorporate all changes between revision 1.4 and 1.6 into
cvs.texi(,6085) your file.
cvs.texi(,6086) 
cvs.texi(,6087) @cindex Overlap
cvs.texi(,6088) If any of the changes between 1.4 and 1.6 were made too
cvs.texi(,6089) close to any of the changes you have made, an
cvs.texi(,6090) @dfn{overlap} occurs.  In such cases a warning is
cvs.texi(,6091) printed, and the resulting file includes both
cvs.texi(,6092) versions of the lines that overlap, delimited by
cvs.texi(,6093) special markers.
cvs.texi(,6094) @xref{update}, for a complete description of the
cvs.texi(,6095) @code{update} command.
cvs.texi(,6096) 
cvs.texi(,6097) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,6098) @node Conflicts example
cvs.texi(,6099) @section Conflicts example
cvs.texi(,6100) @cindex Merge, an example
cvs.texi(,6101) @cindex Example of merge
cvs.texi(,6102) @cindex driver.c (merge example)
cvs.texi(,6103) 
cvs.texi(,6104) Suppose revision 1.4 of @file{driver.c} contains this:
cvs.texi(,6105) 
cvs.texi(,6106) @example
cvs.texi(,6107) #include <stdio.h>
cvs.texi(,6108) 
cvs.texi(,6109) void main()
cvs.texi(,6110) @{
cvs.texi(,6111)     parse();
cvs.texi(,6112)     if (nerr == 0)
cvs.texi(,6113)         gencode();
cvs.texi(,6114)     else
cvs.texi(,6115)         fprintf(stderr, "No code generated.\n");
cvs.texi(,6116)     exit(nerr == 0 ? 0 : 1);
cvs.texi(,6117) @}
cvs.texi(,6118) @end example
cvs.texi(,6119) 
cvs.texi(,6120) @noindent
cvs.texi(,6121) Revision 1.6 of @file{driver.c} contains this:
cvs.texi(,6122) 
cvs.texi(,6123) @example
cvs.texi(,6124) #include <stdio.h>
cvs.texi(,6125) 
cvs.texi(,6126) int main(int argc,
cvs.texi(,6127)          char **argv)
cvs.texi(,6128) @{
cvs.texi(,6129)     parse();
cvs.texi(,6130)     if (argc != 1)
cvs.texi(,6131)     @{
cvs.texi(,6132)         fprintf(stderr, "tc: No args expected.\n");
cvs.texi(,6133)         exit(1);
cvs.texi(,6134)     @}
cvs.texi(,6135)     if (nerr == 0)
cvs.texi(,6136)         gencode();
cvs.texi(,6137)     else
cvs.texi(,6138)         fprintf(stderr, "No code generated.\n");
cvs.texi(,6139)     exit(!!nerr);
cvs.texi(,6140) @}
cvs.texi(,6141) @end example
cvs.texi(,6142) 
cvs.texi(,6143) @noindent
cvs.texi(,6144) Your working copy of @file{driver.c}, based on revision
cvs.texi(,6145) 1.4, contains this before you run @samp{cvs update}:
cvs.texi(,6146) @c -- Really include "cvs"?
cvs.texi(,6147) 
cvs.texi(,6148) @example
cvs.texi(,6149) #include <stdlib.h>
cvs.texi(,6150) #include <stdio.h>
cvs.texi(,6151) 
cvs.texi(,6152) void main()
cvs.texi(,6153) @{
cvs.texi(,6154)     init_scanner();
cvs.texi(,6155)     parse();
cvs.texi(,6156)     if (nerr == 0)
cvs.texi(,6157)         gencode();
cvs.texi(,6158)     else
cvs.texi(,6159)         fprintf(stderr, "No code generated.\n");
cvs.texi(,6160)     exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
cvs.texi(,6161) @}
cvs.texi(,6162) @end example
cvs.texi(,6163) 
cvs.texi(,6164) @noindent
cvs.texi(,6165) You run @samp{cvs update}:
cvs.texi(,6166) @c -- Really include "cvs"?
cvs.texi(,6167) 
cvs.texi(,6168) @example
cvs.texi(,6169) $ cvs update driver.c
cvs.texi(,6170) RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v
cvs.texi(,6171) retrieving revision 1.4
cvs.texi(,6172) retrieving revision 1.6
cvs.texi(,6173) Merging differences between 1.4 and 1.6 into driver.c
cvs.texi(,6174) rcsmerge warning: overlaps during merge
cvs.texi(,6175) cvs update: conflicts found in driver.c
cvs.texi(,6176) C driver.c
cvs.texi(,6177) @end example
cvs.texi(,6178) 
cvs.texi(,6179) @noindent
cvs.texi(,6180) @cindex Conflicts (merge example)
cvs.texi(,6181) @sc{cvs} tells you that there were some conflicts.
cvs.texi(,6182) Your original working file is saved unmodified in
cvs.texi(,6183) @file{.#driver.c.1.4}.  The new version of
cvs.texi(,6184) @file{driver.c} contains this:
cvs.texi(,6185) 
cvs.texi(,6186) @example
cvs.texi(,6187) #include <stdlib.h>
cvs.texi(,6188) #include <stdio.h>
cvs.texi(,6189) 
cvs.texi(,6190) int main(int argc,
cvs.texi(,6191)          char **argv)
cvs.texi(,6192) @{
cvs.texi(,6193)     init_scanner();
cvs.texi(,6194)     parse();
cvs.texi(,6195)     if (argc != 1)
cvs.texi(,6196)     @{
cvs.texi(,6197)         fprintf(stderr, "tc: No args expected.\n");
cvs.texi(,6198)         exit(1);
cvs.texi(,6199)     @}
cvs.texi(,6200)     if (nerr == 0)
cvs.texi(,6201)         gencode();
cvs.texi(,6202)     else
cvs.texi(,6203)         fprintf(stderr, "No code generated.\n");
cvs.texi(,6204) @asis{}<<<<<<< driver.c
cvs.texi(,6205)     exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
cvs.texi(,6206) @asis{}=======
cvs.texi(,6207)     exit(!!nerr);
cvs.texi(,6208) @asis{}>>>>>>> 1.6
cvs.texi(,6209) @}
cvs.texi(,6210) @end example
cvs.texi(,6211) 
cvs.texi(,6212) @noindent
cvs.texi(,6213) @cindex Markers, conflict
cvs.texi(,6214) @cindex Conflict markers
cvs.texi(,6215) @cindex <<<<<<<
cvs.texi(,6216) @cindex >>>>>>>
cvs.texi(,6217) @cindex =======
cvs.texi(,6218) 
cvs.texi(,6219) Note how all non-overlapping modifications are incorporated in your working
cvs.texi(,6220) copy, and that the overlapping section is clearly marked with
cvs.texi(,6221) @samp{<<<<<<<}, @samp{=======} and @samp{>>>>>>>}.
cvs.texi(,6222) 
cvs.texi(,6223) @cindex Resolving a conflict
cvs.texi(,6224) @cindex Conflict resolution
cvs.texi(,6225) You resolve the conflict by editing the file, removing the markers and
cvs.texi(,6226) the erroneous line.  Suppose you end up with this file:
cvs.texi(,6227) @c -- Add xref to the pcl-cvs manual when it talks
cvs.texi(,6228) @c -- about this.
cvs.texi(,6229) @example
cvs.texi(,6230) #include <stdlib.h>
cvs.texi(,6231) #include <stdio.h>
cvs.texi(,6232) 
cvs.texi(,6233) int main(int argc,
cvs.texi(,6234)          char **argv)
cvs.texi(,6235) @{
cvs.texi(,6236)     init_scanner();
cvs.texi(,6237)     parse();
cvs.texi(,6238)     if (argc != 1)
cvs.texi(,6239)     @{
cvs.texi(,6240)         fprintf(stderr, "tc: No args expected.\n");
cvs.texi(,6241)         exit(1);
cvs.texi(,6242)     @}
cvs.texi(,6243)     if (nerr == 0)
cvs.texi(,6244)         gencode();
cvs.texi(,6245)     else
cvs.texi(,6246)         fprintf(stderr, "No code generated.\n");
cvs.texi(,6247)     exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
cvs.texi(,6248) @}
cvs.texi(,6249) @end example
cvs.texi(,6250) 
cvs.texi(,6251) @noindent
cvs.texi(,6252) You can now go ahead and commit this as revision 1.7.
cvs.texi(,6253) 
cvs.texi(,6254) @example
cvs.texi(,6255) $ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c
cvs.texi(,6256) Checking in driver.c;
cvs.texi(,6257) /usr/local/cvsroot/yoyodyne/tc/driver.c,v  <--  driver.c
cvs.texi(,6258) new revision: 1.7; previous revision: 1.6
cvs.texi(,6259) done
cvs.texi(,6260) @end example
cvs.texi(,6261) 
cvs.texi(,6262) For your protection, @sc{cvs} will refuse to check in a
cvs.texi(,6263) file if a conflict occurred and you have not resolved
cvs.texi(,6264) the conflict.  Currently to resolve a conflict, you
cvs.texi(,6265) must change the timestamp on the file.  In previous
cvs.texi(,6266) versions of @sc{cvs}, you also needed to
cvs.texi(,6267) insure that the file contains no conflict markers.
cvs.texi(,6268) Because
cvs.texi(,6269) your file may legitimately contain conflict markers (that
cvs.texi(,6270) is, occurrences of @samp{>>>>>>> } at the start of a
cvs.texi(,6271) line that don't mark a conflict), the current
cvs.texi(,6272) version of @sc{cvs} will print a warning and proceed to
cvs.texi(,6273) check in the file.
cvs.texi(,6274) @c The old behavior was really icky; the only way out
cvs.texi(,6275) @c was to start hacking on
cvs.texi(,6276) @c the @code{CVS/Entries} file or other such workarounds.
cvs.texi(,6277) @c
cvs.texi(,6278) @c If the timestamp thing isn't considered nice enough,
cvs.texi(,6279) @c maybe there should be a "cvs resolved" command
cvs.texi(,6280) @c which clears the conflict indication.  For a nice user
cvs.texi(,6281) @c interface, this should be invoked by an interactive
cvs.texi(,6282) @c merge tool like emerge rather than by the user
cvs.texi(,6283) @c directly--such a tool can verify that the user has
cvs.texi(,6284) @c really dealt with each conflict.
cvs.texi(,6285) 
cvs.texi(,6286) @cindex emerge
cvs.texi(,6287) If you use release 1.04 or later of pcl-cvs (a @sc{gnu}
cvs.texi(,6288) Emacs front-end for @sc{cvs}) you can use an Emacs
cvs.texi(,6289) package called emerge to help you resolve conflicts.
cvs.texi(,6290) See the documentation for pcl-cvs.
cvs.texi(,6291) 
cvs.texi(,6292) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,6293) @node Informing others
cvs.texi(,6294) @section Informing others about commits
cvs.texi(,6295) @cindex Informing others
cvs.texi(,6296) @cindex Spreading information
cvs.texi(,6297) @cindex Mail, automatic mail on commit
cvs.texi(,6298) 
cvs.texi(,6299) It is often useful to inform others when you commit a
cvs.texi(,6300) new revision of a file.  The @samp{-i} option of the
cvs.texi(,6301) @file{modules} file, or the @file{loginfo} file, can be
cvs.texi(,6302) used to automate this process.  @xref{modules}.
cvs.texi(,6303) @xref{loginfo}.  You can use these features of @sc{cvs}
cvs.texi(,6304) to, for instance, instruct @sc{cvs} to mail a
cvs.texi(,6305) message to all developers, or post a message to a local
cvs.texi(,6306) newsgroup.
cvs.texi(,6307) @c -- More text would be nice here.
cvs.texi(,6308) 
cvs.texi(,6309) @node Concurrency
cvs.texi(,6310) @section Several developers simultaneously attempting to run CVS
cvs.texi(,6311) 
cvs.texi(,6312) @cindex Locks, cvs, introduction
cvs.texi(,6313) @c For a discussion of *why* CVS creates locks, see
cvs.texi(,6314) @c the comment at the start of src/lock.c
cvs.texi(,6315) If several developers try to run @sc{cvs} at the same
cvs.texi(,6316) time, one may get the following message:
cvs.texi(,6317) 
cvs.texi(,6318) @example
cvs.texi(,6319) [11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo
cvs.texi(,6320) @end example
cvs.texi(,6321) 
cvs.texi(,6322) @cindex #cvs.rfl, removing
cvs.texi(,6323) @cindex #cvs.wfl, removing
cvs.texi(,6324) @cindex #cvs.lock, removing
cvs.texi(,6325) @sc{cvs} will try again every 30 seconds, and either
cvs.texi(,6326) continue with the operation or print the message again,
cvs.texi(,6327) if it still needs to wait.  If a lock seems to stick
cvs.texi(,6328) around for an undue amount of time, find the person
cvs.texi(,6329) holding the lock and ask them about the cvs command
cvs.texi(,6330) they are running.  If they aren't running a cvs
cvs.texi(,6331) command, look in the repository directory mentioned in
cvs.texi(,6332) the message and remove files which they own whose names
cvs.texi(,6333) start with @file{#cvs.rfl},
cvs.texi(,6334) @file{#cvs.wfl}, or @file{#cvs.lock}.
cvs.texi(,6335) 
cvs.texi(,6336) Note that these locks are to protect @sc{cvs}'s
cvs.texi(,6337) internal data structures and have no relationship to
cvs.texi(,6338) the word @dfn{lock} in the sense used by
cvs.texi(,6339) @sc{rcs}---which refers to reserved checkouts
cvs.texi(,6340) (@pxref{Multiple developers}).
cvs.texi(,6341) 
cvs.texi(,6342) Any number of people can be reading from a given
cvs.texi(,6343) repository at a time; only when someone is writing do
cvs.texi(,6344) the locks prevent other people from reading or writing.
cvs.texi(,6345) 
cvs.texi(,6346) @cindex Atomic transactions, lack of
cvs.texi(,6347) @cindex Transactions, atomic, lack of
cvs.texi(,6348) @c the following talks about what one might call commit/update
cvs.texi(,6349) @c atomicity.
cvs.texi(,6350) @c Probably also should say something about
cvs.texi(,6351) @c commit/commit atomicity, that is, "An update will
cvs.texi(,6352) @c not get partial versions of more than one commit".
cvs.texi(,6353) @c CVS currently has this property and I guess we can
cvs.texi(,6354) @c make it a documented feature.
cvs.texi(,6355) @c For example one person commits
cvs.texi(,6356) @c a/one.c and b/four.c and another commits a/two.c and
cvs.texi(,6357) @c b/three.c.  Then an update cannot get the new a/one.c
cvs.texi(,6358) @c and a/two.c and the old b/four.c and b/three.c.
cvs.texi(,6359) One might hope for the following property:
cvs.texi(,6360) 
cvs.texi(,6361) @quotation
cvs.texi(,6362) If someone commits some changes in one cvs command,
cvs.texi(,6363) then an update by someone else will either get all the
cvs.texi(,6364) changes, or none of them.
cvs.texi(,6365) @end quotation
cvs.texi(,6366) 
cvs.texi(,6367) @noindent
cvs.texi(,6368) but @sc{cvs} does @emph{not} have this property.  For
cvs.texi(,6369) example, given the files
cvs.texi(,6370) 
cvs.texi(,6371) @example
cvs.texi(,6372) a/one.c
cvs.texi(,6373) a/two.c
cvs.texi(,6374) b/three.c
cvs.texi(,6375) b/four.c
cvs.texi(,6376) @end example
cvs.texi(,6377) 
cvs.texi(,6378) @noindent
cvs.texi(,6379) if someone runs
cvs.texi(,6380) 
cvs.texi(,6381) @example
cvs.texi(,6382) cvs ci a/two.c b/three.c
cvs.texi(,6383) @end example
cvs.texi(,6384) 
cvs.texi(,6385) @noindent
cvs.texi(,6386) and someone else runs @code{cvs update} at the same
cvs.texi(,6387) time, the person running @code{update} might get only
cvs.texi(,6388) the change to @file{b/three.c} and not the change to
cvs.texi(,6389) @file{a/two.c}.
cvs.texi(,6390) 
cvs.texi(,6391) @node Watches
cvs.texi(,6392) @section Mechanisms to track who is editing files
cvs.texi(,6393) @cindex Watches
cvs.texi(,6394) 
cvs.texi(,6395) For many groups, use of @sc{cvs} in its default mode is
cvs.texi(,6396) perfectly satisfactory.  Users may sometimes go to
cvs.texi(,6397) check in a modification only to find that another
cvs.texi(,6398) modification has intervened, but they deal with it and
cvs.texi(,6399) proceed with their check in.  Other groups prefer to be
cvs.texi(,6400) able to know who is editing what files, so that if two
cvs.texi(,6401) people try to edit the same file they can choose to
cvs.texi(,6402) talk about who is doing what when rather than be
cvs.texi(,6403) surprised at check in time.  The features in this
cvs.texi(,6404) section allow such coordination, while retaining the
cvs.texi(,6405) ability of two developers to edit the same file at the
cvs.texi(,6406) same time.
cvs.texi(,6407) 
cvs.texi(,6408) @c Some people might ask why CVS does not enforce the
cvs.texi(,6409) @c rule on chmod, by requiring a cvs edit before a cvs
cvs.texi(,6410) @c commit.  The main reason is that it could always be
cvs.texi(,6411) @c circumvented--one could edit the file, and
cvs.texi(,6412) @c then when ready to check it in, do the cvs edit and put
cvs.texi(,6413) @c in the new contents and do the cvs commit.  One
cvs.texi(,6414) @c implementation note: if we _do_ want to have cvs commit
cvs.texi(,6415) @c require a cvs edit, we should store the state on
cvs.texi(,6416) @c whether the cvs edit has occurred in the working
cvs.texi(,6417) @c directory, rather than having the server try to keep
cvs.texi(,6418) @c track of what working directories exist.
cvs.texi(,6419) @c FIXME: should the above discussion be part of the
cvs.texi(,6420) @c manual proper, somewhere, not just in a comment?
cvs.texi(,6421) For maximum benefit developers should use @code{cvs
cvs.texi(,6422) edit} (not @code{chmod}) to make files read-write to
cvs.texi(,6423) edit them, and @code{cvs release} (not @code{rm}) to
cvs.texi(,6424) discard a working directory which is no longer in use,
cvs.texi(,6425) but @sc{cvs} is not able to enforce this behavior.
cvs.texi(,6426) 
cvs.texi(,6427) @c I'm a little dissatisfied with this presentation,
cvs.texi(,6428) @c because "watch on"/"edit"/"editors" are one set of
cvs.texi(,6429) @c functionality, and "watch add"/"watchers" is another
cvs.texi(,6430) @c which is somewhat orthogonal even though they interact in
cvs.texi(,6431) @c various ways.  But I think it might be
cvs.texi(,6432) @c confusing to describe them separately (e.g. "watch
cvs.texi(,6433) @c add" with loginfo).  I don't know.
cvs.texi(,6434) 
cvs.texi(,6435) @menu
cvs.texi(,6436) * Setting a watch::             Telling CVS to watch certain files
cvs.texi(,6437) * Getting Notified::            Telling CVS to notify you
cvs.texi(,6438) * Editing files::               How to edit a file which is being watched
cvs.texi(,6439) * Watch information::           Information about who is watching and editing
cvs.texi(,6440) * Watches Compatibility::       Watches interact poorly with CVS 1.6 or earlier
cvs.texi(,6441) @end menu
cvs.texi(,6442) 
cvs.texi(,6443) @node Setting a watch
cvs.texi(,6444) @subsection Telling CVS to watch certain files
cvs.texi(,6445) 
cvs.texi(,6446) To enable the watch features, you first specify that
cvs.texi(,6447) certain files are to be watched.
cvs.texi(,6448) 
cvs.texi(,6449) @cindex watch on (subcommand)
cvs.texi(,6450) @deffn Command {cvs watch on} [@code{-lR}] [@var{files}]@dots{}
cvs.texi(,6451) 
cvs.texi(,6452) @cindex Read-only files, and watches
cvs.texi(,6453) Specify that developers should run @code{cvs edit}
cvs.texi(,6454) before editing @var{files}.  @sc{cvs} will create working
cvs.texi(,6455) copies of @var{files} read-only, to remind developers
cvs.texi(,6456) to run the @code{cvs edit} command before working on
cvs.texi(,6457) them.
cvs.texi(,6458) 
cvs.texi(,6459) If @var{files} includes the name of a directory, @sc{cvs}
cvs.texi(,6460) arranges to watch all files added to the corresponding
cvs.texi(,6461) repository directory, and sets a default for files
cvs.texi(,6462) added in the future; this allows the user to set
cvs.texi(,6463) notification policies on a per-directory basis.  The
cvs.texi(,6464) contents of the directory are processed recursively,
cvs.texi(,6465) unless the @code{-l} option is given.
cvs.texi(,6466) The @code{-R} option can be used to force recursion if the @code{-l}
cvs.texi(,6467) option is set in @file{~/.cvsrc} (@pxref{~/.cvsrc}).
cvs.texi(,6468) 
cvs.texi(,6469) If @var{files} is omitted, it defaults to the current directory.
cvs.texi(,6470) 
cvs.texi(,6471) @cindex watch off (subcommand)
cvs.texi(,6472) @end deffn
cvs.texi(,6473) 
cvs.texi(,6474) @deffn Command {cvs watch off} [@code{-lR}] [@var{files}]@dots{}
cvs.texi(,6475) 
cvs.texi(,6476) Do not create @var{files} read-only on checkout; thus,
cvs.texi(,6477) developers will not be reminded to use @code{cvs edit}
cvs.texi(,6478) and @code{cvs unedit}.
cvs.texi(,6486) 
cvs.texi(,6487) The @var{files} and options are processed as for @code{cvs
cvs.texi(,6488) watch on}.
cvs.texi(,6489) 
cvs.texi(,6490) @end deffn
cvs.texi(,6491) 
cvs.texi(,6492) @node Getting Notified
cvs.texi(,6493) @subsection Telling CVS to notify you
cvs.texi(,6494) 
cvs.texi(,6495) You can tell @sc{cvs} that you want to receive
cvs.texi(,6496) notifications about various actions taken on a file.
cvs.texi(,6497) You can do this without using @code{cvs watch on} for
cvs.texi(,6498) the file, but generally you will want to use @code{cvs
cvs.texi(,6499) watch on}, to remind developers to use the @code{cvs edit}
cvs.texi(,6500) command.
cvs.texi(,6501) 
cvs.texi(,6502) @cindex watch add (subcommand)
cvs.texi(,6503) @deffn Command {cvs watch add} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{}
cvs.texi(,6504) 
cvs.texi(,6505) Add the current user to the list of people to receive notification of
cvs.texi(,6506) work done on @var{files}.
cvs.texi(,6507) 
cvs.texi(,6508) The @code{-a} option specifies what kinds of events @sc{cvs} should notify
cvs.texi(,6509) the user about.  @var{action} is one of the following:
cvs.texi(,6510) 
cvs.texi(,6511) @table @code
cvs.texi(,6512) 
cvs.texi(,6513) @item edit
cvs.texi(,6514) Another user has applied the @code{cvs edit} command (described
cvs.texi(,6515) below) to a watched file.
cvs.texi(,6516) 
cvs.texi(,6517) @item commit
cvs.texi(,6518) Another user has committed changes to one of the named @var{files}.
cvs.texi(,6519) 
cvs.texi(,6520) @item unedit
cvs.texi(,6521) Another user has abandoned editing a file (other than by committing changes).
cvs.texi(,6522) They can do this in several ways, by:
cvs.texi(,6523) 
cvs.texi(,6524) @itemize @bullet
cvs.texi(,6525) 
cvs.texi(,6526) @item
cvs.texi(,6527) applying the @code{cvs unedit} command (described below) to the file
cvs.texi(,6528) 
cvs.texi(,6529) @item
cvs.texi(,6530) applying the @code{cvs release} command (@pxref{release}) to the file's parent directory
cvs.texi(,6531) (or recursively to a directory more than one level up)
cvs.texi(,6532) 
cvs.texi(,6533) @item
cvs.texi(,6534) deleting the file and allowing @code{cvs update} to recreate it
cvs.texi(,6535) 
cvs.texi(,6536) @end itemize
cvs.texi(,6537) 
cvs.texi(,6538) @item all
cvs.texi(,6539) All of the above.
cvs.texi(,6540) 
cvs.texi(,6541) @item none
cvs.texi(,6542) None of the above.  (This is useful with @code{cvs edit},
cvs.texi(,6543) described below.)
cvs.texi(,6544) 
cvs.texi(,6545) @end table
cvs.texi(,6546) 
cvs.texi(,6547) The @code{-a} option may appear more than once, or not at all.  If
cvs.texi(,6548) omitted, the action defaults to @code{all}.
cvs.texi(,6549) 
cvs.texi(,6550) The @var{files} and options are processed as for
cvs.texi(,6551) @code{cvs watch on}.
cvs.texi(,6552) 
cvs.texi(,6553) @end deffn
cvs.texi(,6554) 
cvs.texi(,6555) 
cvs.texi(,6556) @cindex watch remove (subcommand)
cvs.texi(,6557) @deffn Command {cvs watch remove} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{}
cvs.texi(,6558) 
cvs.texi(,6559) Remove a notification request established using @code{cvs watch add};
cvs.texi(,6560) the arguments are the same.  If the @code{-a} option is present, only
cvs.texi(,6561) watches for the specified actions are removed.
cvs.texi(,6562) 
cvs.texi(,6563) @end deffn
cvs.texi(,6564) 
cvs.texi(,6565) @cindex notify (admin file)
cvs.texi(,6566) When the conditions exist for notification, @sc{cvs}
cvs.texi(,6567) calls the @file{notify} administrative file.  Edit
cvs.texi(,6568) @file{notify} as one edits the other administrative
cvs.texi(,6569) files (@pxref{Intro administrative files}).  This
cvs.texi(,6570) file follows the usual conventions for administrative
cvs.texi(,6571) files (@pxref{syntax}), where each line is a regular
cvs.texi(,6572) expression followed by a command to execute.  The
cvs.texi(,6573) command should contain a single occurrence of @samp{%s}
cvs.texi(,6574) which will be replaced by the user to notify; the rest
cvs.texi(,6575) of the information regarding the notification will be
cvs.texi(,6576) supplied to the command on standard input.  The
cvs.texi(,6577) standard thing to put in the @code{notify} file is the
cvs.texi(,6578) single line:
cvs.texi(,6579) 
cvs.texi(,6580) @example
cvs.texi(,6581) ALL mail %s -s "CVS notification"
cvs.texi(,6582) @end example
cvs.texi(,6583) 
cvs.texi(,6584) @noindent
cvs.texi(,6585) This causes users to be notified by electronic mail.
cvs.texi(,6586) @c FIXME: should it be this hard to set up this
cvs.texi(,6587) @c behavior (and the result when one fails to do so,
cvs.texi(,6588) @c silent failure to notify, so non-obvious)?  Should
cvs.texi(,6589) @c CVS give a warning if no line in notify matches (and
cvs.texi(,6590) @c document the use of "DEFAULT :" for the case where
cvs.texi(,6591) @c skipping the notification is indeed desired)?
cvs.texi(,6592) 
cvs.texi(,6593) @cindex users (admin file)
cvs.texi(,6594) Note that if you set this up in the straightforward
cvs.texi(,6595) way, users receive notifications on the server machine.
cvs.texi(,6596) One could of course write a @file{notify} script which
cvs.texi(,6597) directed notifications elsewhere, but to make this
cvs.texi(,6598) easy, @sc{cvs} allows you to associate a notification
cvs.texi(,6599) address for each user.  To do so create a file
cvs.texi(,6600) @file{users} in @file{CVSROOT} with a line for each
cvs.texi(,6601) user in the format @var{user}:@var{value}.  Then
cvs.texi(,6602) instead of passing the name of the user to be notified
cvs.texi(,6603) to @file{notify}, @sc{cvs} will pass the @var{value}
cvs.texi(,6604) (normally an email address on some other machine).
cvs.texi(,6605) 
cvs.texi(,6606) @sc{cvs} does not notify you for your own changes.
cvs.texi(,6607) Currently this check is done based on whether the user
cvs.texi(,6608) name of the person taking the action which triggers
cvs.texi(,6609) notification matches the user name of the person
cvs.texi(,6610) getting notification.  In fact, in general, the watches
cvs.texi(,6611) features only track one edit by each user.  It probably
cvs.texi(,6612) would be more useful if watches tracked each working
cvs.texi(,6613) directory separately, so this behavior might be worth
cvs.texi(,6614) changing.
cvs.texi(,6615) @c "behavior might be worth changing" is an effort to
cvs.texi(,6616) @c point to future directions while also not promising
cvs.texi(,6617) @c that "they" (as in "why don't they fix CVS to....")
cvs.texi(,6618) @c will do this.
cvs.texi(,6619) @c one implementation issue is identifying whether a
cvs.texi(,6620) @c working directory is same or different.  Comparing
cvs.texi(,6621) @c pathnames/hostnames is hopeless, but having the server
cvs.texi(,6622) @c supply a serial number which the client stores in the
cvs.texi(,6623) @c CVS directory as a magic cookie should work.
cvs.texi(,6624) 
cvs.texi(,6625) @node Editing files
cvs.texi(,6626) @subsection How to edit a file which is being watched
cvs.texi(,6627) 
cvs.texi(,6628) @cindex Checkout, as term for getting ready to edit
cvs.texi(,6629) Since a file which is being watched is checked out
cvs.texi(,6630) read-only, you cannot simply edit it.  To make it
cvs.texi(,6631) read-write, and inform others that you are planning to
cvs.texi(,6632) edit it, use the @code{cvs edit} command.  Some systems
cvs.texi(,6633) call this a @dfn{checkout}, but @sc{cvs} uses that term
cvs.texi(,6634) for obtaining a copy of the sources (@pxref{Getting the
cvs.texi(,6635) source}), an operation which those systems call a
cvs.texi(,6636) @dfn{get} or a @dfn{fetch}.
cvs.texi(,6637) @c Issue to think about: should we transition CVS
cvs.texi(,6638) @c towards the "get" terminology?  "cvs get" is already a
cvs.texi(,6639) @c synonym for "cvs checkout" and that section of the
cvs.texi(,6640) @c manual refers to "Getting the source".  If this is
cvs.texi(,6641) @c done, needs to be done gingerly (for example, we should
cvs.texi(,6642) @c still accept "checkout" in .cvsrc files indefinitely
cvs.texi(,6643) @c even if the CVS's messages are changed from "cvs checkout: "
cvs.texi(,6644) @c to "cvs get: ").
cvs.texi(,6645) @c There is a concern about whether "get" is not as
cvs.texi(,6646) @c good for novices because it is a more general term
cvs.texi(,6647) @c than "checkout" (and thus arguably harder to assign
cvs.texi(,6648) @c a technical meaning for).
cvs.texi(,6649) 
cvs.texi(,6650) @cindex edit (subcommand)
cvs.texi(,6651) @deffn Command {cvs edit} [@code{-lR}] [@code{-a} @var{action}]@dots{} [@var{files}]@dots{}
cvs.texi(,6652) 
cvs.texi(,6653) Prepare to edit the working files @var{files}.  @sc{cvs} makes the
cvs.texi(,6654) @var{files} read-write, and notifies users who have requested
cvs.texi(,6655) @code{edit} notification for any of @var{files}.
cvs.texi(,6656) 
cvs.texi(,6657) The @code{cvs edit} command accepts the same options as the
cvs.texi(,6658) @code{cvs watch add} command, and establishes a temporary watch for the
cvs.texi(,6659) user on @var{files}; @sc{cvs} will remove the watch when @var{files} are
cvs.texi(,6660) @code{unedit}ed or @code{commit}ted.  If the user does not wish to
cvs.texi(,6661) receive notifications, she should specify @code{-a none}.
cvs.texi(,6662) 
cvs.texi(,6663) The @var{files} and the options are processed as for the @code{cvs
cvs.texi(,6664) watch} commands.
cvs.texi(,6665) 
cvs.texi(,6675) 
cvs.texi(,6676) @end deffn
cvs.texi(,6677) 
cvs.texi(,6678) Normally when you are done with a set of changes, you
cvs.texi(,6679) use the @code{cvs commit} command, which checks in your
cvs.texi(,6680) changes and returns the watched files to their usual
cvs.texi(,6681) read-only state.  But if you instead decide to abandon
cvs.texi(,6682) your changes, or not to make any changes, you can use
cvs.texi(,6683) the @code{cvs unedit} command.
cvs.texi(,6684) 
cvs.texi(,6685) @cindex unedit (subcommand)
cvs.texi(,6686) @cindex Abandoning work
cvs.texi(,6687) @cindex Reverting to repository version
cvs.texi(,6688) @deffn Command {cvs unedit} [@code{-lR}] [@var{files}]@dots{}
cvs.texi(,6689) 
cvs.texi(,6690) Abandon work on the working files @var{files}, and revert them to the
cvs.texi(,6691) repository versions on which they are based.  @sc{cvs} makes those
cvs.texi(,6692) @var{files} read-only for which users have requested notification using
cvs.texi(,6693) @code{cvs watch on}.  @sc{cvs} notifies users who have requested @code{unedit}
cvs.texi(,6694) notification for any of @var{files}.
cvs.texi(,6695) 
cvs.texi(,6696) The @var{files} and options are processed as for the
cvs.texi(,6697) @code{cvs watch} commands.
cvs.texi(,6698) 
cvs.texi(,6699) If watches are not in use, the @code{unedit} command
cvs.texi(,6700) probably does not work, and the way to revert to the
cvs.texi(,6701) repository version is with the command @code{cvs update -C file}
cvs.texi(,6702) (@pxref{update}).
cvs.texi(,6703) The meaning is
cvs.texi(,6704) not precisely the same; the latter may also
cvs.texi(,6705) bring in some changes which have been made in the
cvs.texi(,6706) repository since the last time you updated.
cvs.texi(,6707) @c It would be a useful enhancement to CVS to make
cvs.texi(,6708) @c unedit work in the non-watch case as well.
cvs.texi(,6709) @end deffn
cvs.texi(,6710) 
cvs.texi(,6711) When using client/server @sc{cvs}, you can use the
cvs.texi(,6712) @code{cvs edit} and @code{cvs unedit} commands even if
cvs.texi(,6713) @sc{cvs} is unable to successfully communicate with the
cvs.texi(,6714) server; the notifications will be sent upon the next
cvs.texi(,6715) successful @sc{cvs} command.
cvs.texi(,6716) 
cvs.texi(,6717) @node Watch information
cvs.texi(,6718) @subsection Information about who is watching and editing
cvs.texi(,6719) 
cvs.texi(,6720) @cindex watchers (subcommand)
cvs.texi(,6721) @deffn Command {cvs watchers} [@code{-lR}] [@var{files}]@dots{}
cvs.texi(,6722) 
cvs.texi(,6723) List the users currently watching changes to @var{files}.  The report
cvs.texi(,6724) includes the files being watched, and the mail address of each watcher.
cvs.texi(,6725) 
cvs.texi(,6726) The @var{files} and options are processed as for the
cvs.texi(,6727) @code{cvs watch} commands.
cvs.texi(,6728) 
cvs.texi(,6729) @end deffn
cvs.texi(,6730) 
cvs.texi(,6731) 
cvs.texi(,6732) @cindex editors (subcommand)
cvs.texi(,6733) @deffn Command {cvs editors} [@code{-lR}] [@var{files}]@dots{}
cvs.texi(,6734) 
cvs.texi(,6735) List the users currently working on @var{files}.  The report
cvs.texi(,6736) includes the mail address of each user, the time when the user began
cvs.texi(,6737) working with the file, and the host and path of the working directory
cvs.texi(,6738) containing the file.
cvs.texi(,6739) 
cvs.texi(,6740) The @var{files} and options are processed as for the
cvs.texi(,6741) @code{cvs watch} commands.
cvs.texi(,6742) 
cvs.texi(,6743) @end deffn
cvs.texi(,6744) 
cvs.texi(,6745) @node Watches Compatibility
cvs.texi(,6746) @subsection Using watches with old versions of CVS
cvs.texi(,6747) 
cvs.texi(,6748) @cindex CVS 1.6, and watches
cvs.texi(,6749) If you use the watch features on a repository, it
cvs.texi(,6750) creates @file{CVS} directories in the repository and
cvs.texi(,6751) stores the information about watches in that directory.
cvs.texi(,6752) If you attempt to use @sc{cvs} 1.6 or earlier with the
cvs.texi(,6753) repository, you get an error message such as the
cvs.texi(,6754) following (all on one line):
cvs.texi(,6755) 
cvs.texi(,6756) @example
cvs.texi(,6757) cvs update: cannot open CVS/Entries for reading:
cvs.texi(,6758) No such file or directory
cvs.texi(,6759) @end example
cvs.texi(,6760) 
cvs.texi(,6761) @noindent
cvs.texi(,6762) and your operation will likely be aborted.  To use the
cvs.texi(,6763) watch features, you must upgrade all copies of @sc{cvs}
cvs.texi(,6764) which use that repository in local or server mode.  If
cvs.texi(,6765) you cannot upgrade, use the @code{watch off} and
cvs.texi(,6766) @code{watch remove} commands to remove all watches, and
cvs.texi(,6767) that will restore the repository to a state which
cvs.texi(,6768) @sc{cvs} 1.6 can cope with.
cvs.texi(,6769) 
cvs.texi(,6770) @node Choosing a model
cvs.texi(,6771) @section Choosing between reserved or unreserved checkouts
cvs.texi(,6772) @cindex Choosing, reserved or unreserved checkouts
cvs.texi(,6773) 
cvs.texi(,6774) Reserved and unreserved checkouts each have pros and
cvs.texi(,6775) cons.  Let it be said that a lot of this is a matter of
cvs.texi(,6776) opinion or what works given different groups' working
cvs.texi(,6777) styles, but here is a brief description of some of the
cvs.texi(,6778) issues.  There are many ways to organize a team of
cvs.texi(,6779) developers.  @sc{cvs} does not try to enforce a certain
cvs.texi(,6780) organization.  It is a tool that can be used in several
cvs.texi(,6781) ways.
cvs.texi(,6782) 
cvs.texi(,6783) Reserved checkouts can be very counter-productive.  If
cvs.texi(,6784) two persons want to edit different parts of a file,
cvs.texi(,6785) there may be no reason to prevent either of them from
cvs.texi(,6786) doing so.  Also, it is common for someone to take out a
cvs.texi(,6787) lock on a file, because they are planning to edit it,
cvs.texi(,6788) but then forget to release the lock.
cvs.texi(,6789) 
cvs.texi(,6790) @c "many groups"?  specifics?  cites to papers on this?
cvs.texi(,6791) @c some way to weasel-word it a bit more so we don't
cvs.texi(,6792) @c need facts :-)?
cvs.texi(,6793) People, especially people who are familiar with
cvs.texi(,6794) reserved checkouts, often wonder how often conflicts
cvs.texi(,6795) occur if unreserved checkouts are used, and how
cvs.texi(,6796) difficult they are to resolve.  The experience with
cvs.texi(,6797) many groups is that they occur rarely and usually are
cvs.texi(,6798) relatively straightforward to resolve.
cvs.texi(,6799) 
cvs.texi(,6800) The rarity of serious conflicts may be surprising, until one realizes
cvs.texi(,6801) that they occur only when two developers disagree on the proper design
cvs.texi(,6802) for a given section of code; such a disagreement suggests that the
cvs.texi(,6803) team has not been communicating properly in the first place.  In order
cvs.texi(,6804) to collaborate under @emph{any} source management regimen, developers
cvs.texi(,6805) must agree on the general design of the system; given this agreement,
cvs.texi(,6806) overlapping changes are usually straightforward to merge.
cvs.texi(,6807) 
cvs.texi(,6808) In some cases unreserved checkouts are clearly
cvs.texi(,6809) inappropriate.  If no merge tool exists for the kind of
cvs.texi(,6810) file you are managing (for example word processor files
cvs.texi(,6811) or files edited by Computer Aided Design programs), and
cvs.texi(,6812) it is not desirable to change to a program which uses a
cvs.texi(,6813) mergeable data format, then resolving conflicts is
cvs.texi(,6814) going to be unpleasant enough that you generally will
cvs.texi(,6815) be better off to simply avoid the conflicts instead, by
cvs.texi(,6816) using reserved checkouts.
cvs.texi(,6817) 
cvs.texi(,6818) The watches features described above in @ref{Watches}
cvs.texi(,6819) can be considered to be an intermediate model between
cvs.texi(,6820) reserved checkouts and unreserved checkouts.  When you
cvs.texi(,6821) go to edit a file, it is possible to find out who else
cvs.texi(,6822) is editing it.  And rather than having the system
cvs.texi(,6823) simply forbid both people editing the file, it can tell
cvs.texi(,6824) you what the situation is and let you figure out
cvs.texi(,6825) whether it is a problem in that particular case or not.
cvs.texi(,6826) Therefore, for some groups it can be considered the
cvs.texi(,6827) best of both the reserved checkout and unreserved
cvs.texi(,6828) checkout worlds.
cvs.texi(,6829) 
cvs.texi(,6830) @c ---------------------------------------------------------------------
cvs.texi(,6831) @node Revision management
cvs.texi(,6832) @chapter Revision management
cvs.texi(,6833) @cindex Revision management
cvs.texi(,6834) 
cvs.texi(,6835) @c -- This chapter could be expanded a lot.
cvs.texi(,6836) @c -- Experiences are very welcome!
cvs.texi(,6837) 
cvs.texi(,6838) If you have read this far, you probably have a pretty
cvs.texi(,6839) good grasp on what @sc{cvs} can do for you.  This
cvs.texi(,6840) chapter talks a little about things that you still have
cvs.texi(,6841) to decide.
cvs.texi(,6842) 
cvs.texi(,6843) If you are doing development on your own using @sc{cvs}
cvs.texi(,6844) you could probably skip this chapter.  The questions
cvs.texi(,6845) this chapter takes up become more important when more
cvs.texi(,6846) than one person is working in a repository.
cvs.texi(,6847) 
cvs.texi(,6848) @menu
cvs.texi(,6849) * When to commit::              Some discussion on the subject
cvs.texi(,6850) @end menu
cvs.texi(,6851) 
cvs.texi(,6852) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,6853) @node When to commit
cvs.texi(,6854) @section When to commit?
cvs.texi(,6855) @cindex When to commit
cvs.texi(,6856) @cindex Committing, when to
cvs.texi(,6857) @cindex Policy
cvs.texi(,6858) 
cvs.texi(,6859) Your group should decide which policy to use regarding
cvs.texi(,6860) commits.  Several policies are possible, and as your
cvs.texi(,6861) experience with @sc{cvs} grows you will probably find
cvs.texi(,6862) out what works for you.
cvs.texi(,6863) 
cvs.texi(,6864) If you commit files too quickly you might commit files
cvs.texi(,6865) that do not even compile.  If your partner updates his
cvs.texi(,6866) working sources to include your buggy file, he will be
cvs.texi(,6867) unable to compile the code.  On the other hand, other
cvs.texi(,6868) persons will not be able to benefit from the
cvs.texi(,6869) improvements you make to the code if you commit very
cvs.texi(,6870) seldom, and conflicts will probably be more common.
cvs.texi(,6871) 
cvs.texi(,6872) It is common to only commit files after making sure
cvs.texi(,6873) that they can be compiled.  Some sites require that the
cvs.texi(,6874) files pass a test suite.  Policies like this can be
cvs.texi(,6875) enforced using the commitinfo file
cvs.texi(,6876) (@pxref{commitinfo}), but you should think twice before
cvs.texi(,6877) you enforce such a convention.  By making the
cvs.texi(,6878) development environment too controlled it might become
cvs.texi(,6879) too regimented and thus counter-productive to the real
cvs.texi(,6880) goal, which is to get software written.
cvs.texi(,6881) 
cvs.texi(,6882) @c ---------------------------------------------------------------------
cvs.texi(,6883) @node Keyword substitution
cvs.texi(,6884) @chapter Keyword substitution
cvs.texi(,6885) @cindex Keyword substitution
cvs.texi(,6886) @cindex Keyword expansion
cvs.texi(,6887) @cindex Identifying files
cvs.texi(,6888) 
cvs.texi(,6889) @comment   Be careful when editing this chapter.
cvs.texi(,6890) @comment   Remember that this file is kept under
cvs.texi(,6891) @comment   version control, so we must not accidentally
cvs.texi(,6892) @comment   include a valid keyword in the running text.
cvs.texi(,6893) 
cvs.texi(,6894) As long as you edit source files inside a working
cvs.texi(,6895) directory you can always find out the state of
cvs.texi(,6896) your files via @samp{cvs status} and @samp{cvs log}.
cvs.texi(,6897) But as soon as you export the files from your
cvs.texi(,6898) development environment it becomes harder to identify
cvs.texi(,6899) which revisions they are.
cvs.texi(,6900) 
cvs.texi(,6901) @sc{cvs} can use a mechanism known as @dfn{keyword
cvs.texi(,6902) substitution} (or @dfn{keyword expansion}) to help
cvs.texi(,6903) identifying the files.  Embedded strings of the form
cvs.texi(,6904) @code{$@var{keyword}$} and
cvs.texi(,6905) @code{$@var{keyword}:@dots{}$} in a file are replaced
cvs.texi(,6906) with strings of the form
cvs.texi(,6907) @code{$@var{keyword}:@var{value}$} whenever you obtain
cvs.texi(,6908) a new revision of the file.
cvs.texi(,6909) 
cvs.texi(,6910) @menu
cvs.texi(,6911) * Keyword list::                   Keywords
cvs.texi(,6912) * Using keywords::                 Using keywords
cvs.texi(,6913) * Avoiding substitution::          Avoiding substitution
cvs.texi(,6914) * Substitution modes::             Substitution modes
cvs.texi(,6915) * Configuring keyword expansion::  Configuring keyword expansion
cvs.texi(splitrcskeyword,6916) * Log keyword::                    Problems with the $@i{}Log$ keyword.
cvs.texi(,6917) @end menu
cvs.texi(,6918) 
cvs.texi(,6919) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,6920) @node Keyword list
cvs.texi(,6921) @section Keyword List
cvs.texi(,6922) @cindex Keyword List
cvs.texi(,6923) 
cvs.texi(,6924) @c FIXME: need some kind of example here I think,
cvs.texi(,6925) @c perhaps in a
cvs.texi(,6926) @c "Keyword intro" node.  The intro in the "Keyword
cvs.texi(,6927) @c substitution" node itself seems OK, but to launch
cvs.texi(,6928) @c into a list of the keywords somehow seems too abrupt.
cvs.texi(,6929) 
cvs.texi(,6930) This is a list of the keywords:
cvs.texi(,6931) 
cvs.texi(,6932) @table @code
cvs.texi(,6933) @cindex Author keyword
cvs.texi(splitrcskeyword,6934) @item $@i{}Author$
cvs.texi(,6935) The login name of the user who checked in the revision.
cvs.texi(,6936) 
cvs.texi(,6937) @cindex CVSHeader keyword
cvs.texi(splitrcskeyword,6938) @item $@i{}CVSHeader
cvs.texi(splitrcskeyword,6939) A standard header (similar to $@i{}Header$, but with
cvs.texi(,6940) the CVS root stripped off). It contains the relative
cvs.texi(,6941) pathname of the @sc{rcs} file to the CVS root, the
cvs.texi(,6942) revision number, the date (UTC), the author, the state,
cvs.texi(,6943) and the locker (if locked). Files will normally never
cvs.texi(,6944) be locked when you use @sc{cvs}.
cvs.texi(,6945) 
cvs.texi(,6946) Note that this keyword has only been recently
cvs.texi(,6947) introduced to @sc{cvs} and may cause problems with
cvs.texi(splitrcskeyword,6948) existing installations if $@i{}CVSHeader$ is already
cvs.texi(,6949) in the files for a different purpose. This keyword may
cvs.texi(,6950) be excluded using the @code{KeywordExpansion=eCVSHeader}
cvs.texi(,6951) in the @file{CVSROOT/config} file. 
cvs.texi(,6952) See @ref{Configuring keyword expansion} for more details.
cvs.texi(,6953) 
cvs.texi(,6954) @cindex Date keyword
cvs.texi(splitrcskeyword,6955) @item $@i{}Date$
cvs.texi(,6956) The date and time (UTC) the revision was checked in.
cvs.texi(,6957) 
cvs.texi(,6958) @cindex Header keyword
cvs.texi(splitrcskeyword,6959) @item $@i{}Header$
cvs.texi(,6960) A standard header containing the full pathname of the
cvs.texi(,6961) @sc{rcs} file, the revision number, the date (UTC), the
cvs.texi(,6962) author, the state, and the locker (if locked).  Files
cvs.texi(,6963) will normally never be locked when you use @sc{cvs}.
cvs.texi(,6964) 
cvs.texi(,6965) @cindex Id keyword
cvs.texi(splitrcskeyword,6966) @item $@i{}Id$
cvs.texi(splitrcskeyword,6967) Same as @code{$@i{}Header$}, except that the @sc{rcs}
cvs.texi(,6968) filename is without a path.
cvs.texi(,6969) 
cvs.texi(,6970) @cindex Name keyword
cvs.texi(splitrcskeyword,6971) @item $@i{}Name$
cvs.texi(,6972) Tag name used to check out this file.  The keyword is
cvs.texi(,6973) expanded only if one checks out with an explicit tag
cvs.texi(,6974) name.  For example, when running the command @code{cvs
cvs.texi(,6975) co -r first}, the keyword expands to @samp{Name: first}.
cvs.texi(,6976) 
cvs.texi(,6977) @cindex Locker keyword
cvs.texi(splitrcskeyword,6978) @item $@i{}Locker$
cvs.texi(,6979) The login name of the user who locked the revision
cvs.texi(,6980) (empty if not locked, which is the normal case unless
cvs.texi(,6981) @code{cvs admin -l} is in use).
cvs.texi(,6982) 
cvs.texi(,6983) @cindex Log keyword
cvs.texi(splitrcskeyword,6984) @item $@i{}Log$
cvs.texi(,6985) The log message supplied during commit, preceded by a
cvs.texi(,6986) header containing the @sc{rcs} filename, the revision
cvs.texi(,6987) number, the author, and the date (UTC).  Existing log
cvs.texi(,6988) messages are @emph{not} replaced.  Instead, the new log
cvs.texi(splitrcskeyword,6989) message is inserted after @code{$@i{}Log:@dots{}$}.
cvs.texi(,6990) Each new line is prefixed with the same string which
cvs.texi(,6991) precedes the @code{$Log} keyword.  For example, if the
cvs.texi(,6992) file contains:
cvs.texi(,6993) 
cvs.texi(,6994) @example
cvs.texi(,6995)   /* Here is what people have been up to:
cvs.texi(,6996)    *
cvs.texi(splitrcskeyword,6997)    * $@i{}Log: frob.c,v $
cvs.texi(,6998)    * Revision 1.1  1997/01/03 14:23:51  joe
cvs.texi(,6999)    * Add the superfrobnicate option
cvs.texi(,7000)    *
cvs.texi(,7001)    */
cvs.texi(,7002) @end example
cvs.texi(,7003) 
cvs.texi(,7004) @noindent
cvs.texi(,7005) then additional lines which are added when expanding
cvs.texi(,7006) the @code{$Log} keyword will be preceded by @samp{   * }.
cvs.texi(,7007) Unlike previous versions of @sc{cvs} and @sc{rcs}, the
cvs.texi(,7008) @dfn{comment leader} from the @sc{rcs} file is not used.
cvs.texi(,7009) The @code{$Log} keyword is useful for
cvs.texi(,7010) accumulating a complete change log in a source file,
cvs.texi(,7011) but for several reasons it can be problematic.
cvs.texi(,7012) @xref{Log keyword}.
cvs.texi(,7013) 
cvs.texi(,7014) @cindex RCSfile keyword
cvs.texi(splitrcskeyword,7015) @item $@i{}RCSfile$
cvs.texi(,7016) The name of the RCS file without a path.
cvs.texi(,7017) 
cvs.texi(,7018) @cindex Revision keyword
cvs.texi(splitrcskeyword,7019) @item $@i{}Revision$
cvs.texi(,7020) The revision number assigned to the revision.
cvs.texi(,7021) 
cvs.texi(,7022) @cindex Source keyword
cvs.texi(splitrcskeyword,7023) @item $@i{}Source$
cvs.texi(,7024) The full pathname of the RCS file.
cvs.texi(,7025) 
cvs.texi(,7026) @cindex State keyword
cvs.texi(splitrcskeyword,7027) @item $@i{}State$
cvs.texi(,7028) The state assigned to the revision.  States can be
cvs.texi(,7029) assigned with @code{cvs admin -s}---see @ref{admin options}.
cvs.texi(,7030) 
cvs.texi(,7031) @cindex Local keyword
cvs.texi(,7032) @item Local keyword
cvs.texi(,7033) The @code{LocalKeyword} option in the @file{CVSROOT/config} file
cvs.texi(,7034) may be used to specify a local keyword which is to be
cvs.texi(,7035) used as an alias for one of the other keywords. For
cvs.texi(,7036) example, if the @file{CVSROOT/config} file contains
cvs.texi(,7037) a line with @code{LocalKeyword=MYBSD=CVSHeader}, then a
cvs.texi(splitrcskeyword,7038) file with the local keyword $@i{}MYBSD$ will be
cvs.texi(splitrcskeyword,7039) expanded as if it were a $@i{}CVSHeader$ keyword. If
cvs.texi(,7040) the src/frob.c file contained this keyword, it might
cvs.texi(,7041) look something like this:
cvs.texi(,7042) 
cvs.texi(,7043) @example
cvs.texi(,7044)   /*
cvs.texi(splitrcskeyword,7045)    * $@i{}MYBSD: src/frob.c,v 1.1 2003/05/04 09:27:45 john Exp $ 
cvs.texi(,7046)    */
cvs.texi(,7047) @end example
cvs.texi(,7048) 
cvs.texi(,7049) Many repositories make use of a such a ``local
cvs.texi(,7050) keyword'' feature. An old patch to @sc{cvs} provided
cvs.texi(,7051) the @code{LocalKeyword} feature using a @code{tag=}
cvs.texi(,7052) option and called this the ``custom tag'' or ``local
cvs.texi(,7053) tag'' feature. It was used in conjunction with the
cvs.texi(,7054) what they called the @code{tagexpand=} option. In
cvs.texi(,7055) @sc{cvs} this other option is known as the
cvs.texi(,7056) @code{KeywordExpand} option. 
cvs.texi(,7057) See @ref{Configuring keyword expansion} for more
cvs.texi(,7058) details.
cvs.texi(,7059) 
cvs.texi(,7060) Examples from popular projects include:
cvs.texi(splitrcskeyword,7061) $@i{}FreeBSD$, $@i{}NetBSD$,
cvs.texi(splitrcskeyword,7062) $@i{}OpenBSD$, $@i{}XFree86$,
cvs.texi(splitrcskeyword,7063) $@i{}Xorg$.
cvs.texi(,7064) 
cvs.texi(,7065) The advantage of this is that you can include your
cvs.texi(,7066) local version information in a file using this local
cvs.texi(,7067) keyword without disrupting the upstream version
cvs.texi(,7068) information (which may be a different local keyword or
cvs.texi(,7069) a standard keyword). Allowing bug reports and the like
cvs.texi(,7070) to more properly identify the source of the original
cvs.texi(,7071) bug to the third-party and reducing the number of
cvs.texi(,7072) conflicts that arise during an import of a new version.
cvs.texi(,7073) 
cvs.texi(,7074) All keyword expansion except the local keyword may be
cvs.texi(,7075) disabled using the @code{KeywordExpansion} option in
cvs.texi(,7076) the @file{CVSROOT/config} file---see 
cvs.texi(,7077) @ref{Configuring keyword expansion} for more details.
cvs.texi(,7078) 
cvs.texi(,7079) @end table
cvs.texi(,7080) 
cvs.texi(,7081) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,7082) @node Using keywords
cvs.texi(,7083) @section Using keywords
cvs.texi(,7084) 
cvs.texi(,7085) To include a keyword string you simply include the
cvs.texi(splitrcskeyword,7086) relevant text string, such as @code{$@i{}Id$}, inside the
cvs.texi(,7087) file, and commit the file.  @sc{cvs} will automatically
cvs.texi(,7088) expand the string as part of the commit operation.
cvs.texi(,7089) 
cvs.texi(splitrcskeyword,7090) It is common to embed the @code{$@i{}Id$} string in
cvs.texi(,7091) the source files so that it gets passed through to
cvs.texi(,7092) generated files.  For example, if you are managing
cvs.texi(,7093) computer program source code, you might include a
cvs.texi(,7094) variable which is initialized to contain that string.
cvs.texi(,7095) Or some C compilers may provide a @code{#pragma ident}
cvs.texi(,7096) directive.  Or a document management system might
cvs.texi(,7097) provide a way to pass a string through to generated
cvs.texi(,7098) files.
cvs.texi(,7099) 
cvs.texi(,7100) @c Would be nice to give an example, but doing this in
cvs.texi(,7101) @c portable C is not possible and the problem with
cvs.texi(,7102) @c picking any one language (VMS HELP files, Ada,
cvs.texi(,7103) @c troff, whatever) is that people use CVS for all
cvs.texi(,7104) @c kinds of files.
cvs.texi(,7105) 
cvs.texi(,7106) @cindex Ident (shell command)
cvs.texi(,7107) The @code{ident} command (which is part of the @sc{rcs}
cvs.texi(,7108) package) can be used to extract keywords and their
cvs.texi(,7109) values from a file.  This can be handy for text files,
cvs.texi(,7110) but it is even more useful for extracting keywords from
cvs.texi(,7111) binary files.
cvs.texi(,7112) 
cvs.texi(,7113) @example
cvs.texi(,7114) $ ident samp.c
cvs.texi(,7115) samp.c:
cvs.texi(splitrcskeyword,7116)      $@i{}Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
cvs.texi(,7117) $ gcc samp.c
cvs.texi(,7118) $ ident a.out
cvs.texi(,7119) a.out:
cvs.texi(splitrcskeyword,7120)      $@i{}Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
cvs.texi(,7121) @end example
cvs.texi(,7122) 
cvs.texi(,7123) @cindex What (shell command)
cvs.texi(,7124) S@sc{ccs} is another popular revision control system.
cvs.texi(,7125) It has a command, @code{what}, which is very similar to
cvs.texi(,7126) @code{ident} and used for the same purpose.  Many sites
cvs.texi(,7127) without @sc{rcs} have @sc{sccs}.  Since @code{what}
cvs.texi(,7128) looks for the character sequence @code{@@(#)} it is
cvs.texi(,7129) easy to include keywords that are detected by either
cvs.texi(,7130) command.  Simply prefix the keyword with the
cvs.texi(,7131) magic @sc{sccs} phrase, like this:
cvs.texi(,7132) 
cvs.texi(,7133) @example
cvs.texi(splitrcskeyword,7134) static char *id="@@(#) $@i{}Id: ab.c,v 1.5 1993/10/19 14:57:32 ceder Exp $";
cvs.texi(,7135) @end example
cvs.texi(,7136) 
cvs.texi(,7137) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,7138) @node Avoiding substitution
cvs.texi(,7139) @section Avoiding substitution
cvs.texi(,7140) 
cvs.texi(,7141) Keyword substitution has its disadvantages.  Sometimes
cvs.texi(,7142) you might want the literal text string
cvs.texi(splitrcskeyword,7143) @samp{$@i{}Author$} to appear inside a file without
cvs.texi(,7144) @sc{cvs} interpreting it as a keyword and expanding it
cvs.texi(splitrcskeyword,7145) into something like @samp{$@i{}Author: ceder $}.
cvs.texi(,7146) 
cvs.texi(,7147) There is unfortunately no way to selectively turn off
cvs.texi(,7148) keyword substitution.  You can use @samp{-ko}
cvs.texi(,7149) (@pxref{Substitution modes}) to turn off keyword
cvs.texi(,7150) substitution entirely.
cvs.texi(,7151) 
cvs.texi(,7152) In many cases you can avoid using keywords in
cvs.texi(,7153) the source, even though they appear in the final
cvs.texi(,7154) product.  For example, the source for this manual
cvs.texi(,7155) contains @samp{$@@asis@{@}Author$} whenever the text
cvs.texi(splitrcskeyword,7156) @samp{$@i{}Author$} should appear.  In @code{nroff}
cvs.texi(,7157) and @code{troff} you can embed the null-character
cvs.texi(,7158) @code{\&} inside the keyword for a similar effect.
cvs.texi(,7159) 
cvs.texi(,7160) It is also possible to specify an explicit list of
cvs.texi(,7161) keywords to include or exclude using the
cvs.texi(,7162) @code{KeywordExpand} option in the
cvs.texi(,7163) @file{CVSROOT/config} file--see @ref{Configuring keyword expansion}
cvs.texi(,7164) for more details. This feature is intended primarily
cvs.texi(,7165) for use with the @code{LocalKeyword} option--see
cvs.texi(,7166) @ref{Keyword list}.
cvs.texi(,7167) 
cvs.texi(,7168) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,7169) @node Substitution modes
cvs.texi(,7170) @section Substitution modes
cvs.texi(,7171) @cindex Keyword substitution, changing modes
cvs.texi(,7172) @cindex -k (keyword substitution)
cvs.texi(,7173) @cindex Kflag
cvs.texi(,7174) 
cvs.texi(,7175) @c FIXME: This could be made more coherent, by expanding it
cvs.texi(,7176) @c with more examples or something.
cvs.texi(,7177) Each file has a stored default substitution mode, and
cvs.texi(,7178) each working directory copy of a file also has a
cvs.texi(,7179) substitution mode.  The former is set by the @samp{-k}
cvs.texi(,7180) option to @code{cvs add} and @code{cvs admin}; the
cvs.texi(,7181) latter is set by the @samp{-k} or @samp{-A} options to @code{cvs
cvs.texi(,7182) checkout} or @code{cvs update}.  @code{cvs diff} also
cvs.texi(,7183) has a @samp{-k} option.  For some examples,
cvs.texi(,7184) see @ref{Binary files}, and @ref{Merging and keywords}.
cvs.texi(,7185) @c The fact that -A is overloaded to mean both reset
cvs.texi(,7186) @c sticky options and reset sticky tags/dates is
cvs.texi(,7187) @c somewhat questionable.  Perhaps there should be
cvs.texi(,7188) @c separate options to reset sticky options (e.g. -k
cvs.texi(,7189) @c A") and tags/dates (someone suggested -r HEAD could
cvs.texi(,7190) @c do this instead of setting a sticky tag of "HEAD"
cvs.texi(,7191) @c as in the status quo but I haven't thought much
cvs.texi(,7192) @c about that idea.  Of course -r .reset or something
cvs.texi(,7193) @c could be coined if this needs to be a new option).
cvs.texi(,7194) @c On the other hand, having -A mean "get things back
cvs.texi(,7195) @c into the state after a fresh checkout" has a certain
cvs.texi(,7196) @c appeal, and maybe there is no sufficient reason for
cvs.texi(,7197) @c creeping featurism in this area.
cvs.texi(,7198) 
cvs.texi(,7199) The modes available are:
cvs.texi(,7200) 
cvs.texi(,7201) @table @samp
cvs.texi(,7202) @item -kkv
cvs.texi(,7203) Generate keyword strings using the default form, e.g.
cvs.texi(splitrcskeyword,7204) @code{$@i{}Revision: 5.7 $} for the @code{Revision}
cvs.texi(,7205) keyword.
cvs.texi(,7206) 
cvs.texi(,7207) @item -kkvl
cvs.texi(,7208) Like @samp{-kkv}, except that a locker's name is always
cvs.texi(,7209) inserted if the given revision is currently locked.
cvs.texi(,7210) The locker's name is only relevant if @code{cvs admin
cvs.texi(,7211) -l} is in use.
cvs.texi(,7212) 
cvs.texi(,7213) @item -kk
cvs.texi(,7214) Generate only keyword names in keyword strings; omit
cvs.texi(,7215) their values.  For example, for the @code{Revision}
cvs.texi(splitrcskeyword,7216) keyword, generate the string @code{$@i{}Revision$}
cvs.texi(splitrcskeyword,7217) instead of @code{$@i{}Revision: 5.7 $}.  This option
cvs.texi(,7218) is useful to ignore differences due to keyword
cvs.texi(,7219) substitution when comparing different revisions of a
cvs.texi(,7220) file (@pxref{Merging and keywords}).
cvs.texi(,7221) 
cvs.texi(,7222) @item -ko
cvs.texi(,7223) Generate the old keyword string, present in the working
cvs.texi(,7224) file just before it was checked in.  For example, for
cvs.texi(,7225) the @code{Revision} keyword, generate the string
cvs.texi(splitrcskeyword,7226) @code{$@i{}Revision: 1.1 $} instead of
cvs.texi(splitrcskeyword,7227) @code{$@i{}Revision: 5.7 $} if that is how the
cvs.texi(,7228) string appeared when the file was checked in.
cvs.texi(,7229) 
cvs.texi(,7230) @item -kb
cvs.texi(,7231) Like @samp{-ko}, but also inhibit conversion of line
cvs.texi(,7232) endings between the canonical form in which they are
cvs.texi(,7233) stored in the repository (linefeed only), and the form
cvs.texi(,7234) appropriate to the operating system in use on the
cvs.texi(,7235) client.  For systems, like unix, which use linefeed
cvs.texi(,7236) only to terminate lines, this is very similar to
cvs.texi(,7237) @samp{-ko}.  For more information on binary files, see
cvs.texi(,7238) @ref{Binary files}.  In @sc{cvs} version 1.12.2 and later
cvs.texi(,7239) @samp{-kb}, as set by @code{cvs add}, @code{cvs admin}, or
cvs.texi(,7240) @code{cvs import} may not be overridden by a @samp{-k} option
cvs.texi(,7241) specified on the command line.
cvs.texi(,7242) 
cvs.texi(,7243) @item -kv
cvs.texi(,7244) Generate only keyword values for keyword strings.  For
cvs.texi(,7245) example, for the @code{Revision} keyword, generate the string
cvs.texi(splitrcskeyword,7246) @code{5.7} instead of @code{$@i{}Revision: 5.7 $}.
cvs.texi(,7247) This can help generate files in programming languages
cvs.texi(,7248) where it is hard to strip keyword delimiters like
cvs.texi(splitrcskeyword,7249) @code{$@i{}Revision: $} from a string.  However,
cvs.texi(,7250) further keyword substitution cannot be performed once
cvs.texi(,7251) the keyword names are removed, so this option should be
cvs.texi(,7252) used with care.
cvs.texi(,7253) 
cvs.texi(,7254) One often would like to use @samp{-kv} with @code{cvs
cvs.texi(,7255) export}---@pxref{export}.  But be aware that doesn't
cvs.texi(,7256) handle an export containing binary files correctly.
cvs.texi(,7257) 
cvs.texi(,7258) @end table
cvs.texi(,7259) 
cvs.texi(,7260) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,7261) @node Configuring keyword expansion
cvs.texi(,7262) @section Configuring Keyord Expansion
cvs.texi(,7263) @cindex Configuring keyword expansion
cvs.texi(,7264) 
cvs.texi(,7265) In a repository that includes third-party software on
cvs.texi(,7266) vendor branches, it is sometimes helpful to configure
cvs.texi(,7267) CVS to use a local keyword instead of the standard
cvs.texi(splitrcskeyword,7268) $@i{}Id$ or $@i{}Header$ keywords. Examples from
cvs.texi(splitrcskeyword,7269) real projects includ, $@i{}Xorg$, $@i{}XFree86$,
cvs.texi(splitrcskeyword,7270) $@i{}FreeBSD$, $@i{}NetBSD$,
cvs.texi(splitrcskeyword,7271) $@i{}OpenBSD$, and even $@i{}dotat$.
cvs.texi(,7272) The advantage of this is that
cvs.texi(,7273) you can include your local version information in a
cvs.texi(,7274) file using this local keyword (sometimes called a
cvs.texi(,7275) ``custom tag'' or a ``local tag'') without disrupting
cvs.texi(,7276) the upstream version information (which may be a
cvs.texi(,7277) different local keyword or a standard keyword). In
cvs.texi(,7278) these cases, it is typically desirable to disable the
cvs.texi(,7279) expansion of all keywords except the configured local
cvs.texi(,7280) keyword.
cvs.texi(,7281) 
cvs.texi(,7282) The @code{KeywordExpansion} option in the
cvs.texi(,7283) @file{CVSROOT/config} file is intended to allow for the
cvs.texi(,7284) either the explicit exclusion of a keyword or list of
cvs.texi(,7285) keywords, or for the explicit inclusion of a keyword or
cvs.texi(,7286) a list of keywords. This list may include the
cvs.texi(,7287) @code{LocalKeyword} that has been configured.
cvs.texi(,7288) 
cvs.texi(,7289) The @code{KeywordExpansion} option is followed by
cvs.texi(,7290) @code{=} and the next character may either be @code{i}
cvs.texi(,7291) to start an inclusion list or @code{e} to start an
cvs.texi(,7292) exclusion list. If the following lines were added to
cvs.texi(,7293) the @file{CVSROOT/config} file:
cvs.texi(,7294) 
cvs.texi(,7295) @example
cvs.texi(,7296)         # Add a "MyBSD" keyword and restrict keyword
cvs.texi(,7297)         # expansion
cvs.texi(,7298)         LocalKeyword=MyBSD=CVSHeader
cvs.texi(,7299)         KeywordExpand=iMyBSD
cvs.texi(,7300) @end example
cvs.texi(,7301) 
cvs.texi(splitrcskeyword,7302) then only the $@i{}MyBSD$ keyword would be expanded.
cvs.texi(,7303) A list may be used. The this example:
cvs.texi(,7304) 
cvs.texi(,7305) @example
cvs.texi(,7306)         # Add a "MyBSD" keyword and restrict keyword
cvs.texi(,7307)         # expansion to the MyBSD, Name and Date keywords.
cvs.texi(,7308)         LocalKeyword=MyBSD=CVSHeader
cvs.texi(,7309)         KeywordExpand=iMyBSD,Name,Date
cvs.texi(,7310) @end example
cvs.texi(,7311) 
cvs.texi(splitrcskeyword,7312) would allow $@i{}MyBSD$, $@i{}Name$, and
cvs.texi(splitrcskeyword,7313) $@i{}Date$ to be expanded.
cvs.texi(,7314) 
cvs.texi(,7315) It is also possible to configure an exclusion list
cvs.texi(,7316) using the following:
cvs.texi(,7317) 
cvs.texi(,7318) @example
cvs.texi(,7319)         # Do not expand the non-RCS keyword CVSHeader
cvs.texi(,7320)         KeywordExpand=eCVSHeader
cvs.texi(,7321) @end example
cvs.texi(,7322) 
cvs.texi(,7323) This allows @sc{cvs} to ignore the recently introduced
cvs.texi(splitrcskeyword,7324) $@i{}CVSHeader$ keyword and retain all of the
cvs.texi(,7325) others. The exclusion entry could also contain the
cvs.texi(,7326) standard RCS keyword list, but this could be confusing
cvs.texi(,7327) to users that expect RCS keywords to be expanded, so
cvs.texi(,7328) ycare should be taken to properly set user expectations
cvs.texi(,7329) for a repository that is configured in that manner.
cvs.texi(,7330) 
cvs.texi(,7331) If there is a desire to not have any RCS keywords
cvs.texi(,7332) expanded and not use the @code{-ko} flags everywhere,
cvs.texi(,7333) an administrator may disable all keyword expansion
cvs.texi(,7334) using the @file{CVSROOT/config} line:
cvs.texi(,7335) 
cvs.texi(,7336) @example
cvs.texi(,7337) 	# Do not expand any RCS keywords
cvs.texi(,7338) 	KeywordExpand=i
cvs.texi(,7339) @end example
cvs.texi(,7340) 
cvs.texi(,7341) this could be confusing to users that expect RCS
cvs.texi(splitrcskeyword,7342) keywords like $@i{}Id$ to be expanded properly,
cvs.texi(,7343) so care should be taken to properly set user
cvs.texi(,7344) expectations for a repository so configured.
cvs.texi(,7345) 
cvs.texi(,7346) It should be noted that a patch to provide both the
cvs.texi(,7347) @code{KeywordExpand} and @code{LocalKeyword} features
cvs.texi(,7348) has been around a long time. However, that patch
cvs.texi(,7349) implemented these features using @code{tag=} and
cvs.texi(,7350) @code{tagexpand=} keywords and those keywords are NOT
cvs.texi(,7351) recognized.
cvs.texi(,7352) 
cvs.texi(,7353) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,7354) @node Log keyword
cvs.texi(splitrcskeyword,7355) @section Problems with the $@i{}Log$ keyword.
cvs.texi(,7356) 
cvs.texi(splitrcskeyword,7357) The @code{$@i{}Log$} keyword is somewhat
cvs.texi(,7358) controversial.  As long as you are working on your
cvs.texi(,7359) development system the information is easily accessible
cvs.texi(splitrcskeyword,7360) even if you do not use the @code{$@i{}Log$}
cvs.texi(,7361) keyword---just do a @code{cvs log}.  Once you export
cvs.texi(,7362) the file the history information might be useless
cvs.texi(,7363) anyhow.
cvs.texi(,7364) 
cvs.texi(,7365) A more serious concern is that @sc{cvs} is not good at
cvs.texi(splitrcskeyword,7366) handling @code{$@i{}Log$} entries when a branch is
cvs.texi(,7367) merged onto the main trunk.  Conflicts often result
cvs.texi(,7368) from the merging operation.
cvs.texi(,7369) @c Might want to check whether the CVS implementation
cvs.texi(,7370) @c of RCS_merge has this problem the same way rcsmerge
cvs.texi(,7371) @c does.  I would assume so....
cvs.texi(,7372) 
cvs.texi(,7373) People also tend to "fix" the log entries in the file
cvs.texi(,7374) (correcting spelling mistakes and maybe even factual
cvs.texi(,7375) errors).  If that is done the information from
cvs.texi(,7376) @code{cvs log} will not be consistent with the
cvs.texi(,7377) information inside the file.  This may or may not be a
cvs.texi(,7378) problem in real life.
cvs.texi(,7379) 
cvs.texi(splitrcskeyword,7380) It has been suggested that the @code{$@i{}Log$}
cvs.texi(,7381) keyword should be inserted @emph{last} in the file, and
cvs.texi(,7382) not in the files header, if it is to be used at all.
cvs.texi(,7383) That way the long list of change messages will not
cvs.texi(,7384) interfere with everyday source file browsing.
cvs.texi(,7385) 
cvs.texi(,7386) @c ---------------------------------------------------------------------
cvs.texi(,7387) @node Tracking sources
cvs.texi(,7388) @chapter Tracking third-party sources
cvs.texi(,7389) @cindex Third-party sources
cvs.texi(,7390) @cindex Tracking sources
cvs.texi(,7391) 
cvs.texi(,7392) @c FIXME: Need discussion of added and removed files.
cvs.texi(,7393) @c FIXME: This doesn't really adequately introduce the
cvs.texi(,7394) @c concepts of "vendor" and "you".  They don't *have*
cvs.texi(,7395) @c to be separate organizations or separate people.
cvs.texi(,7396) @c We want a description which is somewhat more based on
cvs.texi(,7397) @c the technical issues of which sources go where, but
cvs.texi(,7398) @c also with enough examples of how this relates to
cvs.texi(,7399) @c relationships like customer-supplier, developer-QA,
cvs.texi(,7400) @c maintainer-contributor, or whatever, to make it
cvs.texi(,7401) @c seem concrete.
cvs.texi(,7402) If you modify a program to better fit your site, you
cvs.texi(,7403) probably want to include your modifications when the next
cvs.texi(,7404) release of the program arrives.  @sc{cvs} can help you with
cvs.texi(,7405) this task.
cvs.texi(,7406) 
cvs.texi(,7407) @cindex Vendor
cvs.texi(,7408) @cindex Vendor branch
cvs.texi(,7409) @cindex Branch, vendor-
cvs.texi(,7410) In the terminology used in @sc{cvs}, the supplier of the
cvs.texi(,7411) program is called a @dfn{vendor}.  The unmodified
cvs.texi(,7412) distribution from the vendor is checked in on its own
cvs.texi(,7413) branch, the @dfn{vendor branch}.  @sc{cvs} reserves branch
cvs.texi(,7414) 1.1.1 for this use.
cvs.texi(,7415) 
cvs.texi(,7416) When you modify the source and commit it, your revision
cvs.texi(,7417) will end up on the main trunk.  When a new release is
cvs.texi(,7418) made by the vendor, you commit it on the vendor branch
cvs.texi(,7419) and copy the modifications onto the main trunk.
cvs.texi(,7420) 
cvs.texi(,7421) Use the @code{import} command to create and update
cvs.texi(,7422) the vendor branch.  When you import a new file,
cvs.texi(,7423) the vendor branch is made the `head' revision, so
cvs.texi(,7424) anyone that checks out a copy of the file gets that
cvs.texi(,7425) revision.  When a local modification is committed it is
cvs.texi(,7426) placed on the main trunk, and made the `head'
cvs.texi(,7427) revision.
cvs.texi(,7428) 
cvs.texi(,7429) @menu
cvs.texi(,7430) * First import::                Importing for the first time
cvs.texi(,7431) * Update imports::              Updating with the import command
cvs.texi(,7432) * Reverting local changes::     Reverting to the latest vendor release
cvs.texi(,7433) * Binary files in imports::     Binary files require special handling
cvs.texi(,7434) * Keywords in imports::         Keyword substitution might be undesirable
cvs.texi(,7435) * Multiple vendor branches::    What if you get sources from several places?
cvs.texi(,7436) @end menu
cvs.texi(,7437) 
cvs.texi(,7438) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,7439) @node First import
cvs.texi(,7440) @section Importing for the first time
cvs.texi(,7441) @cindex Importing modules
cvs.texi(,7442) 
cvs.texi(,7443) @c Should mention naming conventions for vendor tags,
cvs.texi(,7444) @c release tags, and perhaps directory names.
cvs.texi(,7445) Use the @code{import} command to check in the sources
cvs.texi(,7446) for the first time.  When you use the @code{import}
cvs.texi(,7447) command to track third-party sources, the @dfn{vendor
cvs.texi(,7448) tag} and @dfn{release tags} are useful.  The
cvs.texi(,7449) @dfn{vendor tag} is a symbolic name for the branch
cvs.texi(,7450) (which is always 1.1.1, unless you use the @samp{-b
cvs.texi(,7451) @var{branch}} flag---see @ref{Multiple vendor branches}.).  The
cvs.texi(,7452) @dfn{release tags} are symbolic names for a particular
cvs.texi(,7453) release, such as @samp{FSF_0_04}.
cvs.texi(,7454) 
cvs.texi(,7455) @c I'm not completely sure this belongs here.  But
cvs.texi(,7456) @c we need to say it _somewhere_ reasonably obvious; it
cvs.texi(,7457) @c is a common misconception among people first learning CVS
cvs.texi(,7458) Note that @code{import} does @emph{not} change the
cvs.texi(,7459) directory in which you invoke it.  In particular, it
cvs.texi(,7460) does not set up that directory as a @sc{cvs} working
cvs.texi(,7461) directory; if you want to work with the sources import
cvs.texi(,7462) them first and then check them out into a different
cvs.texi(,7463) directory (@pxref{Getting the source}).
cvs.texi(,7464) 
cvs.texi(,7465) @cindex wdiff (import example)
cvs.texi(,7466) Suppose you have the sources to a program called
cvs.texi(,7467) @code{wdiff} in a directory @file{wdiff-0.04},
cvs.texi(,7468) and are going to make private modifications that you
cvs.texi(,7469) want to be able to use even when new releases are made
cvs.texi(,7470) in the future.  You start by importing the source to
cvs.texi(,7471) your repository:
cvs.texi(,7472) 
cvs.texi(,7473) @example
cvs.texi(,7474) $ cd wdiff-0.04
cvs.texi(,7475) $ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04
cvs.texi(,7476) @end example
cvs.texi(,7477) 
cvs.texi(,7478) The vendor tag is named @samp{FSF_DIST} in the above
cvs.texi(,7479) example, and the only release tag assigned is
cvs.texi(,7480) @samp{WDIFF_0_04}.
cvs.texi(,7481) @c FIXME: Need to say where fsf/wdiff comes from.
cvs.texi(,7482) 
cvs.texi(,7483) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,7484) @node Update imports
cvs.texi(,7485) @section Updating with the import command
cvs.texi(,7486) 
cvs.texi(,7487) When a new release of the source arrives, you import it into the
cvs.texi(,7488) repository with the same @code{import} command that you used to set up
cvs.texi(,7489) the repository in the first place.  The only difference is that you
cvs.texi(,7490) specify a different release tag this time:
cvs.texi(,7491) 
cvs.texi(,7492) @example
cvs.texi(,7493) $ tar xfz wdiff-0.05.tar.gz
cvs.texi(,7494) $ cd wdiff-0.05
cvs.texi(,7495) $ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF_DIST WDIFF_0_05
cvs.texi(,7496) @end example
cvs.texi(,7497) 
cvs.texi(,7498) For files that have not been modified locally, the newly created
cvs.texi(,7499) revision becomes the head revision.  If you have made local
cvs.texi(,7500) changes, @code{import} will warn you that you must merge the changes
cvs.texi(,7501) into the main trunk, and tell you to use @samp{checkout -j} to do so:
cvs.texi(,7502) 
cvs.texi(,7503) @c FIXME: why "wdiff" here and "fsf/wdiff" in the
cvs.texi(,7504) @c "import"?  I think the assumption is that one has
cvs.texi(,7505) @c "wdiff fsf/wdiff" or some such in modules, but it
cvs.texi(,7506) @c would be better to not use modules in this example.
cvs.texi(,7507) @example
cvs.texi(,7508) $ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff
cvs.texi(,7509) @end example
cvs.texi(,7510) 
cvs.texi(,7511) @noindent
cvs.texi(,7512) The above command will check out the latest revision of
cvs.texi(,7513) @samp{wdiff}, merging the changes made on the vendor branch @samp{FSF_DIST}
cvs.texi(,7514) since yesterday into the working copy.  If any conflicts arise during
cvs.texi(,7515) the merge they should be resolved in the normal way (@pxref{Conflicts
cvs.texi(,7516) example}).  Then, the modified files may be committed.
cvs.texi(,7517) 
cvs.texi(,7518) However, it is much better to use the two release tags rather than using
cvs.texi(,7519) a date on the branch as suggested above:
cvs.texi(,7520) 
cvs.texi(,7521) @example
cvs.texi(,7522) $ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff
cvs.texi(,7523) @end example
cvs.texi(,7524) 
cvs.texi(,7525) @noindent
cvs.texi(,7526) The reason this is better is that
cvs.texi(,7527) using a date, as suggested above, assumes that you do
cvs.texi(,7528) not import more than one release of a product per day.
cvs.texi(,7529) More importantly, using the release tags allows @sc{cvs} to detect files
cvs.texi(,7530) that were removed between the two vendor releases and mark them for
cvs.texi(,7531) removal.  Since @code{import} has no way to detect removed files, you
cvs.texi(,7532) should do a merge like this even if @code{import} doesn't tell you to.
cvs.texi(,7533) 
cvs.texi(,7534) @node Reverting local changes
cvs.texi(,7535) @section Reverting to the latest vendor release
cvs.texi(,7536) 
cvs.texi(,7537) You can also revert local changes completely and return
cvs.texi(,7538) to the latest vendor release by changing the `head'
cvs.texi(,7539) revision back to the vendor branch on all files.  For
cvs.texi(,7540) example, if you have a checked-out copy of the sources
cvs.texi(,7541) in @file{~/work.d/wdiff}, and you want to revert to the
cvs.texi(,7542) vendor's version for all the files in that directory,
cvs.texi(,7543) you would type:
cvs.texi(,7544) 
cvs.texi(,7545) @example
cvs.texi(,7546) $ cd ~/work.d/wdiff
cvs.texi(,7547) $ cvs admin -bWDIFF .
cvs.texi(,7548) @end example
cvs.texi(,7549) 
cvs.texi(,7550) @noindent
cvs.texi(,7551) You must specify the @samp{-bWDIFF} without any space
cvs.texi(,7552) after the @samp{-b}.  @xref{admin options}.
cvs.texi(,7553) 
cvs.texi(,7554) @node Binary files in imports
cvs.texi(,7555) @section How to handle binary files with cvs import
cvs.texi(,7556) 
cvs.texi(,7557) Use the @samp{-k} wrapper option to tell import which
cvs.texi(,7558) files are binary.  @xref{Wrappers}.
cvs.texi(,7559) 
cvs.texi(,7560) @node Keywords in imports
cvs.texi(,7561) @section How to handle keyword substitution with cvs import
cvs.texi(,7562) 
cvs.texi(,7563) The sources which you are importing may contain
cvs.texi(,7564) keywords (@pxref{Keyword substitution}).  For example,
cvs.texi(,7565) the vendor may use @sc{cvs} or some other system
cvs.texi(,7566) which uses similar keyword expansion syntax.  If you
cvs.texi(,7567) just import the files in the default fashion, then
cvs.texi(,7568) the keyword expansions supplied by the vendor will
cvs.texi(,7569) be replaced by keyword expansions supplied by your
cvs.texi(,7570) own copy of @sc{cvs}.  It may be more convenient to
cvs.texi(,7571) maintain the expansions supplied by the vendor, so
cvs.texi(,7572) that this information can supply information about
cvs.texi(,7573) the sources that you imported from the vendor.
cvs.texi(,7574) 
cvs.texi(,7575) To maintain the keyword expansions supplied by the
cvs.texi(,7576) vendor, supply the @samp{-ko} option to @code{cvs
cvs.texi(,7577) import} the first time you import the file.
cvs.texi(,7578) This will turn off keyword expansion
cvs.texi(,7579) for that file entirely, so if you want to be more
cvs.texi(,7580) selective you'll have to think about what you want
cvs.texi(,7581) and use the @samp{-k} option to @code{cvs update} or
cvs.texi(,7582) @code{cvs admin} as appropriate.
cvs.texi(,7583) @c Supplying -ko to import if the file already existed
cvs.texi(,7584) @c has no effect.  Not clear to me whether it should
cvs.texi(,7585) @c or not.
cvs.texi(,7586) 
cvs.texi(,7587) @node Multiple vendor branches
cvs.texi(,7588) @section Multiple vendor branches
cvs.texi(,7589) 
cvs.texi(,7590) All the examples so far assume that there is only one
cvs.texi(,7591) vendor from which you are getting sources.  In some
cvs.texi(,7592) situations you might get sources from a variety of
cvs.texi(,7593) places.  For example, suppose that you are dealing with
cvs.texi(,7594) a project where many different people and teams are
cvs.texi(,7595) modifying the software.  There are a variety of ways to
cvs.texi(,7596) handle this, but in some cases you have a bunch of
cvs.texi(,7597) source trees lying around and what you want to do more
cvs.texi(,7598) than anything else is just to all put them in @sc{cvs} so
cvs.texi(,7599) that you at least have them in one place.
cvs.texi(,7600) 
cvs.texi(,7601) For handling situations in which there may be more than
cvs.texi(,7602) one vendor, you may specify the @samp{-b} option to
cvs.texi(,7603) @code{cvs import}.  It takes as an argument the vendor
cvs.texi(,7604) branch to import to.  The default is @samp{-b 1.1.1}.
cvs.texi(,7605) 
cvs.texi(,7606) For example, suppose that there are two teams, the red
cvs.texi(,7607) team and the blue team, that are sending you sources.
cvs.texi(,7608) You want to import the red team's efforts to branch
cvs.texi(,7609) 1.1.1 and use the vendor tag RED.  You want to import
cvs.texi(,7610) the blue team's efforts to branch 1.1.3 and use the
cvs.texi(,7611) vendor tag BLUE.  So the commands you might use are:
cvs.texi(,7612) 
cvs.texi(,7613) @example
cvs.texi(,7614) $ cvs import dir RED RED_1-0
cvs.texi(,7615) $ cvs import -b 1.1.3 dir BLUE BLUE_1-5
cvs.texi(,7616) @end example
cvs.texi(,7617) 
cvs.texi(,7618) Note that if your vendor tag does not match your
cvs.texi(,7619) @samp{-b} option, @sc{cvs} will not detect this case!  For
cvs.texi(,7620) example,
cvs.texi(,7621) 
cvs.texi(,7622) @example
cvs.texi(,7623) $ cvs import -b 1.1.3 dir RED RED_1-0
cvs.texi(,7624) @end example
cvs.texi(,7625) 
cvs.texi(,7626) @noindent
cvs.texi(,7627) Be careful; this kind of mismatch is sure to sow
cvs.texi(,7628) confusion or worse.  I can't think of a useful purpose
cvs.texi(,7629) for the ability to specify a mismatch here, but if you
cvs.texi(,7630) discover such a use, don't.  @sc{cvs} is likely to make this
cvs.texi(,7631) an error in some future release.
cvs.texi(,7632) 
cvs.texi(,7633) @c Probably should say more about the semantics of
cvs.texi(,7634) @c multiple branches.  What about the default branch?
cvs.texi(,7635) @c What about joining (perhaps not as useful with
cvs.texi(,7636) @c multiple branches, or perhaps it is.  Either way
cvs.texi(,7637) @c should be mentioned).
cvs.texi(,7638) 
cvs.texi(,7639) @c I'm not sure about the best location for this.  In
cvs.texi(,7640) @c one sense, it might belong right after we've introduced
cvs.texi(,7641) @c CVS's basic version control model, because people need
cvs.texi(,7642) @c to figure out builds right away.  The current location
cvs.texi(,7643) @c is based on the theory that it kind of akin to the
cvs.texi(,7644) @c "Revision management" section.
cvs.texi(,7645) @node Builds
cvs.texi(,7646) @chapter How your build system interacts with CVS
cvs.texi(,7647) @cindex Builds
cvs.texi(,7648) @cindex make
cvs.texi(,7649) 
cvs.texi(,7650) As mentioned in the introduction, @sc{cvs} does not
cvs.texi(,7651) contain software for building your software from source
cvs.texi(,7652) code.  This section describes how various aspects of
cvs.texi(,7653) your build system might interact with @sc{cvs}.
cvs.texi(,7654) 
cvs.texi(,7655) @c Is there a way to discuss this without reference to
cvs.texi(,7656) @c tools other than CVS?  I'm not sure there is; I
cvs.texi(,7657) @c wouldn't think that people who learn CVS first would
cvs.texi(,7658) @c even have this concern.
cvs.texi(,7659) One common question, especially from people who are
cvs.texi(,7660) accustomed to @sc{rcs}, is how to make their build get
cvs.texi(,7661) an up to date copy of the sources.  The answer to this
cvs.texi(,7662) with @sc{cvs} is two-fold.  First of all, since
cvs.texi(,7663) @sc{cvs} itself can recurse through directories, there
cvs.texi(,7664) is no need to modify your @file{Makefile} (or whatever
cvs.texi(,7665) configuration file your build tool uses) to make sure
cvs.texi(,7666) each file is up to date.  Instead, just use two
cvs.texi(,7667) commands, first @code{cvs -q update} and then
cvs.texi(,7668) @code{make} or whatever the command is to invoke your
cvs.texi(,7669) build tool.  Secondly, you do not necessarily
cvs.texi(,7670) @emph{want} to get a copy of a change someone else made
cvs.texi(,7671) until you have finished your own work.  One suggested
cvs.texi(,7672) approach is to first update your sources, then
cvs.texi(,7673) implement, build and
cvs.texi(,7674) test the change you were thinking of, and then commit
cvs.texi(,7675) your sources (updating first if necessary).  By
cvs.texi(,7676) periodically (in between changes, using the approach
cvs.texi(,7677) just described) updating your entire tree, you ensure
cvs.texi(,7678) that your sources are sufficiently up to date.
cvs.texi(,7679) 
cvs.texi(,7680) @cindex Bill of materials
cvs.texi(,7681) One common need is to record which versions of which
cvs.texi(,7682) source files went into a particular build.  This kind
cvs.texi(,7683) of functionality is sometimes called @dfn{bill of
cvs.texi(,7684) materials} or something similar.  The best way to do
cvs.texi(,7685) this with @sc{cvs} is to use the @code{tag} command to
cvs.texi(,7686) record which versions went into a given build
cvs.texi(,7687) (@pxref{Tags}).
cvs.texi(,7688) 
cvs.texi(,7689) Using @sc{cvs} in the most straightforward manner
cvs.texi(,7690) possible, each developer will have a copy of the entire
cvs.texi(,7691) source tree which is used in a particular build.  If
cvs.texi(,7692) the source tree is small, or if developers are
cvs.texi(,7693) geographically dispersed, this is the preferred
cvs.texi(,7694) solution.  In fact one approach for larger projects is
cvs.texi(,7695) to break a project down into smaller
cvs.texi(,7696) @c I say subsystem instead of module because they may or
cvs.texi(,7697) @c may not use the modules file.
cvs.texi(,7698) separately-compiled subsystems, and arrange a way of
cvs.texi(,7699) releasing them internally so that each developer need
cvs.texi(,7700) check out only those subsystems which they are
cvs.texi(,7701) actively working on.
cvs.texi(,7702) 
cvs.texi(,7703) Another approach is to set up a structure which allows
cvs.texi(,7704) developers to have their own copies of some files, and
cvs.texi(,7705) for other files to access source files from a central
cvs.texi(,7706) location.  Many people have come up with some such a
cvs.texi(,7707) @c two such people are paul@sander.cupertino.ca.us (for
cvs.texi(,7708) @c a previous employer)
cvs.texi(,7709) @c and gtornblo@senet.abb.se (spicm and related tools),
cvs.texi(,7710) @c but as far as I know
cvs.texi(,7711) @c no one has nicely packaged or released such a system (or
cvs.texi(,7712) @c instructions for constructing one).
cvs.texi(,7713) system using features such as the symbolic link feature
cvs.texi(,7714) found in many operating systems, or the @code{VPATH}
cvs.texi(,7715) feature found in many versions of @code{make}.  One build
cvs.texi(,7716) tool which is designed to help with this kind of thing
cvs.texi(,7717) is Odin (see
cvs.texi(,7718) @code{ftp://ftp.cs.colorado.edu/pub/distribs/odin}).
cvs.texi(,7719) @c Should we be saying more about Odin?  Or how you use
cvs.texi(,7720) @c it with CVS?  Also, the Prime Time Freeware for Unix
cvs.texi(,7721) @c disk (see http://www.ptf.com/) has Odin (with a nice
cvs.texi(,7722) @c paragraph summarizing it on the web), so that might be a
cvs.texi(,7723) @c semi-"official" place to point people.
cvs.texi(,7724) @c
cvs.texi(,7725) @c Of course, many non-CVS systems have this kind of
cvs.texi(,7726) @c functionality, for example OSF's ODE
cvs.texi(,7727) @c (http://www.osf.org/ode/) or mk
cvs.texi(,7728) @c (http://www.grin.net/~pzi/mk-3.18.4.docs/mk_toc.html
cvs.texi(,7729) @c He has changed providers in the past; a search engine search
cvs.texi(,7730) @c for "Peter Ziobrzynski" probably won't get too many
cvs.texi(,7731) @c spurious hits :-).  A more stable URL might be
cvs.texi(,7732) @c ftp://ftp.uu.net/pub/cmvc/mk).  But I'm not sure
cvs.texi(,7733) @c there is any point in mentioning them here unless they
cvs.texi(,7734) @c can work with CVS.
cvs.texi(,7735) 
cvs.texi(,7736) @c ---------------------------------------------------------------------
cvs.texi(,7737) @node Special Files
cvs.texi(,7738) @chapter Special Files
cvs.texi(,7739) 
cvs.texi(,7740) @cindex Special files
cvs.texi(,7741) @cindex Device nodes
cvs.texi(,7742) @cindex Ownership, saving in CVS
cvs.texi(,7743) @cindex Permissions, saving in CVS
cvs.texi(,7744) @cindex Hard links
cvs.texi(,7745) @cindex Symbolic links
cvs.texi(,7746) 
cvs.texi(,7747) In normal circumstances, @sc{cvs} works only with regular
cvs.texi(,7748) files.  Every file in a project is assumed to be
cvs.texi(,7749) persistent; it must be possible to open, read and close
cvs.texi(,7750) them; and so on.  @sc{cvs} also ignores file permissions and
cvs.texi(,7751) ownerships, leaving such issues to be resolved by the
cvs.texi(,7752) developer at installation time.  In other words, it is
cvs.texi(,7753) not possible to "check in" a device into a repository;
cvs.texi(,7754) if the device file cannot be opened, @sc{cvs} will refuse to
cvs.texi(,7755) handle it.  Files also lose their ownerships and
cvs.texi(,7756) permissions during repository transactions.
cvs.texi(,7757) 
cvs.texi(,7838) 
cvs.texi(,7839) @c ---------------------------------------------------------------------
cvs.texi(,7840) @node CVS commands
cvs.texi(,7841) @appendix Guide to CVS commands
cvs.texi(,7842) 
cvs.texi(,7843) This appendix describes the overall structure of
cvs.texi(,7844) @sc{cvs} commands, and describes some commands in
cvs.texi(,7845) detail (others are described elsewhere; for a quick
cvs.texi(,7846) reference to @sc{cvs} commands, @pxref{Invoking CVS}).
cvs.texi(,7847) @c The idea is that we want to move the commands which
cvs.texi(,7848) @c are described here into the main body of the manual,
cvs.texi(,7849) @c in the process reorganizing the manual to be
cvs.texi(,7850) @c organized around what the user wants to do, not
cvs.texi(,7851) @c organized around CVS commands.
cvs.texi(,7852) @c
cvs.texi(,7853) @c Note that many users do expect a manual which is
cvs.texi(,7854) @c organized by command.  At least some users do.
cvs.texi(,7855) @c One good addition to the "organized by command"
cvs.texi(,7856) @c section (if any) would be "see also" links.
cvs.texi(,7857) @c The awk manual might be a good example; it has a
cvs.texi(,7858) @c reference manual which is more verbose than Invoking
cvs.texi(,7859) @c CVS but probably somewhat less verbose than CVS
cvs.texi(,7860) @c Commands.
cvs.texi(,7861) 
cvs.texi(,7862) @menu
cvs.texi(,7863) * Structure::                   Overall structure of CVS commands
cvs.texi(,7864) * Exit status::                 Indicating CVS's success or failure
cvs.texi(,7865) * ~/.cvsrc::                    Default options with the ~/.csvrc file
cvs.texi(,7866) * Global options::              Options you give to the left of cvs_command
cvs.texi(,7867) * Common options::              Options you give to the right of cvs_command
cvs.texi(,7868) * admin::                       Administration
cvs.texi(,7869) * checkout::                    Checkout sources for editing
cvs.texi(,7870) * commit::                      Check files into the repository
cvs.texi(,7871) * diff::                        Show differences between revisions
cvs.texi(,7872) * export::                      Export sources from CVS, similar to checkout
cvs.texi(,7873) * history::                     Show status of files and users
cvs.texi(,7874) * import::                      Import sources into CVS, using vendor branches
cvs.texi(,7875) * log::                         Show log messages for files
cvs.texi(,7876) * rdiff::                       'patch' format diffs between releases
cvs.texi(,7877) * release::                     Indicate that a directory is no longer in use
cvs.texi(,7878) * update::                      Bring work tree in sync with repository
cvs.texi(,7879) @end menu
cvs.texi(,7880) 
cvs.texi(,7881) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,7882) @node Structure
cvs.texi(,7883) @appendixsec Overall structure of CVS commands
cvs.texi(,7884) @cindex Structure
cvs.texi(,7885) @cindex CVS command structure
cvs.texi(,7886) @cindex Command structure
cvs.texi(,7887) @cindex Format of CVS commands
cvs.texi(,7888) 
cvs.texi(,7889) The overall format of all @sc{cvs} commands is:
cvs.texi(,7890) 
cvs.texi(,7891) @example
cvs.texi(,7892) cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ]
cvs.texi(,7893) @end example
cvs.texi(,7894) 
cvs.texi(,7895) @table @code
cvs.texi(,7896) @item cvs
cvs.texi(,7897) The name of the @sc{cvs} program.
cvs.texi(,7898) 
cvs.texi(,7899) @item cvs_options
cvs.texi(,7900) Some options that affect all sub-commands of @sc{cvs}.  These are
cvs.texi(,7901) described below.
cvs.texi(,7902) 
cvs.texi(,7903) @item cvs_command
cvs.texi(,7904) One of several different sub-commands.  Some of the commands have
cvs.texi(,7905) aliases that can be used instead; those aliases are noted in the
cvs.texi(,7906) reference manual for that command.  There are only two situations
cvs.texi(,7907) where you may omit @samp{cvs_command}: @samp{cvs -H} elicits a
cvs.texi(,7908) list of available commands, and @samp{cvs -v} displays version
cvs.texi(,7909) information on @sc{cvs} itself.
cvs.texi(,7910) 
cvs.texi(,7911) @item command_options
cvs.texi(,7912) Options that are specific for the command.
cvs.texi(,7913) 
cvs.texi(,7914) @item command_args
cvs.texi(,7915) Arguments to the commands.
cvs.texi(,7916) @end table
cvs.texi(,7917) 
cvs.texi(,7918) There is unfortunately some confusion between
cvs.texi(,7919) @code{cvs_options} and @code{command_options}.
cvs.texi(,7920) @samp{-l}, when given as a @code{cvs_option}, only
cvs.texi(,7921) affects some of the commands.  When it is given as a
cvs.texi(,7922) @code{command_option} is has a different meaning, and
cvs.texi(,7923) is accepted by more commands.  In other words, do not
cvs.texi(,7924) take the above categorization too seriously.  Look at
cvs.texi(,7925) the documentation instead.
cvs.texi(,7926) 
cvs.texi(,7927) @node Exit status
cvs.texi(,7928) @appendixsec CVS's exit status
cvs.texi(,7929) @cindex Exit status, of CVS
cvs.texi(,7930) 
cvs.texi(,7931) @sc{cvs} can indicate to the calling environment whether it
cvs.texi(,7932) succeeded or failed by setting its @dfn{exit status}.
cvs.texi(,7933) The exact way of testing the exit status will vary from
cvs.texi(,7934) one operating system to another.  For example in a unix
cvs.texi(,7935) shell script the @samp{$?} variable will be 0 if the
cvs.texi(,7936) last command returned a successful exit status, or
cvs.texi(,7937) greater than 0 if the exit status indicated failure.
cvs.texi(,7938) 
cvs.texi(,7939) If @sc{cvs} is successful, it returns a successful status;
cvs.texi(,7940) if there is an error, it prints an error message and
cvs.texi(,7941) returns a failure status.  The one exception to this is
cvs.texi(,7942) the @code{cvs diff} command.  It will return a
cvs.texi(,7943) successful status if it found no differences, or a
cvs.texi(,7944) failure status if there were differences or if there
cvs.texi(,7945) was an error.  Because this behavior provides no good
cvs.texi(,7946) way to detect errors, in the future it is possible that
cvs.texi(,7947) @code{cvs diff} will be changed to behave like the
cvs.texi(,7948) other @sc{cvs} commands.
cvs.texi(,7949) @c It might seem like checking whether cvs -q diff
cvs.texi(,7950) @c produces empty or non-empty output can tell whether
cvs.texi(,7951) @c there were differences or not.  But it seems like
cvs.texi(,7952) @c there are cases with output but no differences
cvs.texi(,7953) @c (testsuite basica-8b).  It is not clear to me how
cvs.texi(,7954) @c useful it is for a script to be able to check
cvs.texi(,7955) @c whether there were differences.
cvs.texi(,7956) @c FIXCVS? In previous versions of CVS, cvs diff
cvs.texi(,7957) @c returned 0 for no differences, 1 for differences, or
cvs.texi(,7958) @c 2 for errors.  Is this behavior worth trying to
cvs.texi(,7959) @c bring back (but what does it mean for VMS?)?
cvs.texi(,7960) 
cvs.texi(,7961) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,7962) @node ~/.cvsrc
cvs.texi(,7963) @appendixsec Default options and the ~/.cvsrc file
cvs.texi(,7964) @cindex .cvsrc file
cvs.texi(,7965) @cindex Option defaults
cvs.texi(,7966) 
cvs.texi(,7967) There are some @code{command_options} that are used so
cvs.texi(,7968) often that you might have set up an alias or some other
cvs.texi(,7969) means to make sure you always specify that option.  One
cvs.texi(,7970) example (the one that drove the implementation of the
cvs.texi(,7971) @file{.cvsrc} support, actually) is that many people find the
cvs.texi(,7972) default output of the @samp{diff} command to be very
cvs.texi(,7973) hard to read, and that either context diffs or unidiffs
cvs.texi(,7974) are much easier to understand.
cvs.texi(,7975) 
cvs.texi(,7976) The @file{~/.cvsrc} file is a way that you can add
cvs.texi(,7977) default options to @code{cvs_commands} within cvs,
cvs.texi(,7978) instead of relying on aliases or other shell scripts.
cvs.texi(,7979) 
cvs.texi(,7980) The format of the @file{~/.cvsrc} file is simple.  The
cvs.texi(,7981) file is searched for a line that begins with the same
cvs.texi(,7982) name as the @code{cvs_command} being executed.  If a
cvs.texi(,7983) match is found, then the remainder of the line is split
cvs.texi(,7984) up (at whitespace characters) into separate options and
cvs.texi(,7985) added to the command arguments @emph{before} any
cvs.texi(,7986) options from the command line.
cvs.texi(,7987) 
cvs.texi(,7988) If a command has two names (e.g., @code{checkout} and
cvs.texi(,7989) @code{co}), the official name, not necessarily the one
cvs.texi(,7990) used on the command line, will be used to match against
cvs.texi(,7991) the file.  So if this is the contents of the user's
cvs.texi(,7992) @file{~/.cvsrc} file:
cvs.texi(,7993) 
cvs.texi(,7994) @example
cvs.texi(,7995) log -N
cvs.texi(,7996) diff -uN
cvs.texi(,7997) rdiff -u
cvs.texi(,7998) update -Pd
cvs.texi(,7999) checkout -P
cvs.texi(,8000) release -d
cvs.texi(,8001) @end example
cvs.texi(,8002) 
cvs.texi(,8003) @noindent
cvs.texi(,8004) the command @samp{cvs checkout foo} would have the
cvs.texi(,8005) @samp{-P} option added to the arguments, as well as
cvs.texi(,8006) @samp{cvs co foo}.
cvs.texi(,8007) 
cvs.texi(,8008) With the example file above, the output from @samp{cvs
cvs.texi(,8009) diff foobar} will be in unidiff format.  @samp{cvs diff
cvs.texi(,8010) -c foobar} will provide context diffs, as usual.
cvs.texi(,8011) Getting "old" format diffs would be slightly more
cvs.texi(,8012) complicated, because @code{diff} doesn't have an option
cvs.texi(,8013) to specify use of the "old" format, so you would need
cvs.texi(,8014) @samp{cvs -f diff foobar}.
cvs.texi(,8015) 
cvs.texi(,8016) In place of the command name you can use @code{cvs} to
cvs.texi(,8017) specify global options (@pxref{Global options}).  For
cvs.texi(,8018) example the following line in @file{.cvsrc}
cvs.texi(,8019) 
cvs.texi(,8020) @example
cvs.texi(,8021) cvs -z6
cvs.texi(,8022) @end example
cvs.texi(,8023) 
cvs.texi(,8024) @noindent
cvs.texi(,8025) causes @sc{cvs} to use compression level 6.
cvs.texi(,8026) 
cvs.texi(,8027) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,8028) @node Global options
cvs.texi(,8029) @appendixsec Global options
cvs.texi(,8030) @cindex Options, global
cvs.texi(,8031) @cindex Global options
cvs.texi(,8032) @cindex Left-hand options
cvs.texi(,8033) 
cvs.texi(,8034) The available @samp{cvs_options} (that are given to the
cvs.texi(,8035) left of @samp{cvs_command}) are:
cvs.texi(,8036) 
cvs.texi(,8037) @table @code
cvs.texi(,8038) @item --allow-root=@var{rootdir}
cvs.texi(,8039) Specify legal @sc{cvsroot} directory.  See
cvs.texi(,8040) @ref{Password authentication server}.
cvs.texi(,8041) 
cvs.texi(,8042) @cindex Authentication, stream
cvs.texi(,8043) @cindex Stream authentication
cvs.texi(,8044) @item -a
cvs.texi(,8045) Authenticate all communication between the client and
cvs.texi(,8046) the server.  Only has an effect on the @sc{cvs} client.
cvs.texi(,8047) As of this writing, this is only implemented when using
cvs.texi(,8048) a GSSAPI connection (@pxref{GSSAPI authenticated}).
cvs.texi(,8049) Authentication prevents certain sorts of attacks
cvs.texi(,8050) involving hijacking the active @sc{tcp} connection.
cvs.texi(,8051) Enabling authentication does not enable encryption.
cvs.texi(,8052) 
cvs.texi(,8053) @cindex RCSBIN, overriding
cvs.texi(,8054) @cindex Overriding RCSBIN
cvs.texi(,8055) @item -b @var{bindir}
cvs.texi(,8056) In @sc{cvs} 1.9.18 and older, this specified that
cvs.texi(,8057) @sc{rcs} programs are in the @var{bindir} directory.
cvs.texi(,8058) Current versions of @sc{cvs} do not run @sc{rcs}
cvs.texi(,8059) programs; for compatibility this option is accepted,
cvs.texi(,8060) but it does nothing.
cvs.texi(,8061) 
cvs.texi(,8062) @cindex TMPDIR, overriding
cvs.texi(,8063) @cindex Overriding TMPDIR
cvs.texi(,8064) @item -T @var{tempdir}
cvs.texi(,8065) Use @var{tempdir} as the directory where temporary files are
cvs.texi(,8066) located.  Overrides the setting of the @code{$TMPDIR} environment
cvs.texi(,8067) variable and any precompiled directory.  This parameter should be
cvs.texi(,8068) specified as an absolute pathname.
cvs.texi(,8069) (When running client/server, @samp{-T} affects only the local process;
cvs.texi(,8070) specifying @samp{-T} for the client has no effect on the server and
cvs.texi(,8071) vice versa.)
cvs.texi(,8072) 
cvs.texi(,8073) @cindex CVSROOT, overriding
cvs.texi(,8074) @cindex Overriding CVSROOT
cvs.texi(,8075) @item -d @var{cvs_root_directory}
cvs.texi(,8076) Use @var{cvs_root_directory} as the root directory
cvs.texi(,8077) pathname of the repository.  Overrides the setting of
cvs.texi(,8078) the @code{$CVSROOT} environment variable.  @xref{Repository}.
cvs.texi(,8079) 
cvs.texi(,8080) @cindex EDITOR, overriding
cvs.texi(,8081) @cindex Overriding EDITOR
cvs.texi(,8082) @item -e @var{editor}
cvs.texi(,8083) Use @var{editor} to enter revision log information.  Overrides the
cvs.texi(,8084) setting of the @code{$CVSEDITOR} and @code{$EDITOR}
cvs.texi(,8085) environment variables.  For more information, see
cvs.texi(,8086) @ref{Committing your changes}.
cvs.texi(,8087) 
cvs.texi(,8088) @item -f
cvs.texi(,8089) Do not read the @file{~/.cvsrc} file.  This
cvs.texi(,8090) option is most often used because of the
cvs.texi(,8091) non-orthogonality of the @sc{cvs} option set.  For
cvs.texi(,8092) example, the @samp{cvs log} option @samp{-N} (turn off
cvs.texi(,8093) display of tag names) does not have a corresponding
cvs.texi(,8094) option to turn the display on.  So if you have
cvs.texi(,8095) @samp{-N} in the @file{~/.cvsrc} entry for @samp{log},
cvs.texi(,8096) you may need to use @samp{-f} to show the tag names.
cvs.texi(,8097) 
cvs.texi(,8098) @item -H
cvs.texi(,8099) @itemx --help
cvs.texi(,8100) Display usage information about the specified @samp{cvs_command}
cvs.texi(,8101) (but do not actually execute the command).  If you don't specify
cvs.texi(,8102) a command name, @samp{cvs -H} displays overall help for
cvs.texi(,8103) @sc{cvs}, including a list of other help options.
cvs.texi(,8104) @c It seems to me it is better to document it this way
cvs.texi(,8105) @c rather than trying to update this documentation
cvs.texi(,8106) @c every time that we add a --help-foo option.  But
cvs.texi(,8107) @c perhaps that is confusing...
cvs.texi(,8108) 
cvs.texi(,8109) @item -l
cvs.texi(,8110) Do not log the @samp{cvs_command} in the command history (but execute it
cvs.texi(,8111) anyway).  @xref{history}, for information on command history.
cvs.texi(,8112) 
cvs.texi(,8113) @cindex Read-only repository mode
cvs.texi(,8114) @item -R
cvs.texi(,8115) Turns on read-only repository mode.  This allows one to check out from a
cvs.texi(,8116) read-only repository, such as within an anoncvs server, or from a CDROM
cvs.texi(,8117) repository.
cvs.texi(,8118) 
cvs.texi(,8119) Same effect as if the @code{CVSREADONLYFS} environment
cvs.texi(,8120) variable is set. Using @samp{-R} can also considerably
cvs.texi(,8121) speed up checkout's over NFS.
cvs.texi(,8122) 
cvs.texi(,8123) @cindex Read-only mode
cvs.texi(,8124) @item -n
cvs.texi(,8125) Do not change any files.  Attempt to execute the
cvs.texi(,8126) @samp{cvs_command}, but only to issue reports; do not remove,
cvs.texi(,8127) update, or merge any existing files, or create any new files.
cvs.texi(,8128) 
cvs.texi(,8129) Note that @sc{cvs} will not necessarily produce exactly
cvs.texi(,8130) the same output as without @samp{-n}.  In some cases
cvs.texi(,8131) the output will be the same, but in other cases
cvs.texi(,8132) @sc{cvs} will skip some of the processing that would
cvs.texi(,8133) have been required to produce the exact same output.
cvs.texi(,8134) 
cvs.texi(,8135) @item -Q
cvs.texi(,8136) Cause the command to be really quiet; the command will only
cvs.texi(,8137) generate output for serious problems.
cvs.texi(,8138) 
cvs.texi(,8139) @item -q
cvs.texi(,8140) Cause the command to be somewhat quiet; informational messages,
cvs.texi(,8141) such as reports of recursion through subdirectories, are
cvs.texi(,8142) suppressed.
cvs.texi(,8143) 
cvs.texi(,8144) @cindex Read-only files, and -r
cvs.texi(,8145) @item -r
cvs.texi(,8146) Make new working files read-only.  Same effect
cvs.texi(,8147) as if the @code{$CVSREAD} environment variable is set
cvs.texi(,8148) (@pxref{Environment variables}).  The default is to
cvs.texi(,8149) make working files writable, unless watches are on
cvs.texi(,8150) (@pxref{Watches}).
cvs.texi(,8151) 
cvs.texi(,8152) @item -s @var{variable}=@var{value}
cvs.texi(,8153) Set a user variable (@pxref{Variables}).
cvs.texi(,8154) 
cvs.texi(,8155) @cindex Trace
cvs.texi(,8156) @item -t
cvs.texi(,8157) Trace program execution; display messages showing the steps of
cvs.texi(,8158) @sc{cvs} activity.  Particularly useful with @samp{-n} to explore the
cvs.texi(,8159) potential impact of an unfamiliar command.
cvs.texi(,8160) 
cvs.texi(,8161) @item -v
cvs.texi(,8162) @item --version
cvs.texi(,8163) Display version and copyright information for @sc{cvs}.
cvs.texi(,8164) 
cvs.texi(,8165) @cindex CVSREAD, overriding
cvs.texi(,8166) @cindex Overriding CVSREAD
cvs.texi(,8167) @item -w
cvs.texi(,8168) Make new working files read-write.  Overrides the
cvs.texi(,8169) setting of the @code{$CVSREAD} environment variable.
cvs.texi(,8170) Files are created read-write by default, unless @code{$CVSREAD} is
cvs.texi(,8171) set or @samp{-r} is given.
cvs.texi(,8172) @c Note that -w only overrides -r and CVSREAD; it has
cvs.texi(,8173) @c no effect on files which are readonly because of
cvs.texi(,8174) @c "cvs watch on".  My guess is that is the way it
cvs.texi(,8175) @c should be (or should "cvs -w get" on a watched file
cvs.texi(,8176) @c be the same as a get and a cvs edit?), but I'm not
cvs.texi(,8177) @c completely sure whether to document it this way.
cvs.texi(,8178) 
cvs.texi(,8179) @item -x
cvs.texi(,8180) @cindex Encryption
cvs.texi(,8181) Encrypt all communication between the client and the
cvs.texi(,8182) server.  Only has an effect on the @sc{cvs} client.  As
cvs.texi(,8183) of this writing, this is only implemented when using a
cvs.texi(,8184) GSSAPI connection (@pxref{GSSAPI authenticated}) or a
cvs.texi(,8185) Kerberos connection (@pxref{Kerberos authenticated}).
cvs.texi(,8186) Enabling encryption implies that message traffic is
cvs.texi(,8187) also authenticated.  Encryption support is not
cvs.texi(,8188) available by default; it must be enabled using a
cvs.texi(,8189) special configure option, @file{--enable-encryption},
cvs.texi(,8190) when you build @sc{cvs}.
cvs.texi(,8191) 
cvs.texi(,8192) @item -z @var{gzip-level}
cvs.texi(,8193) @cindex Compression
cvs.texi(,8194) @cindex Gzip
cvs.texi(,8195) Set the compression level.
cvs.texi(,8196) Valid levels are 1 (high speed, low compression) to
cvs.texi(,8197) 9 (low speed, high compression), or 0 to disable
cvs.texi(,8198) compression (the default).
cvs.texi(,8199) Only has an effect on the @sc{cvs} client.
cvs.texi(,8200) 
cvs.texi(,8201) @end table
cvs.texi(,8202) 
cvs.texi(,8203) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,8204) @node Common options
cvs.texi(,8205) @appendixsec Common command options
cvs.texi(,8206) @cindex Common options
cvs.texi(,8207) @cindex Right-hand options
cvs.texi(,8208) 
cvs.texi(,8209) This section describes the @samp{command_options} that
cvs.texi(,8210) are available across several @sc{cvs} commands.  These
cvs.texi(,8211) options are always given to the right of
cvs.texi(,8212) @samp{cvs_command}. Not all
cvs.texi(,8213) commands support all of these options; each option is
cvs.texi(,8214) only supported for commands where it makes sense.
cvs.texi(,8215) However, when a command has one of these options you
cvs.texi(,8216) can almost always count on the same behavior of the
cvs.texi(,8217) option as in other commands.  (Other command options,
cvs.texi(,8218) which are listed with the individual commands, may have
cvs.texi(,8219) different behavior from one @sc{cvs} command to the other).
cvs.texi(,8220) 
cvs.texi(,8221) @strong{Note: the @samp{history} command is an exception; it supports
cvs.texi(,8222) many options that conflict even with these standard options.}
cvs.texi(,8223) 
cvs.texi(,8224) @table @code
cvs.texi(,8225) @cindex Dates
cvs.texi(,8226) @cindex Time
cvs.texi(,8227) @cindex Specifying dates
cvs.texi(,8228) @item -D @var{date_spec}
cvs.texi(,8229) Use the most recent revision no later than @var{date_spec}.
cvs.texi(,8230) @var{date_spec} is a single argument, a date description
cvs.texi(,8231) specifying a date in the past.
cvs.texi(,8232) 
cvs.texi(,8233) The specification is @dfn{sticky} when you use it to make a
cvs.texi(,8234) private copy of a source file; that is, when you get a working
cvs.texi(,8235) file using @samp{-D}, @sc{cvs} records the date you specified, so that
cvs.texi(,8236) further updates in the same directory will use the same date
cvs.texi(,8237) (for more information on sticky tags/dates, @pxref{Sticky tags}).
cvs.texi(,8238) 
cvs.texi(,8239) @samp{-D} is available with the @code{annotate}, @code{checkout},
cvs.texi(,8240) @code{diff}, @code{export}, @code{history},
cvs.texi(,8241) @code{rdiff}, @code{rtag}, @code{tag}, and @code{update} commands.
cvs.texi(,8242) (The @code{history} command uses this option in a
cvs.texi(,8243) slightly different way; @pxref{history options}).
cvs.texi(,8244) 
cvs.texi(,8245) @c What other formats should we accept?  I don't want
cvs.texi(,8246) @c to start accepting a whole mess of non-standard
cvs.texi(,8247) @c new formats (there are a lot which are in wide use in
cvs.texi(,8248) @c one context or another), but practicality does
cvs.texi(,8249) @c dictate some level of flexibility.
cvs.texi(,8250) @c * POSIX.2 (e.g. touch, ls output, date) and other
cvs.texi(,8251) @c POSIX and/or de facto unix standards (e.g. at).  The
cvs.texi(,8252) @c practice here is too inconsistent to be of any use.
cvs.texi(,8253) @c * VMS dates.  This is not a formal standard, but
cvs.texi(,8254) @c there is a published specification (see SYS$ASCTIM
cvs.texi(,8255) @c and SYS$BINTIM in the _VMS System Services Reference
cvs.texi(,8256) @c Manual_), it is implemented consistently in VMS
cvs.texi(,8257) @c utilities, and VMS users will expect CVS running on
cvs.texi(,8258) @c VMS to support this format (and if we're going to do
cvs.texi(,8259) @c that, better to make CVS support it on all
cvs.texi(,8260) @c platforms.  Maybe).
cvs.texi(,8261) @c
cvs.texi(,8262) @c NOTE: The tar manual has some documentation for
cvs.texi(,8263) @c getdate.y (just for our info; we don't want to
cvs.texi(,8264) @c attempt to document all the formats accepted by
cvs.texi(,8265) @c getdate.y).
cvs.texi(,8266) @c
cvs.texi(,8267) @c One more note: In output, CVS should consistently
cvs.texi(,8268) @c use one date format, and that format should be one that
cvs.texi(,8269) @c it accepts in input as well.  The former isn't
cvs.texi(,8270) @c really true (see survey below), and I'm not
cvs.texi(,8271) @c sure that either of those formats is accepted in
cvs.texi(,8272) @c input.
cvs.texi(,8273) @c
cvs.texi(,8274) @c cvs log
cvs.texi(,8275) @c   current 1996/01/02 13:45:31
cvs.texi(,8276) @c   Internet 02 Jan 1996 13:45:31 UT
cvs.texi(,8277) @c   ISO 1996-01-02 13:45:31
cvs.texi(,8278) @c cvs ann
cvs.texi(,8279) @c   current 02-Jan-96
cvs.texi(,8280) @c   Internet-like 02 Jan 96
cvs.texi(,8281) @c   ISO 96-01-02
cvs.texi(,8282) @c cvs status
cvs.texi(,8283) @c   current Tue Jun 11 02:54:53 1996
cvs.texi(,8284) @c   Internet [Tue,] 11 Jun 1996 02:54:53
cvs.texi(,8285) @c   ISO 1996-06-11 02:54:53
cvs.texi(,8286) @c   note: date possibly should be omitted entirely for
cvs.texi(,8287) @c   other reasons.
cvs.texi(,8288) @c cvs editors
cvs.texi(,8289) @c   current Tue Jun 11 02:54:53 1996 GMT
cvs.texi(,8290) @c cvs history
cvs.texi(,8291) @c   current 06/11 02:54 +0000
cvs.texi(,8292) @c any others?
cvs.texi(,8293) @c There is a good chance the proper solution has to
cvs.texi(,8294) @c involve at least some level of letting the user
cvs.texi(,8295) @c decide which format (with the default being the
cvs.texi(,8296) @c formats CVS has always used; changing these might be
cvs.texi(,8297) @c _very_ disruptive since scripts may very well be
cvs.texi(,8298) @c parsing them).
cvs.texi(,8299) @c
cvs.texi(,8300) @c Another random bit of prior art concerning dates is
cvs.texi(,8301) @c the strptime function which takes templates such as
cvs.texi(,8302) @c "%m/%d/%y", and apparent a variant of getdate()
cvs.texi(,8303) @c which also honors them.  See
cvs.texi(,8304) @c X/Open CAE Specification, System Interfaces and
cvs.texi(,8305) @c Headers Issue 4, Version 2 (September 1994), in the
cvs.texi(,8306) @c entry for getdate() on page 231
cvs.texi(,8307) 
cvs.texi(,8308) @cindex Timezone, in input
cvs.texi(,8309) @cindex Zone, time, in input
cvs.texi(,8310) A wide variety of date formats are supported by
cvs.texi(,8311) @sc{cvs}.  The most standard ones are ISO8601 (from the
cvs.texi(,8312) International Standards Organization) and the Internet
cvs.texi(,8313) e-mail standard (specified in RFC822 as amended by
cvs.texi(,8314) RFC1123).
cvs.texi(,8315) 
cvs.texi(,8316) @c Probably should be doing more to spell out just what
cvs.texi(,8317) @c the rules are, rather than just giving examples.
cvs.texi(,8318) @c But I want to keep this simple too.
cvs.texi(,8319) @c So I don't know....
cvs.texi(,8320) @c A few specific issues: (1) Maybe should reassure
cvs.texi(,8321) @c people that years after 2000
cvs.texi(,8322) @c work (they are in the testsuite, so they do indeed
cvs.texi(,8323) @c work).  (2) What do two digit years
cvs.texi(,8324) @c mean?  Where do we accept them?  (3) Local times can
cvs.texi(,8325) @c be ambiguous or nonexistent if they fall during the
cvs.texi(,8326) @c hour when daylight savings time goes into or out of
cvs.texi(,8327) @c effect.  Pretty obscure, so I'm not at all sure we
cvs.texi(,8328) @c should be documenting the behavior in that case.
cvs.texi(,8329) ISO8601 dates have many variants but a few examples
cvs.texi(,8330) are:
cvs.texi(,8331) 
cvs.texi(,8332) @example
cvs.texi(,8333) 1972-09-24
cvs.texi(,8334) 1972-09-24 20:05
cvs.texi(,8335) @end example
cvs.texi(,8336) @c I doubt we really accept all ISO8601 format dates
cvs.texi(,8337) @c (for example, decimal hours like 1972-09-24 20,2)
cvs.texi(,8338) @c I'm not sure we should, many of them are pretty
cvs.texi(,8339) @c bizarre and it has lots of gratuitous multiple ways
cvs.texi(,8340) @c to specify the same thing.
cvs.texi(,8341) 
cvs.texi(,8342) There are a lot more ISO8601 date formats, and @sc{cvs}
cvs.texi(,8343) accepts many of them, but you probably don't want to
cvs.texi(,8344) hear the @emph{whole} long story :-).
cvs.texi(,8345) 
cvs.texi(,8346) @c Citing a URL here is kind of problematic given how
cvs.texi(,8347) @c much they change and people who have old versions of
cvs.texi(,8348) @c this manual, but in case we want to reinstate an
cvs.texi(,8349) @c ISO8601 URL, a few are:
cvs.texi(,8350) @c http://www.saqqara.demon.co.uk/datefmt.htm
cvs.texi(,8351) @c http://www.cl.cam.ac.uk/~mgk25/iso-time.html
cvs.texi(,8352) @c Citing some other ISO8601 source is probably even
cvs.texi(,8353) @c worse :-).
cvs.texi(,8354) 
cvs.texi(,8355) In addition to the dates allowed in Internet e-mail
cvs.texi(,8356) itself, @sc{cvs} also allows some of the fields to be
cvs.texi(,8357) omitted.  For example:
cvs.texi(,8358) @c FIXME: Need to figure out better, and document,
cvs.texi(,8359) @c what we want to allow the user to omit.
cvs.texi(,8360) @c NOTE: "omit" does not imply "reorder".
cvs.texi(,8361) @c FIXME: Need to cite a web page describing how to get
cvs.texi(,8362) @c RFC's.
cvs.texi(,8363) 
cvs.texi(,8364) @example
cvs.texi(,8365) 24 Sep 1972 20:05
cvs.texi(,8366) 24 Sep
cvs.texi(,8367) @end example
cvs.texi(,8368) 
cvs.texi(,8369) The date is interpreted as being in the
cvs.texi(,8370) local timezone, unless a specific timezone is
cvs.texi(,8371) specified.
cvs.texi(,8372) 
cvs.texi(,8373) These two date formats are preferred.  However,
cvs.texi(,8374) @sc{cvs} currently accepts a wide variety of other date
cvs.texi(,8375) formats.  They are intentionally not documented here in
cvs.texi(,8376) any detail, and future versions of @sc{cvs} might not
cvs.texi(,8377) accept all of them.
cvs.texi(,8378) @c We should document and testsuite "now" and
cvs.texi(,8379) @c "yesterday".  "now" is mentioned in the FAQ and
cvs.texi(,8380) @c "yesterday" is mentioned in this document (and the
cvs.texi(,8381) @c message from "cvs import" suggesting a merge
cvs.texi(,8382) @c command).  What else?  Probably some/all of the "3
cvs.texi(,8383) @c weeks ago" family.
cvs.texi(,8384) @c
cvs.texi(,8385) @c Maybe at
cvs.texi(,8386) @c some point have CVS start give warnings on "unofficial"
cvs.texi(,8387) @c formats (many of which might be typos or user
cvs.texi(,8388) @c misunderstandings, and/or formats people never/rarely
cvs.texi(,8389) @c use to specify dates)?
cvs.texi(,8390) 
cvs.texi(,8391) One such format is
cvs.texi(,8392) @code{@var{month}/@var{day}/@var{year}}.  This may
cvs.texi(,8393) confuse people who are accustomed to having the month
cvs.texi(,8394) and day in the other order; @samp{1/4/96} is January 4,
cvs.texi(,8395) not April 1.
cvs.texi(,8396) 
cvs.texi(,8397) Remember to quote the argument to the @samp{-D}
cvs.texi(,8398) flag so that your shell doesn't interpret spaces as
cvs.texi(,8399) argument separators.  A command using the @samp{-D}
cvs.texi(,8400) flag can look like this:
cvs.texi(,8401) 
cvs.texi(,8402) @example
cvs.texi(,8403) $ cvs diff -D "1 hour ago" cvs.texinfo
cvs.texi(,8404) @end example
cvs.texi(,8405) 
cvs.texi(,8406) @cindex Forcing a tag match
cvs.texi(,8407) @item -f
cvs.texi(,8408) When you specify a particular date or tag to @sc{cvs} commands, they
cvs.texi(,8409) normally ignore files that do not contain the tag (or did not
cvs.texi(,8410) exist prior to the date) that you specified.  Use the @samp{-f} option
cvs.texi(,8411) if you want files retrieved even when there is no match for the
cvs.texi(,8412) tag or date.  (The most recent revision of the file
cvs.texi(,8413) will be used).
cvs.texi(,8414) 
cvs.texi(,8415) Note that even with @samp{-f}, a tag that you specify
cvs.texi(,8416) must exist (that is, in some file, not necessary in
cvs.texi(,8417) every file).  This is so that @sc{cvs} will continue to
cvs.texi(,8418) give an error if you mistype a tag name.
cvs.texi(,8419) 
cvs.texi(,8420) @need 800
cvs.texi(,8421) @samp{-f} is available with these commands:
cvs.texi(,8422) @code{annotate}, @code{checkout}, @code{export},
cvs.texi(,8423) @code{rdiff}, @code{rtag}, and @code{update}.
cvs.texi(,8424) 
cvs.texi(,8425) @strong{WARNING:  The @code{commit} and @code{remove}
cvs.texi(,8426) commands also have a
cvs.texi(,8427) @samp{-f} option, but it has a different behavior for
cvs.texi(,8428) those commands.  See @ref{commit options}, and
cvs.texi(,8429) @ref{Removing files}.}
cvs.texi(,8430) 
cvs.texi(,8431) @item -k @var{kflag}
cvs.texi(,8432) Override the default processing of RCS keywords other than
cvs.texi(,8433) @samp{-kb}.  @xref{Keyword substitution}, for the meaning of
cvs.texi(,8434) @var{kflag}.  Used with the @code{checkout} and @code{update}
cvs.texi(,8435) commands, your @var{kflag} specification is
cvs.texi(,8436) @dfn{sticky}; that is, when you use this option
cvs.texi(,8437) with a @code{checkout} or @code{update} command,
cvs.texi(,8438) @sc{cvs} associates your selected @var{kflag} with any files
cvs.texi(,8439) it operates on, and continues to use that @var{kflag} with future
cvs.texi(,8440) commands on the same files until you specify otherwise.
cvs.texi(,8441) 
cvs.texi(,8442) The @samp{-k} option is available with the @code{add},
cvs.texi(,8443) @code{checkout}, @code{diff}, @code{export}, @code{import} and
cvs.texi(,8444) @code{update} commands.
cvs.texi(,8445) 
cvs.texi(,8446) @strong{WARNING: Prior to CVS version 1.12.2, the @samp{-k} flag
cvs.texi(,8447) overrode the @samp{-kb} indication for a binary file.  This could
cvs.texi(,8448) sometimes corrupt binary files.  @xref{Merging and keywords}, for
cvs.texi(,8449) more.}
cvs.texi(,8450) 
cvs.texi(,8451) @item -l
cvs.texi(,8452) Local; run only in current working directory, rather than
cvs.texi(,8453) recursing through subdirectories.
cvs.texi(,8454) 
cvs.texi(,8455) Available with the following commands: @code{annotate}, @code{checkout},
cvs.texi(,8456) @code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export},
cvs.texi(,8457) @code{log}, @code{rdiff}, @code{remove}, @code{rtag},
cvs.texi(,8458) @code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch},
cvs.texi(,8459) and @code{watchers}.
cvs.texi(,8460) 
cvs.texi(,8461) @cindex Editor, avoiding invocation of
cvs.texi(,8462) @cindex Avoiding editor invocation
cvs.texi(,8463) @item -m @var{message}
cvs.texi(,8464) Use @var{message} as log information, instead of
cvs.texi(,8465) invoking an editor.
cvs.texi(,8466) 
cvs.texi(,8467) Available with the following commands: @code{add},
cvs.texi(,8468) @code{commit} and @code{import}.
cvs.texi(,8469) 
cvs.texi(,8470) @item -n
cvs.texi(,8471) Do not run any tag program.  (A program can be
cvs.texi(,8472) specified to run in the modules
cvs.texi(,8473) database (@pxref{modules}); this option bypasses it).
cvs.texi(,8474) 
cvs.texi(,8475) @strong{Note: this is not the same as the @samp{cvs -n}
cvs.texi(,8476) program option, which you can specify to the left of a cvs command!}
cvs.texi(,8477) 
cvs.texi(,8478) Available with the @code{checkout}, @code{commit}, @code{export},
cvs.texi(,8479) and @code{rtag} commands.
cvs.texi(,8480) 
cvs.texi(,8481) @item -P
cvs.texi(,8482) Prune empty directories.  See @ref{Removing directories}.
cvs.texi(,8483) 
cvs.texi(,8484) @item -p
cvs.texi(,8485) Pipe the files retrieved from the repository to standard output,
cvs.texi(,8486) rather than writing them in the current directory.  Available
cvs.texi(,8487) with the @code{checkout} and @code{update} commands.
cvs.texi(,8488) 
cvs.texi(,8489) @item -R
cvs.texi(,8490) Process directories recursively.  This is on by default.
cvs.texi(,8491) 
cvs.texi(,8492) Available with the following commands: @code{annotate}, @code{checkout},
cvs.texi(,8493) @code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export},
cvs.texi(,8494) @code{rdiff}, @code{remove}, @code{rtag},
cvs.texi(,8495) @code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch},
cvs.texi(,8496) and @code{watchers}.
cvs.texi(,8497) 
cvs.texi(,8498) @item -r @var{tag}
cvs.texi(,8499) @cindex HEAD, special tag
cvs.texi(,8500) @cindex BASE, special tag
cvs.texi(,8501) Use the revision specified by the @var{tag} argument instead of the
cvs.texi(,8502) default @dfn{head} revision.  As well as arbitrary tags defined
cvs.texi(,8503) with the @code{tag} or @code{rtag} command, two special tags are
cvs.texi(,8504) always available: @samp{HEAD} refers to the most recent version
cvs.texi(,8505) available in the repository, and @samp{BASE} refers to the
cvs.texi(,8506) revision you last checked out into the current working directory.
cvs.texi(,8507) 
cvs.texi(,8508) @c FIXME: What does HEAD really mean?  I believe that
cvs.texi(,8509) @c the current answer is the head of the default branch
cvs.texi(,8510) @c for all cvs commands except diff.  For diff, it
cvs.texi(,8511) @c seems to be (a) the head of the trunk (or the default
cvs.texi(,8512) @c branch?) if there is no sticky tag, (b) the head of the
cvs.texi(,8513) @c branch for the sticky tag, if there is a sticky tag.
cvs.texi(,8514) @c (b) is ugly as it differs
cvs.texi(,8515) @c from what HEAD means for other commands, but people
cvs.texi(,8516) @c and/or scripts are quite possibly used to it.
cvs.texi(,8517) @c See "head" tests in sanity.sh.
cvs.texi(,8518) @c Probably the best fix is to introduce two new
cvs.texi(,8519) @c special tags, ".thead" for the head of the trunk,
cvs.texi(,8520) @c and ".bhead" for the head of the current branch.
cvs.texi(,8521) @c Then deprecate HEAD.  This has the advantage of
cvs.texi(,8522) @c not surprising people with a change to HEAD, and a
cvs.texi(,8523) @c side benefit of also phasing out the poorly-named
cvs.texi(,8524) @c HEAD (see discussion of reserved tag names in node
cvs.texi(,8525) @c "Tags").  Of course, .thead and .bhead should be
cvs.texi(,8526) @c carefully implemented (with the implementation the
cvs.texi(,8527) @c same for "diff" as for everyone else), test cases
cvs.texi(,8528) @c written (similar to the ones in "head"), new tests
cvs.texi(,8529) @c cases written for things like default branches, &c.
cvs.texi(,8530) 
cvs.texi(,8531) The tag specification is sticky when you use this
cvs.texi(,8532) @c option
cvs.texi(,8533) with @code{checkout} or @code{update} to make your own
cvs.texi(,8534) copy of a file: @sc{cvs} remembers the tag and continues to use it on
cvs.texi(,8535) future update commands, until you specify otherwise (for more information
cvs.texi(,8536) on sticky tags/dates, @pxref{Sticky tags}).
cvs.texi(,8537) 
cvs.texi(,8538) The tag can be either a symbolic or numeric tag, as
cvs.texi(,8539) described in @ref{Tags}, or the name of a branch, as
cvs.texi(,8540) described in @ref{Branching and merging}.
cvs.texi(,8541) 
cvs.texi(,8542) Specifying the @samp{-q} global option along with the
cvs.texi(,8543) @samp{-r} command option is often useful, to suppress
cvs.texi(,8544) the warning messages when the @sc{rcs} file
cvs.texi(,8545) does not contain the specified tag.
cvs.texi(,8546) 
cvs.texi(,8547) @strong{Note: this is not the same as the overall @samp{cvs -r} option,
cvs.texi(,8548) which you can specify to the left of a @sc{cvs} command!}
cvs.texi(,8549) 
cvs.texi(,8550) @samp{-r} is available with the @code{checkout}, @code{commit},
cvs.texi(,8551) @code{diff}, @code{history}, @code{export}, @code{rdiff},
cvs.texi(,8552) @code{rtag}, and @code{update} commands.
cvs.texi(,8553) 
cvs.texi(,8554) @item -W
cvs.texi(,8555) Specify file names that should be filtered.  You can
cvs.texi(,8556) use this option repeatedly.  The spec can be a file
cvs.texi(,8557) name pattern of the same type that you can specify in
cvs.texi(,8558) the @file{.cvswrappers} file.
cvs.texi(,8559) Available with the following commands: @code{import},
cvs.texi(,8560) and @code{update}.
cvs.texi(,8561) 
cvs.texi(,8562) @end table
cvs.texi(,8563) 
cvs.texi(,8564) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,8565) @node admin
cvs.texi(,8566) @appendixsec admin---Administration
cvs.texi(,8567) @cindex Admin (subcommand)
cvs.texi(,8568) 
cvs.texi(,8569) @itemize @bullet
cvs.texi(,8570) @item
cvs.texi(,8571) Requires: repository, working directory.
cvs.texi(,8572) @item
cvs.texi(,8573) Changes: repository.
cvs.texi(,8574) @item
cvs.texi(,8575) Synonym: rcs
cvs.texi(,8576) @end itemize
cvs.texi(,8577) 
cvs.texi(,8578) This is the @sc{cvs} interface to assorted
cvs.texi(,8579) administrative facilities.  Some of them have
cvs.texi(,8580) questionable usefulness for @sc{cvs} but exist for
cvs.texi(,8581) historical purposes.  Some of the questionable options
cvs.texi(,8582) are likely to disappear in the future.  This command
cvs.texi(,8583) @emph{does} work recursively, so extreme care should be
cvs.texi(,8584) used.
cvs.texi(,8585) 
cvs.texi(,8586) @cindex cvsadmin
cvs.texi(,8587) @cindex UserAdminOptions, in CVSROOT/config
cvs.texi(,8588) On unix, if there is a group named @code{cvsadmin},
cvs.texi(,8589) only members of that group can run @code{cvs admin}
cvs.texi(,8590) commands, except for those specified using the
cvs.texi(,8591) @code{UserAdminOptions} configuration option in the
cvs.texi(,8592) @file{CVSROOT/config} file.  Options specified using
cvs.texi(,8593) @code{UserAdminOptions} can be run by any user.  See
cvs.texi(,8594) @ref{config} for more on @code{UserAdminOptions}.
cvs.texi(,8595) 
cvs.texi(,8596) The @code{cvsadmin} group should exist on the server,
cvs.texi(,8597) or any system running the non-client/server @sc{cvs}.
cvs.texi(,8598) To disallow @code{cvs admin} for all users, create a
cvs.texi(,8599) group with no users in it.  On NT, the @code{cvsadmin}
cvs.texi(,8600) feature does not exist and all users
cvs.texi(,8601) can run @code{cvs admin}.
cvs.texi(,8602) 
cvs.texi(,8603) @menu
cvs.texi(,8604) * admin options::               admin options
cvs.texi(,8605) @end menu
cvs.texi(,8606) 
cvs.texi(,8607) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,8608) @node admin options
cvs.texi(,8609) @appendixsubsec admin options
cvs.texi(,8610) 
cvs.texi(,8611) Some of these options have questionable usefulness for
cvs.texi(,8612) @sc{cvs} but exist for historical purposes.  Some even
cvs.texi(,8613) make it impossible to use @sc{cvs} until you undo the
cvs.texi(,8614) effect!
cvs.texi(,8615) 
cvs.texi(,8616) @table @code
cvs.texi(,8617) @item -A@var{oldfile}
cvs.texi(,8618) Might not work together with @sc{cvs}.  Append the
cvs.texi(,8619) access list of @var{oldfile} to the access list of the
cvs.texi(,8620) @sc{rcs} file.
cvs.texi(,8621) 
cvs.texi(,8622) @item -a@var{logins}
cvs.texi(,8623) Might not work together with @sc{cvs}.  Append the
cvs.texi(,8624) login names appearing in the comma-separated list
cvs.texi(,8625) @var{logins} to the access list of the @sc{rcs} file.
cvs.texi(,8626) 
cvs.texi(,8627) @item -b[@var{rev}]
cvs.texi(,8628) Set the default branch to @var{rev}.  In @sc{cvs}, you
cvs.texi(,8629) normally do not manipulate default branches; sticky
cvs.texi(,8630) tags (@pxref{Sticky tags}) are a better way to decide
cvs.texi(,8631) which branch you want to work on.  There is one reason
cvs.texi(,8632) to run @code{cvs admin -b}: to revert to the vendor's
cvs.texi(,8633) version when using vendor branches (@pxref{Reverting
cvs.texi(,8634) local changes}).
cvs.texi(,8635) There can be no space between @samp{-b} and its argument.
cvs.texi(,8636) @c Hmm, we don't document the usage where rev is
cvs.texi(,8637) @c omitted.  Maybe that usage can/should be deprecated
cvs.texi(,8638) @c (and replaced with -bHEAD or something?) (so we can toss
cvs.texi(,8639) @c the optional argument).  Note that -bHEAD does not
cvs.texi(,8640) @c work, as of 17 Sep 1997, but probably will once "cvs
cvs.texi(,8641) @c admin" is internal to CVS.
cvs.texi(,8642) 
cvs.texi(,8643) @cindex Comment leader
cvs.texi(,8644) @item -c@var{string}
cvs.texi(,8645) Sets the comment leader to @var{string}.  The comment
cvs.texi(,8646) leader is not used by current versions of @sc{cvs} or
cvs.texi(,8647) @sc{rcs} 5.7.  Therefore, you can almost surely not
cvs.texi(,8648) worry about it.  @xref{Keyword substitution}.
cvs.texi(,8649) 
cvs.texi(,8650) @item -e[@var{logins}]
cvs.texi(,8651) Might not work together with @sc{cvs}.  Erase the login
cvs.texi(,8652) names appearing in the comma-separated list
cvs.texi(,8653) @var{logins} from the access list of the RCS file.  If
cvs.texi(,8654) @var{logins} is omitted, erase the entire access list.
cvs.texi(,8655) There can be no space between @samp{-e} and its argument.
cvs.texi(,8656) 
cvs.texi(,8657) @item -I
cvs.texi(,8658) Run interactively, even if the standard input is not a
cvs.texi(,8659) terminal.  This option does not work with the
cvs.texi(,8660) client/server @sc{cvs} and is likely to disappear in
cvs.texi(,8661) a future release of @sc{cvs}.
cvs.texi(,8662) 
cvs.texi(,8663) @item -i
cvs.texi(,8664) Useless with @sc{cvs}.  This creates and initializes a
cvs.texi(,8665) new @sc{rcs} file, without depositing a revision.  With
cvs.texi(,8666) @sc{cvs}, add files with the @code{cvs add} command
cvs.texi(,8667) (@pxref{Adding files}).
cvs.texi(,8668) 
cvs.texi(,8669) @item -k@var{subst}
cvs.texi(,8670) Set the default keyword
cvs.texi(,8671) substitution to @var{subst}.  @xref{Keyword
cvs.texi(,8672) substitution}.  Giving an explicit @samp{-k} option to
cvs.texi(,8673) @code{cvs update}, @code{cvs export}, or @code{cvs
cvs.texi(,8674) checkout} overrides this default.
cvs.texi(,8675) 
cvs.texi(,8676) @item -l[@var{rev}]
cvs.texi(,8677) Lock the revision with number @var{rev}.  If a branch
cvs.texi(,8678) is given, lock the latest revision on that branch.  If
cvs.texi(,8679) @var{rev} is omitted, lock the latest revision on the
cvs.texi(,8680) default branch.  There can be no space between
cvs.texi(,8681) @samp{-l} and its argument.
cvs.texi(,8682) 
cvs.texi(,8683) This can be used in conjunction with the
cvs.texi(,8684) @file{rcslock.pl} script in the @file{contrib}
cvs.texi(,8685) directory of the @sc{cvs} source distribution to
cvs.texi(,8686) provide reserved checkouts (where only one user can be
cvs.texi(,8687) editing a given file at a time).  See the comments in
cvs.texi(,8688) that file for details (and see the @file{README} file
cvs.texi(,8689) in that directory for disclaimers about the unsupported
cvs.texi(,8690) nature of contrib).  According to comments in that
cvs.texi(,8691) file, locking must set to strict (which is the default).
cvs.texi(,8692) 
cvs.texi(,8693) @item -L
cvs.texi(,8694) Set locking to strict.  Strict locking means that the
cvs.texi(,8695) owner of an RCS file is not exempt from locking for
cvs.texi(,8696) checkin.  For use with @sc{cvs}, strict locking must be
cvs.texi(,8697) set; see the discussion under the @samp{-l} option above.
cvs.texi(,8698) 
cvs.texi(,8699) @cindex Changing a log message
cvs.texi(,8700) @cindex Replacing a log message
cvs.texi(,8701) @cindex Correcting a log message
cvs.texi(,8702) @cindex Fixing a log message
cvs.texi(,8703) @cindex Log message, correcting
cvs.texi(,8704) @item -m@var{rev}:@var{msg}
cvs.texi(,8705) Replace the log message of revision @var{rev} with
cvs.texi(,8706) @var{msg}.
cvs.texi(,8707) 
cvs.texi(,8708) @c The rcs -M option, to suppress sending mail, has never been
cvs.texi(,8709) @c documented as a cvs admin option.
cvs.texi(,8710) 
cvs.texi(,8711) @item -N@var{name}[:[@var{rev}]]
cvs.texi(,8712) Act like @samp{-n}, except override any previous
cvs.texi(,8713) assignment of @var{name}.  For use with magic branches,
cvs.texi(,8714) see @ref{Magic branch numbers}.
cvs.texi(,8715) 
cvs.texi(,8716) @item -n@var{name}[:[@var{rev}]]
cvs.texi(,8717) Associate the symbolic name @var{name} with the branch
cvs.texi(,8718) or revision @var{rev}.  It is normally better to use
cvs.texi(,8719) @samp{cvs tag} or @samp{cvs rtag} instead.  Delete the
cvs.texi(,8720) symbolic name if both @samp{:} and @var{rev} are
cvs.texi(,8721) omitted; otherwise, print an error message if
cvs.texi(,8722) @var{name} is already associated with another number.
cvs.texi(,8723) If @var{rev} is symbolic, it is expanded before
cvs.texi(,8724) association.  A @var{rev} consisting of a branch number
cvs.texi(,8725) followed by a @samp{.} stands for the current latest
cvs.texi(,8726) revision in the branch.  A @samp{:} with an empty
cvs.texi(,8727) @var{rev} stands for the current latest revision on the
cvs.texi(,8728) default branch, normally the trunk.  For example,
cvs.texi(,8729) @samp{cvs admin -n@var{name}:} associates @var{name} with the
cvs.texi(,8730) current latest revision of all the RCS files;
cvs.texi(,8731) this contrasts with @samp{cvs admin -n@var{name}:$} which
cvs.texi(,8732) associates @var{name} with the revision numbers
cvs.texi(,8733) extracted from keyword strings in the corresponding
cvs.texi(,8734) working files.
cvs.texi(,8735) 
cvs.texi(,8736) @cindex Deleting revisions
cvs.texi(,8737) @cindex Outdating revisions
cvs.texi(,8738) @cindex Saving space
cvs.texi(,8739) @item -o@var{range}
cvs.texi(,8740) Deletes (@dfn{outdates}) the revisions given by
cvs.texi(,8741) @var{range}.
cvs.texi(,8742) 
cvs.texi(,8743) Note that this command can be quite dangerous unless
cvs.texi(,8744) you know @emph{exactly} what you are doing (for example
cvs.texi(,8745) see the warnings below about how the
cvs.texi(,8746) @var{rev1}:@var{rev2} syntax is confusing).
cvs.texi(,8747) 
cvs.texi(,8748) If you are short on disc this option might help you.
cvs.texi(,8749) But think twice before using it---there is no way short
cvs.texi(,8750) of restoring the latest backup to undo this command!
cvs.texi(,8751) If you delete different revisions than you planned,
cvs.texi(,8752) either due to carelessness or (heaven forbid) a @sc{cvs}
cvs.texi(,8753) bug, there is no opportunity to correct the error
cvs.texi(,8754) before the revisions are deleted.  It probably would be
cvs.texi(,8755) a good idea to experiment on a copy of the repository
cvs.texi(,8756) first.
cvs.texi(,8757) 
cvs.texi(,8758) Specify @var{range} in one of the following ways:
cvs.texi(,8759) 
cvs.texi(,8760) @table @code
cvs.texi(,8761) @item @var{rev1}::@var{rev2}
cvs.texi(,8762) Collapse all revisions between rev1 and rev2, so that
cvs.texi(,8763) @sc{cvs} only stores the differences associated with going
cvs.texi(,8764) from rev1 to rev2, not intermediate steps.  For
cvs.texi(,8765) example, after @samp{-o 1.3::1.5} one can retrieve
cvs.texi(,8766) revision 1.3, revision 1.5, or the differences to get
cvs.texi(,8767) from 1.3 to 1.5, but not the revision 1.4, or the
cvs.texi(,8768) differences between 1.3 and 1.4.  Other examples:
cvs.texi(,8769) @samp{-o 1.3::1.4} and @samp{-o 1.3::1.3} have no
cvs.texi(,8770) effect, because there are no intermediate revisions to
cvs.texi(,8771) remove.
cvs.texi(,8772) 
cvs.texi(,8773) @item ::@var{rev}
cvs.texi(,8774) Collapse revisions between the beginning of the branch
cvs.texi(,8775) containing @var{rev} and @var{rev} itself.  The
cvs.texi(,8776) branchpoint and @var{rev} are left intact.  For
cvs.texi(,8777) example, @samp{-o ::1.3.2.6} deletes revision 1.3.2.1,
cvs.texi(,8778) revision 1.3.2.5, and everything in between, but leaves
cvs.texi(,8779) 1.3 and 1.3.2.6 intact.
cvs.texi(,8780) 
cvs.texi(,8781) @item @var{rev}::
cvs.texi(,8782) Collapse revisions between @var{rev} and the end of the
cvs.texi(,8783) branch containing @var{rev}.  Revision @var{rev} is
cvs.texi(,8784) left intact but the head revision is deleted.
cvs.texi(,8785) 
cvs.texi(,8786) @item @var{rev}
cvs.texi(,8787) Delete the revision @var{rev}.  For example, @samp{-o
cvs.texi(,8788) 1.3} is equivalent to @samp{-o 1.2::1.4}.
cvs.texi(,8789) 
cvs.texi(,8790) @item @var{rev1}:@var{rev2}
cvs.texi(,8791) Delete the revisions from @var{rev1} to @var{rev2},
cvs.texi(,8792) inclusive, on the same branch.  One will not be able to
cvs.texi(,8793) retrieve @var{rev1} or @var{rev2} or any of the
cvs.texi(,8794) revisions in between.  For example, the command
cvs.texi(,8795) @samp{cvs admin -oR_1_01:R_1_02 .} is rarely useful.
cvs.texi(,8796) It means to delete revisions up to, and including, the
cvs.texi(,8797) tag R_1_02.  But beware!  If there are files that have not
cvs.texi(,8798) changed between R_1_02 and R_1_03 the file will have
cvs.texi(,8799) @emph{the same} numerical revision number assigned to
cvs.texi(,8800) the tags R_1_02 and R_1_03.  So not only will it be
cvs.texi(,8801) impossible to retrieve R_1_02; R_1_03 will also have to
cvs.texi(,8802) be restored from the tapes!  In most cases you want to
cvs.texi(,8803) specify @var{rev1}::@var{rev2} instead.
cvs.texi(,8804) 
cvs.texi(,8805) @item :@var{rev}
cvs.texi(,8806) Delete revisions from the beginning of the
cvs.texi(,8807) branch containing @var{rev} up to and including
cvs.texi(,8808) @var{rev}.
cvs.texi(,8809) 
cvs.texi(,8810) @item @var{rev}:
cvs.texi(,8811) Delete revisions from revision @var{rev}, including
cvs.texi(,8812) @var{rev} itself, to the end of the branch containing
cvs.texi(,8813) @var{rev}.
cvs.texi(,8814) @end table
cvs.texi(,8815) 
cvs.texi(,8816) None of the revisions to be deleted may have
cvs.texi(,8817) branches or locks.
cvs.texi(,8818) 
cvs.texi(,8819) If any of the revisions to be deleted have symbolic
cvs.texi(,8820) names, and one specifies one of the @samp{::} syntaxes,
cvs.texi(,8821) then @sc{cvs} will give an error and not delete any
cvs.texi(,8822) revisions.  If you really want to delete both the
cvs.texi(,8823) symbolic names and the revisions, first delete the
cvs.texi(,8824) symbolic names with @code{cvs tag -d}, then run
cvs.texi(,8825) @code{cvs admin -o}.  If one specifies the
cvs.texi(,8826) non-@samp{::} syntaxes, then @sc{cvs} will delete the
cvs.texi(,8827) revisions but leave the symbolic names pointing to
cvs.texi(,8828) nonexistent revisions.  This behavior is preserved for
cvs.texi(,8829) compatibility with previous versions of @sc{cvs}, but
cvs.texi(,8830) because it isn't very useful, in the future it may
cvs.texi(,8831) change to be like the @samp{::} case.
cvs.texi(,8832) 
cvs.texi(,8833) Due to the way @sc{cvs} handles branches @var{rev}
cvs.texi(,8834) cannot be specified symbolically if it is a branch.
cvs.texi(,8835) @xref{Magic branch numbers}, for an explanation.
cvs.texi(,8836) @c FIXME: is this still true?  I suspect not.
cvs.texi(,8837) 
cvs.texi(,8838) Make sure that no-one has checked out a copy of the
cvs.texi(,8839) revision you outdate.  Strange things will happen if he
cvs.texi(,8840) starts to edit it and tries to check it back in.  For
cvs.texi(,8841) this reason, this option is not a good way to take back
cvs.texi(,8842) a bogus commit; commit a new revision undoing the bogus
cvs.texi(,8843) change instead (@pxref{Merging two revisions}).
cvs.texi(,8844) 
cvs.texi(,8845) @item -q
cvs.texi(,8846) Run quietly; do not print diagnostics.
cvs.texi(,8847) 
cvs.texi(,8848) @item -s@var{state}[:@var{rev}]
cvs.texi(,8849) Useful with @sc{cvs}.  Set the state attribute of the
cvs.texi(,8850) revision @var{rev} to @var{state}.  If @var{rev} is a
cvs.texi(,8851) branch number, assume the latest revision on that
cvs.texi(,8852) branch.  If @var{rev} is omitted, assume the latest
cvs.texi(,8853) revision on the default branch.  Any identifier is
cvs.texi(,8854) acceptable for @var{state}.  A useful set of states is
cvs.texi(,8855) @samp{Exp} (for experimental), @samp{Stab} (for
cvs.texi(,8856) stable), and @samp{Rel} (for released).  By default,
cvs.texi(,8857) the state of a new revision is set to @samp{Exp} when
cvs.texi(,8858) it is created.  The state is visible in the output from
cvs.texi(,8859) @var{cvs log} (@pxref{log}), and in the
cvs.texi(splitrcskeyword,8860) @samp{$@i{}Log$} and @samp{$@i{}State$} keywords
cvs.texi(,8861) (@pxref{Keyword substitution}).  Note that @sc{cvs}
cvs.texi(,8862) uses the @code{dead} state for its own purposes; to
cvs.texi(,8863) take a file to or from the @code{dead} state use
cvs.texi(,8864) commands like @code{cvs remove} and @code{cvs add}, not
cvs.texi(,8865) @code{cvs admin -s}.
cvs.texi(,8866) 
cvs.texi(,8867) @item -t[@var{file}]
cvs.texi(,8868) Useful with @sc{cvs}.  Write descriptive text from the
cvs.texi(,8869) contents of the named @var{file} into the RCS file,
cvs.texi(,8870) deleting the existing text.  The @var{file} pathname
cvs.texi(,8871) may not begin with @samp{-}.  The descriptive text can be seen in the
cvs.texi(,8872) output from @samp{cvs log} (@pxref{log}).
cvs.texi(,8873) There can be no space between @samp{-t} and its argument.
cvs.texi(,8874) 
cvs.texi(,8875) If @var{file} is omitted,
cvs.texi(,8876) obtain the text from standard input, terminated by
cvs.texi(,8877) end-of-file or by a line containing @samp{.} by itself.
cvs.texi(,8878) Prompt for the text if interaction is possible; see
cvs.texi(,8879) @samp{-I}.
cvs.texi(,8880) 
cvs.texi(,8881) @item -t-@var{string}
cvs.texi(,8882) Similar to @samp{-t@var{file}}. Write descriptive text
cvs.texi(,8883) from the @var{string} into the @sc{rcs} file, deleting
cvs.texi(,8884) the existing text.
cvs.texi(,8885) There can be no space between @samp{-t} and its argument.
cvs.texi(,8886) 
cvs.texi(,8887) @c The rcs -T option, do not update last-mod time for
cvs.texi(,8888) @c minor changes, has never been documented as a
cvs.texi(,8889) @c cvs admin option.
cvs.texi(,8890) 
cvs.texi(,8891) @item -U
cvs.texi(,8892) Set locking to non-strict.  Non-strict locking means
cvs.texi(,8893) that the owner of a file need not lock a revision for
cvs.texi(,8894) checkin.  For use with @sc{cvs}, strict locking must be
cvs.texi(,8895) set; see the discussion under the @samp{-l} option
cvs.texi(,8896) above.
cvs.texi(,8897) 
cvs.texi(,8898) @item -u[@var{rev}]
cvs.texi(,8899) See the option @samp{-l} above, for a discussion of
cvs.texi(,8900) using this option with @sc{cvs}.  Unlock the revision
cvs.texi(,8901) with number @var{rev}.  If a branch is given, unlock
cvs.texi(,8902) the latest revision on that branch.  If @var{rev} is
cvs.texi(,8903) omitted, remove the latest lock held by the caller.
cvs.texi(,8904) Normally, only the locker of a revision may unlock it;
cvs.texi(,8905) somebody else unlocking a revision breaks the lock.
cvs.texi(,8906) This causes the original locker to be sent a @code{commit}
cvs.texi(,8907) notification (@pxref{Getting Notified}).
cvs.texi(,8908) There can be no space between @samp{-u} and its argument.
cvs.texi(,8909) 
cvs.texi(,8910) @item -V@var{n}
cvs.texi(,8911) In previous versions of @sc{cvs}, this option meant to
cvs.texi(,8912) write an @sc{rcs} file which would be acceptable to
cvs.texi(,8913) @sc{rcs} version @var{n}, but it is now obsolete and
cvs.texi(,8914) specifying it will produce an error.
cvs.texi(,8915) @c Note that -V without an argument has never been
cvs.texi(,8916) @c documented as a cvs admin option.
cvs.texi(,8917) 
cvs.texi(,8918) @item -x@var{suffixes}
cvs.texi(,8919) In previous versions of @sc{cvs}, this was documented
cvs.texi(,8920) as a way of specifying the names of the @sc{rcs}
cvs.texi(,8921) files.  However, @sc{cvs} has always required that the
cvs.texi(,8922) @sc{rcs} files used by @sc{cvs} end in @samp{,v}, so
cvs.texi(,8923) this option has never done anything useful.
cvs.texi(,8924) 
cvs.texi(,8925) @c The rcs -z option, to specify the timezone, has
cvs.texi(,8926) @c never been documented as a cvs admin option.
cvs.texi(,8927) @end table
cvs.texi(,8928) 
cvs.texi(,8929) 
cvs.texi(,8930) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,8931) @node checkout
cvs.texi(,8932) @appendixsec checkout---Check out sources for editing
cvs.texi(,8933) @cindex checkout (subcommand)
cvs.texi(,8934) @cindex co (subcommand)
cvs.texi(,8935) 
cvs.texi(,8936) @itemize @bullet
cvs.texi(,8937) @item
cvs.texi(,8938) Synopsis: checkout [options] modules@dots{}
cvs.texi(,8939) @item
cvs.texi(,8940) Requires: repository.
cvs.texi(,8941) @item
cvs.texi(,8942) Changes: working directory.
cvs.texi(,8943) @item
cvs.texi(,8944) Synonyms: co, get
cvs.texi(,8945) @end itemize
cvs.texi(,8946) 
cvs.texi(,8947) Create or update a working directory containing copies of the
cvs.texi(,8948) source files specified by @var{modules}.  You must execute
cvs.texi(,8949) @code{checkout} before using most of the other @sc{cvs}
cvs.texi(,8950) commands, since most of them operate on your working
cvs.texi(,8951) directory.
cvs.texi(,8952) 
cvs.texi(,8953) The @var{modules} are either
cvs.texi(,8954) symbolic names for some
cvs.texi(,8955) collection of source directories and files, or paths to
cvs.texi(,8956) directories or files in the repository.  The symbolic
cvs.texi(,8957) names are defined in the @samp{modules} file.
cvs.texi(,8958) @xref{modules}.
cvs.texi(,8959) @c Needs an example, particularly of the non-"modules"
cvs.texi(,8960) @c case but probably of both.
cvs.texi(,8961) 
cvs.texi(,8962) @c FIXME: this seems like a very odd place to introduce
cvs.texi(,8963) @c people to how CVS works.  The bit about unreserved
cvs.texi(,8964) @c checkouts is also misleading as it depends on how
cvs.texi(,8965) @c things are set up.
cvs.texi(,8966) Depending on the modules you specify, @code{checkout} may
cvs.texi(,8967) recursively create directories and populate them with
cvs.texi(,8968) the appropriate source files.  You can then edit these
cvs.texi(,8969) source files at any time (regardless of whether other
cvs.texi(,8970) software developers are editing their own copies of the
cvs.texi(,8971) sources); update them to include new changes applied by
cvs.texi(,8972) others to the source repository; or commit your work as
cvs.texi(,8973) a permanent change to the source repository.
cvs.texi(,8974) 
cvs.texi(,8975) Note that @code{checkout} is used to create
cvs.texi(,8976) directories.  The top-level directory created is always
cvs.texi(,8977) added to the directory where @code{checkout} is
cvs.texi(,8978) invoked, and usually has the same name as the specified
cvs.texi(,8979) module.  In the case of a module alias, the created
cvs.texi(,8980) sub-directory may have a different name, but you can be
cvs.texi(,8981) sure that it will be a sub-directory, and that
cvs.texi(,8982) @code{checkout} will show the relative path leading to
cvs.texi(,8983) each file as it is extracted into your private work
cvs.texi(,8984) area (unless you specify the @samp{-Q} global option).
cvs.texi(,8985) 
cvs.texi(,8986) The files created by @code{checkout} are created
cvs.texi(,8987) read-write, unless the @samp{-r} option to @sc{cvs}
cvs.texi(,8988) (@pxref{Global options}) is specified, the
cvs.texi(,8989) @code{CVSREAD} environment variable is specified
cvs.texi(,8990) (@pxref{Environment variables}), or a watch is in
cvs.texi(,8991) effect for that file (@pxref{Watches}).
cvs.texi(,8992) 
cvs.texi(,8993) Note that running @code{checkout} on a directory that was already
cvs.texi(,8994) built by a prior @code{checkout} is also permitted.
cvs.texi(,8995) This is similar to specifying the @samp{-d} option
cvs.texi(,8996) to the @code{update} command in the sense that new
cvs.texi(,8997) directories that have been created in the repository
cvs.texi(,8998) will appear in your work area.
cvs.texi(,8999) However, @code{checkout} takes a module name whereas
cvs.texi(,9000) @code{update} takes a directory name.  Also
cvs.texi(,9001) to use @code{checkout} this way it must be run from the
cvs.texi(,9002) top level directory (where you originally ran
cvs.texi(,9003) @code{checkout} from), so before you run
cvs.texi(,9004) @code{checkout} to update an existing directory, don't
cvs.texi(,9005) forget to change your directory to the top level
cvs.texi(,9006) directory.
cvs.texi(,9007) 
cvs.texi(,9008) For the output produced by the @code{checkout} command
cvs.texi(,9009) see @ref{update output}.
cvs.texi(,9010) 
cvs.texi(,9011) @menu
cvs.texi(,9012) * checkout options::            checkout options
cvs.texi(,9013) * checkout examples::           checkout examples
cvs.texi(,9014) @end menu
cvs.texi(,9015) 
cvs.texi(,9016) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,9017) @node checkout options
cvs.texi(,9018) @appendixsubsec checkout options
cvs.texi(,9019) 
cvs.texi(,9020) These standard options are supported by @code{checkout}
cvs.texi(,9021) (@pxref{Common options}, for a complete description of
cvs.texi(,9022) them):
cvs.texi(,9023) 
cvs.texi(,9024) @table @code
cvs.texi(,9025) @item -D @var{date}
cvs.texi(,9026) Use the most recent revision no later than @var{date}.
cvs.texi(,9027) This option is sticky, and implies @samp{-P}.  See
cvs.texi(,9028) @ref{Sticky tags}, for more information on sticky tags/dates.
cvs.texi(,9029) 
cvs.texi(,9030) @item -f
cvs.texi(,9031) Only useful with the @samp{-D @var{date}} or @samp{-r
cvs.texi(,9032) @var{tag}} flags.  If no matching revision is found,
cvs.texi(,9033) retrieve the most recent revision (instead of ignoring
cvs.texi(,9034) the file).
cvs.texi(,9035) 
cvs.texi(,9036) @item -k @var{kflag}
cvs.texi(,9037) Process keywords according to @var{kflag}.  See
cvs.texi(,9038) @ref{Keyword substitution}.
cvs.texi(,9039) This option is sticky; future updates of
cvs.texi(,9040) this file in this working directory will use the same
cvs.texi(,9041) @var{kflag}.  The @code{status} command can be viewed
cvs.texi(,9042) to see the sticky options.  See @ref{Invoking CVS}, for
cvs.texi(,9043) more information on the @code{status} command.
cvs.texi(,9044) 
cvs.texi(,9045) @item -l
cvs.texi(,9046) Local; run only in current working directory.
cvs.texi(,9047) 
cvs.texi(,9048) @item -n
cvs.texi(,9049) Do not run any checkout program (as specified
cvs.texi(,9050) with the @samp{-o} option in the modules file;
cvs.texi(,9051) @pxref{modules}).
cvs.texi(,9052) 
cvs.texi(,9053) @item -P
cvs.texi(,9054) Prune empty directories.  See @ref{Moving directories}.
cvs.texi(,9055) 
cvs.texi(,9056) @item -p
cvs.texi(,9057) Pipe files to the standard output.
cvs.texi(,9058) 
cvs.texi(,9059) @item -R
cvs.texi(,9060) Checkout directories recursively.  This option is on by default.
cvs.texi(,9061) 
cvs.texi(,9062) @item -r @var{tag}
cvs.texi(,9063) Use revision @var{tag}.  This option is sticky, and implies @samp{-P}.
cvs.texi(,9064) See @ref{Sticky tags}, for more information on sticky tags/dates.
cvs.texi(,9065) @end table
cvs.texi(,9066) 
cvs.texi(,9067) In addition to those, you can use these special command
cvs.texi(,9068) options with @code{checkout}:
cvs.texi(,9069) 
cvs.texi(,9070) @table @code
cvs.texi(,9071) @item -A
cvs.texi(,9072) Reset any sticky tags, dates, or @samp{-k} options.
cvs.texi(,9073) See @ref{Sticky tags}, for more information on sticky tags/dates.
cvs.texi(,9074) 
cvs.texi(,9075) @item -c
cvs.texi(,9076) Copy the module file, sorted, to the standard output,
cvs.texi(,9077) instead of creating or modifying any files or
cvs.texi(,9078) directories in your working directory.
cvs.texi(,9079) 
cvs.texi(,9080) @item -d @var{dir}
cvs.texi(,9081) Create a directory called @var{dir} for the working
cvs.texi(,9082) files, instead of using the module name.  In general,
cvs.texi(,9083) using this flag is equivalent to using @samp{mkdir
cvs.texi(,9084) @var{dir}; cd @var{dir}} followed by the checkout
cvs.texi(,9085) command without the @samp{-d} flag.
cvs.texi(,9086) 
cvs.texi(,9087) There is an important exception, however.  It is very
cvs.texi(,9088) convenient when checking out a single item to have the
cvs.texi(,9089) output appear in a directory that doesn't contain empty
cvs.texi(,9090) intermediate directories.  In this case @emph{only},
cvs.texi(,9091) @sc{cvs} tries to ``shorten'' pathnames to avoid those empty
cvs.texi(,9092) directories.
cvs.texi(,9093) 
cvs.texi(,9094) For example, given a module @samp{foo} that contains
cvs.texi(,9095) the file @samp{bar.c}, the command @samp{cvs co -d dir
cvs.texi(,9096) foo} will create directory @samp{dir} and place
cvs.texi(,9097) @samp{bar.c} inside.  Similarly, given a module
cvs.texi(,9098) @samp{bar} which has subdirectory @samp{baz} wherein
cvs.texi(,9099) there is a file @samp{quux.c}, the command @samp{cvs co
cvs.texi(,9100) -d dir bar/baz} will create directory @samp{dir} and
cvs.texi(,9101) place @samp{quux.c} inside.
cvs.texi(,9102) 
cvs.texi(,9103) Using the @samp{-N} flag will defeat this behavior.
cvs.texi(,9104) Given the same module definitions above, @samp{cvs co
cvs.texi(,9105) -N -d dir foo} will create directories @samp{dir/foo}
cvs.texi(,9106) and place @samp{bar.c} inside, while @samp{cvs co -N -d
cvs.texi(,9107) dir bar/baz} will create directories @samp{dir/bar/baz}
cvs.texi(,9108) and place @samp{quux.c} inside.
cvs.texi(,9109) 
cvs.texi(,9110) @item -j @var{tag}
cvs.texi(,9111) With two @samp{-j} options, merge changes from the
cvs.texi(,9112) revision specified with the first @samp{-j} option to
cvs.texi(,9113) the revision specified with the second @samp{j} option,
cvs.texi(,9114) into the working directory.
cvs.texi(,9115) 
cvs.texi(,9116) With one @samp{-j} option, merge changes from the
cvs.texi(,9117) ancestor revision to the revision specified with the
cvs.texi(,9118) @samp{-j} option, into the working directory.  The
cvs.texi(,9119) ancestor revision is the common ancestor of the
cvs.texi(,9120) revision which the working directory is based on, and
cvs.texi(,9121) the revision specified in the @samp{-j} option.
cvs.texi(,9122) 
cvs.texi(,9123) In addition, each -j option can contain an optional
cvs.texi(,9124) date specification which, when used with branches, can
cvs.texi(,9125) limit the chosen revision to one within a specific
cvs.texi(,9126) date.  An optional date is specified by adding a colon
cvs.texi(,9127) (:) to the tag:
cvs.texi(,9128) @samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}.
cvs.texi(,9129) 
cvs.texi(,9130) @xref{Branching and merging}.
cvs.texi(,9131) 
cvs.texi(,9132) @item -N
cvs.texi(,9133) Only useful together with @samp{-d @var{dir}}.  With
cvs.texi(,9134) this option, @sc{cvs} will not ``shorten'' module paths
cvs.texi(,9135) in your working directory when you check out a single
cvs.texi(,9136) module.  See the @samp{-d} flag for examples and a
cvs.texi(,9137) discussion.
cvs.texi(,9138) 
cvs.texi(,9139) @item -s
cvs.texi(,9140) Like @samp{-c}, but include the status of all modules,
cvs.texi(,9141) and sort it by the status string.  @xref{modules}, for
cvs.texi(,9142) info about the @samp{-s} option that is used inside the
cvs.texi(,9143) modules file to set the module status.
cvs.texi(,9144) @end table
cvs.texi(,9145) 
cvs.texi(,9146) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,9147) @node checkout examples
cvs.texi(,9148) @appendixsubsec checkout examples
cvs.texi(,9149) 
cvs.texi(,9150) Get a copy of the module @samp{tc}:
cvs.texi(,9151) 
cvs.texi(,9152) @example
cvs.texi(,9153) $ cvs checkout tc
cvs.texi(,9154) @end example
cvs.texi(,9155) 
cvs.texi(,9156) Get a copy of the module @samp{tc} as it looked one day
cvs.texi(,9157) ago:
cvs.texi(,9158) 
cvs.texi(,9159) @example
cvs.texi(,9160) $ cvs checkout -D yesterday tc
cvs.texi(,9161) @end example
cvs.texi(,9162) 
cvs.texi(,9163) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,9164) @node commit
cvs.texi(,9165) @appendixsec commit---Check files into the repository
cvs.texi(,9166) @cindex commit (subcommand)
cvs.texi(,9167) 
cvs.texi(,9168) @itemize @bullet
cvs.texi(,9169) @item
cvs.texi(,9170) Synopsis: commit [-lnRf] [-m 'log_message' |
cvs.texi(,9171) -F file] [-r revision] [files@dots{}]
cvs.texi(,9172) @item
cvs.texi(,9173) Requires: working directory, repository.
cvs.texi(,9174) @item
cvs.texi(,9175) Changes: repository.
cvs.texi(,9176) @item
cvs.texi(,9177) Synonym: ci
cvs.texi(,9178) @end itemize
cvs.texi(,9179) 
cvs.texi(,9180) Use @code{commit} when you want to incorporate changes
cvs.texi(,9181) from your working source files into the source
cvs.texi(,9182) repository.
cvs.texi(,9183) 
cvs.texi(,9184) If you don't specify particular files to commit, all of
cvs.texi(,9185) the files in your working current directory are
cvs.texi(,9186) examined.  @code{commit} is careful to change in the
cvs.texi(,9187) repository only those files that you have really
cvs.texi(,9188) changed.  By default (or if you explicitly specify the
cvs.texi(,9189) @samp{-R} option), files in subdirectories are also
cvs.texi(,9190) examined and committed if they have changed; you can
cvs.texi(,9191) use the @samp{-l} option to limit @code{commit} to the
cvs.texi(,9192) current directory only.
cvs.texi(,9193) 
cvs.texi(,9194) @code{commit} verifies that the selected files are up
cvs.texi(,9195) to date with the current revisions in the source
cvs.texi(,9196) repository; it will notify you, and exit without
cvs.texi(,9197) committing, if any of the specified files must be made
cvs.texi(,9198) current first with @code{update} (@pxref{update}).
cvs.texi(,9199) @code{commit} does not call the @code{update} command
cvs.texi(,9200) for you, but rather leaves that for you to do when the
cvs.texi(,9201) time is right.
cvs.texi(,9202) 
cvs.texi(,9203) When all is well, an editor is invoked to allow you to
cvs.texi(,9204) enter a log message that will be written to one or more
cvs.texi(,9205) logging programs (@pxref{modules}, and @pxref{loginfo})
cvs.texi(,9206) and placed in the @sc{rcs} file inside the
cvs.texi(,9207) repository.  This log message can be retrieved with the
cvs.texi(,9208) @code{log} command; see @ref{log}.  You can specify the
cvs.texi(,9209) log message on the command line with the @samp{-m
cvs.texi(,9210) @var{message}} option, and thus avoid the editor invocation,
cvs.texi(,9211) or use the @samp{-F @var{file}} option to specify
cvs.texi(,9212) that the argument file contains the log message.
cvs.texi(,9213) 
cvs.texi(,9214) @menu
cvs.texi(,9215) * commit options::              commit options
cvs.texi(,9216) * commit examples::             commit examples
cvs.texi(,9217) @end menu
cvs.texi(,9218) 
cvs.texi(,9219) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,9220) @node commit options
cvs.texi(,9221) @appendixsubsec commit options
cvs.texi(,9222) 
cvs.texi(,9223) These standard options are supported by @code{commit}
cvs.texi(,9224) (@pxref{Common options}, for a complete description of
cvs.texi(,9225) them):
cvs.texi(,9226) 
cvs.texi(,9227) @table @code
cvs.texi(,9228) @item -l
cvs.texi(,9229) Local; run only in current working directory.
cvs.texi(,9230) 
cvs.texi(,9231) @item -R
cvs.texi(,9232) Commit directories recursively.  This is on by default.
cvs.texi(,9233) 
cvs.texi(,9234) @item -r @var{revision}
cvs.texi(,9235) Commit to @var{revision}.  @var{revision} must be
cvs.texi(,9236) either a branch, or a revision on the main trunk that
cvs.texi(,9237) is higher than any existing revision number
cvs.texi(,9238) (@pxref{Assigning revisions}).  You
cvs.texi(,9239) cannot commit to a specific revision on a branch.
cvs.texi(,9240) @c FIXME: Need xref for branch case.
cvs.texi(,9241) @end table
cvs.texi(,9242) 
cvs.texi(,9243) @code{commit} also supports these options:
cvs.texi(,9244) 
cvs.texi(,9245) @table @code
cvs.texi(,9246) @item -F @var{file}
cvs.texi(,9247) Read the log message from @var{file}, instead
cvs.texi(,9248) of invoking an editor.
cvs.texi(,9249) 
cvs.texi(,9250) @item -f
cvs.texi(,9251) Note that this is not the standard behavior of
cvs.texi(,9252) the @samp{-f} option as defined in @ref{Common options}.
cvs.texi(,9253) 
cvs.texi(,9254) Force @sc{cvs} to commit a new revision even if you haven't
cvs.texi(,9255) made any changes to the file.  If the current revision
cvs.texi(,9256) of @var{file} is 1.7, then the following two commands
cvs.texi(,9257) are equivalent:
cvs.texi(,9258) 
cvs.texi(,9259) @example
cvs.texi(,9260) $ cvs commit -f @var{file}
cvs.texi(,9261) $ cvs commit -r 1.8 @var{file}
cvs.texi(,9262) @end example
cvs.texi(,9263) 
cvs.texi(,9264) @c This is odd, but it's how CVS has worked for some
cvs.texi(,9265) @c time.
cvs.texi(,9266) The @samp{-f} option disables recursion (i.e., it
cvs.texi(,9267) implies @samp{-l}).  To force @sc{cvs} to commit a new
cvs.texi(,9268) revision for all files in all subdirectories, you must
cvs.texi(,9269) use @samp{-f -R}.
cvs.texi(,9270) 
cvs.texi(,9271) @item -m @var{message}
cvs.texi(,9272) Use @var{message} as the log message, instead of
cvs.texi(,9273) invoking an editor.
cvs.texi(,9274) @end table
cvs.texi(,9275) 
cvs.texi(,9276) @need 2000
cvs.texi(,9277) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,9278) @node commit examples
cvs.texi(,9279) @appendixsubsec commit examples
cvs.texi(,9280) 
cvs.texi(,9281) @c FIXME: this material wants to be somewhere
cvs.texi(,9282) @c in "Branching and merging".
cvs.texi(,9283) 
cvs.texi(,9284) @appendixsubsubsec Committing to a branch
cvs.texi(,9285) 
cvs.texi(,9286) You can commit to a branch revision (one that has an
cvs.texi(,9287) even number of dots) with the @samp{-r} option.  To
cvs.texi(,9288) create a branch revision, use the @samp{-b} option
cvs.texi(,9289) of the @code{rtag} or @code{tag} commands
cvs.texi(,9290) (@pxref{Branching and merging}).  Then, either @code{checkout} or
cvs.texi(,9291) @code{update} can be used to base your sources on the
cvs.texi(,9292) newly created branch.  From that point on, all
cvs.texi(,9293) @code{commit} changes made within these working sources
cvs.texi(,9294) will be automatically added to a branch revision,
cvs.texi(,9295) thereby not disturbing main-line development in any
cvs.texi(,9296) way.  For example, if you had to create a patch to the
cvs.texi(,9297) 1.2 version of the product, even though the 2.0 version
cvs.texi(,9298) is already under development, you might do:
cvs.texi(,9299) 
cvs.texi(,9300) @example
cvs.texi(,9301) $ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module
cvs.texi(,9302) $ cvs checkout -r FCS1_2_Patch product_module
cvs.texi(,9303) $ cd product_module
cvs.texi(,9304) [[ hack away ]]
cvs.texi(,9305) $ cvs commit
cvs.texi(,9306) @end example
cvs.texi(,9307) 
cvs.texi(,9308) @noindent
cvs.texi(,9309) This works automatically since the @samp{-r} option is
cvs.texi(,9310) sticky.
cvs.texi(,9311) 
cvs.texi(,9312) @appendixsubsubsec Creating the branch after editing
cvs.texi(,9313) 
cvs.texi(,9314) Say you have been working on some extremely
cvs.texi(,9315) experimental software, based on whatever revision you
cvs.texi(,9316) happened to checkout last week.  If others in your
cvs.texi(,9317) group would like to work on this software with you, but
cvs.texi(,9318) without disturbing main-line development, you could
cvs.texi(,9319) commit your change to a new branch.  Others can then
cvs.texi(,9320) checkout your experimental stuff and utilize the full
cvs.texi(,9321) benefit of @sc{cvs} conflict resolution.  The scenario might
cvs.texi(,9322) look like:
cvs.texi(,9323) 
cvs.texi(,9324) @c FIXME: Should we be recommending tagging the branchpoint?
cvs.texi(,9325) @example
cvs.texi(,9326) [[ hacked sources are present ]]
cvs.texi(,9327) $ cvs tag -b EXPR1
cvs.texi(,9328) $ cvs update -r EXPR1
cvs.texi(,9329) $ cvs commit
cvs.texi(,9330) @end example
cvs.texi(,9331) 
cvs.texi(,9332) The @code{update} command will make the @samp{-r
cvs.texi(,9333) EXPR1} option sticky on all files.  Note that your
cvs.texi(,9334) changes to the files will never be removed by the
cvs.texi(,9335) @code{update} command.  The @code{commit} will
cvs.texi(,9336) automatically commit to the correct branch, because the
cvs.texi(,9337) @samp{-r} is sticky.  You could also do like this:
cvs.texi(,9338) 
cvs.texi(,9339) @c FIXME: Should we be recommending tagging the branchpoint?
cvs.texi(,9340) @example
cvs.texi(,9341) [[ hacked sources are present ]]
cvs.texi(,9342) $ cvs tag -b EXPR1
cvs.texi(,9343) $ cvs commit -r EXPR1
cvs.texi(,9344) @end example
cvs.texi(,9345) 
cvs.texi(,9346) @noindent
cvs.texi(,9347) but then, only those files that were changed by you
cvs.texi(,9348) will have the @samp{-r EXPR1} sticky flag.  If you hack
cvs.texi(,9349) away, and commit without specifying the @samp{-r EXPR1}
cvs.texi(,9350) flag, some files may accidentally end up on the main
cvs.texi(,9351) trunk.
cvs.texi(,9352) 
cvs.texi(,9353) To work with you on the experimental change, others
cvs.texi(,9354) would simply do
cvs.texi(,9355) 
cvs.texi(,9356) @example
cvs.texi(,9357) $ cvs checkout -r EXPR1 whatever_module
cvs.texi(,9358) @end example
cvs.texi(,9359) 
cvs.texi(,9360) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,9361) @node diff
cvs.texi(,9362) @appendixsec diff---Show differences between revisions
cvs.texi(,9363) @cindex diff (subcommand)
cvs.texi(,9364) 
cvs.texi(,9365) @itemize @bullet
cvs.texi(,9366) @item
cvs.texi(,9367) Synopsis: diff [-lR] [-k kflag] [format_options] [[-r rev1 | -D date1] [-r rev2 |  -D date2]] [files@dots{}]
cvs.texi(,9368) @item
cvs.texi(,9369) Requires: working directory, repository.
cvs.texi(,9370) @item
cvs.texi(,9371) Changes: nothing.
cvs.texi(,9372) @end itemize
cvs.texi(,9373) 
cvs.texi(,9374) The @code{diff} command is used to compare different
cvs.texi(,9375) revisions of files.  The default action is to compare
cvs.texi(,9376) your working files with the revisions they were based
cvs.texi(,9377) on, and report any differences that are found.
cvs.texi(,9378) 
cvs.texi(,9379) If any file names are given, only those files are
cvs.texi(,9380) compared.  If any directories are given, all files
cvs.texi(,9381) under them will be compared.
cvs.texi(,9382) 
cvs.texi(,9383) The exit status for diff is different than for other
cvs.texi(,9384) @sc{cvs} commands; for details @ref{Exit status}.
cvs.texi(,9385) 
cvs.texi(,9386) @menu
cvs.texi(,9387) * diff options::                diff options
cvs.texi(,9388) * diff examples::               diff examples
cvs.texi(,9389) @end menu
cvs.texi(,9390) 
cvs.texi(,9391) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,9392) @node diff options
cvs.texi(,9393) @appendixsubsec diff options
cvs.texi(,9394) 
cvs.texi(,9395) These standard options are supported by @code{diff}
cvs.texi(,9396) (@pxref{Common options}, for a complete description of
cvs.texi(,9397) them):
cvs.texi(,9398) 
cvs.texi(,9399) @table @code
cvs.texi(,9400) @item -D @var{date}
cvs.texi(,9401) Use the most recent revision no later than @var{date}.
cvs.texi(,9402) See @samp{-r} for how this affects the comparison.
cvs.texi(,9403) 
cvs.texi(,9404) @item -k @var{kflag}
cvs.texi(,9405) Process keywords according to @var{kflag}.  See
cvs.texi(,9406) @ref{Keyword substitution}.
cvs.texi(,9407) 
cvs.texi(,9408) @item -l
cvs.texi(,9409) Local; run only in current working directory.
cvs.texi(,9410) 
cvs.texi(,9411) @item -R
cvs.texi(,9412) Examine directories recursively.  This option is on by
cvs.texi(,9413) default.
cvs.texi(,9414) 
cvs.texi(,9415) @item -r @var{tag}
cvs.texi(,9416) Compare with revision @var{tag}.  Zero, one or two
cvs.texi(,9417) @samp{-r} options can be present.  With no @samp{-r}
cvs.texi(,9418) option, the working file will be compared with the
cvs.texi(,9419) revision it was based on.  With one @samp{-r}, that
cvs.texi(,9420) revision will be compared to your current working file.
cvs.texi(,9421) With two @samp{-r} options those two revisions will be
cvs.texi(,9422) compared (and your working file will not affect the
cvs.texi(,9423) outcome in any way).
cvs.texi(,9424) @c We should be a lot more explicit, with examples,
cvs.texi(,9425) @c about the difference between "cvs diff" and "cvs
cvs.texi(,9426) @c diff -r HEAD".  This often confuses new users.
cvs.texi(,9427) 
cvs.texi(,9428) One or both @samp{-r} options can be replaced by a
cvs.texi(,9429) @samp{-D @var{date}} option, described above.
cvs.texi(,9430) @end table
cvs.texi(,9431) 
cvs.texi(,9432) @c Conceptually, this is a disaster.  There are 3
cvs.texi(,9433) @c zillion diff formats that we support via the diff
cvs.texi(,9434) @c library.  It is not obvious to me that we should
cvs.texi(,9435) @c document them all.  Maybe just the most common ones
cvs.texi(,9436) @c like -c and -u, and think about phasing out the
cvs.texi(,9437) @c obscure ones.
cvs.texi(,9438) @c FIXCVS: also should be a way to specify an external
cvs.texi(,9439) @c diff program (which can be different for different
cvs.texi(,9440) @c file types) and pass through
cvs.texi(,9441) @c arbitrary options, so that the user can do
cvs.texi(,9442) @c "--pass=-Z --pass=foo" or something even if CVS
cvs.texi(,9443) @c doesn't know about the "-Z foo" option to diff.
cvs.texi(,9444) @c This would fit nicely with deprecating/eliminating
cvs.texi(,9445) @c the obscure options of the diff library, because it
cvs.texi(,9446) @c would let people specify an external GNU diff if
cvs.texi(,9447) @c they are into that sort of thing.
cvs.texi(,9448) The following options specify the format of the
cvs.texi(,9449) output.  They have the same meaning as in GNU diff.
cvs.texi(,9450) Most options have two equivalent names, one of which is a single letter
cvs.texi(,9451) preceded by @samp{-}, and the other of which is a long name preceded by
cvs.texi(,9452) @samp{--}.
cvs.texi(,9453) 
cvs.texi(,9454) @table @samp
cvs.texi(,9455) @item -@var{lines}
cvs.texi(,9456) Show @var{lines} (an integer) lines of context.  This option does not
cvs.texi(,9457) specify an output format by itself; it has no effect unless it is
cvs.texi(,9458) combined with @samp{-c} or @samp{-u}.  This option is obsolete.  For proper
cvs.texi(,9459) operation, @code{patch} typically needs at least two lines of context.
cvs.texi(,9460) 
cvs.texi(,9461) @item -a
cvs.texi(,9462) Treat all files as text and compare them line-by-line, even if they
cvs.texi(,9463) do not seem to be text.
cvs.texi(,9464) 
cvs.texi(,9465) @item -b
cvs.texi(,9466) Ignore trailing white space and consider all other sequences of one or
cvs.texi(,9467) more white space characters to be equivalent.
cvs.texi(,9468) 
cvs.texi(,9469) @item -B
cvs.texi(,9470) Ignore changes that just insert or delete blank lines.
cvs.texi(,9471) 
cvs.texi(,9472) @item --binary
cvs.texi(,9473) Read and write data in binary mode.
cvs.texi(,9474) 
cvs.texi(,9475) @item --brief
cvs.texi(,9476) Report only whether the files differ, not the details of the
cvs.texi(,9477) differences.
cvs.texi(,9478) 
cvs.texi(,9479) @item -c
cvs.texi(,9480) Use the context output format.
cvs.texi(,9481) 
cvs.texi(,9482) @item -C @var{lines}
cvs.texi(,9483) @itemx --context@r{[}=@var{lines}@r{]}
cvs.texi(,9484) Use the context output format, showing @var{lines} (an integer) lines of
cvs.texi(,9485) context, or three if @var{lines} is not given.
cvs.texi(,9486) For proper operation, @code{patch} typically needs at least two lines of
cvs.texi(,9487) context.
cvs.texi(,9488) 
cvs.texi(,9489) @item --changed-group-format=@var{format}
cvs.texi(,9490) Use @var{format} to output a line group containing differing lines from
cvs.texi(,9491) both files in if-then-else format.  @xref{Line group formats}.
cvs.texi(,9492) 
cvs.texi(,9493) @item -d
cvs.texi(,9494) Change the algorithm to perhaps find a smaller set of changes.  This makes
cvs.texi(,9495) @code{diff} slower (sometimes much slower).
cvs.texi(,9496) 
cvs.texi(,9497) @item -e
cvs.texi(,9498) @itemx --ed
cvs.texi(,9499) Make output that is a valid @code{ed} script.
cvs.texi(,9500) 
cvs.texi(,9501) @item --expand-tabs
cvs.texi(,9502) Expand tabs to spaces in the output, to preserve the alignment of tabs
cvs.texi(,9503) in the input files.
cvs.texi(,9504) 
cvs.texi(,9505) @item -f
cvs.texi(,9506) Make output that looks vaguely like an @code{ed} script but has changes
cvs.texi(,9507) in the order they appear in the file.
cvs.texi(,9508) 
cvs.texi(,9509) @item -F @var{regexp}
cvs.texi(,9510) In context and unified format, for each hunk of differences, show some
cvs.texi(,9511) of the last preceding line that matches @var{regexp}.
cvs.texi(,9512) 
cvs.texi(,9513) @item --forward-ed
cvs.texi(,9514) Make output that looks vaguely like an @code{ed} script but has changes
cvs.texi(,9515) in the order they appear in the file.
cvs.texi(,9516) 
cvs.texi(,9517) @item -H
cvs.texi(,9518) Use heuristics to speed handling of large files that have numerous
cvs.texi(,9519) scattered small changes.
cvs.texi(,9520) 
cvs.texi(,9521) @item --horizon-lines=@var{lines}
cvs.texi(,9522) Do not discard the last @var{lines} lines of the common prefix
cvs.texi(,9523) and the first @var{lines} lines of the common suffix.
cvs.texi(,9524) 
cvs.texi(,9525) @item -i
cvs.texi(,9526) Ignore changes in case; consider upper- and lower-case letters
cvs.texi(,9527) equivalent.
cvs.texi(,9528) 
cvs.texi(,9529) @item -I @var{regexp}
cvs.texi(,9530) Ignore changes that just insert or delete lines that match @var{regexp}.
cvs.texi(,9531) 
cvs.texi(,9532) @item --ifdef=@var{name}
cvs.texi(,9533) Make merged if-then-else output using @var{name}.
cvs.texi(,9534) 
cvs.texi(,9535) @item --ignore-all-space
cvs.texi(,9536) Ignore white space when comparing lines.
cvs.texi(,9537) 
cvs.texi(,9538) @item --ignore-blank-lines
cvs.texi(,9539) Ignore changes that just insert or delete blank lines.
cvs.texi(,9540) 
cvs.texi(,9541) @item --ignore-case
cvs.texi(,9542) Ignore changes in case; consider upper- and lower-case to be the same.
cvs.texi(,9543) 
cvs.texi(,9544) @item --ignore-matching-lines=@var{regexp}
cvs.texi(,9545) Ignore changes that just insert or delete lines that match @var{regexp}.
cvs.texi(,9546) 
cvs.texi(,9547) @item --ignore-space-change
cvs.texi(,9548) Ignore trailing white space and consider all other sequences of one or
cvs.texi(,9549) more white space characters to be equivalent.
cvs.texi(,9550) 
cvs.texi(,9551) @item --initial-tab
cvs.texi(,9552) Output a tab rather than a space before the text of a line in normal or
cvs.texi(,9553) context format.  This causes the alignment of tabs in the line to look
cvs.texi(,9554) normal.
cvs.texi(,9555) 
cvs.texi(,9556) @item -L @var{label}
cvs.texi(,9557) Use @var{label} instead of the file name in the context format
cvs.texi(,9558) and unified format headers.
cvs.texi(,9559) 
cvs.texi(,9560) @item --label=@var{label}
cvs.texi(,9561) Use @var{label} instead of the file name in the context format
cvs.texi(,9562) and unified format headers.
cvs.texi(,9563) 
cvs.texi(,9564) @item --left-column
cvs.texi(,9565) Print only the left column of two common lines in side by side format.
cvs.texi(,9566) 
cvs.texi(,9567) @item --line-format=@var{format}
cvs.texi(,9568) Use @var{format} to output all input lines in if-then-else format.
cvs.texi(,9569) @xref{Line formats}.
cvs.texi(,9570) 
cvs.texi(,9571) @item --minimal
cvs.texi(,9572) Change the algorithm to perhaps find a smaller set of changes.  This
cvs.texi(,9573) makes @code{diff} slower (sometimes much slower).
cvs.texi(,9574) 
cvs.texi(,9575) @item -n
cvs.texi(,9576) Output RCS-format diffs; like @samp{-f} except that each command
cvs.texi(,9577) specifies the number of lines affected.
cvs.texi(,9578) 
cvs.texi(,9579) @item -N
cvs.texi(,9580) @itemx --new-file
cvs.texi(,9581) In directory comparison, if a file is found in only one directory,
cvs.texi(,9582) treat it as present but empty in the other directory.
cvs.texi(,9583) 
cvs.texi(,9584) @item --new-group-format=@var{format}
cvs.texi(,9585) Use @var{format} to output a group of lines taken from just the second
cvs.texi(,9586) file in if-then-else format.  @xref{Line group formats}.
cvs.texi(,9587) 
cvs.texi(,9588) @item --new-line-format=@var{format}
cvs.texi(,9589) Use @var{format} to output a line taken from just the second file in
cvs.texi(,9590) if-then-else format.  @xref{Line formats}.
cvs.texi(,9591) 
cvs.texi(,9592) @item --old-group-format=@var{format}
cvs.texi(,9593) Use @var{format} to output a group of lines taken from just the first
cvs.texi(,9594) file in if-then-else format.  @xref{Line group formats}.
cvs.texi(,9595) 
cvs.texi(,9596) @item --old-line-format=@var{format}
cvs.texi(,9597) Use @var{format} to output a line taken from just the first file in
cvs.texi(,9598) if-then-else format.  @xref{Line formats}.
cvs.texi(,9599) 
cvs.texi(,9600) @item -p
cvs.texi(,9601) Show which C function each change is in.
cvs.texi(,9602) 
cvs.texi(,9603) @item --rcs
cvs.texi(,9604) Output RCS-format diffs; like @samp{-f} except that each command
cvs.texi(,9605) specifies the number of lines affected.
cvs.texi(,9606) 
cvs.texi(,9607) @item --report-identical-files
cvs.texi(,9608) @itemx -s
cvs.texi(,9609) Report when two files are the same.
cvs.texi(,9610) 
cvs.texi(,9611) @item --show-c-function
cvs.texi(,9612) Show which C function each change is in.
cvs.texi(,9613) 
cvs.texi(,9614) @item --show-function-line=@var{regexp}
cvs.texi(,9615) In context and unified format, for each hunk of differences, show some
cvs.texi(,9616) of the last preceding line that matches @var{regexp}.
cvs.texi(,9617) 
cvs.texi(,9618) @item --side-by-side
cvs.texi(,9619) Use the side by side output format.
cvs.texi(,9620) 
cvs.texi(,9621) @item --speed-large-files
cvs.texi(,9622) Use heuristics to speed handling of large files that have numerous
cvs.texi(,9623) scattered small changes.
cvs.texi(,9624) 
cvs.texi(,9625) @item --suppress-common-lines
cvs.texi(,9626) Do not print common lines in side by side format.
cvs.texi(,9627) 
cvs.texi(,9628) @item -t
cvs.texi(,9629) Expand tabs to spaces in the output, to preserve the alignment of tabs
cvs.texi(,9630) in the input files.
cvs.texi(,9631) 
cvs.texi(,9632) @item -T
cvs.texi(,9633) Output a tab rather than a space before the text of a line in normal or
cvs.texi(,9634) context format.  This causes the alignment of tabs in the line to look
cvs.texi(,9635) normal.
cvs.texi(,9636) 
cvs.texi(,9637) @item --text
cvs.texi(,9638) Treat all files as text and compare them line-by-line, even if they
cvs.texi(,9639) do not appear to be text.
cvs.texi(,9640) 
cvs.texi(,9641) @item -u
cvs.texi(,9642) Use the unified output format.
cvs.texi(,9643) 
cvs.texi(,9644) @item --unchanged-group-format=@var{format}
cvs.texi(,9645) Use @var{format} to output a group of common lines taken from both files
cvs.texi(,9646) in if-then-else format.  @xref{Line group formats}.
cvs.texi(,9647) 
cvs.texi(,9648) @item --unchanged-line-format=@var{format}
cvs.texi(,9649) Use @var{format} to output a line common to both files in if-then-else
cvs.texi(,9650) format.  @xref{Line formats}.
cvs.texi(,9651) 
cvs.texi(,9652) @item -U @var{lines}
cvs.texi(,9653) @itemx --unified@r{[}=@var{lines}@r{]}
cvs.texi(,9654) Use the unified output format, showing @var{lines} (an integer) lines of
cvs.texi(,9655) context, or three if @var{lines} is not given.
cvs.texi(,9656) For proper operation, @code{patch} typically needs at least two lines of
cvs.texi(,9657) context.
cvs.texi(,9658) 
cvs.texi(,9659) @item -w
cvs.texi(,9660) Ignore white space when comparing lines.
cvs.texi(,9661) 
cvs.texi(,9662) @item -W @var{columns}
cvs.texi(,9663) @itemx --width=@var{columns}
cvs.texi(,9664) Use an output width of @var{columns} in side by side format.
cvs.texi(,9665) 
cvs.texi(,9666) @item -y
cvs.texi(,9667) Use the side by side output format.
cvs.texi(,9668) @end table
cvs.texi(,9669) 
cvs.texi(,9670) @menu
cvs.texi(,9671) * Line group formats::          Line group formats
cvs.texi(,9672) * Line formats::                Line formats
cvs.texi(,9673) @end menu
cvs.texi(,9674) 
cvs.texi(,9675) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,9676) @node Line group formats
cvs.texi(,9677) @appendixsubsubsec Line group formats
cvs.texi(,9678) 
cvs.texi(,9679) Line group formats let you specify formats suitable for many
cvs.texi(,9680) applications that allow if-then-else input, including programming
cvs.texi(,9681) languages and text formatting languages.  A line group format specifies
cvs.texi(,9682) the output format for a contiguous group of similar lines.
cvs.texi(,9683) 
cvs.texi(,9684) For example, the following command compares the TeX file @file{myfile}
cvs.texi(,9685) with the original version from the repository,
cvs.texi(,9686) and outputs a merged file in which old regions are
cvs.texi(,9687) surrounded by @samp{\begin@{em@}}-@samp{\end@{em@}} lines, and new
cvs.texi(,9688) regions are surrounded by @samp{\begin@{bf@}}-@samp{\end@{bf@}} lines.
cvs.texi(,9689) 
cvs.texi(,9690) @example
cvs.texi(,9691) cvs diff \
cvs.texi(,9692)    --old-group-format='\begin@{em@}
cvs.texi(,9693) %<\end@{em@}
cvs.texi(,9694) ' \
cvs.texi(,9695)    --new-group-format='\begin@{bf@}
cvs.texi(,9696) %>\end@{bf@}
cvs.texi(,9697) ' \
cvs.texi(,9698)    myfile
cvs.texi(,9699) @end example
cvs.texi(,9700) 
cvs.texi(,9701) The following command is equivalent to the above example, but it is a
cvs.texi(,9702) little more verbose, because it spells out the default line group formats.
cvs.texi(,9703) 
cvs.texi(,9704) @example
cvs.texi(,9705) cvs diff \
cvs.texi(,9706)    --old-group-format='\begin@{em@}
cvs.texi(,9707) %<\end@{em@}
cvs.texi(,9708) ' \
cvs.texi(,9709)    --new-group-format='\begin@{bf@}
cvs.texi(,9710) %>\end@{bf@}
cvs.texi(,9711) ' \
cvs.texi(,9712)    --unchanged-group-format='%=' \
cvs.texi(,9713)    --changed-group-format='\begin@{em@}
cvs.texi(,9714) %<\end@{em@}
cvs.texi(,9715) \begin@{bf@}
cvs.texi(,9716) %>\end@{bf@}
cvs.texi(,9717) ' \
cvs.texi(,9718)    myfile
cvs.texi(,9719) @end example
cvs.texi(,9720) 
cvs.texi(,9721) Here is a more advanced example, which outputs a diff listing with
cvs.texi(,9722) headers containing line numbers in a ``plain English'' style.
cvs.texi(,9723) 
cvs.texi(,9724) @example
cvs.texi(,9725) cvs diff \
cvs.texi(,9726)    --unchanged-group-format='' \
cvs.texi(,9727)    --old-group-format='-------- %dn line%(n=1?:s) deleted at %df:
cvs.texi(,9728) %<' \
cvs.texi(,9729)    --new-group-format='-------- %dN line%(N=1?:s) added after %de:
cvs.texi(,9730) %>' \
cvs.texi(,9731)    --changed-group-format='-------- %dn line%(n=1?:s) changed at %df:
cvs.texi(,9732) %<-------- to:
cvs.texi(,9733) %>' \
cvs.texi(,9734)    myfile
cvs.texi(,9735) @end example
cvs.texi(,9736) 
cvs.texi(,9737) To specify a line group format, use one of the options
cvs.texi(,9738) listed below.  You can specify up to four line group formats, one for
cvs.texi(,9739) each kind of line group.  You should quote @var{format}, because it
cvs.texi(,9740) typically contains shell metacharacters.
cvs.texi(,9741) 
cvs.texi(,9742) @table @samp
cvs.texi(,9743) @item --old-group-format=@var{format}
cvs.texi(,9744) These line groups are hunks containing only lines from the first file.
cvs.texi(,9745) The default old group format is the same as the changed group format if
cvs.texi(,9746) it is specified; otherwise it is a format that outputs the line group as-is.
cvs.texi(,9747) 
cvs.texi(,9748) @item --new-group-format=@var{format}
cvs.texi(,9749) These line groups are hunks containing only lines from the second
cvs.texi(,9750) file.  The default new group format is same as the changed group
cvs.texi(,9751) format if it is specified; otherwise it is a format that outputs the
cvs.texi(,9752) line group as-is.
cvs.texi(,9753) 
cvs.texi(,9754) @item --changed-group-format=@var{format}
cvs.texi(,9755) These line groups are hunks containing lines from both files.  The
cvs.texi(,9756) default changed group format is the concatenation of the old and new
cvs.texi(,9757) group formats.
cvs.texi(,9758) 
cvs.texi(,9759) @item --unchanged-group-format=@var{format}
cvs.texi(,9760) These line groups contain lines common to both files.  The default
cvs.texi(,9761) unchanged group format is a format that outputs the line group as-is.
cvs.texi(,9762) @end table
cvs.texi(,9763) 
cvs.texi(,9764) In a line group format, ordinary characters represent themselves;
cvs.texi(,9765) conversion specifications start with @samp{%} and have one of the
cvs.texi(,9766) following forms.
cvs.texi(,9767) 
cvs.texi(,9768) @table @samp
cvs.texi(,9769) @item %<
cvs.texi(,9770) stands for the lines from the first file, including the trailing newline.
cvs.texi(,9771) Each line is formatted according to the old line format (@pxref{Line formats}).
cvs.texi(,9772) 
cvs.texi(,9773) @item %>
cvs.texi(,9774) stands for the lines from the second file, including the trailing newline.
cvs.texi(,9775) Each line is formatted according to the new line format.
cvs.texi(,9776) 
cvs.texi(,9777) @item %=
cvs.texi(,9778) stands for the lines common to both files, including the trailing newline.
cvs.texi(,9779) Each line is formatted according to the unchanged line format.
cvs.texi(,9780) 
cvs.texi(,9781) @item %%
cvs.texi(,9782) stands for @samp{%}.
cvs.texi(,9783) 
cvs.texi(,9784) @item %c'@var{C}'
cvs.texi(,9785) where @var{C} is a single character, stands for @var{C}.
cvs.texi(,9786) @var{C} may not be a backslash or an apostrophe.
cvs.texi(,9787) For example, @samp{%c':'} stands for a colon, even inside
cvs.texi(,9788) the then-part of an if-then-else format, which a colon would
cvs.texi(,9789) normally terminate.
cvs.texi(,9790) 
cvs.texi(,9791) @item %c'\@var{O}'
cvs.texi(,9792) where @var{O} is a string of 1, 2, or 3 octal digits,
cvs.texi(,9793) stands for the character with octal code @var{O}.
cvs.texi(,9794) For example, @samp{%c'\0'} stands for a null character.
cvs.texi(,9795) 
cvs.texi(,9796) @item @var{F}@var{n}
cvs.texi(,9797) where @var{F} is a @code{printf} conversion specification and @var{n} is one
cvs.texi(,9798) of the following letters, stands for @var{n}'s value formatted with @var{F}.
cvs.texi(,9799) 
cvs.texi(,9800) @table @samp
cvs.texi(,9801) @item e
cvs.texi(,9802) The line number of the line just before the group in the old file.
cvs.texi(,9803) 
cvs.texi(,9804) @item f
cvs.texi(,9805) The line number of the first line in the group in the old file;
cvs.texi(,9806) equals @var{e} + 1.
cvs.texi(,9807) 
cvs.texi(,9808) @item l
cvs.texi(,9809) The line number of the last line in the group in the old file.
cvs.texi(,9810) 
cvs.texi(,9811) @item m
cvs.texi(,9812) The line number of the line just after the group in the old file;
cvs.texi(,9813) equals @var{l} + 1.
cvs.texi(,9814) 
cvs.texi(,9815) @item n
cvs.texi(,9816) The number of lines in the group in the old file; equals @var{l} - @var{f} + 1.
cvs.texi(,9817) 
cvs.texi(,9818) @item E, F, L, M, N
cvs.texi(,9819) Likewise, for lines in the new file.
cvs.texi(,9820) 
cvs.texi(,9821) @end table
cvs.texi(,9822) 
cvs.texi(,9823) The @code{printf} conversion specification can be @samp{%d},
cvs.texi(,9824) @samp{%o}, @samp{%x}, or @samp{%X}, specifying decimal, octal,
cvs.texi(,9825) lower case hexadecimal, or upper case hexadecimal output
cvs.texi(,9826) respectively.  After the @samp{%} the following options can appear in
cvs.texi(,9827) sequence: a @samp{-} specifying left-justification; an integer
cvs.texi(,9828) specifying the minimum field width; and a period followed by an
cvs.texi(,9829) optional integer specifying the minimum number of digits.
cvs.texi(,9830) For example, @samp{%5dN} prints the number of new lines in the group
cvs.texi(,9831) in a field of width 5 characters, using the @code{printf} format @code{"%5d"}.
cvs.texi(,9832) 
cvs.texi(,9833) @item (@var{A}=@var{B}?@var{T}:@var{E})
cvs.texi(,9834) If @var{A} equals @var{B} then @var{T} else @var{E}.
cvs.texi(,9835) @var{A} and @var{B} are each either a decimal constant
cvs.texi(,9836) or a single letter interpreted as above.
cvs.texi(,9837) This format spec is equivalent to @var{T} if
cvs.texi(,9838) @var{A}'s value equals @var{B}'s; otherwise it is equivalent to @var{E}.
cvs.texi(,9839) 
cvs.texi(,9840) For example, @samp{%(N=0?no:%dN) line%(N=1?:s)} is equivalent to
cvs.texi(,9841) @samp{no lines} if @var{N} (the number of lines in the group in the
cvs.texi(,9842) new file) is 0, to @samp{1 line} if @var{N} is 1, and to @samp{%dN lines}
cvs.texi(,9843) otherwise.
cvs.texi(,9844) @end table
cvs.texi(,9845) 
cvs.texi(,9846) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,9847) @node Line formats
cvs.texi(,9848) @appendixsubsubsec Line formats
cvs.texi(,9849) 
cvs.texi(,9850) Line formats control how each line taken from an input file is
cvs.texi(,9851) output as part of a line group in if-then-else format.
cvs.texi(,9852) 
cvs.texi(,9853) For example, the following command outputs text with a one-column
cvs.texi(,9854) change indicator to the left of the text.  The first column of output
cvs.texi(,9855) is @samp{-} for deleted lines, @samp{|} for added lines, and a space
cvs.texi(,9856) for unchanged lines.  The formats contain newline characters where
cvs.texi(,9857) newlines are desired on output.
cvs.texi(,9858) 
cvs.texi(,9859) @example
cvs.texi(,9860) cvs diff \
cvs.texi(,9861)    --old-line-format='-%l
cvs.texi(,9862) ' \
cvs.texi(,9863)    --new-line-format='|%l
cvs.texi(,9864) ' \
cvs.texi(,9865)    --unchanged-line-format=' %l
cvs.texi(,9866) ' \
cvs.texi(,9867)    myfile
cvs.texi(,9868) @end example
cvs.texi(,9869) 
cvs.texi(,9870) To specify a line format, use one of the following options.  You should
cvs.texi(,9871) quote @var{format}, since it often contains shell metacharacters.
cvs.texi(,9872) 
cvs.texi(,9873) @table @samp
cvs.texi(,9874) @item --old-line-format=@var{format}
cvs.texi(,9875) formats lines just from the first file.
cvs.texi(,9876) 
cvs.texi(,9877) @item --new-line-format=@var{format}
cvs.texi(,9878) formats lines just from the second file.
cvs.texi(,9879) 
cvs.texi(,9880) @item --unchanged-line-format=@var{format}
cvs.texi(,9881) formats lines common to both files.
cvs.texi(,9882) 
cvs.texi(,9883) @item --line-format=@var{format}
cvs.texi(,9884) formats all lines; in effect, it sets all three above options simultaneously.
cvs.texi(,9885) @end table
cvs.texi(,9886) 
cvs.texi(,9887) In a line format, ordinary characters represent themselves;
cvs.texi(,9888) conversion specifications start with @samp{%} and have one of the
cvs.texi(,9889) following forms.
cvs.texi(,9890) 
cvs.texi(,9891) @table @samp
cvs.texi(,9892) @item %l
cvs.texi(,9893) stands for the contents of the line, not counting its trailing
cvs.texi(,9894) newline (if any).  This format ignores whether the line is incomplete.
cvs.texi(,9895) 
cvs.texi(,9896) @item %L
cvs.texi(,9897) stands for the contents of the line, including its trailing newline
cvs.texi(,9898) (if any).  If a line is incomplete, this format preserves its
cvs.texi(,9899) incompleteness.
cvs.texi(,9900) 
cvs.texi(,9901) @item %%
cvs.texi(,9902) stands for @samp{%}.
cvs.texi(,9903) 
cvs.texi(,9904) @item %c'@var{C}'
cvs.texi(,9905) where @var{C} is a single character, stands for @var{C}.
cvs.texi(,9906) @var{C} may not be a backslash or an apostrophe.
cvs.texi(,9907) For example, @samp{%c':'} stands for a colon.
cvs.texi(,9908) 
cvs.texi(,9909) @item %c'\@var{O}'
cvs.texi(,9910) where @var{O} is a string of 1, 2, or 3 octal digits,
cvs.texi(,9911) stands for the character with octal code @var{O}.
cvs.texi(,9912) For example, @samp{%c'\0'} stands for a null character.
cvs.texi(,9913) 
cvs.texi(,9914) @item @var{F}n
cvs.texi(,9915) where @var{F} is a @code{printf} conversion specification,
cvs.texi(,9916) stands for the line number formatted with @var{F}.
cvs.texi(,9917) For example, @samp{%.5dn} prints the line number using the
cvs.texi(,9918) @code{printf} format @code{"%.5d"}.  @xref{Line group formats}, for
cvs.texi(,9919) more about printf conversion specifications.
cvs.texi(,9920) 
cvs.texi(,9921) @end table
cvs.texi(,9922) 
cvs.texi(,9923) The default line format is @samp{%l} followed by a newline character.
cvs.texi(,9924) 
cvs.texi(,9925) If the input contains tab characters and it is important that they line
cvs.texi(,9926) up on output, you should ensure that @samp{%l} or @samp{%L} in a line
cvs.texi(,9927) format is just after a tab stop (e.g.@: by preceding @samp{%l} or
cvs.texi(,9928) @samp{%L} with a tab character), or you should use the @samp{-t} or
cvs.texi(,9929) @samp{--expand-tabs} option.
cvs.texi(,9930) 
cvs.texi(,9931) Taken together, the line and line group formats let you specify many
cvs.texi(,9932) different formats.  For example, the following command uses a format
cvs.texi(,9933) similar to @code{diff}'s normal format.  You can tailor this command
cvs.texi(,9934) to get fine control over @code{diff}'s output.
cvs.texi(,9935) 
cvs.texi(,9936) @example
cvs.texi(,9937) cvs diff \
cvs.texi(,9938)    --old-line-format='< %l
cvs.texi(,9939) ' \
cvs.texi(,9940)    --new-line-format='> %l
cvs.texi(,9941) ' \
cvs.texi(,9942)    --old-group-format='%df%(f=l?:,%dl)d%dE
cvs.texi(,9943) %<' \
cvs.texi(,9944)    --new-group-format='%dea%dF%(F=L?:,%dL)
cvs.texi(,9945) %>' \
cvs.texi(,9946)    --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL)
cvs.texi(,9947) %<---
cvs.texi(,9948) %>' \
cvs.texi(,9949)    --unchanged-group-format='' \
cvs.texi(,9950)    myfile
cvs.texi(,9951) @end example
cvs.texi(,9952) 
cvs.texi(,9953) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,9954) @node diff examples
cvs.texi(,9955) @appendixsubsec diff examples
cvs.texi(,9956) 
cvs.texi(,9957) The following line produces a Unidiff (@samp{-u} flag)
cvs.texi(,9958) between revision 1.14 and 1.19 of
cvs.texi(,9959) @file{backend.c}.  Due to the @samp{-kk} flag no
cvs.texi(,9960) keywords are substituted, so differences that only depend
cvs.texi(,9961) on keyword substitution are ignored.
cvs.texi(,9962) 
cvs.texi(,9963) @example
cvs.texi(,9964) $ cvs diff -kk -u -r 1.14 -r 1.19 backend.c
cvs.texi(,9965) @end example
cvs.texi(,9966) 
cvs.texi(,9967) Suppose the experimental branch EXPR1 was based on a
cvs.texi(,9968) set of files tagged RELEASE_1_0.  To see what has
cvs.texi(,9969) happened on that branch, the following can be used:
cvs.texi(,9970) 
cvs.texi(,9971) @example
cvs.texi(,9972) $ cvs diff -r RELEASE_1_0 -r EXPR1
cvs.texi(,9973) @end example
cvs.texi(,9974) 
cvs.texi(,9975) A command like this can be used to produce a context
cvs.texi(,9976) diff between two releases:
cvs.texi(,9977) 
cvs.texi(,9978) @example
cvs.texi(,9979) $ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs
cvs.texi(,9980) @end example
cvs.texi(,9981) 
cvs.texi(,9982) If you are maintaining ChangeLogs, a command like the following
cvs.texi(,9983) just before you commit your changes may help you write
cvs.texi(,9984) the ChangeLog entry.  All local modifications that have
cvs.texi(,9985) not yet been committed will be printed.
cvs.texi(,9986) 
cvs.texi(,9987) @example
cvs.texi(,9988) $ cvs diff -u | less
cvs.texi(,9989) @end example
cvs.texi(,9990) 
cvs.texi(,9991) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,9992) @node export
cvs.texi(,9993) @appendixsec export---Export sources from CVS, similar to checkout
cvs.texi(,9994) @cindex export (subcommand)
cvs.texi(,9995) 
cvs.texi(,9996) @itemize @bullet
cvs.texi(,9997) @item
cvs.texi(,9998) Synopsis: export [-flNnR] [-r rev|-D date] [-k subst] [-d dir] module@dots{}
cvs.texi(,9999) @item
cvs.texi(,10000) Requires: repository.
cvs.texi(,10001) @item
cvs.texi(,10002) Changes: current directory.
cvs.texi(,10003) @end itemize
cvs.texi(,10004) 
cvs.texi(,10005) This command is a variant of @code{checkout}; use it
cvs.texi(,10006) when you want a copy of the source for module without
cvs.texi(,10007) the @sc{cvs} administrative directories.  For example, you
cvs.texi(,10008) might use @code{export} to prepare source for shipment
cvs.texi(,10009) off-site.  This command requires that you specify a
cvs.texi(,10010) date or tag (with @samp{-D} or @samp{-r}), so that you
cvs.texi(,10011) can count on reproducing the source you ship to others
cvs.texi(,10012) (and thus it always prunes empty directories).
cvs.texi(,10013) 
cvs.texi(,10014) One often would like to use @samp{-kv} with @code{cvs
cvs.texi(,10015) export}.  This causes any keywords to be
cvs.texi(,10016) expanded such that an import done at some other site
cvs.texi(,10017) will not lose the keyword revision information.  But be
cvs.texi(,10018) aware that doesn't handle an export containing binary
cvs.texi(,10019) files correctly.  Also be aware that after having used
cvs.texi(,10020) @samp{-kv}, one can no longer use the @code{ident}
cvs.texi(,10021) command (which is part of the @sc{rcs} suite---see
cvs.texi(,10022) ident(1)) which looks for keyword strings.  If
cvs.texi(,10023) you want to be able to use @code{ident} you must not
cvs.texi(,10024) use @samp{-kv}.
cvs.texi(,10025) 
cvs.texi(,10026) @menu
cvs.texi(,10027) * export options::              export options
cvs.texi(,10028) @end menu
cvs.texi(,10029) 
cvs.texi(,10030) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,10031) @node export options
cvs.texi(,10032) @appendixsubsec export options
cvs.texi(,10033) 
cvs.texi(,10034) These standard options are supported by @code{export}
cvs.texi(,10035) (@pxref{Common options}, for a complete description of
cvs.texi(,10036) them):
cvs.texi(,10037) 
cvs.texi(,10038) @table @code
cvs.texi(,10039) @item -D @var{date}
cvs.texi(,10040) Use the most recent revision no later than @var{date}.
cvs.texi(,10041) 
cvs.texi(,10042) @item -f
cvs.texi(,10043) If no matching revision is found, retrieve the most
cvs.texi(,10044) recent revision (instead of ignoring the file).
cvs.texi(,10045) 
cvs.texi(,10046) @item -l
cvs.texi(,10047) Local; run only in current working directory.
cvs.texi(,10048) 
cvs.texi(,10049) @item -n
cvs.texi(,10050) Do not run any checkout program.
cvs.texi(,10051) 
cvs.texi(,10052) @item -R
cvs.texi(,10053) Export directories recursively.  This is on by default.
cvs.texi(,10054) 
cvs.texi(,10055) @item -r @var{tag}
cvs.texi(,10056) Use revision @var{tag}.
cvs.texi(,10057) @end table
cvs.texi(,10058) 
cvs.texi(,10059) In addition, these options (that are common to
cvs.texi(,10060) @code{checkout} and @code{export}) are also supported:
cvs.texi(,10061) 
cvs.texi(,10062) @table @code
cvs.texi(,10063) @item -d @var{dir}
cvs.texi(,10064) Create a directory called @var{dir} for the working
cvs.texi(,10065) files, instead of using the module name.
cvs.texi(,10066) @xref{checkout options}, for complete details on how
cvs.texi(,10067) @sc{cvs} handles this flag.
cvs.texi(,10068) 
cvs.texi(,10069) @item -k @var{subst}
cvs.texi(,10070) Set keyword expansion mode (@pxref{Substitution modes}).
cvs.texi(,10071) 
cvs.texi(,10072) @item -N
cvs.texi(,10073) Only useful together with @samp{-d @var{dir}}.
cvs.texi(,10074) @xref{checkout options}, for complete details on how
cvs.texi(,10075) @sc{cvs} handles this flag.
cvs.texi(,10076) @end table
cvs.texi(,10077) 
cvs.texi(,10086) 
cvs.texi(,10087) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,10088) @node history
cvs.texi(,10089) @appendixsec history---Show status of files and users
cvs.texi(,10090) @cindex history (subcommand)
cvs.texi(,10091) 
cvs.texi(,10092) @itemize @bullet
cvs.texi(,10093) @item
cvs.texi(,10094) Synopsis:     history [-report] [-flags] [-options args] [files@dots{}]
cvs.texi(,10095) @item
cvs.texi(,10096) Requires: the file @file{$CVSROOT/CVSROOT/history}
cvs.texi(,10097) @item
cvs.texi(,10098) Changes: nothing.
cvs.texi(,10099) @end itemize
cvs.texi(,10100) 
cvs.texi(,10101) @sc{cvs} can keep a history file that tracks each use of the
cvs.texi(,10102) @code{checkout}, @code{commit}, @code{rtag},
cvs.texi(,10103) @code{update}, and @code{release} commands.  You can
cvs.texi(,10104) use @code{history} to display this information in
cvs.texi(,10105) various formats.
cvs.texi(,10106) 
cvs.texi(,10107) Logging must be enabled by creating the file
cvs.texi(,10108) @file{$CVSROOT/CVSROOT/history}.
cvs.texi(,10109) 
cvs.texi(,10110) @strong{Note: @code{history} uses @samp{-f}, @samp{-l},
cvs.texi(,10111) @samp{-n}, and @samp{-p} in ways that conflict with the
cvs.texi(,10112) normal use inside @sc{cvs} (@pxref{Common options}).}
cvs.texi(,10113) 
cvs.texi(,10114) @menu
cvs.texi(,10115) * history options::             history options
cvs.texi(,10116) @end menu
cvs.texi(,10117) 
cvs.texi(,10118) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,10119) @node history options
cvs.texi(,10120) @appendixsubsec history options
cvs.texi(,10121) 
cvs.texi(,10122) Several options (shown above as @samp{-report})  control  what
cvs.texi(,10123) kind of report is generated:
cvs.texi(,10124) 
cvs.texi(,10125) @table @code
cvs.texi(,10126) @item -c
cvs.texi(,10127) Report on each time commit was used (i.e., each time
cvs.texi(,10128) the repository was modified).
cvs.texi(,10129) 
cvs.texi(,10130) @item -e
cvs.texi(,10131) Everything (all record types).  Equivalent to
cvs.texi(,10132) specifying @samp{-x} with all record types.  Of course,
cvs.texi(,10133) @samp{-e} will also include record types which are
cvs.texi(,10134) added in a future version of @sc{cvs}; if you are
cvs.texi(,10135) writing a script which can only handle certain record
cvs.texi(,10136) types, you'll want to specify @samp{-x}.
cvs.texi(,10137) 
cvs.texi(,10138) @item -m @var{module}
cvs.texi(,10139) Report on a particular module.  (You can meaningfully
cvs.texi(,10140) use @samp{-m} more than once on the command line.)
cvs.texi(,10141) 
cvs.texi(,10142) @item -o
cvs.texi(,10143) Report on checked-out modules.  This is the default report type.
cvs.texi(,10144) 
cvs.texi(,10145) @item -T
cvs.texi(,10146) Report on all tags.
cvs.texi(,10147) 
cvs.texi(,10148) @item -x @var{type}
cvs.texi(,10149) Extract a particular set of record types @var{type} from the @sc{cvs}
cvs.texi(,10150) history.  The types are indicated by single letters,
cvs.texi(,10151) which you may specify in combination.
cvs.texi(,10152) 
cvs.texi(,10153) Certain commands have a single record type:
cvs.texi(,10154) 
cvs.texi(,10155) @table @code
cvs.texi(,10156) @item F
cvs.texi(,10157) release
cvs.texi(,10158) @item O
cvs.texi(,10159) checkout
cvs.texi(,10160) @item E
cvs.texi(,10161) export
cvs.texi(,10162) @item T
cvs.texi(,10163) rtag
cvs.texi(,10164) @end table
cvs.texi(,10165) 
cvs.texi(,10166) @noindent
cvs.texi(,10167) One of four record types may result from an update:
cvs.texi(,10168) 
cvs.texi(,10169) @table @code
cvs.texi(,10170) @item C
cvs.texi(,10171) A merge was necessary but collisions were
cvs.texi(,10172) detected (requiring manual merging).
cvs.texi(,10173) @item G
cvs.texi(,10174) A merge was necessary and it succeeded.
cvs.texi(,10175) @item U
cvs.texi(,10176) A working file was copied from the repository.
cvs.texi(,10177) @item W
cvs.texi(,10178) The working copy of a file was deleted during
cvs.texi(,10179) update (because it was gone from the repository).
cvs.texi(,10180) @end table
cvs.texi(,10181) 
cvs.texi(,10182) @noindent
cvs.texi(,10183) One of three record types results from commit:
cvs.texi(,10184) 
cvs.texi(,10185) @table @code
cvs.texi(,10186) @item A
cvs.texi(,10187) A file was added for the first time.
cvs.texi(,10188) @item M
cvs.texi(,10189) A file was modified.
cvs.texi(,10190) @item R
cvs.texi(,10191) A file was removed.
cvs.texi(,10192) @end table
cvs.texi(,10193) @end table
cvs.texi(,10194) 
cvs.texi(,10195) The options shown as @samp{-flags} constrain or expand
cvs.texi(,10196) the report without requiring option arguments:
cvs.texi(,10197) 
cvs.texi(,10198) @table @code
cvs.texi(,10199) @item -a
cvs.texi(,10200) Show data for all users (the default is to show data
cvs.texi(,10201) only for the user executing @code{history}).
cvs.texi(,10202) 
cvs.texi(,10203) @item -l
cvs.texi(,10204) Show last modification only.
cvs.texi(,10205) 
cvs.texi(,10206) @item -w
cvs.texi(,10207) Show only the records for modifications done from the
cvs.texi(,10208) same working directory where @code{history} is
cvs.texi(,10209) executing.
cvs.texi(,10210) @end table
cvs.texi(,10211) 
cvs.texi(,10212) The options shown as @samp{-options @var{args}} constrain the report
cvs.texi(,10213) based on an argument:
cvs.texi(,10214) 
cvs.texi(,10215) @table @code
cvs.texi(,10216) @item -b @var{str}
cvs.texi(,10217) Show data back to a record containing  the  string
cvs.texi(,10218) @var{str}  in  either the module name, the file name, or
cvs.texi(,10219) the repository path.
cvs.texi(,10220) 
cvs.texi(,10221) @item -D @var{date}
cvs.texi(,10222) Show data since @var{date}.  This is slightly different
cvs.texi(,10223) from the normal use of @samp{-D @var{date}}, which
cvs.texi(,10224) selects the newest revision older than @var{date}.
cvs.texi(,10225) 
cvs.texi(,10226) @item -f @var{file}
cvs.texi(,10227) Show data for a particular file
cvs.texi(,10228) (you can specify several @samp{-f} options on the same command line).
cvs.texi(,10229) This is equivalent to specifying the file on the command line.
cvs.texi(,10230) 
cvs.texi(,10231) @item -n @var{module}
cvs.texi(,10232) Show data for a particular module
cvs.texi(,10233) (you can specify several @samp{-n} options on the same command line).
cvs.texi(,10234) 
cvs.texi(,10235) @item -p @var{repository}
cvs.texi(,10236) Show data for a particular source repository  (you
cvs.texi(,10237) can specify several @samp{-p} options on the same command
cvs.texi(,10238) line).
cvs.texi(,10239) 
cvs.texi(,10240) @item -r @var{rev}
cvs.texi(,10241) Show records referring to revisions since the revision
cvs.texi(,10242) or tag named @var{rev} appears in individual @sc{rcs}
cvs.texi(,10243) files.  Each @sc{rcs} file is searched for the revision or
cvs.texi(,10244) tag.
cvs.texi(,10245) 
cvs.texi(,10246) @item -t @var{tag}
cvs.texi(,10247) Show records since tag @var{tag} was last added to the
cvs.texi(,10248) history file.  This differs from the @samp{-r} flag
cvs.texi(,10249) above in that it reads only the history file, not the
cvs.texi(,10250) @sc{rcs} files, and is much faster.
cvs.texi(,10251) 
cvs.texi(,10252) @item -u @var{name}
cvs.texi(,10253) Show records for user @var{name}.
cvs.texi(,10254) 
cvs.texi(,10255) @item -z @var{timezone}
cvs.texi(,10256) Show times in the selected records using the specified
cvs.texi(,10257) time zone instead of UTC.
cvs.texi(,10258) @end table
cvs.texi(,10259) 
cvs.texi(,10268) 
cvs.texi(,10269) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,10270) @node import
cvs.texi(,10271) @appendixsec import---Import sources into CVS, using vendor branches
cvs.texi(,10272) @cindex import (subcommand)
cvs.texi(,10273) 
cvs.texi(,10274) @c FIXME: This node is way too long for one which has subnodes.
cvs.texi(,10275) 
cvs.texi(,10276) @itemize @bullet
cvs.texi(,10277) @item
cvs.texi(,10278) Synopsis: import [-options] repository vendortag releasetag@dots{}
cvs.texi(,10279) @item
cvs.texi(,10280) Requires: Repository, source distribution directory.
cvs.texi(,10281) @item
cvs.texi(,10282) Changes: repository.
cvs.texi(,10283) @end itemize
cvs.texi(,10284) 
cvs.texi(,10285) Use @code{import} to incorporate an entire source
cvs.texi(,10286) distribution from an outside source (e.g., a source
cvs.texi(,10287) vendor) into your source repository directory.  You can
cvs.texi(,10288) use this command both for initial creation of a
cvs.texi(,10289) repository, and for wholesale updates to the module
cvs.texi(,10290) from the outside source.  @xref{Tracking sources}, for
cvs.texi(,10291) a discussion on this subject.
cvs.texi(,10292) 
cvs.texi(,10293) The @var{repository} argument gives a directory name
cvs.texi(,10294) (or a path to a directory) under the @sc{cvs} root directory
cvs.texi(,10295) for repositories; if the directory did not exist,
cvs.texi(,10296) import creates it.
cvs.texi(,10297) 
cvs.texi(,10298) When you use import for updates to source that has been
cvs.texi(,10299) modified in your source repository (since a prior
cvs.texi(,10300) import), it will notify you of any files that conflict
cvs.texi(,10301) in the two branches of development; use @samp{checkout
cvs.texi(,10302) -j} to reconcile the differences, as import instructs
cvs.texi(,10303) you to do.
cvs.texi(,10304) 
cvs.texi(,10305) If @sc{cvs} decides a file should be ignored
cvs.texi(,10306) (@pxref{cvsignore}), it does not import it and prints
cvs.texi(,10307) @samp{I } followed by the filename (@pxref{import output}, for a
cvs.texi(,10308) complete description of the output).
cvs.texi(,10309) 
cvs.texi(,10310) If the file @file{$CVSROOT/CVSROOT/cvswrappers} exists,
cvs.texi(,10311) any file whose names match the specifications in that
cvs.texi(,10312) file will be treated as packages and the appropriate
cvs.texi(,10313) filtering will be performed on the file/directory
cvs.texi(,10314) before being imported.  @xref{Wrappers}.
cvs.texi(,10315) 
cvs.texi(,10316) The outside source is saved in a first-level
cvs.texi(,10317) branch, by default 1.1.1.  Updates are leaves of this
cvs.texi(,10318) branch; for example, files from the first imported
cvs.texi(,10319) collection of source will be revision 1.1.1.1, then
cvs.texi(,10320) files from the first imported update will be revision
cvs.texi(,10321) 1.1.1.2, and so on.
cvs.texi(,10322) 
cvs.texi(,10323) At least three arguments are required.
cvs.texi(,10324) @var{repository} is needed to identify the collection
cvs.texi(,10325) of source.  @var{vendortag} is a tag for the entire
cvs.texi(,10326) branch (e.g., for 1.1.1).  You must also specify at
cvs.texi(,10327) least one @var{releasetag} to identify the files at
cvs.texi(,10328) the leaves created each time you execute @code{import}.
cvs.texi(,10329) 
cvs.texi(,10330) @c I'm not completely sure this belongs here.  But
cvs.texi(,10331) @c we need to say it _somewhere_ reasonably obvious; it
cvs.texi(,10332) @c is a common misconception among people first learning CVS
cvs.texi(,10333) Note that @code{import} does @emph{not} change the
cvs.texi(,10334) directory in which you invoke it.  In particular, it
cvs.texi(,10335) does not set up that directory as a @sc{cvs} working
cvs.texi(,10336) directory; if you want to work with the sources import
cvs.texi(,10337) them first and then check them out into a different
cvs.texi(,10338) directory (@pxref{Getting the source}).
cvs.texi(,10339) 
cvs.texi(,10340) @menu
cvs.texi(,10341) * import options::              import options
cvs.texi(,10342) * import output::               import output
cvs.texi(,10343) * import examples::             import examples
cvs.texi(,10344) @end menu
cvs.texi(,10345) 
cvs.texi(,10346) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,10347) @node import options
cvs.texi(,10348) @appendixsubsec import options
cvs.texi(,10349) 
cvs.texi(,10350) This standard option is supported by @code{import}
cvs.texi(,10351) (@pxref{Common options}, for a complete description):
cvs.texi(,10352) 
cvs.texi(,10353) @table @code
cvs.texi(,10354) @item -m @var{message}
cvs.texi(,10355) Use @var{message} as log information, instead of
cvs.texi(,10356) invoking an editor.
cvs.texi(,10357) @end table
cvs.texi(,10358) 
cvs.texi(,10359) There are the following additional special options.
cvs.texi(,10360) 
cvs.texi(,10361) @table @code
cvs.texi(,10362) @item -b @var{branch}
cvs.texi(,10363) See @ref{Multiple vendor branches}.
cvs.texi(,10364) 
cvs.texi(,10365) @item -k @var{subst}
cvs.texi(,10366) Indicate the keyword expansion mode desired.  This
cvs.texi(,10367) setting will apply to all files created during the
cvs.texi(,10368) import, but not to any files that previously existed in
cvs.texi(,10369) the repository.  See @ref{Substitution modes}, for a
cvs.texi(,10370) list of valid @samp{-k} settings.
cvs.texi(,10371) 
cvs.texi(,10372) @item -I @var{name}
cvs.texi(,10373) Specify file names that should be ignored during
cvs.texi(,10374) import.  You can use this option repeatedly.  To avoid
cvs.texi(,10375) ignoring any files at all (even those ignored by
cvs.texi(,10376) default), specify `-I !'.
cvs.texi(,10377) 
cvs.texi(,10378) @var{name} can be a file name pattern of the same type
cvs.texi(,10379) that you can specify in the @file{.cvsignore} file.
cvs.texi(,10380) @xref{cvsignore}.
cvs.texi(,10381) @c -- Is this really true?
cvs.texi(,10382) 
cvs.texi(,10383) @item -W @var{spec}
cvs.texi(,10384) Specify file names that should be filtered during
cvs.texi(,10385) import.  You can use this option repeatedly.
cvs.texi(,10386) 
cvs.texi(,10387) @var{spec} can be a file name pattern of the same type
cvs.texi(,10388) that you can specify in the @file{.cvswrappers}
cvs.texi(,10389) file. @xref{Wrappers}.
cvs.texi(,10390) @end table
cvs.texi(,10391) 
cvs.texi(,10392) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,10393) @node import output
cvs.texi(,10394) @appendixsubsec import output
cvs.texi(,10395) 
cvs.texi(,10396) @code{import} keeps you informed of its progress by printing a line
cvs.texi(,10397) for each file, preceded by one character indicating the status of the file:
cvs.texi(,10398) 
cvs.texi(,10399) @table @code
cvs.texi(,10400) @item U @var{file}
cvs.texi(,10401) The file already exists in the repository and has not been locally
cvs.texi(,10402) modified; a new revision has been created (if necessary).
cvs.texi(,10403) 
cvs.texi(,10404) @item N @var{file}
cvs.texi(,10405) The file is a new file which has been added to the repository.
cvs.texi(,10406) 
cvs.texi(,10407) @item C @var{file}
cvs.texi(,10408) The file already exists in the repository but has been locally modified;
cvs.texi(,10409) you will have to merge the changes.
cvs.texi(,10410) 
cvs.texi(,10411) @item I @var{file}
cvs.texi(,10412) The file is being ignored (@pxref{cvsignore}).
cvs.texi(,10413) 
cvs.texi(,10414) @cindex Symbolic link, importing
cvs.texi(,10415) @cindex Link, symbolic, importing
cvs.texi(,10416) @c FIXME: also (somewhere else) probably
cvs.texi(,10417) @c should be documenting what happens if you "cvs add"
cvs.texi(,10418) @c a symbolic link.  Also maybe what happens if
cvs.texi(,10419) @c you manually create symbolic links within the
cvs.texi(,10420) @c repository (? - not sure why we'd want to suggest
cvs.texi(,10421) @c doing that).
cvs.texi(,10422) @item L @var{file}
cvs.texi(,10423) The file is a symbolic link; @code{cvs import} ignores symbolic links.
cvs.texi(,10424) People periodically suggest that this behavior should
cvs.texi(,10425) be changed, but if there is a consensus on what it
cvs.texi(,10426) should be changed to, it is not apparent.
cvs.texi(,10427) (Various options in the @file{modules} file can be used
cvs.texi(,10428) to recreate symbolic links on checkout, update, etc.;
cvs.texi(,10429) @pxref{modules}.)
cvs.texi(,10430) @end table
cvs.texi(,10431) 
cvs.texi(,10432) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,10433) @node import examples
cvs.texi(,10434) @appendixsubsec import examples
cvs.texi(,10435) 
cvs.texi(,10436) See @ref{Tracking sources}, and @ref{From files}.
cvs.texi(,10437) 
cvs.texi(,10438) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,10439) @node log
cvs.texi(,10440) @appendixsec log---Print out log information for files
cvs.texi(,10441) @cindex log (subcommand)
cvs.texi(,10442) 
cvs.texi(,10443) @itemize @bullet
cvs.texi(,10444) @item
cvs.texi(,10445) Synopsis: log [options] [files@dots{}]
cvs.texi(,10446) @item
cvs.texi(,10447) Requires: repository, working directory.
cvs.texi(,10448) @item
cvs.texi(,10449) Changes: nothing.
cvs.texi(,10450) @end itemize
cvs.texi(,10451) 
cvs.texi(,10452) Display log information for files.  @code{log} used to
cvs.texi(,10453) call the @sc{rcs} utility @code{rlog}.  Although this
cvs.texi(,10454) is no longer true in the current sources, this history
cvs.texi(,10455) determines the format of the output and the options,
cvs.texi(,10456) which are not quite in the style of the other @sc{cvs}
cvs.texi(,10457) commands.
cvs.texi(,10458) 
cvs.texi(,10459) @cindex Timezone, in output
cvs.texi(,10460) @cindex Zone, time, in output
cvs.texi(,10461) @c Kind of a funny place to document the timezone used
cvs.texi(,10462) @c in output from commands other than @code{log}.
cvs.texi(,10463) @c There is also more we need to say about this,
cvs.texi(,10464) @c including what happens in a client/server environment.
cvs.texi(,10465) The output includes the location of the @sc{rcs} file,
cvs.texi(,10466) the @dfn{head} revision (the latest revision on the
cvs.texi(,10467) trunk), all symbolic names (tags) and some other
cvs.texi(,10468) things.  For each revision, the revision number, the
cvs.texi(,10469) author, the number of lines added/deleted and the log
cvs.texi(,10470) message are printed.  All times are displayed in
cvs.texi(,10471) Coordinated Universal Time (UTC).  (Other parts of
cvs.texi(,10472) @sc{cvs} print times in the local timezone).
cvs.texi(,10473) @c FIXCVS: need a better way to control the timezone
cvs.texi(,10474) @c used in output.  Previous/current versions of CVS did/do
cvs.texi(,10475) @c sometimes support -z in RCSINIT, and/or an
cvs.texi(,10476) @c undocumented (except by reference to 'rlog') -z option
cvs.texi(,10477) @c to cvs log, but this has not been a consistent,
cvs.texi(,10478) @c documented feature.  Perhaps a new global option,
cvs.texi(,10479) @c where LT means the client's timezone, which the
cvs.texi(,10480) @c client then communicates to the server, is the
cvs.texi(,10481) @c right solution.
cvs.texi(,10482) 
cvs.texi(,10483) @strong{Note: @code{log} uses @samp{-R} in a way that conflicts
cvs.texi(,10484) with the normal use inside @sc{cvs} (@pxref{Common options}).}
cvs.texi(,10485) 
cvs.texi(,10486) @menu
cvs.texi(,10487) * log options::                 log options
cvs.texi(,10488) * log examples::                log examples
cvs.texi(,10489) @end menu
cvs.texi(,10490) 
cvs.texi(,10491) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,10492) @node log options
cvs.texi(,10493) @appendixsubsec log options
cvs.texi(,10494) 
cvs.texi(,10495) By default, @code{log} prints all information that is
cvs.texi(,10496) available.  All other options restrict the output.
cvs.texi(,10497) 
cvs.texi(,10498) @table @code
cvs.texi(,10499) @item -b
cvs.texi(,10500) Print information about the revisions on the default
cvs.texi(,10501) branch, normally the highest branch on the trunk.
cvs.texi(,10502) 
cvs.texi(,10503) @item -d @var{dates}
cvs.texi(,10504) Print information about revisions with a checkin
cvs.texi(,10505) date/time in the range given by the
cvs.texi(,10506) semicolon-separated list of dates.  The date formats
cvs.texi(,10507) accepted are those accepted by the @samp{-D} option to
cvs.texi(,10508) many other @sc{cvs} commands (@pxref{Common options}).
cvs.texi(,10509) Dates can be combined into ranges as follows:
cvs.texi(,10510) 
cvs.texi(,10511) @c Should we be thinking about accepting ISO8601
cvs.texi(,10512) @c ranges?  For example "1972-09-10/1972-09-12".
cvs.texi(,10513) @table @code
cvs.texi(,10514) @item @var{d1}<@var{d2}
cvs.texi(,10515) @itemx @var{d2}>@var{d1}
cvs.texi(,10516) Select the revisions that were deposited between
cvs.texi(,10517) @var{d1} and @var{d2}.
cvs.texi(,10518) 
cvs.texi(,10519) @item <@var{d}
cvs.texi(,10520) @itemx @var{d}>
cvs.texi(,10521) Select all revisions dated @var{d} or earlier.
cvs.texi(,10522) 
cvs.texi(,10523) @item @var{d}<
cvs.texi(,10524) @itemx >@var{d}
cvs.texi(,10525) Select all revisions dated @var{d} or later.
cvs.texi(,10526) 
cvs.texi(,10527) @item @var{d}
cvs.texi(,10528) Select the single, latest revision dated @var{d} or
cvs.texi(,10529) earlier.
cvs.texi(,10530) @end table
cvs.texi(,10531) 
cvs.texi(,10532) The @samp{>} or @samp{<} characters may be followed by
cvs.texi(,10533) @samp{=} to indicate an inclusive range rather than an
cvs.texi(,10534) exclusive one.
cvs.texi(,10535) 
cvs.texi(,10536) Note that the separator is a semicolon (;).
cvs.texi(,10537) 
cvs.texi(,10538) @item -h
cvs.texi(,10539) Print only the name of the @sc{rcs} file, name
cvs.texi(,10540) of the file in the working directory, head,
cvs.texi(,10541) default branch, access list, locks, symbolic names, and
cvs.texi(,10542) suffix.
cvs.texi(,10543) 
cvs.texi(,10544) @item -l
cvs.texi(,10545) Local; run only in current working directory.  (Default
cvs.texi(,10546) is to run recursively).
cvs.texi(,10547) 
cvs.texi(,10548) @item -N
cvs.texi(,10549) Do not print the list of tags for this file.  This
cvs.texi(,10550) option can be very useful when your site uses a lot of
cvs.texi(,10551) tags, so rather than "more"'ing over 3 pages of tag
cvs.texi(,10552) information, the log information is presented without
cvs.texi(,10553) tags at all.
cvs.texi(,10554) 
cvs.texi(,10555) @item -R
cvs.texi(,10556) Print only the name of the @sc{rcs} file.
cvs.texi(,10557) 
cvs.texi(,10558) @c Note that using a bare revision (in addition to not
cvs.texi(,10559) @c being explicitly documented here) is potentially
cvs.texi(,10560) @c confusing; it shows the log message to get from the
cvs.texi(,10561) @c previous revision to that revision.  "-r1.3 -r1.6"
cvs.texi(,10562) @c (equivalent to "-r1.3,1.6") is even worse; it
cvs.texi(,10563) @c prints the messages to get from 1.2 to 1.3 and 1.5
cvs.texi(,10564) @c to 1.6.  By analogy with "cvs diff", users might
cvs.texi(,10565) @c expect that it is more like specifying a range.
cvs.texi(,10566) @c It is not 100% clear to me how much of this should
cvs.texi(,10567) @c be documented (for example, multiple -r options
cvs.texi(,10568) @c perhaps could/should be deprecated given the false
cvs.texi(,10569) @c analogy with "cvs diff").
cvs.texi(,10570) @c In general, this section should be rewritten to talk
cvs.texi(,10571) @c about messages to get from revision rev1 to rev2,
cvs.texi(,10572) @c rather than messages for revision rev2 (that is, the
cvs.texi(,10573) @c messages are associated with a change not a static
cvs.texi(,10574) @c revision and failing to make this distinction causes
cvs.texi(,10575) @c much confusion).
cvs.texi(,10576) @item -r@var{revisions}
cvs.texi(,10577) Print information about revisions given in the
cvs.texi(,10578) comma-separated list @var{revisions} of revisions and
cvs.texi(,10579) ranges.  The following table explains the available
cvs.texi(,10580) range formats:
cvs.texi(,10581) 
cvs.texi(,10582) @table @code
cvs.texi(,10583) @item @var{rev1}:@var{rev2}
cvs.texi(,10584) Revisions @var{rev1} to @var{rev2} (which must be on
cvs.texi(,10585) the same branch).
cvs.texi(,10586) 
cvs.texi(,10587) @item @var{rev1}::@var{rev2}
cvs.texi(,10588) The same, but excluding @var{rev1}.
cvs.texi(,10589) 
cvs.texi(,10590) @item :@var{rev}
cvs.texi(,10591) @itemx ::@var{rev}
cvs.texi(,10592) Revisions from the beginning of the branch up to
cvs.texi(,10593) and including @var{rev}.
cvs.texi(,10594) 
cvs.texi(,10595) @item @var{rev}:
cvs.texi(,10596) Revisions starting with @var{rev} to the end of the
cvs.texi(,10597) branch containing @var{rev}.
cvs.texi(,10598) 
cvs.texi(,10599) @item @var{rev}::
cvs.texi(,10600) Revisions starting just after @var{rev} to the end of the
cvs.texi(,10601) branch containing @var{rev}.
cvs.texi(,10602) 
cvs.texi(,10603) @item @var{branch}
cvs.texi(,10604) An argument that is a branch means all revisions on
cvs.texi(,10605) that branch.
cvs.texi(,10606) 
cvs.texi(,10607) @item @var{branch1}:@var{branch2}
cvs.texi(,10608) @itemx @var{branch1}::@var{branch2}
cvs.texi(,10609) A range of branches means all revisions
cvs.texi(,10610) on the branches in that range.
cvs.texi(,10611) 
cvs.texi(,10612) @item @var{branch}.
cvs.texi(,10613) The latest revision in @var{branch}.
cvs.texi(,10614) @end table
cvs.texi(,10615) 
cvs.texi(,10616) A bare @samp{-r} with no revisions means the latest
cvs.texi(,10617) revision on the default branch, normally the trunk.
cvs.texi(,10618) There can be no space between the @samp{-r} option and
cvs.texi(,10619) its argument.
cvs.texi(,10620) 
cvs.texi(,10621) @item -S
cvs.texi(,10622) Suppress the header if no revisions are selected.
cvs.texi(,10623) 
cvs.texi(,10624) @item -s @var{states}
cvs.texi(,10625) Print information about revisions whose state
cvs.texi(,10626) attributes match one of the states given in the
cvs.texi(,10627) comma-separated list @var{states}.
cvs.texi(,10628) 
cvs.texi(,10629) @item -t
cvs.texi(,10630) Print the same as @samp{-h}, plus the descriptive text.
cvs.texi(,10631) 
cvs.texi(,10632) @item -w@var{logins}
cvs.texi(,10633) Print information about revisions checked in by users
cvs.texi(,10634) with login names appearing in the comma-separated list
cvs.texi(,10635) @var{logins}.  If @var{logins} is omitted, the user's
cvs.texi(,10636) login is assumed.  There can be no space between the
cvs.texi(,10637) @samp{-w} option and its argument.
cvs.texi(,10638) @end table
cvs.texi(,10639) 
cvs.texi(,10640) @code{log} prints the intersection of the revisions
cvs.texi(,10641) selected with the options @samp{-d}, @samp{-s}, and
cvs.texi(,10642) @samp{-w}, intersected with the union of the revisions
cvs.texi(,10643) selected by @samp{-b} and @samp{-r}.
cvs.texi(,10644) 
cvs.texi(,10645) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,10646) @node log examples
cvs.texi(,10647) @appendixsubsec log examples
cvs.texi(,10648) 
cvs.texi(,10649) Contributed examples are gratefully accepted.
cvs.texi(,10650) 
cvs.texi(,10651) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,10652) @node rdiff
cvs.texi(,10653) @appendixsec rdiff---'patch' format diffs between releases
cvs.texi(,10654) @cindex rdiff (subcommand)
cvs.texi(,10655) 
cvs.texi(,10656) @itemize @bullet
cvs.texi(,10657) @item
cvs.texi(,10658) rdiff [-flags] [-V vn] [-r t|-D d [-r t2|-D d2]] modules@dots{}
cvs.texi(,10659) @item
cvs.texi(,10660) Requires: repository.
cvs.texi(,10661) @item
cvs.texi(,10662) Changes: nothing.
cvs.texi(,10663) @item
cvs.texi(,10664) Synonym: patch
cvs.texi(,10665) @end itemize
cvs.texi(,10666) 
cvs.texi(,10667) Builds a Larry Wall format patch(1) file between two
cvs.texi(,10668) releases, that can be fed directly into the @code{patch}
cvs.texi(,10669) program to bring an old release up-to-date with the new
cvs.texi(,10670) release.  (This is one of the few @sc{cvs} commands that
cvs.texi(,10671) operates directly from the repository, and doesn't
cvs.texi(,10672) require a prior checkout.) The diff output is sent to
cvs.texi(,10673) the standard output device.
cvs.texi(,10674) 
cvs.texi(,10675) You can specify (using the standard @samp{-r} and
cvs.texi(,10676) @samp{-D} options) any combination of one or two
cvs.texi(,10677) revisions or dates.  If only one revision or date is
cvs.texi(,10678) specified, the patch file reflects differences between
cvs.texi(,10679) that revision or date and the current head revisions in
cvs.texi(,10680) the @sc{rcs} file.
cvs.texi(,10681) 
cvs.texi(,10682) Note that if the software release affected is contained
cvs.texi(,10683) in more than one directory, then it may be necessary to
cvs.texi(,10684) specify the @samp{-p} option to the @code{patch} command when
cvs.texi(,10685) patching the old sources, so that @code{patch} is able to find
cvs.texi(,10686) the files that are located in other directories.
cvs.texi(,10687) 
cvs.texi(,10688) @menu
cvs.texi(,10689) * rdiff options::               rdiff options
cvs.texi(,10690) * rdiff examples::              rdiff examples
cvs.texi(,10691) @end menu
cvs.texi(,10692) 
cvs.texi(,10693) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,10694) @node rdiff options
cvs.texi(,10695) @appendixsubsec rdiff options
cvs.texi(,10696) 
cvs.texi(,10697) These standard options are supported by @code{rdiff}
cvs.texi(,10698) (@pxref{Common options}, for a complete description of
cvs.texi(,10699) them):
cvs.texi(,10700) 
cvs.texi(,10701) @table @code
cvs.texi(,10702) @item -D @var{date}
cvs.texi(,10703) Use the most recent revision no later than @var{date}.
cvs.texi(,10704) 
cvs.texi(,10705) @item -f
cvs.texi(,10706) If no matching revision is found, retrieve the most
cvs.texi(,10707) recent revision (instead of ignoring the file).
cvs.texi(,10708) 
cvs.texi(,10709) @item -l
cvs.texi(,10710) Local; don't descend subdirectories.
cvs.texi(,10711) 
cvs.texi(,10712) @item -R
cvs.texi(,10713) Examine directories recursively.  This option is on by default.
cvs.texi(,10714) 
cvs.texi(,10715) @item -r @var{tag}
cvs.texi(,10716) Use revision @var{tag}.
cvs.texi(,10717) @end table
cvs.texi(,10718) 
cvs.texi(,10719) In addition to the above, these options are available:
cvs.texi(,10720) 
cvs.texi(,10721) @table @code
cvs.texi(,10722) @item -c
cvs.texi(,10723) Use the context diff format.  This is the default format.
cvs.texi(,10724) 
cvs.texi(,10725) @item -s
cvs.texi(,10726) Create a summary change report instead of a patch.  The
cvs.texi(,10727) summary includes information about files that were
cvs.texi(,10728) changed or added between the releases.  It is sent to
cvs.texi(,10729) the standard output device.  This is useful for finding
cvs.texi(,10730) out, for example, which files have changed between two
cvs.texi(,10731) dates or revisions.
cvs.texi(,10732) 
cvs.texi(,10733) @item -t
cvs.texi(,10734) A diff of the top two revisions is sent to the standard
cvs.texi(,10735) output device.  This is most useful for seeing what the
cvs.texi(,10736) last change to a file was.
cvs.texi(,10737) 
cvs.texi(,10738) @item -u
cvs.texi(,10739) Use the unidiff format for the context diffs.
cvs.texi(,10740) Remember that old versions
cvs.texi(,10741) of the @code{patch} program can't handle the unidiff
cvs.texi(,10742) format, so if you plan to post this patch to the net
cvs.texi(,10743) you should probably not use @samp{-u}.
cvs.texi(,10744) 
cvs.texi(,10745) @item -V @var{vn}
cvs.texi(,10746) Expand keywords according to the rules current in
cvs.texi(,10747) @sc{rcs} version @var{vn} (the expansion format changed with
cvs.texi(,10748) @sc{rcs} version 5).  Note that this option is no
cvs.texi(,10749) longer accepted.  @sc{cvs} will always expand keywords the
cvs.texi(,10750) way that @sc{rcs} version 5 does.
cvs.texi(,10751) @end table
cvs.texi(,10752) 
cvs.texi(,10753) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,10754) @node rdiff examples
cvs.texi(,10755) @appendixsubsec rdiff examples
cvs.texi(,10756) 
cvs.texi(,10757) Suppose you receive mail from @t{foo@@example.net} asking for an
cvs.texi(,10758) update from release 1.2 to 1.4 of the tc compiler.  You
cvs.texi(,10759) have no such patches on hand, but with @sc{cvs} that can
cvs.texi(,10760) easily be fixed with a command such as this:
cvs.texi(,10761) 
cvs.texi(,10762) @example
cvs.texi(,10763) $ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \
cvs.texi(,10764) $$ Mail -s 'The patches you asked for' foo@@example.net
cvs.texi(,10765) @end example
cvs.texi(,10766) 
cvs.texi(,10767) Suppose you have made release 1.3, and forked a branch
cvs.texi(,10768) called @samp{R_1_3fix} for bugfixes.  @samp{R_1_3_1}
cvs.texi(,10769) corresponds to release 1.3.1, which was made some time
cvs.texi(,10770) ago.  Now, you want to see how much development has been
cvs.texi(,10771) done on the branch.  This command can be used:
cvs.texi(,10772) 
cvs.texi(,10773) @example
cvs.texi(,10774) $ cvs patch -s -r R_1_3_1 -r R_1_3fix module-name
cvs.texi(,10775) cvs rdiff: Diffing module-name
cvs.texi(,10776) File ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6
cvs.texi(,10777) File foo.c,v changed from revision 1.52.2.3 to 1.52.2.4
cvs.texi(,10778) File bar.h,v changed from revision 1.29.2.1 to 1.2
cvs.texi(,10779) @end example
cvs.texi(,10780) 
cvs.texi(,10781) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,10782) @node release
cvs.texi(,10783) @appendixsec release---Indicate that a Module is no longer in use
cvs.texi(,10784) @cindex release (subcommand)
cvs.texi(,10785) 
cvs.texi(,10786) @itemize @bullet
cvs.texi(,10787) @item
cvs.texi(,10788) release [-d] directories@dots{}
cvs.texi(,10789) @item
cvs.texi(,10790) Requires: Working directory.
cvs.texi(,10791) @item
cvs.texi(,10792) Changes: Working directory, history log.
cvs.texi(,10793) @end itemize
cvs.texi(,10794) 
cvs.texi(,10795) This command is meant to safely cancel the effect of
cvs.texi(,10796) @samp{cvs checkout}.  Since @sc{cvs} doesn't lock files, it
cvs.texi(,10797) isn't strictly necessary to use this command.  You can
cvs.texi(,10798) always simply delete your working directory, if you
cvs.texi(,10799) like; but you risk losing changes you may have
cvs.texi(,10800) forgotten, and you leave no trace in the @sc{cvs} history
cvs.texi(,10801) file (@pxref{history file}) that you've abandoned your
cvs.texi(,10802) checkout.
cvs.texi(,10803) 
cvs.texi(,10804) Use @samp{cvs release} to avoid these problems.  This
cvs.texi(,10805) command checks that no uncommitted changes are
cvs.texi(,10806) present; that you are executing it from immediately
cvs.texi(,10807) above a @sc{cvs} working directory; and that the repository
cvs.texi(,10808) recorded for your files is the same as the repository
cvs.texi(,10809) defined in the module database.
cvs.texi(,10810) 
cvs.texi(,10811) If all these conditions are true, @samp{cvs release}
cvs.texi(,10812) leaves a record of its execution (attesting to your
cvs.texi(,10813) intentionally abandoning your checkout) in the @sc{cvs}
cvs.texi(,10814) history log.
cvs.texi(,10815) 
cvs.texi(,10816) @menu
cvs.texi(,10817) * release options::             release options
cvs.texi(,10818) * release output::              release output
cvs.texi(,10819) * release examples::            release examples
cvs.texi(,10820) @end menu
cvs.texi(,10821) 
cvs.texi(,10822) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,10823) @node release options
cvs.texi(,10824) @appendixsubsec release options
cvs.texi(,10825) 
cvs.texi(,10826) The @code{release} command supports one command option:
cvs.texi(,10827) 
cvs.texi(,10828) @table @code
cvs.texi(,10829) @item -d
cvs.texi(,10830) Delete your working copy of the file if the release
cvs.texi(,10831) succeeds.  If this flag is not given your files will
cvs.texi(,10832) remain in your working directory.
cvs.texi(,10833) 
cvs.texi(,10834) @strong{WARNING:  The @code{release} command deletes
cvs.texi(,10835) all directories and files recursively.  This
cvs.texi(,10836) has the very serious side-effect that any directory
cvs.texi(,10837) that you have created inside your checked-out sources,
cvs.texi(,10838) and not added to the repository (using the @code{add}
cvs.texi(,10839) command; @pxref{Adding files}) will be silently deleted---even
cvs.texi(,10840) if it is non-empty!}
cvs.texi(,10841) @end table
cvs.texi(,10842) 
cvs.texi(,10843) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,10844) @node release output
cvs.texi(,10845) @appendixsubsec release output
cvs.texi(,10846) 
cvs.texi(,10847) Before @code{release} releases your sources it will
cvs.texi(,10848) print a one-line message for any file that is not
cvs.texi(,10849) up-to-date.
cvs.texi(,10850) 
cvs.texi(,10851) @table @code
cvs.texi(,10852) @item U @var{file}
cvs.texi(,10853) @itemx P @var{file}
cvs.texi(,10854) There exists a newer revision of this file in the
cvs.texi(,10855) repository, and you have not modified your local copy
cvs.texi(,10856) of the file (@samp{U} and @samp{P} mean the same thing).
cvs.texi(,10857) 
cvs.texi(,10858) @item A @var{file}
cvs.texi(,10859) The file has been added to your private copy of the
cvs.texi(,10860) sources, but has not yet been committed to the
cvs.texi(,10861) repository.  If you delete your copy of the sources
cvs.texi(,10862) this file will be lost.
cvs.texi(,10863) 
cvs.texi(,10864) @item R @var{file}
cvs.texi(,10865) The file has been removed from your private copy of the
cvs.texi(,10866) sources, but has not yet been removed from the
cvs.texi(,10867) repository, since you have not yet committed the
cvs.texi(,10868) removal.  @xref{commit}.
cvs.texi(,10869) 
cvs.texi(,10870) @item M @var{file}
cvs.texi(,10871) The file is modified in your working directory.  There
cvs.texi(,10872) might also be a newer revision inside the repository.
cvs.texi(,10873) 
cvs.texi(,10874) @item ? @var{file}
cvs.texi(,10875) @var{file} is in your working directory, but does not
cvs.texi(,10876) correspond to anything in the source repository, and is
cvs.texi(,10877) not in the list of files for @sc{cvs} to ignore (see the
cvs.texi(,10878) description of the @samp{-I} option, and
cvs.texi(,10879) @pxref{cvsignore}).  If you remove your working
cvs.texi(,10880) sources, this file will be lost.
cvs.texi(,10881) @end table
cvs.texi(,10882) 
cvs.texi(,10883) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,10884) @node release examples
cvs.texi(,10885) @appendixsubsec release examples
cvs.texi(,10886) 
cvs.texi(,10887) Release the @file{tc} directory, and delete your local working copy
cvs.texi(,10888) of the files.
cvs.texi(,10889) 
cvs.texi(,10890) @example
cvs.texi(,10891) $ cd ..         # @r{You must stand immediately above the}
cvs.texi(,10892)                 # @r{sources when you issue @samp{cvs release}.}
cvs.texi(,10893) $ cvs release -d tc
cvs.texi(,10894) You have [0] altered files in this repository.
cvs.texi(,10895) Are you sure you want to release (and delete) directory `tc': y
cvs.texi(,10896) $
cvs.texi(,10897) @end example
cvs.texi(,10898) 
cvs.texi(,10899) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,10900) @node update
cvs.texi(,10901) @appendixsec update---Bring work tree in sync with repository
cvs.texi(,10902) @cindex update (subcommand)
cvs.texi(,10903) 
cvs.texi(,10904) @itemize @bullet
cvs.texi(,10905) @item
cvs.texi(,10906) update [-ACdflPpR] [-I name] [-j rev [-j rev]] [-k kflag] [-r tag|-D date] [-W spec] files@dots{}
cvs.texi(,10907) @item
cvs.texi(,10908) Requires: repository, working directory.
cvs.texi(,10909) @item
cvs.texi(,10910) Changes: working directory.
cvs.texi(,10911) @end itemize
cvs.texi(,10912) 
cvs.texi(,10913) After you've run checkout to create your private copy
cvs.texi(,10914) of source from the common repository, other developers
cvs.texi(,10915) will continue changing the central source.  From time
cvs.texi(,10916) to time, when it is convenient in your development
cvs.texi(,10917) process, you can use the @code{update} command from
cvs.texi(,10918) within your working directory to reconcile your work
cvs.texi(,10919) with any revisions applied to the source repository
cvs.texi(,10920) since your last checkout or update.  Without the @code{-C}
cvs.texi(,10921) option, @code{update} will also merge any differences
cvs.texi(,10922) between the local copy of files and their base revisions
cvs.texi(,10923) into any destination revisions specified with @code{-r},
cvs.texi(,10924) @code{-D}, or @code{-A}.
cvs.texi(,10925) 
cvs.texi(,10926) @menu
cvs.texi(,10927) * update options::              update options
cvs.texi(,10928) * update output::               update output
cvs.texi(,10929) @end menu
cvs.texi(,10930) 
cvs.texi(,10931) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,10932) @node update options
cvs.texi(,10933) @appendixsubsec update options
cvs.texi(,10934) 
cvs.texi(,10935) These standard options are available with @code{update}
cvs.texi(,10936) (@pxref{Common options}, for a complete description of
cvs.texi(,10937) them):
cvs.texi(,10938) 
cvs.texi(,10939) @table @code
cvs.texi(,10940) @item -D date
cvs.texi(,10941) Use the most recent revision no later than @var{date}.
cvs.texi(,10942) This option is sticky, and implies @samp{-P}.
cvs.texi(,10943) See @ref{Sticky tags}, for more information on sticky tags/dates.
cvs.texi(,10944) 
cvs.texi(,10945) @item -f
cvs.texi(,10946) Only useful with the @samp{-D @var{date}} or @samp{-r
cvs.texi(,10947) @var{tag}} flags.  If no matching revision is found,
cvs.texi(,10948) retrieve the most recent revision (instead of ignoring
cvs.texi(,10949) the file).
cvs.texi(,10950) 
cvs.texi(,10951) @item -k @var{kflag}
cvs.texi(,10952) Process keywords according to @var{kflag}.  See
cvs.texi(,10953) @ref{Keyword substitution}.
cvs.texi(,10954) This option is sticky; future updates of
cvs.texi(,10955) this file in this working directory will use the same
cvs.texi(,10956) @var{kflag}.  The @code{status} command can be viewed
cvs.texi(,10957) to see the sticky options.  See @ref{Invoking CVS}, for
cvs.texi(,10958) more information on the @code{status} command.
cvs.texi(,10959) 
cvs.texi(,10960) @item -l
cvs.texi(,10961) Local; run only in current working directory.  @xref{Recursive behavior}.
cvs.texi(,10962) 
cvs.texi(,10963) @item -P
cvs.texi(,10964) Prune empty directories.  See @ref{Moving directories}.
cvs.texi(,10965) 
cvs.texi(,10966) @item -p
cvs.texi(,10967) Pipe files to the standard output.
cvs.texi(,10968) 
cvs.texi(,10969) @item -R
cvs.texi(,10970) Update directories recursively (default).  @xref{Recursive
cvs.texi(,10971) behavior}.
cvs.texi(,10972) 
cvs.texi(,10973) @item -r rev
cvs.texi(,10974) Retrieve revision/tag @var{rev}.  This option is sticky,
cvs.texi(,10975) and implies @samp{-P}.
cvs.texi(,10976) See @ref{Sticky tags}, for more information on sticky tags/dates.
cvs.texi(,10977) @end table
cvs.texi(,10978) 
cvs.texi(,10979) @need 800
cvs.texi(,10980) These special options are also available with
cvs.texi(,10981) @code{update}.
cvs.texi(,10982) 
cvs.texi(,10983) @table @code
cvs.texi(,10984) @item -A
cvs.texi(,10985) Reset any sticky tags, dates, or @samp{-k} options.
cvs.texi(,10986) See @ref{Sticky tags}, for more information on sticky tags/dates.
cvs.texi(,10987) 
cvs.texi(,10988) @item -C
cvs.texi(,10989) Overwrite locally modified files with clean copies from
cvs.texi(,10990) the repository (the modified file is saved in
cvs.texi(,10991) @file{.#@var{file}.@var{revision}}, however).
cvs.texi(,10992) 
cvs.texi(,10993) @item -d
cvs.texi(,10994) Create any directories that exist in the repository if
cvs.texi(,10995) they're missing from the working directory.  Normally,
cvs.texi(,10996) @code{update} acts only on directories and files that
cvs.texi(,10997) were already enrolled in your working directory.
cvs.texi(,10998) 
cvs.texi(,10999) This is useful for updating directories that were
cvs.texi(,11000) created in the repository since the initial checkout;
cvs.texi(,11001) but it has an unfortunate side effect.  If you
cvs.texi(,11002) deliberately avoided certain directories in the
cvs.texi(,11003) repository when you created your working directory
cvs.texi(,11004) (either through use of a module name or by listing
cvs.texi(,11005) explicitly the files and directories you wanted on the
cvs.texi(,11006) command line), then updating with @samp{-d} will create
cvs.texi(,11007) those directories, which may not be what you want.
cvs.texi(,11008) 
cvs.texi(,11009) @item -I @var{name}
cvs.texi(,11010) Ignore files whose names match @var{name} (in your
cvs.texi(,11011) working directory) during the update.  You can specify
cvs.texi(,11012) @samp{-I} more than once on the command line to specify
cvs.texi(,11013) several files to ignore.  Use @samp{-I !} to avoid
cvs.texi(,11014) ignoring any files at all.  @xref{cvsignore}, for other
cvs.texi(,11015) ways to make @sc{cvs} ignore some files.
cvs.texi(,11016) 
cvs.texi(,11017) @item -W@var{spec}
cvs.texi(,11018) Specify file names that should be filtered during
cvs.texi(,11019) update.  You can use this option repeatedly.
cvs.texi(,11020) 
cvs.texi(,11021) @var{spec} can be a file name pattern of the same type
cvs.texi(,11022) that you can specify in the @file{.cvswrappers}
cvs.texi(,11023) file. @xref{Wrappers}.
cvs.texi(,11024) 
cvs.texi(,11025) @item -j@var{revision}
cvs.texi(,11026) With two @samp{-j} options, merge changes from the
cvs.texi(,11027) revision specified with the first @samp{-j} option to
cvs.texi(,11028) the revision specified with the second @samp{j} option,
cvs.texi(,11029) into the working directory.
cvs.texi(,11030) 
cvs.texi(,11031) With one @samp{-j} option, merge changes from the
cvs.texi(,11032) ancestor revision to the revision specified with the
cvs.texi(,11033) @samp{-j} option, into the working directory.  The
cvs.texi(,11034) ancestor revision is the common ancestor of the
cvs.texi(,11035) revision which the working directory is based on, and
cvs.texi(,11036) the revision specified in the @samp{-j} option.
cvs.texi(,11037) 
cvs.texi(,11038) Note that using a single @samp{-j @var{tagname}} option rather than
cvs.texi(,11039) @samp{-j @var{branchname}} to merge changes from a branch will
cvs.texi(,11040) often not remove files which were removed on the branch.
cvs.texi(,11041) @xref{Merging adds and removals}, for more.
cvs.texi(,11042) 
cvs.texi(,11043) In addition, each @samp{-j} option can contain an optional
cvs.texi(,11044) date specification which, when used with branches, can
cvs.texi(,11045) limit the chosen revision to one within a specific
cvs.texi(,11046) date.  An optional date is specified by adding a colon
cvs.texi(,11047) (:) to the tag:
cvs.texi(,11048) @samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}.
cvs.texi(,11049) 
cvs.texi(,11050) @xref{Branching and merging}.
cvs.texi(,11051) 
cvs.texi(,11052) @end table
cvs.texi(,11053) 
cvs.texi(,11054) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,11055) @node update output
cvs.texi(,11056) @appendixsubsec update output
cvs.texi(,11057) 
cvs.texi(,11058) @code{update} and @code{checkout} keep you informed of
cvs.texi(,11059) their progress by printing a line for each file, preceded
cvs.texi(,11060) by one character indicating the status of the file:
cvs.texi(,11061) 
cvs.texi(,11062) @table @code
cvs.texi(,11063) @item U @var{file}
cvs.texi(,11064) The file was brought up to date with respect to the
cvs.texi(,11065) repository.  This is done for any file that exists in
cvs.texi(,11066) the repository but not in your source, and for files
cvs.texi(,11067) that you haven't changed but are not the most recent
cvs.texi(,11068) versions available in the repository.
cvs.texi(,11069) 
cvs.texi(,11070) @item P @var{file}
cvs.texi(,11071) Like @samp{U}, but the @sc{cvs} server sends a patch instead of an entire
cvs.texi(,11072) file.  This accomplishes the same thing as @samp{U} using less bandwidth.
cvs.texi(,11073) 
cvs.texi(,11074) @item A @var{file}
cvs.texi(,11075) The file has been added to your private copy of the
cvs.texi(,11076) sources, and will be added to the source repository
cvs.texi(,11077) when you run @code{commit} on the file.  This is a
cvs.texi(,11078) reminder to you that the file needs to be committed.
cvs.texi(,11079) 
cvs.texi(,11080) @item R @var{file}
cvs.texi(,11081) The file has been removed from your private copy of the
cvs.texi(,11082) sources, and will be removed from the source repository
cvs.texi(,11083) when you run @code{commit} on the file.  This is a
cvs.texi(,11084) reminder to you that the file needs to be committed.
cvs.texi(,11085) 
cvs.texi(,11086) @item M @var{file}
cvs.texi(,11087) The file is modified in  your  working  directory.
cvs.texi(,11088) 
cvs.texi(,11089) @samp{M} can indicate one of two states for a file
cvs.texi(,11090) you're working on: either there were no modifications
cvs.texi(,11091) to the same file in the repository, so that your file
cvs.texi(,11092) remains as you last saw it; or there were modifications
cvs.texi(,11093) in the repository as well as in your copy, but they
cvs.texi(,11094) were merged successfully, without conflict, in your
cvs.texi(,11095) working directory.
cvs.texi(,11096) 
cvs.texi(,11097) @sc{cvs} will print some messages if it merges your work,
cvs.texi(,11098) and a backup copy of your working file (as it looked
cvs.texi(,11099) before you ran @code{update}) will be made.  The exact
cvs.texi(,11100) name of that file is printed while @code{update} runs.
cvs.texi(,11101) 
cvs.texi(,11102) @item C @var{file}
cvs.texi(,11103) @cindex .# files
cvs.texi(,11104) @cindex __ files (VMS)
cvs.texi(,11105) A conflict was detected while trying to merge your
cvs.texi(,11106) changes to @var{file} with changes from the source
cvs.texi(,11107) repository.  @var{file} (the copy in your working
cvs.texi(,11108) directory) is now the result of attempting to merge
cvs.texi(,11109) the two revisions; an unmodified copy of your file
cvs.texi(,11110) is also in your working directory, with the name
cvs.texi(,11111) @file{.#@var{file}.@var{revision}} where @var{revision}
cvs.texi(,11112) is the revision that your modified file started
cvs.texi(,11113) from.  Resolve the conflict as described in
cvs.texi(,11114) @ref{Conflicts example}.
cvs.texi(,11115) @c "some systems" as in out-of-the-box OSes?  Not as
cvs.texi(,11116) @c far as I know.  We need to advise sysadmins as well
cvs.texi(,11117) @c as users how to set up this kind of purge, if that is
cvs.texi(,11118) @c what they want.
cvs.texi(,11119) @c We also might want to think about cleaner solutions,
cvs.texi(,11120) @c like having CVS remove the .# file once the conflict
cvs.texi(,11121) @c has been resolved or something like that.
cvs.texi(,11122) (Note that some systems automatically purge
cvs.texi(,11123) files that begin with @file{.#} if they have not been
cvs.texi(,11124) accessed for a few days.  If you intend to keep a copy
cvs.texi(,11125) of your original file, it is a very good idea to rename
cvs.texi(,11126) it.)  Under @sc{vms}, the file name starts with
cvs.texi(,11127) @file{__} rather than @file{.#}.
cvs.texi(,11128) 
cvs.texi(,11129) @item ? @var{file}
cvs.texi(,11130) @var{file} is in your working directory, but does not
cvs.texi(,11131) correspond to anything in the source repository, and is
cvs.texi(,11132) not in the list of files for @sc{cvs} to ignore (see the
cvs.texi(,11133) description of the @samp{-I} option, and
cvs.texi(,11134) @pxref{cvsignore}).
cvs.texi(,11135) @end table
cvs.texi(,11136) 
cvs.texi(,11137) @node Invoking CVS
cvs.texi(,11138) @appendix Quick reference to CVS commands
cvs.texi(,11139) @cindex Command reference
cvs.texi(,11140) @cindex Reference, commands
cvs.texi(,11141) @cindex Invoking CVS
cvs.texi(,11142) 
cvs.texi(,11143) This appendix describes how to invoke @sc{cvs}, with
cvs.texi(,11144) references to where each command or feature is
cvs.texi(,11145) described in detail.  For other references run the
cvs.texi(,11146) @code{cvs --help} command, or see @ref{Index}.
cvs.texi(,11147) 
cvs.texi(,11148) A @sc{cvs} command looks like:
cvs.texi(,11149) 
cvs.texi(,11150) @example
cvs.texi(,11151) cvs [ @var{global_options} ] @var{command} [ @var{command_options} ] [ @var{command_args} ]
cvs.texi(,11152) @end example
cvs.texi(,11153) 
cvs.texi(,11154) Global options:
cvs.texi(,11155) 
cvs.texi(,11156) @table @code
cvs.texi(,11157) @item --allow-root=@var{rootdir}
cvs.texi(,11158) Specify legal @sc{cvsroot} directory (server only) (not
cvs.texi(,11159) in @sc{cvs} 1.9 and older).  See @ref{Password
cvs.texi(,11160) authentication server}.
cvs.texi(,11161) 
cvs.texi(,11162) @item -a
cvs.texi(,11163) Authenticate all communication (client only) (not in @sc{cvs}
cvs.texi(,11164) 1.9 and older).  See @ref{Global options}.
cvs.texi(,11165) 
cvs.texi(,11166) @item -b
cvs.texi(,11167) Specify RCS location (@sc{cvs} 1.9 and older).  See
cvs.texi(,11168) @ref{Global options}.
cvs.texi(,11169) 
cvs.texi(,11170) @item -d @var{root}
cvs.texi(,11171) Specify the @sc{cvsroot}.  See @ref{Repository}.
cvs.texi(,11172) 
cvs.texi(,11173) @item -e @var{editor}
cvs.texi(,11174) Edit messages with @var{editor}.  See @ref{Committing
cvs.texi(,11175) your changes}.
cvs.texi(,11176) 
cvs.texi(,11177) @item -f
cvs.texi(,11178) Do not read the @file{~/.cvsrc} file.  See @ref{Global
cvs.texi(,11179) options}.
cvs.texi(,11180) 
cvs.texi(,11181) @item -H
cvs.texi(,11182) @itemx --help
cvs.texi(,11183) Print a help message.  See @ref{Global options}.
cvs.texi(,11184) 
cvs.texi(,11185) @item -l
cvs.texi(,11186) Do not log in @file{$CVSROOT/CVSROOT/history} file.  See @ref{Global
cvs.texi(,11187) options}.
cvs.texi(,11188) 
cvs.texi(,11189) @item -n
cvs.texi(,11190) Do not change any files.  See @ref{Global options}.
cvs.texi(,11191) 
cvs.texi(,11192) @item -Q
cvs.texi(,11193) Be really quiet.  See @ref{Global options}.
cvs.texi(,11194) 
cvs.texi(,11195) @item -q
cvs.texi(,11196) Be somewhat quiet.  See @ref{Global options}.
cvs.texi(,11197) 
cvs.texi(,11198) @item -r
cvs.texi(,11199) Make new working files read-only.  See @ref{Global options}.
cvs.texi(,11200) 
cvs.texi(,11201) @item -s @var{variable}=@var{value}
cvs.texi(,11202) Set a user variable.  See @ref{Variables}.
cvs.texi(,11203) 
cvs.texi(,11204) @item -T @var{tempdir}
cvs.texi(,11205) Put temporary files in @var{tempdir}.  See @ref{Global
cvs.texi(,11206) options}.
cvs.texi(,11207) 
cvs.texi(,11208) @item -t
cvs.texi(,11209) Trace @sc{cvs} execution.  See @ref{Global options}.
cvs.texi(,11210) 
cvs.texi(,11211) @item -v
cvs.texi(,11212) @item --version
cvs.texi(,11213) Display version and copyright information for @sc{cvs}.
cvs.texi(,11214) 
cvs.texi(,11215) @item -w
cvs.texi(,11216) Make new working files read-write.  See @ref{Global
cvs.texi(,11217) options}.
cvs.texi(,11218) 
cvs.texi(,11219) @item -x
cvs.texi(,11220) Encrypt all communication (client only).
cvs.texi(,11221) See @ref{Global options}.
cvs.texi(,11222) 
cvs.texi(,11223) @item -z @var{gzip-level}
cvs.texi(,11224) @cindex Compression
cvs.texi(,11225) @cindex Gzip
cvs.texi(,11226) Set the compression level (client only).
cvs.texi(,11227) See @ref{Global options}.
cvs.texi(,11228) @end table
cvs.texi(,11229) 
cvs.texi(,11230) Keyword expansion modes (@pxref{Substitution modes}):
cvs.texi(,11231) 
cvs.texi(,11232) @example
cvs.texi(splitrcskeyword,11233) -kkv  $@i{}Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp $
cvs.texi(splitrcskeyword,11234) -kkvl $@i{}Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
cvs.texi(splitrcskeyword,11235) -kk   $@i{}Id$
cvs.texi(,11236) -kv   file1,v 1.1 1993/12/09 03:21:13 joe Exp
cvs.texi(,11237) -ko   @i{no expansion}
cvs.texi(,11238) -kb   @i{no expansion, file is binary}
cvs.texi(,11239) @end example
cvs.texi(,11240) 
cvs.texi(,11241) Keywords (@pxref{Keyword list}):
cvs.texi(,11242) 
cvs.texi(,11243) @example
cvs.texi(splitrcskeyword,11244) $@i{}Author: joe $
cvs.texi(splitrcskeyword,11245) $@i{}Date: 1993/12/09 03:21:13 $
cvs.texi(splitrcskeyword,11246) $@i{}CVSHeader: files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
cvs.texi(splitrcskeyword,11247) $@i{}Header: /home/files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
cvs.texi(splitrcskeyword,11248) $@i{}Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
cvs.texi(splitrcskeyword,11249) $@i{}Locker: harry $
cvs.texi(splitrcskeyword,11250) $@i{}Name: snapshot_1_14 $
cvs.texi(splitrcskeyword,11251) $@i{}RCSfile: file1,v $
cvs.texi(splitrcskeyword,11252) $@i{}Revision: 1.1 $
cvs.texi(splitrcskeyword,11253) $@i{}Source: /home/files/file1,v $
cvs.texi(splitrcskeyword,11254) $@i{}State: Exp $
cvs.texi(splitrcskeyword,11255) $@i{}Log: file1,v $
cvs.texi(,11256) Revision 1.1  1993/12/09 03:30:17  joe
cvs.texi(,11257) Initial revision
cvs.texi(,11258) 
cvs.texi(,11259) @end example
cvs.texi(,11260) 
cvs.texi(,11261) @c The idea behind this table is that we want each item
cvs.texi(,11262) @c to be a sentence or two at most.  Preferably a
cvs.texi(,11263) @c single line.
cvs.texi(,11264) @c
cvs.texi(,11265) @c In some cases refs to "foo options" are just to get
cvs.texi(,11266) @c this thing written quickly, not because the "foo
cvs.texi(,11267) @c options" node is really the best place to point.
cvs.texi(,11268) Commands, command options, and command arguments:
cvs.texi(,11269) 
cvs.texi(,11270) @table @code
cvs.texi(,11271) @c ------------------------------------------------------------
cvs.texi(,11272) @item add [@var{options}] [@var{files}@dots{}]
cvs.texi(,11273) Add a new file/directory.  See @ref{Adding files}.
cvs.texi(,11274) 
cvs.texi(,11275) @table @code
cvs.texi(,11276) @item -k @var{kflag}
cvs.texi(,11277) Set keyword expansion.
cvs.texi(,11278) 
cvs.texi(,11279) @item -m @var{msg}
cvs.texi(,11280) Set file description.
cvs.texi(,11281) @end table
cvs.texi(,11282) 
cvs.texi(,11283) @c ------------------------------------------------------------
cvs.texi(,11284) @item admin [@var{options}] [@var{files}@dots{}]
cvs.texi(,11285) Administration of history files in the repository.  See
cvs.texi(,11286) @ref{admin}.
cvs.texi(,11287) @c This list omits those options which are not
cvs.texi(,11288) @c documented as being useful with CVS.  That might be
cvs.texi(,11289) @c a mistake...
cvs.texi(,11290) 
cvs.texi(,11291) @table @code
cvs.texi(,11292) @item -b[@var{rev}]
cvs.texi(,11293) Set default branch.  See @ref{Reverting local changes}.
cvs.texi(,11294) 
cvs.texi(,11295) @item -c@var{string}
cvs.texi(,11296) Set comment leader.
cvs.texi(,11297) 
cvs.texi(,11298) @item -k@var{subst}
cvs.texi(,11299) Set keyword substitution.  See @ref{Keyword
cvs.texi(,11300) substitution}.
cvs.texi(,11301) 
cvs.texi(,11302) @item -l[@var{rev}]
cvs.texi(,11303) Lock revision @var{rev}, or latest revision.
cvs.texi(,11304) 
cvs.texi(,11305) @item -m@var{rev}:@var{msg}
cvs.texi(,11306) Replace the log message of revision @var{rev} with
cvs.texi(,11307) @var{msg}.
cvs.texi(,11308) 
cvs.texi(,11309) @item -o@var{range}
cvs.texi(,11310) Delete revisions from the repository.  See
cvs.texi(,11311) @ref{admin options}.
cvs.texi(,11312) 
cvs.texi(,11313) @item -q
cvs.texi(,11314) Run quietly; do not print diagnostics.
cvs.texi(,11315) 
cvs.texi(,11316) @item -s@var{state}[:@var{rev}]
cvs.texi(,11317) Set the state.
cvs.texi(,11318) 
cvs.texi(,11319) @c Does not work for client/server CVS
cvs.texi(,11320) @item -t
cvs.texi(,11321) Set file description from standard input.
cvs.texi(,11322) 
cvs.texi(,11323) @item -t@var{file}
cvs.texi(,11324) Set file description from @var{file}.
cvs.texi(,11325) 
cvs.texi(,11326) @item -t-@var{string}
cvs.texi(,11327) Set file description to @var{string}.
cvs.texi(,11328) 
cvs.texi(,11329) @item -u[@var{rev}]
cvs.texi(,11330) Unlock revision @var{rev}, or latest revision.
cvs.texi(,11331) @end table
cvs.texi(,11332) 
cvs.texi(,11333) @c ------------------------------------------------------------
cvs.texi(,11334) @item annotate [@var{options}] [@var{files}@dots{}]
cvs.texi(,11335) Show last revision where each line was modified.  See
cvs.texi(,11336) @ref{annotate}.
cvs.texi(,11337) 
cvs.texi(,11338) @table @code
cvs.texi(,11339) @item -D @var{date}
cvs.texi(,11340) Annotate the most recent revision no later than
cvs.texi(,11341) @var{date}.  See @ref{Common options}.
cvs.texi(,11342) 
cvs.texi(,11343) @item -F
cvs.texi(,11344) Force annotation of binary files.  (Without this option,
cvs.texi(,11345) binary files are skipped with a message.)
cvs.texi(,11346) 
cvs.texi(,11347) @item -f
cvs.texi(,11348) Use head revision if tag/date not found.  See
cvs.texi(,11349) @ref{Common options}.
cvs.texi(,11350) 
cvs.texi(,11351) @item -l
cvs.texi(,11352) Local; run only in current working directory.  @xref{Recursive behavior}.
cvs.texi(,11353) 
cvs.texi(,11354) @item -R
cvs.texi(,11355) Operate recursively (default).  @xref{Recursive
cvs.texi(,11356) behavior}.
cvs.texi(,11357) 
cvs.texi(,11358) @item -r @var{tag}
cvs.texi(,11359) Annotate revision @var{tag}.  See @ref{Common options}.
cvs.texi(,11360) @end table
cvs.texi(,11361) 
cvs.texi(,11362) @c ------------------------------------------------------------
cvs.texi(,11363) @item checkout [@var{options}] @var{modules}@dots{}
cvs.texi(,11364) Get a copy of the sources.  See @ref{checkout}.
cvs.texi(,11365) 
cvs.texi(,11366) @table @code
cvs.texi(,11367) @item -A
cvs.texi(,11368) Reset any sticky tags/date/options.  See @ref{Sticky
cvs.texi(,11369) tags} and @ref{Keyword substitution}.
cvs.texi(,11370) 
cvs.texi(,11371) @item -c
cvs.texi(,11372) Output the module database.  See @ref{checkout options}.
cvs.texi(,11373) 
cvs.texi(,11374) @item -D @var{date}
cvs.texi(,11375) Check out revisions as of @var{date} (is sticky).  See
cvs.texi(,11376) @ref{Common options}.
cvs.texi(,11377) 
cvs.texi(,11378) @item -d @var{dir}
cvs.texi(,11379) Check out into @var{dir}.  See @ref{checkout options}.
cvs.texi(,11380) 
cvs.texi(,11381) @item -f
cvs.texi(,11382) Use head revision if tag/date not found.  See
cvs.texi(,11383) @ref{Common options}.
cvs.texi(,11384) 
cvs.texi(,11385) @c Probably want to use rev1/rev2 style like for diff
cvs.texi(,11386) @c -r.  Here and in on-line help.
cvs.texi(,11387) @item -j @var{rev}
cvs.texi(,11388) Merge in changes.  See @ref{checkout options}.
cvs.texi(,11389) 
cvs.texi(,11390) @item -k @var{kflag}
cvs.texi(,11391) Use @var{kflag} keyword expansion.  See
cvs.texi(,11392) @ref{Substitution modes}.
cvs.texi(,11393) 
cvs.texi(,11394) @item -l
cvs.texi(,11395) Local; run only in current working directory.  @xref{Recursive behavior}.
cvs.texi(,11396) 
cvs.texi(,11397) @item -N
cvs.texi(,11398) Don't ``shorten'' module paths if -d specified.  See
cvs.texi(,11399) @ref{checkout options}.
cvs.texi(,11400) 
cvs.texi(,11401) @item -n
cvs.texi(,11402) Do not run module program (if any).  See @ref{checkout options}.
cvs.texi(,11403) 
cvs.texi(,11404) @item -P
cvs.texi(,11405) Prune empty directories.  See @ref{Moving directories}.
cvs.texi(,11406) 
cvs.texi(,11407) @item -p
cvs.texi(,11408) Check out files to standard output (avoids
cvs.texi(,11409) stickiness).  See @ref{checkout options}.
cvs.texi(,11410) 
cvs.texi(,11411) @item -R
cvs.texi(,11412) Operate recursively (default).  @xref{Recursive
cvs.texi(,11413) behavior}.
cvs.texi(,11414) 
cvs.texi(,11415) @item -r @var{tag}
cvs.texi(,11416) Checkout revision @var{tag} (is sticky).  See @ref{Common options}.
cvs.texi(,11417) 
cvs.texi(,11418) @item -s
cvs.texi(,11419) Like -c, but include module status.  See @ref{checkout options}.
cvs.texi(,11420) @end table
cvs.texi(,11421) 
cvs.texi(,11422) @c ------------------------------------------------------------
cvs.texi(,11423) @item commit [@var{options}] [@var{files}@dots{}]
cvs.texi(,11424) Check changes into the repository.  See @ref{commit}.
cvs.texi(,11425) 
cvs.texi(,11426) @table @code
cvs.texi(,11427) @item -F @var{file}
cvs.texi(,11428) Read log message from @var{file}.  See @ref{commit options}.
cvs.texi(,11429) 
cvs.texi(,11430) @item -f
cvs.texi(,11431) @c What is this "disables recursion"?  It is from the
cvs.texi(,11432) @c on-line help; is it documented in this manual?
cvs.texi(,11433) Force the file to be committed; disables recursion.
cvs.texi(,11434) See @ref{commit options}.
cvs.texi(,11435) 
cvs.texi(,11436) @item -l
cvs.texi(,11437) Local; run only in current working directory.  See @ref{Recursive behavior}.
cvs.texi(,11438) 
cvs.texi(,11439) @item -m @var{msg}
cvs.texi(,11440) Use @var{msg} as log message.  See @ref{commit options}.
cvs.texi(,11441) 
cvs.texi(,11442) @item -n
cvs.texi(,11443) Do not run module program (if any).  See @ref{commit options}.
cvs.texi(,11444) 
cvs.texi(,11445) @item -R
cvs.texi(,11446) Operate recursively (default).  @xref{Recursive
cvs.texi(,11447) behavior}.
cvs.texi(,11448) 
cvs.texi(,11449) @item -r @var{rev}
cvs.texi(,11450) Commit to @var{rev}.  See @ref{commit options}.
cvs.texi(,11451) @c FIXME: should be dragging over text from
cvs.texi(,11452) @c commit options, especially if it can be cleaned up
cvs.texi(,11453) @c and made concise enough.
cvs.texi(,11454) @end table
cvs.texi(,11455) 
cvs.texi(,11456) @c ------------------------------------------------------------
cvs.texi(,11457) @item diff [@var{options}] [@var{files}@dots{}]
cvs.texi(,11458) Show differences between revisions.  See @ref{diff}.
cvs.texi(,11459) In addition to the options shown below, accepts a wide
cvs.texi(,11460) variety of options to control output style, for example
cvs.texi(,11461) @samp{-c} for context diffs.
cvs.texi(,11462) 
cvs.texi(,11463) @table @code
cvs.texi(,11464) @item -D @var{date1}
cvs.texi(,11465) Diff revision for date against working file.  See
cvs.texi(,11466) @ref{diff options}.
cvs.texi(,11467) 
cvs.texi(,11468) @item -D @var{date2}
cvs.texi(,11469) Diff @var{rev1}/@var{date1} against @var{date2}.  See
cvs.texi(,11470) @ref{diff options}.
cvs.texi(,11471) 
cvs.texi(,11472) @item -l
cvs.texi(,11473) Local; run only in current working directory.  See @ref{Recursive behavior}.
cvs.texi(,11474) 
cvs.texi(,11475) @item -N
cvs.texi(,11476) Include diffs for added and removed files.  See
cvs.texi(,11477) @ref{diff options}.
cvs.texi(,11478) 
cvs.texi(,11479) @item -R
cvs.texi(,11480) Operate recursively (default).  @xref{Recursive
cvs.texi(,11481) behavior}.
cvs.texi(,11482) 
cvs.texi(,11483) @item -r @var{rev1}
cvs.texi(,11484) Diff revision for @var{rev1} against working file.  See
cvs.texi(,11485) @ref{diff options}.
cvs.texi(,11486) 
cvs.texi(,11487) @item -r @var{rev2}
cvs.texi(,11488) Diff @var{rev1}/@var{date1} against @var{rev2}.  See @ref{diff options}.
cvs.texi(,11489) @end table
cvs.texi(,11490) 
cvs.texi(,11491) @c ------------------------------------------------------------
cvs.texi(,11492) @item edit [@var{options}] [@var{files}@dots{}]
cvs.texi(,11493) Get ready to edit a watched file.  See @ref{Editing files}.
cvs.texi(,11494) 
cvs.texi(,11495) @table @code
cvs.texi(,11496) @item -a @var{actions}
cvs.texi(,11497) Specify actions for temporary watch, where
cvs.texi(,11498) @var{actions} is @code{edit}, @code{unedit},
cvs.texi(,11499) @code{commit}, @code{all}, or @code{none}.  See
cvs.texi(,11500) @ref{Editing files}.
cvs.texi(,11501) 
cvs.texi(,11502) @item -l
cvs.texi(,11503) Local; run only in current working directory.  See @ref{Recursive behavior}.
cvs.texi(,11504) 
cvs.texi(,11505) @item -R
cvs.texi(,11506) Operate recursively (default).  @xref{Recursive
cvs.texi(,11507) behavior}.
cvs.texi(,11508) @end table
cvs.texi(,11509) 
cvs.texi(,11510) @c ------------------------------------------------------------
cvs.texi(,11511) @item editors [@var{options}] [@var{files}@dots{}]
cvs.texi(,11512) See who is editing a watched file.  See @ref{Watch information}.
cvs.texi(,11513) 
cvs.texi(,11514) @table @code
cvs.texi(,11515) @item -l
cvs.texi(,11516) Local; run only in current working directory.  See @ref{Recursive behavior}.
cvs.texi(,11517) 
cvs.texi(,11518) @item -R
cvs.texi(,11519) Operate recursively (default).  @xref{Recursive
cvs.texi(,11520) behavior}.
cvs.texi(,11521) @end table
cvs.texi(,11522) 
cvs.texi(,11523) @c ------------------------------------------------------------
cvs.texi(,11524) @item export [@var{options}] @var{modules}@dots{}
cvs.texi(,11525) Export files from @sc{cvs}.  See @ref{export}.
cvs.texi(,11526) 
cvs.texi(,11527) @table @code
cvs.texi(,11528) @item -D @var{date}
cvs.texi(,11529) Check out revisions as of @var{date}.  See
cvs.texi(,11530) @ref{Common options}.
cvs.texi(,11531) 
cvs.texi(,11532) @item -d @var{dir}
cvs.texi(,11533) Check out into @var{dir}.  See @ref{export options}.
cvs.texi(,11534) 
cvs.texi(,11535) @item -f
cvs.texi(,11536) Use head revision if tag/date not found.  See
cvs.texi(,11537) @ref{Common options}.
cvs.texi(,11538) 
cvs.texi(,11539) @item -k @var{kflag}
cvs.texi(,11540) Use @var{kflag} keyword expansion.  See
cvs.texi(,11541) @ref{Substitution modes}.
cvs.texi(,11542) 
cvs.texi(,11543) @item -l
cvs.texi(,11544) Local; run only in current working directory.  @xref{Recursive behavior}.
cvs.texi(,11545) 
cvs.texi(,11546) @item -N
cvs.texi(,11547) Don't ``shorten'' module paths if -d specified.  See
cvs.texi(,11548) @ref{export options}.
cvs.texi(,11549) 
cvs.texi(,11550) @item -n
cvs.texi(,11551) Do not run module program (if any).  See @ref{export options}.
cvs.texi(,11552) 
cvs.texi(,11553) @item -R
cvs.texi(,11554) Operate recursively (default).  @xref{Recursive
cvs.texi(,11555) behavior}.
cvs.texi(,11556) 
cvs.texi(,11557) @item -r @var{tag}
cvs.texi(,11558) Checkout revision @var{tag}.  See @ref{Common options}.
cvs.texi(,11559) @end table
cvs.texi(,11560) 
cvs.texi(,11561) @c ------------------------------------------------------------
cvs.texi(,11562) @item history [@var{options}] [@var{files}@dots{}]
cvs.texi(,11563) Show repository access history.  See @ref{history}.
cvs.texi(,11564) 
cvs.texi(,11565) @table @code
cvs.texi(,11566) @item -a
cvs.texi(,11567) All users (default is self).  See @ref{history options}.
cvs.texi(,11568) 
cvs.texi(,11569) @item -b @var{str}
cvs.texi(,11570) Back to record with @var{str} in module/file/repos
cvs.texi(,11571) field.  See @ref{history options}.
cvs.texi(,11572) 
cvs.texi(,11573) @item -c
cvs.texi(,11574) Report on committed (modified) files.  See @ref{history options}.
cvs.texi(,11575) 
cvs.texi(,11576) @item -D @var{date}
cvs.texi(,11577) Since @var{date}.  See @ref{history options}.
cvs.texi(,11578) 
cvs.texi(,11579) @item -e
cvs.texi(,11580) Report on all record types.  See @ref{history options}.
cvs.texi(,11581) 
cvs.texi(,11582) @item -l
cvs.texi(,11583) Last modified (committed or modified report).  See @ref{history options}.
cvs.texi(,11584) 
cvs.texi(,11585) @item -m @var{module}
cvs.texi(,11586) Report on @var{module} (repeatable).  See @ref{history options}.
cvs.texi(,11587) 
cvs.texi(,11588) @item -n @var{module}
cvs.texi(,11589) In @var{module}.  See @ref{history options}.
cvs.texi(,11590) 
cvs.texi(,11591) @item -o
cvs.texi(,11592) Report on checked out modules.  See @ref{history options}.
cvs.texi(,11593) 
cvs.texi(,11594) @item -p @var{repository}
cvs.texi(,11595) In @var{repository}.  See @ref{history options}.
cvs.texi(,11596) 
cvs.texi(,11597) @item -r @var{rev}
cvs.texi(,11598) Since revision @var{rev}.  See @ref{history options}.
cvs.texi(,11599) 
cvs.texi(,11600) @item -T
cvs.texi(,11601) @c What the @#$@# is a TAG?  Same as a tag?  This
cvs.texi(,11602) @c wording is also in the online-line help.
cvs.texi(,11603) Produce report on all TAGs.  See @ref{history options}.
cvs.texi(,11604) 
cvs.texi(,11605) @item -t @var{tag}
cvs.texi(,11606) Since tag record placed in history file (by anyone).
cvs.texi(,11607) See @ref{history options}.
cvs.texi(,11608) 
cvs.texi(,11609) @item -u @var{user}
cvs.texi(,11610) For user @var{user} (repeatable).  See @ref{history options}.
cvs.texi(,11611) 
cvs.texi(,11612) @item -w
cvs.texi(,11613) Working directory must match.  See @ref{history options}.
cvs.texi(,11614) 
cvs.texi(,11615) @item -x @var{types}
cvs.texi(,11616) Report on @var{types}, one or more of
cvs.texi(,11617) @code{TOEFWUCGMAR}.  See @ref{history options}.
cvs.texi(,11618) 
cvs.texi(,11619) @item -z @var{zone}
cvs.texi(,11620) Output for time zone @var{zone}.  See @ref{history options}.
cvs.texi(,11621) @end table
cvs.texi(,11622) 
cvs.texi(,11623) @c ------------------------------------------------------------
cvs.texi(,11624) @item import [@var{options}] @var{repository} @var{vendor-tag} @var{release-tags}@dots{}
cvs.texi(,11625) Import files into @sc{cvs}, using vendor branches.  See
cvs.texi(,11626) @ref{import}.
cvs.texi(,11627) 
cvs.texi(,11628) @table @code
cvs.texi(,11629) @item -b @var{bra}
cvs.texi(,11630) Import to vendor branch @var{bra}.  See
cvs.texi(,11631) @ref{Multiple vendor branches}.
cvs.texi(,11632) 
cvs.texi(,11633) @item -d
cvs.texi(,11634) Use the file's modification time as the time of
cvs.texi(,11635) import.  See @ref{import options}.
cvs.texi(,11636) 
cvs.texi(,11637) @item -k @var{kflag}
cvs.texi(,11638) Set default keyword substitution mode.  See
cvs.texi(,11639) @ref{import options}.
cvs.texi(,11640) 
cvs.texi(,11641) @item -m @var{msg}
cvs.texi(,11642) Use @var{msg} for log message.  See
cvs.texi(,11643) @ref{import options}.
cvs.texi(,11644) 
cvs.texi(,11645) @item -I @var{ign}
cvs.texi(,11646) More files to ignore (! to reset).  See
cvs.texi(,11647) @ref{import options}.
cvs.texi(,11648) 
cvs.texi(,11649) @item -W @var{spec}
cvs.texi(,11650) More wrappers.  See @ref{import options}.
cvs.texi(,11651) @end table
cvs.texi(,11652) 
cvs.texi(,11653) @c ------------------------------------------------------------
cvs.texi(,11654) @item init
cvs.texi(,11655) Create a @sc{cvs} repository if it doesn't exist.  See
cvs.texi(,11656) @ref{Creating a repository}.
cvs.texi(,11657) 
cvs.texi(,11658) @c ------------------------------------------------------------
cvs.texi(,11659) @item kserver
cvs.texi(,11660) Kerberos authenticated server.
cvs.texi(,11661) See @ref{Kerberos authenticated}.
cvs.texi(,11662) 
cvs.texi(,11663) @c ------------------------------------------------------------
cvs.texi(,11664) @item log [@var{options}] [@var{files}@dots{}]
cvs.texi(,11665) Print out history information for files.  See @ref{log}.
cvs.texi(,11666) 
cvs.texi(,11667) @table @code
cvs.texi(,11668) @item -b
cvs.texi(,11669) Only list revisions on the default branch.  See @ref{log options}.
cvs.texi(,11670) 
cvs.texi(,11671) @item -d @var{dates}
cvs.texi(,11672) Specify dates (@var{d1}<@var{d2} for range, @var{d} for
cvs.texi(,11673) latest before).  See @ref{log options}.
cvs.texi(,11674) 
cvs.texi(,11675) @item -h
cvs.texi(,11676) Only print header.  See @ref{log options}.
cvs.texi(,11677) 
cvs.texi(,11678) @item -l
cvs.texi(,11679) Local; run only in current working directory.  See @ref{Recursive behavior}.
cvs.texi(,11680) 
cvs.texi(,11681) @item -N
cvs.texi(,11682) Do not list tags.  See @ref{log options}.
cvs.texi(,11683) 
cvs.texi(,11684) @item -R
cvs.texi(,11685) Only print name of RCS file.  See @ref{log options}.
cvs.texi(,11686) 
cvs.texi(,11687) @item -r@var{revs}
cvs.texi(,11688) Only list revisions @var{revs}.  See @ref{log options}.
cvs.texi(,11689) 
cvs.texi(,11690) @item -s @var{states}
cvs.texi(,11691) Only list revisions with specified states.  See @ref{log options}.
cvs.texi(,11692) 
cvs.texi(,11693) @item -t
cvs.texi(,11694) Only print header and descriptive text.  See @ref{log
cvs.texi(,11695) options}.
cvs.texi(,11696) 
cvs.texi(,11697) @item -w@var{logins}
cvs.texi(,11698) Only list revisions checked in by specified logins.  See @ref{log options}.
cvs.texi(,11699) @end table
cvs.texi(,11700) 
cvs.texi(,11701) @c ------------------------------------------------------------
cvs.texi(,11702) @item login
cvs.texi(,11703) Prompt for password for authenticating server.  See
cvs.texi(,11704) @ref{Password authentication client}.
cvs.texi(,11705) 
cvs.texi(,11706) @c ------------------------------------------------------------
cvs.texi(,11707) @item logout
cvs.texi(,11708) Remove stored password for authenticating server.  See
cvs.texi(,11709) @ref{Password authentication client}.
cvs.texi(,11710) 
cvs.texi(,11711) @c ------------------------------------------------------------
cvs.texi(,11712) @item pserver
cvs.texi(,11713) Password authenticated server.
cvs.texi(,11714) See @ref{Password authentication server}.
cvs.texi(,11715) 
cvs.texi(,11716) @c ------------------------------------------------------------
cvs.texi(,11717) @item rannotate [@var{options}] [@var{modules}@dots{}]
cvs.texi(,11718) Show last revision where each line was modified.  See
cvs.texi(,11719) @ref{annotate}.
cvs.texi(,11720) 
cvs.texi(,11721) @table @code
cvs.texi(,11722) @item -D @var{date}
cvs.texi(,11723) Annotate the most recent revision no later than
cvs.texi(,11724) @var{date}.  See @ref{Common options}.
cvs.texi(,11725) 
cvs.texi(,11726) @item -F
cvs.texi(,11727) Force annotation of binary files.  (Without this option,
cvs.texi(,11728) binary files are skipped with a message.)
cvs.texi(,11729) 
cvs.texi(,11730) @item -f
cvs.texi(,11731) Use head revision if tag/date not found.  See
cvs.texi(,11732) @ref{Common options}.
cvs.texi(,11733) 
cvs.texi(,11734) @item -l
cvs.texi(,11735) Local; run only in current working directory.  @xref{Recursive behavior}.
cvs.texi(,11736) 
cvs.texi(,11737) @item -R
cvs.texi(,11738) Operate recursively (default).  @xref{Recursive behavior}.
cvs.texi(,11739) 
cvs.texi(,11740) @item -r @var{tag}
cvs.texi(,11741) Annotate revision @var{tag}.  See @ref{Common options}.
cvs.texi(,11742) @end table
cvs.texi(,11743) 
cvs.texi(,11744) @c ------------------------------------------------------------
cvs.texi(,11745) @item rdiff [@var{options}] @var{modules}@dots{}
cvs.texi(,11746) Show differences between releases.  See @ref{rdiff}.
cvs.texi(,11747) 
cvs.texi(,11748) @table @code
cvs.texi(,11749) @item -c
cvs.texi(,11750) Context diff output format (default).  See @ref{rdiff options}.
cvs.texi(,11751) 
cvs.texi(,11752) @item -D @var{date}
cvs.texi(,11753) Select revisions based on @var{date}.  See @ref{Common options}.
cvs.texi(,11754) 
cvs.texi(,11755) @item -f
cvs.texi(,11756) Use head revision if tag/date not found.  See
cvs.texi(,11757) @ref{Common options}.
cvs.texi(,11758) 
cvs.texi(,11759) @item -l
cvs.texi(,11760) Local; run only in current working directory.  See @ref{Recursive behavior}.
cvs.texi(,11761) 
cvs.texi(,11762) @item -R
cvs.texi(,11763) Operate recursively (default).  @xref{Recursive
cvs.texi(,11764) behavior}.
cvs.texi(,11765) 
cvs.texi(,11766) @item -r @var{rev}
cvs.texi(,11767) Select revisions based on @var{rev}.  See @ref{Common options}.
cvs.texi(,11768) 
cvs.texi(,11769) @item -s
cvs.texi(,11770) Short patch - one liner per file.  See @ref{rdiff options}.
cvs.texi(,11771) 
cvs.texi(,11772) @item -t
cvs.texi(,11773) Top two diffs - last change made to the file.  See
cvs.texi(,11774) @ref{diff options}.
cvs.texi(,11775) 
cvs.texi(,11776) @item -u
cvs.texi(,11777) Unidiff output format.  See @ref{rdiff options}.
cvs.texi(,11778) 
cvs.texi(,11779) @item -V @var{vers}
cvs.texi(,11780) Use RCS Version @var{vers} for keyword expansion (obsolete).  See
cvs.texi(,11781) @ref{rdiff options}.
cvs.texi(,11782) @end table
cvs.texi(,11783) 
cvs.texi(,11784) @c ------------------------------------------------------------
cvs.texi(,11785) @item release [@var{options}] @var{directory}
cvs.texi(,11786) Indicate that a directory is no longer in use.  See
cvs.texi(,11787) @ref{release}.
cvs.texi(,11788) 
cvs.texi(,11789) @table @code
cvs.texi(,11790) @item -d
cvs.texi(,11791) Delete the given directory.  See @ref{release options}.
cvs.texi(,11792) @end table
cvs.texi(,11793) 
cvs.texi(,11794) @c ------------------------------------------------------------
cvs.texi(,11795) @item remove [@var{options}] [@var{files}@dots{}]
cvs.texi(,11796) Remove an entry from the repository.  See @ref{Removing files}.
cvs.texi(,11797) 
cvs.texi(,11798) @table @code
cvs.texi(,11799) @item -f
cvs.texi(,11800) Delete the file before removing it.  See @ref{Removing files}.
cvs.texi(,11801) 
cvs.texi(,11802) @item -l
cvs.texi(,11803) Local; run only in current working directory.  See @ref{Recursive behavior}.
cvs.texi(,11804) 
cvs.texi(,11805) @item -R
cvs.texi(,11806) Operate recursively (default).  @xref{Recursive
cvs.texi(,11807) behavior}.
cvs.texi(,11808) @end table
cvs.texi(,11809) 
cvs.texi(,11810) @c ------------------------------------------------------------
cvs.texi(,11811) @item rlog [@var{options}] [@var{files}@dots{}]
cvs.texi(,11812) Print out history information for modules.  See @ref{log}.
cvs.texi(,11813) 
cvs.texi(,11814) @table @code
cvs.texi(,11815) @item -b
cvs.texi(,11816) Only list revisions on the default branch.  See @ref{log options}.
cvs.texi(,11817) 
cvs.texi(,11818) @item -d @var{dates}
cvs.texi(,11819) Specify dates (@var{d1}<@var{d2} for range, @var{d} for
cvs.texi(,11820) latest before).  See @ref{log options}.
cvs.texi(,11821) 
cvs.texi(,11822) @item -h
cvs.texi(,11823) Only print header.  See @ref{log options}.
cvs.texi(,11824) 
cvs.texi(,11825) @item -l
cvs.texi(,11826) Local; run only in current working directory.  See @ref{Recursive behavior}.
cvs.texi(,11827) 
cvs.texi(,11828) @item -N
cvs.texi(,11829) Do not list tags.  See @ref{log options}.
cvs.texi(,11830) 
cvs.texi(,11831) @item -R
cvs.texi(,11832) Only print name of RCS file.  See @ref{log options}.
cvs.texi(,11833) 
cvs.texi(,11834) @item -r@var{revs}
cvs.texi(,11835) Only list revisions @var{revs}.  See @ref{log options}.
cvs.texi(,11836) 
cvs.texi(,11837) @item -s @var{states}
cvs.texi(,11838) Only list revisions with specified states.  See @ref{log options}.
cvs.texi(,11839) 
cvs.texi(,11840) @item -t
cvs.texi(,11841) Only print header and descriptive text.  See @ref{log options}.
cvs.texi(,11842) 
cvs.texi(,11843) @item -w@var{logins}
cvs.texi(,11844) Only list revisions checked in by specified logins.  See @ref{log options}.
cvs.texi(,11845) @end table
cvs.texi(,11846) 
cvs.texi(,11847) @c ------------------------------------------------------------
cvs.texi(,11848) @item rtag [@var{options}] @var{tag} @var{modules}@dots{}
cvs.texi(,11849) Add a symbolic tag to a module.
cvs.texi(,11850) See @ref{Revisions} and @ref{Branching and merging}.
cvs.texi(,11851) 
cvs.texi(,11852) @table @code
cvs.texi(,11853) @item -a
cvs.texi(,11854) Clear tag from removed files that would not otherwise
cvs.texi(,11855) be tagged.  See @ref{Tagging add/remove}.
cvs.texi(,11856) 
cvs.texi(,11857) @item -b
cvs.texi(,11858) Create a branch named @var{tag}.  See @ref{Branching and merging}.
cvs.texi(,11859) 
cvs.texi(,11860) @item -B
cvs.texi(,11861) Used in conjunction with -F or -d, enables movement and deletion of
cvs.texi(,11862) branch tags.  Use with extreme caution. 
cvs.texi(,11863) 
cvs.texi(,11864) @item -D @var{date}
cvs.texi(,11865) Tag revisions as of @var{date}.  See @ref{Tagging by date/tag}.
cvs.texi(,11866) 
cvs.texi(,11867) @item -d
cvs.texi(,11868) Delete @var{tag}.  See @ref{Modifying tags}.
cvs.texi(,11869) 
cvs.texi(,11870) @item -F
cvs.texi(,11871) Move @var{tag} if it already exists.  See @ref{Modifying tags}.
cvs.texi(,11872) 
cvs.texi(,11873) @item -f
cvs.texi(,11874) Force a head revision match if tag/date not found.
cvs.texi(,11875) See @ref{Tagging by date/tag}.
cvs.texi(,11876) 
cvs.texi(,11877) @item -l
cvs.texi(,11878) Local; run only in current working directory.  See @ref{Recursive behavior}.
cvs.texi(,11879) 
cvs.texi(,11880) @item -n
cvs.texi(,11881) No execution of tag program.  See @ref{Common options}.
cvs.texi(,11882) 
cvs.texi(,11883) @item -R
cvs.texi(,11884) Operate recursively (default).  @xref{Recursive
cvs.texi(,11885) behavior}.
cvs.texi(,11886) 
cvs.texi(,11887) @item -r @var{rev}
cvs.texi(,11888) Tag existing tag @var{rev}.  See @ref{Tagging by date/tag}.
cvs.texi(,11889) @end table
cvs.texi(,11890) 
cvs.texi(,11891) @c ------------------------------------------------------------
cvs.texi(,11892) @item server
cvs.texi(,11893) Rsh server.  See @ref{Connecting via rsh}.
cvs.texi(,11894) 
cvs.texi(,11895) @c ------------------------------------------------------------
cvs.texi(,11896) @item status [@var{options}] @var{files}@dots{}
cvs.texi(,11897) Display status information in a working directory.  See
cvs.texi(,11898) @ref{File status}.
cvs.texi(,11899) 
cvs.texi(,11900) @table @code
cvs.texi(,11901) @item -l
cvs.texi(,11902) Local; run only in current working directory.  See @ref{Recursive behavior}.
cvs.texi(,11903) 
cvs.texi(,11904) @item -R
cvs.texi(,11905) Operate recursively (default).  @xref{Recursive
cvs.texi(,11906) behavior}.
cvs.texi(,11907) 
cvs.texi(,11908) @item -v
cvs.texi(,11909) Include tag information for file.  See @ref{Tags}.
cvs.texi(,11910) @end table
cvs.texi(,11911) 
cvs.texi(,11912) @c ------------------------------------------------------------
cvs.texi(,11913) @item tag [@var{options}] @var{tag} [@var{files}@dots{}]
cvs.texi(,11914) Add a symbolic tag to checked out version of files.
cvs.texi(,11915) See @ref{Revisions} and @ref{Branching and merging}.
cvs.texi(,11916) 
cvs.texi(,11917) @table @code
cvs.texi(,11918) @item -b
cvs.texi(,11919) Create a branch named @var{tag}.  See @ref{Branching and merging}.
cvs.texi(,11920) 
cvs.texi(,11921) @item -c
cvs.texi(,11922) Check that working files are unmodified.  See
cvs.texi(,11923) @ref{Tagging the working directory}.
cvs.texi(,11924) 
cvs.texi(,11925) @item -D @var{date}
cvs.texi(,11926) Tag revisions as of @var{date}.  See @ref{Tagging by date/tag}.
cvs.texi(,11927) 
cvs.texi(,11928) @item -d
cvs.texi(,11929) Delete @var{tag}.  See @ref{Modifying tags}.
cvs.texi(,11930) 
cvs.texi(,11931) @item -F
cvs.texi(,11932) Move @var{tag} if it already exists.  See @ref{Modifying tags}.
cvs.texi(,11933) 
cvs.texi(,11934) @item -f
cvs.texi(,11935) Force a head revision match if tag/date not found.
cvs.texi(,11936) See @ref{Tagging by date/tag}.
cvs.texi(,11937) 
cvs.texi(,11938) @item -l
cvs.texi(,11939) Local; run only in current working directory.  See @ref{Recursive behavior}.
cvs.texi(,11940) 
cvs.texi(,11941) @item -R
cvs.texi(,11942) Operate recursively (default).  @xref{Recursive
cvs.texi(,11943) behavior}.
cvs.texi(,11944) 
cvs.texi(,11945) @item -r @var{rev}
cvs.texi(,11946) Tag existing tag @var{rev}.  See @ref{Tagging by date/tag}.
cvs.texi(,11947) @end table
cvs.texi(,11948) 
cvs.texi(,11949) @c ------------------------------------------------------------
cvs.texi(,11950) @item unedit [@var{options}] [@var{files}@dots{}]
cvs.texi(,11951) Undo an edit command.  See @ref{Editing files}.
cvs.texi(,11952) 
cvs.texi(,11953) @table @code
cvs.texi(,11954) @item -l
cvs.texi(,11955) Local; run only in current working directory.  See @ref{Recursive behavior}.
cvs.texi(,11956) 
cvs.texi(,11957) @item -R
cvs.texi(,11958) Operate recursively (default).  @xref{Recursive behavior}.
cvs.texi(,11959) @end table
cvs.texi(,11960) 
cvs.texi(,11961) @c ------------------------------------------------------------
cvs.texi(,11962) @item update [@var{options}] [@var{files}@dots{}]
cvs.texi(,11963) Bring work tree in sync with repository.  See
cvs.texi(,11964) @ref{update}.
cvs.texi(,11965) 
cvs.texi(,11966) @table @code
cvs.texi(,11967) @item -A
cvs.texi(,11968) Reset any sticky tags/date/options.  See @ref{Sticky
cvs.texi(,11969) tags} and @ref{Keyword substitution}.
cvs.texi(,11970) 
cvs.texi(,11971) @item -C
cvs.texi(,11972) Overwrite locally modified files with clean copies from
cvs.texi(,11973) the repository (the modified file is saved in
cvs.texi(,11974) @file{.#@var{file}.@var{revision}}, however).
cvs.texi(,11975) 
cvs.texi(,11976) @item -D @var{date}
cvs.texi(,11977) Check out revisions as of @var{date} (is sticky).  See
cvs.texi(,11978) @ref{Common options}.
cvs.texi(,11979) 
cvs.texi(,11980) @item -d
cvs.texi(,11981) Create directories.  See @ref{update options}.
cvs.texi(,11982) 
cvs.texi(,11983) @item -f
cvs.texi(,11984) Use head revision if tag/date not found.  See
cvs.texi(,11985) @ref{Common options}.
cvs.texi(,11986) 
cvs.texi(,11987) @item -I @var{ign}
cvs.texi(,11988) More files to ignore (! to reset).  See
cvs.texi(,11989) @ref{import options}.
cvs.texi(,11990) 
cvs.texi(,11991) @c Probably want to use rev1/rev2 style like for diff
cvs.texi(,11992) @c -r.  Here and in on-line help.
cvs.texi(,11993) @item -j @var{rev}
cvs.texi(,11994) Merge in changes.  See @ref{update options}.
cvs.texi(,11995) 
cvs.texi(,11996) @item -k @var{kflag}
cvs.texi(,11997) Use @var{kflag} keyword expansion.  See
cvs.texi(,11998) @ref{Substitution modes}.
cvs.texi(,11999) 
cvs.texi(,12000) @item -l
cvs.texi(,12001) Local; run only in current working directory.  @xref{Recursive behavior}.
cvs.texi(,12002) 
cvs.texi(,12003) @item -P
cvs.texi(,12004) Prune empty directories.  See @ref{Moving directories}.
cvs.texi(,12005) 
cvs.texi(,12006) @item -p
cvs.texi(,12007) Check out files to standard output (avoids
cvs.texi(,12008) stickiness).  See @ref{update options}.
cvs.texi(,12009) 
cvs.texi(,12010) @item -R
cvs.texi(,12011) Operate recursively (default).  @xref{Recursive
cvs.texi(,12012) behavior}.
cvs.texi(,12013) 
cvs.texi(,12014) @item -r @var{tag}
cvs.texi(,12015) Checkout revision @var{tag} (is sticky).  See @ref{Common options}.
cvs.texi(,12016) 
cvs.texi(,12017) @item -W @var{spec}
cvs.texi(,12018) More wrappers.  See @ref{import options}.
cvs.texi(,12019) @end table
cvs.texi(,12020) 
cvs.texi(,12021) @c ------------------------------------------------------------
cvs.texi(,12022) @item version
cvs.texi(,12023) @cindex version (subcommand)
cvs.texi(,12024) 
cvs.texi(,12025) Display the version of @sc{cvs} being used.  If the repository
cvs.texi(,12026) is remote, display both the client and server versions.
cvs.texi(,12027) 
cvs.texi(,12028) @c ------------------------------------------------------------
cvs.texi(,12029) @item watch [on|off|add|remove] [@var{options}] [@var{files}@dots{}]
cvs.texi(,12030) 
cvs.texi(,12031) on/off: turn on/off read-only checkouts of files.  See
cvs.texi(,12032) @ref{Setting a watch}.
cvs.texi(,12033) 
cvs.texi(,12034) add/remove: add or remove notification on actions.  See
cvs.texi(,12035) @ref{Getting Notified}.
cvs.texi(,12036) 
cvs.texi(,12037) @table @code
cvs.texi(,12038) @item -a @var{actions}
cvs.texi(,12039) Specify actions for temporary watch, where
cvs.texi(,12040) @var{actions} is @code{edit}, @code{unedit},
cvs.texi(,12041) @code{commit}, @code{all}, or @code{none}.  See
cvs.texi(,12042) @ref{Editing files}.
cvs.texi(,12043) 
cvs.texi(,12044) @item -l
cvs.texi(,12045) Local; run only in current working directory.  See @ref{Recursive behavior}.
cvs.texi(,12046) 
cvs.texi(,12047) @item -R
cvs.texi(,12048) Operate recursively (default).  @xref{Recursive
cvs.texi(,12049) behavior}.
cvs.texi(,12050) @end table
cvs.texi(,12051) 
cvs.texi(,12052) @c ------------------------------------------------------------
cvs.texi(,12053) @item watchers [@var{options}] [@var{files}@dots{}]
cvs.texi(,12054) See who is watching a file.  See @ref{Watch information}.
cvs.texi(,12055) 
cvs.texi(,12056) @table @code
cvs.texi(,12057) @item -l
cvs.texi(,12058) Local; run only in current working directory.  See @ref{Recursive behavior}.
cvs.texi(,12059) 
cvs.texi(,12060) @item -R
cvs.texi(,12061) Operate recursively (default).  @xref{Recursive
cvs.texi(,12062) behavior}.
cvs.texi(,12063) @end table
cvs.texi(,12064) 
cvs.texi(,12065) @end table
cvs.texi(,12066) 
cvs.texi(,12067) @c ---------------------------------------------------------------------
cvs.texi(,12068) @node Administrative files
cvs.texi(,12069) @appendix Reference manual for Administrative files
cvs.texi(,12070) @cindex Administrative files (reference)
cvs.texi(,12071) @cindex Files, reference manual
cvs.texi(,12072) @cindex Reference manual (files)
cvs.texi(,12073) @cindex CVSROOT (file)
cvs.texi(,12074) 
cvs.texi(,12075) @c FIXME?  Somewhere there needs to be a more "how-to"
cvs.texi(,12076) @c guide to writing these.  I think the triggers
cvs.texi(,12077) @c (commitinfo, loginfo, taginfo, &c) are perhaps a
cvs.texi(,12078) @c different case than files like modules.  One
cvs.texi(,12079) @c particular issue that people sometimes are
cvs.texi(,12080) @c (unnecessarily?) worried about is performance, and
cvs.texi(,12081) @c the impact of writing in perl or sh or ____.
cvs.texi(,12082) Inside the repository, in the directory
cvs.texi(,12083) @file{$CVSROOT/CVSROOT}, there are a number of
cvs.texi(,12084) supportive files for @sc{cvs}.  You can use @sc{cvs} in a limited
cvs.texi(,12085) fashion without any of them, but if they are set up
cvs.texi(,12086) properly they can help make life easier.  For a
cvs.texi(,12087) discussion of how to edit them, see @ref{Intro
cvs.texi(,12088) administrative files}.
cvs.texi(,12089) 
cvs.texi(,12090) The most important of these files is the @file{modules}
cvs.texi(,12091) file, which defines the modules inside the repository.
cvs.texi(,12092) 
cvs.texi(,12093) @menu
cvs.texi(,12094) * modules::                     Defining modules
cvs.texi(,12095) * Wrappers::                    Specify binary-ness based on file name
cvs.texi(,12096) * commit files::                The commit support files (commitinfo,
cvs.texi(,12097)                                 verifymsg, editinfo, loginfo)
cvs.texi(,12098) * rcsinfo::                     Templates for the log messages
cvs.texi(,12099) * cvsignore::                   Ignoring files via cvsignore
cvs.texi(,12100) * checkoutlist::                Adding your own administrative files
cvs.texi(,12101) * history file::                History information
cvs.texi(,12102) * Variables::                   Various variables are expanded
cvs.texi(,12103) * config::                      Miscellaneous CVS configuration
cvs.texi(,12104) @end menu
cvs.texi(,12105) 
cvs.texi(,12106) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,12107) @node modules
cvs.texi(,12108) @appendixsec The modules file
cvs.texi(,12109) @cindex Modules (admin file)
cvs.texi(,12110) @cindex Defining modules (reference manual)
cvs.texi(,12111) 
cvs.texi(,12112) The @file{modules} file records your definitions of
cvs.texi(,12113) names for collections of source code.  @sc{cvs} will
cvs.texi(,12114) use these definitions if you use @sc{cvs} to update the
cvs.texi(,12115) modules file (use normal commands like @code{add},
cvs.texi(,12116) @code{commit}, etc).
cvs.texi(,12117) 
cvs.texi(,12118) The @file{modules} file may contain blank lines and
cvs.texi(,12119) comments (lines beginning with @samp{#}) as well as
cvs.texi(,12120) module definitions.  Long lines can be continued on the
cvs.texi(,12121) next line by specifying a backslash (@samp{\}) as the
cvs.texi(,12122) last character on the line.
cvs.texi(,12123) 
cvs.texi(,12124) There are three basic types of modules: alias modules,
cvs.texi(,12125) regular modules, and ampersand modules.  The difference
cvs.texi(,12126) between them is the way that they map files in the
cvs.texi(,12127) repository to files in the working directory.  In all
cvs.texi(,12128) of the following examples, the top-level repository
cvs.texi(,12129) contains a directory called @file{first-dir}, which
cvs.texi(,12130) contains two files, @file{file1} and @file{file2}, and a
cvs.texi(,12131) directory @file{sdir}.  @file{first-dir/sdir} contains
cvs.texi(,12132) a file @file{sfile}.
cvs.texi(,12133) 
cvs.texi(,12134) @c FIXME: should test all the examples in this section.
cvs.texi(,12135) 
cvs.texi(,12136) @menu
cvs.texi(,12137) * Alias modules::             The simplest kind of module
cvs.texi(,12138) * Regular modules::
cvs.texi(,12139) * Ampersand modules::
cvs.texi(,12140) * Excluding directories::     Excluding directories from a module
cvs.texi(,12141) * Module options::            Regular and ampersand modules can take options
cvs.texi(,12142) * Module program options::    How the modules ``program options'' programs
cvs.texi(,12143)                               are run. 
cvs.texi(,12144) @end menu
cvs.texi(,12145) 
cvs.texi(,12146) @node Alias modules
cvs.texi(,12147) @appendixsubsec Alias modules
cvs.texi(,12148) @cindex Alias modules
cvs.texi(,12149) @cindex -a, in modules file
cvs.texi(,12150) 
cvs.texi(,12151) Alias modules are the simplest kind of module:
cvs.texi(,12152) 
cvs.texi(,12153) @table @code
cvs.texi(,12154) @item @var{mname} -a @var{aliases}@dots{}
cvs.texi(,12155) This represents the simplest way of defining a module
cvs.texi(,12156) @var{mname}.  The @samp{-a} flags the definition as a
cvs.texi(,12157) simple alias: @sc{cvs} will treat any use of @var{mname} (as
cvs.texi(,12158) a command argument) as if the list of names
cvs.texi(,12159) @var{aliases} had been specified instead.
cvs.texi(,12160) @var{aliases} may contain either other module names or
cvs.texi(,12161) paths.  When you use paths in aliases, @code{checkout}
cvs.texi(,12162) creates all intermediate directories in the working
cvs.texi(,12163) directory, just as if the path had been specified
cvs.texi(,12164) explicitly in the @sc{cvs} arguments.
cvs.texi(,12165) @end table
cvs.texi(,12166) 
cvs.texi(,12167) For example, if the modules file contains:
cvs.texi(,12168) 
cvs.texi(,12169) @example
cvs.texi(,12170) amodule -a first-dir
cvs.texi(,12171) @end example
cvs.texi(,12172) 
cvs.texi(,12173) @noindent
cvs.texi(,12174) then the following two commands are equivalent:
cvs.texi(,12175) 
cvs.texi(,12176) @example
cvs.texi(,12177) $ cvs co amodule
cvs.texi(,12178) $ cvs co first-dir
cvs.texi(,12179) @end example
cvs.texi(,12180) 
cvs.texi(,12181) @noindent
cvs.texi(,12182) and they each would provide output such as:
cvs.texi(,12183) 
cvs.texi(,12184) @example
cvs.texi(,12185) cvs checkout: Updating first-dir
cvs.texi(,12186) U first-dir/file1
cvs.texi(,12187) U first-dir/file2
cvs.texi(,12188) cvs checkout: Updating first-dir/sdir
cvs.texi(,12189) U first-dir/sdir/sfile
cvs.texi(,12190) @end example
cvs.texi(,12191) 
cvs.texi(,12192) @node Regular modules
cvs.texi(,12193) @appendixsubsec Regular modules
cvs.texi(,12194) @cindex Regular modules
cvs.texi(,12195) 
cvs.texi(,12196) @table @code
cvs.texi(,12197) @item @var{mname} [ options ] @var{dir} [ @var{files}@dots{} ]
cvs.texi(,12198) In the simplest case, this form of module definition
cvs.texi(,12199) reduces to @samp{@var{mname} @var{dir}}.  This defines
cvs.texi(,12200) all the files in directory @var{dir} as module mname.
cvs.texi(,12201) @var{dir} is a relative path (from @code{$CVSROOT}) to a
cvs.texi(,12202) directory of source in the source repository.  In this
cvs.texi(,12203) case, on checkout, a single directory called
cvs.texi(,12204) @var{mname} is created as a working directory; no
cvs.texi(,12205) intermediate directory levels are used by default, even
cvs.texi(,12206) if @var{dir} was a path involving several directory
cvs.texi(,12207) levels.
cvs.texi(,12208) @end table
cvs.texi(,12209) 
cvs.texi(,12210) For example, if a module is defined by:
cvs.texi(,12211) 
cvs.texi(,12212) @example
cvs.texi(,12213) regmodule first-dir
cvs.texi(,12214) @end example
cvs.texi(,12215) 
cvs.texi(,12216) @noindent
cvs.texi(,12217) then regmodule will contain the files from first-dir:
cvs.texi(,12218) 
cvs.texi(,12219) @example
cvs.texi(,12220) $ cvs co regmodule
cvs.texi(,12221) cvs checkout: Updating regmodule
cvs.texi(,12222) U regmodule/file1
cvs.texi(,12223) U regmodule/file2
cvs.texi(,12224) cvs checkout: Updating regmodule/sdir
cvs.texi(,12225) U regmodule/sdir/sfile
cvs.texi(,12226) $
cvs.texi(,12227) @end example
cvs.texi(,12228) 
cvs.texi(,12229) By explicitly specifying files in the module definition
cvs.texi(,12230) after @var{dir}, you can select particular files from
cvs.texi(,12231) directory @var{dir}.  Here is
cvs.texi(,12232) an example:
cvs.texi(,12233) 
cvs.texi(,12234) @example
cvs.texi(,12235) regfiles first-dir/sdir sfile
cvs.texi(,12236) @end example
cvs.texi(,12237) 
cvs.texi(,12238) @noindent
cvs.texi(,12239) With this definition, getting the regfiles module
cvs.texi(,12240) will create a single working directory
cvs.texi(,12241) @file{regfiles} containing the file listed, which
cvs.texi(,12242) comes from a directory deeper
cvs.texi(,12243) in the @sc{cvs} source repository:
cvs.texi(,12244) 
cvs.texi(,12245) @example
cvs.texi(,12246) $ cvs co regfiles
cvs.texi(,12247) U regfiles/sfile
cvs.texi(,12248) $
cvs.texi(,12249) @end example
cvs.texi(,12250) 
cvs.texi(,12251) @node Ampersand modules
cvs.texi(,12252) @appendixsubsec Ampersand modules
cvs.texi(,12253) @cindex Ampersand modules
cvs.texi(,12254) @cindex &, in modules file
cvs.texi(,12255) 
cvs.texi(,12256) A module definition can refer to other modules by
cvs.texi(,12257) including @samp{&@var{module}} in its definition.
cvs.texi(,12258) @example
cvs.texi(,12259) @var{mname} [ options ] @var{&module}@dots{}
cvs.texi(,12260) @end example
cvs.texi(,12261) 
cvs.texi(,12262) Then getting the module creates a subdirectory for each such
cvs.texi(,12263) module, in the directory containing the module.  For
cvs.texi(,12264) example, if modules contains
cvs.texi(,12265) 
cvs.texi(,12266) @example
cvs.texi(,12267) ampermod &first-dir
cvs.texi(,12268) @end example
cvs.texi(,12269) 
cvs.texi(,12270) @noindent
cvs.texi(,12271) then a checkout will create an @code{ampermod} directory
cvs.texi(,12272) which contains a directory called @code{first-dir},
cvs.texi(,12273) which in turns contains all the directories and files
cvs.texi(,12274) which live there.  For example, the command
cvs.texi(,12275) 
cvs.texi(,12276) @example
cvs.texi(,12277) $ cvs co ampermod
cvs.texi(,12278) @end example
cvs.texi(,12279) 
cvs.texi(,12280) @noindent
cvs.texi(,12281) will create the following files:
cvs.texi(,12282) 
cvs.texi(,12283) @example
cvs.texi(,12284) ampermod/first-dir/file1
cvs.texi(,12285) ampermod/first-dir/file2
cvs.texi(,12286) ampermod/first-dir/sdir/sfile
cvs.texi(,12287) @end example
cvs.texi(,12288) 
cvs.texi(,12289) There is one quirk/bug: the messages that @sc{cvs}
cvs.texi(,12290) prints omit the @file{ampermod}, and thus do not
cvs.texi(,12291) correctly display the location to which it is checking
cvs.texi(,12292) out the files:
cvs.texi(,12293) 
cvs.texi(,12294) @example
cvs.texi(,12295) $ cvs co ampermod
cvs.texi(,12296) cvs checkout: Updating first-dir
cvs.texi(,12297) U first-dir/file1
cvs.texi(,12298) U first-dir/file2
cvs.texi(,12299) cvs checkout: Updating first-dir/sdir
cvs.texi(,12300) U first-dir/sdir/sfile
cvs.texi(,12301) $
cvs.texi(,12302) @end example
cvs.texi(,12303) 
cvs.texi(,12304) Do not rely on this buggy behavior; it may get fixed in
cvs.texi(,12305) a future release of @sc{cvs}.
cvs.texi(,12306) 
cvs.texi(,12307) @c FIXCVS: What happens if regular and & modules are
cvs.texi(,12308) @c combined, as in "ampermodule first-dir &second-dir"?
cvs.texi(,12309) @c When I tried it, it seemed to just ignore the
cvs.texi(,12310) @c "first-dir".  I think perhaps it should be an error
cvs.texi(,12311) @c (but this needs further investigation).
cvs.texi(,12312) @c In addition to discussing what each one does, we
cvs.texi(,12313) @c should put in a few words about why you would use one or
cvs.texi(,12314) @c the other in various situations.
cvs.texi(,12315) 
cvs.texi(,12316) @node Excluding directories
cvs.texi(,12317) @appendixsubsec Excluding directories
cvs.texi(,12318) @cindex Excluding directories, in modules file
cvs.texi(,12319) @cindex !, in modules file
cvs.texi(,12320) 
cvs.texi(,12321) An alias module may exclude particular directories from
cvs.texi(,12322) other modules by using an exclamation mark (@samp{!})
cvs.texi(,12323) before the name of each directory to be excluded.
cvs.texi(,12324) 
cvs.texi(,12325) For example, if the modules file contains:
cvs.texi(,12326) 
cvs.texi(,12327) @example
cvs.texi(,12328) exmodule -a !first-dir/sdir first-dir
cvs.texi(,12329) @end example
cvs.texi(,12330) 
cvs.texi(,12331) @noindent
cvs.texi(,12332) then checking out the module @samp{exmodule} will check
cvs.texi(,12333) out everything in @samp{first-dir} except any files in
cvs.texi(,12334) the subdirectory @samp{first-dir/sdir}.
cvs.texi(,12335) @c Note that the "!first-dir/sdir" sometimes must be listed
cvs.texi(,12336) @c before "first-dir".  That seems like a probable bug, in which
cvs.texi(,12337) @c case perhaps it should be fixed (to allow either
cvs.texi(,12338) @c order) rather than documented.  See modules4 in testsuite.
cvs.texi(,12339) 
cvs.texi(,12340) @node Module options
cvs.texi(,12341) @appendixsubsec Module options
cvs.texi(,12342) @cindex Options, in modules file
cvs.texi(,12343) 
cvs.texi(,12344) Either regular modules or ampersand modules can contain
cvs.texi(,12345) options, which supply additional information concerning
cvs.texi(,12346) the module.
cvs.texi(,12347) 
cvs.texi(,12348) @table @code
cvs.texi(,12349) @cindex -d, in modules file
cvs.texi(,12350) @item -d @var{name}
cvs.texi(,12351) Name the working directory something other than the
cvs.texi(,12352) module name.
cvs.texi(,12353) @c FIXME: Needs a bunch of examples, analogous to the
cvs.texi(,12354) @c examples for alias, regular, and ampersand modules
cvs.texi(,12355) @c which show where the files go without -d.
cvs.texi(,12356) 
cvs.texi(,12357) @cindex Export program
cvs.texi(,12358) @cindex -e, in modules file
cvs.texi(,12359) @item -e @var{prog}
cvs.texi(,12360) Specify a program @var{prog} to run whenever files in a
cvs.texi(,12361) module are exported.  @var{prog} runs with a single
cvs.texi(,12362) argument, the module name.
cvs.texi(,12363) @c FIXME: Is it run on server? client?
cvs.texi(,12364) 
cvs.texi(,12365) @cindex Checkout program
cvs.texi(,12366) @cindex -o, in modules file
cvs.texi(,12367) @item -o @var{prog}
cvs.texi(,12368) Specify a program @var{prog} to run whenever files in a
cvs.texi(,12369) module are checked out.  @var{prog} runs with a single
cvs.texi(,12370) argument, the module name.  See @ref{Module program options} for
cvs.texi(,12371) information on how @var{prog} is called.
cvs.texi(,12372) @c FIXME: Is it run on server? client?
cvs.texi(,12373) 
cvs.texi(,12374) @cindex Status of a module
cvs.texi(,12375) @cindex Module status
cvs.texi(,12376) @cindex -s, in modules file
cvs.texi(,12377) @item -s @var{status}
cvs.texi(,12378) Assign a status to the module.  When the module file is
cvs.texi(,12379) printed with @samp{cvs checkout -s} the modules are
cvs.texi(,12380) sorted according to primarily module status, and
cvs.texi(,12381) secondarily according to the module name.  This option
cvs.texi(,12382) has no other meaning.  You can use this option for
cvs.texi(,12383) several things besides status: for instance, list the
cvs.texi(,12384) person that is responsible for this module.
cvs.texi(,12385) 
cvs.texi(,12386) @cindex Tag program
cvs.texi(,12387) @cindex -t, in modules file
cvs.texi(,12388) @item -t @var{prog}
cvs.texi(,12389) Specify a program @var{prog} to run whenever files in a
cvs.texi(,12390) module are tagged with @code{rtag}.  @var{prog} runs
cvs.texi(,12391) with two arguments: the module name and the symbolic
cvs.texi(,12392) tag specified to @code{rtag}.  It is not run
cvs.texi(,12393) when @code{tag} is executed.  Generally you will find
cvs.texi(,12394) that taginfo is a better solution (@pxref{user-defined logging}).
cvs.texi(,12395) @c FIXME: Is it run on server? client?
cvs.texi(,12396) @c Problems with -t include:
cvs.texi(,12397) @c * It is run after the tag not before
cvs.texi(,12398) @c * It doesn't get passed all the information that
cvs.texi(,12399) @c   taginfo does ("mov", &c).
cvs.texi(,12400) @c * It only is run for rtag, not tag.
cvs.texi(,12401) @end table
cvs.texi(,12402) 
cvs.texi(,12403) You should also see @pxref{Module program options} about how the
cvs.texi(,12404) ``program options'' programs are run.
cvs.texi(,12405) 
cvs.texi(,12406) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,12407) 
cvs.texi(,12408) @node Module program options
cvs.texi(,12409) @appendixsubsec How the modules file ``program options'' programs are run
cvs.texi(,12410) @cindex Modules file program options
cvs.texi(,12411) @cindex -t, in modules file
cvs.texi(,12412) @cindex -o, in modules file
cvs.texi(,12413) @cindex -e, in modules file
cvs.texi(,12414) 
cvs.texi(,12415) @noindent
cvs.texi(,12416) For checkout, rtag, and export, the program is server-based, and as such the
cvs.texi(,12417) following applies:-
cvs.texi(,12418) 
cvs.texi(,12419) If using remote access methods (pserver, ext, etc.),
cvs.texi(,12420) @sc{cvs} will execute this program on the server from a temporary
cvs.texi(,12421) directory. The path is searched for this program.
cvs.texi(,12422) 
cvs.texi(,12423) If using ``local access'' (on a local or remote NFS file system, i.e.
cvs.texi(,12424) repository set just to a path),
cvs.texi(,12425) the program will be executed from the newly checked-out tree, if
cvs.texi(,12426) found there, or alternatively searched for in the path if not.
cvs.texi(,12427) 
cvs.texi(,12428) The programs are all run after the operation has effectively
cvs.texi(,12429) completed.
cvs.texi(,12430) 
cvs.texi(,12431) 
cvs.texi(,12432) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,12433) @node Wrappers
cvs.texi(,12434) @appendixsec The cvswrappers file
cvs.texi(,12435) @cindex cvswrappers (admin file)
cvs.texi(,12436) @cindex CVSWRAPPERS, environment variable
cvs.texi(,12437) @cindex Wrappers
cvs.texi(,12438) 
cvs.texi(,12439) @c FIXME: need some better way of separating this out
cvs.texi(,12440) @c by functionality.  -m is
cvs.texi(,12441) @c one feature, and -k is a another.  And this discussion
cvs.texi(,12442) @c should be better motivated (e.g. start with the
cvs.texi(,12443) @c problems, then explain how the feature solves it).
cvs.texi(,12444) 
cvs.texi(,12445) Wrappers refers to a @sc{cvs} feature which lets you
cvs.texi(,12446) control certain settings based on the name of the file
cvs.texi(,12447) which is being operated on.  The settings are @samp{-k}
cvs.texi(,12448) for binary files, and @samp{-m} for nonmergeable text
cvs.texi(,12449) files.
cvs.texi(,12450) 
cvs.texi(,12451) The @samp{-m} option
cvs.texi(,12452) specifies the merge methodology that should be used when
cvs.texi(,12453) a non-binary file is updated.  @code{MERGE} means the usual
cvs.texi(,12454) @sc{cvs} behavior: try to merge the files.  @code{COPY}
cvs.texi(,12455) means that @code{cvs update} will refuse to merge
cvs.texi(,12456) files, as it also does for files specified as binary
cvs.texi(,12457) with @samp{-kb} (but if the file is specified as
cvs.texi(,12458) binary, there is no need to specify @samp{-m 'COPY'}).
cvs.texi(,12459) @sc{cvs} will provide the user with the
cvs.texi(,12460) two versions of the files, and require the user using
cvs.texi(,12461) mechanisms outside @sc{cvs}, to insert any necessary
cvs.texi(,12462) changes.
cvs.texi(,12463) 
cvs.texi(,12464) @strong{WARNING: do not use @code{COPY} with
cvs.texi(,12465) @sc{cvs} 1.9 or earlier - such versions of @sc{cvs} will
cvs.texi(,12466) copy one version of your file over the other, wiping
cvs.texi(,12467) out the previous contents.}
cvs.texi(,12468) @c Ordinarily we don't document the behavior of old
cvs.texi(,12469) @c versions.  But this one is so dangerous, I think we
cvs.texi(,12470) @c must.  I almost renamed it to -m 'NOMERGE' so we
cvs.texi(,12471) @c could say "never use -m 'COPY'".
cvs.texi(,12472) The @samp{-m} wrapper option only affects behavior when
cvs.texi(,12473) merging is done on update; it does not affect how files
cvs.texi(,12474) are stored.  See @ref{Binary files}, for more on
cvs.texi(,12475) binary files.
cvs.texi(,12476) 
cvs.texi(,12477) The basic format of the file @file{cvswrappers} is:
cvs.texi(,12478) 
cvs.texi(,12479) @c FIXME: @example is all wrong for this.  Use @deffn or
cvs.texi(,12480) @c something more sensible.
cvs.texi(,12481) @example
cvs.texi(,12482) wildcard     [option value][option value]...
cvs.texi(,12483) 
cvs.texi(,12484) where option is one of
cvs.texi(,12485) -m           update methodology      value: MERGE or COPY
cvs.texi(,12486) -k           keyword expansion       value: expansion mode
cvs.texi(,12487) 
cvs.texi(,12488) and value is a single-quote delimited value.
cvs.texi(,12489) @end example
cvs.texi(,12490) 
cvs.texi(,12552) 
cvs.texi(,12553) @c FIXME: We don't document -W or point to where it is
cvs.texi(,12554) @c documented.  Or .cvswrappers.
cvs.texi(,12555) For example, the following command imports a
cvs.texi(,12556) directory, treating files whose name ends in
cvs.texi(,12557) @samp{.exe} as binary:
cvs.texi(,12558) 
cvs.texi(,12559) @example
cvs.texi(,12560) cvs import -I ! -W "*.exe -k 'b'" first-dir vendortag reltag
cvs.texi(,12561) @end example
cvs.texi(,12562) 
cvs.texi(,12563) @c Another good example, would be storing files
cvs.texi(,12564) @c (e.g. binary files) compressed in the repository.
cvs.texi(,12565) @c 	::::::::::::::::::
cvs.texi(,12566) @c 	cvswrappers
cvs.texi(,12567) @c 	::::::::::::::::::
cvs.texi(,12568) @c 	*.t12 -m 'COPY'
cvs.texi(,12569) @c 	*.t[0-9][0-9] -f 'gunzipcp %s' -t 'gzipcp %s %s' -m 'COPY'
cvs.texi(,12570) @c
cvs.texi(,12571) @c	::::::::::::::::::
cvs.texi(,12572) @c	gunzipcp
cvs.texi(,12573) @c	::::::::::::::::::
cvs.texi(,12574) @c	:
cvs.texi(,12575) @c	[ -f $1 ] || exit 1
cvs.texi(,12576) @c	zcat $1 > /tmp/.#$1.$$
cvs.texi(,12577) @c	mv /tmp/.#$1.$$ $1
cvs.texi(,12578) @c
cvs.texi(,12579) @c	::::::::::::::::::
cvs.texi(,12580) @c	gzipcp
cvs.texi(,12581) @c	::::::::::::::::::
cvs.texi(,12582) @c	:
cvs.texi(,12583) @c	DIRNAME=`echo $1 | sed -e "s|/.*/||g"`
cvs.texi(,12584) @c	if [ ! -d $DIRNAME ] ; then
cvs.texi(,12585) @c	      DIRNAME=`echo $1 | sed -e "s|.*/||g"`
cvs.texi(,12586) @c	fi
cvs.texi(,12587) @c	gzip -c  $DIRNAME  > $2
cvs.texi(,12588) @c One catch--"cvs diff" will not invoke the wrappers
cvs.texi(,12589) @c (probably a CVS bug, although I haven't thought it out).
cvs.texi(,12590) 
cvs.texi(,12591) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,12592) @node commit files
cvs.texi(,12593) @appendixsec The commit support files
cvs.texi(,12594) @cindex Committing, administrative support files
cvs.texi(,12595) 
cvs.texi(,12596) The @samp{-i} flag in the @file{modules} file can be
cvs.texi(,12597) used to run a certain program whenever files are
cvs.texi(,12598) committed (@pxref{modules}).  The files described in
cvs.texi(,12599) this section provide other, more flexible, ways to run
cvs.texi(,12600) programs whenever something is committed.
cvs.texi(,12601) 
cvs.texi(,12602) There are three kind of programs that can be run on
cvs.texi(,12603) commit.  They are specified in files in the repository,
cvs.texi(,12604) as described below.  The following table summarizes the
cvs.texi(,12605) file names and the purpose of the corresponding
cvs.texi(,12606) programs.
cvs.texi(,12607) 
cvs.texi(,12608) @table @file
cvs.texi(,12609) @item commitinfo
cvs.texi(,12610) The program is responsible for checking that the commit
cvs.texi(,12611) is allowed.  If it exits with a non-zero exit status
cvs.texi(,12612) the commit will be aborted.
cvs.texi(,12613) 
cvs.texi(,12614) @item verifymsg
cvs.texi(,12615) The specified program is used to evaluate the log message,
cvs.texi(,12616) and possibly verify that it contains all required
cvs.texi(,12617) fields.  This is most useful in combination with the
cvs.texi(,12618) @file{rcsinfo} file, which can hold a log message
cvs.texi(,12619) template (@pxref{rcsinfo}).
cvs.texi(,12620) 
cvs.texi(,12621) @item editinfo
cvs.texi(,12622) The specified program is used to edit the log message,
cvs.texi(,12623) and possibly verify that it contains all required
cvs.texi(,12624) fields.  This is most useful in combination with the
cvs.texi(,12625) @file{rcsinfo} file, which can hold a log message
cvs.texi(,12626) template (@pxref{rcsinfo}).  (obsolete)
cvs.texi(,12627) 
cvs.texi(,12628) @item loginfo
cvs.texi(,12629) The specified program is called when the commit is
cvs.texi(,12630) complete.  It receives the log message and some
cvs.texi(,12631) additional information and can store the log message in
cvs.texi(,12632) a file, or mail it to appropriate persons, or maybe
cvs.texi(,12633) post it to a local newsgroup, or@dots{}  Your
cvs.texi(,12634) imagination is the limit!
cvs.texi(,12635) @end table
cvs.texi(,12636) 
cvs.texi(,12637) @menu
cvs.texi(,12638) * syntax::                      The common syntax
cvs.texi(,12639) * commitinfo::                  Pre-commit checking
cvs.texi(,12640) * verifymsg::                   How are log messages evaluated?
cvs.texi(,12641) * editinfo::                    Specifying how log messages are created
cvs.texi(,12642)                                 (obsolete)
cvs.texi(,12643) * loginfo::                     Where should log messages be sent?
cvs.texi(,12644) @end menu
cvs.texi(,12645) 
cvs.texi(,12646) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,12647) @node syntax
cvs.texi(,12648) @appendixsubsec The common syntax
cvs.texi(,12649) @cindex Info files (syntax)
cvs.texi(,12650) @cindex Syntax of info files
cvs.texi(,12651) @cindex Common syntax of info files
cvs.texi(,12652) 
cvs.texi(,12653) @c FIXME: having this so totally separate from the
cvs.texi(,12654) @c Variables node is rather bogus.
cvs.texi(,12655) 
cvs.texi(,12656) The administrative files such as @file{commitinfo},
cvs.texi(,12657) @file{loginfo}, @file{rcsinfo}, @file{verifymsg}, etc.,
cvs.texi(,12658) all have a common format.  The purpose of the files are
cvs.texi(,12659) described later on.  The common syntax is described
cvs.texi(,12660) here.
cvs.texi(,12661) 
cvs.texi(,12662) @cindex Regular expression syntax
cvs.texi(,12663) Each line contains the following:
cvs.texi(,12664) @itemize @bullet
cvs.texi(,12665) @item
cvs.texi(,12666) @c Say anything about DEFAULT and ALL?  Right now we
cvs.texi(,12667) @c leave that to the description of each file (and in fact
cvs.texi(,12668) @c the practice is inconsistent which is really annoying).
cvs.texi(,12669) A regular expression.  This is a basic regular
cvs.texi(,12670) expression in the syntax used by GNU emacs.
cvs.texi(,12671) @c FIXME: What we probably should be saying is "POSIX Basic
cvs.texi(,12672) @c Regular Expression with the following extensions (`\('
cvs.texi(,12673) @c `\|' '+' etc)"
cvs.texi(,12674) @c rather than define it with reference to emacs.
cvs.texi(,12675) @c The reference to emacs is not strictly speaking
cvs.texi(,12676) @c true, as we don't support \=, \s, or \S.  Also it isn't
cvs.texi(,12677) @c clear we should document and/or promise to continue to
cvs.texi(,12678) @c support all the obscure emacs extensions like \<.
cvs.texi(,12679) @c Also need to better cite (or include) full
cvs.texi(,12680) @c documentation for the syntax.
cvs.texi(,12681) @c Also see comment in configure.in about what happens to the
cvs.texi(,12682) @c syntax if we pick up a system-supplied regexp matcher.
cvs.texi(,12683) 
cvs.texi(,12684) @item
cvs.texi(,12685) A whitespace separator---one or more spaces and/or tabs.
cvs.texi(,12686) 
cvs.texi(,12687) @item
cvs.texi(,12688) A file name or command-line template.
cvs.texi(,12689) @end itemize
cvs.texi(,12690) 
cvs.texi(,12691) @noindent
cvs.texi(,12692) Blank lines are ignored.  Lines that start with the
cvs.texi(,12693) character @samp{#} are treated as comments.  Long lines
cvs.texi(,12694) unfortunately can @emph{not} be broken in two parts in
cvs.texi(,12695) any way.
cvs.texi(,12696) 
cvs.texi(,12697) The first regular expression that matches the current
cvs.texi(,12698) directory name in the repository is used.  The rest of the line
cvs.texi(,12699) is used as a file name or command-line as appropriate.
cvs.texi(,12700) 
cvs.texi(,12701) @c FIXME: need an example.  In particular, show what
cvs.texi(,12702) @c the regular expression is matched against (one
cvs.texi(,12703) @c ordinarily clueful person got confused about whether it
cvs.texi(,12704) @c includes the filename--"directory name" above should be
cvs.texi(,12705) @c unambiguous but there is nothing like an example to
cvs.texi(,12706) @c confirm people's understanding of this sort of thing).
cvs.texi(,12707) 
cvs.texi(,12708) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,12709) @node commitinfo
cvs.texi(,12710) @appendixsubsec Commitinfo
cvs.texi(,12711) @cindex @file{commitinfo}
cvs.texi(,12712) @cindex Commits, precommit verification of
cvs.texi(,12713) @cindex Precommit checking
cvs.texi(,12714) 
cvs.texi(,12715) The @file{commitinfo} file defines programs to execute
cvs.texi(,12716) whenever @samp{cvs commit} is about to execute.  These
cvs.texi(,12717) programs are used for pre-commit checking to verify
cvs.texi(,12718) that the modified, added and removed files are really
cvs.texi(,12719) ready to be committed.  This could be used, for
cvs.texi(,12720) instance, to verify that the changed files conform to
cvs.texi(,12721) to your site's standards for coding practice.
cvs.texi(,12722) 
cvs.texi(,12723) As mentioned earlier, each line in the
cvs.texi(,12724) @file{commitinfo} file consists of a regular expression
cvs.texi(,12725) and a command-line template.  The template can include
cvs.texi(,12726) a program name and any number of arguments you wish to
cvs.texi(,12727) supply to it.  The full path to the current source
cvs.texi(,12728) repository is appended to the template, followed by the
cvs.texi(,12729) file names of any files involved in the commit (added,
cvs.texi(,12730) removed, and modified files).
cvs.texi(,12731) 
cvs.texi(,12732) @cindex Exit status, of commitinfo
cvs.texi(,12733) The first line with a regular expression matching the
cvs.texi(,12734) directory within the repository will be used.  If the
cvs.texi(,12735) command returns a non-zero exit status the commit will
cvs.texi(,12736) be aborted.
cvs.texi(,12737) @c FIXME: need example(s) of what "directory within the
cvs.texi(,12738) @c repository" means.
cvs.texi(,12739) 
cvs.texi(,12740) @cindex DEFAULT in commitinfo
cvs.texi(,12741) If the repository name does not match any of the
cvs.texi(,12742) regular expressions in this file, the @samp{DEFAULT}
cvs.texi(,12743) line is used, if it is specified.
cvs.texi(,12744) 
cvs.texi(,12745) @cindex ALL in commitinfo
cvs.texi(,12746) All occurrences of the name @samp{ALL} appearing as a
cvs.texi(,12747) regular expression are used in addition to the first
cvs.texi(,12748) matching regular expression or the name @samp{DEFAULT}.
cvs.texi(,12749) 
cvs.texi(,12750) @cindex @file{commitinfo}, working directory
cvs.texi(,12751) @cindex @file{commitinfo}, command environment
cvs.texi(,12752) The command will be run in the root of the workspace
cvs.texi(,12753) containing the new versions of any files the user would like
cvs.texi(,12754) to modify (commit), @emph{or in a copy of the workspace on
cvs.texi(,12755) the server (@pxref{Remote repositories})}.  If a file is
cvs.texi(,12756) being removed, there will be no copy of the file under the
cvs.texi(,12757) current directory.  If a file is being added, there will be
cvs.texi(,12758) no corresponding archive file in the repository unless the
cvs.texi(,12759) file is being resurrected.
cvs.texi(,12760) 
cvs.texi(,12761) Note that both the repository directory and the corresponding
cvs.texi(,12762) Attic (@pxref{Attic}) directory may need to be checked to
cvs.texi(,12763) locate the archive file corresponding to any given file being
cvs.texi(,12764) committed.  Much of the information about the specific commit
cvs.texi(,12765) request being made, including the destination branch, commit
cvs.texi(,12766) message, and command line options specified, is not available
cvs.texi(,12767) to the command.
cvs.texi(,12768) 
cvs.texi(,12769) @c FIXME: should discuss using commitinfo to control
cvs.texi(,12770) @c who has checkin access to what (e.g. Joe can check into
cvs.texi(,12771) @c directories a, b, and c, and Mary can check into
cvs.texi(,12772) @c directories b, c, and d--note this case cannot be
cvs.texi(,12773) @c conveniently handled with unix groups).  Of course,
cvs.texi(,12774) @c adding a new set of features to CVS might be a more
cvs.texi(,12775) @c natural way to fix this problem than telling people to
cvs.texi(,12776) @c use commitinfo.
cvs.texi(,12777) @c FIXME: Should make some reference, especially in
cvs.texi(,12778) @c the context of controlling who has access, to the fact
cvs.texi(,12779) @c that commitinfo can be circumvented.  Perhaps
cvs.texi(,12780) @c mention SETXID (but has it been carefully examined
cvs.texi(,12781) @c for holes?).  This fits in with the discussion of
cvs.texi(,12782) @c general CVS security in "Password authentication
cvs.texi(,12783) @c security" (the bit which is not pserver-specific).
cvs.texi(,12784) 
cvs.texi(,12785) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,12786) @node verifymsg
cvs.texi(,12787) @appendixsubsec Verifying log messages
cvs.texi(,12788) @cindex @file{verifymsg} (admin file)
cvs.texi(,12789) @cindex Log message, verifying
cvs.texi(,12790) 
cvs.texi(,12791) Once you have entered a log message, you can evaluate
cvs.texi(,12792) that message to check for specific content, such as
cvs.texi(,12793) a bug ID.  Use the @file{verifymsg} file to
cvs.texi(,12794) specify a program that is used to verify the log message.
cvs.texi(,12795) This program could be a simple script that checks
cvs.texi(,12796) that the entered message contains the required fields.
cvs.texi(,12797) 
cvs.texi(,12798) The @file{verifymsg} file is often most useful together
cvs.texi(,12799) with the @file{rcsinfo} file, which can be used to
cvs.texi(,12800) specify a log message template.
cvs.texi(,12801) 
cvs.texi(,12802) Each line in the @file{verifymsg} file consists of a
cvs.texi(,12803) regular expression and a command-line template.  The
cvs.texi(,12804) template must include a program name, and can include
cvs.texi(,12805) any number of arguments.  The full path to the current
cvs.texi(,12806) log message template file is appended to the template.
cvs.texi(,12807) 
cvs.texi(,12808) One thing that should be noted is that the @samp{ALL}
cvs.texi(,12809) keyword is not supported.  If more than one matching
cvs.texi(,12810) line is found, the first one is used.  This can be
cvs.texi(,12811) useful for specifying a default verification script in a
cvs.texi(,12812) directory, and then overriding it in a subdirectory.
cvs.texi(,12813) 
cvs.texi(,12814) @cindex DEFAULT in @file{verifymsg}
cvs.texi(,12815) If the repository name does not match any of the
cvs.texi(,12816) regular expressions in this file, the @samp{DEFAULT}
cvs.texi(,12817) line is used, if it is specified.
cvs.texi(,12818) 
cvs.texi(,12819) @cindex Exit status, of @file{verifymsg}
cvs.texi(,12820) If the verification script exits with a non-zero exit status,
cvs.texi(,12821) the commit is aborted.
cvs.texi(,12822) 
cvs.texi(,12823) @cindex @file{verifymsg}, changing the log message
cvs.texi(,12824) In the default configuration, CVS allows the
cvs.texi(,12825) verification script to change the log message. This is
cvs.texi(,12826) controlled via the RereadLogAfterVerify CVSROOT/config
cvs.texi(,12827) option.
cvs.texi(,12828) 
cvs.texi(,12829) When @samp{RereadLogAfterVerify=always} or
cvs.texi(,12830) @samp{RereadLogAfterVerify=stat}, the log message will
cvs.texi(,12831) either always be reread after the verification script
cvs.texi(,12832) is run or reread only if the log message file status
cvs.texi(,12833) has changed.
cvs.texi(,12834) 
cvs.texi(,12835) @xref{config}, for more on CVSROOT/config options.
cvs.texi(,12836) 
cvs.texi(,12837) It is NOT a good idea for a @file{verifymsg} script to
cvs.texi(,12838) interact directly with the user in the various
cvs.texi(,12839) client/server methods. For the @code{pserver} method,
cvs.texi(,12840) there is no protocol support for communicating between
cvs.texi(,12841) @file{verifymsg} and the client on the remote end. For the
cvs.texi(,12842) @code{ext} and @code{server} methods, it is possible
cvs.texi(,12843) for CVS to become confused by the characters going
cvs.texi(,12844) along the same channel as the CVS protocol
cvs.texi(,12845) messages. See @ref{Remote repositories}, for more
cvs.texi(,12846) information on client/server setups.  In addition, at the time
cvs.texi(,12847) the @file{verifymsg} script runs, the CVS
cvs.texi(,12848) server has locks in place in the repository.  If control is
cvs.texi(,12849) returned to the user here then other users may be stuck waiting
cvs.texi(,12850) for access to the repository.
cvs.texi(,12851) 
cvs.texi(,12852) This option can be useful if you find yourself using an
cvs.texi(,12853) rcstemplate that needs to be modified to remove empty
cvs.texi(,12854) elements or to fill in default values.  It can also be
cvs.texi(,12855) useful if the rcstemplate has changed in the repository
cvs.texi(,12856) and the CVS/Template was not updated, but is able to be
cvs.texi(,12857) adapted to the new format by the verification script
cvs.texi(,12858) that is run by @file{verifymsg}.
cvs.texi(,12859) 
cvs.texi(,12860) An example of an update might be to change all
cvs.texi(,12861) occurrences of 'BugId:' to be 'DefectId:' (which can be
cvs.texi(,12862) useful if the rcstemplate has recently been changed and
cvs.texi(,12863) there are still checked-out user trees with cached
cvs.texi(,12864) copies in the CVS/Template file of the older version).
cvs.texi(,12865) 
cvs.texi(,12866) Another example of an update might be to delete a line
cvs.texi(,12867) that contains 'BugID: none' from the log message after
cvs.texi(,12868) validation of that value as being allowed is made.
cvs.texi(,12869) 
cvs.texi(,12870) The following is a little silly example of a
cvs.texi(,12871) @file{verifymsg} file, together with the corresponding
cvs.texi(,12872) @file{rcsinfo} file, the log message template and an
cvs.texi(,12873) verification  script.  We begin with the log message template.
cvs.texi(,12874) We want to always record a bug-id number on the first
cvs.texi(,12875) line of the log message.  The rest of log message is
cvs.texi(,12876) free text.  The following template is found in the file
cvs.texi(,12877) @file{/usr/cvssupport/tc.template}.
cvs.texi(,12878) 
cvs.texi(,12879) @example
cvs.texi(,12880) BugId:
cvs.texi(,12881) @end example
cvs.texi(,12882) 
cvs.texi(,12883) The script @file{/usr/cvssupport/bugid.verify} is used to
cvs.texi(,12884) evaluate the log message.
cvs.texi(,12885) 
cvs.texi(,12886) @example
cvs.texi(,12887) #!/bin/sh
cvs.texi(,12888) #
cvs.texi(,12889) #       bugid.verify filename
cvs.texi(,12890) #
cvs.texi(,12891) #  Verify that the log message contains a valid bugid
cvs.texi(,12892) #  on the first line.
cvs.texi(,12893) #
cvs.texi(,12894) if head -1 < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then
cvs.texi(,12895)     exit 0
cvs.texi(,12896) elif head -1 < $1 | grep '^BugId:[ ]*none$' > /dev/null; then
cvs.texi(,12897)     # It is okay to allow commits with 'BugId: none',
cvs.texi(,12898)     # but do not put that text into the real log message.
cvs.texi(,12899)     grep -v '^BugId:[ ]*none$' > $1.rewrite
cvs.texi(,12900)     mv $1.rewrite $1
cvs.texi(,12901)     exit 0
cvs.texi(,12902) else
cvs.texi(,12903)     echo "No BugId found."
cvs.texi(,12904)     exit 1
cvs.texi(,12905) fi
cvs.texi(,12906) @end example
cvs.texi(,12907) 
cvs.texi(,12908) The @file{verifymsg} file contains this line:
cvs.texi(,12909) 
cvs.texi(,12910) @example
cvs.texi(,12911) ^tc     /usr/cvssupport/bugid.verify
cvs.texi(,12912) @end example
cvs.texi(,12913) 
cvs.texi(,12914) The @file{rcsinfo} file contains this line:
cvs.texi(,12915) 
cvs.texi(,12916) @example
cvs.texi(,12917) ^tc     /usr/cvssupport/tc.template
cvs.texi(,12918) @end example
cvs.texi(,12919) 
cvs.texi(,12920) The @file{config} file contains this line:
cvs.texi(,12921) 
cvs.texi(,12922) @example
cvs.texi(,12923) RereadLogAfterVerify=always
cvs.texi(,12924) @end example
cvs.texi(,12925) 
cvs.texi(,12926) 
cvs.texi(,12927) 
cvs.texi(,12928) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,12929) @node editinfo
cvs.texi(,12930) @appendixsubsec Editinfo
cvs.texi(,12931) @cindex editinfo (admin file)
cvs.texi(,12932) @cindex Editor, specifying per module
cvs.texi(,12933) @cindex Per-module editor
cvs.texi(,12934) @cindex Log messages, editing
cvs.texi(,12935) 
cvs.texi(,12936) @strong{Note: The @file{editinfo} feature has been
cvs.texi(,12937) rendered obsolete.  To set a default editor for log
cvs.texi(,12938) messages use the @code{CVSEDITOR}, @code{EDITOR} environment variables
cvs.texi(,12939) (@pxref{Environment variables}) or the @samp{-e} global
cvs.texi(,12940) option (@pxref{Global options}).  See @ref{verifymsg},
cvs.texi(,12941) for information on the use of the @file{verifymsg}
cvs.texi(,12942) feature for evaluating log messages.}
cvs.texi(,12943) 
cvs.texi(,12944) If you want to make sure that all log messages look the
cvs.texi(,12945) same way, you can use the @file{editinfo} file to
cvs.texi(,12946) specify a program that is used to edit the log message.
cvs.texi(,12947) This program could be a custom-made editor that always
cvs.texi(,12948) enforces a certain style of the log message, or maybe a
cvs.texi(,12949) simple shell script that calls an editor, and checks
cvs.texi(,12950) that the entered message contains the required fields.
cvs.texi(,12951) 
cvs.texi(,12952) If no matching line is found in the @file{editinfo}
cvs.texi(,12953) file, the editor specified in the environment variable
cvs.texi(,12954) @code{$CVSEDITOR} is used instead.  If that variable is
cvs.texi(,12955) not set, then the environment variable @code{$EDITOR}
cvs.texi(,12956) is used instead.  If that variable is not
cvs.texi(,12957) set a default will be used.  See @ref{Committing your changes}.
cvs.texi(,12958) 
cvs.texi(,12959) The @file{editinfo} file is often most useful together
cvs.texi(,12960) with the @file{rcsinfo} file, which can be used to
cvs.texi(,12961) specify a log message template.
cvs.texi(,12962) 
cvs.texi(,12963) Each line in the @file{editinfo} file consists of a
cvs.texi(,12964) regular expression and a command-line template.  The
cvs.texi(,12965) template must include a program name, and can include
cvs.texi(,12966) any number of arguments.  The full path to the current
cvs.texi(,12967) log message template file is appended to the template.
cvs.texi(,12968) 
cvs.texi(,12969) One thing that should be noted is that the @samp{ALL}
cvs.texi(,12970) keyword is not supported.  If more than one matching
cvs.texi(,12971) line is found, the first one is used.  This can be
cvs.texi(,12972) useful for specifying a default edit script in a
cvs.texi(,12973) module, and then overriding it in a subdirectory.
cvs.texi(,12974) 
cvs.texi(,12975) @cindex DEFAULT in editinfo
cvs.texi(,12976) If the repository name does not match any of the
cvs.texi(,12977) regular expressions in this file, the @samp{DEFAULT}
cvs.texi(,12978) line is used, if it is specified.
cvs.texi(,12979) 
cvs.texi(,12980) If the edit script exits with a non-zero exit status,
cvs.texi(,12981) the commit is aborted.
cvs.texi(,12982) 
cvs.texi(,12983) Note: when @sc{cvs} is accessing a remote repository,
cvs.texi(,12984) or when the @samp{-m} or @samp{-F} options to @code{cvs
cvs.texi(,12985) commit} are used, @file{editinfo} will not be consulted.
cvs.texi(,12986) There is no good workaround for this; use
cvs.texi(,12987) @file{verifymsg} instead.
cvs.texi(,12988) 
cvs.texi(,12989) @menu
cvs.texi(,12990) * editinfo example::            Editinfo example
cvs.texi(,12991) @end menu
cvs.texi(,12992) 
cvs.texi(,12993) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,12994) @node editinfo example
cvs.texi(,12995) @appendixsubsubsec Editinfo example
cvs.texi(,12996) 
cvs.texi(,12997) The following is a little silly example of a
cvs.texi(,12998) @file{editinfo} file, together with the corresponding
cvs.texi(,12999) @file{rcsinfo} file, the log message template and an
cvs.texi(,13000) editor script.  We begin with the log message template.
cvs.texi(,13001) We want to always record a bug-id number on the first
cvs.texi(,13002) line of the log message.  The rest of log message is
cvs.texi(,13003) free text.  The following template is found in the file
cvs.texi(,13004) @file{/usr/cvssupport/tc.template}.
cvs.texi(,13005) 
cvs.texi(,13006) @example
cvs.texi(,13007) BugId:
cvs.texi(,13008) @end example
cvs.texi(,13009) 
cvs.texi(,13010) The script @file{/usr/cvssupport/bugid.edit} is used to
cvs.texi(,13011) edit the log message.
cvs.texi(,13012) 
cvs.texi(,13013) @example
cvs.texi(,13014) #!/bin/sh
cvs.texi(,13015) #
cvs.texi(,13016) #       bugid.edit filename
cvs.texi(,13017) #
cvs.texi(,13018) #  Call $EDITOR on FILENAME, and verify that the
cvs.texi(,13019) #  resulting file contains a valid bugid on the first
cvs.texi(,13020) #  line.
cvs.texi(,13021) if [ "x$EDITOR" = "x" ]; then EDITOR=vi; fi
cvs.texi(,13022) if [ "x$CVSEDITOR" = "x" ]; then CVSEDITOR=$EDITOR; fi
cvs.texi(,13023) $CVSEDITOR $1
cvs.texi(,13024) until head -1|grep '^BugId:[ ]*[0-9][0-9]*$' < $1
cvs.texi(,13025) do  echo -n  "No BugId found.  Edit again? ([y]/n)"
cvs.texi(,13026)     read ans
cvs.texi(,13027)     case $@{ans@} in
cvs.texi(,13028)         n*) exit 1;;
cvs.texi(,13029)     esac
cvs.texi(,13030)     $CVSEDITOR $1
cvs.texi(,13031) done
cvs.texi(,13032) @end example
cvs.texi(,13033) 
cvs.texi(,13034) The @file{editinfo} file contains this line:
cvs.texi(,13035) 
cvs.texi(,13036) @example
cvs.texi(,13037) ^tc     /usr/cvssupport/bugid.edit
cvs.texi(,13038) @end example
cvs.texi(,13039) 
cvs.texi(,13040) The @file{rcsinfo} file contains this line:
cvs.texi(,13041) 
cvs.texi(,13042) @example
cvs.texi(,13043) ^tc     /usr/cvssupport/tc.template
cvs.texi(,13044) @end example
cvs.texi(,13045) 
cvs.texi(,13046) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,13047) @node loginfo
cvs.texi(,13048) @appendixsubsec Loginfo
cvs.texi(,13049) @cindex loginfo (admin file)
cvs.texi(,13050) @cindex Storing log messages
cvs.texi(,13051) @cindex Mailing log messages
cvs.texi(,13052) @cindex Distributing log messages
cvs.texi(,13053) @cindex Log messages
cvs.texi(,13054) 
cvs.texi(,13055) @c "cvs commit" is not quite right.  What we
cvs.texi(,13056) @c mean is "when the repository gets changed" which
cvs.texi(,13057) @c also includes "cvs import" and "cvs add" on a directory.
cvs.texi(,13058) The @file{loginfo} file is used to control where
cvs.texi(,13059) @samp{cvs commit} log information is sent.  The first
cvs.texi(,13060) entry on a line is a regular expression which is tested
cvs.texi(,13061) against the directory that the change is being made to,
cvs.texi(,13062) relative to the @code{$CVSROOT}.  If a match is found, then
cvs.texi(,13063) the remainder of the line is a filter program that
cvs.texi(,13064) should expect log information on its standard input.
cvs.texi(,13065) 
cvs.texi(,13066) If the repository name does not match any of the
cvs.texi(,13067) regular expressions in this file, the @samp{DEFAULT}
cvs.texi(,13068) line is used, if it is specified.
cvs.texi(,13069) 
cvs.texi(,13070) All occurrences of the name @samp{ALL} appearing as a
cvs.texi(,13071) regular expression are used in addition to the first
cvs.texi(,13072) matching regular expression or @samp{DEFAULT}.
cvs.texi(,13073) 
cvs.texi(,13074) The first matching regular expression is used.
cvs.texi(,13075) 
cvs.texi(,13076) @xref{commit files}, for a description of the syntax of
cvs.texi(,13077) the @file{loginfo} file.
cvs.texi(,13078) 
cvs.texi(,13079) The user may specify a format string as
cvs.texi(,13080) part of the filter.  The string is composed of a
cvs.texi(,13081) @samp{%} followed by a space, or followed by a single
cvs.texi(,13082) format character, or followed by a set of format
cvs.texi(,13083) characters surrounded by @samp{@{} and @samp{@}} as
cvs.texi(,13084) separators.  The format characters are:
cvs.texi(,13085) 
cvs.texi(,13086) @table @t
cvs.texi(,13087) @item s
cvs.texi(,13088) file name
cvs.texi(,13089) @item V
cvs.texi(,13090) old version number (pre-checkin)
cvs.texi(,13091) @item v
cvs.texi(,13092) new version number (post-checkin)
cvs.texi(,13093) @end table
cvs.texi(,13094) 
cvs.texi(,13095) All other characters that appear in a format string
cvs.texi(,13096) expand to an empty field (commas separating fields are
cvs.texi(,13097) still provided).
cvs.texi(,13098) 
cvs.texi(,13099) For example, some valid format strings are @samp{%},
cvs.texi(,13100) @samp{%s}, @samp{%@{s@}}, and @samp{%@{sVv@}}.
cvs.texi(,13101) 
cvs.texi(,13102) The output will be a space separated string of tokens enclosed in
cvs.texi(,13103) quotation marks (@t{"}).
cvs.texi(,13104) Any embedded dollar signs (@t{$}), backticks (@t{`}),
cvs.texi(,13105) backslashes (@t{\}), or quotation marks will be preceded
cvs.texi(,13106) by a backslash (this allows the shell to correctly parse it
cvs.texi(,13107) as a single string, regardless of the characters it contains).
cvs.texi(,13108) For backwards compatibility, the first
cvs.texi(,13109) token will be the repository subdirectory.  The rest of the
cvs.texi(,13110) tokens will be comma-delimited lists of the information
cvs.texi(,13111) requested in the format string.  For example, if
cvs.texi(,13112) @samp{/u/src/master/yoyodyne/tc} is the repository, @samp{%@{sVv@}}
cvs.texi(,13113) is the format string, and three files (@t{ChangeLog},
cvs.texi(,13114) @t{Makefile}, @t{foo.c}) were modified, the output
cvs.texi(,13115) might be:
cvs.texi(,13116) 
cvs.texi(,13117) @example
cvs.texi(,13118) "yoyodyne/tc ChangeLog,1.1,1.2 Makefile,1.3,1.4 foo.c,1.12,1.13"
cvs.texi(,13119) @end example
cvs.texi(,13120) 
cvs.texi(,13121) As another example, @samp{%@{@}} means that only the
cvs.texi(,13122) name of the repository will be generated.
cvs.texi(,13123) 
cvs.texi(,13124) Note: when @sc{cvs} is accessing a remote repository,
cvs.texi(,13125) @file{loginfo} will be run on the @emph{remote}
cvs.texi(,13126) (i.e., server) side, not the client side (@pxref{Remote
cvs.texi(,13127) repositories}).
cvs.texi(,13128) 
cvs.texi(,13129) @menu
cvs.texi(,13130) * loginfo example::             Loginfo example
cvs.texi(,13131) * Keeping a checked out copy::  Updating a tree on every checkin
cvs.texi(,13132) @end menu
cvs.texi(,13133) 
cvs.texi(,13134) @c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cvs.texi(,13135) @node loginfo example
cvs.texi(,13136) @appendixsubsubsec Loginfo example
cvs.texi(,13137) 
cvs.texi(,13138) The following @file{loginfo} file, together with the
cvs.texi(,13139) tiny shell-script below, appends all log messages
cvs.texi(,13140) to the file @file{$CVSROOT/CVSROOT/commitlog},
cvs.texi(,13141) and any commits to the administrative files (inside
cvs.texi(,13142) the @file{CVSROOT} directory) are also logged in
cvs.texi(,13143) @file{/usr/adm/cvsroot-log}.
cvs.texi(,13144) Commits to the @file{prog1} directory are mailed to @t{ceder}.
cvs.texi(,13145) 
cvs.texi(,13146) @c FIXME: is it a CVS feature or bug that only the
cvs.texi(,13147) @c first matching line is used?  It is documented
cvs.texi(,13148) @c above, but is it useful?  For example, if we wanted
cvs.texi(,13149) @c to run both "cvs-log" and "Mail" for the CVSROOT
cvs.texi(,13150) @c directory, it is kind of awkward if
cvs.texi(,13151) @c only the first matching line is used.
cvs.texi(,13152) @example
cvs.texi(,13153) ALL             /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog $USER
cvs.texi(,13154) ^CVSROOT        /usr/local/bin/cvs-log /usr/adm/cvsroot-log
cvs.texi(,13155) ^prog1          Mail -s %s ceder
cvs.texi(,13156) @end example
cvs.texi(,13157) 
cvs.texi(,13158) The shell-script @file{/usr/local/bin/cvs-log} looks
cvs.texi(,13159) like this:
cvs.texi(,13160) 
cvs.texi(,13161) @example
cvs.texi(,13162) #!/bin/sh
cvs.texi(,13163) (echo "------------------------------------------------------";
cvs.texi(,13164)  echo -n $2"  ";
cvs.texi(,13165)  date;
cvs.texi(,13166)  echo;
cvs.texi(,13167)  cat) >> $1
cvs.texi(,13168) @end example
cvs.texi(,13169) 
cvs.texi(,13170) @node Keeping a checked out copy
cvs.texi(,13171) @appendixsubsubsec Keeping a checked out copy
cvs.texi(,13172) 
cvs.texi(,13173) @c What other index entries?  It seems like
cvs.texi(,13174) @c people might want to use a lot of different
cvs.texi(,13175) @c words for this functionality.
cvs.texi(,13176) @cindex Keeping a checked out copy
cvs.texi(,13177) @cindex Checked out copy, keeping
cvs.texi(,13178) @cindex Web pages, maintaining with CVS
cvs.texi(,13179) 
cvs.texi(,13180) It is often useful to maintain a directory tree which
cvs.texi(,13181) contains files which correspond to the latest version
cvs.texi(,13182) in the repository.  For example, other developers might
cvs.texi(,13183) want to refer to the latest sources without having to
cvs.texi(,13184) check them out, or you might be maintaining a web site
cvs.texi(,13185) with @sc{cvs} and want every checkin to cause the files
cvs.texi(,13186) used by the web server to be updated.
cvs.texi(,13187) @c Can we offer more details on the web example?  Or
cvs.texi(,13188) @c point the user at how to figure it out?  This text
cvs.texi(,13189) @c strikes me as sufficient for someone who already has
cvs.texi(,13190) @c some idea of what we mean but not enough for the naive
cvs.texi(,13191) @c user/sysadmin to understand it and set it up.
cvs.texi(,13192) 
cvs.texi(,13193) The way to do this is by having loginfo invoke
cvs.texi(,13194) @code{cvs update}.  Doing so in the naive way will
cvs.texi(,13195) cause a problem with locks, so the @code{cvs update}
cvs.texi(,13196) must be run in the background.
cvs.texi(,13197) @c Should we try to describe the problem with locks?
cvs.texi(,13198) @c It seems like a digression for someone who just
cvs.texi(,13199) @c wants to know how to make it work.
cvs.texi(,13200) @c Another choice which might work for a single file
cvs.texi(,13201) @c is to use "cvs -n update -p" which doesn't take
cvs.texi(,13202) @c out locks (I think) but I don't see many advantages
cvs.texi(,13203) @c of that and we might as well document something which
cvs.texi(,13204) @c works for multiple files.
cvs.texi(,13205) Here is an example for unix (this should all be on one line):
cvs.texi(,13206) 
cvs.texi(,13207) @example
cvs.texi(,13208) ^cyclic-pages		(date; cat; (sleep 2; cd /u/www/local-docs;
cvs.texi(,13209)  cvs -q update -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1
cvs.texi(,13210) @end example
cvs.texi(,13211) 
cvs.texi(,13212) This will cause checkins to repository directories
cvs.texi(,13213) starting with @code{cyclic-pages} to update the checked
cvs.texi(,13214) out tree in @file{/u/www/local-docs}.
cvs.texi(,13215) @c More info on some of the details?  The "sleep 2" is
cvs.texi(,13216) @c so if we are lucky the lock will be gone by the time
cvs.texi(,13217) @c we start and we can wait 2 seconds instead of 30.
cvs.texi(,13218) 
cvs.texi(,13219) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,13220) @node rcsinfo
cvs.texi(,13221) @appendixsec Rcsinfo
cvs.texi(,13222) @cindex rcsinfo (admin file)
cvs.texi(,13223) @cindex Form for log message
cvs.texi(,13224) @cindex Log message template
cvs.texi(,13225) @cindex Template for log message
cvs.texi(,13226) 
cvs.texi(,13227) The @file{rcsinfo} file can be used to specify a form to
cvs.texi(,13228) edit when filling out the commit log.  The
cvs.texi(,13229) @file{rcsinfo} file has a syntax similar to the
cvs.texi(,13230) @file{verifymsg}, @file{commitinfo} and @file{loginfo}
cvs.texi(,13231) files.  @xref{syntax}.  Unlike the other files the second
cvs.texi(,13232) part is @emph{not} a command-line template.  Instead,
cvs.texi(,13233) the part after the regular expression should be a full pathname to
cvs.texi(,13234) a file containing the log message template.
cvs.texi(,13235) 
cvs.texi(,13236) If the repository name does not match any of the
cvs.texi(,13237) regular expressions in this file, the @samp{DEFAULT}
cvs.texi(,13238) line is used, if it is specified.
cvs.texi(,13239) 
cvs.texi(,13240) All occurrences of the name @samp{ALL} appearing as a
cvs.texi(,13241) regular expression are used in addition to the first
cvs.texi(,13242) matching regular expression or @samp{DEFAULT}.
cvs.texi(,13243) 
cvs.texi(,13244) @c FIXME: should be offering advice, somewhere around
cvs.texi(,13245) @c here, about where to put the template file.  The
cvs.texi(,13246) @c verifymsg example uses /usr/cvssupport but doesn't
cvs.texi(,13247) @c say anything about what that directory is for or
cvs.texi(,13248) @c whether it is hardwired into CVS or who creates
cvs.texi(,13249) @c it or anything.  In particular we should say
cvs.texi(,13250) @c how to version control the template file.  A
cvs.texi(,13251) @c probably better answer than the /usr/cvssupport
cvs.texi(,13252) @c stuff is to use checkoutlist (with xref to the
cvs.texi(,13253) @c checkoutlist doc).
cvs.texi(,13254) @c Also I am starting to see a connection between
cvs.texi(,13255) @c this and the Keeping a checked out copy node.
cvs.texi(,13256) @c Probably want to say something about that.
cvs.texi(,13257) The log message template will be used as a default log
cvs.texi(,13258) message.  If you specify a log message with @samp{cvs
cvs.texi(,13259) commit -m @var{message}} or @samp{cvs commit -f
cvs.texi(,13260) @var{file}} that log message will override the
cvs.texi(,13261) template.
cvs.texi(,13262) 
cvs.texi(,13263) @xref{verifymsg}, for an example @file{rcsinfo}
cvs.texi(,13264) file.
cvs.texi(,13265) 
cvs.texi(,13266) When @sc{cvs} is accessing a remote repository,
cvs.texi(,13267) the contents of @file{rcsinfo} at the time a directory
cvs.texi(,13268) is first checked out will specify a template. This
cvs.texi(,13269) template will be updated on all @samp{cvs update}
cvs.texi(,13270) commands. It will also be added to new directories
cvs.texi(,13271) added with a @samp{cvs add new-directry} command.
cvs.texi(,13272) In versions of @sc{cvs} prior to version 1.12, the
cvs.texi(,13273) @file{CVS/Template} file was not updated. If the
cvs.texi(,13274) @sc{cvs} server is at version 1.12 or higher an older
cvs.texi(,13275) client may be used and the @file{CVS/Template} will
cvs.texi(,13276) be updated from the server.
cvs.texi(,13277) 
cvs.texi(,13278) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,13279) @node cvsignore
cvs.texi(,13280) @appendixsec Ignoring files via cvsignore
cvs.texi(,13281) @cindex cvsignore (admin file), global
cvs.texi(,13282) @cindex Global cvsignore
cvs.texi(,13283) @cindex Ignoring files
cvs.texi(,13284) @c -- This chapter should maybe be moved to the
cvs.texi(,13285) @c tutorial part of the manual?
cvs.texi(,13286) 
cvs.texi(,13287) There are certain file names that frequently occur
cvs.texi(,13288) inside your working copy, but that you don't want to
cvs.texi(,13289) put under @sc{cvs} control.  Examples are all the object
cvs.texi(,13290) files that you get while you compile your sources.
cvs.texi(,13291) Normally, when you run @samp{cvs update}, it prints a
cvs.texi(,13292) line for each file it encounters that it doesn't know
cvs.texi(,13293) about (@pxref{update output}).
cvs.texi(,13294) 
cvs.texi(,13295) @sc{cvs} has a list of files (or sh(1) file name patterns)
cvs.texi(,13296) that it should ignore while running @code{update},
cvs.texi(,13297) @code{import} and @code{release}.
cvs.texi(,13298) @c -- Are those the only three commands affected?
cvs.texi(,13299) This list is constructed in the following way.
cvs.texi(,13300) 
cvs.texi(,13301) @itemize @bullet
cvs.texi(,13302) @item
cvs.texi(,13303) The list is initialized to include certain file name
cvs.texi(,13304) patterns: names associated with @sc{cvs}
cvs.texi(,13305) administration, or with other common source control
cvs.texi(,13306) systems; common names for patch files, object files,
cvs.texi(,13307) archive files, and editor backup files; and other names
cvs.texi(,13308) that are usually artifacts of assorted utilities.
cvs.texi(,13309) Currently, the default list of ignored file name
cvs.texi(,13310) patterns is:
cvs.texi(,13311) 
cvs.texi(,13312) @cindex Ignored files
cvs.texi(,13313) @cindex Automatically ignored files
cvs.texi(,13314) @example
cvs.texi(,13315)     RCS     SCCS    CVS     CVS.adm
cvs.texi(,13316)     RCSLOG  cvslog.*
cvs.texi(,13317)     tags    TAGS
cvs.texi(,13318)     .make.state     .nse_depinfo
cvs.texi(,13319)     *~      #*      .#*     ,*      _$*     *$
cvs.texi(,13320)     *.old   *.bak   *.BAK   *.orig  *.rej   .del-*
cvs.texi(,13321)     *.a     *.olb   *.o     *.obj   *.so    *.exe
cvs.texi(,13322)     *.Z     *.elc   *.ln
cvs.texi(,13323)     core
cvs.texi(,13324) @end example
cvs.texi(,13325) 
cvs.texi(,13326) @item
cvs.texi(,13327) The per-repository list in
cvs.texi(,13328) @file{$CVSROOT/CVSROOT/cvsignore} is appended to
cvs.texi(,13329) the list, if that file exists.
cvs.texi(,13330) 
cvs.texi(,13331) @item
cvs.texi(,13332) The per-user list in @file{.cvsignore} in your home
cvs.texi(,13333) directory is appended to the list, if it exists.
cvs.texi(,13334) 
cvs.texi(,13335) @item
cvs.texi(,13336) Any entries in the environment variable
cvs.texi(,13337) @code{$CVSIGNORE} is appended to the list.
cvs.texi(,13338) 
cvs.texi(,13339) @item
cvs.texi(,13340) Any @samp{-I} options given to @sc{cvs} is appended.
cvs.texi(,13341) 
cvs.texi(,13342) @item
cvs.texi(,13343) As @sc{cvs} traverses through your directories, the contents
cvs.texi(,13344) of any @file{.cvsignore} will be appended to the list.
cvs.texi(,13345) The patterns found in @file{.cvsignore} are only valid
cvs.texi(,13346) for the directory that contains them, not for
cvs.texi(,13347) any sub-directories.
cvs.texi(,13348) @end itemize
cvs.texi(,13349) 
cvs.texi(,13350) In any of the 5 places listed above, a single
cvs.texi(,13351) exclamation mark (@samp{!}) clears the ignore list.
cvs.texi(,13352) This can be used if you want to store any file which
cvs.texi(,13353) normally is ignored by @sc{cvs}.
cvs.texi(,13354) 
cvs.texi(,13355) Specifying @samp{-I !} to @code{cvs import} will import
cvs.texi(,13356) everything, which is generally what you want to do if
cvs.texi(,13357) you are importing files from a pristine distribution or
cvs.texi(,13358) any other source which is known to not contain any
cvs.texi(,13359) extraneous files.  However, looking at the rules above
cvs.texi(,13360) you will see there is a fly in the ointment; if the
cvs.texi(,13361) distribution contains any @file{.cvsignore} files, then
cvs.texi(,13362) the patterns from those files will be processed even if
cvs.texi(,13363) @samp{-I !} is specified.  The only workaround is to
cvs.texi(,13364) remove the @file{.cvsignore} files in order to do the
cvs.texi(,13365) import.  Because this is awkward, in the future
cvs.texi(,13366) @samp{-I !} might be modified to override
cvs.texi(,13367) @file{.cvsignore} files in each directory.
cvs.texi(,13368) 
cvs.texi(,13369) Note that the syntax of the ignore files consists of a
cvs.texi(,13370) series of lines, each of which contains a space
cvs.texi(,13371) separated list of filenames.  This offers no clean way
cvs.texi(,13372) to specify filenames which contain spaces, but you can
cvs.texi(,13373) use a workaround like @file{foo?bar} to match a file
cvs.texi(,13374) named @file{foo bar} (it also matches @file{fooxbar}
cvs.texi(,13375) and the like).  Also note that there is currently no
cvs.texi(,13376) way to specify comments.
cvs.texi(,13377) @c FIXCVS?  I don't _like_ this syntax at all, but
cvs.texi(,13378) @c changing it raises all the usual compatibility
cvs.texi(,13379) @c issues and I'm also not sure what to change it to.
cvs.texi(,13380) 
cvs.texi(,13381) @node checkoutlist
cvs.texi(,13382) @appendixsec The checkoutlist file
cvs.texi(,13383) @cindex checkoutlist
cvs.texi(,13384) 
cvs.texi(,13385) It may be helpful to use @sc{cvs} to maintain your own
cvs.texi(,13386) files in the @file{CVSROOT} directory.  For example,
cvs.texi(,13387) suppose that you have a script @file{logcommit.pl}
cvs.texi(,13388) which you run by including the following line in the
cvs.texi(,13389) @file{commitinfo} administrative file:
cvs.texi(,13390) 
cvs.texi(,13391) @example
cvs.texi(,13392) ALL   $CVSROOT/CVSROOT/logcommit.pl
cvs.texi(,13393) @end example
cvs.texi(,13394) 
cvs.texi(,13395) To maintain @file{logcommit.pl} with @sc{cvs} you would
cvs.texi(,13396) add the following line to the @file{checkoutlist}
cvs.texi(,13397) administrative file:
cvs.texi(,13398) 
cvs.texi(,13399) @example
cvs.texi(,13400) logcommit.pl
cvs.texi(,13401) @end example
cvs.texi(,13402) 
cvs.texi(,13403) The format of @file{checkoutlist} is one line for each
cvs.texi(,13404) file that you want to maintain using @sc{cvs}, giving
cvs.texi(,13405) the name of the file.
cvs.texi(,13406) 
cvs.texi(,13407) After setting up @file{checkoutlist} in this fashion,
cvs.texi(,13408) the files listed there will function just like
cvs.texi(,13409) @sc{cvs}'s built-in administrative files.  For example,
cvs.texi(,13410) when checking in one of the files you should get a
cvs.texi(,13411) message such as:
cvs.texi(,13412) 
cvs.texi(,13413) @example
cvs.texi(,13414) cvs commit: Rebuilding administrative file database
cvs.texi(,13415) @end example
cvs.texi(,13416) 
cvs.texi(,13417) @noindent
cvs.texi(,13418) and the checked out copy in the @file{CVSROOT}
cvs.texi(,13419) directory should be updated.
cvs.texi(,13420) 
cvs.texi(,13421) Note that listing @file{passwd} (@pxref{Password
cvs.texi(,13422) authentication server}) in @file{checkoutlist} is not
cvs.texi(,13423) recommended for security reasons.
cvs.texi(,13424) 
cvs.texi(,13425) For information about keeping a checkout out copy in a
cvs.texi(,13426) more general context than the one provided by
cvs.texi(,13427) @file{checkoutlist}, see @ref{Keeping a checked out
cvs.texi(,13428) copy}.
cvs.texi(,13429) 
cvs.texi(,13430) @c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cvs.texi(,13431) @node history file
cvs.texi(,13432) @appendixsec The history file
cvs.texi(,13433) @cindex History file
cvs.texi(,13434) @cindex Log information, saving
cvs.texi(,13435) 
cvs.texi(,13436) The file @file{$CVSROOT/CVSROOT/history} is used
cvs.texi(,13437) to log information for the @code{history} command
cvs.texi(,13438) (@pxref{history}).  This file must be created to turn
cvs.texi(,13439) on logging.  This is done automatically if the
cvs.texi(,13440) @code{cvs init} command is used to set up the
cvs.texi(,13441) repository (@pxref{Creating a repository}).
cvs.texi(,13442) 
cvs.texi(,13443) The file format of the @file{history} file is
cvs.texi(,13444) documented only in comments in the @sc{cvs} source
cvs.texi(,13445) code, but generally programs should use the @code{cvs
cvs.texi(,13446) history} command to access it anyway, in case the
cvs.texi(,13447) format changes with future releases of @sc{cvs}.
cvs.texi(,13448) 
cvs.texi(,13449) @node Variables
cvs.texi(,13450) @appendixsec Expansions in administrative files
cvs.texi(,13451) @cindex Internal variables
cvs.texi(,13452) @cindex Variables
cvs.texi(,13453) 
cvs.texi(,13454) Sometimes in writing an administrative file, you might
cvs.texi(,13455) want the file to be able to know various things based
cvs.texi(,13456) on environment @sc{cvs} is running in.  There are
cvs.texi(,13457) several mechanisms to do that.
cvs.texi(,13458) 
cvs.texi(,13459) To find the home directory of the user running @sc{cvs}
cvs.texi(,13460) (from the @code{HOME} environment variable), use
cvs.texi(,13461) @samp{~} followed by @samp{/} or the end of the line.
cvs.texi(,13462) Likewise for the home directory of @var{user}, use
cvs.texi(,13463) @samp{~@var{user}}.  These variables are expanded on
cvs.texi(,13464) the server machine, and don't get any reasonable
cvs.texi(,13465) expansion if pserver (@pxref{Password authenticated})
cvs.texi(,13466) is in use; therefore user variables (see below) may be
cvs.texi(,13467) a better choice to customize behavior based on the user
cvs.texi(,13468) running @sc{cvs}.
cvs.texi(,13469) @c Based on these limitations, should we deprecate ~?
cvs.texi(,13470) @c What is it good for?  Are people using it?
cvs.texi(,13471) 
cvs.texi(,13472) One may want to know about various pieces of
cvs.texi(,13473) information internal to @sc{cvs}.  A @sc{cvs} internal
cvs.texi(,13474) variable has the syntax @code{$@{@var{variable}@}},
cvs.texi(,13475) where @var{variable} starts with a letter and consists
cvs.texi(,13476) of alphanumeric characters and @samp{_}.  If the
cvs.texi(,13477) character following @var{variable} is a
cvs.texi(,13478) non-alphanumeric character other than @samp{_}, the
cvs.texi(,13479) @samp{@{} and @samp{@}} can be omitted.  The @sc{cvs}
cvs.texi(,13480) internal variables are:
cvs.texi(,13481) 
cvs.texi(,13482) @table @code
cvs.texi(,13483) @item CVSROOT
cvs.texi(,13484) @cindex CVSROOT, internal variable
cvs.texi(,13485) This is the absolute path to the current @sc{cvs} root directory.
cvs.texi(,13486) @xref{Repository}, for a description of the various
cvs.texi(,13487) ways to specify this, but note that the internal
cvs.texi(,13488) variable contains just the directory and not any
cvs.texi(,13489) of the access method information.
cvs.texi(,13490) 
cvs.texi(,13491) @item RCSBIN
cvs.texi(,13492) @cindex RCSBIN, internal variable
cvs.texi(,13493) In @sc{cvs} 1.9.18 and older, this specified the
cvs.texi(,13494) directory where @sc{cvs} was looking for @sc{rcs}
cvs.texi(,13495) programs.  Because @sc{cvs} no longer runs @sc{rcs}
cvs.texi(,13496) programs, specifying this internal variable is now an
cvs.texi(,13497) error.
cvs.texi(,13498) 
cvs.texi(,13499) @item CVSEDITOR
cvs.texi(,13500) @cindex CVSEDITOR, internal variable
cvs.texi(,13501) @itemx EDITOR
cvs.texi(,13502) @cindex EDITOR, internal variable
cvs.texi(,13503) @itemx VISUAL
cvs.texi(,13504) @cindex VISUAL, internal variable
cvs.texi(,13505) These all expand to the same value, which is the editor
cvs.texi(,13506) that @sc{cvs} is using.  @xref{Global options}, for how
cvs.texi(,13507) to specify this.
cvs.texi(,13508) 
cvs.texi(,13509) @item USER
cvs.texi(,13510) @cindex USER, internal variable
cvs.texi(,13511) Username of the user running @sc{cvs} (on the @sc{cvs}
cvs.texi(,13512) server machine).
cvs.texi(,13513) When using pserver, this is the user specified in the repository
cvs.texi(,13514) specification which need not be the same as the username the
cvs.texi(,13515) server is running as (@pxref{Password authentication server}).
cvs.texi(,13516) Do not confuse this with the environment variable of the same name.
cvs.texi(,13517) @end table
cvs.texi(,13518) 
cvs.texi(,13519) If you want to pass a value to the administrative files
cvs.texi(,13520) which the user who is running @sc{cvs} can specify,
cvs.texi(,13521) use a user variable.
cvs.texi(,13522) @cindex User variables
cvs.texi(,13523) To expand a user variable, the
cvs.texi(,13524) administrative file contains
cvs.texi(,13525) @code{$@{=@var{variable}@}}.  To set a user variable,
cvs.texi(,13526) specify the global option @samp{-s} to @sc{cvs}, with
cvs.texi(,13527) argument @code{@var{variable}=@var{value}}.  It may be
cvs.texi(,13528) particularly useful to specify this option via
cvs.texi(,13529) @file{.cvsrc} (@pxref{~/.cvsrc}).
cvs.texi(,13530) 
cvs.texi(,13531) For example, if you want the administrative file to
cvs.texi(,13532) refer to a test directory you might create a user
cvs.texi(,13533) variable @code{TESTDIR}.  Then if @sc{cvs} is invoked
cvs.texi(,13534) as
cvs.texi(,13535) 
cvs.texi(,13536) @example
cvs.texi(,13537) cvs -s TESTDIR=/work/local/tests
cvs.texi(,13538) @end example
cvs.texi(,13539) 
cvs.texi(,13540) @noindent
cvs.texi(,13541) and the
cvs.texi(,13542) administrative file contains @code{sh
cvs.texi(,13543) $@{=TESTDIR@}/runtests}, then that string is expanded
cvs.texi(,13544) to @code{sh /work/local/tests/runtests}.
cvs.texi(,13545) 
cvs.texi(,13546) All other strings containing @samp{$} are reserved;
cvs.texi(,13547) there is no way to quote a @samp{$} character so that
cvs.texi(,13548) @samp{$} represents itself.
cvs.texi(,13549) 
cvs.texi(,13550) Environment variables passed to administrative files are:
cvs.texi(,13551) 
cvs.texi(,13552) @table @code
cvs.texi(,13553) @cindex environment variables, passed to administrative files
cvs.texi(,13554) 
cvs.texi(,13555) @item CVS_USER
cvs.texi(,13556) @cindex CVS_USER, environment variable
cvs.texi(,13557) The @sc{cvs}-specific username provided by the user, if it
cvs.texi(,13558) can be provided (currently just for the pserver access
cvs.texi(,13559) method), and to the empty string otherwise.  (@code{CVS_USER}
cvs.texi(,13560) and @code{USER} may differ when @file{$CVSROOT/CVSROOT/passwd}
cvs.texi(,13561) is used to map @sc{cvs} usernames to system usernames.)
cvs.texi(,13562) 
cvs.texi(,13563) @item LOGNAME
cvs.texi(,13564) @cindex LOGNAME, environment variable
cvs.texi(,13565) The username of the system user.
cvs.texi(,13566) 
cvs.texi(,13567) @item USER
cvs.texi(,13568) @cindex USER, environment variable
cvs.texi(,13569) Same as @code{LOGNAME}.
cvs.texi(,13570) Do not confuse this with the internal variable of the same name.
cvs.texi(,13571) @end table
cvs.texi(,13572) 
cvs.texi(,13573) @node config
cvs.texi(,13574) @appendixsec The CVSROOT/config configuration file
cvs.texi(,13575) 
cvs.texi(,13576) @cindex config, in CVSROOT
cvs.texi(,13577) @cindex CVSROOT/config
cvs.texi(,13578) 
cvs.texi(,13579) The administrative file @file{config} contains various
cvs.texi(,13580) miscellaneous settings which affect the behavior of
cvs.texi(,13581) @sc{cvs}.  The syntax is slightly different from the
cvs.texi(,13582) other administrative files.  Variables are not
cvs.texi(,13583) expanded.  Lines which start with @samp{#} are
cvs.texi(,13584) considered comments.
cvs.texi(,13585) @c FIXME: where do we define comments for the other
cvs.texi(,13586) @c administrative files.
cvs.texi(,13587) Other lines consist of a keyword, @samp{=}, and a
cvs.texi(,13588) value.  Note that this syntax is very strict.
cvs.texi(,13589) Extraneous spaces or tabs are not permitted.
cvs.texi(,13590) @c See comments in parseinfo.c:parse_config for more
cvs.texi(,13591) @c discussion of this strictness.
cvs.texi(,13592) 
cvs.texi(,13593) Currently defined keywords are:
cvs.texi(,13594) 
cvs.texi(,13595) @table @code
cvs.texi(,13596) @cindex RCSBIN, in CVSROOT/config
cvs.texi(,13597) @item RCSBIN=@var{bindir}
cvs.texi(,13598) For @sc{cvs} 1.9.12 through 1.9.18, this setting told
cvs.texi(,13599) @sc{cvs} to look for @sc{rcs} programs in the
cvs.texi(,13600) @var{bindir} directory.  Current versions of @sc{cvs}
cvs.texi(,13601) do not run @sc{rcs} programs; for compatibility this
cvs.texi(,13602) setting is accepted, but it does nothing.
cvs.texi(,13603) 
cvs.texi(,13604) @cindex SystemAuth, in CVSROOT/config
cvs.texi(,13605) @item SystemAuth=@var{value}
cvs.texi(,13606) If @var{value} is @samp{yes}, then pserver should check
cvs.texi(,13607) for users in the system's user database if not found in
cvs.texi(,13608) @file{CVSROOT/passwd}.  If it is @samp{no}, then all
cvs.texi(,13609) pserver users must exist in @file{CVSROOT/passwd}.
cvs.texi(,13610) The default is @samp{yes}.  For more on pserver, see
cvs.texi(,13611) @ref{Password authenticated}.
cvs.texi(,13612) 
cvs.texi(,13622) 
cvs.texi(,13623) @cindex TopLevelAdmin, in CVSROOT/config
cvs.texi(,13624) @item TopLevelAdmin=@var{value}
cvs.texi(,13625) Modify the @samp{checkout} command to create a
cvs.texi(,13626) @samp{CVS} directory at the top level of the new
cvs.texi(,13627) working directory, in addition to @samp{CVS}
cvs.texi(,13628) directories created within checked-out directories.
cvs.texi(,13629) The default value is @samp{no}.
cvs.texi(,13630) 
cvs.texi(,13631) This option is useful if you find yourself performing
cvs.texi(,13632) many commands at the top level of your working
cvs.texi(,13633) directory, rather than in one of the checked out
cvs.texi(,13634) subdirectories.  The @file{CVS} directory created there
cvs.texi(,13635) will mean you don't have to specify @code{CVSROOT} for
cvs.texi(,13636) each command.  It also provides a place for the
cvs.texi(,13637) @file{CVS/Template} file (@pxref{Working directory
cvs.texi(,13638) storage}).
cvs.texi(,13639) 
cvs.texi(,13640) @cindex LockDir, in CVSROOT/config
cvs.texi(,13641) @item LockDir=@var{directory}
cvs.texi(,13642) Put @sc{cvs} lock files in @var{directory} rather than
cvs.texi(,13643) directly in the repository.  This is useful if you want
cvs.texi(,13644) to let users read from the repository while giving them
cvs.texi(,13645) write access only to @var{directory}, not to the
cvs.texi(,13646) repository.
cvs.texi(,13647) It can also be used to put the locks on a very fast
cvs.texi(,13648) in-memory file system to speed up locking and unlocking
cvs.texi(,13649) the repository.
cvs.texi(,13650) You need to create @var{directory}, but
cvs.texi(,13651) @sc{cvs} will create subdirectories of @var{directory} as it
cvs.texi(,13652) needs them.  For information on @sc{cvs} locks, see
cvs.texi(,13653) @ref{Concurrency}.
cvs.texi(,13654) 
cvs.texi(,13655) @c Mention this in Compatibility section?
cvs.texi(,13656) Before enabling the LockDir option, make sure that you
cvs.texi(,13657) have tracked down and removed any copies of @sc{cvs} 1.9 or
cvs.texi(,13658) older.  Such versions neither support LockDir, nor will
cvs.texi(,13659) give an error indicating that they don't support it.
cvs.texi(,13660) The result, if this is allowed to happen, is that some
cvs.texi(,13661) @sc{cvs} users will put the locks one place, and others will
cvs.texi(,13662) put them another place, and therefore the repository
cvs.texi(,13663) could become corrupted.  @sc{cvs} 1.10 does not support
cvs.texi(,13664) LockDir but it will print a warning if run on a
cvs.texi(,13665) repository with LockDir enabled.
cvs.texi(,13666) 
cvs.texi(,13667) @cindex LogHistory, in CVSROOT/config
cvs.texi(,13668) @item LogHistory=@var{value}
cvs.texi(,13669) Control what is logged to the @file{CVSROOT/history} file (@pxref{history}).
cvs.texi(,13670) Default of @samp{TOEFWUCGMAR} (or simply @samp{all}) will log
cvs.texi(,13671) all transactions.  Any subset of the default is
cvs.texi(,13672) legal.  (For example, to only log transactions that modify the
cvs.texi(,13673) @file{*,v} files, use @samp{LogHistory=TMAR}.)
cvs.texi(,13674) 
cvs.texi(,13675) @cindex RereadLogAfterVerify, in CVSROOT/config
cvs.texi(,13676) @cindex @file{verifymsg}, changing the log message
cvs.texi(,13677) @item RereadLogAfterVerify=@var{value}
cvs.texi(,13678) Modify the @samp{commit} command such that CVS will reread the
cvs.texi(,13679) log message after running the program specified by @file{verifymsg}.
cvs.texi(,13680) @var{value} may be one of @samp{yes} or @samp{always}, indicating that
cvs.texi(,13681) the log message should always be reread; @samp{no}
cvs.texi(,13682) or @samp{never}, indicating that it should never be
cvs.texi(,13683) reread; or @var{value} may be @samp{stat}, indicating
cvs.texi(,13684) that the file should be checked with the filesystem
cvs.texi(,13685) @samp{stat()} function to see if it has changed (see warning below)
cvs.texi(,13686) before rereading.  The default value is @samp{always}.
cvs.texi(,13687) 
cvs.texi(,13688) @strong{Note: the `stat' mode can cause CVS to pause for up to
cvs.texi(,13689) one extra second per directory committed.  This can be less IO and
cvs.texi(,13690) CPU intensive but is not recommended for use with large repositories}
cvs.texi(,13691) 
cvs.texi(,13692) @xref{verifymsg}, for more information on how verifymsg
cvs.texi(,13693) may be used.
cvs.texi(,13694) 
cvs.texi(,13695) @cindex UserAdminOptions, in CVSROOT/config
cvs.texi(,13696) @item UserAdminOptions=@var{value}
cvs.texi(,13697) Control what options will be allowed with the @code{cvs admin}
cvs.texi(,13698) command (@pxref{admin}) for users not in the @code{cvsadmin} group.
cvs.texi(,13699) The @var{value} string is a list of single character options
cvs.texi(,13700) which should be allowed.  If a user who is not a member of the
cvs.texi(,13701) @code{cvsadmin} group tries to execute any @code{cvs admin}
cvs.texi(,13702) option which is not listed they will will receive an error message
cvs.texi(,13703) reporting that the option is restricted.
cvs.texi(,13704) 
cvs.texi(,13705) If no @code{cvsadmin} group exists on the server, @sc{cvs} will
cvs.texi(,13706) ignore the @code{UserAdminOptions} keyword (@pxref{admin}).
cvs.texi(,13707) 
cvs.texi(,13708) When not specified, @code{UserAdminOptions} defaults to
cvs.texi(,13709) @samp{k}.  In other words, it defaults to allowing
cvs.texi(,13710) users outside of the @code{cvsadmin} group to use the
cvs.texi(,13711) @code{cvs admin} command only to change the default keyword
cvs.texi(,13712) expansion mode for files.
cvs.texi(,13713) 
cvs.texi(,13714) As an example, to restrict users not in the @code{cvsadmin}
cvs.texi(,13715) group to using @code{cvs admin} to change the default keyword
cvs.texi(,13716) substitution mode, lock revisions, unlock revisions, and
cvs.texi(,13717) replace the log message, use @samp{UserAdminOptions=klum}.
cvs.texi(,13718) @end table
cvs.texi(,13719) 
cvs.texi(,13720) @c ---------------------------------------------------------------------
cvs.texi(,13721) @node Environment variables
cvs.texi(,13722) @appendix All environment variables which affect CVS
cvs.texi(,13723) @cindex Environment variables
cvs.texi(,13724) @cindex Reference manual for variables
cvs.texi(,13725) 
cvs.texi(,13726) This is a complete list of all environment variables
cvs.texi(,13727) that affect @sc{cvs}.
cvs.texi(,13728) 
cvs.texi(,13729) @table @code
cvs.texi(,13730) @cindex CVSIGNORE, environment variable
cvs.texi(,13731) @item $CVSIGNORE
cvs.texi(,13732) A whitespace-separated list of file name patterns that
cvs.texi(,13733) @sc{cvs} should ignore. @xref{cvsignore}.
cvs.texi(,13734) 
cvs.texi(,13735) @cindex CVSWRAPPERS, environment variable
cvs.texi(,13736) @item $CVSWRAPPERS
cvs.texi(,13737) A whitespace-separated list of file name patterns that
cvs.texi(,13738) @sc{cvs} should treat as wrappers. @xref{Wrappers}.
cvs.texi(,13739) 
cvs.texi(,13740) @cindex CVSREAD, environment variable
cvs.texi(,13741) @cindex Read-only files, and CVSREAD
cvs.texi(,13742) @item $CVSREAD
cvs.texi(,13743) If this is set, @code{checkout} and @code{update} will
cvs.texi(,13744) try hard to make the files in your working directory
cvs.texi(,13745) read-only.  When this is not set, the default behavior
cvs.texi(,13746) is to permit modification of your working files.
cvs.texi(,13747) 
cvs.texi(,13748) @cindex CVSREADONLYFS, environment variable
cvs.texi(,13749) @item $CVSREADONLYFS
cvs.texi(,13750) Turns on read-only repository mode. This allows one to
cvs.texi(,13751) check out from a read-only repository, such as within
cvs.texi(,13752) an anoncvs server, or from a CDROM repository.
cvs.texi(,13753) 
cvs.texi(,13754) It has the same effect as if the @samp{-R} command-line
cvs.texi(,13755) option is used. This can also allow the use of
cvs.texi(,13756) read-only NFS repositories.
cvs.texi(,13757) 
cvs.texi(,13758) @item $CVSUMASK
cvs.texi(,13759) Controls permissions of files in the repository.  See
cvs.texi(,13760) @ref{File permissions}.
cvs.texi(,13761) 
cvs.texi(,13762) @item $CVSROOT
cvs.texi(,13763) Should contain the full pathname to the root of the @sc{cvs}
cvs.texi(,13764) source repository (where the @sc{rcs} files are
cvs.texi(,13765) kept).  This information must be available to @sc{cvs} for
cvs.texi(,13766) most commands to execute; if @code{$CVSROOT} is not set,
cvs.texi(,13767) or if you wish to override it for one invocation, you
cvs.texi(,13768) can supply it on the command line: @samp{cvs -d cvsroot
cvs.texi(,13769) cvs_command@dots{}} Once you have checked out a working
cvs.texi(,13770) directory, @sc{cvs} stores the appropriate root (in
cvs.texi(,13771) the file @file{CVS/Root}), so normally you only need to
cvs.texi(,13772) worry about this when initially checking out a working
cvs.texi(,13773) directory.
cvs.texi(,13774) 
cvs.texi(,13775) @item $CVSEDITOR
cvs.texi(,13776) @cindex CVSEDITOR, environment variable
cvs.texi(,13777) @itemx $EDITOR
cvs.texi(,13778) @cindex EDITOR, environment variable
cvs.texi(,13779) @itemx $VISUAL
cvs.texi(,13780) @cindex VISUAL, environment variable
cvs.texi(,13781) Specifies the program to use for recording log messages
cvs.texi(,13782) during commit.  @code{$CVSEDITOR} overrides
cvs.texi(,13783) @code{$EDITOR}, which overrides @code{$VISUAL}.
cvs.texi(,13784) See @ref{Committing your changes} for more or
cvs.texi(,13785) @ref{Global options} for alternative ways of specifying a
cvs.texi(,13786) log editor.
cvs.texi(,13787) 
cvs.texi(,13788) @cindex PATH, environment variable
cvs.texi(,13789) @item $PATH
cvs.texi(,13790) If @code{$RCSBIN} is not set, and no path is compiled
cvs.texi(,13791) into @sc{cvs}, it will use @code{$PATH} to try to find all
cvs.texi(,13792) programs it uses.
cvs.texi(,13793) 
cvs.texi(,13794) @cindex HOME, environment variable
cvs.texi(,13795) @item $HOME
cvs.texi(,13796) @cindex HOMEPATH, environment variable
cvs.texi(,13797) @item $HOMEPATH
cvs.texi(,13798) @cindex HOMEDRIVE, environment variable
cvs.texi(,13799) @item $HOMEDRIVE
cvs.texi(,13800) Used to locate the directory where the @file{.cvsrc}
cvs.texi(,13801) file, and other such files, are searched.  On Unix, @sc{cvs}
cvs.texi(,13802) just checks for @code{HOME}.  On Windows NT, the system will
cvs.texi(,13803) set @code{HOMEDRIVE}, for example to @samp{d:} and @code{HOMEPATH},
cvs.texi(,13804) for example to @file{\joe}.  On Windows 95, you'll
cvs.texi(,13805) probably need to set @code{HOMEDRIVE} and @code{HOMEPATH} yourself.
cvs.texi(,13806) @c We are being vague about whether HOME works on
cvs.texi(,13807) @c Windows; see long comment in windows-NT/filesubr.c.
cvs.texi(,13808) 
cvs.texi(,13809) @cindex CVS_RSH, environment variable
cvs.texi(,13810) @item $CVS_RSH
cvs.texi(,13811) Specifies the external program which @sc{cvs} connects with,
cvs.texi(,13812) when @code{:ext:} access method is specified.
cvs.texi(,13813) @pxref{Connecting via rsh}.
cvs.texi(,13814) 
cvs.texi(,13815) @item $CVS_SERVER
cvs.texi(,13816) Used in client-server mode when accessing a remote
cvs.texi(,13817) repository using @sc{rsh}.  It specifies the name of
cvs.texi(,13818) the program to start on the server side (and any
cvs.texi(,13819) necessary arguments) when accessing a remote repository
cvs.texi(,13820) using the @code{:ext:}, @code{:fork:}, or @code{:server:} access methods.
cvs.texi(,13821) The default value for @code{:ext:} and @code{:server:} is @code{cvs};
cvs.texi(,13822) the default value for @code{:fork:} is the name used to run the client.
cvs.texi(,13823) @pxref{Connecting via rsh}
cvs.texi(,13824) 
cvs.texi(,13825) @item $CVS_PASSFILE
cvs.texi(,13826) Used in client-server mode when accessing the @code{cvs
cvs.texi(,13827) login server}.  Default value is @file{$HOME/.cvspass}.
cvs.texi(,13828) @pxref{Password authentication client}
cvs.texi(,13829) 
cvs.texi(,13830) @item $CVS_CLIENT_PORT
cvs.texi(,13831) Used in client-server mode to set the port to use when accessing the server
cvs.texi(,13832) via Kerberos, GSSAPI, or @sc{cvs}'s password authentication protocol
cvs.texi(,13833) if the port is not specified in the CVSROOT.
cvs.texi(,13834) @pxref{Remote repositories}
cvs.texi(,13835) 
cvs.texi(,13836) @cindex CVS_RCMD_PORT, environment variable
cvs.texi(,13837) @item $CVS_RCMD_PORT
cvs.texi(,13838) Used in client-server mode.  If set, specifies the port
cvs.texi(,13839) number to be used when accessing the @sc{rcmd} demon on
cvs.texi(,13840) the server side. (Currently not used for Unix clients).
cvs.texi(,13841) 
cvs.texi(,13842) @cindex CVS_CLIENT_LOG, environment variable
cvs.texi(,13843) @item $CVS_CLIENT_LOG
cvs.texi(,13844) Used for debugging only in client-server
cvs.texi(,13845) mode.  If set, everything sent to the server is logged
cvs.texi(,13846) into @file{@code{$CVS_CLIENT_LOG}.in} and everything
cvs.texi(,13847) sent from the server is logged into
cvs.texi(,13848) @file{@code{$CVS_CLIENT_LOG}.out}.
cvs.texi(,13849) 
cvs.texi(,13850) @cindex CVS_SERVER_SLEEP, environment variable
cvs.texi(,13851) @item $CVS_SERVER_SLEEP
cvs.texi(,13852) Used only for debugging the server side in
cvs.texi(,13853) client-server mode.  If set, delays the start of the
cvs.texi(,13854) server child process the specified amount of
cvs.texi(,13855) seconds so that you can attach to it with a debugger.
cvs.texi(,13856) 
cvs.texi(,13857) @cindex CVS_IGNORE_REMOTE_ROOT, environment variable
cvs.texi(,13858) @item $CVS_IGNORE_REMOTE_ROOT
cvs.texi(,13859) For @sc{cvs} 1.10 and older, setting this variable
cvs.texi(,13860) prevents @sc{cvs} from overwriting the @file{CVS/Root}
cvs.texi(,13861) file when the @samp{-d} global option is specified.
cvs.texi(,13862) Later versions of @sc{cvs} do not rewrite
cvs.texi(,13863) @file{CVS/Root}, so @code{CVS_IGNORE_REMOTE_ROOT} has no
cvs.texi(,13864) effect.
cvs.texi(,13865) 
cvs.texi(,13866) @cindex CVS_LOCAL_BRANCH_NUM, environment variable
cvs.texi(,13867) @item $CVS_LOCAL_BRANCH_NUM
cvs.texi(,13868) Setting this variable allows some control over the
cvs.texi(,13869) branch number that is assigned. This is specifically to
cvs.texi(,13870) support the local commit feature of CVSup. If one sets
cvs.texi(,13871) @code{CVS_LOCAL_BRANCH_NUM} to (say) 1000 then branches
cvs.texi(,13872) the local repository, the revision numbers will look
cvs.texi(,13873) like 1.66.1000.xx. There is almost a dead-set certainty
cvs.texi(,13874) that there will be no conflicts with version numbers.
cvs.texi(,13875) 
cvs.texi(,13876) @cindex COMSPEC, environment variable
cvs.texi(,13877) @item $COMSPEC
cvs.texi(,13878) Used under OS/2 only.  It specifies the name of the
cvs.texi(,13879) command interpreter and defaults to @sc{cmd.exe}.
cvs.texi(,13880) 
cvs.texi(,13881) @cindex TMPDIR, environment variable
cvs.texi(,13882) @item $TMPDIR
cvs.texi(,13883) @cindex TMP, environment variable
cvs.texi(,13884) @itemx $TMP
cvs.texi(,13885) @cindex TEMP, environment variable
cvs.texi(,13886) @itemx $TEMP
cvs.texi(,13887) @cindex Temporary files, location of
cvs.texi(,13888) @c This is quite nuts.  We don't talk about tempnam
cvs.texi(,13889) @c or mkstemp which we sometimes use.  The discussion
cvs.texi(,13890) @c of "Global options" is semi-incoherent.
cvs.texi(,13891) @c I'm not even sure those are the only inaccuracies.
cvs.texi(,13892) @c Furthermore, the conventions are
cvs.texi(,13893) @c pretty crazy and they should be simplified.
cvs.texi(,13894) Directory in which temporary files are located.
cvs.texi(,13895) The @sc{cvs} server uses
cvs.texi(,13896) @code{TMPDIR}.  @xref{Global options}, for a
cvs.texi(,13897) description of how to specify this.
cvs.texi(,13898) Some parts of @sc{cvs} will always use @file{/tmp} (via
cvs.texi(,13899) the @code{tmpnam} function provided by the system).
cvs.texi(,13900) 
cvs.texi(,13901) On Windows NT, @code{TMP} is used (via the @code{_tempnam}
cvs.texi(,13902) function provided by the system).
cvs.texi(,13903) 
cvs.texi(,13904) The @code{patch} program which is used by the @sc{cvs}
cvs.texi(,13905) client uses @code{TMPDIR}, and if it is not set, uses
cvs.texi(,13906) @file{/tmp} (at least with GNU patch 2.1).  Note that
cvs.texi(,13907) if your server and client are both running @sc{cvs}
cvs.texi(,13908) 1.9.10 or later, @sc{cvs} will not invoke an external
cvs.texi(,13909) @code{patch} program.
cvs.texi(,13910) 
cvs.texi(,13911) @cindex CVS_PID, environment variable
cvs.texi(,13912) @item $CVS_PID
cvs.texi(,13913) This is the process identification (aka pid) number of
cvs.texi(,13914) the @sc{cvs} process. It is often useful in the
cvs.texi(,13915) programs and/or scripts specified by the
cvs.texi(,13916) @file{commitinfo}, @file{verifymsg}, @file{loginfo}
cvs.texi(,13917) files.
cvs.texi(,13918) @end table
cvs.texi(,13919) 
cvs.texi(,13920) @node Compatibility
cvs.texi(,13921) @appendix Compatibility between CVS Versions
cvs.texi(,13922) 
cvs.texi(,13923) @cindex CVS, versions of
cvs.texi(,13924) @cindex Versions, of CVS
cvs.texi(,13925) @cindex Compatibility, between CVS versions
cvs.texi(,13926) @c We don't mention versions older than CVS 1.3
cvs.texi(,13927) @c on the theory that it would clutter it up for the vast
cvs.texi(,13928) @c majority of people, who don't have anything that old.
cvs.texi(,13929) @c
cvs.texi(,13930) The repository format is compatible going back to
cvs.texi(,13931) @sc{cvs} 1.3.  But see @ref{Watches Compatibility}, if
cvs.texi(,13932) you have copies of @sc{cvs} 1.6 or older and you want
cvs.texi(,13933) to use the optional developer communication features.
cvs.texi(,13934) @c If you "cvs rm" and commit using 1.3, then you'll
cvs.texi(,13935) @c want to run "rcs -sdead <file,v>" on each of the
cvs.texi(,13936) @c files in the Attic if you then want 1.5 and
cvs.texi(,13937) @c later to recognize those files as dead (I think the
cvs.texi(,13938) @c symptom if this is not done is that files reappear
cvs.texi(,13939) @c in joins).  (Wait: the above will work but really to
cvs.texi(,13940) @c be strictly correct we should suggest checking
cvs.texi(,13941) @c in a new revision rather than just changing the
cvs.texi(,13942) @c state of the head revision, shouldn't we?).
cvs.texi(,13943) @c The old convert.sh script was for this, but it never
cvs.texi(,13944) @c did get updated to reflect use of the RCS "dead"
cvs.texi(,13945) @c state.
cvs.texi(,13946) @c Note: this is tricky to document without confusing
cvs.texi(,13947) @c people--need to carefully say what CVS version we
cvs.texi(,13948) @c are talking about and keep in mind the distinction
cvs.texi(,13949) @c between a
cvs.texi(,13950) @c repository created with 1.3 and on which one now
cvs.texi(,13951) @c uses 1.5+, and a repository on which one wants to
cvs.texi(,13952) @c use both versions side by side (e.g. during a
cvs.texi(,13953) @c transition period).
cvs.texi(,13954) @c Wait, can't CVS just detect the case in which a file
cvs.texi(,13955) @c is in the Attic but the head revision is not dead?
cvs.texi(,13956) @c Not sure whether this should produce a warning or
cvs.texi(,13957) @c something, and probably needs further thought, but
cvs.texi(,13958) @c it would appear that the situation can be detected.
cvs.texi(,13959) @c
cvs.texi(,13960) @c We might want to separate out the 1.3 compatibility
cvs.texi(,13961) @c section (for repository & working directory) from the
cvs.texi(,13962) @c rest--that might help avoid confusing people who
cvs.texi(,13963) @c are upgrading (for example) from 1.6 to 1.8.
cvs.texi(,13964) @c
cvs.texi(,13965) @c A minor incompatibility is if a current version of CVS
cvs.texi(,13966) @c puts "Nfoo" into CVS/Tag, then CVS 1.9 or older will
cvs.texi(,13967) @c see this as if there is no tag.  Seems to me this is
cvs.texi(,13968) @c too obscure to mention.
cvs.texi(,13969) 
cvs.texi(,13970) The working directory format is compatible going back
cvs.texi(,13971) to @sc{cvs} 1.5.  It did change between @sc{cvs} 1.3
cvs.texi(,13972) and @sc{cvs} 1.5.  If you run @sc{cvs} 1.5 or newer on
cvs.texi(,13973) a working directory checked out with @sc{cvs} 1.3,
cvs.texi(,13974) @sc{cvs} will convert it, but to go back to @sc{cvs}
cvs.texi(,13975) 1.3 you need to check out a new working directory with
cvs.texi(,13976) @sc{cvs} 1.3.
cvs.texi(,13977) 
cvs.texi(,13978) The remote protocol is interoperable going back to @sc{cvs} 1.5, but no
cvs.texi(,13979) further (1.5 was the first official release with the remote protocol,
cvs.texi(,13980) but some older versions might still be floating around).  In many
cvs.texi(,13981) cases you need to upgrade both the client and the server to take
cvs.texi(,13982) advantage of new features and bugfixes, however.
cvs.texi(,13983) 
cvs.texi(,13984) @c Perhaps should be saying something here about the
cvs.texi(,13985) @c "D" lines in Entries (written by CVS 1.9; 1.8 and
cvs.texi(,13986) @c older don't use them).  These are supposed to be
cvs.texi(,13987) @c compatible in both directions, but I'm not sure
cvs.texi(,13988) @c they quite are 100%.  One common gripe is if you
cvs.texi(,13989) @c "rm -r" a directory and 1.9 gets confused, as it
cvs.texi(,13990) @c still sees it in Entries.  That one is fixed in
cvs.texi(,13991) @c (say) 1.9.6.  Someone else reported problems with
cvs.texi(,13992) @c starting with a directory which was checked out with
cvs.texi(,13993) @c an old version, and then using a new version, and
cvs.texi(,13994) @c some "D" lines appeared, but not for every
cvs.texi(,13995) @c directory, causing some directories to be skipped.
cvs.texi(,13996) @c They weren't sure how to reproduce this, though.
cvs.texi(,13997) 
cvs.texi(,13998) @c ---------------------------------------------------------------------
cvs.texi(,13999) @node Troubleshooting
cvs.texi(,14000) @appendix Troubleshooting
cvs.texi(,14001) 
cvs.texi(,14002) If you are having trouble with @sc{cvs}, this appendix
cvs.texi(,14003) may help.  If there is a particular error message which
cvs.texi(,14004) you are seeing, then you can look up the message
cvs.texi(,14005) alphabetically.  If not, you can look through the
cvs.texi(,14006) section on other problems to see if your problem is
cvs.texi(,14007) mentioned there.
cvs.texi(,14008) 
cvs.texi(,14009) @menu
cvs.texi(,14010) * Error messages::              Partial list of CVS errors
cvs.texi(,14011) * Connection::                  Trouble making a connection to a CVS server
cvs.texi(,14012) * Other problems::              Problems not readily listed by error message
cvs.texi(,14013) @end menu
cvs.texi(,14014) 
cvs.texi(,14022) 
cvs.texi(,14023) @node Error messages
cvs.texi(,14024) @appendixsec Partial list of error messages
cvs.texi(,14025) 
cvs.texi(,14026) Here is a partial list of error messages that you may
cvs.texi(,14027) see from @sc{cvs}.  It is not a complete list---@sc{cvs}
cvs.texi(,14028) is capable of printing many, many error messages, often
cvs.texi(,14029) with parts of them supplied by the operating system,
cvs.texi(,14030) but the intention is to list the common and/or
cvs.texi(,14031) potentially confusing error messages.
cvs.texi(,14032) 
cvs.texi(,14033) The messages are alphabetical, but introductory text
cvs.texi(,14034) such as @samp{cvs update: } is not considered in
cvs.texi(,14035) ordering them.
cvs.texi(,14036) 
cvs.texi(,14037) In some cases the list includes messages printed by old
cvs.texi(,14038) versions of @sc{cvs} (partly because users may not be
cvs.texi(,14039) sure which version of @sc{cvs} they are using at any
cvs.texi(,14040) particular moment).
cvs.texi(,14041) @c If we want to start retiring messages, perhaps we
cvs.texi(,14042) @c should pick a cutoff version (for example, no more
cvs.texi(,14043) @c messages which are specific to versions before 1.9)
cvs.texi(,14044) @c and then move the old messages to an "old messages"
cvs.texi(,14045) @c node rather than deleting them completely.
cvs.texi(,14046) 
cvs.texi(,14047) @table @code
cvs.texi(,14048) @c FIXME: What is the correct way to format a multiline
cvs.texi(,14049) @c error message here?  Maybe @table is the wrong
cvs.texi(,14050) @c choice?  Texinfo gurus?
cvs.texi(,14051) @item @var{file}:@var{line}: Assertion '@var{text}' failed
cvs.texi(,14052) The exact format of this message may vary depending on
cvs.texi(,14053) your system.  It indicates a bug in @sc{cvs}, which can
cvs.texi(,14054) be handled as described in @ref{BUGS}.
cvs.texi(,14055) 
cvs.texi(,14056) @item cvs @var{command}: authorization failed: server @var{host} rejected access
cvs.texi(,14057) This is a generic response when trying to connect to a
cvs.texi(,14058) pserver server which chooses not to provide a
cvs.texi(,14059) specific reason for denying authorization.  Check that
cvs.texi(,14060) the username and password specified are correct and
cvs.texi(,14061) that the @code{CVSROOT} specified is allowed by @samp{--allow-root}
cvs.texi(,14062) in @file{inetd.conf}.  See @ref{Password authenticated}.
cvs.texi(,14063) 
cvs.texi(,14064) @item cvs @var{command}: conflict: removed @var{file} was modified by second party
cvs.texi(,14065) This message indicates that you removed a file, and
cvs.texi(,14066) someone else modified it.  To resolve the conflict,
cvs.texi(,14067) first run @samp{cvs add @var{file}}.  If desired, look
cvs.texi(,14068) at the other party's modification to decide whether you
cvs.texi(,14069) still want to remove it.  If you don't want to remove
cvs.texi(,14070) it, stop here.  If you do want to remove it, proceed
cvs.texi(,14071) with @samp{cvs remove @var{file}} and commit your
cvs.texi(,14072) removal.
cvs.texi(,14073) @c Tests conflicts2-142b* in sanity.sh test for this.
cvs.texi(,14074) 
cvs.texi(,14075) @item cannot change permissions on temporary directory
cvs.texi(,14076) @example
cvs.texi(,14077) Operation not permitted
cvs.texi(,14078) @end example
cvs.texi(,14079) This message has been happening in a non-reproducible,
cvs.texi(,14080) occasional way when we run the client/server testsuite,
cvs.texi(,14081) both on Red Hat Linux 3.0.3 and 4.1.  We haven't been
cvs.texi(,14082) able to figure out what causes it, nor is it known
cvs.texi(,14083) whether it is specific to linux (or even to this
cvs.texi(,14084) particular machine!).  If the problem does occur on
cvs.texi(,14085) other unices, @samp{Operation not permitted} would be
cvs.texi(,14086) likely to read @samp{Not owner} or whatever the system
cvs.texi(,14087) in question uses for the unix @code{EPERM} error.  If
cvs.texi(,14088) you have any information to add, please let us know as
cvs.texi(,14089) described in @ref{BUGS}.  If you experience this error
cvs.texi(,14090) while using @sc{cvs}, retrying the operation which
cvs.texi(,14091) produced it should work fine.
cvs.texi(,14092) @c This has been seen in a variety of tests, including
cvs.texi(,14093) @c multibranch-2, multibranch-5, and basic1-24-rm-rm,
cvs.texi(,14094) @c so it doesn't seem particularly specific to any one
cvs.texi(,14095) @c test.
cvs.texi(,14096) 
cvs.texi(,14097) @item cvs [server aborted]: Cannot check out files into the repository itself
cvs.texi(,14098) The obvious cause for this message (especially for
cvs.texi(,14099) non-client/server @sc{cvs}) is that the @sc{cvs} root
cvs.texi(,14100) is, for example, @file{/usr/local/cvsroot} and you try
cvs.texi(,14101) to check out files when you are in a subdirectory, such
cvs.texi(,14102) as @file{/usr/local/cvsroot/test}.  However, there is a
cvs.texi(,14103) more subtle cause, which is that the temporary
cvs.texi(,14104) directory on the server is set to a subdirectory of the
cvs.texi(,14105) root (which is also not allowed).  If this is the
cvs.texi(,14106) problem, set the temporary directory to somewhere else,
cvs.texi(,14107) for example @file{/var/tmp}; see @code{TMPDIR} in
cvs.texi(,14108) @ref{Environment variables}, for how to set the
cvs.texi(,14109) temporary directory.
cvs.texi(,14110) 
cvs.texi(,14111) @item cannot commit files as 'root'
cvs.texi(,14112) See @samp{'root' is not allowed to commit files}.
cvs.texi(,14113) 
cvs.texi(,14114) @c For one example see basica-1a10 in the testsuite
cvs.texi(,14115) @c For another example, "cvs co ." on NT; see comment
cvs.texi(,14116) @c at windows-NT/filesubr.c (expand_wild).
cvs.texi(,14117) @c For another example, "cvs co foo/bar" where foo exists.
cvs.texi(,14118) @item cannot open CVS/Entries for reading: No such file or directory
cvs.texi(,14119) This generally indicates a @sc{cvs} internal error, and
cvs.texi(,14120) can be handled as with other @sc{cvs} bugs
cvs.texi(,14121) (@pxref{BUGS}).  Usually there is a workaround---the
cvs.texi(,14122) exact nature of which would depend on the situation but
cvs.texi(,14123) which hopefully could be figured out.
cvs.texi(,14124) 
cvs.texi(,14125) @c This is more obscure than it might sound; it only
cvs.texi(,14126) @c happens if you run "cvs init" from a directory which
cvs.texi(,14127) @c contains a CVS/Root file at the start.
cvs.texi(,14128) @item cvs [init aborted]: cannot open CVS/Root: No such file or directory
cvs.texi(,14129) This message is harmless.  Provided it is not
cvs.texi(,14130) accompanied by other errors, the operation has
cvs.texi(,14131) completed successfully.  This message should not occur
cvs.texi(,14132) with current versions of @sc{cvs}, but it is documented
cvs.texi(,14133) here for the benefit of @sc{cvs} 1.9 and older.
cvs.texi(,14134) 
cvs.texi(,14135) @item cvs server: cannot open /root/.cvsignore: Permission denied
cvs.texi(,14136) @itemx cvs [server aborted]: can't chdir(/root): Permission denied
cvs.texi(,14137) See @ref{Connection}.
cvs.texi(,14138) 
cvs.texi(,14139) @item cvs [checkout aborted]: cannot rename file @var{file} to CVS/,,@var{file}: Invalid argument
cvs.texi(,14140) This message has been reported as intermittently
cvs.texi(,14141) happening with @sc{cvs} 1.9 on Solaris 2.5.  The cause is
cvs.texi(,14142) unknown; if you know more about what causes it, let us
cvs.texi(,14143) know as described in @ref{BUGS}.
cvs.texi(,14144) 
cvs.texi(,14145) @item cvs [@var{command} aborted]: cannot start server via rcmd
cvs.texi(,14146) This, unfortunately, is a rather nonspecific error
cvs.texi(,14147) message which @sc{cvs} 1.9 will print if you are
cvs.texi(,14148) running the @sc{cvs} client and it is having trouble
cvs.texi(,14149) connecting to the server.  Current versions of @sc{cvs}
cvs.texi(,14150) should print a much more specific error message.  If
cvs.texi(,14151) you get this message when you didn't mean to run the
cvs.texi(,14152) client at all, you probably forgot to specify
cvs.texi(,14153) @code{:local:}, as described in @ref{Repository}.
cvs.texi(,14154) 
cvs.texi(,14155) @item ci: @var{file},v: bad diff output line: Binary files - and /tmp/T2a22651 differ
cvs.texi(,14156) @sc{cvs} 1.9 and older will print this message
cvs.texi(,14157) when trying to check in a binary file if
cvs.texi(,14158) @sc{rcs} is not correctly installed.  Re-read the
cvs.texi(,14159) instructions that came with your @sc{rcs} distribution
cvs.texi(,14160) and the @sc{install} file in the @sc{cvs}
cvs.texi(,14161) distribution.  Alternately, upgrade to a current
cvs.texi(,14162) version of @sc{cvs}, which checks in files itself
cvs.texi(,14163) rather than via @sc{rcs}.
cvs.texi(,14164) 
cvs.texi(,14165) @item cvs checkout: could not check out @var{file}
cvs.texi(,14166) With @sc{cvs} 1.9, this can mean that the @code{co} program
cvs.texi(,14167) (part of @sc{rcs}) returned a failure.  It should be
cvs.texi(,14168) preceded by another error message, however it has been
cvs.texi(,14169) observed without another error message and the cause is
cvs.texi(,14170) not well-understood.  With the current version of @sc{cvs},
cvs.texi(,14171) which does not run @code{co}, if this message occurs
cvs.texi(,14172) without another error message, it is definitely a @sc{cvs}
cvs.texi(,14173) bug (@pxref{BUGS}).
cvs.texi(,14174) @c My current suspicion is that the RCS in the rcs (not
cvs.texi(,14175) @c cvs/winnt/rcs57nt.zip) directory on the _Practical_
cvs.texi(,14176) @c CD is bad (remains to be confirmed).
cvs.texi(,14177) @c There is also a report of something which looks
cvs.texi(,14178) @c very similar on SGI, Irix 5.2, so I dunno.
cvs.texi(,14179) 
cvs.texi(,14180) @item cvs [login aborted]: could not find out home directory
cvs.texi(,14181) This means that you need to set the environment
cvs.texi(,14182) variables that @sc{cvs} uses to locate your home directory.
cvs.texi(,14183) See the discussion of @code{HOME}, @code{HOMEDRIVE}, and @code{HOMEPATH} in
cvs.texi(,14184) @ref{Environment variables}.
cvs.texi(,14185) 
cvs.texi(,14186) @item cvs update: could not merge revision @var{rev} of @var{file}: No such file or directory
cvs.texi(,14187) @sc{cvs} 1.9 and older will print this message if there was
cvs.texi(,14188) a problem finding the @code{rcsmerge} program.  Make
cvs.texi(,14189) sure that it is in your @code{PATH}, or upgrade to a
cvs.texi(,14190) current version of @sc{cvs}, which does not require
cvs.texi(,14191) an external @code{rcsmerge} program.
cvs.texi(,14192) 
cvs.texi(,14193) @item cvs [update aborted]: could not patch @var{file}: No such file or directory
cvs.texi(,14194) This means that there was a problem finding the
cvs.texi(,14195) @code{patch} program.  Make sure that it is in your
cvs.texi(,14196) @code{PATH}.  Note that despite appearances the message
cvs.texi(,14197) is @emph{not} referring to whether it can find @var{file}.
cvs.texi(,14198) If both the client and the server are running a current
cvs.texi(,14199) version of @sc{cvs}, then there is no need for an
cvs.texi(,14200) external patch program and you should not see this
cvs.texi(,14201) message.  But if either client or server is running
cvs.texi(,14202) @sc{cvs} 1.9, then you need @code{patch}.
cvs.texi(,14203) 
cvs.texi(,14204) @item cvs update: could not patch @var{file}; will refetch
cvs.texi(,14205) This means that for whatever reason the client was
cvs.texi(,14206) unable to apply a patch that the server sent.  The
cvs.texi(,14207) message is nothing to be concerned about, because
cvs.texi(,14208) inability to apply the patch only slows things down and
cvs.texi(,14209) has no effect on what @sc{cvs} does.
cvs.texi(,14210) @c xref to update output.  Or File status?
cvs.texi(,14211) @c Or some place else that
cvs.texi(,14212) @c explains this whole "patch"/P/Needs Patch thing?
cvs.texi(,14213) 
cvs.texi(,14214) @item dying gasps from @var{server} unexpected
cvs.texi(,14215) There is a known bug in the server for @sc{cvs} 1.9.18
cvs.texi(,14216) and older which can cause this.  For me, this was
cvs.texi(,14217) reproducible if I used the @samp{-t} global option.  It
cvs.texi(,14218) was fixed by Andy Piper's 14 Nov 1997 change to
cvs.texi(,14219) src/filesubr.c, if anyone is curious.
cvs.texi(,14220) If you see the message,
cvs.texi(,14221) you probably can just retry the operation which failed,
cvs.texi(,14222) or if you have discovered information concerning its
cvs.texi(,14223) cause, please let us know as described in @ref{BUGS}.
cvs.texi(,14224) 
cvs.texi(,14225) @item end of file from server (consult above messages if any)
cvs.texi(,14226) The most common cause for this message is if you are
cvs.texi(,14227) using an external @code{rsh} program and it exited with
cvs.texi(,14228) an error.  In this case the @code{rsh} program should
cvs.texi(,14229) have printed a message, which will appear before the
cvs.texi(,14230) above message.  For more information on setting up a
cvs.texi(,14231) @sc{cvs} client and server, see @ref{Remote repositories}.
cvs.texi(,14232) 
cvs.texi(,14233) @item cvs [update aborted]: EOF in key in RCS file @var{file},v
cvs.texi(,14234) @itemx cvs [checkout aborted]: EOF while looking for end of string in RCS file @var{file},v
cvs.texi(,14235) This means that there is a syntax error in the given
cvs.texi(,14236) @sc{rcs} file.  Note that this might be true even if @sc{rcs} can
cvs.texi(,14237) read the file OK; @sc{cvs} does more error checking of
cvs.texi(,14238) errors in the RCS file.  That is why you may see this
cvs.texi(,14239) message when upgrading from @sc{cvs} 1.9 to @sc{cvs}
cvs.texi(,14240) 1.10.  The likely cause for the original corruption is
cvs.texi(,14241) hardware, the operating system, or the like.  Of
cvs.texi(,14242) course, if you find a case in which @sc{cvs} seems to
cvs.texi(,14243) corrupting the file, by all means report it,
cvs.texi(,14244) (@pxref{BUGS}).
cvs.texi(,14245) There are quite a few variations of this error message,
cvs.texi(,14246) depending on exactly where in the @sc{rcs} file @sc{cvs}
cvs.texi(,14247) finds the syntax error.
cvs.texi(,14248) 
cvs.texi(,14249) @cindex mkmodules
cvs.texi(,14250) @item cvs commit: Executing 'mkmodules'
cvs.texi(,14251) This means that your repository is set up for a version
cvs.texi(,14252) of @sc{cvs} prior to @sc{cvs} 1.8.  When using @sc{cvs}
cvs.texi(,14253) 1.8 or later, the above message will be preceded by
cvs.texi(,14254) 
cvs.texi(,14255) @example
cvs.texi(,14256) cvs commit: Rebuilding administrative file database
cvs.texi(,14257) @end example
cvs.texi(,14258) 
cvs.texi(,14259) If you see both messages, the database is being rebuilt
cvs.texi(,14260) twice, which is unnecessary but harmless.  If you wish
cvs.texi(,14261) to avoid the duplication, and you have no versions of
cvs.texi(,14262) @sc{cvs} 1.7 or earlier in use, remove @code{-i mkmodules}
cvs.texi(,14263) every place it appears in your @code{modules}
cvs.texi(,14264) file.  For more information on the @code{modules} file,
cvs.texi(,14265) see @ref{modules}.
cvs.texi(,14266) 
cvs.texi(,14267) @c This message comes from "co", and I believe is
cvs.texi(,14268) @c possible only with older versions of CVS which call
cvs.texi(,14269) @c co.  The problem with being able to create the bogus
cvs.texi(,14270) @c RCS file still exists, though (and I think maybe
cvs.texi(,14271) @c there is a different symptom(s) now).
cvs.texi(,14272) @c FIXME: Would be nice to have a more exact wording
cvs.texi(,14273) @c for this message.
cvs.texi(,14274) @item missing author
cvs.texi(,14275) Typically this can happen if you created an RCS file
cvs.texi(,14276) with your username set to empty.  @sc{cvs} will, bogusly,
cvs.texi(,14277) create an illegal RCS file with no value for the author
cvs.texi(,14278) field.  The solution is to make sure your username is
cvs.texi(,14279) set to a non-empty value and re-create the RCS file.
cvs.texi(,14280) @c "make sure your username is set" is complicated in
cvs.texi(,14281) @c and of itself, as there are the environment
cvs.texi(,14282) @c variables the system login name, &c, and it depends
cvs.texi(,14283) @c on the version of CVS.
cvs.texi(,14284) 
cvs.texi(,14285) @item cvs [checkout aborted]: no such tag @var{tag}
cvs.texi(,14286) This message means that @sc{cvs} isn't familiar with
cvs.texi(,14287) the tag @var{tag}.  Usually this means that you have
cvs.texi(,14288) mistyped a tag name; however there are (relatively
cvs.texi(,14289) obscure) cases in which @sc{cvs} will require you to
cvs.texi(,14290) @c Search sanity.sh for "no such tag" to see some of
cvs.texi(,14291) @c the relatively obscure cases.
cvs.texi(,14292) try a few other @sc{cvs} commands involving that tag,
cvs.texi(,14293) before you find one which will cause @sc{cvs} to update
cvs.texi(,14294) the @file{val-tags} file; see discussion of val-tags in
cvs.texi(,14295) @ref{File permissions}.  You only need to worry about
cvs.texi(,14296) this once for a given tag; when a tag is listed in
cvs.texi(,14297) @file{val-tags}, it stays there.  Note that using
cvs.texi(,14298) @samp{-f} to not require tag matches does not override
cvs.texi(,14299) this check; see @ref{Common options}.
cvs.texi(,14300) 
cvs.texi(,14301) @item *PANIC* administration files missing
cvs.texi(,14302) This typically means that there is a directory named
cvs.texi(,14303) @sc{cvs} but it does not contain the administrative files
cvs.texi(,14304) which @sc{cvs} puts in a CVS directory.  If the problem is
cvs.texi(,14305) that you created a CVS directory via some mechanism
cvs.texi(,14306) other than @sc{cvs}, then the answer is simple, use a name
cvs.texi(,14307) other than @sc{cvs}.  If not, it indicates a @sc{cvs} bug
cvs.texi(,14308) (@pxref{BUGS}).
cvs.texi(,14309) 
cvs.texi(,14310) @item rcs error: Unknown option: -x,v/
cvs.texi(,14311) This message will be followed by a usage message for
cvs.texi(,14312) @sc{rcs}.  It means that you have an old version of
cvs.texi(,14313) @sc{rcs} (probably supplied with your operating
cvs.texi(,14314) system), as well as an old version of @sc{cvs}.
cvs.texi(,14315) @sc{cvs} 1.9.18 and earlier only work with @sc{rcs} version 5 and
cvs.texi(,14316) later; current versions of @sc{cvs} do not run @sc{rcs} programs.
cvs.texi(,14317) @c For more information on installing @sc{cvs}, see
cvs.texi(,14318) @c (FIXME: where?  it depends on whether you are
cvs.texi(,14319) @c getting binaries or sources or what).
cvs.texi(,14320) @c The message can also say "ci error" or something
cvs.texi(,14321) @c instead of "rcs error", I suspect.
cvs.texi(,14322) 
cvs.texi(,14323) @item cvs [server aborted]: received broken pipe signal
cvs.texi(,14324) This message seems to be caused by a hard-to-track-down
cvs.texi(,14325) bug in @sc{cvs} or the systems it runs on (we don't
cvs.texi(,14326) know---we haven't tracked it down yet!).  It seems to
cvs.texi(,14327) happen only after a @sc{cvs} command has completed, and
cvs.texi(,14328) you should be able to just ignore the message.
cvs.texi(,14329) However, if you have discovered information concerning its
cvs.texi(,14330) cause, please let us know as described in @ref{BUGS}.
cvs.texi(,14331) 
cvs.texi(,14332) @item 'root' is not allowed to commit files
cvs.texi(,14333) When committing a permanent change, @sc{cvs} makes a log entry of
cvs.texi(,14334) who committed the change.  If you are committing the change logged
cvs.texi(,14335) in as "root" (not under "su" or other root-priv giving program),
cvs.texi(,14336) @sc{cvs} cannot determine who is actually making the change.
cvs.texi(,14337) As such, by default, @sc{cvs} disallows changes to be committed by users
cvs.texi(,14338) logged in as "root".  (You can disable this option by passing the
cvs.texi(,14339) @code{--enable-rootcommit} option to @file{configure} and recompiling @sc{cvs}.
cvs.texi(,14340) On some systems this means editing the appropriate @file{config.h} file
cvs.texi(,14341) before building @sc{cvs}.)
cvs.texi(,14342) 
cvs.texi(,14343) @item Too many arguments!
cvs.texi(,14344) This message is typically printed by the @file{log.pl}
cvs.texi(,14345) script which is in the @file{contrib} directory in the
cvs.texi(,14346) @sc{cvs} source distribution.  In some versions of
cvs.texi(,14347) @sc{cvs}, @file{log.pl} has been part of the default
cvs.texi(,14348) @sc{cvs} installation.  The @file{log.pl} script gets
cvs.texi(,14349) called from the @file{loginfo} administrative file.
cvs.texi(,14350) Check that the arguments passed in @file{loginfo} match
cvs.texi(,14351) what your version of @file{log.pl} expects.  In
cvs.texi(,14352) particular, the @file{log.pl} from @sc{cvs} 1.3 and
cvs.texi(,14353) older expects the logfile as an argument whereas the
cvs.texi(,14354) @file{log.pl} from @sc{cvs} 1.5 and newer expects the
cvs.texi(,14355) logfile to be specified with a @samp{-f} option.  Of
cvs.texi(,14356) course, if you don't need @file{log.pl} you can just
cvs.texi(,14357) comment it out of @file{loginfo}.
cvs.texi(,14358) 
cvs.texi(,14359) @item cvs [update aborted]: unexpected EOF reading @var{file},v
cvs.texi(,14360) See @samp{EOF in key in RCS file}.
cvs.texi(,14361) 
cvs.texi(,14362) @item cvs [login aborted]: unrecognized auth response from @var{server}
cvs.texi(,14363) This message typically means that the server is not set
cvs.texi(,14364) up properly.  For example, if @file{inetd.conf} points
cvs.texi(,14365) to a nonexistent cvs executable.  To debug it further,
cvs.texi(,14366) find the log file which inetd writes
cvs.texi(,14367) (@file{/var/log/messages} or whatever inetd uses on
cvs.texi(,14368) your system).  For details, see @ref{Connection}, and
cvs.texi(,14369) @ref{Password authentication server}.
cvs.texi(,14370) 
cvs.texi(,14371) @item cvs commit: Up-to-date check failed for `@var{file}'
cvs.texi(,14372) This means that someone else has committed a change to
cvs.texi(,14373) that file since the last time that you did a @code{cvs
cvs.texi(,14374) update}.  So before proceeding with your @code{cvs
cvs.texi(,14375) commit} you need to @code{cvs update}.  @sc{cvs} will merge
cvs.texi(,14376) the changes that you made and the changes that the
cvs.texi(,14377) other person made.  If it does not detect any conflicts
cvs.texi(,14378) it will report @samp{M @var{file}} and you are ready
cvs.texi(,14379) to @code{cvs commit}.  If it detects conflicts it will
cvs.texi(,14380) print a message saying so, will report @samp{C @var{file}},
cvs.texi(,14381) and you need to manually resolve the
cvs.texi(,14382) conflict.  For more details on this process see
cvs.texi(,14383) @ref{Conflicts example}.
cvs.texi(,14384) 
cvs.texi(,14385) @item Usage:	diff3 [-exEX3 [-i | -m] [-L label1 -L label3]] file1 file2 file3
cvs.texi(,14386) @example
cvs.texi(,14387) Only one of [exEX3] allowed
cvs.texi(,14388) @end example
cvs.texi(,14389) This indicates a problem with the installation of
cvs.texi(,14390) @code{diff3} and @code{rcsmerge}.  Specifically
cvs.texi(,14391) @code{rcsmerge} was compiled to look for GNU diff3, but
cvs.texi(,14392) it is finding unix diff3 instead.  The exact text of
cvs.texi(,14393) the message will vary depending on the system.  The
cvs.texi(,14394) simplest solution is to upgrade to a current version of
cvs.texi(,14395) @sc{cvs}, which does not rely on external
cvs.texi(,14396) @code{rcsmerge} or @code{diff3} programs.
cvs.texi(,14397) 
cvs.texi(,14398) @item warning: unrecognized response `@var{text}' from cvs server
cvs.texi(,14399) If @var{text} contains a valid response (such as
cvs.texi(,14400) @samp{ok}) followed by an extra carriage return
cvs.texi(,14401) character (on many systems this will cause the second
cvs.texi(,14402) part of the message to overwrite the first part), then
cvs.texi(,14403) it probably means that you are using the @samp{:ext:}
cvs.texi(,14404) access method with a version of rsh, such as most
cvs.texi(,14405) non-unix rsh versions, which does not by default
cvs.texi(,14406) provide a transparent data stream.  In such cases you
cvs.texi(,14407) probably want to try @samp{:server:} instead of
cvs.texi(,14408) @samp{:ext:}.  If @var{text} is something else, this
cvs.texi(,14409) may signify a problem with your @sc{cvs} server.
cvs.texi(,14410) Double-check your installation against the instructions
cvs.texi(,14411) for setting up the @sc{cvs} server.
cvs.texi(,14412) @c FIXCVS: should be printing CR as \r or \015 or some
cvs.texi(,14413) @c such, probably.
cvs.texi(,14414) 
cvs.texi(,14415) @item cvs commit: [@var{time}] waiting for @var{user}'s lock in @var{directory}
cvs.texi(,14416) This is a normal message, not an error.  See
cvs.texi(,14417) @ref{Concurrency}, for more details.
cvs.texi(,14418) 
cvs.texi(,14419) @item cvs commit: warning: editor session failed
cvs.texi(,14420) @cindex Exit status, of editor
cvs.texi(,14421) This means that the editor which @sc{cvs} is using exits with a nonzero
cvs.texi(,14422) exit status.  Some versions of vi will do this even when there was not
cvs.texi(,14423) a problem editing the file.  If so, point the
cvs.texi(,14424) @code{CVSEDITOR} environment variable to a small script
cvs.texi(,14425) such as:
cvs.texi(,14426) 
cvs.texi(,14427) @example
cvs.texi(,14428) #!/bin/sh
cvs.texi(,14429) vi $*
cvs.texi(,14430) exit 0
cvs.texi(,14431) @end example
cvs.texi(,14432) 
cvs.texi(,14433) @c "warning: foo was lost" and "no longer pertinent" (both normal).
cvs.texi(,14434) @c Would be nice to write these up--they are
cvs.texi(,14435) @c potentially confusing for the new user.
cvs.texi(,14436) @end table
cvs.texi(,14437) 
cvs.texi(,14438) @node Connection
cvs.texi(,14439) @appendixsec Trouble making a connection to a CVS server
cvs.texi(,14440) 
cvs.texi(,14441) This section concerns what to do if you are having
cvs.texi(,14442) trouble making a connection to a @sc{cvs} server.  If
cvs.texi(,14443) you are running the @sc{cvs} command line client
cvs.texi(,14444) running on Windows, first upgrade the client to
cvs.texi(,14445) @sc{cvs} 1.9.12 or later.  The error reporting in
cvs.texi(,14446) earlier versions provided much less information about
cvs.texi(,14447) what the problem was.  If the client is non-Windows,
cvs.texi(,14448) @sc{cvs} 1.9 should be fine.
cvs.texi(,14449) 
cvs.texi(,14450) If the error messages are not sufficient to track down
cvs.texi(,14451) the problem, the next steps depend largely on which
cvs.texi(,14452) access method you are using.
cvs.texi(,14453) 
cvs.texi(,14454) @table @code
cvs.texi(,14455) @cindex :ext:, troubleshooting
cvs.texi(,14456) @item :ext:
cvs.texi(,14457) Try running the rsh program from the command line.  For
cvs.texi(,14458) example: "rsh servername cvs -v" should print @sc{cvs}
cvs.texi(,14459) version information.  If this doesn't work, you need to
cvs.texi(,14460) fix it before you can worry about @sc{cvs} problems.
cvs.texi(,14461) 
cvs.texi(,14462) @cindex :server:, troubleshooting
cvs.texi(,14463) @item :server:
cvs.texi(,14464) You don't need a command line rsh program to use this
cvs.texi(,14465) access method, but if you have an rsh program around,
cvs.texi(,14466) it may be useful as a debugging tool.  Follow the
cvs.texi(,14467) directions given for :ext:.
cvs.texi(,14468) 
cvs.texi(,14469) @cindex :pserver:, troubleshooting
cvs.texi(,14470) @item :pserver:
cvs.texi(,14471) Errors along the lines of "connection refused" typically indicate
cvs.texi(,14472) that inetd isn't even listening for connections on port 2401
cvs.texi(,14473) whereas errors like "connection reset by peer",
cvs.texi(,14474) "received broken pipe signal", "recv() from server: EOF",
cvs.texi(,14475) or "end of file from server"
cvs.texi(,14476) typically indicate that inetd is listening for
cvs.texi(,14477) connections but is unable to start @sc{cvs} (this is frequently
cvs.texi(,14478) caused by having an incorrect path in @file{inetd.conf}
cvs.texi(,14479) or by firewall software rejecting the connection).
cvs.texi(,14480) "unrecognized auth response" errors are caused by a bad command
cvs.texi(,14481) line in @file{inetd.conf}, typically an invalid option or forgetting
cvs.texi(,14482) to put the @samp{pserver} command at the end of the line.
cvs.texi(,14483) Another less common problem is invisible control characters that
cvs.texi(,14484) your editor "helpfully" added without you noticing.
cvs.texi(,14485) 
cvs.texi(,14486) One good debugging tool is to "telnet servername
cvs.texi(,14487) 2401".  After connecting, send any text (for example
cvs.texi(,14488) "foo" followed by return).  If @sc{cvs} is working
cvs.texi(,14489) correctly, it will respond with
cvs.texi(,14490) 
cvs.texi(,14491) @example
cvs.texi(,14492) cvs [pserver aborted]: bad auth protocol start: foo
cvs.texi(,14493) @end example
cvs.texi(,14494) 
cvs.texi(,14495) If instead you get:
cvs.texi(,14496) 
cvs.texi(,14497) @example
cvs.texi(,14498) Usage: cvs [cvs-options] command [command-options-and-arguments]
cvs.texi(,14499) ...
cvs.texi(,14500) @end example
cvs.texi(,14501) 
cvs.texi(,14502) @noindent
cvs.texi(,14503) then you're missing the @samp{pserver} command at the end of the
cvs.texi(,14504) line in @file{inetd.conf}; check to make sure that the entire command
cvs.texi(,14505) is on one line and that it's complete.
cvs.texi(,14506) 
cvs.texi(,14507) Likewise, if you get something like:
cvs.texi(,14508) 
cvs.texi(,14509) @example
cvs.texi(,14510) Unknown command: `pserved'
cvs.texi(,14511) 
cvs.texi(,14512) CVS commands are:
cvs.texi(,14513)         add          Add a new file/directory to the repository
cvs.texi(,14514) ...
cvs.texi(,14515) @end example
cvs.texi(,14516) 
cvs.texi(,14517) @noindent
cvs.texi(,14518) then you've misspelled @samp{pserver} in some way.  If it isn't
cvs.texi(,14519) obvious, check for invisible control characters (particularly
cvs.texi(,14520) carriage returns) in @file{inetd.conf}.
cvs.texi(,14521) 
cvs.texi(,14522) If it fails to work at all, then make sure inetd is working
cvs.texi(,14523) right.  Change the invocation in @file{inetd.conf} to run the
cvs.texi(,14524) echo program instead of cvs.  For example:
cvs.texi(,14525) 
cvs.texi(,14526) @example
cvs.texi(,14527) 2401  stream  tcp  nowait  root /bin/echo echo hello
cvs.texi(,14528) @end example
cvs.texi(,14529) 
cvs.texi(,14530) After making that change and instructing inetd to
cvs.texi(,14531) re-read its configuration file, "telnet servername
cvs.texi(,14532) 2401" should show you the text hello and then the
cvs.texi(,14533) server should close the connection.  If this doesn't
cvs.texi(,14534) work, you need to fix it before you can worry about
cvs.texi(,14535) @sc{cvs} problems.
cvs.texi(,14536) 
cvs.texi(,14537) On AIX systems, the system will often have its own
cvs.texi(,14538) program trying to use port 2401.  This is AIX's problem
cvs.texi(,14539) in the sense that port 2401 is registered for use with
cvs.texi(,14540) @sc{cvs}.  I hear that there is an AIX patch available
cvs.texi(,14541) to address this problem.
cvs.texi(,14542) 
cvs.texi(,14543) Another good debugging tool is the @samp{-d}
cvs.texi(,14544) (debugging) option to inetd.  Consult your system
cvs.texi(,14545) documentation for more information.
cvs.texi(,14546) 
cvs.texi(,14547) If you seem to be connecting but get errors like:
cvs.texi(,14548) 
cvs.texi(,14549) @example
cvs.texi(,14550) cvs server: cannot open /root/.cvsignore: Permission denied
cvs.texi(,14551) cvs [server aborted]: can't chdir(/root): Permission denied
cvs.texi(,14552) @end example
cvs.texi(,14553) 
cvs.texi(,14554) @noindent
cvs.texi(,14555) then you probably haven't specified @samp{-f} in @file{inetd.conf}.
cvs.texi(,14556) (In releases prior to @sc{cvs} 1.11.1, this problem can be caused by
cvs.texi(,14557) your system setting the @code{$HOME} environment variable
cvs.texi(,14558) for programs being run by inetd.  In this case, you can either
cvs.texi(,14559) have inetd run a shell script that unsets @code{$HOME} and then runs
cvs.texi(,14560) @sc{cvs}, or you can use @code{env} to run @sc{cvs} with a pristine
cvs.texi(,14561) environment.)
cvs.texi(,14562) 
cvs.texi(,14563) If you can connect successfully for a while but then can't,
cvs.texi(,14564) you've probably hit inetd's rate limit.
cvs.texi(,14565) (If inetd receives too many requests for the same service
cvs.texi(,14566) in a short period of time, it assumes that something is wrong
cvs.texi(,14567) and temporarily disables the service.)
cvs.texi(,14568) Check your inetd documentation to find out how to adjust the
cvs.texi(,14569) rate limit (some versions of inetd have a single rate limit,
cvs.texi(,14570) others allow you to set the limit for each service separately.)
cvs.texi(,14571) @end table
cvs.texi(,14572) 
cvs.texi(,14573) @node Other problems
cvs.texi(,14574) @appendixsec Other common problems
cvs.texi(,14575) 
cvs.texi(,14576) Here is a list of problems which do not fit into the
cvs.texi(,14577) above categories.  They are in no particular order.
cvs.texi(,14578) 
cvs.texi(,14579) @itemize @bullet
cvs.texi(,14580) @item
cvs.texi(,14581) On Windows, if there is a 30 second or so delay when
cvs.texi(,14582) you run a @sc{cvs} command, it may mean that you have
cvs.texi(,14583) your home directory set to @file{C:/}, for example (see
cvs.texi(,14584) @code{HOMEDRIVE} and @code{HOMEPATH} in
cvs.texi(,14585) @ref{Environment variables}).  @sc{cvs} expects the home
cvs.texi(,14586) directory to not end in a slash, for example @file{C:}
cvs.texi(,14587) or @file{C:\cvs}.
cvs.texi(,14588) @c FIXCVS: CVS should at least detect this and print an
cvs.texi(,14589) @c error, presumably.
cvs.texi(,14590) 
cvs.texi(,14591) @item
cvs.texi(,14592) If you are running @sc{cvs} 1.9.18 or older, and
cvs.texi(,14593) @code{cvs update} finds a conflict and tries to
cvs.texi(,14594) merge, as described in @ref{Conflicts example}, but
cvs.texi(,14595) doesn't tell you there were conflicts, then you may
cvs.texi(,14596) have an old version of @sc{rcs}.  The easiest solution
cvs.texi(,14597) probably is to upgrade to a current version of
cvs.texi(,14598) @sc{cvs}, which does not rely on external @sc{rcs}
cvs.texi(,14599) programs.
cvs.texi(,14600) @end itemize
cvs.texi(,14601) 
cvs.texi(,14602) @c ---------------------------------------------------------------------
cvs.texi(,14603) @node Credits
cvs.texi(,14604) @appendix Credits
cvs.texi(,14605) 
cvs.texi(,14606) @cindex Contributors (manual)
cvs.texi(,14607) @cindex Credits (manual)
cvs.texi(,14608) Roland Pesch, then of Cygnus Support <@t{roland@@wrs.com}>
cvs.texi(,14609) wrote the manual pages which were distributed with
cvs.texi(,14610) @sc{cvs} 1.3.  Much of their text was copied into this
cvs.texi(,14611) manual.  He also read an early draft
cvs.texi(,14612) of this manual and contributed many ideas and
cvs.texi(,14613) corrections.
cvs.texi(,14614) 
cvs.texi(,14615) The mailing-list @code{info-cvs} is sometimes
cvs.texi(,14616) informative. I have included information from postings
cvs.texi(,14617) made by the following persons:
cvs.texi(,14618) David G. Grubbs <@t{dgg@@think.com}>.
cvs.texi(,14619) 
cvs.texi(,14620) Some text has been extracted from the man pages for
cvs.texi(,14621) @sc{rcs}.
cvs.texi(,14622) 
cvs.texi(,14623) The @sc{cvs} @sc{faq} by David G. Grubbs has provided
cvs.texi(,14624) useful material.  The @sc{faq} is no longer maintained,
cvs.texi(,14625) however, and this manual is about the closest thing there
cvs.texi(,14626) is to a successor (with respect to documenting how to
cvs.texi(,14627) use @sc{cvs}, at least).
cvs.texi(,14628) 
cvs.texi(,14629) In addition, the following persons have helped by
cvs.texi(,14630) telling me about mistakes I've made:
cvs.texi(,14631) 
cvs.texi(,14632) @display
cvs.texi(,14633) Roxanne Brunskill <@t{rbrunski@@datap.ca}>,
cvs.texi(,14634) Kathy Dyer <@t{dyer@@phoenix.ocf.llnl.gov}>,
cvs.texi(,14635) Karl Pingle <@t{pingle@@acuson.com}>,
cvs.texi(,14636) Thomas A Peterson <@t{tap@@src.honeywell.com}>,
cvs.texi(,14637) Inge Wallin <@t{ingwa@@signum.se}>,
cvs.texi(,14638) Dirk Koschuetzki <@t{koschuet@@fmi.uni-passau.de}>
cvs.texi(,14639) and Michael Brown <@t{brown@@wi.extrel.com}>.
cvs.texi(,14640) @end display
cvs.texi(,14641) 
cvs.texi(,14642) The list of contributors here is not comprehensive; for a more
cvs.texi(,14643) complete list of who has contributed to this manual see
cvs.texi(,14644) the file @file{doc/ChangeLog} in the @sc{cvs} source
cvs.texi(,14645) distribution.
cvs.texi(,14646) 
cvs.texi(,14647) @c ---------------------------------------------------------------------
cvs.texi(,14648) @node BUGS
cvs.texi(,14649) @appendix Dealing with bugs in CVS or this manual
cvs.texi(,14650) 
cvs.texi(,14651) @cindex Bugs in this manual or CVS
cvs.texi(,14652) Neither @sc{cvs} nor this manual is perfect, and they
cvs.texi(,14653) probably never will be.  If you are having trouble
cvs.texi(,14654) using @sc{cvs}, or think you have found a bug, there
cvs.texi(,14655) are a number of things you can do about it.  Note that
cvs.texi(,14656) if the manual is unclear, that can be considered a bug
cvs.texi(,14657) in the manual, so these problems are often worth doing
cvs.texi(,14658) something about as well as problems with @sc{cvs} itself.
cvs.texi(,14659) 
cvs.texi(,14660) @cindex Reporting bugs
cvs.texi(,14661) @cindex Bugs, reporting
cvs.texi(,14662) @cindex Errors, reporting
cvs.texi(,14663) @itemize @bullet
cvs.texi(,14664) @item
cvs.texi(,14665) If you want someone to help you and fix bugs that you
cvs.texi(,14666) report, there are companies which will do that for a
cvs.texi(,14667) fee.  One such company is:
cvs.texi(,14668) 
cvs.texi(,14669) @cindex Ximbiot
cvs.texi(,14670) @cindex Support, getting CVS support
cvs.texi(,14671) @example
cvs.texi(,14672) Ximbiot
cvs.texi(,14673) 319 S. River St.
cvs.texi(,14674) Harrisburg, PA  17104-1657
cvs.texi(,14675) USA
cvs.texi(,14676) Email: info@@ximbiot.com
cvs.texi(,14677) Phone: (717) 579-6168
cvs.texi(,14678) Fax:   (717) 234-3125
cvs.texi(,14679) http://ximbiot.com/
cvs.texi(,14680) 
cvs.texi(,14681) @end example
cvs.texi(,14682) 
cvs.texi(,14683) @item
cvs.texi(,14684) If you got @sc{cvs} through a distributor, such as an
cvs.texi(,14685) operating system vendor or a vendor of freeware
cvs.texi(,14686) @sc{cd-rom}s, you may wish to see whether the
cvs.texi(,14687) distributor provides support.  Often, they will provide
cvs.texi(,14688) no support or minimal support, but this may vary from
cvs.texi(,14689) distributor to distributor.
cvs.texi(,14690) 
cvs.texi(,14691) @item
cvs.texi(,14692) If you have the skills and time to do so, you may wish
cvs.texi(,14693) to fix the bug yourself.  If you wish to submit your
cvs.texi(,14694) fix for inclusion in future releases of @sc{cvs}, see
cvs.texi(,14695) the file @sc{hacking} in the @sc{cvs} source
cvs.texi(,14696) distribution.  It contains much more information on the
cvs.texi(,14697) process of submitting fixes.
cvs.texi(,14698) 
cvs.texi(,14699) @item
cvs.texi(,14700) There may be resources on the net which can help.  Two
cvs.texi(,14701) good places to start are:
cvs.texi(,14702) 
cvs.texi(,14703) @example
cvs.texi(,14704) http://www.cvshome.org
cvs.texi(,14705) http://www.loria.fr/~molli/cvs-index.html
cvs.texi(,14706) @end example
cvs.texi(,14707) 
cvs.texi(,14708) If you are so inspired, increasing the information
cvs.texi(,14709) available on the net is likely to be appreciated.  For
cvs.texi(,14710) example, before the standard @sc{cvs} distribution
cvs.texi(,14711) worked on Windows 95, there was a web page with some
cvs.texi(,14712) explanation and patches for running @sc{cvs} on Windows
cvs.texi(,14713) 95, and various people helped out by mentioning this
cvs.texi(,14714) page on mailing lists or newsgroups when the subject
cvs.texi(,14715) came up.
cvs.texi(,14716) 
cvs.texi(,14717) @item
cvs.texi(,14718) It is also possible to report bugs to @code{bug-cvs}.
cvs.texi(,14719) Note that someone may or may not want to do anything
cvs.texi(,14720) with your bug report---if you need a solution consider
cvs.texi(,14721) one of the options mentioned above.  People probably do
cvs.texi(,14722) want to hear about bugs which are particularly severe
cvs.texi(,14723) in consequences and/or easy to fix, however.  You can
cvs.texi(,14724) also increase your odds by being as clear as possible
cvs.texi(,14725) about the exact nature of the bug and any other
cvs.texi(,14726) relevant information.  The way to report bugs is to
cvs.texi(,14727) send email to @code{bug-cvs@@gnu.org}.  Note
cvs.texi(,14728) that submissions to @code{bug-cvs} may be distributed
cvs.texi(,14729) under the terms of the @sc{gnu} Public License, so if
cvs.texi(,14730) you don't like this, don't submit them.  There is
cvs.texi(,14731) usually no justification for sending mail directly to
cvs.texi(,14732) one of the @sc{cvs} maintainers rather than to
cvs.texi(,14733) @code{bug-cvs}; those maintainers who want to hear
cvs.texi(,14734) about such bug reports read @code{bug-cvs}.  Also note
cvs.texi(,14735) that sending a bug report to other mailing lists or
cvs.texi(,14736) newsgroups is @emph{not} a substitute for sending it to
cvs.texi(,14737) @code{bug-cvs}.  It is fine to discuss @sc{cvs} bugs on
cvs.texi(,14738) whatever forum you prefer, but there are not
cvs.texi(,14739) necessarily any maintainers reading bug reports sent
cvs.texi(,14740) anywhere except @code{bug-cvs}.
cvs.texi(,14741) @end itemize
cvs.texi(,14742) 
cvs.texi(,14743) @cindex Known bugs in this manual or CVS
cvs.texi(,14744) People often ask if there is a list of known bugs or
cvs.texi(,14745) whether a particular bug is a known one.  The file
cvs.texi(,14746) @sc{bugs} in the @sc{cvs} source distribution is one
cvs.texi(,14747) list of known bugs, but it doesn't necessarily try to
cvs.texi(,14748) be comprehensive.  Perhaps there will never be a
cvs.texi(,14749) comprehensive, detailed list of known bugs.
cvs.texi(,14750) 
cvs.texi(,14751) @c ---------------------------------------------------------------------
cvs.texi(,14752) @node Index
cvs.texi(,14753) @unnumbered Index
cvs.texi(,14754) @cindex Index
cvs.texi(,14755) 
cvs.texi(,14756) @printindex cp
cvs.texi(,14757) 
cvs.texi(,14758) @summarycontents
cvs.texi(,14759) 
cvs.texi(,14760) @contents
cvs.texi(,14761) 
cvs.texi(,14762) @bye