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: Top,  Next: Preface,  Up: (dir)



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

* Menu:

* Preface::                     About this manual
* What is CVS?::                What is CVS?
* 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
* Revisions and branches::      Numeric, symbolic, and branch revisions
* Merging::                     How to move changes between branches
* Recursive behavior::          CVS descends directories
* Adding and removing::         Adding/removing/renaming files/directories
* Tracking sources::            Tracking third-party sources
* 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.

* Menu:

* Checklist::                   Checklist for the impatient reader
* Credits::                     A few of the people who wrote this manual
* BUGS::                        Dealing with bugs in CVS or this manual


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.

     See *Note Binary files::, for more details on binary files.

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.  Much of their text
was copied into this manual.  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 is 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>.

   The list of contributors here is not comprehensive; for a more
complete list of who has contributed to this manual see the file
`doc/ChangeLog' in the CVS source distribution.


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

Dealing with bugs in CVS or this manual
=======================================

   Neither CVS nor this manual is perfect, and they probably never will
be.  If you are having trouble using CVS, or think you have found a
bug, there are a number of things you can do about it.  Note that if
the manual is unclear, that can be considered a bug in the manual, so
these problems are often worth doing something about as well as
problems with CVS itself.

   * If you want someone to help you and fix bugs that you report,
     there are companies which will do that for a fee.  Two such
     companies are:

          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
          http://www.signum.se/
          
          Cyclic Software
          United States of America
          http://www.cyclic.com/
          info@cyclic.com

   * If you got CVS through a distributor, such as an operating system
     vendor or a vendor of freeware CD-ROMs, you may wish to see
     whether the distributor provides support.  Often, they will provide
     no support or minimal support, but this may vary from distributor
     to distributor.

   * If you have the skills and time to do so, you may wish to fix the
     bug yourself.  If you wish to submit your fix for inclusion in
     future releases of CVS, see the file HACKING in the CVS source
     distribution.  It contains much more information on the process of
     submitting fixes.

   * There may be resources on the net which can help.  Two good places
     to start are:

          http://www.cyclic.com
          http://www.loria.fr/~molli/cvs-index.html

     If you are so inspired, increasing the information available on
     the net is likely to be appreciated.  For example, before the
     standard CVS distribution worked on Windows 95, there was a web
     page with some explanation and patches for running CVS on Windows
     95, and various people helped out by mentioning this page on
     mailing lists or newsgroups when the subject came up.

   * It is also possible to report bugs to `bug-cvs'.  Note that
     someone may or may not want to do anything with your bug
     report--if you need a solution consider one of the options
     mentioned above.  People probably do want to hear about bugs which
     are particularly severe in consequences and/or easy to fix,
     however.  You can also increase your odds by being as clear as
     possible about the exact nature of the bug and any other relevant
     information.  The way to report bugs is to send email to
     `bug-cvs@prep.ai.mit.edu'.  Note that submissions to `bug-cvs' may
     be distributed under the terms of the GNU Public License, so if
     you don't like this, don't submit them.  There is usually no
     justification for sending mail directly to one of the CVS
     maintainers rather than to `bug-cvs'; those maintainers who want
     to hear about such bug reports read `bug-cvs'.  Also note that
     sending a bug report to other mailing lists or newsgroups is *not*
     a substitute for sending it to `bug-cvs'.  It is fine to discuss
     CVS bugs on whatever forum you prefer, but there are not
     necessarily any maintainers reading bug reports sent anywhere
     except `bug-cvs'.

   People often ask if there is a list of known bugs or whether a
particular bug is a known one.  The file BUGS in the CVS source
distribution is one list of known bugs, but it doesn't necessarily try
to be comprehensive.  Perhaps there will never be a comprehensive,
detailed list of known bugs.


File: cvs.info,  Node: What is CVS?,  Next: A sample session,  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 the newsgroup `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'.

   You can also subscribe to the bug-cvs mailing list, described in
more detail in *Note BUGS::.  To subscribe send mail to
bug-cvs-request@prep.ai.mit.edu.

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: A sample session,  Next: Repository,  Prev: What is CVS?,  Up: Top

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

   As a way of introducing CVS, we'll go through a typical work-session
using CVS.  The first thing to understand is that CVS stores all files
in a centralized "repository" (*note Repository::.); this section
assumes that a repository is set up.

   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'.  This will store your new
`backend.c' in the repository and make it available to anyone else who
is using that same repository.

     $ 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 there is a default which will vary with your operating
system, for example `vi' for unix or `notepad' for Windows NT/95.

   When CVS starts the editor, it includes a list of files which are
modified.  For the CVS client, this list is based on comparing the
modification time of the file against the modification time that the
file had when it was last gotten or updated.  Therefore, if a file's
modification time has changed but its contents have not, it will show
up as modified.  The simplest way to handle this is simply not to worry
about it--if you proceed with the commit CVS will detect that the
contents are not modified and treat it as an unmodified file.  The next
`update' will clue CVS in to the fact that the file is unmodified, and
it will reset its stored timestamp so that the file will not show up in
future editor sessions.

   If you want to avoid 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 into a "working directory", 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.  Note that the repository is
not a subdirectory of the working directory, or vice versa; they should
be in separate locations.

   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 `:' then
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
* Working directory storage::   The structure of working directories
* Intro administrative files::  Defining modules
* Multiple repositories::       Multiple repositories
* Creating a repository::       Creating a repository
* Backing up::                  Backing up a repository
* Moving a repository::         Moving a repository
* Remote repositories::         Accessing repositories on remote machines
* Read-only access::            Granting read-only access to the repository
* Server temporary directory::  The server creates temporary directories


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

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

   There are several 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', `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: Working directory storage,  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
* Windows permissions::         Issues specific to Windows
* Attic::                       Some files are stored in the Attic
* CVSROOT storage::             A few things about CVSROOT are different


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, or the file `doc/RCSFILES' in the CVS source
distribution.  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,  Next: Windows 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).

   Each RCS file will be owned by the user who last checked it in.
This has little significance; what really matters is who owns the
directories.

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

   Note that using the client/server CVS (*note Remote
repositories::.), there is no good way to set `CVSUMASK'; the setting
on the client machine has no effect.  If you are connecting with `rsh',
you can set `CVSUMASK' in `.bashrc' or `.cshrc', as described in the
documentation for your operating system.  This behavior might change in
future versions of CVS; do not rely on the setting of `CVSUMASK' on the
client having no effect.

   Using pserver, you will generally need stricter permissions on the
CVSROOT directory and directories above it in the tree; see *Note
Password authentication security::.

   Some operating systems have features which allow a particular
program to run with the ability to perform operations which the caller
of the program could not.  For example, the set user ID (setuid) or set
group ID (setgid) features of unix or the installed image feature of
VMS.  CVS was not written to use such features and therefore attempting
to install CVS in this fashion will provide protection against only
accidental lapses; anyone who is trying to circumvent the measure will
be able to do so, and depending on how you have set it up may gain
access to more than just CVS.  You may wish to instead consider
pserver.  It shares some of the same attributes, in terms of possibly
providing a false sense of security or opening security holes wider
than the ones you are trying to fix, so read the documentation on
pserver security carefully if you are considering this option (*Note
Password authentication security::).


File: cvs.info,  Node: Windows permissions,  Next: Attic,  Prev: File permissions,  Up: Repository storage

File Permission issues specific to Windows
------------------------------------------

   Some file permission issues are specific to Windows operating
systems (Windows 95, Windows NT, and presumably future operating
systems in this family.  Some of the following might apply to OS/2 but
I'm not sure).

   If you are using local CVS and the repository is on a networked file
system which is served by the Samba SMB server, some people have
reported problems with permissions.  Enabling WRITE=YES in the samba
configuration is said to fix/workaround it.  Disclaimer: I haven't
investigated enough to know the implications of enabling that option,
nor do I know whether there is something which CVS could be doing
differently in order to avoid the problem.  If you find something out,
please let us know as described in *Note BUGS::.


File: cvs.info,  Node: Attic,  Next: CVSROOT storage,  Prev: Windows permissions,  Up: Repository storage

The attic
---------

   You will notice that sometimes CVS stores an RCS file in the
`Attic'.  For example, if the CVSROOT is `/usr/local/cvsroot' and we are
talking about the file `backend.c' in the directory `yoyodyne/tc', then
the file normally would be in

     /usr/local/cvsroot/yoyodyne/tc/backend.c,v

   but if it goes in the attic, it would be in

     /usr/local/cvsroot/yoyodyne/tc/Attic/backend.c,v

   instead.  It should not matter from a user point of view whether a
file is in the attic; CVS keeps track of this and looks in the attic
when it needs to.  But in case you want to know, the rule is that the
RCS file is stored in the attic if and only if the head revision on the
trunk has state `dead'.  A `dead' state means that file has been
removed, or never added, for that revision.  For example, if you add a
file on a branch, it will have a trunk revision in `dead' state, and a
branch revision in a non-`dead' state.


File: cvs.info,  Node: CVSROOT storage,  Prev: Attic,  Up: Repository storage

How files are stored in the CVSROOT directory
---------------------------------------------

   The `$CVSROOT/CVSROOT' directory contains the various administrative
files.  In some ways this directory is just like any other directory in
the repository; it contains RCS files whose names end in `,v', and many
of the CVS commands operate on it the same way.  However, there are a
few differences.

   For each administrative file, in addition to the RCS file, there is
also a checked out copy of the file.  For example, there is an RCS file
`loginfo,v' and a file `loginfo' which contains the latest revision
contained in `loginfo,v'.  When you check in an administrative file,
CVS should print

     cvs commit: Rebuilding administrative file database

and update the checked out copy in `$CVSROOT/CVSROOT'.  If it does not,
there is something wrong (*note BUGS::.).  To add your own files to the
files to be updated in this fashion, you can add them to the
`checkoutlist' administrative file.

   By default, the `modules' file behaves as described above.  If the
modules file is very large, storing it as a flat text file may make
looking up modules slow (I'm not sure whether this is as much of a
concern now as when CVS first evolved this feature; I haven't seen
benchmarks).  Therefore, by making appropriate edits to the CVS source
code one can store the modules file in a database which implements the
`ndbm' interface, such as Berkeley db or GDBM.  If this option is in
use, then the modules database will be stored in the files `modules.db',
`modules.pag', and/or `modules.dir'.

   For information on the meaning of the various administrative files,
see *Note Administrative files::.


File: cvs.info,  Node: Working directory storage,  Next: Intro administrative files,  Prev: Repository storage,  Up: Repository

How data is stored in the working directory
===========================================

   While we are discussing CVS internals which may become visible from
time to time, we might as well talk about what CVS puts in the `CVS'
directories in the working directories.  As with the repository, CVS
handles this information and one can usually access it via CVS
commands.  But in some cases it may be useful to look at it, and other
programs, such as the `jCVS' graphical user interface or the `VC'
package for emacs, may need to look at it.  Such programs should follow
the recommendations in this section if they hope to be able to work
with other programs which use those files, including future versions of
the programs just mentioned and the command-line CVS client.

   The `CVS' directory contains several files.  Programs which are
reading this directory should silently ignore files which are in the
directory but which are not documented here, to allow for future
expansion.

`Root'
     This file contains the current CVS root, as described in *Note
     Specifying a repository::.

`Repository'
     This file contains the directory within the repository which the
     current directory corresponds with.  It can be either an absolute
     pathname or a relative pathname; CVS has had the ability to read
     either format since at least version 1.3 or so.  The relative
     pathname is relative to the root, and is the more sensible
     approach, but the absolute pathname is quite common and
     implementations should accept either.  For example, after the
     command

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

     `Root' will contain

          :local:/usr/local/cvsroot

     and `Repository' will contain either

          /usr/local/cvsroot/yoyodyne/tc

     or

          yoyodyne/tc

`Entries'
     This file lists the files and directories in the working
     directory.  It is a text file according to the conventions
     appropriate for the operating system in question.  The first
     character of each line indicates what sort of line it is.  If the
     character is unrecognized, programs reading the file should
     silently skip that line, to allow for future expansion.

     If the first character is `/', then the format is:

          /NAME/REVISION/TIMESTAMP[+CONFLICT]/OPTIONS/TAGDATE

     where `[' and `]' are not part of the entry, but instead indicate
     that the `+' and conflict marker are optional.  NAME is the name
     of the file within the directory.  REVISION is the revision that
     the file in the working derives from, or `0' for an added file, or
     `-' followed by a revision for a removed file.  TIMESTAMP is the
     timestamp of the file at the time that CVS created it; if the
     timestamp differs with the actual modification time of the file it
     means the file has been modified.  It is in Universal Time (UT),
     stored in the format used by the ISO C asctime() function (for
     example, `Sun Apr  7 01:29:26 1996').  One may write a string
     which is not in that format, for example, `Result of merge', to
     indicate that the file should always be considered to be modified.
     This is not a special case; to see whether a file is modified a
     program should take the timestamp of the file and simply do a
     string compare with TIMESTAMP.  CONFLICT indicates that there was
     a conflict; if it is the same as the actual modification time of
     the file it means that the user has obviously not resolved the
     conflict.  OPTIONS contains sticky options (for example `-kb' for a
     binary file).  TAGDATE contains `T' followed by a tag name, or `D'
     for a date, followed by a sticky tag or date.  Note that if
     TIMESTAMP contains a pair of timestamps separated by a space,
     rather than a single timestamp, you are dealing with a version of
     CVS earlier than CVS 1.5 (not documented here).

     If the first character of a line in `Entries' is `D', then it
     indicates a subdirectory.  `D' on a line all by itself indicates
     that the program which wrote the `Entries' file does record
     subdirectories (therefore, if there is such a line and no other
     lines beginning with `D', one knows there are no subdirectories).
     Otherwise, the line looks like:

          D/NAME/FILLER1/FILLER2/FILLER3/FILLER4

     where NAME is the name of the subdirectory, and all the FILLER
     fields should be silently ignored, for future expansion.  Programs
     which modify `Entries' files should preserve these fields.

`Entries.Log'
     This file does not record any information beyond that in
     `Entries', but it does provide a way to update the information
     without having to rewrite the entire `Entries' file, including the
     ability to preserve the information even if the program writing
     `Entries' and `Entries.Log' abruptly aborts.  Programs which are
     reading the `Entries' file should also check for `Entries.Log'.
     If the latter exists, they should read `Entries' and then apply
     the changes mentioned in `Entries.Log'.  After applying the
     changes, the recommended practice is to rewrite `Entries' and then
     delete `Entries.Log'.  The format of a line in `Entries.Log' is a
     single character command followed by a space followed by a line in
     the format specified for a line in `Entries'.  The single
     character command is `A' to indicate that the entry is being added,
     `R' to indicate that the entry is being removed, or any other
     character to indicate that the entire line in `Entries.Log' should
     be silently ignored (for future expansion).  If the second
     character of the line in `Entries.Log' is not a space, then it was
     written by an older version of CVS (not documented here).

`Entries.Backup'
     This is a temporary file.  Recommended usage is to write a new
     entries file to `Entries.Backup', and then to rename it
     (atomically, where possible) to `Entries'.

`Entries.Static'
     The only relevant thing about this file is whether it exists or
     not.  If it exists, then it means that only part of a directory
     was gotten and CVS will not create additional files in that
     directory.  To clear it, use the `update' command with the `-d'
     option, which will get the additional files and remove
     `Entries.Static'.

`Tag'
     This file contains per-directory sticky tags or dates.  The first
     character is `T' for a branch tag, `N' for a non-branch tag, or
     `D' for a date, or another character to mean the file should be
     silently ignored, for future expansion.  This character is
     followed by the tag or date.  Note that per-directory sticky tags
     or dates are used for things like applying to files which are
     newly added; they might not be the same as the sticky tags or
     dates on individual files.  For general information on sticky tags
     and dates, see *Note Sticky tags::.

`Checkin.prog'
`Update.prog'
     These files store the programs specified by the `-i' and `-u'
     options in the modules file, respectively.

`Notify'
     This file stores notifications (for example, for `edit' or
     `unedit') which have not yet been sent to the server.  Its format
     is not yet documented here.

`Notify.tmp'
     This file is to `Notify' as `Entries.Backup' is to `Entries'.
     That is, to write `Notify', first write the new contents to
     `Notify.tmp' and then (atomically where possible), rename it to
     `Notify'.

`Base'
     If watches are in use, then an `edit' command stores the original
     copy of the file in the `Base' directory.  This allows the
     `unedit' command to operate even if it is unable to communicate
     with the server.

`Baserev'
     The file lists the revision for each of the files in the `Base'
     directory.  The format is:

          BNAME/REV/EXPANSION

     where EXPANSION should be ignored, to allow for future expansion.

`Baserev.tmp'
     This file is to `Baserev' as `Entries.Backup' is to `Entries'.
     That is, to write `Baserev', first write the new contents to
     `Baserev.tmp' and then (atomically where possible), rename it to
     `Baserev'.

`Template'
     This file contains the template specified by the `rcsinfo' file
     (*note rcsinfo::.).  It is only used by the client; the
     non-client/server CVS consults `rcsinfo' directly.


File: cvs.info,  Node: Intro administrative files,  Next: Multiple repositories,  Prev: Working directory 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.

