This is Info file cvs.info, produced by Makeinfo version 1.67 from the
input file ./cvs.texinfo.

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


File: cvs.info,  Node: Setting a watch,  Next: Getting Notified,  Up: Watches

Telling CVS to watch certain files
----------------------------------

   To enable the watch features, you first specify that certain files
are to be watched.

 - Command: cvs watch on [`-lR'] FILES ...
     Specify that developers should run `cvs edit' before editing
     FILES.  CVS will create working copies of FILES read-only, to
     remind developers to run the `cvs edit' command before working on
     them.

     If 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
     `-l' option is given.  The `-R' option can be used to force
     recursion if the `-l' option is set in `~/.cvsrc' (*note
     ~/.cvsrc::.).

     If FILES is omitted, it defaults to the current directory.


 - Command: cvs watch off [`-lR'] FILES ...
     Do not provide notification about work on FILES.  CVS will create
     working copies of FILES read-write.

     The FILES and options are processed as for `cvs watch on'.



File: cvs.info,  Node: Getting Notified,  Next: Editing files,  Prev: Setting a watch,  Up: Watches

Telling CVS to notify you
-------------------------

   You can tell CVS that you want to receive notifications about
various actions taken on a file.  You can do this without using `cvs
watch on' for the file, but generally you will want to use `cvs watch
on', so that developers use the `cvs edit' command.

 - Command: cvs watch add [`-a' ACTION] [`-lR'] FILES ...
     Add the current user to the list of people to receive notification
     of work done on FILES.

     The `-a' option specifies what kinds of events CVS should notify
     the user about.  ACTION is one of the following:

    `edit'
          Another user has applied the `cvs edit' command (described
          below) to a file.

    `unedit'
          Another user has applied the `cvs unedit' command (described
          below) or the `cvs release' command to a file, or has deleted
          the file and allowed `cvs update' to recreate it.

    `commit'
          Another user has committed changes to a file.

    `all'
          All of the above.

    `none'
          None of the above.  (This is useful with `cvs edit',
          described below.)

     The `-a' option may appear more than once, or not at all.  If
     omitted, the action defaults to `all'.

     The FILES and options are processed as for the `cvs watch'
     commands.


 - Command: cvs watch remove [`-a' ACTION] [`-lR'] FILES ...
     Remove a notification request established using `cvs watch add';
     the arguments are the same.  If the `-a' option is present, only
     watches for the specified actions are removed.


   When the conditions exist for notification, CVS calls the `notify'
administrative file.  Edit `notify' as one edits the other
administrative files (*note Intro administrative files::.).  This file
follows the usual conventions for administrative files (*note
syntax::.), where each line is a regular expression followed by a
command to execute.  The command should contain a single ocurrence of
`%s' which will be replaced by the user to notify; the rest of the
information regarding the notification will be supplied to the command
on standard input.  The standard thing to put in the `notify' file is
the single line:

     ALL mail %s -s \"CVS notification\"

   This causes users to be notified by electronic mail.

   Note that if you set this up in the straightforward way, users
receive notifications on the server machine.  One could of course write
a `notify' script which directed notifications elsewhere, but to make
this easy, CVS allows you to associate a notification address for each
user.  To do so create a file `users' in `CVSROOT' with a line for each
user in the format USER:VALUE.  Then instead of passing the name of the
user to be notified to `notify', CVS will pass the VALUE (normally an
email address on some other machine).

   CVS does not notify you for your own changes.  Currently this check
is done based on whether the user name of the person taking the action
which triggers notification matches the user name of the person getting
notification.  In fact, in general, the watches features only track one
edit by each user.  It probably would be more useful if watches tracked
each working directory separately, so this behavior might be worth
changing.


File: cvs.info,  Node: Editing files,  Next: Watch information,  Prev: Getting Notified,  Up: Watches

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 `cvs edit' command.  Some systems
call this a "checkout", but CVS uses that term for obtaining a copy of
the sources (*note Getting the source::.), an operation which those
systems call a "get" or a "fetch".

 - Command: cvs edit [OPTIONS] FILES ...
     Prepare to edit the working files FILES.  CVS makes the FILES
     read-write, and notifies users who have requested `edit'
     notification for any of FILES.

     The `cvs edit' command accepts the same OPTIONS as the `cvs watch
     add' command, and establishes a temporary watch for the user on
     FILES; CVS will remove the watch when FILES are `unedit'ed or
     `commit'ted.  If the user does not wish to receive notifications,
     she should specify `-a none'.

     The FILES and options are processed as for the `cvs watch'
     commands.


   Normally when you are done with a set of changes, you use the `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 `cvs
unedit' command.

 - Command: cvs unedit [`-lR'] FILES ...
     Abandon work on the working files FILES, and revert them to the
     repository versions on which they are based.  CVS makes those
     FILES read-only for which users have requested notification using
     `cvs watch on'.  CVS notifies users who have requested `unedit'
     notification for any of FILES.

     The FILES and options are processed as for the `cvs watch'
     commands.

     If watches are not in use, the `unedit' command probably does not
     work, and the way to revert to the repository version is to remove
     the file and then use `cvs update' to get a new copy.  The meaning
     is not precisely the same; removing and updating may also bring in
     some changes which have been made in the repository since the last
     time you updated.

   When using client/server CVS, you can use the `cvs edit' and `cvs
unedit' commands even if CVS is unable to succesfully communicate with
the server; the notifications will be sent upon the next successful CVS
command.


File: cvs.info,  Node: Watch information,  Next: Watches Compatibility,  Prev: Editing files,  Up: Watches

Information about who is watching and editing
---------------------------------------------

 - Command: cvs watchers [`-lR'] FILES ...
     List the users currently watching changes to FILES.  The report
     includes the files being watched, and the mail address of each
     watcher.

     The FILES and options are processed as for the `cvs watch'
     commands.


 - Command: cvs editors [`-lR'] FILES ...
     List the users currently working on 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 FILES and options are processed as for the `cvs watch'
     commands.



File: cvs.info,  Node: Watches Compatibility,  Prev: Watch information,  Up: Watches

Using watches with old versions of CVS
--------------------------------------

   If you use the watch features on a repository, it creates `CVS'
directories in the repository and stores the information about watches
in that directory.  If you attempt to use CVS 1.6 or earlier with the
repository, you get an error message such as the following (all on one
line):

     cvs update: cannot open CVS/Entries for reading:
     No such file or directory

   and your operation will likely be aborted.  To use the watch
features, you must upgrade all copies of CVS which use that repository
in local or server mode.  If you cannot upgrade, use the `watch off' and
`watch remove' commands to remove all watches, and that will restore
the repository to a state which CVS 1.6 can cope with.


File: cvs.info,  Node: Choosing a model,  Prev: Watches,  Up: Multiple developers

Choosing between reserved or unreserved checkouts
=================================================

   Reserved and unreserved checkouts each have pros and cons.  Let it
be said that a lot of this is a matter of opinion or what works given
different groups' working styles, but here is a brief description of
some of the issues.  There are many ways to organize a team of
developers.  CVS does not try to enforce a certain organization.  It is
a tool that can be used in several ways.

   Reserved checkouts 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.  Also, it is common for someone
to take out a lock on a file, because they are planning to edit it, but
then forget to release the lock.

   People, especially people who are familiar with reserved checkouts,
often wonder how often conflicts occur if unreserved checkouts are
used, and how difficult they are to resolve.  The experience with many
groups is that they occur rarely and usually are relatively
straightforward to resolve.

   The rarity of serious conflicts may be surprising, until one realizes
that they occur only when two developers disagree on the proper design
for a given section of code; such a disagreement suggests that the team
has not been communicating properly in the first place.  In order to
collaborate under *any* source management regimen, developers must
agree on the general design of the system; given this agreement,
overlapping changes are usually straightforward to merge.

   In some cases unreserved checkouts are clearly inappropriate.  If no
merge tool exists for the kind of file you are managing (for example
word processor files or files edited by Computer Aided Design
programs), and it is not desirable to change to a program which uses a
mergeable data format, then resolving conflicts is going to be
unpleasant enough that you generally will be better off to simply avoid
the conflicts instead, by using reserved checkouts.

   The watches features described above in *Note Watches:: can be
considered to be an intermediate model between reserved checkouts and
unreserved checkouts.  When you go to edit a file, it is possible to
find out who else is editing it.  And rather than having the system
simply forbid both people editing the file, it can tell you what the
situation is and let you figure out whether it is a problem in that
particular case or not.  Therefore, for some groups it can be
considered the best of both the reserved checkout and unreserved
checkout worlds.


File: cvs.info,  Node: Revisions and branches,  Next: Merging,  Prev: Multiple developers,  Up: Top

Revisions and branches
**********************

   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.

   Another useful feature, especially when maintaining several releases
of a software product at once, is the ability to make branches on the
revision tree.

* Menu:

* Revision numbers::            The meaning of a revision number
* Versions revisions releases::  Terminology used in this manual
* Assigning revisions::         Assigning revisions
* Tags::                        Tags-Symbolic revisions
* Branches motivation::         What branches are good for
* Creating a branch::           Creating a branch
* Sticky tags::                 Sticky tags
* Magic branch numbers::        Magic branch numbers


File: cvs.info,  Node: Revision numbers,  Next: Versions revisions releases,  Up: Revisions and branches

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

   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 (*note Magic branch
numbers::.).  The branch 1.1.1 has a special meaning.  *Note Tracking
sources::.


File: cvs.info,  Node: Versions revisions releases,  Next: Assigning revisions,  Prev: Revision numbers,  Up: Revisions and branches

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.


File: cvs.info,  Node: Assigning revisions,  Next: Tags,  Prev: Versions revisions releases,  Up: Revisions and branches

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

   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 (*note 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 (*note Revisions and branches::.).


File: cvs.info,  Node: Tags,  Next: Branches motivation,  Prev: Assigning revisions,  Up: Revisions and branches

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 (*note user-defined
logging::.).

   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 `backend.c'
resides.

     $ 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     /u/cvsroot/yoyodyne/tc/backend.c,v
         Sticky Tag:         (none)
         Sticky Date:        (none)
         Sticky Options:     (none)
     
         Existing Tags:
             release-0-4                     (revision: 1.4)

   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 release-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.  *Note 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 release-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 at any given date.  *Note
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:

             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


File: cvs.info,  Node: Branches motivation,  Next: Creating a branch,  Prev: Tags,  Up: Revisions and branches

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 (*note 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 "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.


File: cvs.info,  Node: Creating a branch,  Next: Sticky tags,  Prev: Branches motivation,  Up: Revisions and branches

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

   The `rtag' command can be used to create a branch.  The `rtag'
command is much like `tag', but it does not require that you have a
working copy of the module.  *Note rtag::.  (You can also use the `tag'
command; *note tag::.).

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

   The `-b' flag makes `rtag' create a branch (rather than just a
symbolic revision name).  `-r release-1-0' says that this branch should
be rooted at the node (in the revision tree) that corresponds to the tag
`release-1-0'.  Note that the numeric revision number that matches
`release-1-0' will probably be different from file to file.  The name
of the new branch is `release-1-0-patches', and the module affected is
`tc'.

   To fix the problem in release 1.0, you need a working copy of the
branch you just created.

     $ 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     /u/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     /u/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)

   As the output from the `status' command shows the branch number is
created by adding a digit at the tail of the revision number it is
based on.  (If `release-1-0' corresponds to revision 1.4, the branch's
revision number will be 1.4.2.  For obscure reasons CVS always gives
branches even numbers, starting at 2.  *Note Revision numbers::.).


File: cvs.info,  Node: Sticky tags,  Next: Magic branch numbers,  Prev: Creating a branch,  Up: Revisions and branches

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

   The `-r release-1-0-patches' flag that was given to `checkout' in
the previous example is "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.  *Note Merging::.

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

     $ vi driver.c   # 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 /u/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)

   The sticky tags will remain on your working files until you delete
them with `cvs update -A'.  The `-A' option retrieves the version of
the file from the head of the trunk, and forgets any sticky tags,
dates, or options.

   Sticky tags are not just for branches.  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' 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.

   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 `-p'
option to `checkout' or `update', which sends the contents of the file
to standard output.  For example, suppose you have a file named `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:

     $ 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: re-adding file file1 (in place of dead revision 1.2)
     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
     $


File: cvs.info,  Node: Magic branch numbers,  Prev: Sticky tags,  Up: Revisions and branches

Magic branch numbers
====================

   This section describes a CVS feature called "magic branches".  For
most purposes, you need not worry about magic branches; CVS handles
them for you.  However, they are visible to you in certain
circumstances, so it may be useful to have some idea of how it works.

   Externally, branch numbers consist of an odd number of dot-separated
decimal integers.  *Note Revision numbers::.  That is not the whole
truth, however.  For efficiency reasons 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).

   CVS does a pretty good job at hiding these so called magic branches,
but in a few places the hiding is incomplete:

   * The magic branch number appears in the output from `cvs log'.

   * You cannot specify a symbolic branch name to `cvs admin'.

   You can use the `admin' command to reassign a symbolic name to a
branch the way RCS expects it to be.  If `R4patches' is assigned to the
branch 1.4.2 (magic branch number 1.4.0.2) in file `numbers.c' you can
do this:

     $ cvs admin -NR4patches:1.4.2 numbers.c

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


File: cvs.info,  Node: Merging,  Next: Recursive behavior,  Prev: Revisions and branches,  Up: Top

Merging
*******

   You can include the changes made between any two revisions into your
working copy, by "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
* Merging adds and removals::   What if files are added or removed?


File: cvs.info,  Node: Merging a branch,  Next: Merging more than once,  Up: Merging

Merging an entire branch
========================

   You can merge changes made on a branch into your working copy by
giving the `-j BRANCH' flag to the `update' command.  With one `-j
BRANCH' option it merges the changes made between the point where the
branch forked and newest revision on that branch (into your working
copy).

   The `-j' stands for "join".

   Consider this revision tree:

     +-----+    +-----+    +-----+    +-----+
     ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !      <- The main trunk
     +-----+    +-----+    +-----+    +-----+
                     !
                     !
                     !   +---------+    +---------+
     Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
                         +---------+    +---------+

The branch 1.2.2 has been given the tag (symbolic name) `R1fix'.  The
following example assumes that the module `mod' contains only one file,
`m.c'.

     $ cvs checkout mod               # Retrieve the latest revision, 1.4
     
     $ cvs update -j R1fix m.c        # Merge all changes made on the branch,
                                      # i.e. the changes between revision 1.2
                                      # and 1.2.2.2, into your working copy
                                      # of the file.
     
     $ cvs commit -m "Included R1fix" # Create revision 1.5.

   A conflict can result from a merge operation.  If that happens, you
should resolve it before committing the new revision.  *Note Conflicts
example::.

   The `checkout' command also supports the `-j BRANCH' flag.  The same
effect as above could be achieved with this:

     $ cvs checkout -j R1fix mod
     $ cvs commit -m "Included R1fix"


File: cvs.info,  Node: Merging more than once,  Next: Merging two revisions,  Prev: Merging a branch,  Up: Merging

Merging from a branch several times
===================================

   Continuing our example, the revision tree now looks like this:

     +-----+    +-----+    +-----+    +-----+    +-----+
     ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !   <- The main trunk
     +-----+    +-----+    +-----+    +-----+    +-----+
                     !                           *
                     !                          *
                     !   +---------+    +---------+
     Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
                         +---------+    +---------+

   where the starred line represents the merge from the `R1fix' branch
to the main trunk, as just discussed.

   Now suppose that development continues on the `R1fix' branch:

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

   and then you want to merge those new changes onto the main trunk.
If you just use the `cvs update -j R1fix m.c' command again, 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 `-j' options, and CVS merges the changes from
the first revision to the second revision.  For example, in this case
the simplest way would be

     cvs update -j 1.2.2.2 -j R1fix m.c    # Merge changes from 1.2.2.2 to the
                                           # head of the R1fix branch

   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:

     cvs update -j R1fix:yesterday -j R1fix m.c

   Better yet, tag the R1fix branch after every merge into the trunk,
and then use that tag for subsequent merges:

     cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c


File: cvs.info,  Node: Merging two revisions,  Next: Merging adds and removals,  Prev: Merging more than once,  Up: Merging

Merging differences between any two revisions
=============================================

   With two `-j REVISION' flags, the `update' (and `checkout') command
can merge the differences between any two revisions into your working
file.

     $ cvs update -j 1.5 -j 1.3 backend.c

will *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.


File: cvs.info,  Node: Merging adds and removals,  Prev: Merging two revisions,  Up: Merging

Merging can add or remove files
===============================

   If the changes which you are merging involve removing or adding some
files, `update -j' will reflect such additions or removals.

   For example:
     cvs update -A
     touch a b c
     cvs add a b c ; cvs ci -m "added" a b c
     cvs tag -b branchtag
     cvs update -r branchtag
     touch d ; cvs add d
     rm a ; cvs rm a
     cvs ci -m "added d, removed a"
     cvs update -A
     cvs update -jbranchtag

   After these commands are executed and a `cvs commit' is done, file
`a' will be removed and file `d' added in the main branch.


File: cvs.info,  Node: Recursive behavior,  Next: Adding and removing,  Prev: Merging,  Up: Top

Recursive behavior
******************

   Almost all of the subcommands of CVS work recursively when you
specify a directory as an argument.  For instance, consider this
directory structure:

           `$HOME'
             |
             +--tc
             |   |
                 +--CVS
                 |      (internal CVS files)
                 +--Makefile
                 +--backend.c
                 +--driver.c
                 +--frontend.c
                 +--parser.c
                 +--man
                 |    |
                 |    +--CVS
                 |    |  (internal CVS files)
                 |    +--tc.1
                 |
                 +--testing
                      |
                      +--CVS
                      |  (internal CVS files)
                      +--testpgm.t
                      +--test2.t

If `tc' is the current working directory, the following is true:

   * `cvs update testing' is equivalent to

          cvs update testing/testpgm.t testing/test2.t

   * `cvs update testing man' updates all files in the subdirectories

   * `cvs update .' or just `cvs update' updates all files in the `tc'
     module

   If no arguments are given to `update' it will update all files in
the current working directory and all its subdirectories.  In other
words, `.' is a default argument to `update'.  This is also true for
most of the CVS subcommands, not only the `update' command.

   The recursive behavior of the CVS subcommands can be turned off with
the `-l' option.  Conversely, the `-R' option can be used to force
recursion if `-l' is specified in `~/.cvsrc' (*note ~/.cvsrc::.).

     $ cvs update -l         # Don't update files in subdirectories


File: cvs.info,  Node: Adding and removing,  Next: Tracking sources,  Prev: Recursive behavior,  Up: Top

Adding, removing, and renaming files and directories
****************************************************

   In the course of a project, one will often add new files.  Likewise
with removing or renaming, or with directories.  The general concept to
keep in mind in all these cases is that instead of making an
irreversible change you want CVS to record the fact that a change has
taken place, just as with modifying an existing file.  The exact
mechanisms to do this in CVS vary depending on the situation.

* Menu:

* Adding files::                Adding files
* Removing files::              Removing files
* Removing directories::        Removing directories
* Moving files::                Moving and renaming files
* Moving directories::          Moving and renaming directories


File: cvs.info,  Node: Adding files,  Next: Removing files,  Up: Adding and removing

Adding files to a directory
===========================

   To add a new file to a directory, follow these steps.

   * You must have a working copy of the directory.  *Note Getting the
     source::.

   * Create the new file inside your working copy of the directory.

   * Use `cvs add FILENAME' to tell CVS that you want to version
     control the file.  If the file contains binary data, specify `-kb'
     (*note Binary files::.).

   * Use `cvs commit FILENAME' to actually check in the file into the
     repository.  Other developers cannot see the file until you
     perform this step.

   You can also use the `add' command to add a new directory.

   Unlike most other commands, the `add' command is not recursive.  You
cannot even type `cvs add foo/bar'!  Instead, you have to

     $ cd foo
     $ cvs add bar

 - Command: cvs add [`-k' KFLAG] [`-m' MESSAGE] FILES ...
     Schedule FILES to be added to the repository.  The files or
     directories specified with `add' must already exist in the current
     directory.  To add a whole new directory hierarchy to the source
     repository (for example, files received from a third-party
     vendor), use the `import' command instead.  *Note import::.

     The added files are not placed in the source repository until you
     use `commit' to make the change permanent.  Doing an `add' on a
     file that was removed with the `remove' command will undo the
     effect of the `remove', unless a `commit' command intervened.
     *Note Removing files::, for an example.

     The `-k' option specifies the default way that this file will be
     checked out; for more information see *Note Substitution modes::.

     The `-m' option specifies a description for the file.  This
     description appears in the history log (if it is enabled, *note
     history file::.).  It will also be saved in the version history
     inside the repository when the file is committed.  The `log'
     command displays this description.  The description can be changed
     using `admin -t'.  *Note admin::.  If you omit the `-m
     DESCRIPTION' flag, an empty string will be used.  You will not be
     prompted for a description.

   For example, the following commands add the file `backend.c' to the
repository:

     $ cvs add backend.c
     $ cvs commit -m "Early version. Not yet compilable." backend.c

   When you add a file it is added only on the branch which you are
working on (*note Revisions and branches::.).  You can later merge the
additions to another branch if you want (*note Merging adds and
removals::.).


File: cvs.info,  Node: Removing files,  Next: Removing directories,  Prev: Adding files,  Up: Adding and removing

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

   Here is what you can do to remove a file, but remain able to
retrieve old revisions:

   * Make sure that you have not made any uncommitted modifications to
     the file.  *Note Viewing differences::, for one way to do that.
     You can also use the `status' or `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.

   * Remove the file from your working copy of the directory.  You can
     for instance use `rm'.

   * Use `cvs remove FILENAME' to tell CVS that you really want to
     delete the file.

   * Use `cvs commit FILENAME' to actually perform the removal of the
     file from the repository.

   When you commit the removal of the file, 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 `-r' and `-D' options specified to `checkout' or `update'.

 - Command: cvs remove [OPTIONS] FILES ...
     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.  For a full list of
     options, see *Note Invoking CVS::.

   Here is an example of removing several files:

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

   As a convenience you can remove the file and `cvs remove' it in one
step, by specifying the `-f' option.  For example, the above example
could also be done like this:

     $ cd test
     $ cvs remove -f *.c
     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 .

   If you execute `remove' for a file, and then change your mind before
you commit, you can undo the `remove' with an `add' command.

     $ 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

   If you realize your mistake before you run the `remove' command you
can use `update' to resurrect the file:

     $ rm oj.c
     $ cvs update oj.c
     cvs update: warning: oj.c was lost
     U oj.c

   When you remove a file it is removed only on the branch which you
are working on (*note Revisions and branches::.).  You can later merge
the removals to another branch if you want (*note Merging adds and
removals::.).


File: cvs.info,  Node: Removing directories,  Next: Moving files,  Prev: Removing files,  Up: Adding and removing

Removing directories
====================

   In concept removing directories is somewhat similar to removing
files--you want the directory to not exist in your current working
directories, but you also want to be able to retrieve old releases in
which the directory existed.

   The way that you remove a directory is to remove all the files in
it.  You don't remove the directory itself; there is no way to do that.
Instead you specify the `-P' option to `cvs update', `cvs checkout', or
`cvs export', which will cause CVS to remove empty directories from
working directories.  Probably the best way to do this is to always
specify `-P'; if you want an empty directory then put a dummy file (for
example `.keepme') in it to prevent `-P' from removing it.

   Note that `-P' is implied by the `-r' or `-D' options of `checkout'
and `export'.  This way CVS will be able to correctly create the
directory or not depending on whether the particular version you are
checking out contains any files in that directory.


File: cvs.info,  Node: Moving files,  Next: Moving directories,  Prev: Removing directories,  Up: Adding and removing

Moving and renaming files
=========================

   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.  *Note Moving
directories::.).

   The examples below assume that the file OLD is renamed to NEW.

* Menu:

* Outside::                     The normal way to Rename
* Inside::                      A tricky, alternative way
* Rename by copying::           Another tricky, alternative way


File: cvs.info,  Node: Outside,  Next: Inside,  Up: Moving files

The Normal way to Rename
------------------------

   The normal way to move a file is to copy OLD to NEW, and then issue
the normal CVS commands to remove OLD from the repository, and add NEW
to it.

     $ mv OLD NEW
     $ cvs remove OLD
     $ cvs add NEW
     $ cvs commit -m "Renamed OLD to NEW" OLD NEW

   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, `cvs
log OLD' will give the log up until the time of the rename.

   When NEW is committed its revision numbers will start again, usually
at 1.1, so if that bothers you, use the `-r rev' option to commit.  For
more information see *Note Assigning revisions::.

