Direct connection with Kerberos
-------------------------------

   The easiest way to use Kerberos is to use the Kerberos `rsh', as
described in Connecting via rsh.  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 TCP connection, authenticating with Kerberos.

   This section concerns the Kerberos network security system, version
4.  Kerberos version 5 is supported via the GSSAPI generic network
security interface, as described in the previous section.

   To do this, CVS needs to be compiled with Kerberos support; when
configuring CVS it tries to detect whether Kerberos is present or you
can use the `--with-krb4' flag to configure.

   The data transmitted is _not_ encrypted by default.  Encryption
support must be compiled into both the client and server; use the
`--enable-encryption' configure option to turn it on.  You must then
use the `-x' global option to request encryption.

   The CVS client will attempt to connect to port 1999 by default.

   When you want to use CVS, get a ticket in the usual way (generally
`kinit'); it must be a ticket which allows you to log into the server
machine.  Then you are ready to go:

     cvs -d :kserver:faun.example.org:/usr/local/cvsroot checkout foo

   Previous versions of CVS would fall back to a connection via rsh;
this version will not do so.

Connecting with fork
--------------------

   This access method allows you to connect to a repository on your
local disk via the remote protocol.  In other words it does pretty much
the same thing as `:local:', but various quirks, bugs and the like are
those of the remote CVS rather than the local CVS.

   For day-to-day operations you might prefer either `:local:' or
`:fork:', depending on your preferences.  Of course `:fork:' comes in
particularly handy in testing or debugging `cvs' and the remote
protocol.  Specifically, we avoid all of the network-related
setup/configuration, timeouts, and authentication inherent in the other
remote access methods but still create a connection which uses the
remote protocol.

   To connect using the `fork' method, use `:fork:' and the pathname to
your local repository.  For example:

     cvs -d :fork:/usr/local/cvsroot checkout foo

   As with `:ext:', the server is called `cvs' by default, or the value
of the `CVS_SERVER' environment variable.

Distributing load across several CVS servers
--------------------------------------------

   CVS can be configured to distribute usage across several CVS
servers.  This is accomplished by means of one or more "write proxies",
or "secondary servers", for a single "primary server".

   When a CVS client accesses a secondary server and only sends read
requests, then the secondary server handles the entire request.  If the
client sends any write requests, however, the secondary server asks the
client to redirect its write request to the primary server, if the
client supports redirect requests, and otherwise becomes a transparent
proxy for the primary server, which actually handles the write request.

   In this manner, any number of read-only secondary servers may be
configured as write proxies for the primary server, effectively
distributing the load from all read operations between the secondary
servers and restricting the load on the primary server to write
operations and pushing changes to the secondaries.

   Primary servers will not automatically push changes to secondaries.
This must be configured via `loginfo', `postadmin', `posttag', &
`postwatch' scripts (see Trigger Scripts) like the following:

     ALL	rsync -gopr -essh ./ secondary:/cvsroot/%p &

   You would probably actually want to lock directories for write on
the secondary and for read on the primary before running the `rsync' in
the above example, but describing such a setup is beyond the scope of
this document.

   A secondary advantage of a write proxy setup is that users pointing
at the secondary server can still execute fast read operations while on
a network that connects to the primary over a slow link or even one
where the link to the primary is periodically broken.  Only write
operations will require the network link to the primary.

   To configure write proxies, the primary must be specified with the
`PrimaryServer' option in `CVSROOT/config' (see config).  For the
transparent proxy mode to work, all secondary servers must also be
running the same version of the CVS server, or at least one that
provides the same list of supported requests to the client as the
primary server.  This is not necessary for redirection.

   Once a primary server is configured, secondary servers may be
configured by:

  1. Duplicating the primary repository at the new location.

  2. Setting up the `loginfo', `postadmin', `posttag', and `postwatch'
     files on the primary to propagate writes to the new secondary.

  3. Configure remote access to the secondary(ies) as you would
     configure access to any other CVS server (see Remote repositories).

  4. Ensuring that `--allow-root=SECONDARY-CVSROOT' is passed to *all*
     incovations of the secondary server if the path to the CVS
     repository directory is different on the two servers and you wish
     to support clients that do not handle the `Redirect' resopnse (CVS
     1.12.9 and earlier clients do not handle the `Redirect' response).

     Please note, again, that writethrough proxy suport requires
     `--allow-root=SECONDARY-CVSROOT' to be specified for *all*
     incovations of the secondary server, not just `pserver'
     invocations.  This may require a wrapper script for the CVS
     executable on your server machine.

Read-only repository access
===========================

   It is possible to grant read-only repository access to people using
the password-authenticated server (see Password authenticated).
(The other access methods do not have explicit support for read-only
users because those methods all assume login access to the repository
machine anyway, and therefore the user can do whatever local file
permissions allow her to do.)

   A user who has read-only access can do only those CVS operations
which do not modify the repository, except for certain "administrative"
files (such as lock files and the history file).  It may be desirable
to use this feature in conjunction with user-aliasing (see Password authentication server).

   Unlike with previous versions of CVS, read-only users should be able
merely to read the repository, and not to execute programs on the
server or otherwise gain unexpected levels of access.  Or to be more
accurate, the _known_ holes have been plugged.  Because this feature is
new and has not received a comprehensive security audit, you should use
whatever level of caution seems warranted given your attitude concerning
security.

   There are two ways to specify read-only access for a user: by
inclusion, and by exclusion.

   "Inclusion" means listing that user specifically in the
`$CVSROOT/CVSROOT/readers' file, which is simply a newline-separated
list of users.  Here is a sample `readers' file:

     melissa
     splotnik
     jrandom

(Don't forget the newline after the last user.)

   "Exclusion" means explicitly listing everyone who has _write_
access--if the file

     $CVSROOT/CVSROOT/writers

exists, then only those users listed in it have write access, and
everyone else has read-only access (of course, even the read-only users
still need to be listed in the CVS `passwd' file).  The `writers' file
has the same format as the `readers' file.

   Note: if your CVS `passwd' file maps cvs users onto system users
(see Password authentication server), make sure you deny or grant
read-only access using the _cvs_ usernames, not the system usernames.
That is, the `readers' and `writers' files contain cvs usernames, which
may or may not be the same as system usernames.

   Here is a complete description of the server's behavior in deciding
whether to grant read-only or read-write access:

   If `readers' exists, and this user is listed in it, then she gets
read-only access.  Or if `writers' exists, and this user is NOT listed
in it, then she also gets read-only access (this is true even if
`readers' exists but she is not listed there).  Otherwise, she gets
full read-write access.

   Of course there is a conflict if the user is listed in both files.
This is resolved in the more conservative way, it being better to
protect the repository too much than too little: such a user gets
read-only access.

Temporary directories for the server
====================================

   While running, the CVS server creates temporary directories.  They
are named

     cvs-servPID

where PID is the process identification number of the server.  They are
located in the directory specified by the `-T' global option (see
Global options), the `TMPDIR' environment variable (see Environment variables),
or, failing that, `/tmp'.

   In most cases the server will remove the temporary directory when it
is done, whether it finishes normally or abnormally.  However, there
are a few cases in which the server does not or cannot remove the
temporary directory, for example:

   * If the server aborts due to an internal server error, it may
     preserve the directory to aid in debugging

   * If the server is killed in a way that it has no way of cleaning up
     (most notably, `kill -KILL' on unix).

   * If the system shuts down without an orderly shutdown, which tells
     the server to clean up.

   In cases such as this, you will need to manually remove the
`cvs-servPID' directories.  As long as there is no server running with
process identification number PID, it is safe to do so.

Starting a project with CVS
***************************

   Because renaming files and moving them between directories is
somewhat inconvenient, the first thing you do when you start a new
project should be to think through your file organization.  It is not
impossible to rename or move files, but it does increase the potential
for confusion and CVS does have some quirks particularly in the area of
renaming directories.  See Moving files.

   What to do next depends on the situation at hand.

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.

Creating a directory tree from a number of files
------------------------------------------------

   When you begin using CVS, you will probably already have several
projects that can be put under CVS control.  In these cases the easiest
way is to use the `import' command.  An example is probably the easiest
way to explain how to use it.  If the files you want to install in CVS
reside in `WDIR', and you want them to appear in the repository as
`$CVSROOT/yoyodyne/RDIR', you can do this:

     $ cd WDIR
     $ cvs import -m "Imported sources" yoyodyne/RDIR yoyo start

   Unless you supply a log message with the `-m' flag, CVS starts an
editor and prompts for a message.  The string `yoyo' is a "vendor tag",
and `start' is a "release tag".  They may fill no purpose in this
context, but since CVS requires them they must be present.  See
Tracking sources, for more information about them.

   You can now verify that it worked, and remove your original source
directory.

     $ cd ..
     $ cvs checkout yoyodyne/RDIR       # Explanation below
     $ diff -r WDIR yoyodyne/RDIR
     $ rm -r WDIR

Erasing the original sources is a good idea, to make sure that you do
not accidentally edit them in WDIR, bypassing CVS.  Of course, it would
be wise to make sure that you have a backup of the sources before you
remove them.

   The `checkout' command can either take a module name as argument (as
it has done in all previous examples) or a path name relative to
`$CVSROOT', as it did in the example above.

   It is a good idea to check that the permissions CVS sets on the
directories inside `$CVSROOT' are reasonable, and that they belong to
the proper groups.  See File permissions.

   If some of the files you want to import are binary, you may want to
use the wrappers features to specify which files are binary and which
are not.  See Wrappers.

Creating Files From Other Version Control Systems
-------------------------------------------------

   If you have a project which you are maintaining with another version
control system, such as RCS, you may wish to put the files from that
project into CVS, and preserve the revision history of the files.

From RCS
     If you have been using RCS, find the RCS files--usually a file
     named `foo.c' will have its RCS file in `RCS/foo.c,v' (but it
     could be other places; consult the RCS documentation for details).
     Then create the appropriate directories in CVS if they do not
     already exist.  Then copy the files into the appropriate
     directories in the CVS repository (the name in the repository must
     be the name of the source file with `,v' added; the files go
     directly in the appropriate directory of the repository, not in an
     `RCS' subdirectory).  This is one of the few times when it is a
     good idea to access the CVS repository directly, rather than using
     CVS commands.  Then you are ready to check out a new working
     directory.

     The RCS file should not be locked when you move it into CVS; if it
     is, CVS will have trouble letting you operate on it.

From another version control system
     Many version control systems have the ability to export RCS files
     in the standard format.  If yours does, export the RCS files and
     then follow the above instructions.

     Failing that, probably your best bet is to write a script that
     will check out the files one revision at a time using the command
     line interface to the other system, and then check the revisions
     into CVS.  The `sccs2rcs' script mentioned below may be a useful
     example to follow.

From SCCS
     There is a script in the `contrib' directory of the CVS source
     distribution called `sccs2rcs' which converts SCCS files to RCS
     files.  Note: you must run it on a machine which has both SCCS and
     RCS installed, and like everything else in contrib it is
     unsupported (your mileage may vary).

From PVCS
     There is a script in the `contrib' directory of the CVS source
     distribution called `pvcs_to_rcs' which converts PVCS archives to
     RCS files.  You must run it on a machine which has both PVCS and
     RCS installed, and like everything else in contrib it is
     unsupported (your mileage may vary).  See the comments in the
     script for details.

Creating a directory tree from scratch
--------------------------------------

   For a new project, the easiest thing to do is probably to create an
empty directory structure, like this:

     $ mkdir tc
     $ mkdir tc/man
     $ mkdir tc/testing

   After that, you use the `import' command to create the corresponding
(empty) directory structure inside the repository:

     $ cd tc
     $ cvs import -m "Created directory structure" yoyodyne/DIR yoyo start

   This will add yoyodyne/DIR as a directory under `$CVSROOT'.

   Then, use `add' to add files (and new directories) as they appear.

   Check that the permissions CVS sets on the directories inside
`$CVSROOT' are reasonable.

Defining the module
===================

   The next step is to define the module in the `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.

  1. Get a working copy of the modules file.

          $ cvs checkout CVSROOT/modules
          $ cd CVSROOT

  2. Edit the file and insert a line that defines the module.  See
     Intro administrative files, for an introduction.  See
     modules, for a full description of the modules file.  You can
     use the following line to define the module `tc':

          tc   yoyodyne/tc

  3. Commit your changes to the modules file.

          $ cvs commit -m "Added the tc module." modules

  4. Release the modules module.

          $ cd ..
          $ cvs release -d CVSROOT

Revisions
*********

   For many uses of CVS, one doesn't need to worry too much about
revision numbers; CVS assigns numbers such as `1.1', `1.2', and so on,
and that is all one needs to know.  However, some people prefer to have
more knowledge and control concerning how CVS assigns revision numbers.

   If one wants to keep track of a set of revisions involving more than
one file, such as which revisions went into a particular release, one
uses a "tag", which is a symbolic revision which can be assigned to a
numeric revision in each file.

Revision numbers
================

   Each version of a file has a unique "revision number".  Revision
numbers look like `1.1', `1.2', `1.3.2.2' or even `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.

            +-----+    +-----+    +-----+    +-----+    +-----+
            ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
            +-----+    +-----+    +-----+    +-----+    +-----+

   It is also possible to end up with numbers containing more than one
period, for example `1.3.2.2'.  Such revisions represent revisions on
branches (see Branching and merging); such revision numbers are
explained in detail in Branches and revisions.

Versions, revisions and releases
================================

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

   Versions in the first sense are called "revisions" in this document,
and versions in the second sense are called "releases".  To avoid
confusion, the word "version" is almost never used in this document.

Assigning revisions
===================

   By default, CVS will assign numeric revisions by leaving the first
number the same and incrementing the second number.  For example,
`1.1', `1.2', `1.3', etc.

   When adding a new file, the second number will always be one and the
first number will equal the highest first number of any file in that
directory.  For example, the current directory contains files whose
highest numbered revisions are `1.7', `3.1', and `4.12', then an added
file will be given the numeric revision `4.1'.  (When using
client/server CVS, only files that are actually sent to the server are
considered.)

   Normally there is no reason to care about the revision numbers--it
is easier to treat them as internal numbers that CVS maintains, and tags
provide a better way to distinguish between things like release 1
versus release 2 of your product (see Tags).  However, if you want
to set the numeric revisions, the `-r' option to `cvs commit' can do
that.  The `-r' option implies the `-f' option, in the sense that it
causes the files to be committed even if they are not modified.

   For example, to bring all your files up to revision 3.0 (including
those that haven't changed), you might invoke:

     $ cvs commit -r 3.0

   Note that the number you specify with `-r' must be larger than any
existing revision number.  That is, if revision 3.0 exists, you cannot
`cvs commit -r 1.3'.  If you want to maintain several releases in
parallel, you need to use a branch (see Branching and merging).

Tags-Symbolic revisions
=======================

   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 CVS the revision numbers might
change several times between two releases.  As an example, some of the
source files that make up RCS 5.6 have the following revision numbers:

     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

   You can use the `tag' command to give a symbolic name to a certain
revision of a file.  You can use the `-v' flag to the `status' command
to see all tags that a file has, and which revision numbers they
represent.  Tag names must start with an uppercase or lowercase letter
and can contain uppercase and lowercase letters, digits, `-', and `_'.
The two tag names `BASE' and `HEAD' are reserved for use by CVS.  It is
expected that future names which are special to CVS will be specially
named, for example by starting with `.', rather than being named
analogously to `BASE' and `HEAD', to avoid conflicts with actual tag
names.

   You'll want to choose some convention for naming tags, based on
information such as the name of the program and the version number of
the release.  For example, one might take the name of the program,
immediately followed by the version number with `.' changed to `-', so
that CVS 1.9 would be tagged with the name `cvs1-9'.  If you choose a
consistent convention, then you won't constantly be guessing whether a
tag is `cvs-1-9' or `cvs1_9' or what.  You might even want to consider
enforcing your convention in the `taginfo' file (see taginfo).

   The following example shows how you can add a tag to a file.  The
commands must be issued inside your working directory.  That is, you
should issue the command in the directory where `backend.c' resides.

     $ cvs tag rel-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     /u/cvsroot/yoyodyne/tc/backend.c,v
         Sticky Tag:         (none)
         Sticky Date:        (none)
         Sticky Options:     (none)

         Existing Tags:
             rel-0-4                     (revision: 1.4)

   For a complete summary of the syntax of `cvs tag', including the
various options, see Invoking CVS.

   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.

     $ cvs tag rel-1-0 .
     cvs tag: Tagging .
     T Makefile
     T backend.c
     T driver.c
     T frontend.c
     T parser.c

(When you give 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.  See Recursive behavior.)

   The `checkout' command has a flag, `-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 `tc' at any time in the
future:

     $ cvs checkout -r rel-1-0 tc

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 on any branch at any given
date.  See checkout options.  When specifying `-r' or `-D' to any
of these commands, you will need beware of sticky tags; see
Sticky tags.

   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:

             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

   At some time in the past, the `*' 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:

             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

Specifying what to tag from the working directory
=================================================

   The example in the previous section demonstrates one of the most
common ways to choose which revisions to tag.  Namely, running the `cvs
tag' command without arguments causes CVS to select the revisions which
are checked out in the current working directory.  For example, if the
copy of `backend.c' in working directory was checked out from revision
1.4, then CVS will tag revision 1.4.  Note that the tag is applied
immediately to revision 1.4 in the repository; tagging is not like
modifying a file, or other operations in which one first modifies the
working directory and then runs `cvs commit' to transfer that
modification to the repository.

   One potentially surprising aspect of the fact that `cvs tag'
operates on the repository is that you are tagging the checked-in
revisions, which may differ from locally modified files in your working
directory.  If you want to avoid doing this by mistake, specify the
`-c' option to `cvs tag'.  If there are any locally modified files, CVS
will abort with an error before it tags any files:

     $ cvs tag -c rel-0-4
     cvs tag: backend.c is locally modified
     cvs [tag aborted]: correct the above errors first!

Specifying what to tag by date or revision
==========================================

   The `cvs rtag' command tags the repository as of a certain date or
time (or can be used to tag the latest revision).  `rtag' works
directly on the repository contents (it requires no prior checkout and
does not look for a working directory).

   The following options specify which date or revision to tag.  See
Common options, for a complete description of them.

`-D DATE'
     Tag the most recent revision no later than DATE.

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

`-r TAG[:DATE]'
     Tag the revision already tagged with TAG or, when DATE is specified
     and TAG is a branch tag, the version from the branch TAG as it
     existed on DATE.  See Common options.

   The `cvs tag' command also allows one to specify files by revision
or date, using the same `-r', `-D', and `-f' options.  However, this
feature is probably not what you want.  The reason is that `cvs tag'
chooses which files to tag based on the files that exist in the working
directory, rather than the files which existed as of the given tag/date.
Therefore, you are generally better off using `cvs rtag'.  The
exceptions might be cases like:

     cvs tag -r 1.4 stable backend.c

Deleting, moving, and renaming tags
===================================

   Normally one does not modify tags.  They exist in order to record
the history of the repository and so deleting them or changing their
meaning would, generally, not be what you want.

   However, there might be cases in which one uses a tag temporarily or
accidentally puts one in the wrong place.  Therefore, one might delete,
move, or rename a tag.

*WARNING: the commands in this section are dangerous; they permanently
discard historical information and it can be difficult or impossible to
recover from errors.  If you are a CVS administrator, you may consider
restricting these commands with the `taginfo' file (see taginfo).*

   To delete a tag, specify the `-d' option to either `cvs tag' or `cvs
rtag'.  For example:

     cvs rtag -d rel-0-4 tc

deletes the non-branch tag `rel-0-4' from the module `tc'.  In the
event that branch tags are encountered within the repository with the
given name, a warning message will be issued and the branch tag will
not be deleted.  If you are absolutely certain you know what you are
doing, the `-B' option may be specified to allow deletion of branch
tags.  In that case, any non-branch tags encountered will trigger
warnings and will not be deleted.

*WARNING: Moving branch tags is very dangerous!  If you think you need
the `-B' option, think again and ask your CVS administrator about it
(if that isn't you).  There is almost certainly another way to
accomplish what you want to accomplish.*

   When we say "move" a tag, we mean to make the same name point to
different revisions.  For example, the `stable' tag may currently point
to revision 1.4 of `backend.c' and perhaps we want to make it point to
revision 1.6.  To move a non-branch tag, specify the `-F' option to
either `cvs tag' or `cvs rtag'.  For example, the task just mentioned
might be accomplished as:

     cvs tag -r 1.6 -F stable backend.c

If any branch tags are encountered in the repository with the given
name, a warning is issued and the branch tag is not disturbed.  If you
are absolutely certain you wish to move the branch tag, the `-B' option
may be specified.  In that case, non-branch tags encountered with the
given name are ignored with a warning message.

*WARNING: Moving branch tags is very dangerous!  If you think you need
the `-B' option, think again and ask your CVS administrator about it
(if that isn't you).  There is almost certainly another way to
accomplish what you want to accomplish.*

   When we say "rename" a tag, we mean to make a different name point
to the same revisions as the old tag.  For example, one may have
misspelled the tag name and want to correct it (hopefully before others
are relying on the old spelling).  To rename a tag, first create a new
tag using the `-r' option to `cvs rtag', and then delete the old name.
(Caution: this method will not work with branch tags.)  This leaves the
new tag on exactly the same files as the old tag.  For example:

     cvs rtag -r old-name-0-4 rel-0-4 tc
     cvs rtag -d old-name-0-4 tc

Tagging and adding and removing files
=====================================

   The subject of exactly how tagging interacts with adding and
removing files is somewhat obscure; for the most part CVS will keep
track of whether files exist or not without too much fussing.  By
default, tags are applied to only files which have a revision
corresponding to what is being tagged.  Files which did not exist yet,
or which were already removed, simply omit the tag, and CVS knows to
treat the absence of a tag as meaning that the file didn't exist as of
that tag.

   However, this can lose a small amount of information.  For example,
suppose a file was added and then removed.  Then, if the tag is missing
for that file, there is no way to know whether the tag refers to the
time before the file was added, or the time after it was removed.  If
you specify the `-r' option to `cvs rtag', then CVS tags the files
which have been removed, and thereby avoids this problem.  For example,
one might specify `-r HEAD' to tag the head.

   On the subject of adding and removing files, the `cvs rtag' command
has a `-a' option which means to clear the tag from removed files that
would not otherwise be tagged.  For example, one might specify this
option in conjunction with `-F' when moving a tag.  If one moved a tag
without `-a', then the tag in the removed files might still refer to
the old revision, rather than reflecting the fact that the file had
been removed.  I don't think this is necessary if `-r' is specified, as
noted above.

Sticky tags
===========

   Sometimes a working copy's revision has extra data associated with
it, for example it might be on a branch (see Branching and merging),
or restricted to versions prior to a certain date by
`checkout -D' or `update -D'.  Because this data persists - that is, it
applies to subsequent commands in the working copy - we refer to it as
"sticky".

   Most of the time, stickiness is an obscure aspect of CVS that you
don't need to think about.  However, even if you don't want to use the
feature, you may need to know _something_ about sticky tags (for
example, how to avoid them!).

   You can use the `status' command to see if any sticky tags or dates
are set:

     $ cvs status 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 /u/cvsroot/yoyodyne/tc/driver.c,v
         Sticky Tag:         rel-1-0-patches (branch: 1.7.2)
         Sticky Date:        (none)
         Sticky Options:     (none)

   The sticky tags will remain on your working files until you delete
them with `cvs update -A'.  The `-A' option merges local changes into
the version of the file from the head of the trunk, removing any sticky
tags, dates, or options.  See update for more on the operation
of `cvs update'.

   The most common use of sticky tags is to identify which branch one
is working on, as described in Accessing branches.  However,
non-branch sticky tags have uses as well.  For example, suppose that
you want to avoid updating your working directory, to isolate yourself
from possibly destabilizing changes other people are making.  You can,
of course, just refrain from running `cvs update'.  But if you want to
avoid updating only a portion of a larger tree, then sticky tags can
help.  If you check out a certain revision (such as 1.4) it will become
sticky.  Subsequent `cvs update' commands will not retrieve the latest
revision until you reset the tag with `cvs update -A'.  Likewise, use
of the `-D' option to `update' or `checkout' sets a "sticky date",
which, similarly, causes that date to be used for future retrievals.

   People often want to retrieve an old version of a file without
setting a sticky tag.  This can be done with the `-p' option to
`checkout' or `update', which sends the contents of the file to
standard output.  For 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
     ***************
     $

   However, this isn't the easiest way, if you are asking how to undo a
previous checkin (in this example, put `file1' back to the way it was
as of revision 1.1).  In that case you are better off using the `-j'
option to `update'; for further discussion see Merging two revisions.

Branching and merging
*********************

   CVS allows you to isolate changes onto a separate line of
development, known as a "branch".  When you change files on a branch,
those changes do not appear on the main trunk or other branches.

   Later you can move changes from one branch to another branch (or the
main trunk) by "merging".  Merging involves first running `cvs update
-j', to merge the changes into the working directory.  You can then
commit that revision, and thus effectively copy the changes onto
another branch.

What branches are good for
==========================

   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 (see 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 bug fix release based on the
newest sources.

   The thing to do in a situation like this is to create a "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 elect to
either incorporate them on the main trunk, or leave them on the branch.

Creating a branch
=================

   You can create a branch with `tag -b'; for example, assuming you're
in a working copy:

     $ cvs tag -b rel-1-0-patches

   This splits off a branch based on the current revisions in the
working copy, assigning that branch the name `rel-1-0-patches'.

   It is important to understand that branches get created in the
repository, not in the working copy.  Creating a branch based on
current revisions, as the above example does, will _not_ automatically
switch the working copy to be on the new branch.  For information on how
to do that, see Accessing branches.

   You can also create a branch without reference to any working copy,
by using `rtag':

     $ cvs rtag -b -r rel-1-0 rel-1-0-patches tc

   `-r rel-1-0' says that this branch should be rooted at the revision
that corresponds to the tag `rel-1-0'.  It need not be the most recent
revision - it's often useful to split a branch off an old revision (for
example, when fixing a bug in a past release otherwise known to be
stable).

   As with `tag', the `-b' flag tells `rtag' to create a branch (rather
than just a symbolic revision name).  Note that the numeric revision
number that matches `rel-1-0' will probably be different from file to
file.

   So, the full effect of the command is to create a new branch - named
`rel-1-0-patches' - in module `tc', rooted in the revision tree at the
point tagged by `rel-1-0'.

Accessing branches
==================

   You can retrieve a branch in one of two ways: by checking it out
fresh from the repository, or by switching an existing working copy
over to the branch.

   To check out a branch from the repository, invoke `checkout' with
the `-r' flag, followed by the tag name of the branch (see Creating a branch):

     $ cvs checkout -r rel-1-0-patches tc

   Or, if you already have a working copy, you can switch it to a given
branch with `update -r':

     $ cvs update -r rel-1-0-patches tc

or equivalently:

     $ cd tc
     $ cvs update -r rel-1-0-patches

   It does not matter if the working copy was originally on the main
trunk or on some other branch - the above command will switch it to the
named branch.  And similarly to a regular `update' command, `update -r'
merges any changes you have made, notifying you of conflicts where they
occur.

   Once you have a working copy tied to a particular branch, it remains
there until you tell it otherwise.  This means that changes checked in
from the working copy will add new revisions on that branch, while
leaving the main trunk and other branches unaffected.

   To find out what branch a working copy is on, you can use the
`status' command.  In its output, look for the field named `Sticky tag'
(see Sticky tags) - that's CVS's way of telling you the branch, if
any, of the current working files:

     $ 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     /u/cvsroot/yoyodyne/tc/driver.c,v
         Sticky Tag:         rel-1-0-patches (branch: 1.7.2)
         Sticky Date:        (none)
         Sticky Options:     (none)

         Existing Tags:
             rel-1-0-patches             (branch: 1.7.2)
             rel-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     /u/cvsroot/yoyodyne/tc/backend.c,v
         Sticky Tag:         rel-1-0-patches (branch: 1.4.2)
         Sticky Date:        (none)
         Sticky Options:     (none)

         Existing Tags:
             rel-1-0-patches             (branch: 1.4.2)
             rel-1-0                     (revision: 1.4)
             rel-0-4                     (revision: 1.4)

   Don't be confused by the fact that the branch numbers for each file
are different (`1.7.2' and `1.4.2' respectively).  The branch tag is the
same, `rel-1-0-patches', and the files are indeed on the same branch.
The numbers simply reflect the point in each file's revision history at
which the branch was made.  In the above example, one can deduce that
`driver.c' had been through more changes than `backend.c' before this
branch was created.

   See Branches and revisions for details about how branch
numbers are constructed.

Branches and revisions
======================

   Ordinarily, a file's revision history is a linear series of
increments (see Revision numbers):

            +-----+    +-----+    +-----+    +-----+    +-----+
            ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
            +-----+    +-----+    +-----+    +-----+    +-----+

   However, CVS is not limited to linear development.  The "revision
tree" can be split into "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 "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.

   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.

                                                           +-------------+
                                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.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 !
                         +---------+    +---------+    +---------+

   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 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 CVS (see Magic branch numbers).
The branch 1.1.1 has a special meaning.  See Tracking sources.