   Copyright (C) 1992, 1993 Signum Support AB Copyright (C) 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.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
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 this permission notice may be stated in a
translation approved by the Free Software Foundation.

update options
--------------

   These standard options are available with `update' (see Common options,
for a complete description of them):

`-D date'
     Use the most recent revision no later than DATE.  This option is
     sticky, and implies `-P'.  See Sticky tags, for more
     information on sticky tags/dates.

`-f'
     Only useful with the `-D DATE' or `-r TAG' flags.  If no matching
     revision is found, retrieve the most recent revision (instead of
     ignoring the file).

`-k KFLAG'
     Process keywords according to KFLAG.  See Keyword substitution.
     This option is sticky; future updates of this
     file in this working directory will use the same KFLAG.  The
     `status' command can be viewed to see the sticky options.  See
     Invoking CVS, for more information on the `status' command.

`-l'
     Local; run only in current working directory.  See Recursive behavior.

`-P'
     Prune empty directories.  See Moving directories.

`-p'
     Pipe files to the standard output.

`-R'
     Update directories recursively (default).  See Recursive behavior.

`-r rev'
     Retrieve revision/tag REV.  This option is sticky, and implies
     `-P'.  See Sticky tags, for more information on sticky
     tags/dates.

   These special options are also available with `update'.

`-A'
     Reset any sticky tags, dates, or `-k' options.  See Sticky tags,
     for more information on sticky tags/dates.

`-C'
     Overwrite locally modified files with clean copies from the
     repository (the modified file is saved in `.#FILE.REVISION',
     however).

`-d'
     Create any directories that exist in the repository if they're
     missing from the working directory.  Normally, `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 `-d' will create those directories, which may not be what you
     want.

`-I NAME'
     Ignore files whose names match NAME (in your working directory)
     during the update.  You can specify `-I' more than once on the
     command line to specify several files to ignore.  Use `-I !' to
     avoid ignoring any files at all.  See cvsignore, for other
     ways to make CVS ignore some files.

`-WSPEC'
     Specify file names that should be filtered during update.  You can
     use this option repeatedly.

     SPEC can be a file name pattern of the same type that you can
     specify in the `.cvswrappers' file. See Wrappers.

`-jREVISION'
     With two `-j' options, merge changes from the revision specified
     with the first `-j' option to the revision specified with the
     second `j' option, into the working directory.

     With one `-j' option, merge changes from the ancestor revision to
     the revision specified with the `-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 `-j' option.

     Note that using a single `-j TAGNAME' option rather than `-j
     BRANCHNAME' to merge changes from a branch will often not remove
     files which were removed on the branch.  See Merging adds and removals,
     for more.

     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:
     `-jSYMBOLIC_TAG:DATE_SPECIFIER'.

     See Branching and merging.

update output
-------------

   `update' and `checkout' keep you informed of their progress by
printing a line for each file, preceded by one character indicating the
status of the file:

`U 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.

`P FILE'
     Like `U', but the CVS server sends a patch instead of an entire
     file.  This accomplishes the same thing as `U' using less
     bandwidth.

`A FILE'
     The file has been added to your private copy of the sources, and
     will be added to the source repository when you run `commit' on
     the file.  This is a reminder to you that the file needs to be
     committed.

`R FILE'
     The file has been removed from your private copy of the sources,
     and will be removed from the source repository when you run
     `commit' on the file.  This is a reminder to you that the file
     needs to be committed.

`M FILE'
     The file is modified in  your  working  directory.

     `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.

     CVS will print some messages if it merges your work, and a backup
     copy of your working file (as it looked before you ran `update')
     will be made.  The exact name of that file is printed while
     `update' runs.

`C FILE'
     A conflict was detected while trying to merge your changes to FILE
     with changes from the source repository.  FILE (the copy in your
     working directory) is now the result of attempting to merge the
     two revisions; an unmodified copy of your file is also in your
     working directory, with the name `.#FILE.REVISION' where REVISION
     is the revision that your modified file started from.  Resolve the
     conflict as described in Conflicts example.  (Note that
     some systems automatically purge files that begin with `.#' 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.)  Under VMS, the file name starts with `__' rather than `.#'.

`? FILE'
     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 CVS to ignore (see the description of the `-I' option, and
     cvsignore).

Quick reference to CVS commands
*******************************

   This appendix describes how to invoke CVS, with references to where
each command or feature is described in detail.  For other references
run the `cvs --help' command, or see Index.

   A CVS command looks like:

     cvs [ GLOBAL_OPTIONS ] COMMAND [ COMMAND_OPTIONS ] [ COMMAND_ARGS ]

   Global options:

`--allow-root=ROOTDIR'
     Specify legal CVSROOT directory (server only) (not in CVS 1.9 and
     older).  See Password authentication server.

`-a'
     Authenticate all communication (client only) (not in CVS 1.9 and
     older).  See Global options.

`-b'
     Specify RCS location (CVS 1.9 and older).  See Global options.

`-d ROOT'
     Specify the CVSROOT.  See Repository.

`-e EDITOR'
     Edit messages with EDITOR.  See Committing your changes.

`-f'
     Do not read the `~/.cvsrc' file.  See Global options.

`-H'
`--help'
     Print a help message.  See Global options.

`-l'
     Do not log in `$CVSROOT/CVSROOT/history' file.  See Global options.

`-n'
     Do not change any files.  See Global options.

`-Q'
     Be really quiet.  See Global options.

`-q'
     Be somewhat quiet.  See Global options.

`-r'
     Make new working files read-only.  See Global options.

`-s VARIABLE=VALUE'
     Set a user variable.  See Variables.

`-T TEMPDIR'
     Put temporary files in TEMPDIR.  See Global options.

`-t'
     Trace CVS execution.  See Global options.

`-v'

`--version'
     Display version and copyright information for CVS.

`-w'
     Make new working files read-write.  See Global options.

`-x'
     Encrypt all communication (client only).  See Global options.

`-z GZIP-LEVEL'
     Set the compression level (client only).  See Global options.

   Keyword expansion modes (see Substitution modes):

     -kkv  $Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp $
     -kkvl $Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
     -kk   $Id$
     -kv   file1,v 1.1 1993/12/09 03:21:13 joe Exp
     -ko   no expansion
     -kb   no expansion, file is binary

   Keywords (see Keyword list):

     $Author: joe $
     $Date: 1993/12/09 03:21:13 $
     $Header: /home/files/file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
     $Id: file1,v 1.1 1993/12/09 03:21:13 joe Exp harry $
     $Locker: harry $
     $Name: snapshot_1_14 $
     $RCSfile: file1,v $
     $Revision: 1.1 $
     $Source: /home/files/file1,v $
     $State: Exp $
     $Log: file1,v $
     Revision 1.1  1993/12/09 03:30:17  joe
     Initial revision

   Commands, command options, and command arguments:

`add [OPTIONS] [FILES...]'
     Add a new file/directory.  See Adding files.

    `-k KFLAG'
          Set keyword expansion.

    `-m MSG'
          Set file description.

`admin [OPTIONS] [FILES...]'
     Administration of history files in the repository.  See
     admin.

    `-b[REV]'
          Set default branch.  See Reverting local changes.

    `-cSTRING'
          Set comment leader.

    `-kSUBST'
          Set keyword substitution.  See Keyword substitution.

    `-l[REV]'
          Lock revision REV, or latest revision.

    `-mREV:MSG'
          Replace the log message of revision REV with MSG.

    `-oRANGE'
          Delete revisions from the repository.  See admin options.

    `-q'
          Run quietly; do not print diagnostics.

    `-sSTATE[:REV]'
          Set the state.

    `-t'
          Set file description from standard input.

    `-tFILE'
          Set file description from FILE.

    `-t-STRING'
          Set file description to STRING.

    `-u[REV]'
          Unlock revision REV, or latest revision.

`annotate [OPTIONS] [FILES...]'
     Show last revision where each line was modified.  See
     annotate.

    `-D DATE'
          Annotate the most recent revision no later than DATE.  See
          Common options.

    `-F'
          Force annotation of binary files.  (Without this option,
          binary files are skipped with a message.)

    `-f'
          Use head revision if tag/date not found.  See Common options.

    `-l'
          Local; run only in current working directory.  See
          Recursive behavior.

    `-R'
          Operate recursively (default).  See Recursive behavior.

    `-r TAG'
          Annotate revision TAG.  See Common options.

`checkout [OPTIONS] MODULES...'
     Get a copy of the sources.  See checkout.

    `-A'
          Reset any sticky tags/date/options.  See Sticky tags
          and Keyword substitution.

    `-c'
          Output the module database.  See checkout options.

    `-D DATE'
          Check out revisions as of DATE (is sticky).  See Common options.

    `-d DIR'
          Check out into DIR.  See checkout options.

    `-f'
          Use head revision if tag/date not found.  See Common options.

    `-j REV'
          Merge in changes.  See checkout options.

    `-k KFLAG'
          Use KFLAG keyword expansion.  See Substitution modes.

    `-l'
          Local; run only in current working directory.  See
          Recursive behavior.

    `-N'
          Don't "shorten" module paths if -d specified.  See
          checkout options.

    `-n'
          Do not run module program (if any).  See checkout options.

    `-P'
          Prune empty directories.  See Moving directories.

    `-p'
          Check out files to standard output (avoids stickiness).  See
          checkout options.

    `-R'
          Operate recursively (default).  See Recursive behavior.

    `-r TAG'
          Checkout revision TAG (is sticky).  See Common options.

    `-s'
          Like -c, but include module status.  See checkout options.

`commit [OPTIONS] [FILES...]'
     Check changes into the repository.  See commit.

    `-F FILE'
          Read log message from FILE.  See commit options.

    `-f'
          Force the file to be committed; disables recursion.  See
          commit options.

    `-l'
          Local; run only in current working directory.  See
          Recursive behavior.

    `-m MSG'
          Use MSG as log message.  See commit options.

    `-n'
          Do not run module program (if any).  See commit options.

    `-R'
          Operate recursively (default).  See Recursive behavior.

    `-r REV'
          Commit to REV.  See commit options.

`diff [OPTIONS] [FILES...]'
     Show differences between revisions.  See diff.  In
     addition to the options shown below, accepts a wide variety of
     options to control output style, for example `-c' for context
     diffs.

    `-D DATE1'
          Diff revision for date against working file.  See diff options.

    `-D DATE2'
          Diff REV1/DATE1 against DATE2.  See diff options.

    `-l'
          Local; run only in current working directory.  See
          Recursive behavior.

    `-N'
          Include diffs for added and removed files.  See diff options.

    `-R'
          Operate recursively (default).  See Recursive behavior.

    `-r REV1'
          Diff revision for REV1 against working file.  See diff options.

    `-r REV2'
          Diff REV1/DATE1 against REV2.  See diff options.

`edit [OPTIONS] [FILES...]'
     Get ready to edit a watched file.  See Editing files.

    `-a ACTIONS'
          Specify actions for temporary watch, where ACTIONS is `edit',
          `unedit', `commit', `all', or `none'.  See Editing files.

    `-l'
          Local; run only in current working directory.  See
          Recursive behavior.

    `-R'
          Operate recursively (default).  See Recursive behavior.

`editors [OPTIONS] [FILES...]'
     See who is editing a watched file.  See Watch information.

    `-l'
          Local; run only in current working directory.  See
          Recursive behavior.

    `-R'
          Operate recursively (default).  See Recursive behavior.

`export [OPTIONS] MODULES...'
     Export files from CVS.  See export.

    `-D DATE'
          Check out revisions as of DATE.  See Common options.

    `-d DIR'
          Check out into DIR.  See export options.

    `-f'
          Use head revision if tag/date not found.  See Common options.

    `-k KFLAG'
          Use KFLAG keyword expansion.  See Substitution modes.

    `-l'
          Local; run only in current working directory.  See
          Recursive behavior.

    `-N'
          Don't "shorten" module paths if -d specified.  See
          export options.

    `-n'
          Do not run module program (if any).  See export options.

    `-P'
          Prune empty directories.  See Moving directories.

    `-R'
          Operate recursively (default).  See Recursive behavior.

    `-r TAG'
          Checkout revision TAG.  See Common options.

`history [OPTIONS] [FILES...]'
     Show repository access history.  See history.

    `-a'
          All users (default is self).  See history options.

    `-b STR'
          Back to record with STR in module/file/repos field.  See
          history options.

    `-c'
          Report on committed (modified) files.  See history options.

    `-D DATE'
          Since DATE.  See history options.

    `-e'
          Report on all record types.  See history options.

    `-l'
          Last modified (committed or modified report).  See
          history options.

    `-m MODULE'
          Report on MODULE (repeatable).  See history options.

    `-n MODULE'
          In MODULE.  See history options.

    `-o'
          Report on checked out modules.  See history options.

    `-p REPOSITORY'
          In REPOSITORY.  See history options.

    `-r REV'
          Since revision REV.  See history options.

    `-T'
          Produce report on all TAGs.  See history options.

    `-t TAG'
          Since tag record placed in history file (by anyone).  See
          history options.

    `-u USER'
          For user USER (repeatable).  See history options.

    `-w'
          Working directory must match.  See history options.

    `-x TYPES'
          Report on TYPES, one or more of `TOEFWUCGMAR'.  See
          history options.

    `-z ZONE'
          Output for time zone ZONE.  See history options.

`import [OPTIONS] REPOSITORY VENDOR-TAG RELEASE-TAGS...'
     Import files into CVS, using vendor branches.  See import.

    `-b BRA'
          Import to vendor branch BRA.  See Multiple vendor branches.

    `-d'
          Use the file's modification time as the time of import.  See
          import options.

    `-k KFLAG'
          Set default keyword substitution mode.  See import options.

    `-m MSG'
          Use MSG for log message.  See import options.

    `-I IGN'
          More files to ignore (! to reset).  See import options.

    `-W SPEC'
          More wrappers.  See import options.

`init'
     Create a CVS repository if it doesn't exist.  See Creating a repository.

`kserver'
     Kerberos authenticated server.  See Kerberos authenticated.

`log [OPTIONS] [FILES...]'
     Print out history information for files.  See log.

    `-b'
          Only list revisions on the default branch.  See log options.

    `-d DATES'
          Specify dates (D1<D2 for range, D for latest before).  See
          log options.

    `-h'
          Only print header.  See log options.

    `-l'
          Local; run only in current working directory.  See
          Recursive behavior.

    `-N'
          Do not list tags.  See log options.

    `-R'
          Only print name of RCS file.  See log options.

    `-rREVS'
          Only list revisions REVS.  See log options.

    `-s STATES'
          Only list revisions with specified states.  See log options.

    `-t'
          Only print header and descriptive text.  See log options.

    `-wLOGINS'
          Only list revisions checked in by specified logins.  See
          log options.

`login'
     Prompt for password for authenticating server.  See Password authentication client.

`logout'
     Remove stored password for authenticating server.  See
     Password authentication client.

`pserver'
     Password authenticated server.  See Password authentication server.

`rannotate [OPTIONS] [MODULES...]'
     Show last revision where each line was modified.  See
     annotate.

    `-D DATE'
          Annotate the most recent revision no later than DATE.  See
          Common options.

    `-F'
          Force annotation of binary files.  (Without this option,
          binary files are skipped with a message.)

    `-f'
          Use head revision if tag/date not found.  See Common options.

    `-l'
          Local; run only in current working directory.  See
          Recursive behavior.

    `-R'
          Operate recursively (default).  See Recursive behavior.

    `-r TAG'
          Annotate revision TAG.  See Common options.

`rdiff [OPTIONS] MODULES...'
     Show differences between releases.  See rdiff.

    `-c'
          Context diff output format (default).  See rdiff options.

    `-D DATE'
          Select revisions based on DATE.  See Common options.

    `-f'
          Use head revision if tag/date not found.  See Common options.

    `-l'
          Local; run only in current working directory.  See
          Recursive behavior.

    `-R'
          Operate recursively (default).  See Recursive behavior.

    `-r REV'
          Select revisions based on REV.  See Common options.

    `-s'
          Short patch - one liner per file.  See rdiff options.

    `-t'
          Top two diffs - last change made to the file.  See diff options.

    `-u'
          Unidiff output format.  See rdiff options.

    `-V VERS'
          Use RCS Version VERS for keyword expansion (obsolete).  See
          rdiff options.

`release [OPTIONS] DIRECTORY'
     Indicate that a directory is no longer in use.  See
     release.

    `-d'
          Delete the given directory.  See release options.

`remove [OPTIONS] [FILES...]'
     Remove an entry from the repository.  See Removing files.

    `-f'
          Delete the file before removing it.  See Removing files.

    `-l'
          Local; run only in current working directory.  See
          Recursive behavior.

    `-R'
          Operate recursively (default).  See Recursive behavior.

`rlog [OPTIONS] [FILES...]'
     Print out history information for modules.  See log.

    `-b'
          Only list revisions on the default branch.  See log options.

    `-d DATES'
          Specify dates (D1<D2 for range, D for latest before).  See
          log options.

    `-h'
          Only print header.  See log options.

    `-l'
          Local; run only in current working directory.  See
          Recursive behavior.

    `-N'
          Do not list tags.  See log options.

    `-R'
          Only print name of RCS file.  See log options.

    `-rREVS'
          Only list revisions REVS.  See log options.

    `-s STATES'
          Only list revisions with specified states.  See log options.

    `-t'
          Only print header and descriptive text.  See log options.

    `-wLOGINS'
          Only list revisions checked in by specified logins.  See
          log options.

`rtag [OPTIONS] TAG MODULES...'
     Add a symbolic tag to a module.  See Revisions and
     Branching and merging.

    `-a'
          Clear tag from removed files that would not otherwise be
          tagged.  See Tagging add/remove.

    `-b'
          Create a branch named TAG.  See Branching and merging.

    `-B'
          Used in conjuntion with -F or -d, enables movement and
          deletion of branch tags.  Use with extreme caution.

    `-D DATE'
          Tag revisions as of DATE.  See Tagging by date/tag.

    `-d'
          Delete TAG.  See Modifying tags.

    `-F'
          Move TAG if it already exists.  See Modifying tags.

    `-f'
          Force a head revision match if tag/date not found.  See
          Tagging by date/tag.

    `-l'
          Local; run only in current working directory.  See
          Recursive behavior.

    `-n'
          No execution of tag program.  See Common options.

    `-R'
          Operate recursively (default).  See Recursive behavior.

    `-r REV'
          Tag existing tag REV.  See Tagging by date/tag.

`server'
     Rsh server.  See Connecting via rsh.

`status [OPTIONS] FILES...'
     Display status information in a working directory.  See File status.

    `-l'
          Local; run only in current working directory.  See
          Recursive behavior.

    `-R'
          Operate recursively (default).  See Recursive behavior.

    `-v'
          Include tag information for file.  See Tags.

`tag [OPTIONS] TAG [FILES...]'
     Add a symbolic tag to checked out version of files.  See
     Revisions and Branching and merging.

    `-b'
          Create a branch named TAG.  See Branching and merging.

    `-c'
          Check that working files are unmodified.  See Tagging the working directory.

    `-D DATE'
          Tag revisions as of DATE.  See Tagging by date/tag.

    `-d'
          Delete TAG.  See Modifying tags.

    `-F'
          Move TAG if it already exists.  See Modifying tags.

    `-f'
          Force a head revision match if tag/date not found.  See
          Tagging by date/tag.

    `-l'
          Local; run only in current working directory.  See
          Recursive behavior.

    `-R'
          Operate recursively (default).  See Recursive behavior.

    `-r REV'
          Tag existing tag REV.  See Tagging by date/tag.

`unedit [OPTIONS] [FILES...]'
     Undo an edit command.  See Editing files.

    `-l'
          Local; run only in current working directory.  See
          Recursive behavior.

    `-R'
          Operate recursively (default).  See Recursive behavior.

`update [OPTIONS] [FILES...]'
     Bring work tree in sync with repository.  See update.

    `-A'
          Reset any sticky tags/date/options.  See Sticky tags
          and Keyword substitution.

    `-C'
          Overwrite locally modified files with clean copies from the
          repository (the modified file is saved in `.#FILE.REVISION',
          however).

    `-D DATE'
          Check out revisions as of DATE (is sticky).  See Common options.

    `-d'
          Create directories.  See update options.

    `-f'
          Use head revision if tag/date not found.  See Common options.

    `-I IGN'
          More files to ignore (! to reset).  See import options.

    `-j REV'
          Merge in changes.  See update options.

    `-k KFLAG'
          Use KFLAG keyword expansion.  See Substitution modes.

    `-l'
          Local; run only in current working directory.  See
          Recursive behavior.

    `-P'
          Prune empty directories.  See Moving directories.

    `-p'
          Check out files to standard output (avoids stickiness).  See
          update options.

    `-R'
          Operate recursively (default).  See Recursive behavior.

    `-r TAG'
          Checkout revision TAG (is sticky).  See Common options.

    `-W SPEC'
          More wrappers.  See import options.

`version'
     Display the version of CVS being used.  If the repository is
     remote, display both the client and server versions.

`watch [on|off|add|remove] [OPTIONS] [FILES...]'
     on/off: turn on/off read-only checkouts of files.  See
     Setting a watch.

     add/remove: add or remove notification on actions.  See
     Getting Notified.

    `-a ACTIONS'
          Specify actions for temporary watch, where ACTIONS is `edit',
          `unedit', `commit', `all', or `none'.  See Editing files.

    `-l'
          Local; run only in current working directory.  See
          Recursive behavior.

    `-R'
          Operate recursively (default).  See Recursive behavior.

`watchers [OPTIONS] [FILES...]'
     See who is watching a file.  See Watch information.

    `-l'
          Local; run only in current working directory.  See
          Recursive behavior.

    `-R'
          Operate recursively (default).  See Recursive behavior.

Reference manual for Administrative files
*****************************************

   Inside the repository, in the directory `$CVSROOT/CVSROOT', there
are a number of supportive files for CVS.  You can use CVS in a limited
fashion without any of them, but if they are set up properly they can
help make life easier.  For a discussion of how to edit them, see
Intro administrative files.

   The most important of these files is the `modules' file, which
defines the modules inside the repository.

The modules file
================

   The `modules' file records your definitions of names for collections
of source code.  CVS will use these definitions if you use CVS to
update the modules file (use normal commands like `add', `commit', etc).

   The `modules' file may contain blank lines and comments (lines
beginning with `#') as well as module definitions.  Long lines can be
continued on the next line by specifying a backslash (`\') as the last
character on the line.

   There are three basic types of modules: alias modules, regular
modules, and ampersand modules.  The difference between them is the way
that they map files in the repository to files in the working
directory.  In all of the following examples, the top-level repository
contains a directory called `first-dir', which contains two files,
`file1' and `file2', and a directory `sdir'.  `first-dir/sdir' contains
a file `sfile'.

Alias modules
-------------

   Alias modules are the simplest kind of module:

`MNAME -a ALIASES...'
     This represents the simplest way of defining a module MNAME.  The
     `-a' flags the definition as a simple alias: CVS will treat any
     use of MNAME (as a command argument) as if the list of names
     ALIASES had been specified instead.  ALIASES may contain either
     other module names or paths.  When you use paths in aliases,
     `checkout' creates all intermediate directories in the working
     directory, just as if the path had been specified explicitly in
     the CVS arguments.

   For example, if the modules file contains:

     amodule -a first-dir

then the following two commands are equivalent:

     $ cvs co amodule
     $ cvs co first-dir

and they each would provide output such as:

     cvs checkout: Updating first-dir
     U first-dir/file1
     U first-dir/file2
     cvs checkout: Updating first-dir/sdir
     U first-dir/sdir/sfile

Regular modules
---------------

`MNAME [ options ] DIR [ FILES... ]'
     In the simplest case, this form of module definition reduces to
     `MNAME DIR'.  This defines all the files in directory DIR as
     module mname.  DIR is a relative path (from `$CVSROOT') to a
     directory of source in the source repository.  In this case, on
     checkout, a single directory called MNAME is created as a working
     directory; no intermediate directory levels are used by default,
     even if DIR was a path involving several directory levels.

   For example, if a module is defined by:

     regmodule first-dir

then regmodule will contain the files from first-dir:

     $ cvs co regmodule
     cvs checkout: Updating regmodule
     U regmodule/file1
     U regmodule/file2
     cvs checkout: Updating regmodule/sdir
     U regmodule/sdir/sfile
     $

   By explicitly specifying files in the module definition after DIR,
you can select particular files from directory DIR.  Here is an example:

     regfiles first-dir/sdir sfile

With this definition, getting the regfiles module will create a single
working directory `regfiles' containing the file listed, which comes
from a directory deeper in the CVS source repository:

     $ cvs co regfiles
     U regfiles/sfile
     $

Ampersand modules
-----------------

   A module definition can refer to other modules by including
`&MODULE' in its definition.
     MNAME [ options ] &MODULE...

   Then getting the module creates a subdirectory for each such module,
in the directory containing the module.  For example, if modules
contains

     ampermod &first-dir

then a checkout will create an `ampermod' directory which contains a
directory called `first-dir', which in turns contains all the
directories and files which live there.  For example, the command

     $ cvs co ampermod

will create the following files:

     ampermod/first-dir/file1
     ampermod/first-dir/file2
     ampermod/first-dir/sdir/sfile

   There is one quirk/bug: the messages that CVS prints omit the
`ampermod', and thus do not correctly display the location to which it
is checking out the files:

     $ cvs co ampermod
     cvs checkout: Updating first-dir
     U first-dir/file1
     U first-dir/file2
     cvs checkout: Updating first-dir/sdir
     U first-dir/sdir/sfile
     $

   Do not rely on this buggy behavior; it may get fixed in a future
release of CVS.

Excluding directories
---------------------

   An alias module may exclude particular directories from other
modules by using an exclamation mark (`!') before the name of each
directory to be excluded.

   For example, if the modules file contains:

     exmodule -a !first-dir/sdir first-dir

then checking out the module `exmodule' will check out everything in
`first-dir' except any files in the subdirectory `first-dir/sdir'.

Module options
--------------

   Either regular modules or ampersand modules can contain options,
which supply additional information concerning the module.

`-d NAME'
     Name the working directory something other than the module name.

`-e PROG'
     Specify a program PROG to run whenever files in a module are
     exported.  PROG runs with a single argument, the module name.

`-i PROG'
     Specify a program PROG to run whenever files in a module are
     committed.  PROG runs with a single argument, the full pathname of
     the affected directory in a source repository.  The `commitinfo',
     `loginfo', and `verifymsg' files provide other ways to call a
     program on commit.

`-o PROG'
     Specify a program PROG to run whenever files in a module are
     checked out.  PROG runs with a single argument, the module name.

`-s STATUS'
     Assign a status to the module.  When the module file is printed
     with `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.

`-t PROG'
     Specify a program PROG to run whenever files in a module are
     tagged with `rtag'.  PROG runs with two arguments: the module name
     and the symbolic tag specified to `rtag'.  It is not run when
     `tag' is executed.  Generally you will find that taginfo is a
     better solution (see user-defined logging).

`-u PROG'
     Specify a program PROG to run whenever `cvs update' is executed
     from the top-level directory of the checked-out module.  PROG runs
     with a single argument, the full path to the source repository for
     this module.

   You should also see Module program options about how the
"program options" programs are run.

How the modules file "program options" programs are run
-------------------------------------------------------

For checkout, rtag, and export, the program is server-based, and as
such the following applies:-

   If using remote access methods (pserver, ext, etc.), CVS will
execute this program on the server from a temporary directory. The path
is searched for this program.

   If using "local access" (on a local or remote NFS file system, i.e.
repository set just to a path), the program will be executed from the
newly checked-out tree, if found there, or alternatively searched for
in the path if not.

The commit and update programs are locally-based, and are run as
follows:-

   The program is always run locally. One must re-checkout the tree one
is using if these options are updated in the modules administrative
file. The file CVS/Checkin.prog contains the value of the option `-i'
set in the modules file, and similarly for the file CVS/Update.prog and
`-u'. The program is always executed from the top level of the
checked-out copy on the client. Again, the program is first searched
for in the checked-out copy and then using the path.

   The programs are all run after the operation has effectively
completed.

The cvswrappers file
====================

   Wrappers refers to a CVS feature which lets you control certain
settings based on the name of the file which is being operated on.  The
settings are `-k' for binary files, and `-m' for nonmergeable text
files.

   The `-m' option specifies the merge methodology that should be used
when a non-binary file is updated.  `MERGE' means the usual CVS
behavior: try to merge the files.  `COPY' means that `cvs update' will
refuse to merge files, as it also does for files specified as binary
with `-kb' (but if the file is specified as binary, there is no need to
specify `-m 'COPY'').  CVS will provide the user with the two versions
of the files, and require the user using mechanisms outside CVS, to
insert any necessary changes.  *WARNING*: do not use `COPY' with CVS
1.9 or earlier-such versions of CVS will copy one version of your file
over the other, wiping out the previous contents.  The `-m' wrapper
option only affects behavior when merging is done on update; it does
not affect how files are stored.  See Binary files, for more on
binary files.

   The basic format of the file `cvswrappers' is:

     wildcard     [option value][option value]...

     where option is one of
     -m           update methodology      value: MERGE or COPY
     -k           keyword expansion       value: expansion mode

     and value is a single-quote delimited value.

   For example, the following command imports a directory, treating
files whose name ends in `.exe' as binary:

     cvs import -I ! -W "*.exe -k 'b'" first-dir vendortag reltag

The commit support files
========================

   The `-i' flag in the `modules' file can be used to run a certain
program whenever files are committed (see 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.

`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.

`verifymsg'
     The specified program is used to evaluate the log message, and
     possibly verify that it contains all required fields.  This is
     most useful in combination with the `rcsinfo' file, which can hold
     a log message template (see rcsinfo).

`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 `rcsinfo' file, which can hold
     a log message template (see rcsinfo).  (obsolete)

`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...  Your
     imagination is the limit!

The common syntax
-----------------

   The administrative files such as `commitinfo', `loginfo', `rcsinfo',
`verifymsg', etc., 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:
   * A regular expression.  This is a basic regular expression in the
     syntax used by GNU emacs.

   * A whitespace separator--one or more spaces and/or tabs.

   * A file name or command-line template.

Blank lines are ignored.  Lines that start with the character `#' are
treated as comments.  Long lines unfortunately can _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.

Commitinfo
----------

   The `commitinfo' file defines programs to execute whenever `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 `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 directory
within the repository will be used.  If the command returns a non-zero
exit status the commit will be aborted.

   If the repository name does not match any of the regular expressions
in this file, the `DEFAULT' line is used, if it is specified.

   All occurrences of the name `ALL' appearing as a regular expression
are used in addition to the first matching regular expression or the
name `DEFAULT'.

   Note: when CVS is accessing a remote repository, `commitinfo' will
be run on the _remote_ (i.e., server) side, not the client side (see
Remote repositories).

Verifying log messages
----------------------

   Once you have entered a log message, you can evaluate that message
to check for specific content, such as a bug ID.  Use the `verifymsg'
file to specify a program that is used to verify the log message.  This
program could be a simple script that checks that the entered message
contains the required fields.

   The `verifymsg' file is often most useful together with the
`rcsinfo' file, which can be used to specify a log message template.

   Each line in the `verifymsg' 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 `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 verification script
in a directory, and then overriding it in a subdirectory.

   If the repository name does not match any of the regular expressions
in this file, the `DEFAULT' line is used, if it is specified.

   If the verification script exits with a non-zero exit status, the
commit is aborted.

   In the default configuration, CVS allows the verification script to
change the log message. This is controlled via the RereadLogAfterVerify
CVSROOT/config option.

   When `RereadLogAfterVerify=always' or `RereadLogAfterVerify=stat',
the log message will either always be reread after the verification
script is run or reread only if the log message file status has changed.

   See config, for more on CVSROOT/config options.

   It is NOT a good idea for a `verifymsg' script to interact directly
with the user in the various client/server methods. For the `pserver'
method, there is no protocol support for communicating between
`verifymsg' and the client on the remote end. For the `ext' and
`server' methods, it is possible for CVS to become confused by the
characters going along the same channel as the CVS protocol messages.
See Remote repositories, for more information on client/server
setups.  In addition, at the time the `verifymsg' script runs, the CVS
server has locks in place in the repository.  If control is returned to
the user here then other users may be stuck waiting for access to the
repository.

   This option can be useful if you find yourself using an rcstemplate
that needs to be modified to remove empty elements or to fill in
default values.  It can also be useful if the rcstemplate has changed
in the repository and the CVS/Template was not updated, but is able to
be adapted to the new format by the verification script that is run by
`verifymsg'.

   An example of an update might be to change all occurrences of
'BugId:' to be 'DefectId:' (which can be useful if the rcstemplate has
recently been changed and there are still checked-out user trees with
cached copies in the CVS/Template file of the older version).

   Another example of an update might be to delete a line that contains
'BugID: none' from the log message after validation of that value as
being allowed is made.

   The following is a little silly example of a `verifymsg' file,
together with the corresponding `rcsinfo' file, the log message
template and an verification  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 `/usr/cvssupport/tc.template'.

     BugId:

   The script `/usr/cvssupport/bugid.verify' is used to evaluate the
log message.

     #!/bin/sh
     #
     #       bugid.verify filename
     #
     #  Verify that the log message contains a valid bugid
     #  on the first line.
     #
     if head -1 < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then
         exit 0
     elif head -1 < $1 | grep '^BugId:[ ]*none$' > /dev/null; then
         # It is okay to allow commits with 'BugId: none',
         # but do not put that text into the real log message.
         grep -v '^BugId:[ ]*none$' > $1.rewrite
         mv $1.rewrite $1
         exit 0
     else
         echo "No BugId found."
         exit 1
     fi

   The `verifymsg' file contains this line:

     ^tc     /usr/cvssupport/bugid.verify

   The `rcsinfo' file contains this line:

     ^tc     /usr/cvssupport/tc.template

   The `config' file contains this line:

     RereadLogAfterVerify=always