path: root/gnu/usr.bin/cvs/doc/cvs.info-1

This is Info file cvs.info, produced by Makeinfo-1.64 from the input
file ../../work/ccvs/doc/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: Top,  Next: Preface,  Up: (dir)



   This info manual describes how to use and administer CVS version
1.9.2.

* Menu:

* Preface::                     About this manual
* What is CVS?::                What is CVS?
* Basic concepts::              Basic concepts of revision management
* A sample session::            A tour of basic CVS usage
* Repository::                  Where all your sources are stored
* Starting a new project::      Starting a project with CVS
* Multiple developers::         How CVS helps a group of developers
* Branches::                    Parallel development explained
* Merging::                     How to move changes between branches
* Recursive behavior::          CVS descends directories
* Adding files::                Adding files
* Removing files::              Removing files
* Removing directories::        Removing directories
* Tracking sources::            Tracking third-party sources
* Moving files::                Moving and renaming files
* Moving directories::          Moving and renaming directories
* History browsing::            Viewing the history of files in various ways
* Keyword substitution::        CVS can include the revision inside the file
* Binary files::                CVS can handle binary files
* Builds::                      Issues related to CVS and builds
* Compatibility::               Upgrading CVS versions
* Revision management::         Policy questions for revision management
* CVS commands::                CVS commands share some things
* Invoking CVS::                Quick reference to CVS commands
* Administrative files::        Reference manual for the Administrative files
* Environment variables::       All environment variables which affect CVS
* Troubleshooting::             Some tips when nothing works
* Copying::                     GNU GENERAL PUBLIC LICENSE
* Index::                       Index


File: cvs.info,  Node: Preface,  Next: What is CVS?,  Prev: Top,  Up: Top

About this manual
*****************

   Up to this point, one of the weakest parts of CVS has been the
documentation.  CVS is a complex program.  Previous versions of the
manual were written in the manual page format, which is not really well
suited for such a complex program.

   When writing this manual, I had several goals in mind:

   * No knowledge of RCS should be necessary.

   * No previous knowledge of revision control software should be
     necessary.  All terms, such as "revision numbers", "revision
     trees" and "merging" are explained as they are introduced.

   * The manual should concentrate on the things CVS users want to do,
     instead of what the CVS commands can do.  The first part of this
     manual leads you through things you might want to do while doing
     development, and introduces the relevant CVS commands as they are
     needed.

   * Information should be easy to find.  In the reference manual in
     the appendices almost all information about every CVS command is
     gathered together.  There is also an extensive index, and a lot of
     cross references.

   This manual was contributed by Signum Support AB in Sweden.  Signum
is yet another in the growing list of companies that support free
software.  You are free to copy both this manual and the CVS program.
*Note Copying::, for the details.  Signum Support offers support
contracts and binary distribution for many programs, such as CVS, GNU
Emacs, the GNU C compiler and others.  Write to us for more information.

     Signum Support AB
     Box 2044
     S-580 02  Linkoping
     Sweden
     
     Email: info@signum.se
     Phone: +46 (0)13 - 21 46 00
     Fax:   +46 (0)13 - 21 47 00

   Another company selling support for CVS is Cyclic Software, web:
`http://www.cyclic.com/', email: `info@cyclic.com'.

* Menu:

* Checklist::
* Credits::
* BUGS::


File: cvs.info,  Node: Checklist,  Next: Credits,  Up: Preface

Checklist for the impatient reader
==================================

   CVS is a complex system.  You will need to read the manual to be
able to use all of its capabilities.  There are dangers that can easily
be avoided if you know about them, and this manual tries to warn you
about them.  This checklist is intended to help you avoid the dangers
without reading the entire manual.  If you intend to read the entire
manual you can skip this table.

Binary files
     CVS can handle binary files, but you must have RCS release 5.5 or
     later and a release of GNU diff that supports the `-a' flag
     (release 1.15 and later are OK).  You must also configure both RCS
     and CVS to handle binary files when you install them.

     Keword substitution can be a source of trouble with binary files.
     *Note Keyword substitution::, for solutions.

The `admin' command
     Careless use of the `admin' command can cause CVS to cease
     working.  *Note admin::, before trying to use it.


File: cvs.info,  Node: Credits,  Next: BUGS,  Prev: Checklist,  Up: Preface

Credits
=======

   Roland Pesch, then of Cygnus Support <roland@wrs.com> wrote the
manual pages which were distributed with CVS 1.3.  Appendix A and B
contain much text that was extracted from them.  He also read an early
draft of this manual and contributed many ideas and corrections.

   The mailing-list `info-cvs' is sometimes informative. I have
included information from postings made by the following persons: David
G. Grubbs <dgg@think.com>.

   Some text has been extracted from the man pages for RCS.

   The CVS FAQ by David G. Grubbs has provided useful material.  The
FAQ is no longer maintained, however, and this manual about the closest
thing there is to a successor (with respect to documenting how to use
CVS, at least).

   In addition, the following persons have helped by telling me about
mistakes I've made: Roxanne Brunskill <rbrunski@datap.ca>, Kathy Dyer
<dyer@phoenix.ocf.llnl.gov>, Karl Pingle <pingle@acuson.com>, Thomas A
Peterson <tap@src.honeywell.com>, Inge Wallin <ingwa@signum.se>, Dirk
Koschuetzki <koschuet@fmi.uni-passau.de> and Michael Brown
<brown@wi.extrel.com>.


File: cvs.info,  Node: BUGS,  Prev: Credits,  Up: Preface

BUGS
====

   This manual is known to have room for improvement.  Here is a list
of known deficiencies:

   * In the examples, the output from CVS is sometimes displayed,
     sometimes not.

   * The input that you are supposed to type in the examples should
     have a different font than the output from the computer.

   * This manual should be clearer about what file permissions you
     should set up in the repository, and about setuid/setgid.

   * Some of the chapters are not yet complete.  They are noted by
     comments in the `cvs.texinfo' file.

   * This list is not complete.  If you notice any error, omission, or
     something that is unclear, please send mail to
     bug-cvs@prep.ai.mit.edu.

   I hope that you will find this manual useful, despite the
above-mentioned shortcomings.


                                                Linkoping, October 1993
                                                         Per Cederqvist


File: cvs.info,  Node: What is CVS?,  Next: Basic concepts,  Prev: Preface,  Up: Top

What is CVS?
************

   CVS is a version control system.  Using it, you can record the
history of your source files.

   For example, bugs sometimes creep in when software is modified, and
you might not detect the bug until a long time after you make the
modification.  With CVS, you can easily retrieve old versions to see
exactly which change caused the bug.  This can sometimes be a big help.

   You could of course save every version of every file you have ever
created.  This would however waste an enormous amount of disk space.
CVS stores all the versions of a file in a single file in a clever way
that only stores the differences between versions.

   CVS also helps you if you are part of a group of people working on
the same project.  It is all too easy to overwrite each others' changes
unless you are extremely careful.  Some editors, like GNU Emacs, try to
make sure that the same file is never modified by two people at the
same time.  Unfortunately, if someone is using another editor, that
safeguard will not work.  CVS solves this problem by insulating the
different developers from each other.  Every developer works in his own
directory, and CVS merges the work when each developer is done.

   CVS started out as a bunch of shell scripts written by Dick Grune,
posted to `comp.sources.unix' in the volume 6 release of December,
1986.  While no actual code from these shell scripts is present in the
current version of CVS much of the CVS conflict resolution algorithms
come from them.

   In April, 1989, Brian Berliner designed and coded CVS.  Jeff Polk
later helped Brian with the design of the CVS module and vendor branch
support.

   You can get CVS via anonymous FTP from a number of sites; for
example see
     http://www.gnu.ai.mit.edu/order/ftp.html
   for a list of the GNU FTP sites.

   There is a mailing list, known as `info-cvs', devoted to CVS.  To
subscribe or unsubscribe send a message to
`info-cvs-request@prep.ai.mit.edu'.  Please be specific about your
email address.  As of May 1996, subscription requests are handled by a
busy human being, so you cannot expect to be added or removed
immediately.  If you prefer a usenet group, the right group is
`comp.software.config-mgmt' which is for CVS discussions (along with
other configuration management systems).  In the future, it might be
possible to create a `comp.software.config-mgmt.cvs', but probably only
if there is sufficient CVS traffic on `comp.software.config-mgmt'.

   To report bugs in CVS send mail to `bug-cvs@prep.ai.mit.edu'.  Do
note that someone may or may not feel like taking care of your bug
report--if you need a response consider a support contract from Cyclic
Software (`http://www.cyclic.com' or `info@cyclic.com').  This is also
the procedure for submitting suggested changes to CVS (see the file
HACKING in the source distribution for more details).  Note that all
submitted changes may be distributed under the terms of the GNU Public
License, so if you don't like this, don't submit them.

CVS is not...
=============

   CVS can do a lot of things for you, but it does not try to be
everything for everyone.

CVS is not a build system.
     Though the structure of your repository and modules file interact
     with your build system (e.g. `Makefile's), they are essentially
     independent.

     CVS does not dictate how you build anything.  It merely stores
     files for retrieval in a tree structure you devise.

     CVS does not dictate how to use disk space in the checked out
     working directories.  If you write your `Makefile's or scripts in
     every directory so they have to know the relative positions of
     everything else, you wind up requiring the entire repository to be
     checked out.

     If you modularize your work, and construct a build system that
     will share files (via links, mounts, `VPATH' in `Makefile's,
     etc.), you can arrange your disk usage however you like.

     But you have to remember that *any* such system is a lot of work
     to construct and maintain.  CVS does not address the issues
     involved.

     Of course, you should place the tools created to support such a
     build system (scripts, `Makefile's, etc) under CVS.

     Figuring out what files need to be rebuilt when something changes
     is, again, something to be handled outside the scope of CVS.  One
     traditional approach is to use `make' for building, and use some
     automated tool for generating the dependencies which `make' uses.

     See *Note Builds::, for more information on doing builds in
     conjunction with CVS.

CVS is not a substitute for management.
     Your managers and project leaders are expected to talk to you
     frequently enough to make certain you are aware of schedules,
     merge points, branch names and release dates.  If they don't, CVS
     can't help.

     CVS is an instrument for making sources dance to your tune.  But
     you are the piper and the composer.  No instrument plays itself or
     writes its own music.

CVS is not a substitute for developer communication.
     When faced with conflicts within a single file, most developers
     manage to resolve them without too much effort.  But a more
     general definition of "conflict" includes problems too difficult
     to solve without communication between developers.

     CVS cannot determine when simultaneous changes within a single
     file, or across a whole collection of files, will logically
     conflict with one another.  Its concept of a "conflict" is purely
     textual, arising when two changes to the same base file are near
     enough to spook the merge (i.e. `diff3') command.

     CVS does not claim to help at all in figuring out non-textual or
     distributed conflicts in program logic.

     For example: Say you change the arguments to function `X' defined
     in file `A'.  At the same time, someone edits file `B', adding new
     calls to function `X' using the old arguments.  You are outside
     the realm of CVS's competence.

     Acquire the habit of reading specs and talking to your peers.

CVS does not have change control
     Change control refers to a number of things.  First of all it can
     mean "bug-tracking", that is being able to keep a database of
     reported bugs and the status of each one (is it fixed?  in what
     release?  has the bug submitter agreed that it is fixed?).  For
     interfacing CVS to an external bug-tracking system, see the
     `rcsinfo' and `verifymsg' files (*note Administrative files::.).

     Another aspect of change control is keeping track of the fact that
     changes to several files were in fact changed together as one
     logical change.  If you check in several files in a single `cvs
     commit' operation, CVS then forgets that those files were checked
     in together, and the fact that they have the same log message is
     the only thing tying them together.  Keeping a GNU style
     `ChangeLog' can help somewhat.

     Another aspect of change control, in some systems, is the ability
     to keep track of the status of each change.  Some changes have
     been written by a developer, others have been reviewed by a second
     developer, and so on.  Generally, the way to do this with CVS is to
     generate a diff (using `cvs diff' or `diff') and email it to
     someone who can then apply it using the `patch' utility.  This is
     very flexible, but depends on mechanisms outside CVS to make sure
     nothing falls through the cracks.

CVS is not an automated testing program
     It should be possible to enforce mandatory use of a testsuite
     using the `commitinfo' file.  I haven't heard a lot about projects
     trying to do that or whether there are subtle gotchas, however.

CVS does not have a builtin process model
     Some systems provide ways to ensure that changes or releases go
     through various steps, with various approvals as needed.
     Generally, one can accomplish this with CVS but it might be a
     little more work.  In some cases you'll want to use the
     `commitinfo', `loginfo', `rcsinfo', or `verifymsg' files, to
     require that certain steps be performed before cvs will allow a
     checkin.  Also consider whether features such as branches and tags
     can be used to perform tasks such as doing work in a development
     tree and then merging certain changes over to a stable tree only
     once they have been proven.


File: cvs.info,  Node: Basic concepts,  Next: A sample session,  Prev: What is CVS?,  Up: Top

Basic concepts
**************

   CVS stores all files in a centralized "repository" (*note
Repository::.).

   The repository contains directories and files, in an arbitrary tree.
The "modules" feature can be used to group together a set of
directories or files into a single entity (*note modules::.).  A
typical usage is to define one module per project.

* Menu:

* Revision numbers::            The meaning of a revision number
* Versions revisions releases::  Terminology used in this manual


File: cvs.info,  Node: Revision numbers,  Next: Versions revisions releases,  Up: Basic concepts

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.2.2.4 !
                    / +---------+    +---------+    +---------+    +---------+
                   /
                  /
     +-----+    +-----+    +-----+    +-----+    +-----+
     ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !      <- The main trunk
     +-----+    +-----+    +-----+    +-----+    +-----+
                     !
                     !
                     !   +---------+    +---------+    +---------+
     Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 !
                         +---------+    +---------+    +---------+

   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,  Prev: Revision numbers,  Up: Basic concepts

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: A sample session,  Next: Repository,  Prev: Basic concepts,  Up: Top

A sample session
****************

   This section describes a typical work-session using CVS.  It assumes
that a repository is set up (*note Repository::.).

   Suppose you are working on a simple compiler.  The source consists
of a handful of C files and a `Makefile'.  The compiler is called `tc'
(Trivial Compiler), and the repository is set up so that there is a
module called `tc'.

* Menu:

* Getting the source::          Creating a workspace
* Committing your changes::     Making your work available to others
* Cleaning up::                 Cleaning up
* Viewing differences::         Viewing differences


File: cvs.info,  Node: Getting the source,  Next: Committing your changes,  Up: A sample session

Getting the source
==================

   The first thing you must do is to get your own working copy of the
source for `tc'.  For this, you use the `checkout' command:

     $ cvs checkout tc

This will create a new directory called `tc' and populate it with the
source files.

     $ cd tc
     $ ls
     CVS         Makefile    backend.c   driver.c    frontend.c  parser.c

   The `CVS' directory is used internally by CVS.  Normally, you should
not modify or remove any of the files in it.

   You start your favorite editor, hack away at `backend.c', and a
couple of hours later you have added an optimization pass to the
compiler.  A note to RCS and SCCS users: There is no need to lock the
files that you want to edit.  *Note Multiple developers::, for an
explanation.


File: cvs.info,  Node: Committing your changes,  Next: Cleaning up,  Prev: Getting the source,  Up: A sample session

Committing your changes
=======================

   When you have checked that the compiler is still compilable you
decide to make a new version of `backend.c'.

     $ cvs commit backend.c

CVS starts an editor, to allow you to enter a log message.  You type in
"Added an optimization pass.", save the temporary file, and exit the
editor.

   The environment variable `$CVSEDITOR' determines which editor is
started.  If `$CVSEDITOR' is not set, then if the environment variable
`$EDITOR' is set, it will be used. If both `$CVSEDITOR' and `$EDITOR'
are not set then the editor defaults to `vi'.  If you want to avoid the
overhead of starting an editor you can specify the log message on the
command line using the `-m' flag instead, like this:

     $ cvs commit -m "Added an optimization pass" backend.c


File: cvs.info,  Node: Cleaning up,  Next: Viewing differences,  Prev: Committing your changes,  Up: A sample session

Cleaning up
===========

   Before you turn to other tasks you decide to remove your working
copy of tc.  One acceptable way to do that is of course

     $ cd ..
     $ rm -r tc

but a better way is to use the `release' command (*note release::.):

     $ cd ..
     $ cvs release -d tc
     M driver.c
     ? tc
     You have [1] altered files in this repository.
     Are you sure you want to release (and delete) module `tc': n
     ** `release' aborted by user choice.

   The `release' command checks that all your modifications have been
committed.  If history logging is enabled it also makes a note in the
history file.  *Note history file::.

   When you use the `-d' flag with `release', it also removes your
working copy.

   In the example above, the `release' command wrote a couple of lines
of output.  `? tc' means that the file `tc' is unknown to CVS.  That is
nothing to worry about: `tc' is the executable compiler, and it should
not be stored in the repository.  *Note cvsignore::, for information
about how to make that warning go away.  *Note release output::, for a
complete explanation of all possible output from `release'.

   `M driver.c' is more serious.  It means that the file `driver.c' has
been modified since it was checked out.

   The `release' command always finishes by telling you how many
modified files you have in your working copy of the sources, and then
asks you for confirmation before deleting any files or making any note
in the history file.

   You decide to play it safe and answer `n RET' when `release' asks
for confirmation.


File: cvs.info,  Node: Viewing differences,  Prev: Cleaning up,  Up: A sample session

Viewing differences
===================

   You do not remember modifying `driver.c', so you want to see what
has happened to that file.

     $ cd tc
     $ cvs diff driver.c

   This command runs `diff' to compare the version of `driver.c' that
you checked out with your working copy.  When you see the output you
remember that you added a command line option that enabled the
optimization pass.  You check it in, and release the module.

     $ cvs commit -m "Added an optimization pass" driver.c
     Checking in driver.c;
     /usr/local/cvsroot/tc/driver.c,v  <--  driver.c
     new revision: 1.2; previous revision: 1.1
     done
     $ cd ..
     $ cvs release -d tc
     ? tc
     You have [0] altered files in this repository.
     Are you sure you want to release (and delete) module `tc': y


File: cvs.info,  Node: Repository,  Next: Starting a new project,  Prev: A sample session,  Up: Top

The Repository
**************

   The CVS "repository" stores a complete copy of all the files and
directories which are under version control.

   Normally, you never access any of the files in the repository
directly.  Instead, you use CVS commands to get your own copy of the
files, and then work on that copy.  When you've finished a set of
changes, you check (or "commit") them back into the repository.  The
repository then contains the changes which you have made, as well as
recording exactly what you changed, when you changed it, and other such
information.

   CVS can access a repository by a variety of means.  It might be on
the local computer, or it might be on a computer across the room or
across the world.  To distinguish various ways to access a repository,
the repository name can start with an "access method".  For example,
the access method `:local:' means to access a repository directory, so
the repository `:local:/usr/local/cvsroot' means that the repository is
in `/usr/local/cvsroot' on the computer running CVS.  For information
on other access methods, see *Note Remote repositories::.

   If the access method is omitted, then if the repository does not
contain `:', then `:local:' is assumed.  If it does contain `:' than
either `:ext:' or `:server:' is assumed.  For example, if you have a
local repository in `/usr/local/cvsroot', you can use
`/usr/local/cvsroot' instead of `:local:/usr/local/cvsroot'.  But if
(under Windows NT, for example) your local repository is
`c:\src\cvsroot', then you must specify the access method, as in
`:local:c:\src\cvsroot'.

   The repository is split in two parts.  `$CVSROOT/CVSROOT' contains
administrative files for CVS.  The other directories contain the actual
user-defined modules.

* Menu:

* Specifying a repository::     Telling CVS where your repository is
* Repository storage::          The structure of the repository
* Intro administrative files::  Defining modules
* Multiple repositories::       Multiple repositories
* Creating a repository::       Creating a repository
* Remote repositories::         Accessing repositories on remote machines
* Read-only access::            Granting read-only access to the repository


File: cvs.info,  Node: Specifying a repository,  Next: Repository storage,  Up: Repository

Telling CVS where your repository is
====================================

   There are a couple of different ways to tell CVS where to find the
repository.  You can name the repository on the command line
explicitly, with the `-d' (for "directory") option:

     cvs -d /usr/local/cvsroot checkout yoyodyne/tc

   Or you can set the `$CVSROOT' environment variable to an absolute
path to the root of the repository, `/usr/local/cvsroot' in this
example.  To set `$CVSROOT', all `csh' and `tcsh' users should have
this line in their `.cshrc' or `.tcshrc' files:

     setenv CVSROOT /usr/local/cvsroot

`sh' and `bash' users should instead have these lines in their
`.profile' or `.bashrc':

     CVSROOT=/usr/local/cvsroot
     export CVSROOT

   A repository specified with `-d' will override the `$CVSROOT'
environment variable.  Once you've checked a working copy out from the
repository, it will remember where its repository is (the information
is recorded in the `CVS/Root' file in the working copy).

   The `-d' option and the `CVS/Root' file both override the `$CVSROOT'
environment variable.  If `-d' option differs from `CVS/Root', the
former is used (and specifying `-d' will cause `CVS/Root' to be
updated).  Of course, for proper operation they should be two ways of
referring to the same repository.


File: cvs.info,  Node: Repository storage,  Next: Intro administrative files,  Prev: Specifying a repository,  Up: Repository

How data is stored in the repository
====================================

   For most purposes it isn't important *how* CVS stores information in
the repository.  In fact, the format has changed in the past, and is
likely to change in the future.  Since in almost all cases one accesses
the repository via CVS commands; such changes need not be disruptive.

   However, in some cases it may be necessary to understand how CVS
stores data in the repository, for example you might need to track down
CVS locks (*note Concurrency::.) or you might need to deal with the
file permissions appropriate for the repository.

* Menu:

* Repository files::            What files are stored in the repository
* File permissions::            File permissions


File: cvs.info,  Node: Repository files,  Next: File permissions,  Up: Repository storage

Where files are stored within the repository
--------------------------------------------

   The overall structure of the repository is a directory tree
corresponding to the directories in the working directory.  For
example, supposing the repository is in `/usr/local/cvsroot', here is a
possible directory tree (showing only the directories):

     /usr
      |
      +--local
      |   |
      |   +--cvsroot
      |   |    |
      |   |    +--CVSROOT
               |      (administrative files)
               |
               +--gnu
               |   |
               |   +--diff
               |   |   (source code to GNU diff)
               |   |
               |   +--rcs
               |   |   (source code to RCS)
               |   |
               |   +--cvs
               |       (source code to CVS)
               |
               +--yoyodyne
                   |
                   +--tc
                   |    |
                   |    +--man
                   |    |
                   |    +--testing
                   |
                   +--(other Yoyodyne software)

   With the directories are "history files" for each file under version
control.  The name of the history file is the name of the corresponding
file with `,v' appended to the end.  Here is what the repository for
the `yoyodyne/tc' directory might look like:

       `$CVSROOT'
         |
         +--yoyodyne
         |   |
         |   +--tc
         |   |   |
                 +--Makefile,v
                 +--backend.c,v
                 +--driver.c,v
                 +--frontend.c,v
                 +--parser.c,v
                 +--man
                 |    |
                 |    +--tc.1,v
                 |
                 +--testing
                      |
                      +--testpgm.t,v
                      +--test2.t,v

   The history files contain, among other things, enough information to
recreate any revision of the file, a log of all commit messages and the
user-name of the person who committed the revision.  The history files
are known as "RCS files", because the first program to store files in
that format was a version control system known as RCS.  For a full
description of the file format, see the `man' page `rcsfile(5)',
distributed with RCS.  This file format has become very common--many
systems other than CVS or RCS can at least import history files in this
format.

   The RCS files used in CVS differ in a few ways from the standard
format.  The biggest difference is magic branches; for more information
see *Note Magic branch numbers::.  Also in CVS the valid tag names are
a subset of what RCS accepts; for CVS's rules see *Note Tags::.


File: cvs.info,  Node: File permissions,  Prev: Repository files,  Up: Repository storage

File permissions
----------------

   All `,v' files are created read-only, and you should not change the
permission of those files.  The directories inside the repository
should be writable by the persons that have permission to modify the
files in each directory.  This normally means that you must create a
UNIX group (see group(5)) consisting of the persons that are to edit
the files in a project, and set up the repository so that it is that
group that owns the directory.

   This means that you can only control access to files on a
per-directory basis.

   Note that users must also have write access to check out files,
because CVS needs to create lock files (*note Concurrency::.).

   Also note that users must have write access to the
`CVSROOT/val-tags' file.  CVS uses it to keep track of what tags are
valid tag names (it is sometimes updated when tags are used, as well as
when they are created, though).

   CVS tries to set up reasonable file permissions for new directories
that are added inside the tree, but you must fix the permissions
manually when a new directory should have different permissions than its
parent directory.  If you set the `CVSUMASK' environment variable that
will control the file permissions which CVS uses in creating directories
and/or files in the repository.  `CVSUMASK' does not affect the file
permissions in the working directory; such files have the permissions
which are typical for newly created files, except that sometimes CVS
creates them read-only (see the sections on watches, *Note Setting a
watch::; -r, *Note Global options::; or CVSREAD, *Note Environment
variables::).

   Since CVS was not written to be run setuid, it is unsafe to try to
run it setuid.  You cannot use the setuid features of RCS together with
CVS.


File: cvs.info,  Node: Intro administrative files,  Next: Multiple repositories,  Prev: Repository storage,  Up: Repository

The administrative files
========================

   The directory `$CVSROOT/CVSROOT' contains some "administrative
files".  *Note Administrative files::, for a complete description.  You
can use CVS without any of these files, but some commands work better
when at least the `modules' file is properly set up.

   The most important of these files is the `modules' file.  It defines
all modules in the repository.  This is a sample `modules' file.

     CVSROOT         CVSROOT
     modules         CVSROOT modules
     cvs             gnu/cvs
     rcs             gnu/rcs
     diff            gnu/diff
     tc              yoyodyne/tc

   The `modules' file is line oriented.  In its simplest form each line
contains the name of the module, whitespace, and the directory where
the module resides.  The directory is a path relative to `$CVSROOT'.
The last four lines in the example above are examples of such lines.

   The line that defines the module called `modules' uses features that
are not explained here.  *Note modules::, for a full explanation of all
the available features.

Editing administrative files
----------------------------

   You edit the administrative files in the same way that you would edit
any other module.  Use `cvs checkout CVSROOT' to get a working copy,
edit it, and commit your changes in the normal way.

   It is possible to commit an erroneous administrative file.  You can
often fix the error and check in a new revision, but sometimes a
particularly bad error in the administrative file makes it impossible
to commit new revisions.


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: Remote repositories,  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--a server with 32M of memory or even
less can handle a fairly large source tree with a fair amount of
activity.  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).  Don't worry about CPU and memory requirements for the
clients--any machine with enough capacity to run the operating system in
question should have little trouble.

   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: Remote repositories,  Next: Read-only access,  Prev: Creating 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:

* 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: Connecting via rsh,  Next: Password authenticated,  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
`anklet.grunge.com', and the server machine is
`chainsaw.brickyard.com'.  On chainsaw, put the following line into the
file `.rhosts' in `bach''s home directory:

     anklet.grunge.com  mozart

   Then test that `rsh' is working with

     rsh -l bach chainsaw.brickyard.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 programs 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 incorrect; 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.brickyard.com', you are ready to go:

     cvs -d :ext:bach@chainsaw.brickyard.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
.................................................

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

   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.  When using the CVS `passwd' file,
the server runs under as the username specified in the the third
argument in the entry, or as the first argument if there is no third
argument (in this way 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.brickyard.com' with the following command:

     cvs -d :pserver:cvs@chainsaw.brickyard.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 *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.brickyard.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.brickyard.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 `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.