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: Multiple repositories,  Next: Creating a repository,  Prev: Intro administrative files,  Up: Repository

Multiple repositories
=====================

   In some situations it is a good idea to have more than one
repository, for instance if you have two development groups that work
on separate projects without sharing any code.  All you have to do to
have several repositories is to specify the appropriate repository,
using the `CVSROOT' environment variable, the `-d' option to CVS, or
(once you have checked out a working directory) by simply allowing CVS
to use the repository that was used to check out the working directory
(*note Specifying a repository::.).

   The big advantage of having multiple repositories is that they can
reside on different servers.  The big disadvantage is that you cannot
have a single CVS command recurse into directories which comes from
different repositories.  Generally speaking, if you are thinking of
setting up several repositories on the same machine, you might want to
consider using several directories within the same repository.

   None of the examples in this manual show multiple repositories.


File: cvs.info,  Node: Creating a repository,  Next: Backing up,  Prev: Multiple repositories,  Up: Repository

Creating a repository
=====================

   To set up a CVS repository, first choose the machine and disk on
which you want to store the revision history of the source files.  CPU
and memory requirements are modest, so most machines should be
adequate.  For details see *Note Server requirements::.

   To estimate disk space requirements, if you are importing RCS files
from another system, the size of those files is the approximate initial
size of your repository, or if you are starting without any version
history, a rule of thumb is to allow for the server approximately three
times the size of the code to be under CVS for the repository (you will
eventually outgrow this, but not for a while).  On the machines on
which the developers will be working, you'll want disk space for
approximately one working directory for each developer (either the
entire tree or a portion of it, depending on what each developer uses).

   The repository should be accessable (directly or via a networked
file system) from all machines which want to use CVS in server or local
mode; the client machines need not have any access to it other than via
the CVS protocol.  It is not possible to use CVS to read from a
repository which one only has read access to; CVS needs to be able to
create lock files (*note Concurrency::.).

   To create a repository, run the `cvs init' command.  It will set up
an empty repository in the CVS root specified in the usual way (*note
Repository::.).  For example,

     cvs -d /usr/local/cvsroot init

   `cvs init' is careful to never overwrite any existing files in the
repository, so no harm is done if you run `cvs init' on an already
set-up repository.

   `cvs init' will enable history logging; if you don't want that,
remove the history file after running `cvs init'.  *Note history file::.


File: cvs.info,  Node: Backing up,  Next: Moving a repository,  Prev: Creating a repository,  Up: Repository

Backing up a repository
=======================

   There is nothing particularly magical about the files in the
repository; for the most part it is possible to back them up just like
any other files.  However, there are a few issues to consider.

   The first is that to be paranoid, one should either not use CVS
during the backup, or have the backup program lock CVS while doing the
backup.  To not use CVS, you might forbid logins to machines which can
access the repository, turn off your CVS server, or similar mechanisms.
The details would depend on your operating system and how you have CVS
set up.  To lock CVS, you would create `#cvs.rfl' locks in each
repository directory.  See *Note Concurrency::, for more on CVS locks.
Having said all this, if you just back up without any of these
precautions, the results are unlikely to be particularly dire.
Restoring from backup, the repository might be in an inconsistent
state, but this would not be particularly hard to fix manually.

   When you restore a repository from backup, assuming that changes in
the repository were made after the time of the backup, working
directories which were not affected by the failure may refer to
revisions which no longer exist in the repository.  Trying to run CVS
in such directories will typically produce an error message.  One way
to get those changes back into the repository is as follows:

   * Get a new working directory.

   * Copy the files from the working directory from before the failure
     over to the new working directory (do not copy the contents of the
     `CVS' directories, of course).

   * Working in the new working directory, use commands such as `cvs
     update' and `cvs diff' to figure out what has changed, and then
     when you are ready, commit the changes into the repository.


File: cvs.info,  Node: Moving a repository,  Next: Remote repositories,  Prev: Backing up,  Up: Repository

Moving a repository
===================

   Just as backing up the files in the repository is pretty much like
backing up any other files, if you need to move a repository from one
place to another it is also pretty much like just moving any other
collection of files.

   The main thing to consider is that working directories point to the
repository.  The simplest way to deal with a moved repository is to
just get a fresh working directory after the move.  Of course, you'll
want to make sure that the old working directory had been checked in
before the move, or you figured out some other way to make sure that
you don't lose any changes.  If you really do want to reuse the existing
working directory, it should be possible with manual surgery on the
`CVS/Repository' files.  You can see *Note Working directory storage::,
for information on the `CVS/Repository' and `CVS/Root' files, but
unless you are sure you want to bother, it probably isn't worth it.


File: cvs.info,  Node: Remote repositories,  Next: Read-only access,  Prev: Moving a repository,  Up: Repository

Remote repositories
===================

   Your working copy of the sources can be on a different machine than
the repository.  Using CVS in this manner is known as "client/server"
operation.  You run CVS on a machine which can mount your working
directory, known as the "client", and tell it to communicate to a
machine which can mount the repository, known as the "server".
Generally, using a remote repository is just like using a local one,
except that the format of the repository name is:

     :METHOD:USER@HOSTNAME:/path/to/repository

   The details of exactly what needs to be set up depend on how you are
connecting to the server.

   If METHOD is not specified, and the repository name contains `:',
then the default is `ext' or `server', depending on your platform; both
are described in *Note Connecting via rsh::.

* Menu:

* Server requirements::         Memory and other resources for servers
* Connecting via rsh::          Using the `rsh' program to connect
* Password authenticated::      Direct connections using passwords
* Kerberos authenticated::      Direct connections with kerberos


File: cvs.info,  Node: Server requirements,  Next: Connecting via rsh,  Up: Remote repositories

Server requirements
-------------------

   The quick answer to what sort of machine is suitable as a server is
that requirements are modest--a server with 32M of memory or even less
can handle a fairly large source tree with a fair amount of activity.

   The real answer, of course, is more complicated.  Estimating the
known areas of large memory consumption should be sufficient to
estimate memory requirements.  There are two such areas documented
here; other memory consumption should be small by comparison (if you
find that is not the case, let us know, as described in *Note BUGS::,
so we can update this documentation).

   The first area of big memory consumption is large checkouts, when
using the CVS server.  The server consists of two processes for each
client that it is serving.  Memory consumption on the child process
should remain fairly small.  Memory consumption on the parent process,
particularly if the network connection to the client is slow, can be
expected to grow to slightly more than the size of the sources in a
single directory, or two megabytes, whichever is larger.

   Multiplying the size of each CVS server by the number of servers
which you expect to have active at one time should give an idea of
memory requirements for the server.  For the most part, the memory
consumed by the parent process probably can be swap space rather than
physical memory.

   The second area of large memory consumption is `diff', when checking
in large files.  This is required even for binary files.  The rule of
thumb is to allow about ten times the size of the largest file you will
want to check in, although five times may be adequate.  For example, if
you want to check in a file which is 10 megabytes, you should have 100
megabytes of memory on the machine doing the checkin (the server
machine for client/server, or the machine running CVS for
non-client/server).  This can be swap space rather than physical
memory.  Because the memory is only required briefly, there is no
particular need to allow memory for more than one such checkin at a
time.

   Resource consumption for the client is even more modest--any machine
with enough capacity to run the operating system in question should
have little trouble.

   For information on disk space requirements, see *Note Creating a
repository::.


File: cvs.info,  Node: Connecting via rsh,  Next: Password authenticated,  Prev: Server requirements,  Up: Remote repositories

Connecting with rsh
-------------------

   CVS uses the `rsh' protocol to perform these operations, so the
remote user host needs to have a `.rhosts' file which grants access to
the local user.

   For example, suppose you are the user `mozart' on the local machine
`toe.grunge.com', and the server machine is `chainsaw.yard.com'.  On
chainsaw, put the following line into the file `.rhosts' in `bach''s
home directory:

     toe.grunge.com  mozart

   Then test that `rsh' is working with

     rsh -l bach chainsaw.yard.com 'echo $PATH'

   Next you have to make sure that `rsh' will be able to find the
server.  Make sure that the path which `rsh' printed in the above
example includes the directory containing a program named `cvs' which
is the server.  You need to set the path in `.bashrc', `.cshrc', etc.,
not `.login' or `.profile'.  Alternately, you can set the environment
variable `CVS_SERVER' on the client machine to the filename of the
server you want to use, for example `/usr/local/bin/cvs-1.6'.

   There is no need to edit `inetd.conf' or start a CVS server daemon.

   There are two access methods that you use in CVSROOT for rsh.
`:server:' specifies an internal rsh client, which is supported only by
some CVS ports.  `:ext:' specifies an external rsh program.  By default
this is `rsh' but you may set the `CVS_RSH' environment variable to
invoke another program which can access the remote server (for example,
`remsh' on HP-UX 9 because `rsh' is something different).  It must be a
program which can transmit data to and from the server without modifying
it; for example the Windows NT `rsh' is not suitable since it by
default translates between CRLF and LF.  The OS/2 CVS port has a hack
to pass `-b' to `rsh' to get around this, but since this could
potentially cause problems for programs other than the standard `rsh',
it may change in the future.  If you set `CVS_RSH' to `SSH' or some
other rsh replacement, the instructions in the rest of this section
concerning `.rhosts' and so on are likely to be inapplicable; consult
the documentation for your rsh replacement.

   Continuing our example, supposing you want to access the module
`foo' in the repository `/usr/local/cvsroot/', on machine
`chainsaw.yard.com', you are ready to go:

     cvs -d :ext:bach@chainsaw.yard.com:/usr/local/cvsroot checkout foo

   (The `bach@' can be omitted if the username is the same on both the
local and remote hosts.)


File: cvs.info,  Node: Password authenticated,  Next: Kerberos authenticated,  Prev: Connecting via rsh,  Up: Remote repositories

Direct connection with password authentication
----------------------------------------------

   The CVS client can also connect to the server using a password
protocol.  This is particularly useful if using `rsh' is not feasible
(for example, the server is behind a firewall), and Kerberos also is
not available.

   To use this method, it is necessary to make some adjustments on both
the server and client sides.

* Menu:

* Password authentication server::     Setting up the server
* Password authentication client::     Using the client
* Password authentication security::   What this method does and does not do


File: cvs.info,  Node: Password authentication server,  Next: Password authentication client,  Up: Password authenticated

Setting up the server for password authentication
.................................................

   First of all, you probably want to tighten the permissions on the
`$CVSROOT' and `$CVSROOT/CVSROOT' directories.  See *Note Password
authentication security::, for more details.

   On the server side, the file `/etc/inetd.conf' needs to be edited so
`inetd' knows to run the command `cvs pserver' when it receives a
connection on the right port.  By default, the port number is 2401; it
would be different if your client were compiled with `CVS_AUTH_PORT'
defined to something else, though.

   If your `inetd' allows raw port numbers in `/etc/inetd.conf', then
the following (all on a single line in `inetd.conf') should be
sufficient:

     2401  stream  tcp  nowait  root  /usr/local/bin/cvs
     cvs -b /usr/local/bin --allow-root=/usr/cvsroot pserver

   The `-b' option specifies the directory which contains the RCS
binaries on the server.  You could also use the `-T' option to specify
a temporary directory.

   The `--allow-root' option specifies the allowable CVSROOT directory.
Clients which attempt to use a different CVSROOT directory will not be
allowed to connect.  If there is more than one CVSROOT directory which
you want to allow, repeat the option.

   Note that some versions of `inetd' may limit the number of arguments
to four.  If your server outputs usage messages instead of the CVS
protocol (which will typically cause a client to complain with protocol
errors), then try limiting the number of arguments.  For example,
instead of

     -b /usr/local/bin

   in `inetd.conf', as described above, put the following in
`CVSROOT/config' (as described in *note config::.):

     RCSBIN=/usr/local/bin

   If your `inetd' wants a symbolic service name instead of a raw port
number, then put this in `/etc/services':

     cvspserver      2401/tcp

   and put `cvspserver' instead of `2401' in `inetd.conf'.

   Once the above is taken care of, restart your `inetd', or do
whatever is necessary to force it to reread its initialization files.

   Because the client stores and transmits passwords in cleartext
(almost--see *Note Password authentication security::, for details), a
separate CVS password file may be used, so people don't compromise their
regular passwords when they access the repository.  This file is
`$CVSROOT/CVSROOT/passwd' (*note Intro administrative files::.).  Its
format is similar to `/etc/passwd', except that it only has two fields,
username and password.  For example:

     bach:ULtgRLXo7NRxs
     cwang:1sOp854gDF3DY

   The password is encrypted according to the standard Unix `crypt()'
function, so it is possible to paste in passwords directly from regular
Unix `passwd' files.

   When authenticating a password, the server first checks for the user
in the CVS `passwd' file.  If it finds the user, it compares against
that password.  If it does not find the user, or if the CVS `passwd'
file does not exist, then the server tries to match the password using
the system's user-lookup routine (using the system's user-lookup
routine can be disabled by setting `SystemAuth=no' in the config file,
*note config::.).  When using the CVS `passwd' file, the server runs as
the username specified in the third argument in the entry, or as the
first argument if there is no third argument (in this way CVS allows
imaginary usernames provided the CVS `passwd' file indicates
corresponding valid system usernames).  In any case, CVS will have no
privileges which the (valid) user would not have.

   It is possible to "map" cvs-specific usernames onto system usernames
(i.e., onto system login names) in the `$CVSROOT/CVSROOT/passwd' file
by appending a colon and the system username after the password.  For
example:

     cvs:ULtgRLXo7NRxs:kfogel
     generic:1sOp854gDF3DY:spwang
     anyone:1sOp854gDF3DY:spwang

   Thus, someone remotely accessing the repository on
`chainsaw.yard.com' with the following command:

     cvs -d :pserver:cvs@chainsaw.yard.com:/usr/local/cvsroot checkout foo

   would end up running the server under the system identity kfogel,
assuming successful authentication.  However, the remote user would not
necessarily need to know kfogel's system password, as the
`$CVSROOT/CVSROOT/passwd' file might contain a different password, used
only for CVS.  And as the example above indicates, it is permissible to
map multiple cvs usernames onto a single system username.

   This feature is designed to allow people repository access without
full system access (in particular, see *Note Read-only access::);
however, also see *Note Password authentication security::.  Any sort of
repository access very likely implies a degree of general system access
as well.

   Right now, the only way to put a password in the CVS `passwd' file
is to paste it there from somewhere else.  Someday, there may be a `cvs
passwd' command.


File: cvs.info,  Node: Password authentication client,  Next: Password authentication security,  Prev: Password authentication server,  Up: Password authenticated

Using the client with password authentication
.............................................

   Before connecting to the server, the client must "log in" with the
command `cvs login'.  Logging in verifies a password with the server,
and also records the password for later transactions with the server.
The `cvs login' command needs to know the username, server hostname,
and full repository path, and it gets this information from the
repository argument or the `CVSROOT' environment variable.

   `cvs login' is interactive -- it prompts for a password:

     cvs -d :pserver:bach@chainsaw.yard.com:/usr/local/cvsroot login
     CVS password:

   The password is checked with the server; if it is correct, the
`login' succeeds, else it fails, complaining that the password was
incorrect.

   Once you have logged in, you can force CVS to connect directly to
the server and authenticate with the stored password:

     cvs -d :pserver:bach@chainsaw.yard.com:/usr/local/cvsroot checkout foo

   The `:pserver:' is necessary because without it, CVS will assume it
should use `rsh' to connect with the server (*note Connecting via
rsh::.).  (Once you have a working copy checked out and are running CVS
commands from within it, there is no longer any need to specify the
repository explicitly, because CVS records it in the working copy's
`CVS' subdirectory.)

   Passwords are stored by default in the file `$HOME/.cvspass'.  Its
format is human-readable, but don't edit it unless you know what you
are doing.  The passwords are not stored in cleartext, but are
trivially encoded to protect them from "innocent" compromise (i.e.,
inadvertently being seen by a system administrator who happens to look
at that file).

   The password for the currently choosen remote repository can be
removed from the CVS_PASSFILE by using the `cvs logout' command.

   The `CVS_PASSFILE' environment variable overrides this default.  If
you use this variable, make sure you set it *before* `cvs login' is
run.  If you were to set it after running `cvs login', then later CVS
commands would be unable to look up the password for transmission to
the server.


File: cvs.info,  Node: Password authentication security,  Prev: Password authentication client,  Up: Password authenticated

Security considerations with password authentication
....................................................

   The passwords are stored on the client side in a trivial encoding of
the cleartext, and transmitted in the same encoding.  The encoding is
done only to prevent inadvertent password compromises (i.e., a system
administrator accidentally looking at the file), and will not prevent
even a naive attacker from gaining the password.

   The separate CVS password file (*note Password authentication
server::.) allows people to use a different password for repository
access than for login access.  On the other hand, once a user has
non-read-only access to the repository, she can execute programs on the
server system through a variety of means.  Thus, repository access
implies fairly broad system access as well.  It might be possible to
modify CVS to prevent that, but no one has done so as of this writing.
Furthermore, there may be other ways in which having access to CVS
allows people to gain more general access to the system; no one has
done a careful audit.

   Note that because the `$CVSROOT/CVSROOT' directory contains `passwd'
and other files which are used to check security, you must control the
permissions on this directory as tightly as the permissions on `/etc'.
The same applies to the `$CVSROOT' directory itself and any directory
above it in the tree.  Anyone who has write access to such a directory
will have the ability to become any user on the system.  Note that
these permissions are typically tighter than you would use if you are
not using pserver.

   In summary, anyone who gets the password gets repository access, and
some measure of general system access as well.  The password is
available to anyone who can sniff network packets or read a protected
(i.e., user read-only) file.  If you want real security, get Kerberos.


File: cvs.info,  Node: Kerberos authenticated,  Prev: Password authenticated,  Up: Remote repositories

Direct connection with kerberos
-------------------------------

   The easiest way to use kerberos is to use the kerberos `rsh', as
described in *Note 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.

   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.

   You need to edit `inetd.conf' on the server machine to run `cvs
kserver'.  The client uses port 1999 by default; if you want to use
another port specify it in the `CVS_CLIENT_PORT' environment variable
on the client.

   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:chainsaw.yard.com:/user/local/cvsroot checkout foo

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


File: cvs.info,  Node: Read-only access,  Next: Server temporary directory,  Prev: Remote repositories,  Up: Repository

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

   It is possible to grant read-only repository access to people using
the password-authenticated server (*note 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 (*note 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
(*note 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.


File: cvs.info,  Node: Server temporary directory,  Prev: Read-only access,  Up: Repository

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 `TMPDIR' environment variable
(*note Environment variables::.), the `-T' global option (*note Global
options::.), 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.


File: cvs.info,  Node: Starting a new project,  Next: Multiple developers,  Prev: Repository,  Up: Top

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

   What to do next depends on the situation at hand.

* Menu:

* Setting up the files::        Getting the files into the repository
* Defining the module::         How to make a module of the files


File: cvs.info,  Node: Setting up the files,  Next: Defining the module,  Up: Starting a new project

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.

* Menu:

* From files::                  This method is useful with old projects
                                where files already exists.
* From other version control systems::  Old projects where you want to
                                        preserve history from another system.
* From scratch::                Creating a directory tree from scratch.


File: cvs.info,  Node: From files,  Next: From other version control systems,  Up: Setting up the files

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.  *Note
Tracking sources::, for more information about them.

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

     $ cd ..
     $ mv DIR DIR.orig
     $ cvs checkout yoyodyne/DIR       # Explanation below
     $ diff -r DIR.orig yoyodyne/DIR
     $ rm -r DIR.orig

Erasing the original sources is a good idea, to make sure that you do
not accidentally edit them in DIR, 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.  *Note 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.  *Note Wrappers::.


File: cvs.info,  Node: From other version control systems,  Next: From scratch,  Prev: From files,  Up: Setting up the files

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


File: cvs.info,  Node: From scratch,  Prev: From other version control systems,  Up: Setting up the files

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

   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.


File: cvs.info,  Node: Defining the module,  Prev: Setting up the files,  Up: Starting a new project

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.  *Note
     Intro administrative files::, for an introduction.  *Note
     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


File: cvs.info,  Node: Multiple developers,  Next: Revisions and branches,  Prev: Starting a new project,  Up: Top

Multiple developers
*******************

   When more than one person works on a software project things often
get complicated.  Often, two people try to edit the same file
simultaneously.  One solution, known as "file locking" or "reserved
checkouts", is to allow only one person to edit each file at a time.
This is the only solution with some version control systems, including
RCS and SCCS.  Currently the usual way to get reserved checkouts with
CVS is the `cvs admin -l' command (*note admin options::.).  This is
not as nicely integrated into CVS as the watch features, described
below, but it seems that most people with a need for reserved checkouts
find it adequate.  It also may be possible to use the watches features
described below, together with suitable procedures (not enforced by
software), to avoid having two people edit at the same time.

   The default model with CVS is known as "unreserved checkouts".  In
this model, developers can edit their own "working copy" of a file
simultaneously.  The first person that commits his changes has no
automatic way of knowing that another has started to edit it.  Others
will get an error message when they try to commit the file.  They must
then use CVS commands to bring their working copy up to date with the
repository revision.  This process is almost automatic.

   CVS also supports mechanisms which facilitate various kinds of
communcation, without actually enforcing rules like reserved checkouts
do.

   The rest of this chapter describes how these various models work,
and some of the issues involved in choosing between them.

* Menu:

* File status::                 A file can be in several states
* Updating a file::             Bringing a file up-to-date
* Conflicts example::           An informative example
* Informing others::            To cooperate you must inform
* Concurrency::                 Simultaneous repository access
* Watches::                     Mechanisms to track who is editing files
* Choosing a model::            Reserved or unreserved checkouts?


File: cvs.info,  Node: File status,  Next: Updating a file,  Up: Multiple developers

File status
===========

   Based on what operations you have performed on a checked out file,
and what operations others have performed to that file in the
repository, one can classify a file in a number of states.  The states,
as reported by the `status' command, are:

Up-to-date
     The file is identical with the latest revision in the repository
     for the branch in use.

Locally Modified
     You have edited the file, and not yet committed your changes.

Locally Added
     You have added the file with `add', and not yet committed your
     changes.

Locally Removed
     You have removed the file with `remove', and not yet committed
     your changes.

Needs Checkout
     Someone else has committed a newer revision to the repository.
     The name is slightly misleading; you will ordinarily use `update'
     rather than `checkout' to get that newer revision.

Needs Patch
     Like Needs Checkout, but the CVS server will send a patch rather
     than the entire file.  Sending a patch or sending an entire file
     accomplishes the same thing.

Needs Merge
     Someone else has committed a newer revision to the repository, and
     you have also made modifications to the file.

File had conflicts on merge
     This is like Locally Modified, except that a previous `update'
     command gave a conflict.  If you have not already done so, you
     need to resolve the conflict as described in *Note Conflicts
     example::.

Unknown
     CVS doesn't know anything about this file.  For example, you have
     created a new file and have not run `add'.

   To help clarify the file status, `status' also reports the `Working
revision' which is the revision that the file in the working directory
derives from, and the `Repository revision' which is the latest
revision in the repository for the branch in use.

   The options to `status' are listed in *Note Invoking CVS::.  For
information on its `Sticky tag' and `Sticky date' output, see *Note
Sticky tags::.  For information on its `Sticky options' output, see the
`-k' option in *Note update options::.

   You can think of the `status' and `update' commands as somewhat
complementary.  You use `update' to bring your files up to date, and you
can use `status' to give you some idea of what an `update' would do (of
course, the state of the repository might change before you actually run
`update').  In fact, if you want a command to display file status in a
more brief format than is displayed by the `status' command, you can
invoke

     $ cvs -n -q update

   The `-n' option means to not actually do the update, but merely to
display statuses; the `-q' option avoids printing the name of each
directory.  For more information on the `update' command, and these
options, see *Note Invoking CVS::.


File: cvs.info,  Node: Updating a file,  Next: Conflicts example,  Prev: File status,  Up: Multiple developers

Bringing a file up to date
==========================

   When you want to update or merge a file, use the `update' command.
For files that are not up to date this is roughly equivalent to a
`checkout' command: the newest revision of the file is extracted from
the repository and put in your working copy of the module.

   Your modifications to a file are never lost when you use `update'.
If no newer revision exists, running `update' has no effect.  If you
have edited the file, and a newer revision is available, CVS will merge
all changes into your working copy.

   For instance, imagine that you checked out revision 1.4 and started
editing it.  In the meantime someone else committed revision 1.5, and
shortly after that revision 1.6.  If you run `update' on the file now,
CVS will incorporate all changes between revision 1.4 and 1.6 into your
file.

   If any of the changes between 1.4 and 1.6 were made too close to any
of the changes you have made, an "overlap" occurs.  In such cases a
warning is printed, and the resulting file includes both versions of
the lines that overlap, delimited by special markers.  *Note update::,
for a complete description of the `update' command.


File: cvs.info,  Node: Conflicts example,  Next: Informing others,  Prev: Updating a file,  Up: Multiple developers

Conflicts example
=================

   Suppose revision 1.4 of `driver.c' contains this:

     #include <stdio.h>
     
     void main()
     {
         parse();
         if (nerr == 0)
             gencode();
         else
             fprintf(stderr, "No code generated.\n");
         exit(nerr == 0 ? 0 : 1);
     }

Revision 1.6 of `driver.c' contains this:

     #include <stdio.h>
     
     int main(int argc,
              char **argv)
     {
         parse();
         if (argc != 1)
         {
             fprintf(stderr, "tc: No args expected.\n");
             exit(1);
         }
         if (nerr == 0)
             gencode();
         else
             fprintf(stderr, "No code generated.\n");
         exit(!!nerr);
     }

Your working copy of `driver.c', based on revision 1.4, contains this
before you run `cvs update':

     #include <stdlib.h>
     #include <stdio.h>
     
     void main()
     {
         init_scanner();
         parse();
         if (nerr == 0)
             gencode();
         else
             fprintf(stderr, "No code generated.\n");
         exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
     }

You run `cvs update':

     $ cvs update driver.c
     RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v
     retrieving revision 1.4
     retrieving revision 1.6
     Merging differences between 1.4 and 1.6 into driver.c
     rcsmerge warning: overlaps during merge
     cvs update: conflicts found in driver.c
     C driver.c

CVS tells you that there were some conflicts.  Your original working
file is saved unmodified in `.#driver.c.1.4'.  The new version of
`driver.c' contains this:

     #include <stdlib.h>
     #include <stdio.h>
     
     int main(int argc,
              char **argv)
     {
         init_scanner();
         parse();
         if (argc != 1)
         {
             fprintf(stderr, "tc: No args expected.\n");
             exit(1);
         }
         if (nerr == 0)
             gencode();
         else
             fprintf(stderr, "No code generated.\n");
     <<<<<<< driver.c
         exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
     =======
         exit(!!nerr);
     >>>>>>> 1.6
     }

Note how all non-overlapping modifications are incorporated in your
working copy, and that the overlapping section is clearly marked with
`<<<<<<<', `=======' and `>>>>>>>'.

   You resolve the conflict by editing the file, removing the markers
and the erroneous line.  Suppose you end up with this file:
     #include <stdlib.h>
     #include <stdio.h>
     
     int main(int argc,
              char **argv)
     {
         init_scanner();
         parse();
         if (argc != 1)
         {
             fprintf(stderr, "tc: No args expected.\n");
             exit(1);
         }
         if (nerr == 0)
             gencode();
         else
             fprintf(stderr, "No code generated.\n");
         exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
     }

You can now go ahead and commit this as revision 1.7.

     $ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c
     Checking in driver.c;
     /usr/local/cvsroot/yoyodyne/tc/driver.c,v  <--  driver.c
     new revision: 1.7; previous revision: 1.6
     done

   For your protection, CVS will refuse to check in a file if a
conflict occurred and you have not resolved the conflict.  Currently to
resolve a conflict, you must change the timestamp on the file, and must
also insure that the file contains no conflict markers.  If your file
legitimately contains conflict markers (that is, occurrences of
`>>>>>>> ' at the start of a line that don't mark a conflict), then CVS
has trouble handling this and you need to start hacking on the
`CVS/Entries' file or other such workarounds.

   If you use release 1.04 or later of pcl-cvs (a GNU Emacs front-end
for CVS) you can use an Emacs package called emerge to help you resolve
conflicts.  See the documentation for pcl-cvs.


File: cvs.info,  Node: Informing others,  Next: Concurrency,  Prev: Conflicts example,  Up: Multiple developers

Informing others about commits
==============================

   It is often useful to inform others when you commit a new revision
of a file.  The `-i' option of the `modules' file, or the `loginfo'
file, can be used to automate this process.  *Note modules::.  *Note
loginfo::.  You can use these features of CVS to, for instance,
instruct CVS to mail a message to all developers, or post a message to
a local newsgroup.


File: cvs.info,  Node: Concurrency,  Next: Watches,  Prev: Informing others,  Up: Multiple developers

Several developers simultaneously attempting to run CVS
=======================================================

   If several developers try to run CVS at the same time, one may get
the following message:

     [11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo

   CVS will try again every 30 seconds, and either continue with the
operation or print the message again, if it still needs to wait.  If a
lock seems to stick around for an undue amount of time, find the person
holding the lock and ask them about the cvs command they are running.
If they aren't running a cvs command, look in the repository directory
mentioned in the message and remove files which they own whose names
start with `#cvs.tfl', `#cvs.rfl', or `#cvs.wfl'.

   Note that these locks are to protect CVS's internal data structures
and have no relationship to the word "lock" in the sense used by
RCS--which refers to reserved checkouts (*note Multiple developers::.).

   Any number of people can be reading from a given repository at a
time; only when someone is writing do the locks prevent other people
from reading or writing.

   One might hope for the following property

     If someone commits some changes in one cvs command,
     then an update by someone else will either get all the
     changes, or none of them.

   but CVS does *not* have this property.  For example, given the files

     a/one.c
     a/two.c
     b/three.c
     b/four.c

   if someone runs

     cvs ci a/two.c b/three.c

   and someone else runs `cvs update' at the same time, the person
running `update' might get only the change to `b/three.c' and not the
change to `a/two.c'.


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

Mechanisms to track who is editing files
========================================

   For many groups, use of CVS in its default mode is perfectly
satisfactory.  Users may sometimes go to check in a modification only
to find that another modification has intervened, but they deal with it
and proceed with their check in.  Other groups prefer to be able to
know who is editing what files, so that if two people try to edit the
same file they can choose to talk about who is doing what when rather
than be surprised at check in time.  The features in this section allow
such coordination, while retaining the ability of two developers to
edit the same file at the same time.

   For maximum benefit developers should use `cvs edit' (not `chmod')
to make files read-write to edit them, and `cvs release' (not `rm') to
discard a working directory which is no longer in use, but CVS is not
able to enforce this behavior.

* Menu:

* Setting a watch::             Telling CVS to watch certain files
* Getting Notified::            Telling CVS to notify you
* Editing files::               How to edit a file which is being watched
* Watch information::           Information about who is watching and editing
* Watches Compatibility::       Watches interact poorly with CVS 1.6 or earlier

