1 files changed, 7738 insertions, 0 deletions

diff --git a/contrib/cvs/doc/cvs.texinfo b/contrib/cvs/doc/cvs.texinfo
new file mode 100644
index 000000000000..29bc5f350601
--- /dev/null
+++ b/contrib/cvs/doc/cvs.texinfo
@@ -0,0 +1,7738 @@
+\input texinfo  @c -*-texinfo-*-
+@comment cvs.texinfo,v 1.6 1995/10/12 23:39:26 kfogel Exp
+@comment Documentation for CVS.
+@comment Copyright (C) 1992, 1993 Signum Support AB
+@comment Copyright (C) 1993 Free Software Foundation, Inc.
+
+@comment This file is part of the CVS distribution.
+
+@comment CVS is free software; you can redistribute it and/or modify
+@comment it under the terms of the GNU General Public License as published by
+@comment the Free Software Foundation; either version 1, or (at your option)
+@comment any later version.
+
+@comment CVS is distributed in the hope that it will be useful,
+@comment but WITHOUT ANY WARRANTY; without even the implied warranty of
+@comment MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+@comment GNU General Public License for more details.
+
+@comment You should have received a copy of the GNU General Public License
+@comment along with CVS; see the file COPYING.  If not, write to
+@comment the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
+
+@afourpaper
+@setfilename cvs.info
+@include CVSvn.texi
+@settitle CVS---Concurrent Versions System
+@setchapternewpage odd
+
+@c -- TODO list:
+@c -- Fix all lines that match "^@c -- "
+@c -- Document how CVS finds the binaries it executes.
+@c Things to include in the index:
+@c Finding RCS binaries
+@c Path to RCS binaries
+@c RCS, how CVS finds them
+@c s/RCS/diff/
+@c -- More on binary files
+
+@ifinfo
+Copyright @copyright{} 1992, 1993 Signum Support AB
+Copyright @copyright{} 1993, 1994 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through Tex and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+section entitled ``GNU General Public License'' is included exactly as
+in the original, and provided that the entire resulting derived work is
+distributed under the terms of a permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that the section entitled ``GNU General Public License'' and
+this permission notice may be included in translations approved by the
+Free Software Foundation instead of in the original English.
+@end ifinfo
+
+@comment The titlepage section does not appear in the Info file.
+@titlepage
+@sp 4
+@comment The title is printed in a large font.
+@center @titlefont{Version Management}
+@sp
+@center @titlefont{with}
+@sp
+@center @titlefont{CVS}
+@sp 2
+@center for @sc{cvs} @value{CVSVN}
+@comment -release-
+@sp 3
+@center Per Cederqvist et al
+
+@comment  The following two commands start the copyright page
+@comment  for the printed manual.  This will not appear in the Info file.
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1992, 1993 Signum Support AB
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+section entitled ``GNU General Public License'' is included exactly as
+in the original, and provided that the entire resulting derived work is
+distributed under the terms of a permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that the section entitled ``GNU General Public License'' and
+this permission notice may be included in translations approved by the
+Free Software Foundation instead of in the original English.
+@end titlepage
+
+@comment ================================================================
+@comment                   The real text starts here
+@comment ================================================================
+
+@ifinfo
+@c ---------------------------------------------------------------------
+@node    Top
+@top 
+@c Note: there is a space after that @top command.
+@c The texinfo-format-buffer Emacs function and
+@c the makeinfo shell command disagree on what arguments
+@c @top takes; @top followed by a single space is
+@c something they can both cope with.
+
+This info manual describes how to use and administer
+@sc{cvs} version @value{CVSVN}.
+@end ifinfo
+
+@menu
+* Preface::                     About this manual
+* What is CVS?::                What is CVS?
+* Basic concepts::              Basic concepts of revision management
+* A sample session::            A tour of basic CVS usage
+* Repository::                  Where all your sources are stored
+* Starting a new project::      Starting a project with CVS
+* Multiple developers::         How CVS helps a group of developers
+* Branches::                    Parallel development explained
+* Merging::                     How to move changes between branches
+* Recursive behavior::          CVS descends directories
+* Adding files::                Adding files to a module
+* Removing files::              Removing files from a module
+* Tracking sources::            Tracking third-party sources
+* Moving files::                Moving and renaming files
+* Moving directories::          Moving and renaming directories
+* History browsing::            Viewing the history of files in various ways
+* Keyword substitution::        CVS can include the revision inside the file
+* Binary files::                CVS can handle binary files
+* Revision management::         Policy questions for revision management
+* Invoking CVS::                Reference manual for CVS commands
+* Administrative files::        Reference manual for the Administrative files
+* Environment variables::       All environment variables which affect CVS
+* Troubleshooting::             Some tips when nothing works
+* Copying::                     GNU GENERAL PUBLIC LICENSE
+* Index::                       Index
+@end menu
+
+@c ---------------------------------------------------------------------
+@node Preface
+@unnumbered About this manual
+@cindex Preface
+@cindex About this manual
+
+Up to this point, one of the weakest parts of @sc{cvs}
+has been the documentation.  @sc{cvs} is a complex
+program.  Previous versions of the manual were written
+in the manual page format, which is not really well
+suited for such a complex program.
+
+When writing this manual, I had several goals in mind:
+
+@itemize @bullet
+@item
+No knowledge of @sc{rcs} should be necessary.
+
+@item
+No previous knowledge of revision control software
+should be necessary.  All terms, such as @dfn{revision
+numbers}, @dfn{revision trees} and @dfn{merging} are
+explained as they are introduced.
+
+@item
+The manual should concentrate on the things @sc{cvs} users
+want to do, instead of what the @sc{cvs} commands can do.
+The first part of this manual leads you through things
+you might want to do while doing development, and
+introduces the relevant @sc{cvs} commands as they are
+needed.
+
+@item
+Information should be easy to find.  In the reference
+manual in the appendices almost all information about
+every @sc{cvs} command is gathered together.  There is also
+an extensive index, and a lot of cross references.
+@end itemize
+
+@cindex Signum Support
+@cindex Support, getting CVS support
+This manual was contributed by Signum Support AB in
+Sweden.  Signum is yet another in the growing list of
+companies that support free software.  You are free to
+copy both this manual and the @sc{cvs} program.
+@xref{Copying}, for the details.  Signum Support offers
+@c -- Check this reference! It has been bogus in the past.
+support contracts and binary distribution for many
+programs, such as @sc{cvs}, @sc{gnu} Emacs, the
+@sc{gnu} C compiler and others.  Write to us for
+more information.
+
+@example
+Signum Support AB
+Box 2044
+S-580 02  Linkoping
+Sweden
+
+Email: info@@signum.se
+Phone: +46 (0)13 - 21 46 00
+Fax:   +46 (0)13 - 21 47 00
+@end example
+
+Another company selling support for @sc{cvs} is Cyclic
+Software, web: @code{http://www.cyclic.com/}, email:
+@code{info@@cyclic.com}.
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@menu
+* Checklist::                   
+* Credits::                     
+* BUGS::                        
+@end menu
+
+@node Checklist
+@unnumberedsec Checklist for the impatient reader
+
+@sc{cvs} is a complex system.  You will need to read
+the manual to be able to use all of its capabilities.
+There are dangers that can easily be avoided if you
+know about them, and this manual tries to warn you
+about them.  This checklist is intended to help you
+avoid the dangers without reading the entire manual.
+If you intend to read the entire manual you can skip
+this table.
+
+@table @asis
+@item Binary files
+@sc{cvs} can handle binary files, but
+you must have @sc{rcs} release 5.5 or later and
+a release of @sc{gnu} diff that supports the @samp{-a}
+flag (release 1.15 and later are OK).  You must also
+configure both @sc{rcs} and @sc{cvs} to handle binary
+files when you install them.
+
+Keword substitution can be a source of trouble with
+binary files. @xref{Keyword substitution}, for
+solutions.
+
+@item The @code{admin} command
+Uncareful use of the @code{admin} command can cause
+@sc{cvs} to cease working.  @xref{admin}, before trying
+to use it.
+@end table
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Credits
+@unnumberedsec Credits
+
+@cindex Contributors (manual)
+@cindex Credits (manual)
+Roland Pesch, Cygnus Support <@t{pesch@@cygnus.com}>
+wrote the manual pages which were distributed with
+@sc{cvs} 1.3.  Appendix A and B contain much text that
+was extracted from them.  He also read an early draft
+of this manual and contributed many ideas and
+corrections.
+
+The mailing-list @code{info-cvs} is sometimes
+informative. I have included information from postings
+made by the following persons:
+David G. Grubbs <@t{dgg@@think.com}>.
+
+Some text has been extracted from the man pages for
+@sc{rcs}.
+
+The @sc{cvs} @sc{faq} (@pxref{What is CVS?}) by David
+G. Grubbs has been used as a check-list to make sure
+that this manual is as complete as possible.  (This
+manual does however not include all of the material in
+the @sc{faq}).  The @sc{faq} contains a lot of useful
+information.
+
+In addition, the following persons have helped by
+telling me about mistakes I've made:
+Roxanne Brunskill <@t{rbrunski@@datap.ca}>,
+Kathy Dyer <@t{dyer@@phoenix.ocf.llnl.gov}>,
+Karl Pingle <@t{pingle@@acuson.com}>,
+Thomas A Peterson <@t{tap@@src.honeywell.com}>,
+Inge Wallin <@t{ingwa@@signum.se}>,
+Dirk Koschuetzki <@t{koschuet@@fmi.uni-passau.de}>
+and Michael Brown <@t{brown@@wi.extrel.com}>.
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node BUGS
+@unnumberedsec BUGS
+
+@cindex Bugs, known in this manual
+@cindex Known bugs in this manual
+This manual is known to have room for improvement.
+Here is a list of known deficiencies:
+
+@itemize @bullet
+@item
+In the examples, the output from @sc{cvs} is sometimes
+displayed, sometimes not.
+
+@item
+The input that you are supposed to type in the examples
+should have a different font than the output from the
+computer.
+
+@item
+This manual should be clearer about what file
+permissions you should set up in the repository, and
+about setuid/setgid.
+
+@item
+Some of the chapters are not yet complete.  They are
+noted by comments in the @file{cvs.texinfo} file.
+
+@item
+@cindex Reporting bugs (manual)
+@cindex Bugs, reporting (manual)
+@cindex Errors, reporting (manual)
+This list is not complete.  If you notice any error,
+omission, or something that is unclear, please send
+mail to @t{bug-cvs@@prep.ai.mit.edu}.
+@end itemize
+
+I hope that you will find this manual useful, despite
+the above-mentioned shortcomings.
+
+@flushright
+
+Linkoping, October 1993
+Per Cederqvist
+@end flushright
+
+@c ---------------------------------------------------------------------
+@node What is CVS?
+@chapter What is CVS?
+@cindex What is CVS?
+@cindex Introduction to CVS
+@cindex CVS, introduction to
+
+@sc{cvs} is a version control system.  Using it, you can
+record the history of your source files.
+
+@c -- ///
+@c -- ///Those who cannot remember the past are condemned to repeat it.
+@c -- ///               -- George Santayana
+@c -- //////
+
+@c -- Insert history  quote here!
+For example, bugs sometimes creep in when
+software is modified, and you might not detect the bug
+until a long time after you make the modification.
+With @sc{cvs}, you can easily retrieve old versions to see
+exactly which change caused the bug.  This can
+sometimes be a big help.
+
+You could of course save every version of every file
+you have ever created.  This would
+however waste an enormous amount of disk space.  @sc{cvs}
+stores all the versions of a file in a single file in a
+clever way that only stores the differences between
+versions.
+
+@sc{cvs} also helps you if you are part of a group of people working
+on the same project.  It is all too easy to overwrite
+each others' changes unless you are extremely careful.
+Some editors, like @sc{gnu} Emacs, try to make sure that
+the same file is never modified by two people at the
+same time.  Unfortunately, if someone is using another
+editor, that safeguard will not work.  @sc{cvs} solves this problem
+by insulating the different developers from each other.  Every
+developer works in his own directory, and @sc{cvs} merges
+the work when each developer is done.
+
+@cindex History of CVS
+@cindex CVS, history of
+@cindex Credits (CVS program)
+@cindex Contributors (CVS program)
+@sc{cvs} started out as a bunch of shell scripts written by
+Dick Grune, posted to @code{comp.sources.unix} in the volume 6
+release of December, 1986.  While no actual code from
+these shell scripts is present in the current version
+of @sc{cvs} much of the @sc{cvs} conflict resolution algorithms
+come from them.
+
+In April, 1989, Brian Berliner designed and coded @sc{cvs}.
+Jeff Polk later helped Brian with the design of the @sc{cvs}
+module and vendor branch support.
+
+@cindex Source, getting CVS source
+You can get @sc{cvs} via anonymous ftp from a number of
+sites, for instance @t{prep.ai.mit.edu} in
+@file{pub/gnu}.
+
+@cindex Mailing list
+@cindex List, mailing list
+There is a mailing list for @sc{cvs} where bug reports
+can be sent, questions can be asked, an FAQ is posted,
+and discussion about future enhancements to @sc{cvs}
+take place.  To submit a message to the list, write to
+<@t{info-cvs@@prep.ai.mit.edu}>.  To subscribe or
+unsubscribe, write to
+<@t{info-cvs-request@@prep.ai.mit.edu}>. Please be
+specific about your email address.
+
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@unnumberedsec CVS is not@dots{}
+
+@sc{cvs} can do a lot of things for you, but it does
+not try to be everything for everyone.
+
+@table @asis
+@item @sc{cvs} is not a build system.
+
+Though the structure of your repository and modules
+file interact with your build system
+(e.g. @file{Makefile}s), they are essentially
+independent.
+
+@sc{cvs} does not dictate how you build anything.  It
+merely stores files for retrieval in a tree structure
+you devise.
+
+@sc{cvs} does not dictate how to use disk space in the
+checked out working directories.  If you write your
+@file{Makefile}s or scripts in every directory so they
+have to know the relative positions of everything else,
+you wind up requiring the entire repository to be
+checked out.  That's simply bad planning.
+
+If you modularize your work, and construct a build
+system that will share files (via links, mounts,
+@code{VPATH} in @file{Makefile}s, etc.), you can
+arrange your disk usage however you like.
+
+But you have to remember that @emph{any} such system is
+a lot of work to construct and maintain.  @sc{cvs} does
+not address the issues involved.  You must use your
+brain and a collection of other tools to provide a
+build scheme to match your plans.
+
+Of course, you should place the tools created to
+support such a build system (scripts, @file{Makefile}s,
+etc) under @sc{cvs}.
+
+@item @sc{cvs} is not a substitute for management.
+
+Your managers and project leaders are expected to talk
+to you frequently enough to make certain you are aware
+of schedules, merge points, branch names and release
+dates.  If they don't, @sc{cvs} can't help.
+
+@sc{cvs} is an instrument for making sources dance to
+your tune.  But you are the piper and the composer.  No
+instrument plays itself or writes its own music.
+
+@item @sc{cvs} is not a substitute for developer communication.
+
+When faced with conflicts within a single file, most
+developers manage to resolve them without too much
+effort.  But a more general definition of ``conflict''
+includes problems too difficult to solve without
+communication between developers.
+
+@sc{cvs} cannot determine when simultaneous changes
+within a single file, or across a whole collection of
+files, will logically conflict with one another.  Its
+concept of a @dfn{conflict} is purely textual, arising
+when two changes to the same base file are near enough
+to spook the merge (i.e. @code{diff3}) command.
+
+@sc{cvs} does not claim to help at all in figuring out
+non-textual or distributed conflicts in program logic.
+
+For example: Say you change the arguments to function
+@code{X} defined in file @file{A}.  At the same time,
+someone edits file @file{B}, adding new calls to
+function @code{X} using the old arguments.  You are
+outside the realm of @sc{cvs}'s competence.
+
+Acquire the habit of reading specs and talking to your
+peers.
+
+
+@item @sc{cvs} is not a configuration management system.
+
+@sc{cvs} is a source control system.  The phrase
+``configuration management'' is a marketing term, not
+an industry-recognized set of functions.
+
+A true ``configuration management system'' would contain
+elements of the following:
+
+@itemize @bullet
+@item Source control.
+@item Dependency tracking.
+@item Build systems (i.e. What to build and how to find
+things during a build.  What is shared?  What is local?)
+@item Bug tracking.
+@item Automated Testing procedures.
+@item Release Engineering documentation and procedures.
+@item Tape Construction.
+@item Customer Installation.
+@item A way for users to run different versions of the same
+software on the same host at the same time.
+@end itemize
+
+@sc{cvs} provides only the first.
+@end table
+
+This section is taken from release 2.3 of the @sc{cvs}
+@sc{faq}.
+
+@c ---------------------------------------------------------------------
+@node Basic concepts
+@chapter Basic concepts
+@cindex Modules (intro)
+@cindex Repository (intro)
+
+@sc{cvs} stores all files in a centralized
+@dfn{repository}: a directory (such as
+@file{/usr/local/cvsroot} or
+@file{user@@remotehost:/usr/local/cvsroot}) which is
+populated with a hierarchy of files and directories.
+(@pxref{Remote repositories} for information about
+keeping the repository on a remote machine.)
+
+Normally, you never access any of the files in the
+repository directly.  Instead, you use @sc{cvs}
+commands to get your own copy of the files, and then
+work on that copy.  When you've finished a set of
+changes, you check (or @dfn{commit}) them back into the
+repository.
+
+The files in the repository are organized in
+@dfn{modules}.  Each module is made up of one or more
+files, and can include files from several directories.
+A typical usage is to define one module per project.
+
+@menu
+* Revision numbers::            The meaning of a revision number
+* Versions revisions releases::  Terminology used in this manual
+@end menu
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Revision numbers
+@section Revision numbers
+@cindex Revision numbers
+@cindex Revision tree
+@cindex Linear development
+@cindex Number, revision-
+@cindex Decimal revision number
+@cindex Main trunk (intro)
+@cindex Branch number
+@cindex Number, branch
+
+Each version of a file has a unique @dfn{revision
+number}.  Revision numbers look like @samp{1.1},
+@samp{1.2}, @samp{1.3.2.2} or even @samp{1.3.2.2.4.5}.
+A revision number always has an even number of
+period-separated decimal integers.  By default revision
+1.1 is the first revision of a file.  Each successive
+revision is given a new number by increasing the
+rightmost number by one.  The following figure displays
+a few revisions, with newer revisions to the right.
+
+@example
+       +-----+    +-----+    +-----+    +-----+    +-----+
+       ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
+       +-----+    +-----+    +-----+    +-----+    +-----+
+@end example
+
+@sc{cvs} is not limited to linear development.  The
+@dfn{revision tree} can be split into @dfn{branches},
+where each branch is a self-maintained line of
+development.  Changes made on one branch can easily be
+moved back to the main trunk.  
+
+Each branch has a @dfn{branch number}, consisting of an
+odd number of period-separated decimal integers.  The
+branch number is created by appending an integer to the
+revision number where the corresponding branch forked
+off.  Having branch numbers allows more than one branch
+to be forked off from a certain revision.
+
+@need 3500
+All revisions on a branch have revision numbers formed
+by appending an ordinal number to the branch number.
+The following figure illustrates branching with an
+example.
+
+@example
+@group
+                                                     +-------------+
+                          Branch 1.2.2.3.2 ->        ! 1.2.2.3.2.1 !
+                                                   / +-------------+
+                                                  /
+                                                 /
+                 +---------+    +---------+    +---------+    +---------+
+Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !----! 1.2.2.4 !
+               / +---------+    +---------+    +---------+    +---------+
+              /
+             /
++-----+    +-----+    +-----+    +-----+    +-----+
+! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !      <- The main trunk
++-----+    +-----+    +-----+    +-----+    +-----+
+                !
+                !
+                !   +---------+    +---------+    +---------+
+Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 !
+                    +---------+    +---------+    +---------+
+
+@end group
+@end example
+
+@c --   However, at least for me the figure is not enough.  I suggest more
+@c --   text to accompany it.  "A picture is worth a thousand words", so you
+@c --   have to make sure the reader notices the couple of hundred words
+@c --   *you* had in mind more than the others!
+
+@c --   Why an even number of segments?  This section implies that this is
+@c --   how the main trunk is distinguished from branch roots, but you never
+@c --   explicitly say that this is the purpose of the [by itself rather
+@c --   surprising] restriction to an even number of segments.
+
+The exact details of how the branch number is
+constructed is not something you normally need to be
+concerned about, but here is how it works: When
+@sc{cvs} creates a branch number it picks the first
+unused even integer, starting with 2.  So when you want
+to create a branch from revision 6.4 it will be
+numbered 6.4.2.  All branch numbers ending in a zero
+(such as 6.4.0) are used internally by @sc{cvs}
+(@pxref{Magic branch numbers}).  The branch 1.1.1 has a
+special meaning.  @xref{Tracking sources}.
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Versions revisions releases
+@section Versions, revisions and releases
+@cindex Revisions, versions and releases
+@cindex Versions, revisions and releases
+@cindex Releases, revisions and versions
+
+A file can have several versions, as described above.
+Likewise, a software product can have several versions.
+A software product is often given a version number such
+as @samp{4.1.1}.
+
+Versions in the first sense are called @dfn{revisions}
+in this document, and versions in the second sense are
+called @dfn{releases}.  To avoid confusion, the word
+@dfn{version} is almost never used in this document.
+
+@c ---------------------------------------------------------------------
+@node A sample session
+@chapter A sample session
+@cindex A sample session
+@cindex Example of a work-session
+@cindex Getting started
+@cindex Work-session, example of
+@cindex tc, Trivial Compiler (example)
+@cindex Trivial Compiler (example)
+
+This section describes a typical work-session using
+@sc{cvs}.  It assumes that a repository is set up
+(@pxref{Repository}).
+
+Suppose you are working on a simple compiler.  The source
+consists of a handful of C files and a @file{Makefile}.
+The compiler is called @samp{tc} (Trivial Compiler),
+and the repository is set up so that there is a module
+called @samp{tc}.
+
+@menu
+* Getting the source::          Creating a workspace
+* Committing your changes::     Making your work available to others
+* Cleaning up::                 Cleaning up
+* Viewing differences::         Viewing differences
+@end menu
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Getting the source
+@section Getting the source
+@cindex Getting the source
+@cindex Checking out source
+@cindex Fetching source
+@cindex Source, getting from CVS
+@cindex Checkout, example
+
+The first thing you must do is to get your own working copy of the
+source for @samp{tc}.  For this, you use the @code{checkout} command:
+
+@example
+$ cvs checkout tc
+@end example
+
+@noindent
+This will create a new directory called @file{tc} and populate it with
+the source files.
+
+@example
+$ cd tc
+$ ls tc
+CVS         Makefile    backend.c   driver.c    frontend.c  parser.c
+@end example
+
+The @file{CVS} directory is used internally by
+@sc{cvs}.  Normally, you should not modify or remove
+any of the files in it.
+
+You start your favorite editor, hack away at @file{backend.c}, and a couple
+of hours later you have added an optimization pass to the compiler.
+A note to @sc{rcs} and @sc{sccs} users: There is no need to lock the files that
+you want to edit.  @xref{Multiple developers} for an explanation.
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Committing your changes
+@section Committing your changes
+@cindex Committing changes
+@cindex Log message entry
+@cindex CVSEDITOR, environment variable
+@cindex EDITOR, environment variable
+
+When you have checked that the compiler is still compilable you decide
+to make a new version of @file{backend.c}.
+
+@example
+$ cvs commit backend.c
+@end example
+
+@noindent
+@sc{cvs} starts an editor, to allow you to enter a log
+message.  You type in ``Added an optimization pass.'',
+save the temporary file, and exit the editor.
+
+The environment variable @code{$CVSEDITOR} determines
+which editor is started.  If @code{$CVSEDITOR} is not
+set, then if the environment variable @code{$EDITOR} is
+set, it will be used. If both @code{$CVSEDITOR} and
+@code{$EDITOR} are not set then the editor defaults to
+@code{vi}.  If you want to avoid the overhead of
+starting an editor you can specify the log message on
+the command line using the @samp{-m} flag instead, like
+this:
+
+@example
+$ cvs commit -m "Added an optimization pass" backend.c
+@end example
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Cleaning up
+@section Cleaning up
+@cindex Cleaning up
+@cindex Working copy, removing
+@cindex Removing your working copy
+@cindex Releasing your working copy
+
+Before you turn to other tasks you decide to remove your working copy of
+tc.  One acceptable way to do that is of course
+
+@example
+$ cd ..
+$ rm -r tc
+@end example
+
+@noindent
+but a better way is to use the @code{release} command (@pxref{release}):
+
+@example
+$ cd ..
+$ cvs release -d tc
+M driver.c
+? tc
+You have [1] altered files in this repository.
+Are you sure you want to release (and delete) module `tc': n
+** `release' aborted by user choice.
+@end example
+
+The @code{release} command checks that all your modifications have been
+committed.  If history logging is enabled it also makes a note in the
+history file.  @xref{history file}.
+
+When you use the @samp{-d} flag with @code{release}, it
+also removes your working copy.
+
+In the example above, the @code{release} command wrote a couple of lines
+of output.  @samp{? tc} means that the file @file{tc} is unknown to @sc{cvs}.
+That is nothing to worry about: @file{tc} is the executable compiler,
+and it should not be stored in the repository.  @xref{cvsignore},
+for information about how to make that warning go away.
+@xref{release output}, for a complete explanation of
+all possible output from @code{release}.
+
+@samp{M driver.c} is more serious.  It means that the
+file @file{driver.c} has been modified since it was
+checked out.
+
+The @code{release} command always finishes by telling
+you how many modified files you have in your working
+copy of the sources, and then asks you for confirmation
+before deleting any files or making any note in the
+history file.
+
+You decide to play it safe and answer @kbd{n @key{RET}}
+when @code{release} asks for confirmation.
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Viewing differences
+@section Viewing differences
+@cindex Viewing differences
+@cindex Diff
+
+You do not remember modifying @file{driver.c}, so you want to see what
+has happened to that file.
+
+@example
+$ cd tc
+$ cvs diff driver.c
+@end example
+
+This command runs @code{diff} to compare the version of @file{driver.c}
+that you checked out with your working copy.  When you see the output
+you remember that you added a command line option that enabled the
+optimization pass.  You check it in, and release the module.
+
+@example
+$ cvs commit -m "Added an optimization pass" driver.c
+Checking in driver.c;
+/usr/local/cvsroot/tc/driver.c,v  <--  driver.c
+new revision: 1.2; previous revision: 1.1
+done
+$ cd ..
+$ cvs release -d tc
+? tc
+You have [0] altered files in this repository.
+Are you sure you want to release (and delete) module `tc': y
+@end example
+
+@c ---------------------------------------------------------------------
+@node Repository
+@chapter The Repository
+@cindex Repository, example
+@cindex Layout of repository
+@cindex Typical repository
+@cindex CVSROOT, environment variable
+@cindex .profile
+@cindex .cshrc
+@cindex .tcshrc
+@cindex .bashrc
+@cindex /usr/local/cvsroot
+@cindex cvsroot
+
+Figure 3 below shows a typical setup of a repository.
+Only directories are shown below.
+
+@example
+@t{/usr}
+ |
+ +--@t{local}
+ |   |
+ |   +--@t{cvsroot}
+ |   |    | 
+ |   |    +--@t{CVSROOT}
+          |      (administrative files) 
+          | 
+          +--@t{gnu}
+          |   | 
+          |   +--@t{diff}
+          |   |   (source code to @sc{gnu} diff) 
+          |   | 
+          |   +--@t{rcs}
+          |   |   (source code to @sc{rcs})
+          |   | 
+          |   +--@t{cvs}
+          |       (source code to @sc{cvs}) 
+          | 
+          +--@t{yoyodyne}
+              | 
+              +--@t{tc}
+              |    |
+              |    +--@t{man}
+              |    |
+              |    +--@t{testing}
+              | 
+              +--(other Yoyodyne software)
+@end example                              
+
+
+There are a couple of different ways to tell @sc{cvs}
+where to find the repository.  You can name the
+repository on the command line explicitly, with the
+@code{-d} (for "directory") option:
+
+@example
+cvs -d /usr/local/cvsroot checkout yoyodyne/tc
+@end example
+
+        Or you can set the @code{$CVSROOT} environment
+variable to an absolute path to the root of the
+repository, @file{/usr/local/cvsroot} in this example.
+To set @code{$CVSROOT}, all @code{csh} and @code{tcsh}
+users should have this line in their @file{.cshrc} or
+@file{.tcshrc} files:
+
+@example
+setenv CVSROOT /usr/local/cvsroot
+@end example
+
+@noindent
+@code{sh} and @code{bash} users should instead have these lines in their
+@file{.profile} or @file{.bashrc}:
+
+@example
+CVSROOT=/usr/local/cvsroot
+export CVSROOT
+@end example
+
+        A repository specified with @code{-d} will
+override the @code{$CVSROOT} environment variable.
+Once you've checked a working copy out from the
+repository, it will remember where its repository is
+(the information is recorded in the
+@file{CVS/Root} file in the working copy).  
+
+The @code{-d} option and the @file{CVS/Root} file
+both override the @code{$CVSROOT} environment variable;
+however, @sc{CVS} will complain if the @file{-d}
+argument and the @file{CVS/Root} file disagree.
+
+There is nothing magical about the name
+@file{/usr/local/cvsroot}.  You can choose to place the
+repository anywhere you like.  
+@xref{Remote repositories} to learn how the repository can be on a
+different machine than your working copy of the sources.
+
+The repository is split in two parts.  @file{$CVSROOT/CVSROOT} contains
+administrative files for @sc{cvs}.  The other directories contain the actual
+user-defined modules.
+
+@menu
+* User modules::                The structure of the repository
+* Intro administrative files::  Defining modules
+* Multiple repositories::       Multiple repositories
+* Creating a repository::       Creating a repository
+* Remote repositories::         Accessing repositories on remote machines
+@end menu
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node User modules
+@section User modules
+@cindex User modules
+@cindex Repository, user parts
+
+@example
+  @code{$CVSROOT}
+    |
+    +--@t{yoyodyne}
+    |   |
+    |   +--@t{tc}
+    |   |   |
+            +--@t{Makefile,v}
+            +--@t{backend.c,v}
+            +--@t{driver.c,v}
+            +--@t{frontend.c,v}
+            +--@t{parser.c,v}
+            +--@t{man}
+            |    |
+            |    +--@t{tc.1,v}
+            |     
+            +--@t{testing}
+                 |
+                 +--@t{testpgm.t,v}
+                 +--@t{test2.t,v}
+@end example
+
+@cindex History files
+@cindex RCS history files
+@cindex RCS, CVS uses RCS
+The figure above shows the contents of the @samp{tc}
+module inside the repository.  As you can see all file
+names end in @samp{,v}.  The files are @dfn{history
+files}.  They contain, among other things, enough
+information to recreate any revision of the file, a log
+of all commit messages and the user-name of the person
+who committed the revision.  @sc{cvs} uses the
+facilities of @sc{rcs}, a simpler version control
+system, to maintain these files.  For a full
+description of the file format, see the @code{man} page
+@cite{rcsfile(5)}.
+@c -- Use this format for all references to man pages,
+@c -- or use something better!
+
+@menu
+* File permissions::            File permissions
+@end menu
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node File permissions
+@subsection File permissions
+@c -- Move this to @node Setting up
+@cindex Security
+@cindex File permissions
+@cindex Group
+All @samp{,v} files are created read-only, and you
+should not change the permission of those files.  The
+directories inside the repository should be writable by
+the persons that have permission to modify the files in
+each directory.  This normally means that you must
+create a UNIX group (see group(5)) consisting of the
+persons that are to edit the files in a project, and
+set up the repository so that it is that group that
+owns the directory.
+
+This means that you can only control access to files on
+a per-directory basis.
+
+@sc{cvs} tries to set up reasonable file permissions
+for new directories that are added inside the tree, but
+you must fix the permissions manually when a new
+directory should have different permissions than its
+parent directory.
+
+@cindex setuid
+@cindex setgid
+Since @sc{cvs} was not written to be run setuid, it is
+unsafe to try to run it setuid.  You cannot use the
+setuid features of @sc{rcs} together with @sc{cvs}.
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Intro administrative files
+@section The administrative files
+@cindex Administrative files (intro)
+@cindex Modules file
+@cindex CVSROOT, module name
+@cindex Defining modules (intro)
+
+The directory @file{$CVSROOT/CVSROOT} contains some @dfn{administrative
+files}.  @xref{Administrative files}, for a complete description.
+You can use @sc{cvs} without any of these files, but
+some commands work better when at least the
+@file{modules} file is properly set up.
+
+The most important of these files is the @file{modules}
+file.  It defines all modules in the repository.  This
+is a sample @file{modules} file.
+
+@c FIXME: The CVSROOT line is a goofy example now that
+@c mkmodules doesn't exist.
+@example
+CVSROOT         CVSROOT
+modules         CVSROOT modules
+cvs             gnu/cvs
+rcs             gnu/rcs
+diff            gnu/diff
+tc              yoyodyne/tc
+@end example
+
+The @file{modules} file is line oriented.  In its simplest form each
+line contains the name of the module, whitespace, and the directory
+where the module resides.  The directory is a path relative to
+@code{$CVSROOT}.  The last for lines in the example
+above are examples of such lines.
+
+@c FIXME: might want to introduce the concept of options in modules file
+@c (the old example which was here, -i mkmodules, is obsolete).
+
+The line that defines the module called @samp{modules}
+uses features that are not explained here.
+@xref{modules}, for a full explanation of all the
+available features.
+
+@subsection Editing administrative files
+@cindex Editing administrative files
+@cindex Administrative files, editing them
+
+You edit the administrative files in the same way that you would edit
+any other module.  Use @samp{cvs checkout CVSROOT} to get a working
+copy, edit it, and commit your changes in the normal way.
+
+It is possible to commit an erroneous administrative
+file.  You can often fix the error and check in a new
+revision, but sometimes a particularly bad error in the
+administrative file makes it impossible to commit new
+revisions.  
+@c @xref{Bad administrative files} for a hint
+@c about how to solve such situations.
+@c -- administrative file checking--
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Multiple repositories
+@section Multiple repositories
+@cindex Multiple repositories
+@cindex Repositories, multiple
+@cindex Many repositories
+@cindex Parallel repositories
+@cindex Disjoint repositories
+@cindex CVSROOT, multiple repositories
+
+In some situations it is a good idea to have more than
+one repository, for instance if you have two
+development groups that work on separate projects
+without sharing any code.  All you have to do to have
+several repositories is to specify the appropriate
+repository, using the @code{CVSROOT} environment
+variable, the @samp{-d} option to @sc{cvs}, or (once
+you have checked out a working directories) by
+simply allowing @sc{cvs} to use the repository that was
+used to check out the working directory (@pxref{Repository}).
+
+Notwithstanding, it can be confusing to have two or
+more repositories.
+
+None of the examples in this manual show multiple
+repositories.
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Creating a repository
+@section Creating a repository
+@c -- Well, how do you do?
+
+See the instructions in the @file{INSTALL} file in the
+@sc{cvs} distribution.
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Remote repositories
+@section Remote repositories
+@cindex Repositories, remote
+@cindex Remote repositories
+@cindex Client/Server Operation
+
+        Your working copy of the sources can be on a
+different machine than the repository.  Generally,
+using a remote repository is just like using a local
+one, except that the format of the repository name is:
+
+@example
+        user@@hostname:/path/to/repository
+@end example
+
+The details of exactly what needs to be set up depend
+on how you are connecting to the server.
+
+@menu
+* Connecting via rsh::          Using the @code{rsh} program to connect
+* Password authenticated::      Direct connections using passwords
+* Kerberos authenticated::      Direct connections with kerberos
+@end menu
+
+@node Connecting via rsh
+@subsection Connecting with rsh
+
+@cindex rsh
+CVS uses the @file{rsh} protocol to perform these
+operations, so the remote user host needs to have a
+@file{.rhosts} file which grants access to the local
+user.
+
+For example, suppose you are the user @file{mozart} on
+the local machine @file{anklet.grunge.com}, and the
+server machine is @file{chainsaw.brickyard.com}.  On
+chainsaw, put the following line into the file
+@file{.rhosts} in @file{bach}'s home directory:
+
+@example
+anklet.grunge.com  mozart
+@end example
+
+Then test that @code{rsh} is working with
+
+@example
+rsh -l bach chainsaw.brickyard.com echo $PATH
+@end example
+
+@cindex CVS_SERVER
+Next you have to make sure that @code{rsh} will be able
+to find the server.  Make sure that the path which
+@code{rsh} printed in the above example includes the
+directory containing a program named @code{cvs} which
+is the server.  You need to set the path in
+@file{.bashrc}, @file{.cshrc}, etc., not @file{.login}
+or @file{.profile}.  Alternately, you can set the
+environment variable @code{CVS_SERVER} on the client
+machine to the filename of the server you want to use,
+for example @file{/usr/local/bin/cvs-1.6}.
+
+There is no need to edit @code{inetd.conf} or start a
+@sc{cvs} server daemon.
+
+Continuing our example, supposing you want to access
+the module @file{foo} in the repository
+@file{/usr/local/cvsroot/}, on machine
+@file{chainsaw.brickyard.com}, you are ready to go:
+
+@example
+cvs -d bach@@chainsaw.brickyard.com:/user/local/cvsroot checkout foo
+@end example
+
+(The @file{bach@@} can be omitted if the username is
+the same on both the local and remote hosts.)
+
+@node Password authenticated
+@subsection Direct connection with password authentication
+
+The @sc{cvs} client can also connect to the server
+using a password protocol.  This is particularly useful
+if using @code{rsh} is not feasible (for example,
+the server is behind a firewall), and Kerberos also is
+not available.
+
+        To use this method, it is necessary to make
+some adjustments on both the server and client sides.
+
+@menu
+* Password authentication server::     Setting up the server
+* Password authentication client::     Using the client
+* Password authentication security::   What this method does and does not do
+@end menu
+
+@node Password authentication server
+@subsubsection Setting up the server for password authentication
+
+@cindex Pserver (subcommand)
+@cindex password server, setting up
+@cindex authenticating server, setting up
+On the server side, the file @file{/etc/inetd.conf}
+needs to be edited so @code{inetd} knows to run the
+command @code{cvs pserver} when it receives a
+connection on the right port.  By default, the port
+number is 2401; it would be different if your client
+were compiled with @code{CVS_AUTH_PORT} defined to
+something else, though.
+
+        If your @code{inetd} allows raw port numbers in
+@file{/etc/inetd.conf}, then the following (all on a
+single line in @file{inetd.conf}) should be sufficient:
+
+@example
+2401  stream  tcp  nowait  root  /usr/local/bin/cvs
+cvs -b /usr/local/bin pserver
+@end example
+
+The @samp{-b} option specifies the directory which contains
+the @sc{rcs} binaries on the server.
+
+        If your @code{inetd} wants a symbolic service
+name instead of a raw port number, then put this in
+@file{/etc/services}:
+
+@example
+cvspserver      2401/tcp
+@end example
+
+        and put @code{cvspserver} instead of
+@code{2401} in @file{inetd.conf}.
+
+        Once the above is taken care of, restart your
+@code{inetd}, or do whatever is necessary to force it
+to reread its initialization files.
+
+@cindex CVS passwd file
+@cindex passwd file
+Because the client stores and transmits passwords in
+cleartext (almost---see @ref{Password authentication
+security} for details), a separate @sc{cvs} password
+file may be used, so people don't compromise their
+regular passwords when they access the repository.
+This file is @file{$CVSROOT/CVSROOT/passwd}
+(@pxref{Intro administrative files}).  Its format is
+similar to @file{/etc/passwd}, except that it only has
+two fields, username and password.  For example:
+
+@example
+bach:ULtgRLXo7NRxs
+cwang:1sOp854gDF3DY
+@end example
+
+The password is encrypted according to the standard
+Unix @code{crypt()} function, so it is possible to
+paste in passwords directly from regular Unix
+@file{passwd} files.
+
+When authenticating a password, the server first checks
+for the user in the @sc{cvs} @file{passwd} file.  If it
+finds the user, it compares against that password.  If
+it does not find the user, or if the @sc{cvs}
+@file{passwd} file does not exist, then the server
+tries to match the password using the system's
+user-lookup routine.  When using the @sc{cvs}
+@file{passwd} file, the server runs under as the
+username specified in the the third argument in the
+entry, or as the first argument if there is no third
+argument (in this way @sc{cvs} allows imaginary
+usernames provided the @sc{cvs} @file{passwd} file
+indicates corresponding valid system usernames).  In
+any case, @sc{cvs} will have no privileges which the
+(valid) user would not have.
+
+Right now, the only way to put a password in the
+@sc{cvs} @file{passwd} file is to paste it there from
+somewhere else.  Someday, there may be a @code{cvs
+passwd} command.
+
+@node Password authentication client
+@subsubsection Using the client with password authentication
+@cindex Login (subcommand)
+@cindex password client, using
+@cindex authenticated client, using
+Before connecting to the server, the client must @dfn{log
+in} with the command @code{cvs login}.  Logging in
+verifies a password with the server, and also records
+the password for later transactions with the server.
+The @code{cvs login} command needs to know the
+username, server hostname, and full repository path,
+and it gets this information from the repository
+argument or the @code{CVSROOT} environment variable.
+
+@code{cvs login} is interactive --- it prompts for a
+password:
+
+@example
+cvs -d bach@@chainsaw.brickyard.com:/usr/local/cvsroot login 
+CVS password: 
+@end example
+
+The password is checked with the server; if it is
+correct, the @code{login} succeeds, else it fails,
+complaining that the password was incorrect.
+
+Once you have logged in, you can force @sc{cvs} to
+connect directly to the server and authenticate with
+the stored password by prefixing the repository with
+@samp{:pserver:}:
+
+@example
+cvs -d :pserver:bach@@chainsaw.brickyard.com:/usr/local/cvsroot checkout foo
+@end example
+
+The @samp{:pserver:} is necessary because without it,
+@sc{cvs} will assume it should use @code{rsh} to
+connect with the server (@pxref{Connecting via rsh}).
+(Once you have a working copy checked out and are
+running @sc{cvs} commands from within it, there is no
+longer any need to specify the repository explicitly,
+because @sc{cvs} records it in the working copy's
+@file{CVS} subdirectory.)
+
+@cindex CVS_PASSFILE, environment variable
+Passwords are stored by default in the file
+@file{$HOME/.cvspass}.  Its format is human-readable,
+but don't edit it unless you know what you are doing.
+The passwords are not stored in cleartext, but are
+trivially encoded to protect them from "innocent"
+compromise (i.e., inadvertently being seen by a system
+administrator who happens to look at that file).
+
+The @code{CVS_PASSFILE} environment variable overrides
+this default.  If you use this variable, make sure you
+set it @emph{before} @code{cvs login} is run.  If you
+were to set it after running @code{cvs login}, then
+later @sc{cvs} commands would be unable to look up the
+password for transmission to the server.
+
+@cindex CVS_PASSWORD, environment variable
+The @code{CVS_PASSWORD} environment variable overrides
+@emph{all} stored passwords.  If it is set, @sc{cvs}
+will use it for all password-authenticated
+connections.
+
+@node Password authentication security
+@subsubsection Security considerations with password authentication
+
+The passwords are stored on the client side in a
+trivial encoding of the cleartext, and transmitted in
+the same encoding.  The encoding is done only to
+prevent inadvertent password compromises (i.e., a
+system administrator accidentally looking at the file),
+and will not prevent even a naive attacker from gaining
+the password.
+
+The separate @sc{cvs} password file (@pxref{Password
+authentication server}) allows people
+to use a different password for repository access than
+for login access.  On the other hand, once a user has
+access to the repository, she can execute programs on
+the server system through a variety of means.  Thus, repository
+access implies fairly broad system access as well.  It
+might be possible to modify @sc{cvs} to prevent that,
+but no one has done so as of this writing.
+Furthermore, there may be other ways in which having
+access to @sc{cvs} allows people to gain more general
+access to the system; noone has done a careful audit.
+
+In summary, anyone who gets the password gets
+repository access, and some measure of general system
+access as well.  The password is available to anyone
+who can sniff network packets or read a protected
+(i.e., user read-only) file.  If you want real
+security, get Kerberos.
+
+@node Kerberos authenticated
+@subsection Direct connection with kerberos
+
+@cindex kerberos
+The main disadvantage of using rsh is that all the data
+needs to pass through additional programs, so it may be
+slower.  So if you have kerberos installed you can
+connect via a direct @sc{tcp} connection,
+authenticating with kerberos (note that the data
+transmitted is @emph{not} encrypted).
+
+To do this, @sc{cvs} needs to be compiled with kerberos
+support; when configuring @sc{cvs} it tries to detect
+whether kerberos is present or you can use the
+@file{--with-krb4} flag to configure.
+
+@cindex CVS_CLIENT_PORT
+You need to edit @code{inetd.conf} on the server
+machine to run @code{cvs kserver}.  The client uses
+port 1999 by default; if you want to use another port
+specify it in the @code{CVS_CLIENT_PORT} environment
+variable on the client.  Set @code{CVS_CLIENT_PORT} to
+@samp{-1} to force an rsh connection.
+
+@cindex kinit
+When you want to use @sc{cvs}, get a ticket in the
+usual way (generally @code{kinit}); it must be a ticket
+which allows you to log into the server machine.  Then
+you are ready to go:
+
+@example
+cvs -d chainsaw.brickyard.com:/user/local/cvsroot checkout foo
+@end example
+
+If @sc{cvs} fails to connect, it will fall back to
+trying rsh.
+
+@c ---------------------------------------------------------------------
+@node Starting a new project
+@chapter Starting a project with CVS
+@cindex Starting a project with CVS
+@cindex Creating a project
+
+@comment --moduledb--
+Since @sc{cvs} 1.x is bad at renaming files and moving
+them between directories, the first thing you do when
+you start a new project should be to think through your
+file organization.  It is not impossible---just
+awkward---to rename or move files.
+@xref{Moving files}.
+
+What to do next depends on the situation at hand.
+
+@menu
+* Setting up the files::        Getting the files into the repository
+* Defining the module::         How to make a module of the files
+@end menu
+@c -- File permissions!
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Setting up the files
+@section Setting up the files
+
+The first step is to create the files inside the repository.  This can
+be done in a couple of different ways.
+
+@c -- The contributed scripts
+@menu
+* From files::                  This method is useful with old projects
+                                where files already exists.
+* From other version control systems::  Old projects where you want to
+                                        preserve history from another system.
+* From scratch::                Creating a module from scratch.
+@end menu
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node From files
+@subsection Creating a module from a number of files
+@cindex Importing files
+
+When you begin using @sc{cvs}, you will probably already have several
+projects that can be
+put under @sc{cvs} control.  In these cases the easiest way is to use the
+@code{import} command.  An example is probably the easiest way to
+explain how to use it.  If the files you want to install in
+@sc{cvs} reside in @file{@var{dir}}, and you want them to appear in the
+repository as @file{$CVSROOT/yoyodyne/@var{dir}}, you can do this:
+
+@example
+$ cd @var{dir}
+$ cvs import -m "Imported sources" yoyodyne/@var{dir} yoyo start
+@end example
+
+Unless you supply a log message with the @samp{-m}
+flag, @sc{cvs} starts an editor and prompts for a
+message.  The string @samp{yoyo} is a @dfn{vendor tag},
+and @samp{start} is a @dfn{release tag}.  They may fill
+no purpose in this context, but since @sc{cvs} requires
+them they must be present.  @xref{Tracking sources}, for
+more information about them.
+
+You can now verify that it worked, and remove your
+original source directory.
+
+@example
+$ cd ..
+$ mv @var{dir} @var{dir}.orig
+$ cvs checkout yoyodyne/@var{dir}       # @r{Explanation below}
+$ ls -R yoyodyne
+$ rm -r @var{dir}.orig
+@end example
+
+@noindent
+Erasing the original sources is a good idea, to make sure that you do
+not accidentally edit them in @var{dir}, bypassing @sc{cvs}.
+Of course, it would be wise to make sure that you have
+a backup of the sources before you remove them.
+
+The @code{checkout} command can either take a module
+name as argument (as it has done in all previous
+examples) or a path name relative to @code{$CVSROOT},
+as it did in the example above.
+
+It is a good idea to check that the permissions
+@sc{cvs} sets on the directories inside @samp{$CVSROOT}
+are reasonable, and that they belong to the proper
+groups.  @xref{File permissions}.
+
+@c The node name is too long, but I am having trouble
+@c thinking of something more concise.
+@node From other version control systems
+@subsection Creating Files From Other Version Control Systems
+@cindex Importing files, from other version control systesm
+
+If you have a project which you are maintaining with
+another version control system, such as @sc{rcs}, you
+may wish to put the files from that project into
+@sc{cvs}, and preserve the revision history of the
+files.
+
+@table @asis
+@cindex RCS, importing files from
+@item From RCS
+If you have been using @sc{rcs}, find the @sc{rcs}
+files---usually a file named @file{foo.c} will have its
+@sc{rcs} file in @file{RCS/foo.c,v} (but it could be
+other places; consult the @sc{rcs} documentation for
+details).  Then create the appropriate directories in
+@sc{cvs} if they do not already exist.  Then copy the
+files into the appropriate directories in the @sc{cvs}
+repository (the name in the repository must be the name
+of the source file with @samp{,v} added; the files go
+directly in the appopriate directory of the repository,
+not in an @file{RCS} subdirectory).  This is one of the
+few times when it is a good idea to access the @sc{cvs}
+repository directly, rather than using @sc{cvs}
+commands.  Then you are ready to check out a new
+working directory.
+@c Someday there probably should be a "cvs import -t
+@c rcs" or some such.  It could even create magic
+@c branches.  It could also do something about the case
+@c where the RCS file had a (non-magic) "0" branch.
+
+@c How many is "many"? Or do they just import RCS files?
+@item From another version control system
+Many version control systems have the ability to export
+@sc{rcs} files in the standard format.  If yours does,
+export the @sc{rcs} files and then follow the above
+instructions.
+
+@cindex SCCS, importing files from
+@item From SCCS
+There is a script in the @file{contrib} directory of
+the @sc{cvs} source distribution called @file{sccs2rcs}
+which converts @sc{sccs} files to @sc{rcs} files.
+Note: you must run it on a machine which has both
+@sc{sccs} and @sc{rcs} installed, and like everything
+else in contrib it is unsupported (your mileage may
+vary).
+@end table
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node From scratch
+@subsection Creating a module from scratch
+
+For a new project, the easiest thing to do is probably
+to create an empty directory structure, like this:
+
+@example
+$ mkdir tc
+$ mkdir tc/man
+$ mkdir tc/testing
+@end example
+
+After that, you use the @code{import} command to create
+the corresponding (empty) directory structure inside
+the repository:
+
+@example
+$ cd tc
+$ cvs import -m "Created directory structure" yoyodyne/@var{dir} yoyo start
+@end example
+
+Then, use @code{add} to add files (and new directories)
+as they appear.
+
+Check that the permissions @sc{cvs} sets on the
+directories inside @samp{$CVSROOT} are reasonable.
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Defining the module
+@section Defining the module
+@cindex Defining a module
+@cindex Editing the modules file
+@cindex Module, defining
+@cindex Modules file, changing
+
+The next step is to define the module in the
+@file{modules} file.  This is not strictly necessary,
+but modules can be convenient in grouping together
+related files and directories.
+
+In simple cases these steps are sufficient to define a module.
+
+@enumerate
+@item
+Get a working copy of the modules file.
+
+@example
+$ cvs checkout modules
+$ cd modules
+@end example
+
+@item
+Edit the file and insert a line that defines the module.  @xref{Intro
+administrative files}, for an introduction.  @xref{modules}, for a full
+description of the modules file.  You can use the
+following line to define the module @samp{tc}:
+
+@example
+tc   yoyodyne/tc
+@end example
+
+@item
+Commit your changes to the modules file.
+
+@example
+$ cvs commit -m "Added the tc module." modules
+@end example
+
+@item
+Release the modules module.
+
+@example
+$ cd ..
+$ cvs release -d modules
+@end example
+@end enumerate
+
+@c ---------------------------------------------------------------------
+@node Multiple developers
+@chapter Multiple developers
+@cindex Multiple developers
+@cindex Team of developers
+@cindex File locking
+@cindex Locking files
+@cindex Working copy
+
+When more than one person works on a software project
+things often get complicated.  Often, two people try to
+edit the same file simultaneously.  Some other version
+control systems (including @sc{rcs} and @sc{sccs})
+try to solve that particular problem by introducing
+@dfn{file locking}, so that only one person can edit
+each file at a time.  Unfortunately, file locking can
+be very counter-productive.  If two persons want
+to edit different parts of a file, there may be no
+reason to prevent either of them from doing so.
+
+@sc{cvs} does not use file locking.  Instead, it allows many
+people to edit their own @dfn{working copy} of a file
+simultaneously.  The first person that commits his
+changes has no automatic way of knowing that another has started to
+edit it.  Others will get an error message when they
+try to commit the file.  They must then use @sc{cvs}
+commands to bring their working copy up to date with
+the repository revision.  This process is almost
+automatic, and explained in this chapter.
+
+There are many ways to organize a team of developers.
+@sc{cvs} does not try to enforce a certain
+organization.  It is a tool that can be used in several
+ways.  It is often useful to inform the group of
+commits you have done.  @sc{cvs} has several ways of
+automating that process.  @xref{Informing others}.
+@xref{Revision management}, for more tips on how to use
+@sc{cvs}.
+
+@menu
+* File status::                 A file can be in several states
+* Updating a file::             Bringing a file up-to-date
+* Conflicts example::           An informative example
+* Informing others::            To cooperate you must inform
+* Concurrency::                 Simultaneous repository access
+* Watches::                     Mechanisms to track who is editing files
+@end menu
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node File status
+@section File status
+@cindex File status
+@cindex Status of a file
+@cindex Four states of a file
+
+After you have checked out a file out from @sc{cvs}, it is in
+one of these four states:
+
+@table @asis
+@cindex Up-to-date
+@item Up-to-date
+The file is identical with the latest revision in the
+repository.
+@c -- The above is not always true if branching is used.
+
+@item Locally modified
+@cindex Locally modified
+You have edited the file, and not yet committed your changes.
+
+@item Needing update
+@cindex Needing update
+Someone else has committed a newer revision to the repository.
+
+@item Needing merge
+@cindex Needing merge
+Someone else have committed a newer revision to the repository, and you
+have also made modifications to the file.
+@c -- What about "added" "removed" and so on?
+@end table
+
+You can use the @code{status} command to find out the status of a given
+file.  @xref{status}.
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Updating a file
+@section Bringing a file up to date
+@cindex Bringing a file up to date
+@cindex Updating a file
+@cindex Merging a file
+@cindex update, introduction
+
+When you want to update or merge a file, use the @code{update}
+command.  For files that are not up to date this is roughly equivalent
+to a @code{checkout} command: the newest revision of the file is
+extracted from the repository and put in your working copy of the
+module.
+
+Your modifications to a file are never lost when you
+use @code{update}.  If no newer revision exists,
+running @code{update} has no effect.  If you have
+edited the file, and a newer revision is available,
+@sc{cvs} will merge all changes into your working copy.
+
+For instance, imagine that you checked out revision 1.4 and started
+editing it.  In the meantime someone else committed revision 1.5, and
+shortly after that revision 1.6.  If you run @code{update} on the file
+now, @sc{cvs} will incorporate all changes between revision 1.4 and 1.6 into
+your file.
+
+@cindex Overlap
+If any of the changes between 1.4 and 1.6 were made too
+close to any of the changes you have made, an
+@dfn{overlap} occurs.  In such cases a warning is
+printed, and the resulting file includes both
+versions of the lines that overlap, delimited by
+special markers.
+@xref{update}, for a complete description of the
+@code{update} command.
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Conflicts example
+@section Conflicts example
+@cindex Merge, an example
+@cindex Example of merge
+@cindex driver.c (merge example)
+
+Suppose revision 1.4 of @file{driver.c} contains this:
+
+@example
+#include <stdio.h>
+
+void main()
+@{
+    parse();
+    if (nerr == 0)
+        gencode();
+    else
+        fprintf(stderr, "No code generated.\n");
+    exit(nerr == 0 ? 0 : 1);
+@}
+@end example
+
+@noindent
+Revision 1.6 of @file{driver.c} contains this:
+
+@example
+#include <stdio.h>
+
+int main(int argc,
+         char **argv)
+@{
+    parse();
+    if (argc != 1)
+    @{
+        fprintf(stderr, "tc: No args expected.\n");
+        exit(1);
+    @}
+    if (nerr == 0)
+        gencode();
+    else
+        fprintf(stderr, "No code generated.\n");
+    exit(!!nerr);
+@}
+@end example
+
+@noindent
+Your working copy of @file{driver.c}, based on revision
+1.4, contains this before you run @samp{cvs update}:
+@c -- Really include "cvs"?
+
+@example
+#include <stdlib.h>
+#include <stdio.h>
+
+void main()
+@{
+    init_scanner();
+    parse();
+    if (nerr == 0)
+        gencode();
+    else
+        fprintf(stderr, "No code generated.\n");
+    exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
+@}
+@end example
+
+@noindent
+You run @samp{cvs update}:
+@c -- Really include "cvs"?
+
+@example
+$ cvs update driver.c
+RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v
+retrieving revision 1.4
+retrieving revision 1.6
+Merging differences between 1.4 and 1.6 into driver.c
+rcsmerge warning: overlaps during merge
+cvs update: conflicts found in driver.c
+C driver.c
+@end example
+
+@noindent
+@cindex Conflicts (merge example)
+@sc{cvs} tells you that there were some conflicts.
+Your original working file is saved unmodified in
+@file{.#driver.c.1.4}.  The new version of
+@file{driver.c} contains this:
+
+@example
+#include <stdlib.h>
+#include <stdio.h>
+
+int main(int argc,
+         char **argv)
+@{
+    init_scanner();
+    parse();
+    if (argc != 1)
+    @{
+        fprintf(stderr, "tc: No args expected.\n");
+        exit(1);
+    @}
+    if (nerr == 0)
+        gencode();
+    else
+        fprintf(stderr, "No code generated.\n");
+<<<<<<< driver.c
+    exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
+=======
+    exit(!!nerr);
+>>>>>>> 1.6
+@}
+@end example
+
+@noindent
+@cindex Markers, conflict
+@cindex Conflict markers
+@cindex <<<<<<<
+@cindex >>>>>>>
+@cindex =======
+
+Note how all non-overlapping modifications are incorporated in your working
+copy, and that the overlapping section is clearly marked with
+@samp{<<<<<<<}, @samp{=======} and @samp{>>>>>>>}.
+
+@cindex Resolving a conflict
+@cindex Conflict resolution
+You resolve the conflict by editing the file, removing the markers and
+the erroneous line.  Suppose you end up with this file:
+@c -- Add xref to the pcl-cvs manual when it talks
+@c -- about this.
+@example
+#include <stdlib.h>
+#include <stdio.h>
+
+int main(int argc,
+         char **argv)
+@{
+    init_scanner();
+    parse();
+    if (argc != 1)
+    @{
+        fprintf(stderr, "tc: No args expected.\n");
+        exit(1);
+    @}
+    if (nerr == 0)
+        gencode();
+    else
+        fprintf(stderr, "No code generated.\n");
+    exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
+@}
+@end example
+
+@noindent
+You can now go ahead and commit this as revision 1.7.
+
+@example
+$ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c
+Checking in driver.c;
+/usr/local/cvsroot/yoyodyne/tc/driver.c,v  <--  driver.c
+new revision: 1.7; previous revision: 1.6
+done
+@end example
+
+@cindex emerge
+If you use release 1.04 or later of pcl-cvs (a @sc{gnu}
+Emacs front-end for @sc{cvs}) you can use an Emacs
+package called emerge to help you resolve conflicts.
+See the documentation for pcl-cvs.
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Informing others
+@section Informing others about commits
+@cindex Informing others
+@cindex Spreading information
+@cindex Mail, automatic mail on commit
+
+It is often useful to inform others when you commit a
+new revision of a file.  The @samp{-i} option of the
+@file{modules} file, or the @file{loginfo} file, can be
+used to automate this process.  @xref{modules}.
+@xref{loginfo}.  You can use these features of @sc{cvs}
+to, for instance, instruct @sc{cvs} to mail a
+message to all developers, or post a message to a local
+newsgroup.
+@c -- More text would be nice here.
+
+@node Concurrency
+@section Several developers simultaneously attempting to run CVS
+
+@cindex locks, cvs
+If several developers try to run @sc{cvs} at the same
+time, one may get the following message:
+
+@example
+[11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo
+@end example
+
+@sc{cvs} will try again every 30 seconds, and either
+continue with the operation or print the message again,
+if it still needs to wait.  If a lock seems to stick
+around for an undue amount of time, find the person
+holding the lock and ask them about the cvs command
+they are running.  If they aren't running a cvs
+command, look for and remove files starting with
+@file{#cvs.tfl}, @file{#cvs.rfl}, or @file{#cvs.wfl}
+from the repository.
+
+Note that these locks are to protect @sc{cvs}'s
+internal data structures and have no relationship to
+the word @dfn{lock} in the sense used by @sc{rcs}--a
+way to prevent other developers from working on a
+particular file.
+
+Any number of people can be reading from a given
+repository at a time; only when someone is writing do
+the locks prevent other people from reading or writing.
+
+@cindex Atomic transactions, lack of
+@cindex Transactions, atomic, lack of
+One might hope for the following property
+
+@example
+If someone commits some changes in one cvs command,
+then an update by someone else will either get all the
+changes, or none of them.
+@end example
+
+but @sc{cvs} does @emph{not} have this property.  For
+example, given the files
+
+@example
+a/one.c
+a/two.c
+b/three.c
+b/four.c
+@end example
+
+if someone runs
+
+@example
+cvs ci a/two.c b/three.c
+@end example
+
+and someone else runs @code{cvs update} at the same
+time, the person running @code{update} might get only
+the change to @file{b/three.c} and not the change to
+@file{a/two.c}.
+
+@node Watches
+@section Mechanisms to track who is editing files
+@cindex Watches
+
+For many groups, use of @sc{cvs} in its default mode is
+perfectly satisfactory.  Users may sometimes go to
+check in a modification only to find that another
+modification has intervened, but they deal with it and
+proceed with their check in.  Other groups prefer to be
+able to know who is editing what files, so that if two
+people try to edit the same file they can choose to
+talk about who is doing what when rather than be
+surprised at check in time.  The features in this
+section allow such coordination, while retaining the
+ability of two developers to edit the same file at the
+same time.
+
+For maximum benefit developers should use @code{cvs
+edit} (not @code{chmod}) to make files read-write to
+edit them, and @code{cvs release} (not @code{rm}) to
+discard a working directory which is no longer in use,
+but @sc{cvs} is not able to enforce this behavior.
+
+@c I'm a little dissatisfied with this presentation,
+@c because "watch on"/"edit"/"editors" are one set of
+@c functionality, and "watch add"/"watchers" is another
+@c which is somewhat orthogonal even though they interact in
+@c various ways.  But I think it might be
+@c confusing to describe them separately (e.g. "watch
+@c add" with loginfo).  I don't know.
+
+@menu
+* Setting a watch::             Telling CVS to watch certain files
+* Getting Notified::            Telling CVS to notify you
+* Editing files::               How to edit a file which is being watched
+* Watch information::           Information about who is watching and editing
+* Watches Compatibility::       Watches interact poorly with CVS 1.6 or earlier
+@end menu
+
+@node Setting a watch
+@subsection Telling CVS to watch certain files
+
+To enable the watch features, you first specify that
+certain files are to be watched.
+
+@cindex watch on (subcommand)
+@deffn Command {cvs watch on} [@code{-l}] files @dots{}
+
+Specify that developers should run @code{cvs edit}
+before editing @var{files}.  CVS will create working
+copies of @var{files} read-only, to remind developers
+to run the @code{cvs edit} command before working on
+them.
+
+If @var{files} includes the name of a directory, CVS
+arranges to watch all files added to the corresponding
+repository directory, and sets a default for files
+added in the future; this allows the user to set
+notification policies on a per-directory basis.  The
+contents of the directory are processed recursively,
+unless the @code{-l} option is given.
+
+If @var{files} is omitted, it defaults to the current directory.
+
+@cindex watch off (subcommand)
+@end deffn
+
+@deffn Command {cvs watch off} [@code{-l}] files @dots{}
+
+Do not provide notification about work on @var{files}.  CVS will create
+working copies of @var{files} read-write.
+
+The @var{files} and @code{-l} arguments are processed as for @code{cvs
+watch on}.
+
+@end deffn
+
+@node Getting Notified
+@subsection Telling CVS to notify you
+
+You can tell @sc{cvs} that you want to receive
+notifications about various actions taken on a file.
+You can do this without using @code{cvs watch on} for
+the file, but generally you will want to use @code{cvs
+watch on}, so that developers use the @code{cvs edit}
+command.
+
+@cindex watch add (subcommand)
+@deffn Command {cvs watch add} [@code{-a} action] [@code{-l}] files @dots{}
+
+Add the current user to the list of people to receive notification of
+work done on @var{files}.
+
+The @code{-a} option specifies what kinds of events CVS should notify
+the user about.  @var{action} is one of the following:
+
+@table @code
+
+@item edit
+Another user has applied the @code{cvs edit} command (described
+below) to a file.
+
+@item unedit
+Another user has applied the @code{cvs unedit} command (described
+below) or the @code{cvs release} command to a file, or has deleted
+the file and allowed @code{cvs update} to recreate it.
+
+@item commit
+Another user has committed changes to a file.
+
+@item all
+All of the above.
+
+@item none
+None of the above.  (This is useful with @code{cvs edit},
+described below.)
+
+@end table
+
+The @code{-a} option may appear more than once, or not at all.  If
+omitted, the action defaults to @code{all}.
+
+The @var{files} and @code{-l} option are processed as for the
+@code{cvs watch} commands.
+
+@end deffn
+
+
+@cindex watch remove (subcommand)
+@deffn Command {cvs watch remove} [@code{-a} action] [@code{-l}] files @dots{}
+
+Remove a notification request established using @code{cvs watch add};
+the arguments are the same.  If the @code{-a} option is present, only
+watches for the specified actions are removed.
+
+@end deffn
+
+When the conditions exist for notification, @sc{cvs}
+calls the @file{notify} administrative file, passing it
+the user to receive the notification and the user who
+is taking the action which results in notification.
+Normally @file{notify} will just send an email message.
+
+@cindex users (admin file)
+Note that if you set this up in the straightforward
+way, users receive notifications on the server machine.
+One could of course write a @file{notify} script which
+directed notifications elsewhere, but to make this
+easy, @sc{cvs} allows you to associate a notification
+address for each user.  To do so create a file
+@file{users} in @file{CVSROOT} with a line for each
+user in the format @var{user}:@var{value}.  Then
+instead of passing the name of the user to be notified
+to @file{notify}, @sc{cvs} will pass the @var{value}
+(normally an email address on some other machine).
+
+@node Editing files
+@subsection How to edit a file which is being watched
+
+Since a file which is being watched is checked out
+read-only, you cannot simply edit it.  To make it
+read-write, and inform others that you are planning
+to edit it, use the @code{cvs edit} command.
+
+@cindex edit (subcommand)
+@deffn Command {cvs edit} [options] files @dots{}
+
+Prepare to edit the working files @var{files}.  CVS makes the
+@var{files} read-write, and notifies users who have requested
+@code{edit} notification for any of @var{files}.
+
+The @code{cvs edit} command accepts the same @var{options} as the
+@code{cvs watch add} command, and establishes a temporary watch for the
+user on @var{files}; CVS will remove the watch when @var{files} are
+@code{unedit}ed or @code{commit}ted.  If the user does not wish to
+receive notifications, she should specify @code{-a none}.
+
+The @var{files} and @code{-l} option are processed as for the @code{cvs
+watch} commands.
+
+@end deffn
+
+Normally when you are done with a set of changes, you
+use the @code{cvs commit} command, which checks in your
+changes and returns the watched files to their usual
+read-only state.  But if you instead decide to abandon
+your changes, or not to make any changes, you can use
+the @code{cvs unedit} command.
+
+@cindex unedit (subcommand)
+@deffn Command {cvs unedit} [@code{-l}] files @dots{}
+
+Abandon work on the working files @var{files}, and revert them to the
+repository versions on which they are based.  CVS makes those
+@var{files} read-only for which users have requested notification using
+@code{cvs watch on}.  CVS notifies users who have requested @code{unedit}
+notification for any of @var{files}.
+
+The @var{files} and @code{-l} option are processed as for the
+@code{cvs watch} commands.
+
+@end deffn
+
+When using client/server @sc{cvs}, you can use the
+@code{cvs edit} and @code{cvs unedit} commands even if
+@sc{cvs} is unable to succesfully communicate with the
+server; the notifications will be sent upon the next
+successful @sc{cvs} command.
+
+@node Watch information
+@subsection Information about who is watching and editing
+
+@cindex watchers (subcommand)
+@deffn Command {cvs watchers} [@code{-l}] files @dots{}
+
+List the users currently watching changes to @var{files}.  The report
+includes the files being watched, and the mail address of each watcher.
+
+The @var{files} and @code{-l} arguments are processed as for the
+@code{cvs watch} commands.
+
+@end deffn
+
+
+@cindex editors (subcommand)
+@deffn Command {cvs editors} [@code{-l}] files @dots{}
+
+List the users currently working on @var{files}.  The report
+includes the mail address of each user, the time when the user began
+working with the file, and the host and path of the working directory
+containing the file.
+
+The @var{files} and @code{-l} arguments are processed as for the
+@code{cvs watch} commands.
+
+@end deffn
+
+@node Watches Compatibility
+@subsection Using watches with old versions of CVS
+
+@cindex CVS 1.6, and watches
+If you use the watch features on a repository, it
+creates @file{CVS} directories in the repository and
+stores the information about watches in that directory.
+If you attempt to use @sc{cvs} 1.6 or earlier with the
+repository, you get an error message such as
+
+@example
+cvs update: cannot open CVS/Entries for reading: No such file or directory
+@end example
+
+and your operation will likely be aborted.  To use the
+watch features, you must upgrade all copies of @sc{cvs}
+which use that repository in local or server mode.  If
+you cannot upgrade, use the @code{watch off} and
+@code{watch remove} commands to remove all watches, and
+that will restore the repository to a state which
+@sc{cvs} 1.6 can cope with.
+
+@c ---------------------------------------------------------------------
+@node Branches
+@chapter Branches
+@cindex Branches
+@cindex Main trunk and branches
+@cindex Revision tree, making branches
+
+So far, all revisions shown in this manual have been on
+the @dfn{main trunk}
+of the revision tree, i.e., all revision numbers
+have been of the form @var{x}.@var{y}.  One useful
+feature, especially when maintaining several releases
+of a software product at once, is the ability to make
+branches on the revision tree.  @dfn{Tags}, symbolic
+names for revisions, will also be
+introduced in this chapter.
+
+@menu
+* Tags::                        Tags--Symbolic revisions
+* Branches motivation::         What branches are good for
+* Creating a branch::           Creating a branch
+* Sticky tags::                 Sticky tags
+@end menu
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Tags
+@section Tags--Symbolic revisions
+@cindex Tags
+
+The revision numbers live a life of their own.  They
+need not have anything at all to do with the release
+numbers of your software product.  Depending
+on how you use @sc{cvs} the revision numbers might change several times
+between two releases.  As an example, some of the
+source files that make up @sc{rcs} 5.6 have the following
+revision numbers:
+@cindex RCS revision numbers
+
+@example
+ci.c            5.21
+co.c            5.9
+ident.c         5.3
+rcs.c           5.12
+rcsbase.h       5.11
+rcsdiff.c       5.10
+rcsedit.c       5.11
+rcsfcmp.c       5.9
+rcsgen.c        5.10
+rcslex.c        5.11
+rcsmap.c        5.2
+rcsutil.c       5.10
+@end example
+
+@cindex tag, command, introduction
+@cindex Tag, symbolic name
+@cindex Symbolic name (tag)
+@cindex Name, symbolic (tag)
+You can use the @code{tag} command to give a symbolic name to a
+certain revision of a file.  You can use the @samp{-v} flag to the
+@code{status} command to see all tags that a file has, and
+which revision numbers they represent.  Tag names can
+contain uppercase and lowercase letters, digits,
+@samp{-}, and @samp{_}.  The two tag names @code{BASE}
+and @code{HEAD} are reserved for use by @sc{cvs}.  It
+is expected that future names which are special to
+@sc{cvs} will contain characters such as @samp{%} or
+@samp{=}, rather than being named analogously to
+@code{BASE} and @code{HEAD}, to avoid conflicts with
+actual tag names.
+@c FIXME: is the above list of valid characters in tag
+@c names complete?
+
+@cindex Adding a tag
+@cindex tag, example
+The following example shows how you can add a tag to a
+file.  The commands must be issued inside your working
+copy of the module.  That is, you should issue the
+command in the directory where @file{backend.c}
+resides.
+
+@example
+$ cvs tag release-0-4 backend.c
+T backend.c
+$ cvs status -v backend.c
+===================================================================
+File: backend.c         Status: Up-to-date
+
+    Version:            1.4     Tue Dec  1 14:39:01 1992
+    RCS Version:        1.4     /usr/local/cvsroot/yoyodyne/tc/backend.c,v
+    Sticky Tag:         (none)
+    Sticky Date:        (none)
+    Sticky Options:     (none)
+
+    Existing Tags:
+        release-0-4                     (revision: 1.4)
+
+@end example
+
+There is seldom reason to tag a file in isolation.  A more common use is
+to tag all the files that constitute a module with the same tag at
+strategic points in the development life-cycle, such as when a release
+is made.
+
+@example
+$ cvs tag release-1-0 .
+cvs tag: Tagging .
+T Makefile
+T backend.c
+T driver.c
+T frontend.c
+T parser.c
+@end example
+
+(When you give @sc{cvs} a directory as argument, it generally applies the
+operation to all the files in that directory, and (recursively), to any
+subdirectories that it may contain.  @xref{Recursive behavior}.)
+
+@cindex Retrieving an old revision using tags
+@cindex Tag, retrieving old revisions
+The @code{checkout} command has a flag, @samp{-r}, that lets you check out
+a certain revision of a module.  This flag makes it easy to
+retrieve the sources that make up release 1.0 of the module @samp{tc} at
+any time in the future:
+
+@example
+$ cvs checkout -r release-1-0 tc
+@end example
+
+@noindent
+This is useful, for instance, if someone claims that there is a bug in
+that release, but you cannot find the bug in the current working copy.
+
+You can also check out a module as it was at any given date.
+@xref{checkout options}.
+
+When you tag more than one file with the same tag you
+can think about the tag as "a curve drawn through a
+matrix of filename vs. revision number."  Say we have 5
+files with the following revisions:
+
+@example
+@group
+        file1   file2   file3   file4   file5
+
+        1.1     1.1     1.1     1.1  /--1.1*      <-*-  TAG
+        1.2*-   1.2     1.2    -1.2*-
+        1.3  \- 1.3*-   1.3   / 1.3
+        1.4          \  1.4  /  1.4
+                      \-1.5*-   1.5
+                        1.6
+@end group
+@end example
+
+At some time in the past, the @code{*} versions were tagged.
+You can think of the tag as a handle attached to the curve
+drawn through the tagged revisions.  When you pull on
+the handle, you get all the tagged revisions.  Another
+way to look at it is that you "sight" through a set of
+revisions that is "flat" along the tagged revisions,
+like this:
+
+@example
+@group
+        file1   file2   file3   file4   file5
+
+                        1.1
+                        1.2
+                1.1     1.3                       _
+        1.1     1.2     1.4     1.1              /
+        1.2*----1.3*----1.5*----1.2*----1.1     (--- <--- Look here
+        1.3             1.6     1.3              \_
+        1.4                     1.4
+                                1.5
+@end group
+@end example
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Branches motivation
+@section What branches are good for
+@cindex Branches motivation
+@cindex What branches are good for
+@cindex Motivation for branches
+
+Suppose that release 1.0 of tc has been made.  You are continuing to
+develop tc, planning to create release 1.1 in a couple of months.  After a
+while your customers start to complain about a fatal bug.  You check
+out release 1.0 (@pxref{Tags}) and find the bug
+(which turns out to have a trivial fix).  However, the current revision
+of the sources are in a state of flux and are not expected to be stable
+for at least another month.  There is no way to make a
+bugfix release based on the newest sources.
+
+The thing to do in a situation like this is to create a @dfn{branch} on
+the revision trees for all the files that make up
+release 1.0 of tc.  You can then make
+modifications to the branch without disturbing the main trunk.  When the
+modifications are finished you can select to either incorporate them on
+the main trunk, or leave them on the branch.
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Creating a branch
+@section Creating a branch
+@cindex Creating a branch
+@cindex Branch, creating a
+@cindex rtag, creating a branch using
+
+@c FIXME: should be more explicit about the value of
+@c having a tag on the branchpoint.  Also should talk
+@c about creating a branch with tag not rtag.
+The @code{rtag} command can be used to create a branch.
+The @code{rtag} command is much like @code{tag}, but it
+does not require that you have a working copy of the
+module.  @xref{rtag}.  (You can also use the @code{tag}
+command; @pxref{tag}).
+
+@example
+$ cvs rtag -b -r release-1-0 release-1-0-patches tc
+@end example
+
+The @samp{-b} flag makes @code{rtag} create a branch
+(rather than just a symbolic revision name).  @samp{-r
+release-1-0} says that this branch should be rooted at the node (in
+the revision tree) that corresponds to the tag
+@samp{release-1-0}.  Note that the numeric revision number that matches
+@samp{release-1-0} will probably be different from file to file.  The
+name of the new branch is @samp{release-1-0-patches}, and the
+module affected is @samp{tc}.
+
+To fix the problem in release 1.0, you need a working
+copy of the branch you just created.
+
+@example
+$ cvs checkout -r release-1-0-patches tc
+$ cvs status -v driver.c backend.c
+===================================================================
+File: driver.c          Status: Up-to-date
+
+    Version:            1.7     Sat Dec  5 18:25:54 1992
+    RCS Version:        1.7     /usr/local/cvsroot/yoyodyne/tc/driver.c,v
+    Sticky Tag:         release-1-0-patches (branch: 1.7.2)
+    Sticky Date:        (none)
+    Sticky Options:     (none)
+
+    Existing Tags:
+        release-1-0-patches             (branch: 1.7.2)
+        release-1-0                     (revision: 1.7)
+
+===================================================================
+File: backend.c         Status: Up-to-date
+
+    Version:            1.4     Tue Dec  1 14:39:01 1992
+    RCS Version:        1.4     /usr/local/cvsroot/yoyodyne/tc/backend.c,v
+    Sticky Tag:         release-1-0-patches (branch: 1.4.2)
+    Sticky Date:        (none)
+    Sticky Options:     (none)
+
+    Existing Tags:
+        release-1-0-patches             (branch: 1.4.2)
+        release-1-0                     (revision: 1.4)
+        release-0-4                     (revision: 1.4)
+
+@end example
+
+@cindex Branch numbers
+As the output from the @code{status} command shows the branch
+number is created by adding a digit at the tail of the revision number
+it is based on.  (If @samp{release-1-0} corresponds to revision 1.4, the
+branch's revision number will be 1.4.2.  For obscure reasons @sc{cvs} always
+gives branches even numbers, starting at 2.
+@xref{Revision numbers}).
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Sticky tags
+@section Sticky tags
+@cindex Sticky tags
+@cindex Tags, sticky
+@cindex Branches, sticky
+
+@c FIXME: make this stand alone better; many places
+@c @xref to this node.
+The @samp{-r release-1-0-patches} flag that was given
+to @code{checkout} in the previous example
+is @dfn{sticky}, that is, it will apply to subsequent commands
+in this directory.  If you commit any modifications, they are
+committed on the branch.  You can later merge the modifications into
+the main trunk.  @xref{Merging}.
+
+You can use the @code{status} command to see what
+sticky tags or dates are set:
+
+@c FIXME: This example needs to stand alone better and it
+@c would also better if it didn't use -v which only
+@c clutters the output in this context.
+@example
+$ vi driver.c   # @r{Fix the bugs}
+$ cvs commit -m "Fixed initialization bug" driver.c
+Checking in driver.c;
+/usr/local/cvsroot/yoyodyne/tc/driver.c,v  <--  driver.c
+new revision: 1.7.2.1; previous revision: 1.7
+done
+$ cvs status -v driver.c
+===================================================================
+File: driver.c          Status: Up-to-date
+
+    Version:            1.7.2.1 Sat Dec  5 19:35:03 1992
+    RCS Version:        1.7.2.1 /usr/local/cvsroot/yoyodyne/tc/driver.c,v
+    Sticky Tag:         release-1-0-patches (branch: 1.7.2)
+    Sticky Date:        (none)
+    Sticky Options:     (none)
+
+    Existing Tags:
+        release-1-0-patches             (branch: 1.7.2)
+        release-1-0                     (revision: 1.7)
+
+@end example
+
+@cindex Resetting sticky tags
+@cindex Sticky tags, resetting
+@cindex Deleting sticky tags
+The sticky tags will remain on your working files until
+you delete them with @samp{cvs update -A}.  The
+@samp{-A} option retrieves the version of the file from
+the head of the trunk, and forgets any sticky tags,
+dates, or options.
+
+@c Is the fact that CVS works this way a bug or a
+@c feature?  If a feature, describe how you would use
+@c it to do something useful.
+Sticky tags are not just for branches.  If you check
+out a certain revision (such as 1.4) it will also
+become sticky.  Subsequent @samp{cvs update} will not
+retrieve the latest revision until you reset the tag
+with @samp{cvs update -A}.  Likewise, use of the
+@samp{-D} option to @code{update} or @code{checkout}
+sets a @dfn{sticky date}, which, similarly, causes that
+date to be used for future retrievals.
+
+@cindex Restoring old version of removed file
+@cindex Resurrecting old version of dead file
+Many times you will want to retrieve an old version of
+a file without setting a sticky tag.  The way to do
+that is with the @samp{-p} option to @code{checkout} or
+@code{update}, which sends the contents of the file to
+standard output.  For example, suppose you have a file
+named @file{file1} which existed as revision 1.1, and
+you then removed it (thus adding a dead revision 1.2).
+Now suppose you want to add it again, with the same
+contents it had previously.  Here is how to do it:
+
+@example
+$ cvs update -p -r 1.1 file1 >file1
+===================================================================
+Checking out file1
+RCS:  /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v
+VERS: 1.1
+***************
+$ cvs add file1
+cvs add: version 1.2 of `file1' will be resurrected
+cvs add: use 'cvs commit' to add this file permanently
+$ cvs commit -m test
+Checking in file1;
+/tmp/cvs-sanity/cvsroot/first-dir/file1,v  <--  file1
+new revision: 1.3; previous revision: 1.2
+done
+$ 
+@end example
+
+@c ---------------------------------------------------------------------
+@node Merging
+@chapter Merging
+@cindex Merging
+@cindex Copying changes
+@cindex Branches, copying changes between
+@cindex Changes, copying between branches
+@cindex Modifications, copying between branches
+
+You can include the changes made between any two
+revisions into your working copy, by @dfn{merging}.
+You can then commit that revision, and thus effectively
+copy the changes onto another branch.
+
+@menu
+* Merging a branch::            Merging an entire branch
+* Merging more than once::      Merging from a branch several times
+* Merging two revisions::       Merging differences between two revisions
+@end menu
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Merging a branch
+@section Merging an entire branch
+@cindex Merging a branch
+@cindex -j (merging branches)
+
+You can merge changes made on a branch into your working copy by giving
+the @samp{-j @var{branch}} flag to the @code{update} command.  With one
+@samp{-j @var{branch}} option it merges the changes made between the
+point where the branch forked and newest revision on that branch (into
+your working copy).
+
+@cindex Join
+The @samp{-j} stands for ``join''.
+
+@cindex Branch merge example
+@cindex Example, branch merge
+@cindex Merge, branch example
+Consider this revision tree:
+
+@example
++-----+    +-----+    +-----+    +-----+
+! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !      <- The main trunk
++-----+    +-----+    +-----+    +-----+
+                !
+                !
+                !   +---------+    +---------+
+Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
+                    +---------+    +---------+
+@end example
+
+@noindent
+The branch 1.2.2 has been given the tag (symbolic name) @samp{R1fix}.  The
+following example assumes that the module @samp{mod} contains only one
+file, @file{m.c}.
+
+@example
+$ cvs checkout mod               # @r{Retrieve the latest revision, 1.4}
+
+$ cvs update -j R1fix m.c        # @r{Merge all changes made on the branch,}
+                                 # @r{i.e. the changes between revision 1.2}
+                                 # @r{and 1.2.2.2, into your working copy}
+                                 # @r{of the file.}
+
+$ cvs commit -m "Included R1fix" # @r{Create revision 1.5.}
+@end example
+
+A conflict can result from a merge operation.  If that
+happens, you should resolve it before committing the
+new revision.  @xref{Conflicts example}.
+
+The @code{checkout} command also supports the @samp{-j @var{branch}} flag.  The
+same effect as above could be achieved with this:
+
+@example
+$ cvs checkout -j R1fix mod
+$ cvs commit -m "Included R1fix"
+@end example
+
+@node Merging more than once
+@section Merging from a branch several times
+
+Continuing our example, the revision tree now looks
+like this:
+
+@example
++-----+    +-----+    +-----+    +-----+    +-----+
+! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !      <- The main trunk
++-----+    +-----+    +-----+    +-----+    +-----+
+                !                           *
+                !                          *
+                !   +---------+    +---------+
+Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
+                    +---------+    +---------+
+@end example
+
+where the starred line represents the merge from the
+@samp{R1fix} branch to the main trunk, as just
+discussed.
+
+Now suppose that development continues on the
+@samp{R1fix} branch:
+
+@example
++-----+    +-----+    +-----+    +-----+    +-----+
+! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !      <- The main trunk
++-----+    +-----+    +-----+    +-----+    +-----+
+                !                           *
+                !                          *
+                !   +---------+    +---------+    +---------+
+Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
+                    +---------+    +---------+    +---------+
+@end example
+
+and then you want to merge those new changes onto the
+main trunk.  If you just use the @code{cvs update -j
+R1fix m.c} command again, @sc{cvs} will attempt to
+merge again the changes which you have already merged,
+which can have undesirable side effects.
+
+So instead you need to specify that you only want to
+merge the changes on the branch which have not yet been
+merged into the trunk.  To do that you specify two
+@samp{-j} options, and @sc{cvs} merges the changes from
+the first revision to the second revision.  For
+example, in this case the simplest way would be
+
+@example
+cvs update -j 1.2.2.2 -j R1fix m.c    # @r{Merge changes from 1.2.2.2 to the}
+                                      # @r{head of the R1fix branch}
+@end example
+
+The problem with this is that you need to specify the
+1.2.2.2 revision manually.  A slightly better approach
+might be to use the date the last merge was done:
+
+@example
+cvs update -j R1fix:yesterday -j R1fix m.c
+@end example
+
+Better yet, tag the R1fix branch after every merge into
+the trunk, and then use that tag for subsequent merges:
+
+@example
+cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c
+@end example
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Merging two revisions
+@section Merging differences between any two revisions
+@cindex Merging two revisions
+@cindex Revisions, merging differences between
+@cindex Differences, merging
+
+With two @samp{-j @var{revision}} flags, the @code{update}
+(and @code{checkout}) command can merge the differences
+between any two revisions into your working file.
+
+@cindex Undoing a change
+@cindex Removing a change
+@example
+$ cvs update -j 1.5 -j 1.3 backend.c
+@end example
+
+@noindent
+will @emph{remove} all changes made between revision
+1.3 and 1.5.  Note the order of the revisions!
+
+If you try to use this option when operating on
+multiple files, remember that the numeric revisions will
+probably be very different between the various files
+that make up a module.  You almost always use symbolic
+tags rather than revision numbers when operating on
+multiple files.
+
+@c ---------------------------------------------------------------------
+@node Recursive behavior
+@chapter Recursive behavior
+@cindex Recursive (directory descending)
+@cindex Directory, descending
+@cindex Descending directories
+@cindex Subdirectories
+
+Almost all of the subcommands of @sc{cvs} work
+recursively when you specify a directory as an
+argument.  For instance, consider this directory
+structure:
+
+@example
+      @code{$HOME}
+        |
+        +--@t{tc}
+        |   |
+            +--@t{CVS}
+            |      (internal @sc{cvs} files)
+            +--@t{Makefile}
+            +--@t{backend.c}
+            +--@t{driver.c}
+            +--@t{frontend.c}
+            +--@t{parser.c}
+            +--@t{man}
+            |    |
+            |    +--@t{CVS}
+            |    |  (internal @sc{cvs} files)
+            |    +--@t{tc.1}
+            |     
+            +--@t{testing}
+                 |
+                 +--@t{CVS}
+                 |  (internal @sc{cvs} files)
+                 +--@t{testpgm.t}
+                 +--@t{test2.t}
+@end example
+
+@noindent
+If @file{tc} is the current working directory, the
+following is true:
+
+@itemize @bullet
+@item
+@samp{cvs update testing} is equivalent to @samp{cvs
+update testing/testpgm.t testing/test2.t}
+
+@item
+@samp{cvs update testing man} updates all files in the
+subdirectories 
+
+@item
+@samp{cvs update .} or just @samp{cvs update} updates
+all files in the @code{tc} module
+@end itemize
+
+If no arguments are given to @code{update} it will
+update all files in the current working directory and
+all its subdirectories.  In other words, @file{.} is a
+default argument to @code{update}.  This is also true
+for most of the @sc{cvs} subcommands, not only the
+@code{update} command.
+
+The recursive behavior of the @sc{cvs} subcommands can be
+turned off with the @samp{-l} option.
+
+@example
+$ cvs update -l         # @r{Don't update files in subdirectories}
+@end example
+
+@c ---------------------------------------------------------------------
+@node Adding files
+@chapter Adding files to a module
+@cindex Adding files
+
+To add a new file to a module, follow these steps.
+
+@itemize @bullet
+@item
+You must have a working copy of the module.
+@xref{Getting the source}.
+
+@item
+Create the new file inside your working copy of the module.
+
+@item
+Use @samp{cvs add @var{filename}} to tell @sc{cvs} that you
+want to version control the file.
+
+@item
+Use @samp{cvs commit @var{filename}} to actually check
+in the file into the repository.  Other developers
+cannot see the file until you perform this step.
+
+@item
+If the file contains binary data it might be necessary
+to change the default keyword substitution.
+@xref{Keyword substitution}.  @xref{admin examples}.
+@end itemize
+
+You can also use the @code{add} command to add a new
+directory inside a module.
+
+Unlike most other commands, the @code{add} command is
+not recursive.  You cannot even type @samp{cvs add
+foo/bar}!  Instead, you have to
+
+@example
+$ cd foo
+$ cvs add bar
+@end example
+
+@xref{add}, for a more complete description of the @code{add}
+command.
+
+@c ---------------------------------------------------------------------
+@node Removing files
+@chapter Removing files from a module
+@cindex Removing files
+@cindex Deleting files
+
+Modules change.  New files are added, and old files
+disappear.  Still, you want to be able to retrieve an
+exact copy of old releases of the module.
+
+Here is what you can do to remove a file from a module,
+but remain able to retrieve old revisions:
+
+@itemize @bullet
+@item
+Make sure that you have not made any uncommitted
+modifications to the file.  @xref{Viewing differences},
+for one way to do that.  You can also use the
+@code{status} or @code{update} command.  If you remove
+the file without committing your changes, you will of
+course not be able to retrieve the file as it was
+immediately before you deleted it.
+
+@item
+Remove the file from your working copy of the module.
+You can for instance use @code{rm}.
+
+@item
+Use @samp{cvs remove @var{filename}} to tell @sc{cvs} that
+you really want to delete the file.
+
+@item
+Use @samp{cvs commit @var{filename}} to actually
+perform the removal of the file from the repository.
+@end itemize
+
+When you commit the removal of the file, @sc{cvs}
+records the fact that the file no longer exists.  It is
+possible for a file to exist on only some branches and
+not on others, or to re-add another file with the same
+name later.  CVS will correctly create or not create
+the file, based on the @samp{-r} and @samp{-D} options
+specified to @code{checkout} or @code{update}.
+
+@cindex Remove (subcommand)
+@deffn Command {cvs remove} [@code{-lR}] files @dots{}
+
+Schedule file(s) to be removed from the repository
+(files which have not already been removed from the
+working directory are not processed).  This command
+does not actually remove the file from the repository
+until you commit the removal.  The @samp{-R} option
+(the default) specifies that it will recurse into
+subdirectories; @samp{-l} specifies that it will not.
+@end deffn
+
+Here is an example of removing several files:
+
+@example
+$ cd test
+$ rm ?.c
+$ cvs remove
+cvs remove: Removing .
+cvs remove: scheduling a.c for removal
+cvs remove: scheduling b.c for removal
+cvs remove: use 'cvs commit' to remove these files permanently
+$ cvs ci -m "Removed unneeded files"
+cvs commit: Examining .
+cvs commit: Committing .
+@end example
+
+If you change your mind you can easily resurrect the
+file before you commit it, using the @code{add}
+command.
+
+@example
+$ ls
+CVS   ja.h  oj.c
+$ rm oj.c
+$ cvs remove oj.c
+cvs remove: scheduling oj.c for removal
+cvs remove: use 'cvs commit' to remove this file permanently
+$ cvs add oj.c
+U oj.c
+cvs add: oj.c, version 1.1.1.1, resurrected
+@end example
+
+If you realize your mistake before you run the
+@code{remove} command you can use @code{update} to
+resurrect the file:
+
+@example
+$ rm oj.c
+$ cvs update oj.c
+cvs update: warning: oj.c was lost
+U oj.c
+@end example
+
+@c ---------------------------------------------------------------------
+@node Tracking sources
+@chapter Tracking third-party sources
+@cindex Third-party sources
+@cindex Tracking sources
+
+If you modify a program to better fit your site, you
+probably want to include your modifications when the next
+release of the program arrives.  @sc{cvs} can help you with
+this task.
+
+@cindex Vendor
+@cindex Vendor branch
+@cindex Branch, vendor-
+In the terminology used in @sc{cvs}, the supplier of the
+program is called a @dfn{vendor}.  The unmodified
+distribution from the vendor is checked in on its own
+branch, the @dfn{vendor branch}.  @sc{cvs} reserves branch
+1.1.1 for this use.
+
+When you modify the source and commit it, your revision
+will end up on the main trunk.  When a new release is
+made by the vendor, you commit it on the vendor branch
+and copy the modifications onto the main trunk.
+
+Use the @code{import} command to create and update
+the vendor branch.  After a successful @code{import}
+the vendor branch is made the `head' revision, so
+anyone that checks out a copy of the file gets that
+revision.  When a local modification is committed it is
+placed on the main trunk, and made the `head'
+revision.
+
+@menu
+* First import::                Importing a module for the first time
+* Update imports::              Updating a module with the import command
+@end menu
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node First import
+@section Importing a module for the first time
+@cindex Importing modules
+
+Use the @code{import} command to check in the sources
+for the first time.  When you use the @code{import}
+command to track third-party sources, the @dfn{vendor
+tag} and @dfn{release tags} are useful.  The
+@dfn{vendor tag} is a symbolic name for the branch
+(which is always 1.1.1, unless you use the @samp{-b
+@var{branch}} flag---@xref{import options}).  The
+@dfn{release tags} are symbolic names for a particular
+release, such as @samp{FSF_0_04}.
+
+@cindex Wdiff (import example)
+Suppose you use @code{wdiff} (a variant of @code{diff}
+that ignores changes that only involve whitespace), and
+are going to make private modifications that you want
+to be able to use even when new releases are made in
+the future.  You start by importing the source to your
+repository:
+
+@example
+$ tar xfz wdiff-0.04.tar.gz
+$ cd wdiff-0.04
+$ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04
+@end example
+
+The vendor tag is named @samp{FSF_DIST} in the above
+example, and the only release tag assigned is
+@samp{WDIFF_0_04}.
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Update imports
+@section Updating a module with the import command
+
+When a new release of the source arrives, you import it into the
+repository with the same @code{import} command that you used to set up
+the repository in the first place.  The only difference is that you
+specify a different release tag this time.
+
+@example
+$ tar xfz wdiff-0.05.tar.gz
+$ cd wdiff-0.05
+$ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF_DIST WDIFF_0_05
+@end example
+
+For files that have not been modified locally, the newly created
+revision becomes the head revision.  If you have made local
+changes, @code{import} will warn you that you must merge the changes
+into the main trunk, and tell you to use @samp{checkout -j} to do so.
+
+@example
+$ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff
+@end example
+
+@noindent
+The above command will check out the latest revision of
+@samp{wdiff}, merging the changes made on the vendor branch @samp{FSF_DIST}
+since yesterday into the working copy.  If any conflicts arise during
+the merge they should be resolved in the normal way (@pxref{Conflicts
+example}).  Then, the modified files may be committed.
+
+Using a date, as suggested above, assumes that you do
+not import more than one release of a product per
+day. If you do, you can always use something like this
+instead:
+
+@example
+$ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff
+@end example
+
+@noindent
+In this case, the two above commands are equivalent.
+
+@c ---------------------------------------------------------------------
+@node Moving files
+@chapter Moving and renaming files
+@cindex Moving files
+@cindex Renaming files
+@cindex Files, moving
+
+Moving files to a different directory or renaming them
+is not difficult, but some of the ways in which this
+works may be non-obvious.  (Moving or renaming a
+directory is even harder.  @xref{Moving directories}).
+
+The examples below assume that the file @var{old} is renamed to
+@var{new}.
+
+@menu
+* Outside::                     The normal way to Rename
+* Inside::                      A tricky, alternative way
+* Rename by copying::           Another tricky, alternative way
+@end menu
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Outside
+@section The Normal way to Rename
+
+The normal way to move a file is to copy @var{old} to
+@var{new}, and then issue the normal @sc{cvs} commands
+to remove @var{old} from the repository, and add
+@var{new} to it.  (Both @var{old} and @var{new} could
+contain relative paths, for example @file{foo/bar.c}).
+
+@example
+$ mv @var{old} @var{new}
+$ cvs remove @var{old}
+$ cvs add @var{new} 
+$ cvs commit -m "Renamed @var{old} to @var{new}" @var{old} @var{new}
+@end example
+
+This is the simplest way to move a file, it is not
+error-prone, and it preserves the history of what was
+done.  Note that to access the history of the file you
+must specify the old or the new name, depending on what
+portion of the history you are accessing.  For example,
+@code{cvs log @var{old}} will give the log up until the
+time of the rename.
+
+When @var{new} is committed its revision numbers will
+start at 1.0 again, so if that bothers you, use the
+@samp{-r rev} option to commit (@pxref{commit options})
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Inside
+@section Moving the history file
+
+This method is more dangerous, since it involves moving
+files inside the repository.  Read this entire section
+before trying it out!
+
+@example
+$ cd $CVSROOT/@var{module}
+$ mv @var{old},v @var{new},v
+@end example
+
+@noindent
+Advantages:
+
+@itemize @bullet
+@item
+The log of changes is maintained intact.
+
+@item
+The revision numbers are not affected.
+@end itemize
+
+@noindent
+Disadvantages:
+
+@itemize @bullet
+@item
+Old releases of the module cannot easily be fetched from the
+repository.  (The file will show up as @var{new} even
+in revisions from the time before it was renamed).
+
+@item
+There is no log information of when the file was renamed.
+
+@item
+Nasty things might happen if someone accesses the history file
+while you are moving it.  Make sure no one else runs any of the @sc{cvs}
+commands while you move it.
+@end itemize
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Rename by copying
+@section Copying the history file
+
+This way also involves direct modifications to the
+repository.  It is safe, but not without drawbacks.
+
+@example
+# @r{Copy the @sc{rcs} file inside the repository}
+$ cd $CVSROOT/@var{module}
+$ cp @var{old},v @var{new},v
+# @r{Remove the old file}
+$ cd ~/@var{module}
+$ rm @var{old}
+$ cvs remove @var{old}
+$ cvs commit @var{old}
+# @r{Remove all tags from @var{new}}
+$ cvs update @var{new}
+$ cvs log @var{new}             # @r{Remember the tag names}
+$ cvs tag -d @var{tag1}
+$ cvs tag -d @var{tag2}
+@dots{}
+@end example
+
+By removing the tags you will be able to check out old
+revisions of the module.
+
+@noindent
+Advantages:
+
+@itemize @bullet
+@item
+@c FIXME: Is this true about -D now that we have death
+@c support?  See 5B.3 in the FAQ.
+Checking out old revisions works correctly, as long as
+you use @samp{-r@var{tag}} and not @samp{-D@var{date}}
+to retrieve the revisions.
+
+@item
+The log of changes is maintained intact.
+
+@item
+The revision numbers are not affected.
+@end itemize
+
+@noindent
+Disadvantages:
+
+@itemize @bullet
+@item
+You cannot easily see the history of the file across the rename.
+
+@item
+Unless you use the @samp{-r rev} (@pxref{commit
+options}) flag when @var{new} is committed its revision
+numbers will start at 1.0 again.
+@end itemize
+
+@c ---------------------------------------------------------------------
+@node Moving directories
+@chapter Moving and renaming directories
+@cindex Moving directories
+@cindex Renaming directories
+@cindex Directories, moving
+
+If you want to be able to retrieve old versions of the
+module, you must move each file in the directory
+with the @sc{cvs} commands.  @xref{Outside}.  The old, empty
+directory will remain inside the repository, but it
+will not appear in your workspace when you check out
+the module in the future.
+@c -- rephrase
+
+If you really want to rename or delete a directory, you
+can do it like this:
+
+@enumerate
+@item
+Inform everyone who has a copy of the module that the
+directory will be renamed.  They should commit all
+their changes, and remove their working copies of the
+module, before you take the steps below.
+
+@item
+Rename the directory inside the repository.
+
+@example
+$ cd $CVSROOT/@var{module}
+$ mv @var{old-dir} @var{new-dir}
+@end example
+
+@item
+Fix the @sc{cvs} administrative files, if necessary (for
+instance if you renamed an entire module).
+
+@item
+Tell everyone that they can check out the module and continue
+working.
+
+@end enumerate
+
+If someone had a working copy of the module the @sc{cvs} commands will
+cease to work for him, until he removes the directory
+that disappeared inside the repository.
+
+It is almost always better to move the files in the
+directory instead of moving the directory.  If you move the
+directory you are unlikely to be able to retrieve old
+releases correctly, since they probably depend on the
+name of the directories.
+
+@c ---------------------------------------------------------------------
+@node History browsing
+@chapter History browsing
+@cindex History browsing
+@cindex Traceability
+@cindex Isolation
+
+@ignore
+@c This is too long for an introduction (goal is
+@c one 20x80 character screen), and also mixes up a
+@c variety of issues (parallel development, history,
+@c maybe even touches on process control).
+
+@c -- @quote{To lose ones history is to lose ones soul.}
+@c -- ///
+@c -- ///Those who cannot remember the past are condemned to repeat it.
+@c -- ///               -- George Santayana
+@c -- ///
+
+@sc{cvs} tries to make it easy for a group of people to work
+together.  This is done in two ways:
+
+@itemize @bullet
+@item
+Isolation---You have your own working copy of the
+source.  You are not affected by modifications made by
+others until you decide to incorporate those changes
+(via the @code{update} command---@pxref{update}).
+
+@item 
+Traceability---When something has changed, you can
+always see @emph{exactly} what changed.
+@end itemize
+
+There are several features of @sc{cvs} that together lead
+to traceability:
+
+@itemize @bullet
+@item
+Each revision of a file has an accompanying log
+message.
+
+@item
+All commits are optionally logged to a central history
+database.
+
+@item
+Logging information can be sent to a user-defined
+program (@pxref{loginfo}).
+@end itemize
+
+@c -- More text here.
+
+This chapter should talk about the history file, the
+@code{log} command, the usefulness of ChangeLogs
+even when you run @sc{cvs}, and things like that.
+
+@end ignore
+
+@c kind of lame, in a lot of ways the above text inside
+@c the @ignore motivates this chapter better
+Once you have used @sc{cvs} to store a version control
+history---what files have changed when, how, and by
+whom, there are a variety of mechanisms for looking
+through the history.
+
+@menu
+* log messages::                Log messages
+* history database::            The history database
+* user-defined logging::        User-defined logging
+* annotate::                    What revision modified each line of a file?
+@end menu
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node log messages
+@section Log messages
+
+@c FIXME: @xref to place where we talk about how to
+@c specify message to commit.
+Whenever you commit a file you specify a log message.
+
+@c FIXME: bring the information here, and get rid of or
+@c greatly shrink the "log" node.
+To look through the log messages which have been
+specified for every revision which has been committed,
+use the @code{cvs log} command (@pxref{log}).
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node history database
+@section The history database
+
+@c FIXME: bring the information from the history file
+@c and history nodes here.  Rewrite it to be motivated
+@c better (start out by clearly explaining what gets
+@c logged in history, for example).
+You can use the history file (@pxref{history file}) to
+log various @sc{cvs} actions.  To retrieve the
+information from the history file, use the @code{cvs
+history} command (@pxref{history}).
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node user-defined logging
+@section User-defined logging
+
+@c FIXME: should probably also mention the fact the -l
+@c global option can disable most of the mechanisms
+@c discussed here (why?  What is the -l global option for?).
+@c
+@c FIXME: probably should centralize this information
+@c here, at least to some extent.  Maybe by moving the
+@c loginfo, etc., nodes here and replacing
+@c the "user-defined logging" node with one node for
+@c each method.
+You can customize @sc{cvs} to log various kinds of
+actions, in whatever manner you choose.  These
+mechanisms operate by executing a script at various
+times.  The script might append a message to a file
+listing the information and the programmer who created
+it, or send mail to a group of developers, or, perhaps,
+post a message to a particular newsgroup.  To log
+commits, use the @file{loginfo} file (@pxref{loginfo}).
+@c FIXME: What is difference between doing it in the
+@c modules file and using loginfo/taginfo?  Why should
+@c user use one or the other?
+To log commits, checkouts, exports, and tags,
+respectively, you can also use the @samp{-i},
+@samp{-o}, @samp{-e}, and @samp{-t} options in the
+modules file.  For a more flexible way of giving
+notifications to various users, which requires less in
+the way of keeping centralized scripts up to date, use
+the @code{cvs watch add} command (@pxref{Getting
+Notified}); this command is useful even if you are not
+using @code{cvs watch on}.
+
+@cindex taginfo
+The @file{taginfo} file defines programs to execute
+when someone executes a @code{tag} or @code{rtag}
+command.  The @file{taginfo} file has the standard form
+for administrative files (@pxref{Administrative
+files}), where each line is a regular expression
+followed by a command to execute.  The arguments passed
+to the command are, in order, the @var{tagname},
+@var{operation} (@code{add} for @code{tag},
+@code{mov} for @code{tag -F}, and @code{del} for
+@code{tag -d}), @var{repository}, and any remaining are
+pairs of @var{filename} @var{revision}.  A non-zero
+exit of the filter program will cause the tag to be
+aborted.
+
+@node annotate
+@section Annotate command
+@cindex annotate (subcommand)
+
+@deffn Command {cvs annotate} [@code{-l}] files @dots{}
+
+For each file in @var{files}, print the head revision
+of the trunk, together with information on the last
+modification for each line.  The @code{-l} option means
+to process the local directory only, not to recurse
+(@pxref{Common options}).  For example:
+
+@example
+$ cvs annotate ssfile
+Annotations for ssfile
+***************
+1.1          (mary     27-Mar-96): ssfile line 1
+1.2          (joe      28-Mar-96): ssfile line 2
+@end example
+
+The file @file{ssfile} currently contains two lines.
+The @code{ssfile line 1} line was checked in by
+@code{mary} on March 27.  Then, on March 28, @code{joe}
+added a line @code{ssfile line 2}, without modifying
+the @code{ssfile line 1} line.  This report doesn't
+tell you anything about lines which have been deleted
+or replaced; you need to use @code{cvs diff} for that
+(@pxref{diff}).
+
+@end deffn
+
+@c ---------------------------------------------------------------------
+@node Keyword substitution
+@chapter Keyword substitution
+@cindex Keyword substitution
+@cindex Keyword expansion
+@cindex Identifying files
+
+@comment   Be careful when editing this chapter.
+@comment   Remember that this file is kept under
+@comment   version control, so we must not accidentally
+@comment   include a valid keyword in the running text.
+
+As long as you edit source files inside your working
+copy of a module you can always find out the state of
+your files via @samp{cvs status} and @samp{cvs log}.
+But as soon as you export the files from your
+development environment it becomes harder to identify
+which revisions they are.
+
+@sc{Rcs} uses a mechanism known as @dfn{keyword
+substitution} (or @dfn{keyword expansion}) to help
+identifying the files.  Embedded strings of the form
+@code{$@var{keyword}$} and
+@code{$@var{keyword}:@dots{}$} in a file are replaced
+with strings of the form
+@code{$@var{keyword}:@var{value}$} whenever you obtain
+a new revision of the file.
+
+@menu
+* Keyword list::                RCS Keywords
+* Using keywords::              Using keywords
+* Avoiding substitution::       Avoiding substitution
+* Substitution modes::          Substitution modes
+* Log keyword::                 Problems with the $@asis{}Log$ keyword.
+@end menu
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Keyword list
+@section RCS Keywords
+@cindex RCS keywords
+
+This is a list of the keywords that @sc{rcs} currently
+(in release 5.6.0.1) supports:
+
+@table @code
+@cindex Author keyword
+@item $@asis{Author}$
+The login name of the user who checked in the revision.
+
+@cindex Date keyword
+@item $@asis{Date}$
+The date and time (UTC) the revision was checked in.
+
+@cindex Header keyword
+@item $@asis{Header}$
+A standard header containing the full pathname of the
+@sc{rcs} file, the revision number, the date (UTC), the
+author, the state, and the locker (if locked).  Files
+will normally never be locked when you use @sc{cvs}.
+
+@cindex Id keyword
+@item $@asis{Id}$
+Same as @code{$@asis{Header}$}, except that the @sc{rcs}
+filename is without a path.
+
+@cindex Locker keyword
+@item $@asis{Locker}$
+The login name of the user who locked the revision
+(empty if not locked, and thus almost always useless
+when you are using @sc{cvs}).
+
+@cindex Log keyword
+@item $@asis{Log}$
+The log message supplied during commit, preceded by a
+header containing the @sc{rcs} filename, the revision
+number, the author, and the date (UTC).  Existing log
+messages are @emph{not} replaced.  Instead, the new log
+message is inserted after @code{$@asis{Log:@dots{}}$}.
+Each new line is prefixed with a @dfn{comment leader}
+which @sc{rcs} guesses from the file name extension.
+It can be changed with @code{cvs admin -c}.
+@xref{admin options}.  This keyword is useful for
+accumulating a complete change log in a source file,
+but for several reasons it can be problematic.
+@xref{Log keyword}.
+
+@cindex RCSfile keyword
+@item $@asis{RCSfile}$
+The name of the RCS file without a path.
+
+@cindex Revision keyword
+@item $@asis{Revision}$
+The revision number assigned to the revision.
+
+@cindex Source keyword
+@item $@asis{Source}$
+The full pathname of the RCS file.
+
+@cindex State keyword
+@item $@asis{State}$
+The state assigned to the revision.  States can be
+assigned with @code{cvs admin -s}---@xref{admin options}.
+
+@end table
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Using keywords
+@section Using keywords
+
+To include a keyword string you simply include the
+relevant text string, such as @code{$@asis{Id}$}, inside the
+file, and commit the file.  @sc{cvs} will automatically
+expand the string as part of the commit operation.
+
+@need 800
+It is common to embed @code{$@asis{}Id$} string in the
+C source code.  This example shows the first few lines
+of a typical file, after keyword substitution has been
+performed:
+
+@example
+static char *rcsid="$@asis{}Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $";
+/* @r{The following lines will prevent @code{gcc} version 2.@var{x}}
+   @r{from issuing an "unused variable" warning}. */
+#if __GNUC__ == 2
+#define USE(var) static void * use_##var = (&use_##var, (void *) &var) 
+USE (rcsid);
+#endif
+@end example
+
+Even though a clever optimizing compiler could remove
+the unused variable @code{rcsid}, most compilers tend
+to include the string in the binary.  Some compilers
+have a @code{#pragma} directive to include literal text
+in the binary.
+
+@cindex Ident (shell command)
+The @code{ident} command (which is part of the @sc{rcs}
+package) can be used to extract keywords and their
+values from a file.  This can be handy for text files,
+but it is even more useful for extracting keywords from
+binary files.
+
+@example
+$ ident samp.c
+samp.c:
+     $@asis{}Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
+$ gcc samp.c
+$ ident a.out
+a.out:
+     $@asis{}Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
+@end example
+
+@cindex What (shell command)
+S@sc{ccs} is another popular revision control system.
+It has a command, @code{what}, which is very similar to
+@code{ident} and used for the same purpose.  Many sites
+without @sc{rcs} have @sc{sccs}.  Since @code{what}
+looks for the character sequence @code{@@(#)} it is
+easy to include keywords that are detected by either
+command.  Simply prefix the @sc{rcs} keyword with the
+magic @sc{sccs} phrase, like this:
+
+@example
+static char *id="@@(#) $@asis{}Id: ab.c,v 1.5 1993/10/19 14:57:32 ceder Exp $";
+@end example
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Avoiding substitution
+@section Avoiding substitution
+
+Keyword substitution has its disadvantages.  Sometimes
+you might want the literal text string
+@samp{$@asis{}Author$} to appear inside a file without
+@sc{rcs} interpreting it as a keyword and expanding it
+into something like @samp{$@asis{}Author: ceder $}.  
+
+There is unfortunately no way to selectively turn off
+keyword substitution.  You can use @samp{-ko}
+(@pxref{Substitution modes}) to turn off keyword
+substitution entirely.
+
+In many cases you can avoid using @sc{rcs} keywords in
+the source, even though they appear in the final
+product.  For example, the source for this manual
+contains @samp{$@@asis@{@}Author$} whenever the text
+@samp{$@asis{}Author$} should appear.  In @code{nroff}
+and @code{troff} you can embed the null-character
+@code{\&} inside the keyword for a similar effect.
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Substitution modes
+@section Substitution modes
+@cindex -k (RCS kflags)
+@cindex Kflag
+
+@c FIXME: This could be made more coherent, by expanding it
+@c with more examples or something.
+Each file has a stored default substitution mode, and
+each working directory copy of a file also has a
+substitution mode.  The former is set by the @samp{-k}
+option to @code{cvs add} and @code{cvs admin}; the
+latter is set by the -k or -A options to @code{cvs
+checkout} or @code{cvs update}.  @code{cvs diff} also
+has a @samp{-k} option.  For some examples,
+@xref{Binary files}.
+
+The modes available are:
+
+@table @samp
+@item -kkv
+Generate keyword strings using the default form, e.g.
+@code{$@asis{}Revision: 5.7 $} for the @code{Revision}
+keyword.
+
+@item -kkvl
+Like @samp{-kkv}, except that a locker's name is always
+inserted if the given revision is currently locked.
+This option is normally not useful when @sc{cvs} is used.
+
+@item -kk
+Generate only keyword names in keyword strings; omit
+their values.  For example, for the @code{Revision}
+keyword, generate the string @code{$@asis{}Revision$}
+instead of @code{$@asis{}Revision: 5.7 $}.  This option
+is useful to ignore differences due to keyword
+substitution when comparing different revisions of a
+file.
+
+@item -ko
+Generate the old keyword string, present in the working
+file just before it was checked in.  For example, for
+the @code{Revision} keyword, generate the string
+@code{$@asis{}Revision: 1.1 $} instead of
+@code{$@asis{}Revision: 5.7 $} if that is how the
+string appeared when the file was checked in.
+
+@item -kb
+Like @samp{-ko}, but also inhibit conversion of line
+endings between the canonical form in which they are
+stored in the repository (linefeed only), and the form
+appropriate to the operating system in use on the
+client.  For systems, like unix, which use linefeed
+only to terminate lines, this is the same as
+@samp{-ko}.  For more information on binary files, see
+@ref{Binary files}.
+
+@item -kv
+Generate only keyword values for keyword strings.  For
+example, for the @code{Revision} keyword, generate the string
+@code{5.7} instead of @code{$@asis{}Revision: 5.7 $}.
+This can help generate files in programming languages
+where it is hard to strip keyword delimiters like
+@code{$@asis{}Revision: $} from a string.  However,
+further keyword substitution cannot be performed once
+the keyword names are removed, so this option should be
+used with care.
+
+One often would like to use @samp{-kv} with @code{cvs
+export}---@pxref{export}.  But be aware that doesn't
+handle an export containing binary files correctly.
+
+@end table
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Log keyword
+@section Problems with the $@asis{}Log$ keyword.
+
+The @code{$@asis{}Log$} keyword is somewhat
+controversial.  As long as you are working on your
+development system the information is easily accessible
+even if you do not use the @code{$@asis{}Log$}
+keyword---just do a @code{cvs log}.  Once you export
+the file the history information might be useless
+anyhow.
+
+A more serious concern is that @sc{rcs} is not good at
+handling @code{$@asis{}Log$} entries when a branch is
+merged onto the main trunk.  Conflicts often result
+from the merging operation.
+
+People also tend to "fix" the log entries in the file
+(correcting spelling mistakes and maybe even factual
+errors).  If that is done the information from
+@code{cvs log} will not be consistent with the
+information inside the file.  This may or may not be a
+problem in real life.
+
+It has been suggested that the @code{$@asis{}Log$}
+keyword should be inserted @emph{last} in the file, and
+not in the files header, if it is to be used at all.
+That way the long list of change messages will not
+interfere with everyday source file browsing.
+
+@c ---------------------------------------------------------------------
+@node Binary files
+@chapter Handling binary files
+@cindex Binary files
+
+There are two issues with using @sc{cvs} to store
+binary files.  The first is that @sc{cvs} by default
+convert line endings between the canonical form in
+which they are stored in the repository (linefeed
+only), and the form appropriate to the operating system
+in use on the client (for example, carriage return
+followed by line feed for Windows NT).
+
+The second is that a binary file might happen to
+contain data which looks like a keyword (@pxref{Keyword
+substitution}), so keyword expansion must be turned
+off.
+
+The @samp{-kb} option available with some @sc{cvs}
+commands insures that neither line ending conversion
+nor keyword expansion will be done.  If you are using
+an old version of @sc{rcs} without this option, and you
+are using an operating system, such as unix, which
+terminates lines with linefeeds only, you can use
+@samp{-ko} instead; if you are on another operating
+system, upgrade to a version of @sc{rcs}, such as 5.7
+or later, which supports @samp{-kb}.
+
+Here is an example of how you can create a new file
+using the @samp{-kb} flag:
+
+@example
+$ echo '$@asis{}Id$' > kotest
+$ cvs add -kb -m"A test file" kotest
+$ cvs ci -m"First checkin; contains a keyword" kotest
+@end example
+
+If a file accidentally gets added without @samp{-kb},
+one can use the @code{cvs admin} command to recover.
+For example:
+
+@example
+$ echo '$@asis{}Id$' > kotest
+$ cvs add -m"A test file" kotest
+$ cvs ci -m"First checkin; contains a keyword" kotest
+$ cvs admin -kb kotest
+$ cvs update -A kotest
+@end example
+
+When you check in the file @file{kotest} the keywords
+are expanded.  (Try the above example, and do a
+@code{cat kotest} after every command).  The @code{cvs
+admin -kb} command sets the default keyword
+substitution method for this file, but it does not
+alter the working copy of the file that you have.  The
+easiest way to get the unexpanded version of
+@file{kotest} is @code{cvs update -A}.
+
+@c ---------------------------------------------------------------------
+@node Revision management
+@chapter Revision management
+@cindex Revision management
+
+@c -- This chapter could be expanded a lot.
+@c -- Experiences are very welcome!
+
+If you have read this far, you probably have a pretty
+good grasp on what @sc{cvs} can do for you.  This
+chapter talks a little about things that you still have
+to decide.
+
+If you are doing development on your own using @sc{cvs}
+you could probably skip this chapter.  The questions
+this chapter takes up become more important when more
+than one person is working in a repository.
+
+@menu
+* When to commit::              Some discussion on the subject
+@end menu
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node When to commit
+@section When to commit?
+@cindex When to commit
+@cindex Commit, when to
+@cindex Policy
+
+Your group should decide which policy to use regarding
+commits.  Several policies are possible, and as your
+experience with @sc{cvs} grows you will probably find
+out what works for you.
+
+If you commit files too quickly you might commit files
+that do not even compile.  If your partner updates his
+working sources to include your buggy file, he will be
+unable to compile the code.  On the other hand, other
+persons will not be able to benefit from the
+improvements you make to the code if you commit very
+seldom, and conflicts will probably be more common.
+
+It is common to only commit files after making sure
+that they can be compiled.  Some sites require that the
+files pass a test suite.  Policies like this can be
+enforced using the commitinfo file
+(@pxref{commitinfo}), but you should think twice before
+you enforce such a convention.  By making the
+development environment too controlled it might become
+too regimented and thus counter-productive to the real
+goal, which is to get software written.
+
+@c ---------------------------------------------------------------------
+@node Invoking CVS
+@appendix Reference manual for CVS commands
+@cindex Command reference
+@cindex Reference, commands
+@cindex Invoking CVS
+
+This appendix describes how to invoke @sc{cvs}, and
+describes in detail those subcommands of @sc{cvs} which
+are not fully described elsewhere.  To look up a
+particular subcommand, see @ref{Index}.
+
+@menu
+* Structure::                   Overall structure of CVS commands
+* ~/.cvsrc::                    Default options with the ~/.csvrc file
+* Global options::              Options you give to the left of cvs_command
+* Common options::              Options you give to the right of cvs_command
+* add::                         Add a new file/directory to the repository
+* admin::                       Administration front end for rcs
+* checkout::                    Checkout sources for editing
+* commit::                      Check files into the repository
+* diff::                        Run diffs between revisions
+* export::                      Export sources from CVS, similar to checkout
+* history::                     Show status of files and users
+* import::                      Import sources into CVS, using vendor branches
+* log::                         Print out 'rlog' information for files
+* rdiff::                       'patch' format diffs between releases
+* release::                     Indicate that a Module is no longer in use
+* rtag::                        Add a tag to a module
+* status::                      Status info on the revisions
+* tag::                         Add a tag to checked out version
+* update::                      Bring work tree in sync with repository
+@end menu
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Structure
+@appendixsec Overall structure of CVS commands
+@cindex Structure
+@cindex CVS command structure
+@cindex Command structure
+@cindex Format of CVS commands
+
+The first release of @sc{cvs} consisted of a number of shell-scripts.
+Today @sc{cvs} is implemented as a single program that is a front-end
+to @sc{rcs} and @code{diff}. The overall format of all
+@sc{cvs} commands is:
+
+@example
+cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ]
+@end example
+
+@table @code
+@item cvs
+The program that is a front-end to @sc{rcs}.
+
+@item cvs_options
+Some options that affect all sub-commands of @sc{cvs}.  These are
+described below.
+
+@item cvs_command
+One of several different sub-commands.  Some of the commands have
+aliases that can be used instead; those aliases are noted in the
+reference manual for that command.  There are only two situations
+where you may omit @samp{cvs_command}: @samp{cvs -H} elicits a
+list of available commands, and @samp{cvs -v} displays version
+information on @sc{cvs} itself.
+
+@item command_options
+Options that are specific for the command.
+
+@item command_args
+Arguments to the commands.
+@end table
+
+There is unfortunately some confusion between
+@code{cvs_options} and @code{command_options}.
+@samp{-l}, when given as a @code{cvs_option}, only
+affects some of the commands.  When it is given as a
+@code{command_option} is has a different meaning, and
+is accepted by more commands.  In other words, do not
+take the above categorization too seriously.  Look at
+the documentation instead.
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node ~/.cvsrc
+@appendixsec Default options and the ~/.cvsrc file
+@cindex .cvsrc file
+@cindex option defaults
+
+There are some @code{command_options} that are used so
+often that you might have set up an alias or some other
+means to make sure you always specify that option.  One
+example (the one that drove the implementation of the
+.cvsrc support, actually) is that many people find the
+default output of the @samp{diff} command to be very
+hard to read, and that either context diffs or unidiffs
+are much easier to understand.
+
+The @file{~/.cvsrc} file is a way that you can add
+default options to @code{cvs_commands} within cvs,
+instead of relying on aliases or other shell scripts.
+
+The format of the @file{~/.cvsrc} file is simple.  The
+file is searched for a line that begins with the same
+name as the @code{cvs_command} being executed.  If a
+match is found, then the remainder of the line is split
+up (at whitespace characters) into separate options and
+added to the command arguments @emph{before} any
+options from the command line.
+
+If a command has two names (e.g., @code{checkout} and
+@code{co}), the official name, not necessarily the one
+used on the command line, will be used to match against
+the file.  So if this is the contents of the user's
+@file{~/.cvsrc} file:
+
+@example
+log -N
+diff -u
+update -P
+co -P
+@end example
+
+@noindent
+the command @samp{cvs checkout foo} would have the
+@samp{-P} option added to the arguments, as well as
+@samp{cvs co foo}.
+
+With the example file above, the output from @samp{cvs
+diff foobar} will be in unidiff format.  @samp{cvs diff
+-c foobar} will provide context diffs, as usual.
+Getting "old" format diffs would be slightly more
+complicated, because @code{diff} doesn't have an option
+to specify use of the "old" format, so you would need
+@samp{cvs -f diff foobar}.
+
+In place of the command name you can use @code{cvs} to
+specify global options (@pxref{Global options}).  For
+example the following line in @file{.cvsrc}
+
+@example
+cvs -z6
+@end example
+
+causes @sc{cvs} to use compression level 6
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Global options
+@appendixsec Global options
+@cindex Options, global
+@cindex Global options
+@cindex Left-hand options
+
+The available @samp{cvs_options} (that are given to the
+left of @samp{cvs_command}) are:
+
+@table @code
+@cindex RCSBIN, overriding
+@cindex Overriding RCSBIN
+@item -b @var{bindir}
+Use @var{bindir} as the directory where @sc{rcs} programs are
+located.  Overrides the setting of the @code{$RCSBIN} environment
+variable and any precompiled directory.  This parameter should be
+specified as an absolute pathname.
+
+@cindex CVSROOT, overriding
+@cindex Overriding CVSROOT
+@item -d @var{cvs_root_directory}
+Use @var{cvs_root_directory} as the root directory
+pathname of the repository.  Overrides the setting of
+the @code{$CVSROOT} environment variable.  @xref{Repository}.
+
+@cindex EDITOR, overriding
+@cindex Overriding EDITOR
+@item -e @var{editor}
+Use @var{editor} to enter revision log information.  Overrides the
+setting of the @code{$CVSEDITOR} and @code{$EDITOR} environment variables.
+
+@item -f
+Do not read the @file{~/.cvsrc} file.  This
+option is most often used because of the
+non-orthogonality of the @sc{cvs} option set.  For
+example, the @samp{cvs log} option @samp{-N} (turn off
+display of tag names) does not have a corresponding
+option to turn the display on.  So if you have
+@samp{-N} in the @file{~/.cvsrc} entry for @samp{diff},
+you may need to use @samp{-f} to show the tag names.
+@footnote{Yes, this really should be fixed, and it's
+being worked on}
+
+@item -H
+Display usage information about the specified @samp{cvs_command}
+(but do not actually execute the command).  If you don't specify
+a command name, @samp{cvs -H} displays a summary of all the
+commands available.
+
+@item -l
+Do not log the cvs_command in the command history (but execute it
+anyway).  @xref{history}, for information on command history.
+
+@cindex Read-only mode
+@item -n
+Do not change any files.  Attempt to execute the
+@samp{cvs_command}, but only to issue reports; do not remove,
+update, or merge any existing files, or create any new files.
+
+@item -Q
+Cause the command to be really quiet; the command will only
+generate output for serious problems.
+
+@item -q
+Cause the command to be somewhat quiet; informational messages,
+such as reports of recursion through subdirectories, are
+suppressed.
+
+@cindex Read-only files
+@item -r
+Make new working files files read-only.  Same effect
+as if the @code{$CVSREAD} environment variable is set
+(@pxref{Environment variables}).  The default is to
+make working files writable, unless watches are on
+(@pxref{Watches}).
+
+@item -s @var{variable}=@var{value}
+Set a user variable (@pxref{Variables}).
+
+@cindex Trace
+@item -t
+Trace program execution; display messages showing the steps of
+@sc{cvs} activity.  Particularly useful with @samp{-n} to explore the
+potential impact of an unfamiliar command.
+
+@item -v
+Display version and copyright information for @sc{cvs}.
+
+@cindex CVSREAD, overriding
+@cindex Overriding CVSREAD
+@item -w
+Make new working files read-write.  Overrides the
+setting of the @code{$CVSREAD} environment variable.
+Files are created read-write by default, unless @code{$CVSREAD} is
+set or @samp{-r} is given.
+
+@item -z @var{gzip-level}
+Set the compression level.  Only has an effect on the
+@sc{cvs} client.
+
+@end table
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Common options
+@appendixsec Common command options
+@cindex Common options
+@cindex Right-hand options
+
+This section describes the @samp{command_options} that
+are available across several @sc{cvs} commands.  These
+options are always given to the right of
+@samp{cvs_command}. Not all
+commands support all of these options; each option is
+only supported for commands where it makes sense.
+However, when a command has one of these options you
+can almost always count on the same behavior of the
+option as in other commands.  (Other command options,
+which are listed with the individual commands, may have
+different behavior from one @sc{cvs} command to the other).
+
+@strong{Warning:} the @samp{history} command is an exception; it supports
+many options that conflict even with these standard options.
+
+@table @code
+@cindex Dates
+@cindex Time
+@cindex Specifying dates
+@item -D @var{date_spec}
+Use the most recent revision no later than @var{date_spec}.
+@var{date_spec} is a single argument, a date description
+specifying a date in the past.
+
+The specification is @dfn{sticky} when you use it to make a
+private copy of a source file; that is, when you get a working
+file using @samp{-D}, @sc{cvs} records the date you specified, so that
+further updates in the same directory will use the same date
+(for more information on sticky tags/dates, @pxref{Sticky tags}).
+
+A wide variety of date formats are supported by the underlying
+@sc{rcs} facilities, similar to those described in co(1), but not
+exactly the same.  The @var{date_spec} is interpreted as being
+in the local timezone, unless a specific timezone is specified.
+Examples of valid date specifications include:
+
+@example
+                    1 month ago
+                    2 hours ago
+                    400000 seconds ago
+                    last year
+                    last Monday
+                    yesterday
+                    a fortnight ago
+                    3/31/92 10:00:07 PST
+                    January 23, 1987 10:05pm
+                    22:00 GMT
+@end example
+
+@samp{-D} is available with the @code{checkout},
+@code{diff}, @code{export}, @code{history},
+@code{rdiff}, @code{rtag}, and @code{update} commands.
+(The @code{history} command uses this option in a
+slightly different way; @pxref{history options}).
+
+Remember to quote the argument to the @samp{-D}
+flag so that your shell doesn't interpret spaces as
+argument separators.  A command using the @samp{-D}
+flag can look like this:
+
+@example
+$ cvs diff -D "1 hour ago" cvs.texinfo
+@end example
+
+@cindex Forcing a tag match
+@item -f
+When you specify a particular date or tag to @sc{cvs} commands, they
+normally ignore files that do not contain the tag (or did not
+exist prior to the date) that you specified.  Use the @samp{-f} option
+if you want files retrieved even when there is no match for the
+tag or date.  (The most recent revision of the file
+will be used). 
+
+@need 800
+@samp{-f} is available with these commands: @code{checkout},
+@code{export}, @code{rdiff}, @code{rtag}, and @code{update}.
+
+@strong{Warning:}  The @code{commit} command also has a
+@samp{-f} option, but it has a different behavior for
+that command.  @xref{commit options}.
+
+@item -H
+Help; describe the options available for this command.  This is
+the only option supported for all @sc{cvs} commands.
+
+@item -k @var{kflag}
+Alter the default @sc{rcs} processing of keywords.
+@xref{Keyword substitution}, for the meaning of
+@var{kflag}.  Your @var{kflag} specification is
+@dfn{sticky} when you use it to create a private copy
+of a source file; that is, when you use this option
+with the @code{checkout} or @code{update} commands,
+@sc{cvs} associates your selected @var{kflag} with the
+file, and continues to use it with future update
+commands on the same file until you specify otherwise.
+
+The @samp{-k} option is available with the @code{add},
+@code{checkout}, @code{diff} and
+@code{update} commands.
+
+@item -l
+Local; run only in current working directory, rather than
+recursing through subdirectories.  
+
+@strong{Warning:} this is not the same
+as the overall @samp{cvs -l} option, which you can specify to the
+left of a cvs command!
+
+Available with the following commands: @code{checkout},
+@code{commit}, @code{diff}, @code{export}, @code{log},
+@code{remove}, @code{rdiff}, @code{rtag},
+@code{status}, @code{tag}, and @code{update}.
+
+@cindex Editor, avoiding invocation of
+@cindex Avoiding editor invocation
+@item -m @var{message}
+Use @var{message} as log information, instead of
+invoking an editor.
+
+Available with the following commands: @code{add},
+@code{commit} and @code{import}.
+
+@item -n
+Do not run any checkout/commit/tag program.  (A program can be
+specified to run on each of these activities, in the modules
+database (@pxref{modules}); this option bypasses it). 
+
+@strong{Warning:} this is not the same as the overall @samp{cvs -n}
+option, which you can specify to the left of a cvs command!
+
+Available with the @code{checkout}, @code{commit}, @code{export},
+and @code{rtag} commands.
+
+@item -P
+Prune (remove) directories that are empty after being updated, on
+@code{checkout}, or @code{update}.  Normally, an empty directory
+(one that is void of revision-controlled files) is left alone.
+Specifying @samp{-P} will cause these directories to be silently
+removed from your checked-out sources.  This does not remove the
+directory from the repository, only from your checked out copy.
+Note that this option is implied by the @samp{-r} or @samp{-D}
+options of @code{checkout} and @code{export}.
+@c -- implied--
+
+@item -p
+Pipe the files retrieved from the repository to standard output,
+rather than writing them in the current directory.  Available
+with the @code{checkout} and @code{update} commands.
+
+@item -W
+Specify file names that should be filtered.  You can
+use this option repeatedly.  The spec can be a file
+name pattern of the same type that you can specify in
+the @file{.cvswrappers} file.
+Avaliable with the following commands: @code{import},
+and @code{update}.
+
+@item -r @var{tag}
+Use the revision specified by the @var{tag} argument instead of the
+default @dfn{head} revision.  As well as arbitrary tags defined
+with the @code{tag} or @code{rtag} command, two special tags are
+always available: @samp{HEAD} refers to the most recent version
+available in the repository, and @samp{BASE} refers to the
+revision you last checked out into the current working directory.
+
+The tag specification is sticky when you use this option
+with @code{checkout} or @code{update} to make your own
+copy of a file: @sc{cvs} remembers the tag and continues to use it on
+future update commands, until you specify otherwise (for more information
+on sticky tags/dates, @pxref{Sticky tags}).  The
+tag can be either a symbolic or numeric tag.
+@xref{Tags}.
+
+Specifying the @samp{-q} global option along with the
+@samp{-r} command option is often useful, to suppress
+the warning messages when the @sc{rcs} history file
+does not contain the specified tag.
+
+@strong{Warning:} this is not the same as the overall `cvs -r' option,
+which you can specify to the left of a cvs command!
+
+@samp{-r} is available with the @code{checkout}, @code{commit},
+@code{diff}, @code{history}, @code{export}, @code{rdiff},
+@code{rtag}, and @code{update} commands.
+
+@end table
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node add
+@appendixsec add---Add a new file/directory to the repository
+@cindex Add (subcommand)
+
+@itemize @bullet
+@item
+Synopsis: add [-k kflag] [-m 'message'] files@dots{}
+@item
+Requires: repository, working directory.
+@item
+Changes: working directory.
+@item
+Synonym: new
+@end itemize
+
+Use the @code{add} command to create a new file or directory in the 
+source repository.  The files or directories specified with @code{add}
+must already exist in the current directory (which must have been
+created with the @code{checkout} command).  To add a whole new directory
+hierarchy to the source repository (for example, files received
+from a third-party vendor), use the @code{import} command
+instead.  @xref{import}.
+
+If the argument to @code{add} refers to an immediate
+sub-directory, the directory is created at the correct place in
+the source repository, and the necessary @sc{cvs} administration
+files are created in your working directory.  If the directory
+already exists in the source repository, @code{add} still creates
+the administration files in your version of the directory.
+This allows you to use @code{add} to add a particular directory
+to your private sources even if someone else created that
+directory after your checkout of the sources.  You can do the
+following:
+
+@example
+$ mkdir new_directory
+$ cvs add new_directory
+$ cvs update new_directory
+@end example
+
+An alternate approach using @code{update} might be:
+
+@example
+$ cvs update -d new_directory
+@end example
+
+(To add any available new directories to your working directory,
+it's probably simpler to use @code{checkout} (@pxref{checkout})
+or @samp{update -d} (@pxref{update})).
+
+The added files are not placed in the source repository until you
+use @code{commit} to make the change permanent.  Doing an
+@code{add} on a file that was removed with the @code{remove}
+command will resurrect the file, unless a @code{commit} command
+intervened.
+@xref{Removing files}, for an example.
+
+
+Unlike most other commands @code{add} never recurses down
+directories.  It cannot yet handle relative paths.  Instead of
+
+@example
+$ cvs add foo/bar.c
+@end example
+
+you have to do
+
+@example
+$ cd foo
+$ cvs add bar.c
+@end example
+
+@menu
+* add options::                 add options
+* add examples::                add examples
+@end menu
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node add options
+@appendixsubsec add options
+@cindex Add options
+
+There are only two options you can give to @samp{add}:
+
+@table @code
+@item -k @var{kflag}
+This option specifies the default way that this file
+will be checked out.  The @var{kflag} argument
+(@pxref{Substitution modes}) is stored in the @sc{rcs}
+file and can be changed with @code{admin -k}
+(@pxref{admin options}).  See @ref{Binary files}, for
+information on using this option for binary files.
+
+@item -m @var{description}
+Using this option, you can give a description for the file.  This
+description appears in the history log (if it is enabled,
+@pxref{history file}).  It will also be saved in the @sc{rcs} history
+file inside the repository when the file is committed.  The
+@code{log} command displays this description.
+
+The description can be changed using @samp{admin -t}.
+@xref{admin}.
+
+If you omit the @samp{-m @var{description}} flag, an empty string will be
+used.  You will not be prompted for a description.
+@end table
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node add examples
+@appendixsubsec add examples
+
+To add the file @file{backend.c} to the repository, with a
+description, the following can be used.
+
+@example
+$ cvs add -m "Optimizer and code generation passes." backend.c
+$ cvs commit -m "Early version. Not yet compilable." backend.c
+@end example
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node admin
+@appendixsec admin---Administration front end for rcs
+@cindex Admin (subcommand)
+
+@itemize @bullet
+@item
+Requires: repository, working directory.
+@item
+Changes: repository.
+@item
+Synonym: rcs
+@end itemize
+
+This is the @sc{cvs} interface to assorted administrative @sc{rcs}
+facilities, documented in rcs(1).  @code{admin} simply passes
+all its options and arguments to the @code{rcs} command; it does
+no filtering or other processing.  This command @emph{does} work
+recursively, however, so extreme care should be used.
+
+If there is a group whose name matches a compiled in
+value which defaults to @code{cvsadmin}, only members
+of that group can use @code{cvs admin}.  To disallow
+@code{cvs admin} for all users, create a group with no
+users in it.
+
+@menu
+* admin options::               admin options
+* admin examples::              admin examples
+@end menu
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node admin options
+@appendixsubsec admin options
+
+Not all valid @code{rcs} options are useful together
+with @sc{cvs}.  Some even makes it impossible to use
+@sc{cvs} until you undo the effect!
+
+This description of the available options is based on
+the @samp{rcs(1)} man page, but modified to suit
+readers that are more interrested in @sc{cvs} than
+@sc{rcs}.
+
+@table @code
+@item -A@var{oldfile}
+Might not work together with @sc{cvs}.  Append the
+access list of @var{oldfile} to the access list of the
+@sc{rcs} file.
+
+@item -a@var{logins}
+Might not work together with @sc{cvs}.  Append the
+login names appearing in the comma-separated list
+@var{logins} to the access list of the @sc{rcs} file.
+
+@item -b[@var{rev}]
+When used with bare @sc{rcs}, this
+option sets the default branch to @var{rev}; in
+@sc{cvs} sticky tags (@pxref{Sticky tags}) are a better
+way to decide which branch you want to work on.  With
+@sc{cvs}, this option can be used to control behavior
+with respect to the vendor branch.
+@c FIXME: document how you use it with the vendor
+@c branch (or fix cvs so that there is a more graceful
+@c way to handle the case).
+
+@item -c@var{string}
+Useful with @sc{cvs}.  Sets the comment leader to
+@var{string}.  The comment leader is printed before
+every log message line generated by the keyword
+@code{$@asis{}Log$} (@pxref{Keyword substitution}).
+This is useful for programming languages without
+multi-line comments.  @sc{Rcs} initially guesses the
+value of the comment leader from the file name
+extension when the file is first committed.
+
+@item -e[@var{logins}]
+Might not work together with @sc{cvs}.  Erase the login
+names appearing in the comma-separated list
+@var{logins} from the access list of the RCS file.  If
+@var{logins} is omitted, erase the entire access list.
+
+@item -I
+Run interactively, even if the standard input is not a
+terminal.
+
+@item -i
+Useless with @sc{cvs}.  When using bare @sc{rcs}, this
+is used to create and initialize a new @sc{rcs} file,
+without depositing a revision.
+
+@item -k@var{subst}
+Useful with @sc{cvs}.  Set the default keyword
+substitution to @var{subst}.  @xref{Keyword
+substitution}.  Giving an explicit @samp{-k} option to
+@code{cvs update}, @code{cvs export}, or @code{cvs
+checkout} overrides this default.
+
+@cindex Reserved checkouts
+@cindex RCS-style locking
+@item -l[@var{rev}]
+Lock the revision with number @var{rev}.  If a branch
+is given, lock the latest revision on that branch.  If
+@var{rev} is omitted, lock the latest revision on the
+default branch.
+
+This can be used in conjunction with the
+@file{rcslock.pl} script in the @file{contrib}
+directory of the @sc{cvs} source distribution to
+provide reserved checkouts (where only one user can be
+editing a given file at a time).  See the comments in
+that file for details (and see the @file{README} file
+in that directory for disclaimers about the unsupported
+nature of contrib).  According to comments in that
+file, locking must set to strict (which is the default).
+
+@item -L
+Set locking to strict.  Strict locking means that the
+owner of an RCS file is not exempt from locking for
+checkin.  For use with @sc{cvs}, strict locking must be
+set; see the discussion under the @samp{-l} option above.
+
+@cindex Changing a log message
+@cindex Replacing a log message
+@cindex Correcting a log message
+@cindex Fixing a log message
+@cindex Log message, correcting
+@item -m@var{rev}:@var{msg}
+Replace the log message of revision @var{rev} with
+@var{msg}.
+
+@item -N@var{name}[:[@var{rev}]]
+Act like @samp{-n}, except override any previous
+assignment of @var{name}.
+
+@item -n@var{name}[:[@var{rev}]]
+Associate the symbolic name @var{name} with the branch
+or revision @var{rev}.  It is normally better to use
+@samp{cvs tag} or @samp{cvs rtag} instead.  Delete the
+symbolic name if both @samp{:} and @var{rev} are
+omitted; otherwise, print an error message if
+@var{name} is already associated with another number.
+If @var{rev} is symbolic, it is expanded before
+association.  A @var{rev} consisting of a branch number
+followed by a @samp{.} stands for the current latest
+revision in the branch.  A @samp{:} with an empty
+@var{rev} stands for the current latest revision on the
+default branch, normally the trunk.  For example,
+@samp{rcs -n@var{name}: RCS/*} associates @var{name} with the
+current latest revision of all the named RCS files;
+this contrasts with @samp{rcs -n@var{name}:$ RCS/*} which
+associates @var{name} with the revision numbers
+extracted from keyword strings in the corresponding
+working files.
+
+@cindex Deleting revisions
+@cindex Outdating revisions
+@cindex Saving space
+@item -o@var{range}
+Potentially useful, but dangerous, with @sc{cvs} (see below).
+Deletes (@dfn{outdates}) the revisions given by
+@var{range}.  A range consisting of a single revision
+number means that revision.  A range consisting of a
+branch number means the latest revision on that branch.
+A range of the form @samp{@var{rev1}:@var{rev2}} means
+revisions @var{rev1} to @var{rev2} on the same branch,
+@samp{:@var{rev}} means from the beginning of the
+branch containing @var{rev} up to and including
+@var{rev}, and @samp{@var{rev}:} means from revision
+@var{rev} to the end of the branch containing
+@var{rev}.  None of the outdated revisions may have
+branches or locks.
+
+Due to the way @sc{cvs} handles branches @var{rev}
+cannot be specified symbolically if it is a branch.
+@xref{Magic branch numbers}, for an explanation.
+
+Make sure that no-one has checked out a copy of the
+revision you outdate.  Strange things will happen if he
+starts to edit it and tries to check it back in.  For
+this reason, this option is not a good way to take back
+a bogus commit; commit a new revision undoing the bogus
+change instead (@pxref{Merging two revisions}).
+
+@item -q
+Run quietly; do not print diagnostics.
+
+@item -s@var{state}[:@var{rev}]
+Useful with @sc{cvs}.  Set the state attribute of the
+revision @var{rev} to @var{state}.  If @var{rev} is a
+branch number, assume the latest revision on that
+branch.  If @var{rev} is omitted, assume the latest
+revision on the default branch.  Any identifier is
+acceptable for @var{state}.  A useful set of states is
+@samp{Exp} (for experimental), @samp{Stab} (for
+stable), and @samp{Rel} (for released).  By default,
+the state of a new revision is set to @samp{Exp} when
+it is created.  The state is visible in the output from
+@var{cvs log} (@pxref{log}), and in the
+@samp{$@asis{}Log$} and @samp{$@asis{}State$} keywords
+(@pxref{Keyword substitution}).  Note that @sc{cvs}
+uses the @code{dead} state for its own purposes; to
+take a file to or from the @code{dead} state use
+commands like @code{cvs remove} and @code{cvs add}, not
+@code{cvs admin -s}.
+
+@item -t[@var{file}]
+Useful with @sc{cvs}.  Write descriptive text from the
+contents of the named @var{file} into the RCS file,
+deleting the existing text.  The @var{file} pathname
+may not begin with @samp{-}.  If @var{file} is omitted,
+obtain the text from standard input, terminated by
+end-of-file or by a line containing @samp{.} by itself.
+Prompt for the text if interaction is possible; see
+@samp{-I}.  The descriptive text can be seen in the
+output from @samp{cvs log} (@pxref{log}).
+
+@item -t-@var{string}
+Similar to @samp{-t@var{file}}. Write descriptive text
+from the @var{string} into the @sc{rcs} file, deleting
+the existing text.
+
+@item -U
+Set locking to non-strict.  Non-strict locking means
+that the owner of a file need not lock a revision for
+checkin.  For use with @sc{cvs}, strict locking must be
+set; see the discussion under the @samp{-l} option
+above.
+
+@item -u[@var{rev}]
+See the option @samp{-l} above, for a discussion of
+using this option with @sc{cvs}.  Unlock the revision
+with number @var{rev}.  If a branch is given, unlock
+the latest revision on that branch.  If @var{rev} is
+omitted, remove the latest lock held by the caller.
+Normally, only the locker of a revision may unlock it.
+Somebody else unlocking a revision breaks the lock.
+This causes a mail message to be sent to the original
+locker.  The message contains a commentary solicited
+from the breaker.  The commentary is terminated by
+end-of-file or by a line containing @code{.} by itself.
+
+@item -V@var{n}
+Emulate @sc{rcs} version @var{n}. Use -V@var{n} to make
+an @sc{rcs} file acceptable to @sc{rcs} version @var{n}
+by discarding information that would confuse version
+@var{n}.
+
+@item -x@var{suffixes}
+Useless with @sc{cvs}. Use @var{suffixes} to
+characterize RCS files.
+@end table
+
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node admin examples
+@appendixsubsec admin examples
+
+@appendixsubsubsec Outdating is dangerous
+
+First, an example of how @emph{not} to use the
+@code{admin} command.  It is included to stress the
+fact that this command can be quite dangerous unless
+you know @emph{exactly} what you are doing.
+
+The @samp{-o} option can be used to @dfn{outdate} old revisions
+from the history file.  If you are short on disc this option
+might help you.  But think twice before using it---there is no
+way short of restoring the latest backup to undo this command!
+
+The next line is an example of a command that you would
+@emph{not} like to execute.
+
+@example
+$ cvs admin -o:R_1_02 .
+@end example
+
+The above command will delete all revisions up to, and
+including, the revision that corresponds to the tag
+R_1_02.  But beware!  If there are files that have not
+changed between R_1_02 and R_1_03 the file will have
+@emph{the same} numerical revision number assigned to
+the tags R_1_02 and R_1_03.  So not only will it be
+impossible to retrieve R_1_02; R_1_03 will also have to
+be restored from the tapes!
+
+@appendixsubsubsec Comment leaders
+@cindex Comment leader
+@cindex Log keyword, selecting comment leader
+@cindex Nroff (selecting comment leader)
+
+If you use the @code{$@asis{}Log$} keyword and you do
+not agree with the guess for comment leader that
+@sc{cvs} has done, you can enforce your will with
+@code{cvs admin -c}.  This might be suitable for
+@code{nroff} source:
+
+@example
+$ cvs admin -c'.\" ' *.man
+$ rm *.man
+$ cvs update
+@end example
+
+The two last steps are to make sure that you get the
+versions with correct comment leaders in your working
+files.
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node checkout
+@appendixsec checkout---Check out sources for editing
+@cindex Checkout (subcommand)
+@cindex Co (subcommand)
+
+@itemize @bullet
+@item
+Synopsis: checkout [options] modules@dots{}
+@item
+Requires: repository.
+@item
+Changes: working directory.
+@item
+Synonyms: co, get
+@end itemize
+
+Make a working directory containing copies of the
+source files specified by @var{modules}.  You must execute
+@code{checkout} before using most of the other @sc{cvs}
+commands, since most of them operate on your working
+directory.
+
+The @var{modules} part of the command are either
+symbolic names for some
+collection of source directories and files, or paths to
+directories or files in the repository.  The symbolic
+names are defined in the @samp{modules} file.
+@xref{modules}.
+
+Depending on the modules you specify, @code{checkout} may
+recursively create directories and populate them with
+the appropriate source files.  You can then edit these
+source files at any time (regardless of whether other
+software developers are editing their own copies of the
+sources); update them to include new changes applied by
+others to the source repository; or commit your work as
+a permanent change to the source repository.
+
+Note that @code{checkout} is used to create
+directories.  The top-level directory created is always
+added to the directory where @code{checkout} is
+invoked, and usually has the same name as the specified
+module.  In the case of a module alias, the created
+sub-directory may have a different name, but you can be
+sure that it will be a sub-directory, and that
+@code{checkout} will show the relative path leading to
+each file as it is extracted into your private work
+area (unless you specify the @samp{-Q} global option).
+
+The files created by @code{checkout} are created
+read-write, unless the @samp{-r} option to @sc{cvs}
+(@pxref{Global options}) is specified, the
+@code{CVSREAD} environment variable is specified
+(@pxref{Environment variables}), or a watch is in
+effect for that file (@pxref{Watches}).
+
+@c FIXME: misleading--checkout takes a module as
+@c argument, and update does not--so -d behavior is not the only
+@c difference.
+Running @code{checkout} on a directory that was already
+built by a prior @code{checkout} is also permitted, and
+has the same effect as specifying the @samp{-d} option
+to the @code{update} command, that is, any new
+directories that have been created in the repository
+will appear in your work area.  @xref{update}.
+
+@menu
+* checkout options::            checkout options
+* checkout examples::           checkout examples
+@end menu
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node checkout options
+@appendixsubsec checkout options
+
+These standard options are supported by @code{checkout}
+(@pxref{Common options}, for a complete description of
+them):
+
+@table @code
+@item -D @var{date}
+Use the most recent revision no later than @var{date}.
+This option is sticky, and implies @samp{-P}.  See
+@ref{Sticky tags}, for more information on sticky tags/dates.
+
+@item -f
+Only useful with the @samp{-D @var{date}} or @samp{-r
+@var{tag}} flags.  If no matching revision is found,
+retrieve the most recent revision (instead of ignoring
+the file).
+
+@item -k @var{kflag}
+Process @sc{rcs} keywords according to @var{kflag}.  See
+co(1).  This option is sticky; future updates of
+this file in this working directory will use the same
+@var{kflag}.  The @code{status} command can be viewed
+to see the sticky options.  @xref{status}.
+
+@item -l
+Local; run only in current working directory.
+
+@item -n
+Do not run any checkout program (as specified
+with the @samp{-o} option in the modules file;
+@pxref{modules}).
+
+@item -P
+Prune empty directories.
+
+@item -p
+Pipe files to the standard output.
+
+@item -r @var{tag}
+Use revision @var{tag}.  This option is sticky, and implies @samp{-P}.
+See @ref{Sticky tags}, for more information on sticky tags/dates.
+@end table
+
+In addition to those, you can use these special command
+options with @code{checkout}:
+
+@table @code
+@item -A
+Reset any sticky tags, dates, or @samp{-k} options.
+See @ref{Sticky tags}, for more information on sticky tags/dates.
+
+@item -c
+Copy the module file, sorted, to the standard output,
+instead of creating or modifying any files or
+directories in your working directory.
+
+@item -d @var{dir}
+Create a directory called @var{dir} for the working
+files, instead of using the module name.  Unless you
+also use @samp{-N}, the paths created under @var{dir}
+will be as short as possible.
+
+@item -j @var{tag}
+With two @samp{-j} options, merge changes from the
+revision specified with the first @samp{-j} option to
+the revision specified with the second @samp{j} option,
+into the working directory.
+
+With one @samp{-j} option, merge changes from the
+ancestor revision to the revision specified with the
+@samp{-j} option, into the working directory.  The
+ancestor revision is the common ancestor of the
+revision which the working directory is based on, and
+the revision specified in the @samp{-j} option.
+
+In addition, each -j option can contain an optional
+date specification which, when used with branches, can
+limit the chosen revision to one within a specific
+date.  An optional date is specified by adding a colon
+(:) to the tag:
+@samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}.
+
+@xref{Merging}.
+
+@item -N
+Only useful together with @samp{-d @var{dir}}.  With this
+option, @sc{cvs} will not shorten module paths in your
+working directory.  (Normally, @sc{cvs} shortens paths as
+much as possible when you specify an explicit target
+directory).
+
+@item -s
+Like @samp{-c}, but include the status of all modules,
+and sort it by the status string.  @xref{modules}, for
+info about the @samp{-s} option that is used inside the
+modules file to set the module status.
+@end table
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node checkout examples
+@appendixsubsec checkout examples
+
+Get a copy of the module @samp{tc}:
+
+@example
+$ cvs checkout tc
+@end example
+
+Get a copy of the module @samp{tc} as it looked one day
+ago:
+
+@example
+$ cvs checkout -D yesterday tc
+@end example
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node commit
+@appendixsec commit---Check files into the repository
+@cindex Commit (subcommand)
+
+@itemize @bullet
+@item
+Version 1.3 Synopsis: commit [-lnR] [-m 'log_message' |
+-f file] [-r revision] [files@dots{}]
+@item
+Version 1.3.1 Synopsis: commit [-lnRf] [-m 'log_message' |
+-F file] [-r revision] [files@dots{}]
+@c -- rename-f-F--
+@item
+Requires: working directory, repository.
+@item
+Changes: repository.
+@item
+Synonym: ci
+@end itemize
+
+@strong{Warning:} The @samp{-f @var{file}} option will
+probably be renamed to @samp{-F @var{file}}, and @samp{-f}
+will be given a new behavior in future releases of @sc{cvs}.
+@c -- rename-f-F--
+
+Use @code{commit} when you want to incorporate changes
+from your working source files into the source
+repository.
+
+If you don't specify particular files to commit, all of
+the files in your working current directory are
+examined.  @code{commit} is careful to change in the
+repository only those files that you have really
+changed.  By default (or if you explicitly specify the
+@samp{-R} option), files in subdirectories are also
+examined and committed if they have changed; you can
+use the @samp{-l} option to limit @code{commit} to the
+current directory only.
+
+@code{commit} verifies that the selected files are up
+to date with the current revisions in the source
+repository; it will notify you, and exit without
+committing, if any of the specified files must be made
+current first with @code{update} (@pxref{update}).
+@code{commit} does not call the @code{update} command
+for you, but rather leaves that for you to do when the
+time is right.
+
+When all is well, an editor is invoked to allow you to
+enter a log message that will be written to one or more
+logging programs (@pxref{modules}, and @pxref{loginfo})
+and placed in the @sc{rcs} history file inside the
+repository.  This log message can be retrieved with the
+@code{log} command; @xref{log}.  You can specify the
+log message on the command line with the @samp{-m
+@var{message}} option, and thus avoid the editor invocation,
+or use the @samp{-f @var{file}} option to specify
+@c -- rename-f-F--
+that the argument file contains the log message.
+
+@menu
+* commit options::              commit options
+* commit examples::             commit examples
+@end menu
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node commit options
+@appendixsubsec commit options
+
+These standard options are supported by @code{commit}
+(@pxref{Common options}, for a complete description of
+them):
+
+@table @code
+@item -l
+Local; run only in current working directory.
+
+@item -n
+Do not run any module program.
+
+@item -R
+Commit directories recursively.  This is on by default.
+
+@item -r @var{revision}
+Commit to @var{revision}.  @var{revision} must be
+either a branch, or a revision on the main trunk that
+is higher than any existing revision number.  You
+cannot commit to a specific revision on a branch.
+@end table
+
+@code{commit} also supports these options:
+
+@table @code
+@item -F @var{file}
+This option is present in @sc{cvs} releases 1.3-s3 and
+later.  Read the log message from @var{file}, instead
+of invoking an editor.
+
+@item -f
+@c -- rename-f-F--
+This option is present in @sc{cvs} 1.3-s3 and later releases
+of @sc{cvs}.  Note that this is not the standard behavior of
+the @samp{-f} option as defined in @xref{Common options}.
+
+Force @sc{cvs} to commit a new revision even if you haven't
+made any changes to the file.  If the current revision
+of @var{file} is 1.7, then the following two commands
+are equivalent:
+
+@example
+$ cvs commit -f @var{file}
+$ cvs commit -r 1.8 @var{file}
+@end example
+
+@item -f @var{file}
+@c -- rename-f-F--
+This option is present in @sc{cvs} releases 1.3, 1.3-s1 and
+1.3-s2.  Note that this is not the standard behavior of
+the @samp{-f} option as defined in @xref{Common options}.
+
+Read the log message from @var{file}, instead
+of invoking an editor.
+
+@item -m @var{message}
+Use @var{message} as the log message, instead of
+invoking an editor.
+@end table
+
+@need 2000
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node commit examples
+@appendixsubsec commit examples
+
+@appendixsubsubsec New major release number
+
+When you make a major release of your product, you
+might want the revision numbers to track your major
+release number.  You should normally not care about
+the revision numbers, but this is a thing that many
+people want to do, and it can be done without doing any
+harm.
+
+To bring all your files up to the @sc{rcs} revision 3.0
+(including those that haven't changed), you might do:
+
+@example
+$ cvs commit -r 3.0
+@end example
+
+Note that it is generally a bad idea to try to make the
+@sc{rcs} revision number equal to the current release number
+of your product.  You should think of the revision
+number as an internal number that the @sc{cvs} package
+maintains, and that you generally never need to care
+much about.  Using the @code{tag} and @code{rtag}
+commands you can give symbolic names to the releases
+instead.  @xref{tag} and @xref{rtag}.
+
+Note that the number you specify with @samp{-r} must be
+larger than any existing revision number.  That is, if
+revision 3.0 exists, you cannot @samp{cvs commit
+-r 1.3}.
+
+@appendixsubsubsec Committing to a branch
+
+You can commit to a branch revision (one that has an
+even number of dots) with the @samp{-r} option.  To
+create a branch revision, use the @samp{-b} option
+of the @code{rtag} or @code{tag} commands (@pxref{tag}
+or @pxref{rtag}).  Then, either @code{checkout} or
+@code{update} can be used to base your sources on the
+newly created branch.  From that point on, all
+@code{commit} changes made within these working sources
+will be automatically added to a branch revision,
+thereby not disturbing main-line development in any
+way.  For example, if you had to create a patch to the
+1.2 version of the product, even though the 2.0 version
+is already under development, you might do:
+
+@example
+$ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module
+$ cvs checkout -r FCS1_2_Patch product_module
+$ cd product_module
+[[ hack away ]]
+$ cvs commit
+@end example
+
+@noindent
+This works automatically since the @samp{-r} option is
+sticky.
+
+@appendixsubsubsec Creating the branch after editing
+
+Say you have been working on some extremely
+experimental software, based on whatever revision you
+happened to checkout last week.  If others in your
+group would like to work on this software with you, but
+without disturbing main-line development, you could
+commit your change to a new branch.  Others can then
+checkout your experimental stuff and utilize the full
+benefit of @sc{cvs} conflict resolution.  The scenario might
+look like:
+
+@c FIXME: Should we be recommending tagging the branchpoint?
+@example
+[[ hacked sources are present ]]
+$ cvs tag -b EXPR1
+$ cvs update -r EXPR1
+$ cvs commit
+@end example
+
+The @code{update} command will make the @samp{-r
+EXPR1} option sticky on all files.  Note that your
+changes to the files will never be removed by the
+@code{update} command.  The @code{commit} will
+automatically commit to the correct branch, because the
+@samp{-r} is sticky.  You could also do like this:
+
+@c FIXME: Should we be recommending tagging the branchpoint?
+@example
+[[ hacked sources are present ]]
+$ cvs tag -b EXPR1
+$ cvs commit -r EXPR1
+@end example
+
+@noindent
+but then, only those files that were changed by you
+will have the @samp{-r EXPR1} sticky flag.  If you hack
+away, and commit without specifying the @samp{-r EXPR1}
+flag, some files may accidentally end up on the main
+trunk.
+
+To work with you on the experimental change, others
+would simply do
+
+@example
+$ cvs checkout -r EXPR1 whatever_module
+@end example
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node diff
+@appendixsec diff---Run diffs between revisions
+@cindex Diff (subcommand)
+
+@itemize @bullet
+@item
+Synopsis: diff [-l] [rcsdiff_options] [[-r rev1 | -D date1] [-r rev2 |  -D date2]] [files@dots{}]
+@item
+Requires: working directory, repository.
+@item
+Changes: nothing.
+@end itemize
+
+The @code{diff} command is used to compare different
+revisions of files.  The default action is to compare
+your working files with the revisions they were based
+on, and report any differences that are found.
+
+If any file names are given, only those files are
+compared.  If any directories are given, all files
+under them will be compared.
+
+The exit status will be 0 if no differences were found,
+1 if some differences were found, and 2 if any error
+occurred.
+
+@menu
+* diff options::                diff options
+* diff examples::               diff examples
+@end menu
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node diff options
+@appendixsubsec diff options
+
+These standard options are supported by @code{diff}
+(@pxref{Common options}, for a complete description of
+them):
+
+@table @code
+@item -D @var{date}
+Use the most recent revision no later than @var{date}.
+See @samp{-r} for how this affects the comparison.
+
+@sc{cvs} can be configured to pass the @samp{-D} option
+through to @code{rcsdiff} (which in turn passes it on
+to @code{diff}.  @sc{Gnu} diff uses @samp{-D} as a way to
+put @code{cpp}-style @samp{#define} statements around the output
+differences.  There is no way short of testing to
+figure out how @sc{cvs} was configured.  In the default
+configuration @sc{cvs} will use the @samp{-D @var{date}} option.
+
+@item -k @var{kflag}
+Process @sc{rcs} keywords according to @var{kflag}.  See
+co(1).
+
+@item -l
+Local; run only in current working directory.
+
+@item -R
+Examine directories recursively.  This option is on by
+default.
+
+@item -r @var{tag}
+Compare with revision @var{tag}.  Zero, one or two
+@samp{-r} options can be present.  With no @samp{-r}
+option, the working file will be compared with the
+revision it was based on.  With one @samp{-r}, that
+revision will be compared to your current working file.
+With two @samp{-r} options those two revisions will be
+compared (and your working file will not affect the
+outcome in any way).
+
+One or both @samp{-r} options can be replaced by a
+@samp{-D @var{date}} option, described above.
+@end table
+
+Any other options that are found are passed through to
+@code{rcsdiff}, which in turn passes them to
+@code{diff}.  The exact meaning of the options depends
+on which @code{diff} you are using.  The long options
+introduced in @sc{gnu} diff 2.0 are not yet supported in
+@sc{cvs}.  See the documentation for your @code{diff} to see
+which options are supported.
+
+@c -- Document some common useful diff options, such as
+@c -u and -c.
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node diff examples
+@appendixsubsec diff examples
+
+The following line produces a Unidiff (@samp{-u} flag)
+between revision 1.14 and 1.19 of
+@file{backend.c}.  Due to the @samp{-kk} flag no
+keywords are substituted, so differences that only depend
+on keyword substitution are ignored.
+
+@example
+$ cvs diff -kk -u -r 1.14 -r 1.19 backend.c
+@end example
+
+Suppose the experimental branch EXPR1 was based on a
+set of files tagged RELEASE_1_0.  To see what has
+happened on that branch, the following can be used:
+
+@example
+$ cvs diff -r RELEASE_1_0 -r EXPR1
+@end example
+
+A command like this can be used to produce a context
+diff between two releases:
+
+@example
+$ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs
+@end example
+
+If you are maintaining ChangeLogs, a command like the following
+just before you commit your changes may help you write
+the ChangeLog entry.  All local modifications that have
+not yet been committed will be printed.
+
+@example
+$ cvs diff -u | less
+@end example
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node export
+@appendixsec export---Export sources from CVS, similar to checkout
+@cindex Export (subcommand)
+
+@itemize @bullet
+@item
+Synopsis: export [-flNn] [-r rev|-D date] [-k subst] [-d dir] module@dots{}
+@item
+Requires: repository.
+@item
+Changes: current directory.
+@end itemize
+
+This command is a variant of @code{checkout}; use it
+when you want a copy of the source for module without
+the @sc{cvs} administrative directories.  For example, you
+might use @code{export} to prepare source for shipment
+off-site.  This command requires that you specify a
+date or tag (with @samp{-D} or @samp{-r}), so that you
+can count on reproducing the source you ship to others.
+
+One often would like to use @samp{-kv} with @code{cvs
+export}.  This causes any @sc{rcs} keywords to be
+expanded such that an import done at some other site
+will not lose the keyword revision information.  But be
+aware that doesn't handle an export containing binary
+files correctly.  Also be aware that after having used
+@samp{-kv}, one can no longer use the @code{ident}
+command (which is part of the @sc{rcs} suite---see
+ident(1)) which looks for @sc{rcs} keyword strings.  If
+you want to be able to use @code{ident} you must not
+use @samp{-kv}.
+
+@menu
+* export options::              export options
+@end menu
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node export options
+@appendixsubsec export options
+
+These standard options are supported by @code{export}
+(@pxref{Common options}, for a complete description of
+them):
+
+@table @code
+@item -D @var{date}
+Use the most recent revision no later than @var{date}.
+
+@item -f
+If no matching revision is found, retrieve the most
+recent revision (instead of ignoring the file).
+
+@item -l
+Local; run only in current working directory.
+
+@item -n
+Do not run any checkout program.
+
+@item -R
+Export directories recursively.  This is on by default.
+
+@item -r @var{tag}
+Use revision @var{tag}.
+@end table
+
+In addition, these options (that are common to
+@code{checkout} and @code{export}) are also supported:
+
+@table @code
+@item -d @var{dir}
+Create a directory called @var{dir} for the working
+files, instead of using the module name.  Unless you
+also use @samp{-N}, the paths created under @var{dir}
+will be as short as possible.
+
+@item -k @var{subst}
+Set keyword expansion mode (@pxref{Substitution modes}).
+
+@item -N
+Only useful together with @samp{-d @var{dir}}.  With this
+option, @sc{cvs} will not shorten module paths in your
+working directory.  (Normally, @sc{cvs} shortens paths as
+much as possible when you specify an explicit target
+directory.)
+@end table
+
+@ignore
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@c @node export examples
+@appendixsubsec export examples
+
+Contributed examples are gratefully accepted.
+@c -- Examples here!!
+@end ignore
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node history
+@appendixsec history---Show status of files and users
+@cindex History (subcommand)
+
+@itemize @bullet
+@item
+Synopsis:     history [-report] [-flags] [-options args] [files@dots{}]
+@item
+Requires: the file @file{$CVSROOT/CVSROOT/history}
+@item
+Changes: nothing.
+@end itemize
+
+@sc{cvs} can keep a history file that tracks each use of the
+@code{checkout}, @code{commit}, @code{rtag},
+@code{update}, and @code{release} commands.  You can
+use @code{history} to display this information in
+various formats.
+
+Logging must be enabled by creating the file
+@file{$CVSROOT/CVSROOT/history}.
+
+@strong{Warning:} @code{history} uses @samp{-f}, @samp{-l},
+@samp{-n}, and @samp{-p} in ways that conflict with the
+normal use inside @sc{cvs} (@pxref{Common options}).
+
+@menu
+* history options::             history options
+@end menu
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node history options
+@appendixsubsec history options
+
+Several options (shown above as @samp{-report})  control  what
+kind of report is generated:
+
+@table @code
+@item -c
+Report on each time commit was used (i.e., each time
+the repository was modified).
+
+@item -e 
+Everything (all record types); equivalent to specifying
+@samp{-xMACFROGWUT}.
+
+@item -m @var{module}
+Report on a particular module.  (You can meaningfully
+use @samp{-m} more than once on the command line.)
+
+@item -o
+Report on checked-out modules.
+
+@item -T
+Report on all tags.
+
+@item -x @var{type}
+Extract a particular set of record types @var{type} from the @sc{cvs}
+history.  The types are indicated by single letters,
+which you may specify in combination.  
+
+Certain commands have a single record type: 
+
+@table @code
+@item F
+release
+@item O
+checkout
+@item T
+rtag
+@end table
+
+@noindent
+One of four record types may result from an update:
+
+@table @code
+@item C
+A merge was necessary but collisions were
+detected (requiring manual merging).  
+@item G
+A merge was necessary and it succeeded.
+@item U
+A working file was copied from the repository.
+@item W
+The working copy of a file was deleted during
+update (because it was gone from the repository).
+@end table
+
+@noindent
+One of three record types results from commit:
+
+@table @code
+@item A
+A file was added for the first time.
+@item M
+A file was modified.
+@item R
+A file was removed.
+@end table
+@end table
+
+The options shown as @samp{-flags} constrain or expand
+the report without requiring option arguments:
+
+@table @code
+@item -a
+Show data for all users (the default is to show data
+only for the user executing @code{history}).
+
+@item -l
+Show last modification only.
+
+@item -w
+Show only the records for modifications done from the
+same working directory where @code{history} is
+executing.
+@end table
+
+The options shown as @samp{-options @var{args}} constrain the report
+based on an argument:
+
+@table @code
+@item -b @var{str}
+Show data back to a record containing  the  string
+@var{str}  in  either the module name, the file name, or
+the repository path.
+
+@item -D @var{date}
+Show data since @var{date}.  This is slightly different
+from the normal use of @samp{-D @var{date}}, which
+selects the newest revision older than @var{date}.
+
+@item -p @var{repository}
+Show data for a particular source repository  (you
+can specify several @samp{-p} options on the same command
+line).
+
+@item -r @var{rev}
+Show records referring to revisions since the revision
+or tag named @var{rev} appears in individual @sc{rcs}
+files.  Each @sc{rcs} file is searched for the revision or
+tag.
+
+@item -t @var{tag}
+Show records since tag @var{tag} was last added to the the
+history file.  This differs from the @samp{-r} flag
+above in that it reads only the history file, not the
+@sc{rcs} files, and is much faster.
+
+@item -u @var{name}
+Show records for user @var{name}.
+@end table
+
+@ignore
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@c @node history examples
+@appendixsubsec history examples
+
+Contributed examples will gratefully be accepted.
+@c -- Examples here!
+@end ignore
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node import
+@appendixsec import---Import sources into CVS, using vendor branches
+@cindex Import (subcommand)
+
+@itemize @bullet
+@item
+Synopsis: import [-options] repository vendortag releasetag@dots{}
+@item
+Requires: Repository, source distribution directory.
+@item
+Changes: repository.
+@end itemize
+
+Use @code{import} to incorporate an entire source
+distribution from an outside source (e.g., a source
+vendor) into your source repository directory.  You can
+use this command both for initial creation of a
+repository, and for wholesale updates to the module
+from the outside source.  @xref{Tracking sources}, for
+a discussion on this subject.
+
+The @var{repository} argument gives a directory name
+(or a path to a directory) under the @sc{cvs} root directory
+for repositories; if the directory did not exist,
+import creates it.
+
+When you use import for updates to source that has been
+modified in your source repository (since a prior
+import), it will notify you of any files that conflict
+in the two branches of development; use @samp{checkout
+-j} to reconcile the differences, as import instructs
+you to do.
+
+If @sc{cvs} decides a file should be ignored
+(@pxref{cvsignore}), it does not import it and prints
+@samp{I } followed by the filename
+
+If the file @file{$CVSROOT/CVSROOT/cvswrappers} exists,
+any file whose names match the specifications in that
+file will be treated as packages and the appropriate
+filtering will be performed on the file/directory
+before being imported, @xref{Wrappers}.
+
+The outside source is saved in a first-level @sc{rcs}
+branch, by default 1.1.1.  Updates are leaves of this
+branch; for example, files from the first imported
+collection of source will be revision 1.1.1.1, then
+files from the first imported update will be revision
+1.1.1.2, and so on.
+
+At least three arguments are required.
+@var{repository} is needed to identify the collection
+of source.  @var{vendortag} is a tag for the entire
+branch (e.g., for 1.1.1).  You must also specify at
+least one @var{releasetag} to identify the files at
+the leaves created each time you execute @code{import}.
+
+@menu
+* import options::              import options
+* import examples::             import examples
+@end menu
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node import options
+@appendixsubsec import options
+
+This standard option is supported by @code{import}
+(@pxref{Common options}, for a complete description):
+
+@table @code
+@item -m @var{message}
+Use @var{message} as log information, instead of
+invoking an editor.
+@end table
+
+There are three additional special options.
+
+@table @code
+@item -b @var{branch}
+Specify a first-level branch other than 1.1.1.  Unless
+the @samp{-b @var{branch}} flag is given, revisions will
+@emph{always} be made to the branch 1.1.1---even if a
+@var{vendortag} that matches another branch is given!
+What happens in that case, is that the tag will be
+reset to 1.1.1.  Warning: This behavior might change
+in the future.
+
+@item -k @var{subst}
+Indicate the RCS keyword expansion mode desired.  This
+setting will apply to all files created during the
+import, but not to any files that previously existed in
+the repository.  See @ref{Substitution modes} for a
+list of valid @samp{-k} settings.
+
+@item -I @var{name}
+Specify file names that should be ignored during
+import.  You can use this option repeatedly.  To avoid
+ignoring any files at all (even those ignored by
+default), specify `-I !'.
+
+@var{name} can be a file name pattern of the same type
+that you can specify in the @file{.cvsignore} file.
+@xref{cvsignore}.
+@c -- Is this really true?
+
+@item -W @var{spec}
+Specify file names that should be filtered during
+import.  You can use this option repeatedly.
+
+@var{spec} can be a file name pattern of the same type
+that you can specify in the @file{.cvswrappers}
+file. @xref{Wrappers}.
+@end table
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node import examples
+@appendixsubsec import examples
+
+@xref{Tracking sources}, and @xref{From files}.
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node log
+@appendixsec log---Print out 'rlog' information for files
+@cindex Log (subcommand)
+
+@itemize @bullet
+@item
+Synopsis: log [-l] rlog-options [files@dots{}]
+@item
+Requires: repository, working directory.
+@item
+Changes: nothing.
+@item
+Synonym: rlog
+@end itemize
+
+Display log information for files.  @code{log} calls
+the @sc{rcs} utility @code{rlog}, which prints all available
+information about the @sc{rcs} history file.  This includes
+the location of the @sc{rcs} file, the @dfn{head} revision
+(the latest revision on the trunk), all symbolic names (tags)
+and some other things.  For each revision, the revision
+number, the author, the number of lines added/deleted and
+the log message are printed.  All times are displayed in
+Coordinated Universal Time (UTC).  (Other parts of @sc{cvs}
+print times in the local timezone).
+@c -- timezone--
+
+@menu
+* log options::                 log options
+* log examples::                log examples
+@end menu
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node log options
+@appendixsubsec log options
+
+Only one option is interpreted by @sc{cvs} and not passed on to @code{rlog}:
+
+@table @code
+@item -l
+Local; run only in current working directory.  (Default
+is to run recursively).
+@end table
+
+By default, @code{rlog} prints all information that is
+available.  All other options (including those that
+normally behave differently) are passed through to
+@code{rlog} and restrict the output.  See rlog(1) for a
+complete description of options.  This incomplete list
+(which is a slightly edited extract from rlog(1)) lists
+all options that are useful in conjunction with @sc{cvs}.
+
+@strong{Please note:}  There can be no space between the option
+and its argument, since @code{rlog} parses its options
+in a different way than @sc{cvs}.
+
+@table @code
+@item -b
+Print information about the revisions on the default
+branch, normally the highest branch on the trunk.
+
+@item -d@var{dates}
+Print information about revisions with a checkin
+date/time in the range given by the
+semicolon-separated list of dates.  The following table
+explains the available range formats:
+
+@table @code
+@item @var{d1}<@var{d2}
+@itemx @var{d2}>@var{d1}
+Select the revisions that were deposited between
+@var{d1} and @var{d2} inclusive.
+
+@item <@var{d}
+@itemx @var{d}>
+Select all revisions dated @var{d} or earlier.
+
+@item @var{d}<
+@itemx >@var{d}
+Select all revisions dated @var{d} or later.
+
+@item @var{d}
+Select the single, latest revision dated @var{d} or
+earlier.
+@end table
+
+The date/time strings @var{d}, @var{d1}, and @var{d2}
+are in the free format explained in co(1).  Quoting is
+normally necessary, especially for < and >.  Note that
+the separator is a semicolon (;).
+
+@item -h
+Print only the @sc{rcs} pathname, working pathname, head,
+default branch, access list, locks, symbolic names, and
+suffix.
+
+@item -N
+Do not print the list of tags for this file.  This
+option can be very useful when your site uses a lot of
+tags, so rather than "more"'ing over 3 pages of tag
+information, the log information is presented without
+tags at all.  
+
+@item -R
+Print only the name of the @sc{rcs} history file.
+
+@item -r@var{revisions}
+Print information about revisions given in the
+comma-separated list @var{revisions} of revisions and
+ranges.  The following table explains the available
+range formats:
+
+@table @code
+@item @var{rev1}:@var{rev2}
+Revisions @var{rev1} to @var{rev2} (which must be on
+the same branch).
+
+@item :@var{rev}
+Revisions from the beginning of the branch up to
+and including @var{rev}.
+
+@item @var{rev}: 
+Revisions starting with @var{rev} to the end of the
+branch containing @var{rev}.
+
+@item @var{branch}
+An argument that is a branch means all revisions on
+that branch.  You can unfortunately not specify a
+symbolic branch here.  You must specify the numeric
+branch number.  @xref{Magic branch numbers}, for an
+explanation.
+
+@item @var{branch1}:@var{branch2}
+A range of branches means all revisions
+on the branches in that range.
+
+@item @var{branch}.
+The latest revision in @var{branch}.
+@end table
+
+A bare @samp{-r} with no revisions means the latest
+revision on the default branch, normally the trunk.
+
+@item -s@var{states}
+Print information about revisions whose state
+attributes match one of the states given in the
+comma-separated list @var{states}.
+
+@item -t
+Print the same as @samp{-h}, plus the descriptive text.
+
+@item -w@var{logins}
+Print information about revisions checked in by users
+with login names appearing in the comma-separated list
+@var{logins}.  If @var{logins} is omitted, the user's
+login is assumed.
+@end table
+
+@code{rlog} prints the intersection of the revisions
+selected with the options @samp{-d}, @samp{-l},
+@samp{-s}, and @samp{-w}, intersected with the union of
+the revisions selected by @samp{-b} and @samp{-r}.
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node log examples
+@appendixsubsec log examples
+
+Contributed examples are gratefully accepted.
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node rdiff
+@appendixsec rdiff---'patch' format diffs between releases
+@cindex Rdiff (subcommand)
+
+@itemize @bullet
+@item
+rdiff [-flags] [-V vn] [-r t|-D d [-r t2|-D d2]] modules@dots{}
+@item
+Requires: repository.
+@item
+Changes: nothing.
+@item
+Synonym: patch
+@end itemize
+
+Builds a Larry Wall format patch(1) file between two
+releases, that can be fed directly into the patch
+program to bring an old release up-to-date with the new
+release.  (This is one of the few @sc{cvs} commands that
+operates directly from the repository, and doesn't
+require a prior checkout.) The diff output is sent to
+the standard output device.
+
+You can specify (using the standard @samp{-r} and
+@samp{-D} options) any combination of one or two
+revisions or dates.  If only one revision or date is
+specified, the patch file reflects differences between
+that revision or date and the current head revisions in
+the @sc{rcs} file.
+
+Note that if the software release affected is contained
+in more than one directory, then it may be necessary to
+specify the @samp{-p} option to the patch command when
+patching the old sources, so that patch is able to find
+the files that are located in other directories.
+
+@menu
+* rdiff options::               rdiff options
+* rdiff examples::              rdiff examples
+@end menu
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node rdiff options
+@appendixsubsec rdiff options
+
+These standard options are supported by @code{rdiff}
+(@pxref{Common options}, for a complete description of
+them):
+
+@table @code
+@item -D @var{date}
+Use the most recent revision no later than @var{date}.
+
+@item -f
+If no matching revision is found, retrieve the most
+recent revision (instead of ignoring the file).
+
+@item -l
+Local; don't descend subdirectories.
+
+@item -r @var{tag}
+Use revision @var{tag}.
+@end table
+
+In addition to the above, these options are available:
+
+@table @code
+@item -c
+Use the context diff format.  This is the default format.
+
+@item -s
+Create a summary change report instead of a patch.  The
+summary includes information about files that were
+changed or added between the releases.  It is sent to
+the standard output device.  This is useful for finding
+out, for example, which files have changed between two
+dates or revisions.
+
+@item -t
+A diff of the top two revisions is sent to the standard
+output device.  This is most useful for seeing what the
+last change to a file was.
+
+@item -u
+Use the unidiff format for the context diffs.
+This option is not available if your diff does not
+support the unidiff format.  Remember that old versions
+of the @code{patch} program can't handle the unidiff
+format, so if you plan to post this patch to the net
+you should probably not use @samp{-u}.
+
+@item -V @var{vn}
+Expand @sc{rcs} keywords according to the rules current in
+@sc{rcs} version @var{vn} (the expansion format changed with
+@sc{rcs} version 5).
+@end table
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node rdiff examples
+@appendixsubsec rdiff examples
+
+Suppose you receive mail from @t{foo@@bar.com} asking for an
+update from release 1.2 to 1.4 of the tc compiler.  You
+have no such patches on hand, but with @sc{cvs} that can
+easily be fixed with a command such as this:
+
+@example
+$ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \
+$$ Mail -s 'The patches you asked for' foo@@bar.com
+@end example
+
+Suppose you have made release 1.3, and forked a branch
+called @samp{R_1_3fix} for bugfixes.  @samp{R_1_3_1}
+corresponds to release 1.3.1, which was made some time
+ago.  Now, you want to see how much development has been
+done on the branch.  This command can be used:
+
+@example
+$ cvs patch -s -r R_1_3_1 -r R_1_3fix module-name
+cvs rdiff: Diffing module-name
+File ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6
+File foo.c,v changed from revision 1.52.2.3 to 1.52.2.4
+File bar.h,v changed from revision 1.29.2.1 to 1.2
+@end example
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node release
+@appendixsec release---Indicate that a Module is no longer in use
+@cindex Release (subcommand)
+
+@itemize @bullet
+@item
+release [-d] directories@dots{}
+@item
+Requires: Working directory.
+@item
+Changes: Working directory, history log.
+@end itemize
+
+This command is meant to safely cancel the effect of
+@samp{cvs checkout}.  Since @sc{cvs} doesn't lock files, it
+isn't strictly necessary to use this command.  You can
+always simply delete your working directory, if you
+like; but you risk losing changes you may have
+forgotten, and you leave no trace in the @sc{cvs} history
+file (@pxref{history file}) that you've abandoned your
+checkout.
+
+Use @samp{cvs release} to avoid these problems.  This
+command checks that no uncommitted changes are
+present; that you are executing it from immediately
+above a @sc{cvs} working directory; and that the repository
+recorded for your files is the same as the repository
+defined in the module database.
+
+If all these conditions are true, @samp{cvs release}
+leaves a record of its execution (attesting to your
+intentionally abandoning your checkout) in the @sc{cvs}
+history log.
+
+@menu
+* release options::             release options
+* release output::              release options
+* release examples::            release examples
+@end menu
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node release options
+@appendixsubsec release options
+
+The @code{release} command supports one command option:
+
+@table @code
+@item -d
+Delete your working copy of the file if the release
+succeeds.  If this flag is not given your files will
+remain in your working directory.
+
+@strong{Warning:}  The @code{release} command uses
+@samp{rm -r @file{module}} to delete your file.  This
+has the very serious side-effect that any directory
+that you have created inside your checked-out sources,
+and not added to the repository (using the @code{add}
+command; @pxref{add}) will be silently deleted---even
+if it is non-empty!
+@end table
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node release output
+@appendixsubsec release output
+
+Before @code{release} releases your sources it will
+print a one-line message for any file that is not
+up-to-date.  
+
+@strong{Warning:}  Any new directories that you have
+created, but not added to the @sc{cvs} directory hierarchy
+with the @code{add} command (@pxref{add}) will be
+silently ignored (and deleted, if @samp{-d} is
+specified), even if they contain files.
+
+@table @code
+@item U @var{file}
+There exists a newer revision of this file in the
+repository, and you have not modified your local copy
+of the file.
+
+@item A @var{file}
+The file has been added to your private copy of the
+sources, but has not yet been committed to the
+repository.  If you delete your copy of the sources
+this file will be lost.
+
+@item R @var{file}
+The file has been removed from your private copy of the
+sources, but has not yet been removed from the
+repository, since you have not yet committed the
+removal.  @xref{commit}.
+
+@item M @var{file}
+The file is modified in your working directory.  There
+might also be a newer revision inside the repository.
+
+@item ? @var{file}
+@var{file} is in your working directory, but does not
+correspond to anything in the source repository, and is
+not in the list of files for @sc{cvs} to ignore (see the
+description of the @samp{-I} option, and
+@pxref{cvsignore}).  If you remove your working
+sources, this file will be lost.
+
+Note that no warning message like this is printed for
+spurious directories that @sc{cvs} encounters.  The
+directory, and all its contents, are silently ignored.
+
+@c FIXME -- CVS should be fixed to print "? foo" for
+@c such spurious directories
+@end table
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node release examples
+@appendixsubsec release examples
+
+Release the module, and delete your local working copy
+of the files.
+
+@example
+$ cd ..         # @r{You must stand immediately above the}
+                # @r{sources when you issue @samp{cvs release}.}
+$ cvs release -d tc
+You have [0] altered files in this repository.
+Are you sure you want to release (and delete) module `tc': y
+$
+@end example
+
+@node rtag
+@appendixsec rtag---Add a tag to the RCS file
+@cindex Rtag (subcommand)
+
+@itemize @bullet
+@item
+rtag [-falnR] [-b] [-d] [-r tag | -Ddate] symbolic_tag modules@dots{}
+@item
+Requires: repository.
+@item
+Changes: repository.
+@item
+Synonym: rfreeze
+@end itemize
+
+You can use this command to assign symbolic tags to
+particular, explicitly specified source revisions in
+the repository.  @code{rtag} works directly on the
+repository contents (and requires no prior checkout).
+Use @code{tag} instead (@pxref{tag}), to base the
+selection of revisions on the contents of your
+working directory.
+
+If you attempt to use a tag name that already exists,
+@sc{cvs} will complain and not overwrite that tag.  Use
+the @samp{-F} option to force the new tag value.
+
+@menu
+* rtag options::                rtag options
+@end menu
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node rtag options
+@appendixsubsec rtag options
+
+These standard options are supported by @code{rtag}
+(@pxref{Common options}, for a complete description of
+them):
+
+@table @code
+@item -D @var{date}
+Tag the most recent revision no later than @var{date}.
+
+@item -f
+Only useful with the @samp{-D @var{date}} or @samp{-r @var{tag}}
+flags.  If no matching revision is found, use the most
+recent revision (instead of ignoring the file).
+
+@item -F 
+Overwrite an existing tag of the same name on a
+different revision.  This option is new in @sc{cvs}
+1.4.  The old behavior is matched by @samp{cvs tag -F}.
+
+@item -l
+Local; run only in current working directory.
+
+@item -n
+Do not run any tag program that was specified with the
+@samp{-t} flag inside the @file{modules} file.
+(@pxref{modules}).
+
+@item -R
+Commit directories recursively.  This is on by default.
+
+@item -r @var{tag}
+Only tag those files that contain @var{tag}.  This can
+be used to rename a tag: tag only the files identified
+by the old tag, then delete the old tag, leaving the
+new tag on exactly the same files as the old tag.
+@end table
+
+In addition to the above common options, these options
+are available:
+
+@table @code
+@item -a
+Use the @samp{-a} option to have @code{rtag} look in the
+@file{Attic} (@pxref{Removing files}) for removed files
+that contain the specified tag.  The tag is removed from
+these files, which makes it convenient to re-use a
+symbolic tag as development continues (and files get
+removed from the up-coming distribution).
+
+@item -b
+Make the tag a branch tag.  @xref{Branches}.
+
+@item -d
+Delete the tag instead of creating it.
+
+In general, tags (often the symbolic names of software
+distributions) should not be removed, but the @samp{-d}
+option is available as a means to remove completely
+obsolete symbolic names if necessary (as might be the
+case for an Alpha release, or if you mistagged a
+module).
+@end table
+
+@ignore
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@c @node rtag examples
+@appendixsubsec rtag examples
+
+@c -- Examples here!
+@end ignore
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node status
+@appendixsec status---Status info on the revisions
+@cindex Status (subcommand)
+
+@itemize @bullet
+@item
+status [-lR] [-v] [files@dots{}]
+@item
+Requires: working directory, repository.
+@item
+Changes: nothing.
+@end itemize
+
+Display a brief report on the current status of files
+with respect to the source repository, including any
+sticky tags, dates, or @samp{-k} options.
+
+You can also use this command to determine the
+potential impact of a @samp{cvs update} on your working
+source directory---but remember that things might
+change in the repository before you run @code{update}.
+
+@menu
+* status options::              status options
+@end menu
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node status options
+@appendixsubsec status options
+
+These standard options are supported by @code{status}
+(@pxref{Common options}, for a complete description of
+them):
+
+@table @code
+@item -l
+Local; run only in current working directory.
+
+@item -R
+Commit directories recursively.  This is on by default.
+@end table
+
+There is one additional option:
+
+@table @code
+@item -v
+Verbose.  In addition to the information normally
+displayed, print all symbolic tags, together with the
+numerical value of the revision or branch they refer
+to.
+@end table
+
+@ignore
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@c @node status examples
+@appendixsubsec status examples
+
+@c -- FIXME
+@end ignore
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node tag
+@appendixsec tag---Add a symbolic tag to checked out version of RCS file
+@c --                    //////// - unnecessary. Also
+@c --                               in a lot of other
+@c --                               places.
+@cindex Tag (subcommand)
+
+@itemize @bullet
+@item
+tag [-lR] [-b] [-d] symbolic_tag [files@dots{}]
+@item
+Requires: working directory, repository.
+@item
+Changes: repository.
+@item
+Synonym: freeze
+@end itemize
+
+Use this command to assign symbolic tags to the nearest
+repository versions to your working sources.  The tags
+are applied immediately to the repository, as with
+@code{rtag}, but the versions are supplied implicitly by the
+@sc{cvs} records of your working files' history rather than
+applied explicitly.
+
+One use for tags is to record a snapshot of the
+current sources when the software freeze date of a
+project arrives.  As bugs are fixed after the freeze
+date, only those changed sources that are to be part of
+the release need be re-tagged.
+
+The symbolic tags are meant to permanently record which
+revisions of which files were used in creating a
+software distribution.  The @code{checkout} and
+@code{update} commands allow you to extract an exact
+copy of a tagged release at any time in the future,
+regardless of whether files have been changed, added,
+or removed since the release was tagged.
+
+This command can also be used to delete a symbolic tag,
+or to create a branch.  See the options section below.
+
+If you attempt to use a tag name that already exists,
+@sc{cvs} will complain and not overwrite that tag.  Use
+the @samp{-F} option to force the new tag value.
+
+
+@menu
+* tag options::                 tag options
+@end menu
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node tag options
+@appendixsubsec tag options
+
+These standard options are supported by @code{tag}
+(@pxref{Common options}, for a complete description of
+them):
+
+@table @code
+@item -F 
+Overwrite an existing tag of the same name on a
+different revision.  This option is new in @sc{cvs}
+1.4.  The old behavior is matched by @samp{cvs tag -F}.
+
+@item -l
+Local; run only in current working directory.
+
+@item -R
+Commit directories recursively.  This is on by default.
+@end table
+
+Two special options are available:
+
+@table @code
+@item -b
+The -b option makes the tag a branch tag
+(@pxref{Branches}), allowing concurrent, isolated
+development.  This is most useful for creating a patch
+to a previously released software distribution.
+
+@item -d
+Delete a tag.
+
+If you use @samp{cvs tag -d symbolic_tag}, the symbolic
+tag you specify is deleted instead of being added.
+Warning: Be very certain of your ground before you
+delete a tag; doing this permanently discards some
+historical information, which may later turn out to
+be valuable.
+@end table
+
+@ignore
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@c @node tag examples
+@appendixsubsec tag examples
+
+@c -- FIXME
+@end ignore
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node update
+@appendixsec update---Bring work tree in sync with repository
+@cindex Update (subcommand)
+
+@itemize @bullet
+@item
+update [-AdflPpR] [-d] [-r tag|-D date] files@dots{}
+@item
+Requires: repository, working directory.
+@item
+Changes: working directory.
+@end itemize
+
+After you've run checkout to create your private copy
+of source from the common repository, other developers
+will continue changing the central source.  From time
+to time, when it is convenient in your development
+process, you can use the @code{update} command from
+within your working directory to reconcile your work
+with any revisions applied to the source repository
+since your last checkout or update.
+
+@menu
+* update options::              update options
+* update output::               update output
+* update examples::             update examples
+@end menu
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node update options
+@appendixsubsec update options
+
+These standard options are available with @code{update}
+(@pxref{Common options}, for a complete description of
+them):
+
+@table @code
+@item -D date
+Use the most recent revision no later than @var{date}.
+This option is sticky, and implies @samp{-P}.
+See @ref{Sticky tags}, for more information on sticky tags/dates.
+
+@item -f
+Only useful with the @samp{-D @var{date}} or @samp{-r
+@var{tag}} flags.  If no matching revision is found,
+retrieve the most recent revision (instead of ignoring
+the file).
+
+@item -k @var{kflag}
+Process @sc{rcs} keywords according to @var{kflag}.  See
+co(1).  This option is sticky; future updates of
+this file in this working directory will use the same
+@var{kflag}.  The @code{status} command can be viewed
+to see the sticky options.  @xref{status}.
+
+@item -l
+Local; run only in current working directory.  @xref{Recursive behavior}.
+
+@item -P
+Prune empty directories.
+
+@item -p
+Pipe files to the standard output.
+
+@item -R
+Operate recursively.  This is on by default.
+@xref{Recursive behavior}.
+
+@item -r tag
+Retrieve revision @var{tag}.  This option is sticky,
+and implies @samp{-P}.
+See @ref{Sticky tags}, for more information on sticky tags/dates.
+@end table
+
+@need 800
+These special options are also available with
+@code{update}.
+
+@table @code
+@item -A
+Reset any sticky tags, dates, or @samp{-k} options.
+See @ref{Sticky tags}, for more information on sticky tags/dates.
+
+@item -d
+Create any directories that exist in the repository if
+they're missing from the working directory.  Normally,
+@code{update} acts only on directories and files that
+were already enrolled in your working directory.  
+
+This is useful for updating directories that were
+created in the repository since the initial checkout;
+but it has an unfortunate side effect.  If you
+deliberately avoided certain directories in the
+repository when you created your working directory
+(either through use of a module name or by listing
+explicitly the files and directories you wanted on the
+command line), then updating with @samp{-d} will create
+those directories, which may not be what you want.
+
+@item -I @var{name}
+Ignore files whose names match @var{name} (in your
+working directory) during the update.  You can specify
+@samp{-I} more than once on the command line to specify
+several files to ignore.  Use @samp{-I !} to avoid
+ignoring any files at all.  @xref{cvsignore}, for other
+ways to make @sc{cvs} ignore some files.
+
+@item -W@var{spec}
+Specify file names that should be filtered during
+update.  You can use this option repeatedly.
+
+@var{spec} can be a file name pattern of the same type
+that you can specify in the @file{.cvswrappers}
+file. @xref{Wrappers}.
+
+@item -j@var{revision}
+With two @samp{-j} options, merge changes from the
+revision specified with the first @samp{-j} option to
+the revision specified with the second @samp{j} option,
+into the working directory.
+
+With one @samp{-j} option, merge changes from the
+ancestor revision to the revision specified with the
+@samp{-j} option, into the working directory.  The
+ancestor revision is the common ancestor of the
+revision which the working directory is based on, and
+the revision specified in the @samp{-j} option.
+
+In addition, each -j option can contain an optional
+date specification which, when used with branches, can
+limit the chosen revision to one within a specific
+date.  An optional date is specified by adding a colon
+(:) to the tag:
+@samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}.
+
+@xref{Merging}.
+
+@end table
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node update output
+@appendixsubsec update output
+
+@code{update} keeps you informed of its progress by
+printing a line for each file, preceded by one
+character indicating the status of the file:
+
+@table @code
+@item U @var{file}
+The file was brought up to date with respect to the
+repository.  This is done for any file that exists in
+the repository but not in your source, and for files
+that you haven't changed but are not the most recent
+versions available in the repository.
+
+@item A @var{file}
+The file has been added to your private copy of the
+sources, and will be added to the source repository
+when you run @code{commit} on the file.  This is a
+reminder to you that the file needs to be committed.
+
+@item R @var{file}
+The file has been removed from your private copy of the
+sources, and will be removed from the source repository
+when you run @code{commit} on the file.  This is a
+reminder to you that the file needs to be committed.
+
+@item M @var{file}
+The file is modified in  your  working  directory.
+
+@samp{M} can indicate one of two states for a file
+you're working on: either there were no modifications
+to the same file in the repository, so that your file
+remains as you last saw it; or there were modifications
+in the repository as well as in your copy, but they
+were merged successfully, without conflict, in your
+working directory.
+
+@sc{cvs} will print some messages if it merges your work,
+and a backup copy of your working file (as it looked
+before you ran @code{update}) will be made.  The exact
+name of that file is printed while @code{update} runs.
+
+@item C @var{file}
+A conflict was detected while trying to merge your
+changes to @var{file} with changes from the source
+repository.  @var{file} (the copy in your working
+directory) is now the output of the rcsmerge(1) command
+on the two revisions; an unmodified copy of your file
+is also in your working directory, with the name
+@file{.#@var{file}.@var{revision}} where @var{revision}
+is the @sc{rcs} revision that your modified file started
+from.  (Note that some systems automatically purge
+files that begin with @file{.#} if they have not been
+accessed for a few days.  If you intend to keep a copy
+of your original file, it is a very good idea to rename
+it.)
+
+@item ? @var{file}
+@var{file} is in your working directory, but does not
+correspond to anything in the source repository, and is
+not in the list of files for @sc{cvs} to ignore (see the
+description of the @samp{-I} option, and
+@pxref{cvsignore}).
+
+Note that no warning message like this is printed for
+spurious directories that @sc{cvs} encounters.  The
+directory, and all its contents, are silently ignored.
+@end table
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node update examples
+@appendixsubsec update examples
+
+The following line will display all files which are not
+up-to-date without actually change anything in your
+working directory.  It can be used to check what has
+been going on with the project.
+
+@example
+$ cvs -n -q update
+@end example
+
+@c ---------------------------------------------------------------------
+@node Administrative files
+@appendix Reference manual for the Administrative files
+@cindex Administrative files (reference)
+@cindex Files, reference manual
+@cindex Reference manual (files)
+@cindex CVSROOT (file)
+
+Inside the repository, in the directory
+@file{$CVSROOT/CVSROOT}, there are a number of
+supportive files for @sc{cvs}.  You can use @sc{cvs} in a limited
+fashion without any of them, but if they are set up
+properly they can help make life easier.
+
+The most important of these files is the @file{modules}
+file, which defines the modules inside the repository.
+
+@menu
+* modules::                     Defining modules
+* Wrappers::                    Treat directories as files
+* commit files::                The commit support files
+* commitinfo::                  Pre-commit checking
+* editinfo::                    Specifying how log messages are created
+* loginfo::                     Where should log messages be sent?
+* rcsinfo::                     Templates for the log messages
+* cvsignore::                   Ignoring files via cvsignore
+* history file::                History information
+* Setting up::                  Setting up the repository
+* Variables::                   Various variables are expanded
+@end menu
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node modules
+@appendixsec The modules file
+@cindex Modules (admin file)
+@cindex Defining modules (reference manual)
+
+The @file{modules} file records your definitions of
+names for collections of source code.  @sc{cvs} will
+use these definitions if you use @sc{cvs} to update the
+modules file (use normal commands like @code{add},
+@code{commit}, etc).
+
+The @file{modules} file may contain blank lines and
+comments (lines beginning with @samp{#}) as well as
+module definitions.  Long lines can be continued on the
+next line by specifying a backslash (@samp{\}) as the
+last character on the line.
+
+A module definition is a single line of the
+@file{modules} file, in either of two formats.  In both
+cases, @var{mname} represents the symbolic module name,
+and the remainder of the line is its definition.
+
+@table @code
+@item @var{mname} -a @var{aliases}@dots{}
+This represents the simplest way of defining a module
+@var{mname}.  The @samp{-a} flags the definition as a
+simple alias: @sc{cvs} will treat any use of @var{mname} (as
+a command argument) as if the list of names
+@var{aliases} had been specified instead.
+@var{aliases} may contain either other module names or
+paths.  When you use paths in aliases, @code{checkout}
+creates all intermediate directories in the working
+directory, just as if the path had been specified
+explicitly in the @sc{cvs} arguments.
+
+@item @var{mname} [ options ] @var{dir} [ @var{files}@dots{} ] [ &@var{module}@dots{} ]
+In the simplest case, this form of module definition
+reduces to @samp{@var{mname} @var{dir}}.  This defines
+all the files in directory @var{dir} as module mname.
+@var{dir} is a relative path (from @code{$CVSROOT}) to a
+directory of source in the source repository.  In this
+case, on checkout, a single directory called
+@var{mname} is created as a working directory; no
+intermediate directory levels are used by default, even
+if @var{dir} was a path involving several directory
+levels.
+
+By explicitly specifying files in the module definition
+after @var{dir}, you can select particular files from
+directory @var{dir}.  The sample definition for
+@samp{modules} is an example of a module defined with a
+single file from a particular directory.  Here is
+another example:
+
+@example
+m4test  unsupported/gnu/m4 foreach.m4 forloop.m4
+@end example
+
+@noindent
+With this definition, executing @samp{cvs checkout
+m4test} will create a single working directory
+@file{m4test} containing the two files listed, which
+both come from a common directory several levels deep
+in the @sc{cvs} source repository.
+
+A module definition can refer to other modules by
+including @samp{&@var{module}} in its definition.
+@code{checkout} creates a subdirectory for each such
+module, in your working directory.
+@c -- Nope. "in your working directory" is wrong. What
+@c -- is right?
+
+@table @code
+@item -d @var{name}
+Name the working directory something other than the
+module name.
+
+@cindex Export program
+@item -e @var{prog}
+Specify a program @var{prog} to run whenever files in a
+module are exported.  @var{prog} runs with a single
+argument, the module name.
+
+@cindex Checkin program
+@item -i @var{prog}
+Specify a program @var{prog} to run whenever files in a
+module are committed.  @var{prog} runs with a single
+argument, the full pathname of the affected directory
+in a source repository.  The @file{commitinfo},
+@file{loginfo}, and @file{editinfo} files provide other
+ways to call a program on commit.
+
+@cindex Checkout program
+@item -o @var{prog}
+Specify a program @var{prog} to run whenever files in a
+module are checked out.  @var{prog} runs with a single
+argument, the module name.
+
+@cindex Status of a module
+@cindex Module status
+@item -s @var{status}
+Assign a status to the module.  When the module file is
+printed with @samp{cvs checkout -s} the modules are
+sorted according to primarily module status, and
+secondarily according to the module name.  This option
+has no other meaning.  You can use this option for
+several things besides status: for instance, list the
+person that is responsible for this module.
+
+@cindex Tag program
+@item -t @var{prog}
+Specify a program @var{prog} to run whenever files in a
+module are tagged with @code{rtag}.  @var{prog} runs
+with two arguments: the module name and the symbolic
+tag specified to @code{rtag}.  There is no way to
+specify a program to run when @code{tag} is executed.
+
+@cindex Update program
+@item -u @var{prog}
+Specify a program @var{prog} to run whenever @samp{cvs
+update} is executed from the top-level directory of the
+checked-out module.  @var{prog} runs with a single
+argument, the full path to the source repository for
+this module.
+@end table
+@end table
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Wrappers
+@appendixsec The cvswrappers file
+@cindex cvswrappers (admin file)
+@cindex CVSWRAPPERS, environment variable
+@cindex Wrappers
+
+Wrappers allow you to set a hook which transforms files on
+their way in and out of @sc{cvs}.  Most or all of the
+wrappers features do not work with client/server @sc{cvs}.
+
+The file @file{cvswrappers} defines the script that will be
+run on a file when its name matches a regular
+expresion. There are two scripts that can be run on a
+file or directory. One script is executed on the file/directory
+before being checked into the repository (this is denoted
+with the @code{-t} flag) and the other when the file is
+checked out of the repository (this is denoted with the
+@code{-f} flag)
+
+The @file{cvswrappers} also has a @samp{-m} option to
+specify the merge methodology that should be used when
+the file is updated.  @code{MERGE} means the usual
+@sc{cvs} behavior: try to merge the files (this
+generally will not work for binary files).  @code{COPY}
+means that @code{cvs update} will merely copy one
+version over the other, and require the user using
+mechanisms outside @sc{cvs}, to insert any necessary
+changes.
+@c FIXME: which version is copied over which version?
+The @samp{-m} wrapper option only affects behavior when
+merging is done on update; it does not affect how files
+are stored.  See @xref{Binary files}, for more on
+binary files.
+
+The basic format of the file @file{cvswrappers} is:
+
+@example
+wildcard     [option value][option value]...
+
+where option is one of
+-f           from cvs filter         value: path tofilter
+-t           to cvs filter           value: path to filter
+-m           update methodology      value: MERGE or COPY
+
+and value is a single-quote delimited value.
+@end example
+
+@example
+*.nib    -f 'unwrap %s' -t 'wrap %s %s' -m 'COPY'
+*.c      -t 'indent %s %s'
+@end example
+
+@noindent
+The above example of a @file{cvswrappers} file
+states that all files/directories that end with a @code{.nib}
+should be filtered with the @file{wrap} program before
+checking the file into the repository. The file should
+be filtered though the @file{unwrap} program when the
+file is checked out of the repository. The
+@file{cvswrappers} file also states that a @code{COPY}
+methodology should be used when updating the files in
+the repository (that is no merging should be performed).
+
+The last example line says that all files that end with
+a @code{*.c} should be filtered with @file{indent}
+before being checked into the repository. Unlike the previous
+example no filtering of the @code{*.c} file is done when
+it is checked out of the repository.
+@noindent
+The @code{-t} filter is called with two arguments,
+the first is the name of the file/directory to filter
+and the second is the pathname to where the resulting
+filtered file should be placed.
+
+@noindent
+The @code{-f} filter is called with one argument,
+which is the name of the file to filter from. The end
+result of this filter will be a file in the users directory
+that they can work on as they normally would.
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node commit files
+@appendixsec The commit support files
+@cindex Commit files
+
+The @samp{-i} flag in the @file{modules} file can be
+used to run a certain program whenever files are
+committed (@pxref{modules}).  The files described in
+this section provide other, more flexible, ways to run
+programs whenever something is committed.
+
+There are three kind of programs that can be run on
+commit.  They are specified in files in the repository,
+as described below.  The following table summarizes the
+file names and the purpose of the corresponding
+programs.
+
+@table @file
+@item commitinfo
+The program is responsible for checking that the commit
+is allowed.  If it exits with a non-zero exit status
+the commit will be aborted.
+
+@item editinfo
+The specified program is used to edit the log message,
+and possibly verify that it contains all required
+fields.  This is most useful in combination with the
+@file{rcsinfo} file, which can hold a log message
+template (@pxref{rcsinfo}).
+
+@item loginfo
+The specified program is called when the commit is
+complete.  It receives the log message and some
+additional information and can store the log message in
+a file, or mail it to appropriate persons, or maybe
+post it to a local newsgroup, or@dots{}  Your
+imagination is the limit!
+@end table
+
+@menu
+* syntax::                      The common syntax
+@end menu
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node syntax
+@appendixsubsec The common syntax
+@cindex Info files (syntax)
+@cindex Syntax of info files
+@cindex Common syntax of info files
+
+The four files @file{commitinfo}, @file{loginfo},
+@file{rcsinfo} and @file{editinfo} all have a common
+format.  The purpose of the files are described later
+on.  The common syntax is described here.
+
+Each line contains the following:
+@itemize @bullet
+@item
+A regular expression
+
+@item
+A whitespace separator---one or more spaces and/or tabs.
+
+@item
+A file name or command-line template.
+@end itemize
+
+@noindent
+Blank lines are ignored.  Lines that start with the
+character @samp{#} are treated as comments.  Long lines
+unfortunately can @emph{not} be broken in two parts in
+any way.
+
+The first regular expression that matches the current
+directory name in the repository is used.  The rest of the line
+is used as a file name or command-line as appropriate.
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node commitinfo
+@appendixsec Commitinfo
+@cindex Commitinfo
+@cindex Checking commits
+@cindex Precommit checking
+
+The @file{commitinfo} file defines programs to execute
+whenever @samp{cvs commit} is about to execute.  These
+programs are used for pre-commit checking to verify
+that the modified, added and removed files are really
+ready to be committed.  This could be used, for
+instance, to verify that the changed files conform to
+to your site's standards for coding practice.
+
+As mentioned earlier, each line in the
+@file{commitinfo} file consists of a regular expression
+and a command-line template.  The template can include
+a program name and any number of arguments you wish to
+supply to it.  The full path to the current source
+repository is appended to the template, followed by the
+file names of any files involved in the commit (added,
+removed, and modified files).
+
+The first line with a regular expression matching the
+relative path to the module will be used.  If the
+command returns a non-zero exit status the commit will
+be aborted.
+
+@cindex DEFAULT in commitinfo
+If the repository name does not match any of the
+regular expressions in this file, the @samp{DEFAULT}
+line is used, if it is specified.
+
+@cindex ALL in commitinfo
+All occurances of the name @samp{ALL} appearing as a
+regular expression are used in addition to the first
+matching regular expression or the name @samp{DEFAULT}.
+
+Note: when @sc{CVS} is accessing a remote repository,
+@file{commitinfo} will be run on the @emph{remote}
+(i.e., server) side, not the client side (@pxref{Remote
+repositories}).
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node editinfo
+@appendixsec Editinfo
+@cindex Editinfo
+@cindex Editor, specifying per module
+@cindex Per-module editor
+@cindex Log messages, editing
+
+If you want to make sure that all log messages look the
+same way, you can use the @file{editinfo} file to
+specify a program that is used to edit the log message.
+This program could be a custom-made editor that always
+enforces a certain style of the log message, or maybe a
+simple shell script that calls an editor, and checks
+that the entered message contains the required fields.
+
+If no matching line is found in the @file{editinfo}
+file, the editor specified in the environment variable
+@code{$CVSEDITOR} is used instead.  If that variable is
+not set, then the environment variable @code{$EDITOR}
+is used instead.  If that variable is not
+set a precompiled default, normally @code{vi}, will be
+used.
+
+The @file{editinfo} file is often most useful together
+with the @file{rcsinfo} file, which can be used to
+specify a log message template.
+
+Each line in the @file{editinfo} file consists of a
+regular expression and a command-line template.  The
+template must include a program name, and can include
+any number of arguments.  The full path to the current
+log message template file is appended to the template.
+
+One thing that should be noted is that the @samp{ALL}
+keyword is not supported.  If more than one matching
+line is found, the first one is used.  This can be
+useful for specifying a default edit script in a
+module, and then overriding it in a subdirectory.
+
+@cindex DEFAULT in editinfo
+If the repository name does not match any of the
+regular expressions in this file, the @samp{DEFAULT}
+line is used, if it is specified.
+
+If the edit script exits with a non-zero exit status,
+the commit is aborted.
+
+Note: when @sc{CVS} is accessing a remote repository,
+@file{editinfo} will be run on the @emph{remote}
+(i.e., server) side, not the client side (@pxref{Remote
+repositories}).
+
+@menu
+* editinfo example::            Editinfo example
+@end menu
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node editinfo example
+@appendixsubsec Editinfo example
+
+The following is a little silly example of a
+@file{editinfo} file, together with the corresponding
+@file{rcsinfo} file, the log message template and an
+editor script.  We begin with the log message template.
+We want to always record a bug-id number on the first
+line of the log message.  The rest of log message is
+free text.  The following template is found in the file
+@file{/usr/cvssupport/tc.template}.
+
+@example
+BugId:    
+@end example
+
+The script @file{/usr/cvssupport/bugid.edit} is used to
+edit the log message.
+
+@example
+#!/bin/sh
+#
+#       bugid.edit filename
+#
+#  Call $EDITOR on FILENAME, and verify that the
+#  resulting file contains a valid bugid on the first
+#  line.
+if [ "x$EDITOR" = "x" ]; then EDITOR=vi; fi
+if [ "x$CVSEDITOR" = "x" ]; then CVSEDITOR=$EDITOR; fi
+$CVSEDITOR $1
+until head -1|grep '^BugId:[ ]*[0-9][0-9]*$' < $1
+do  echo -n  "No BugId found.  Edit again? ([y]/n)"
+    read ans
+    case $@{ans@} in
+        n*) exit 1;;
+    esac
+    $CVSEDITOR $1
+done
+@end example
+
+The @file{editinfo} file contains this line:
+
+@example
+^tc     /usr/cvssupport/bugid.edit
+@end example
+
+The @file{rcsinfo} file contains this line:
+
+@example
+^tc     /usr/cvssupport/tc.template
+@end example
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node loginfo
+@appendixsec Loginfo
+@cindex Loginfo
+@cindex Storing log messages
+@cindex Mailing log messages
+@cindex Distributing log messages
+@cindex Log messages
+
+The @file{loginfo} file is used to control where
+@samp{cvs commit} log information is sent.  The first
+entry on a line is a regular expression which is tested
+against the directory that the change is being made to,
+relative to the @code{$CVSROOT}.  If a match is found, then
+the remainder of the line is a filter program that
+should expect log information on its standard input.
+
+The filter program may use one and only one % modifier
+(a la printf).  If @samp{%s} is specified in the filter
+program, a brief title is included (enclosed in single
+quotes) showing the modified file names.
+
+If the repository name does not match any of the
+regular expressions in this file, the @samp{DEFAULT}
+line is used, if it is specified.
+
+All occurances of the name @samp{ALL} appearing as a
+regular expression are used in addition to the first
+matching regular expression or @samp{DEFAULT}.
+
+The first matching regular expression is used.
+
+@xref{commit files}, for a description of the syntax of
+the @file{loginfo} file.  
+
+Note: when @sc{CVS} is accessing a remote repository,
+@file{loginfo} will be run on the @emph{remote}
+(i.e., server) side, not the client side (@pxref{Remote
+repositories}).
+
+@menu
+* loginfo example::             Loginfo example
+@end menu
+
+@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+@node loginfo example
+@appendixsubsec Loginfo example
+
+The following @file{loginfo} file, together with the
+tiny shell-script below, appends all log messages 
+to the file @file{$CVSROOT/CVSROOT/commitlog},
+and any commits to the administrative files (inside
+the @file{CVSROOT} directory) are also logged in
+@file{/usr/adm/cvsroot-log}.
+@c and mailed to @t{ceder}.
+
+@c FIXME: is it a CVS feature or bug that only the
+@c first matching line is used?  It is documented
+@c above, but is it useful?  This example (with the
+@c mail to ceder put back in) is awkward to write if
+@c only the first matching line is used.
+@example
+ALL             /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog
+@c ^CVSROOT        Mail -s %s ceder
+^CVSROOT        /usr/local/bin/cvs-log /usr/adm/cvsroot-log
+@end example
+
+The shell-script @file{/usr/local/bin/cvs-log} looks
+like this:
+
+@example
+#!/bin/sh
+(echo "-----------------------------------------------------------------";
+ echo -n $USER"  ";
+ date;
+ echo;
+ sed '1s+'$@{CVSROOT@}'++') >> $1
+@end example
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node rcsinfo
+@appendixsec Rcsinfo
+@cindex Rcsinfo
+@cindex Form for log message
+@cindex Log message template
+@cindex Template for log message
+
+The @file{rcsinfo} file can be used to specify a form to
+edit when filling out the commit log.  The
+@file{rcsinfo} file has a syntax similar to the
+@file{editinfo}, @file{commitinfo} and @file{loginfo}
+files.  @xref{syntax}.  Unlike the other files the second
+part is @emph{not} a command-line template.  Instead,
+the part after the regular expression should be a full pathname to
+a file containing the log message template.
+
+If the repository name does not match any of the
+regular expressions in this file, the @samp{DEFAULT}
+line is used, if it is specified.
+
+All occurances of the name @samp{ALL} appearing as a
+regular expression are used in addition to the first
+matching regular expression or @samp{DEFAULT}.
+
+The log message template will be used as a default log
+message.  If you specify a log message with @samp{cvs
+commit -m @var{message}} or @samp{cvs commit -f
+@var{file}} that log message will override the
+template.
+
+@xref{editinfo example}, for an example @file{rcsinfo}
+file.
+
+When @sc{CVS} is accessing a remote repository,
+the contents of @file{rcsinfo} at the time a directory
+is first checked out will specify a template which does
+not then change.  If you edit @file{rcsinfo} or its
+templates, you may need to check out a new working
+directory.
+@c Would be nice to fix CVS so this isn't needed.  For
+@c example, a mechanism analogous to CVS/Entries, where
+@c the client keeps track of what version of the template
+@c it has.
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node cvsignore
+@appendixsec Ignoring files via cvsignore
+@cindex Cvsignore, global
+@cindex Global cvsignore
+@cindex Ignoring files
+@c -- This chapter should maybe be moved to the
+@c tutorial part of the manual?
+
+There are certain file names that frequently occur
+inside your working copy, but that you don't want to
+put under @sc{cvs} control.  Examples are all the object
+files that you get while you compile your sources.
+Normally, when you run @samp{cvs update}, it prints a
+line for each file it encounters that it doesn't know
+about (@pxref{update output}).
+
+@sc{cvs} has a list of files (or sh(1) file name patterns)
+that it should ignore while running @code{update},
+@code{import} and @code{release}.
+@c -- Are those the only three commands affected?
+This list is constructed in the following way.
+
+@itemize @bullet
+@item
+The list is initialized to include certain file name
+patterns: names associated with @sc{cvs}
+administration, or with other common source control
+systems; common names for patch files, object files,
+archive files, and editor backup files; and other names
+that are usually artifacts of assorted utilities.
+Currently, the default list of ignored file name
+patterns is:
+
+@cindex Ignored files
+@cindex Automatically ignored files
+@example
+    RCS     SCCS    CVS     CVS.adm
+    RCSLOG  cvslog.*
+    tags    TAGS
+    .make.state     .nse_depinfo
+    *~      #*      .#*     ,*      _$*     *$
+    *.old   *.bak   *.BAK   *.orig  *.rej   .del-*
+    *.a     *.olb   *.o     *.obj   *.so    *.exe
+    *.Z     *.elc   *.ln  
+    core
+@end example
+
+@item
+The per-repository list in
+@file{$CVSROOT/CVSROOT/cvsignore} is appended to
+the list, if that file exists.
+
+@item
+The per-user list in @file{.cvsignore} in your home
+directory is appended to the list, if it exists.
+
+@item
+Any entries in the environment variable
+@code{$CVSIGNORE} is appended to the list.
+
+@item
+Any @samp{-I} options given to @sc{cvs} is appended.
+
+@item
+As @sc{cvs} traverses through your directories, the contents
+of any @file{.cvsignore} will be appended to the list.
+The patterns found in @file{.cvsignore} are only valid
+for the directory that contains them, not for
+any sub-directories.
+@end itemize
+
+In any of the 5 places listed above, a single
+exclamation mark (@samp{!}) clears the ignore list.
+This can be used if you want to store any file which
+normally is ignored by @sc{cvs}.
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node history file
+@appendixsec The history file
+@cindex History file
+@cindex Log information, saving
+
+The file @file{$CVSROOT/CVSROOT/history} is used
+to log information for the @code{history} command
+(@pxref{history}).  This file must be created to turn
+on logging.  This is done automatically if the
+@code{cvs init} command is used to set up the
+repository (@pxref{Setting up}).
+
+The file format of the @file{history} file is
+documented only in comments in the @sc{cvs} source
+code, but generally programs should use the @code{cvs
+history} command to access it anyway, in case the
+format changes with future releases of @sc{cvs}.
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Setting up
+@appendixsec Setting up the repository 
+@cindex Repository, setting up
+@cindex Creating a repository
+@cindex Setting up a repository
+
+To set up a @sc{cvs} repository, choose a directory
+with ample disk space available for the revision
+history of the source files.  It should be accessable
+(directly or via a networked file system) from all
+machines which want to use @sc{cvs} in server or local
+mode; the client machines need not have any access to
+it other than via the @sc{cvs} protocol.
+
+To create a repository, run the @code{cvs init}
+command.  It will set up an empty repository in the
+@sc{cvs} root specified in the usual way
+(@pxref{Repository}).  For example,
+
+@example
+cvs -d /usr/local/cvsroot init
+@end example
+
+@code{cvs init} is careful to never overwrite any
+existing files in the repository, so no harm is done if
+you run @code{cvs init} on an already set-up
+repository.
+
+@code{cvs init} will enable history logging; if you
+don't want that, remove the history file after running
+@code{cvs init}.  @xref{history file}.
+
+@node Variables
+@appendixsec Expansions in administrative files
+
+Sometimes in writing an administrative file, you might
+want the file to be able to know various things based
+on environment @sc{cvs} is running in.  There are
+several mechanisms to do that.
+
+To find the home directory of the user running @sc{cvs}
+(from the @code{HOME} environment variable), use
+@samp{~} followed by @samp{/} or the end of the line.
+Likewise for the home directory of @var{user}, use
+@samp{~@var{user}}.  These variables are expanded on
+the server machine, and don't get any resonable
+expansion if pserver (@pxref{Password authenticated})
+is in used; therefore user variables (see below) may be
+a better choice to customize behavior based on the user
+running @sc{cvs}.
+@c Based on these limitations, should we deprecate ~?
+@c What is it good for?  Are people using it?
+
+One may want to know about various pieces of
+information internal to @sc{cvs}.  A @sc{cvs} internal
+variable has the syntax @code{$@{@var{variable}@}},
+where @var{variable} starts with a letter and consists
+of alphanumberic characters and @samp{_}.  If the
+character following @var{variable} is a
+non-alphanumeric character other than @samp{_}, the
+@samp{@{} and @samp{@}} can be omitted.  The @sc{cvs}
+internal variables are:
+
+@table @code
+@item CVSROOT
+This is the value of the @sc{cvs} root in use.
+@xref{Repository}, for a description of the various
+ways to specify this.
+
+@item RCSBIN
+This is the value @sc{cvs} is using for where to find
+@sc{rcs} binaries.  @xref{Global options}, for a
+description of how to specify this.
+
+@item CVSEDITOR
+@itemx VISUAL
+@itemx EDITOR
+These all expand to the same value, which is the editor
+that @sc{cvs} is using.  @xref{Global options}, for how
+to specify this.
+
+@item USER
+Username of the user running @sc{cvs} (on the @sc{cvs}
+server machine).
+@end table
+
+If you want to pass a value to the administrative files
+which the user that is running @sc{cvs} can specify,
+use a user variable.  To expand a user variable, the
+administrative file contains
+@code{$@{=@var{variable}@}}.  To set a user variable,
+specify the global option @samp{-s} to @sc{cvs}, with
+argument @code{@var{variable}=@var{value}}.  It may be
+particularly useful to specify this option via
+@file{.cvsrc} (@pxref{~/.cvsrc}).
+
+For example, if you want the administrative file to
+refer to a test directory you might create a user
+variable @code{TESTDIR}.  Then if @sc{cvs} is invoked
+as @code{cvs -s TESTDIR=/work/local/tests}, and the
+administrative file contains @code{sh
+$@{=TESTDIR@}/runtests}, then that string is expanded
+to @code{sh /work/local/tests/runtests}.
+
+All other strings containing @samp{$} are reserved;
+there is no way to quote a @samp{$} character so that
+@samp{$} represents itself.
+
+@c ---------------------------------------------------------------------
+@node Environment variables
+@appendix All environment variables which affect CVS
+@cindex Environment variables
+@cindex Reference manual for variables
+
+This is a complete list of all environment variables
+that affect @sc{cvs}.
+
+@table @code
+@cindex CVSIGNORE
+@item $CVSIGNORE
+A whitespace-separated list of file name patterns that
+@sc{cvs} should ignore. @xref{cvsignore}.
+
+@cindex CVSWRAPPERS
+@item $CVSWRAPPERS
+A whitespace-separated list of file name patterns that
+@sc{cvs} should treat as wrappers. @xref{Wrappers}.
+
+@cindex CVSREAD
+@item $CVSREAD
+If this is set, @code{checkout} and @code{update} will
+try hard to make the files in your working directory
+read-only.  When this is not set, the default behavior
+is to permit modification of your working files.
+
+@cindex CVSROOT
+@item $CVSROOT
+Should contain the full pathname to the root of the @sc{cvs}
+source repository (where the @sc{rcs} history files are
+kept).  This information must be available to @sc{cvs} for
+most commands to execute; if @code{$CVSROOT} is not set,
+or if you wish to override it for one invocation, you
+can supply it on the command line: @samp{cvs -d cvsroot
+cvs_command@dots{}} Once you have checked out a working
+directory, @sc{cvs} stores the appropriate root (in
+the file @file{CVS/Root}), so normally you only need to
+worry about this when initially checking out a working 
+directory.
+
+@cindex EDITOR
+@cindex CVSEDITOR
+@item $EDITOR
+@itemx $CVSEDITOR
+Specifies the program to use for recording log messages
+during commit.  If not set, the default is
+@samp{/usr/ucb/vi}.  @code{$CVSEDITOR} overrides
+@code{$EDITOR}.  @code{$CVSEDITOR} does not exist in
+@sc{cvs} 1.3, but the next release will probably
+include it.
+
+@cindex PATH
+@item $PATH
+If @code{$RCSBIN} is not set, and no path is compiled
+into @sc{cvs}, it will use @code{$PATH} to try to find all
+programs it uses.
+
+@cindex RCSBIN
+@item $RCSBIN
+Specifies the full pathname of the location of @sc{rcs} programs,
+such as co(1) and ci(1).  If not set, a compiled-in
+value is used, or your @code{$PATH} is searched.
+
+@cindex HOME
+@item $HOME
+@cindex HOMEPATH
+@item $HOMEPATH
+Used to locate the directory where the @file{.cvsrc}
+file is searched (@code{$HOMEPATH} is used for Windows-NT).
+@pxref{~/.cvsrc}
+
+@cindex CVS_RSH
+@item $CVS_RSH
+Used in client-server mode when accessing a remote
+repository using @sc{rsh}.  The default value is
+@code{rsh}.  You can set it to use another program for
+accssing the remote server (e.g. for HP-UX 9, you
+should set it to @code{remsh} because @code{rsh}
+invokes the restricted shell).  @pxref{Connecting via
+rsh}
+
+@item $CVS_SERVER
+Used in client-server mode when accessing a remote
+repository using @sc{rsh}.  It specifies the name of
+the program to start on the server side when accessing
+a remote repository using @sc{rsh}.  The default value
+is @code{cvs}.  @pxref{Connecting via rsh}
+
+@item $CVS_PASSFILE
+Used in client-server mode when accessing the @code{cvs
+login server}.  Default value is @file{$HOME/.cvspass}.
+@pxref{Password authentication client}
+
+@item $CVS_PASSWORD
+Used in client-server mode when accessing the @code{cvs
+login server}.
+@pxref{Password authentication client}
+
+@item $CVS_CLIENT_PORT
+Used in client-server mode when accessing the server
+via Kerberos.
+@pxref{Kerberos authenticated}
+
+@cindex CVS_RCMD_PORT
+@item $CVS_RCMD_PORT
+Used in client-server mode.  If set, specifies the port
+number to be used when accessing the @sc{rcmd} demon on
+the server side. (Currently not used for Unix clients).
+
+@cindex CVS_CLIENT_LOG
+@item $CVS_CLIENT_LOG
+Used for debugging only in client-server
+mode.  If set, everything send to the server is logged
+into @file{@code{$CVS_CLIENT_LOG}.in} and everything
+send from the server is logged into
+@file{@code{$CVS_CLIENT_LOG}.out}.
+
+@cindex CVS_SERVER_SLEEP
+@item $CVS_SERVER_SLEEP
+Used only for debugging the server side in
+client-server mode.  If set, delays the start of the
+server child process the the specified amount of
+seconds so that you can attach to it with a debugger.
+
+@cindex CVS_IGNORE_REMOTE_ROOT
+@item $CVS_IGNORE_REMOTE_ROOT
+(What is the purpose of this variable?)
+
+@cindex COMSPEC
+@item $COMSPEC
+Used under OS/2 only.  It specifies the name of the
+command interpreter and defaults to @sc{cmd.exe}.
+
+
+@end table
+
+@sc{cvs} is a front-end to @sc{rcs}.  The following environment
+variables affect @sc{rcs}.  Note that if you are using
+the client/server @sc{cvs}, these variables need to be
+set on the server side (which may or not may be
+possible depending on how you are connecting).  There
+is probably not any need to set any of them, however.
+
+@table @code
+@cindex LOGNAME
+@item $LOGNAME
+@cindex USER
+@itemx $USER
+If set, they affect who @sc{rcs} thinks you are.  If you
+have trouble checking in files it might be because your
+login name differs from the setting of e.g.
+@code{$LOGNAME}.
+
+@cindex RCSINIT
+@item $RCSINIT
+Options prepended to the argument list, separated by
+spaces.  A backslash escapes spaces within an option.
+The @code{$RCSINIT} options are prepended to the
+argument lists of most @sc{rcs} commands.
+
+@cindex TMPDIR
+@item $TMPDIR
+@cindex TMP
+@itemx $TMP
+@cindex TEMP
+@itemx $TEMP
+Name of the temporary directory.  The environment
+variables are inspected in the order they appear above
+and the first value found is taken; if none of them are
+set, a host-dependent default is used, typically
+@file{/tmp}.
+@end table
+
+@c ---------------------------------------------------------------------
+@node Troubleshooting
+@appendix Troubleshooting
+
+@menu
+* Magic branch numbers::        Magic branch numbers
+@end menu
+
+@ignore
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@c @node Bad administrative files
+@appendixsec Bad administrative files
+
+@c -- Give hints on how to fix them
+@end ignore
+
+@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+@node Magic branch numbers
+@appendixsec Magic branch numbers
+
+Externally, branch numbers consist of an odd number of
+dot-separated decimal integers.  @xref{Revision
+numbers}.  That is not the whole truth, however.  For
+efficiency reasons @sc{cvs} sometimes inserts an extra 0
+in the second rightmost position (1.2.3 becomes
+1.2.0.3, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so
+on).
+
+@sc{cvs} does a pretty good job at hiding these so
+called magic branches, but in at least four places the
+hiding is incomplete.
+
+@itemize @bullet
+@item
+The magic branch can appear in the output from
+@code{cvs status} in vanilla @sc{cvs} 1.3.  This is
+fixed in @sc{cvs} 1.3-s2.
+
+@item
+The magic branch number appears in the output from
+@code{cvs log}.  This is much harder to fix, since
+@code{cvs log} runs @code{rlog} (which is part of the
+@sc{rcs} distribution), and modifying @code{rlog} to
+know about magic branches would probably break someone's
+habits (if they use branch 0 for their own purposes).
+
+@item
+You cannot specify a symbolic branch name to @code{cvs log}.
+
+@item
+You cannot specify a symbolic branch name to @code{cvs
+admin}.
+
+@end itemize
+
+You can use the @code{admin} command to reassign a
+symbolic name to a branch the way @sc{rcs} expects it
+to be.  If @code{R4patches} is assigned to the branch
+1.4.2 (magic branch number 1.4.0.2) in file
+@file{numbers.c} you can do this:
+
+@example
+$ cvs admin -NR4patches:1.4.2 numbers.c
+@end example
+
+It only works if at least one revision is already
+committed on the branch.  Be very careful so that you
+do not assign the tag to the wrong number.  (There is
+no way to see how the tag was assigned yesterday).
+
+@c ---------------------------------------------------------------------
+@node Copying
+@appendix GNU GENERAL PUBLIC LICENSE
+@c @include gpl.texinfo
+
+@c ---------------------------------------------------------------------
+@node Index
+@unnumbered Index
+@cindex Index
+
+@printindex cp
+
+@summarycontents
+
+@contents
+
+@bye
+
+Local Variables:
+fill-column: 55
+End: