\input texinfo  @c -*-texinfo-*-
@comment Documentation for CVS.
@setfilename cvs.info
@macro copyleftnotice
@noindent
Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
                       2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
                       Free Software Foundation, Inc.

@multitable @columnfractions .12 .88
@item Portions
@item @tab Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005,
				  2006, 2007 Derek R. Price,
@item @tab Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007
                                  Ximbiot @url{http://ximbiot.com},
@item @tab Copyright @copyright{} 1992, 1993, 1999 Signum Support AB,
@item @tab and Copyright @copyright{} others.
@end multitable

@ignore
Permission is granted to process this file through Tex and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
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
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 this permission notice may be stated in a translation
approved by the Free Software Foundation.
@end macro

@comment This file is part of the CVS distribution.

@comment CVS is free software; you can redistribute it and/or modify
@comment it under the terms of the GNU General Public License as published by
@comment the Free Software Foundation; either version 2, or (at your option)
@comment any later version.

@comment CVS is distributed in the hope that it will be useful,
@comment but WITHOUT ANY WARRANTY; without even the implied warranty of
@comment MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@comment GNU General Public License for more details.

@c See ../README for A4 vs. US letter size.
@c When we provided A4 postscript, and people tried to
@c print it on US letter, the usual complaint was that the
@c page numbers would get cut off.
@c If one prints US letter on A4, reportedly there is
@c some extra space at the top and/or bottom, and the side
@c margins are a bit narrow, but no text is lost.
@c
@c See
@c http://www.ft.uni-erlangen.de/~mskuhn/iso-paper.html
@c for more on paper sizes.  Insuring that margins are
@c big enough to print on either A4 or US letter does
@c indeed seem to be the usual approach (RFC2346).

@c This document seems to get overfull hboxes with some
@c frequency (probably because the tendency is to
@c sanity-check it with "make info" and run TeX less
@c often).  The big ugly boxes just seem to add insult
@c to injury, and I'm not aware of them helping to fix
@c the overfull hboxes at all.
@finalout

@include version.texi
@settitle CVS---Concurrent Versions System v@value{VERSION}
@setchapternewpage odd

@c -- TODO list:
@c -- Fix all lines that match "^@c -- "
@c -- Also places marked with FIXME should be manual
@c problems (as opposed to FIXCVS for CVS problems).

@c @splitrcskeyword{} is used to avoid keyword expansion.  It is replaced by
@c @asis when generating info and dvi, and by <i></i> in the generated html,
@c such that keywords are not expanded in the generated html. 
@ifnothtml
@macro splitrcskeyword {arg}
@asis{}\arg\
@end macro
@end ifnothtml

@ifhtml
@macro splitrcskeyword {arg}
@i{}\arg\
@end macro
@end ifhtml

@dircategory GNU Packages
@direntry
* CVS: (cvs).                   Concurrent Versions System
@end direntry
@dircategory Individual utilities
@direntry
* cvs: (cvs)CVS commands.       Concurrent Versions System
@end direntry

@comment The titlepage section does not appear in the Info file.
@titlepage
@sp 4
@comment The title is printed in a large font.
@center @titlefont{Version Management}
@sp
@center @titlefont{with}
@sp
@center @titlefont{CVS}
@sp 2
@center for @sc{cvs} @value{VERSION}
@comment -release-
@sp 3
@center Per Cederqvist et al

@comment  The following two commands start the copyright page
@comment  for the printed manual.  This will not appear in the Info file.
@page
@vskip 0pt plus 1filll
@copyleftnotice
@end titlepage

@summarycontents

@contents

@comment ================================================================
@comment                   The real text starts here
@comment ================================================================

@ifnottex
@c ---------------------------------------------------------------------
@node    Top
@top

This info manual describes how to use and administer
@sc{cvs} version @value{VERSION}.
@end ifnottex

@ifinfo
@copyleftnotice
@end ifinfo

@c This menu is pretty long.  Not sure how easily that
@c can be fixed (no brilliant ideas right away)...
@menu
* Overview::                    An introduction to CVS
* Repository::                  Where all your sources are stored
* Starting a new project::      Starting a project with CVS
* Revisions::                   Numeric and symbolic names for revisions
* Branching and merging::       Diverging/rejoining branches of development
* Recursive behavior::          CVS descends directories
* Adding and removing::         Adding/removing/renaming files/directories
* History browsing::            Viewing the history of files in various ways

CVS and the Real World.
-----------------------
* Binary files::                CVS can handle binary files
* Multiple developers::         How CVS helps a group of developers
* Revision management::         Policy questions for revision management
* Keyword substitution::        CVS can include the revision inside the file
* Tracking sources::            Tracking third-party sources
* Builds::                      Issues related to CVS and builds
* Special Files::		Devices, links and other non-regular files

References.
-----------
* 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
* Compatibility::               Upgrading CVS versions
* Troubleshooting::             Some tips when nothing works
* Credits::                     Some of the contributors to this manual
* BUGS::                        Dealing with bugs in CVS or this manual
* Index::                       Index
@end menu

@c ---------------------------------------------------------------------
@node Overview
@chapter Overview
@cindex Overview

This chapter is for people who have never used
@sc{cvs}, and perhaps have never used version control
software before.

If you are already familiar with @sc{cvs} and are just
trying to learn a particular feature or remember a
certain command, you can probably skip everything here.

@menu
* What is CVS?::                What you can do with @sc{cvs}
* What is CVS not?::            Problems @sc{cvs} doesn't try to solve
* A sample session::            A tour of basic @sc{cvs} usage
@end menu

@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@node What is CVS?
@section What is CVS?
@cindex What is CVS?
@cindex Introduction to CVS
@cindex CVS, introduction to

@sc{cvs} is a version control system.  Using it, you can
record the history of your source files.

@c -- ///
@c -- ///Those who cannot remember the past are condemned to repeat it.
@c -- ///               -- George Santayana
@c -- //////

@c -- Insert history  quote here!
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 @sc{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.  @sc{cvs}
stores all the versions of a file in a single file in a
clever way that only stores the differences between
versions.

@sc{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 @sc{gnu} Emacs, try to make sure that
two people never modify the same file at the
same time.  Unfortunately, if someone is using another
editor, that safeguard will not work.  @sc{cvs} solves this problem
by insulating the different developers from each other.  Every
developer works in his own directory, and @sc{cvs} merges
the work when each developer is done.

@cindex History of CVS
@cindex CVS, history of
@cindex Credits (CVS program)
@cindex Contributors (CVS program)
@sc{cvs} started out as a bunch of shell scripts written by
Dick Grune, posted to the newsgroup
@code{comp.sources.unix} in the volume 6
release of July, 1986.  While no actual code from
these shell scripts is present in the current version
of @sc{cvs} much of the @sc{cvs} conflict resolution algorithms
come from them.

In April, 1989, Brian Berliner designed and coded @sc{cvs}.
Jeff Polk later helped Brian with the design of the @sc{cvs}
module and vendor branch support.

@cindex Source, getting CVS source
You can get @sc{cvs} in a variety of ways, including
free download from the Internet.  For more information
on downloading @sc{cvs} and other @sc{cvs} topics, see:

@example
@url{http://cvs.nongnu.org/}
@end example

@cindex Mailing list
@cindex List, mailing list
@cindex Newsgroups
There is a mailing list, known as @email{info-cvs@@nongnu.org},
devoted to @sc{cvs}.  To subscribe or
unsubscribe
write to
@email{info-cvs-request@@nongnu.org}.
If you prefer a Usenet group, there is a one-way mirror (posts to the email
list are usually sent to the news group, but not vice versa) of
@email{info-cvs@@nongnu.org} at @url{news:gnu.cvs.help}.  The right
Usenet group for posts is @url{news:comp.software.config-mgmt} which is for
@sc{cvs} discussions (along with other configuration
management systems).  In the future, it might be
possible to create a
@code{comp.software.config-mgmt.cvs}, but probably only
if there is sufficient @sc{cvs} traffic on
@url{news:comp.software.config-mgmt}.
@c Other random data is that the tale was very
@c skeptical of comp.software.config-mgmt.cvs when the
@c subject came up around 1995 or so (for one
@c thing, because creating it would be a "reorg" which
@c would need to take a more comprehensive look at the
@c whole comp.software.config-mgmt.* hierarchy).

You can also subscribe to the @email{bug-cvs@@nongnu.org} mailing list,
described in more detail in @ref{BUGS}.  To subscribe
send mail to @email{bug-cvs-request@@nongnu.org}.  There is a two-way
Usenet mirror (posts to the Usenet group are usually sent to the email list and
vice versa) of @email{bug-cvs@@nongnu.org} named @url{news:gnu.cvs.bug}.

@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@node What is CVS not?
@section What is CVS not?
@cindex What is CVS not?

@sc{cvs} can do a lot of things for you, but it does
not try to be everything for everyone.

@table @asis
@item @sc{cvs} is not a build system.

Though the structure of your repository and modules
file interact with your build system
(e.g. @file{Makefile}s), they are essentially
independent.

@sc{cvs} does not dictate how you build anything.  It
merely stores files for retrieval in a tree structure
you devise.

@sc{cvs} does not dictate how to use disk space in the
checked out working directories.  If you write your
@file{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,
@code{VPATH} in @file{Makefile}s, etc.), you can
arrange your disk usage however you like.

But you have to remember that @emph{any} such system is
a lot of work to construct and maintain.  @sc{cvs} does
not address the issues involved.

Of course, you should place the tools created to
support such a build system (scripts, @file{Makefile}s,
etc.) under @sc{cvs}.

Figuring out what files need to be rebuilt when
something changes is, again, something to be handled
outside the scope of @sc{cvs}.  One traditional
approach is to use @code{make} for building, and use
some automated tool for generating the dependencies which
@code{make} uses.

See @ref{Builds}, for more information on doing builds
in conjunction with @sc{cvs}.

@item @sc{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, @sc{cvs} can't help.

@sc{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.

@item @sc{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.

@sc{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 @dfn{conflict} is purely textual, arising
when two changes to the same base file are near enough
to spook the merge (i.e., @code{diff3}) command.

@sc{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
@code{X} defined in file @file{A}.  At the same time,
someone edits file @file{B}, adding new calls to
function @code{X} using the old arguments.  You are
outside the realm of @sc{cvs}'s competence.

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


@item @sc{cvs} does not have change control

Change control refers to a number of things.  First of
all it can mean @dfn{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
@sc{cvs} to an external bug-tracking system, see the
@file{rcsinfo} and @file{verifymsg} files
(@pxref{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 @code{cvs commit}
operation, @sc{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 @sc{gnu} style @file{ChangeLog}
can help somewhat.
@c FIXME: should have an xref to a section which talks
@c more about keeping ChangeLog's with CVS, but that
@c section hasn't been written yet.

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 @sc{cvs} is to
generate a diff (using @code{cvs diff} or @code{diff})
and email it to someone who can then apply it using the
@code{patch} utility.  This is very flexible, but
depends on mechanisms outside @sc{cvs} to make sure
nothing falls through the cracks.

@item @sc{cvs} is not an automated testing program

It should be possible to enforce mandatory use of a
test suite using the @code{commitinfo} file.  I haven't
heard a lot about projects trying to do that or whether
there are subtle gotchas, however.

@item @sc{cvs} does not have a built-in 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 @sc{cvs} but it might be a little more work.
In some cases you'll want to use the @file{commitinfo},
@file{loginfo}, @file{rcsinfo}, or @file{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.
@end table

@c ---------------------------------------------------------------------
@node A sample session
@section A sample session
@cindex Example of a work-session
@cindex Getting started
@cindex Work-session, example of
@cindex tc, Trivial Compiler (example)
@cindex Trivial Compiler (example)

@c I think an example is a pretty good way to start.  But
@c somewhere in here, maybe after the sample session,
@c we need something which is kind of
@c a "roadmap" which is more directed at sketching out
@c the functionality of CVS and pointing people to
@c various other parts of the manual.  As it stands now
@c people who read in order get dumped right into all
@c manner of hair regarding remote repositories,
@c creating a repository, etc.
@c
@c The following was in the old Basic concepts node.  I don't
@c know how good a job it does at introducing modules,
@c or whether they need to be introduced so soon, but
@c something of this sort might go into some
@c introductory material somewhere.
@ignore
@cindex Modules (intro)
The repository contains directories and files, in an
arbitrary tree.  The @dfn{modules} feature can be used
to group together a set of directories or files into a
single entity (@pxref{modules}).  A typical usage is to
define one module per project.
@end ignore

As a way of introducing @sc{cvs}, we'll go through a
typical work-session using @sc{cvs}.  The first thing
to understand is that @sc{cvs} stores all files in a
centralized @dfn{repository} (@pxref{Repository}); this
section assumes that a repository is set up.
@c I'm not sure that the sentence concerning the
@c repository quite tells the user what they need to
@c know at this point.  Might need to expand on "centralized"
@c slightly (maybe not here, maybe further down in the example?)

Suppose you are working on a simple compiler.  The source
consists of a handful of C files and a @file{Makefile}.
The compiler is called @samp{tc} (Trivial Compiler),
and the repository is set up so that there is a module
called @samp{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
@end menu

@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@node Getting the source
@subsection Getting the source
@cindex Getting the source
@cindex Checking out source
@cindex Fetching source
@cindex Source, getting from CVS
@cindex Checkout, example

The first thing you must do is to get your own working copy of the
source for @samp{tc}.  For this, you use the @code{checkout} command:

@example
$ cvs checkout tc
@end example

@noindent
This will create a new directory called @file{tc} and populate it with
the source files.

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

The @file{CVS} directory is used internally by
@sc{cvs}.  Normally, you should not modify or remove
any of the files in it.

You start your favorite editor, hack away at @file{backend.c}, and a couple
of hours later you have added an optimization pass to the compiler.
A note to @sc{rcs} and @sc{sccs} users: There is no need to lock the files that
you want to edit.  @xref{Multiple developers}, for an explanation.

@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@node Committing your changes
@subsection Committing your changes
@cindex Committing changes to files
@cindex Log message entry

When you have checked that the compiler is still compilable you decide
to make a new version of @file{backend.c}.  This will
store your new @file{backend.c} in the repository and
make it available to anyone else who is using that same
repository.

@example
$ cvs commit backend.c
@end example

@noindent
@sc{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.

@cindex CVSEDITOR, environment variable
@cindex EDITOR, environment variable
The environment variable @code{$CVSEDITOR} determines
which editor is started.  If @code{$CVSEDITOR} is not
set, then if the environment variable @code{$EDITOR} is
set, it will be used. If both @code{$CVSEDITOR} and
@code{$EDITOR} are not set then there is a default
which will vary with your operating system, for example
@code{vi} for unix or @code{notepad} for Windows
NT/95.

@cindex VISUAL, environment variable
In addition, @sc{cvs} checks the @code{$VISUAL} environment
variable.  Opinions vary on whether this behavior is desirable and
whether future releases of @sc{cvs} should check @code{$VISUAL} or
ignore it.  You will be OK either way if you make sure that
@code{$VISUAL} is either unset or set to the same thing as
@code{$EDITOR}.

@c This probably should go into some new node
@c containing detailed info on the editor, rather than
@c the intro.  In fact, perhaps some of the stuff with
@c CVSEDITOR and -m and so on should too.
When @sc{cvs} starts the editor, it includes a list of
files which are modified.  For the @sc{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 @sc{cvs} will detect that
the contents are not modified and treat it as an
unmodified file.  The next @code{update} will clue
@sc{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.
@c FIXCVS: Might be nice if "commit" and other commands
@c would reset that timestamp too, but currently commit
@c doesn't.
@c FIXME: Need to talk more about the process of
@c prompting for the log message.  Like show an example
@c of what it pops up in the editor, for example.  Also
@c a discussion of how to get the "a)bort, c)ontinue,
@c e)dit" prompt and what to do with it.  Might also
@c work in the suggestion that if you want a diff, you
@c should make it before running commit (someone
@c suggested that the diff pop up in the editor.  I'm
@c not sure that is better than telling people to run
@c "cvs diff" first if that is what they want, but if
@c we want to tell people that, the manual possibly
@c should say it).

If you want to avoid
starting an editor you can specify the log message on
the command line using the @samp{-m} flag instead, like
this:

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

@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@node Cleaning up
@subsection Cleaning up
@cindex Cleaning up
@cindex Working copy, removing
@cindex Removing your working copy
@cindex Releasing your working copy

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

@example
$ cd ..
$ rm -r tc
@end example

@noindent
but a better way is to use the @code{release} command (@pxref{release}):

@example
$ 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) directory `tc': n
** `release' aborted by user choice.
@end example

The @code{release} command checks that all your modifications have been
committed.  If history logging is enabled it also makes a note in the
history file.  @xref{history file}.

When you use the @samp{-d} flag with @code{release}, it
also removes your working copy.

In the example above, the @code{release} command wrote a couple of lines
of output.  @samp{? tc} means that the file @file{tc} is unknown to @sc{cvs}.
That is nothing to worry about: @file{tc} is the executable compiler,
and it should not be stored in the repository.  @xref{cvsignore},
for information about how to make that warning go away.
@xref{release output}, for a complete explanation of
all possible output from @code{release}.

@samp{M driver.c} is more serious.  It means that the
file @file{driver.c} has been modified since it was
checked out.

The @code{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 @kbd{n @key{RET}}
when @code{release} asks for confirmation.

@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@node Viewing differences
@subsection Viewing differences
@cindex Viewing differences
@cindex Diff

You do not remember modifying @file{driver.c}, so you want to see what
has happened to that file.

@example
$ cd tc
$ cvs diff driver.c
@end example

This command runs @code{diff} to compare the version of @file{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.
@c FIXME: we haven't yet defined the term "check in".

@example
$ 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) directory `tc': y
@end example

@c ---------------------------------------------------------------------
@node Repository
@chapter The Repository
@cindex Repository (intro)
@cindex Repository, example
@cindex Layout of repository
@cindex Typical repository
@cindex /usr/local/cvsroot, as example repository
@cindex cvsroot

The @sc{cvs} @dfn{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 @sc{cvs}
commands to get your own copy of the files into a
@dfn{working directory}, and then
work on that copy.  When you've finished a set of
changes, you check (or @dfn{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.
@c Need some example, e.g. repository
@c /usr/local/cvsroot; working directory
@c /home/joe/sources.  But this node is too long
@c as it is; need a little reorganization...

@cindex :local:, setting up
@sc{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 @dfn{access method}.
For example, the access method @code{:local:} means to
access a repository directory, so the repository
@code{:local:/usr/local/cvsroot} means that the
repository is in @file{/usr/local/cvsroot} on the
computer running @sc{cvs}.  For information on other
access methods, see @ref{Remote repositories}.

@c Can se say this more concisely?  Like by passing
@c more of the buck to the Remote repositories node?
If the access method is omitted, then if the repository
starts with @samp{/}, then @code{:local:} is
assumed.  If it does not start with @samp{/} then either
@code{:ext:} or @code{:server:} is assumed.  For
example, if you have a local repository in
@file{/usr/local/cvsroot}, you can use
@code{/usr/local/cvsroot} instead of
@code{:local:/usr/local/cvsroot}.  But if (under
Windows NT, for example) your local repository is
@file{c:\src\cvsroot}, then you must specify the access
method, as in @code{:local:c:/src/cvsroot}.

@c This might appear to go in Repository storage, but
@c actually it is describing something which is quite
@c user-visible, when you do a "cvs co CVSROOT".  This
@c isn't necessary the perfect place for that, though.
The repository is split in two parts.  @file{$CVSROOT/CVSROOT} contains
administrative files for @sc{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
@end menu

@node Specifying a repository
@section Telling CVS where your repository is

There are several ways to tell @sc{cvs}
where to find the repository.  You can name the
repository on the command line explicitly, with the
@code{-d} (for "directory") option:

@example
cvs -d /usr/local/cvsroot checkout yoyodyne/tc
@end example

@cindex .profile, setting CVSROOT in
@cindex .cshrc, setting CVSROOT in
@cindex .tcshrc, setting CVSROOT in
@cindex .bashrc, setting CVSROOT in
@cindex CVSROOT, environment variable
        Or you can set the @code{$CVSROOT} environment
variable to an absolute path to the root of the
repository, @file{/usr/local/cvsroot} in this example.
To set @code{$CVSROOT}, @code{csh} and @code{tcsh}
users should have this line in their @file{.cshrc} or
@file{.tcshrc} files:

@example
setenv CVSROOT /usr/local/cvsroot
@end example

@noindent
@code{sh} and @code{bash} users should instead have these lines in their
@file{.profile} or @file{.bashrc}:

@example
CVSROOT=/usr/local/cvsroot
export CVSROOT
@end example

@cindex Root file, in CVS directory
@cindex CVS/Root file
        A repository specified with @code{-d} will
override the @code{$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
@file{CVS/Root} file in the working copy).

The @code{-d} option and the @file{CVS/Root} file both
override the @code{$CVSROOT} environment variable.  If
@code{-d} option differs from @file{CVS/Root}, the
former is used.  Of course, for proper operation they
should be two ways of referring to the same repository.

@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@node Repository storage
@section How data is stored in the repository
@cindex Repository, how data is stored

For most purposes it isn't important @emph{how}
@sc{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 @sc{cvs} commands, such
changes need not be disruptive.

However, in some cases it may be necessary to
understand how @sc{cvs} stores data in the repository,
for example you might need to track down @sc{cvs} locks
(@pxref{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
* CVS in repository::           Additional information in CVS directory
* Locks::                       CVS locks control concurrent accesses
* CVSROOT storage::             A few things about CVSROOT are different
@end menu

@node Repository files
@subsection Where files are stored within the repository

@c @cindex Filenames, legal
@c @cindex Legal filenames
@c Somewhere we need to say something about legitimate
@c characters in filenames in working directory and
@c repository.  Not "/" (not even on non-unix).  And
@c here is a specific set of issues:
@c 	Files starting with a - are handled inconsistently. They can not
@c   be added to a repository with an add command, because it they are
@c   interpreted as a switch. They can appear in a repository if they are
@c   part of a tree that is imported. They can not be removed from the tree
@c   once they are there.
@c Note that "--" *is* supported (as a
@c consequence of using GNU getopt).  Should document
@c this somewhere ("Common options"?).  The other usual technique,
@c "./-foo", isn't as effective, at least for "cvs add"
@c which doesn't support pathnames containing "/".

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

@example
/usr/local/cvsroot
@end example

@noindent
here is a possible directory tree (showing only the
directories):

@example
@t{/usr}
 |
 +--@t{local}
 |   |
 |   +--@t{cvsroot}
 |   |    |
 |   |    +--@t{CVSROOT}
          |      (administrative files)
          |
          +--@t{gnu}
          |   |
          |   +--@t{diff}
          |   |   (source code to @sc{gnu} diff)
          |   |
          |   +--@t{rcs}
          |   |   (source code to @sc{rcs})
          |   |
          |   +--@t{cvs}
          |       (source code to @sc{cvs})
          |
          +--@t{yoyodyne}
              |
              +--@t{tc}
              |    |
              |    +--@t{man}
              |    |
              |    +--@t{testing}
              |
              +--(other Yoyodyne software)
@end example

With the directories are @dfn{history files} for each file
under version control.  The name of the history file is
the name of the corresponding file with @samp{,v}
appended to the end.  Here is what the repository for
the @file{yoyodyne/tc} directory might look like:
@c FIXME: Should also mention CVS (CVSREP)
@c FIXME? Should we introduce Attic with an xref to
@c Attic?  Not sure whether that is a good idea or not.
@example
  @code{$CVSROOT}
    |
    +--@t{yoyodyne}
    |   |
    |   +--@t{tc}
    |   |   |
            +--@t{Makefile,v}
            +--@t{backend.c,v}
            +--@t{driver.c,v}
            +--@t{frontend.c,v}
            +--@t{parser.c,v}
            +--@t{man}
            |    |
            |    +--@t{tc.1,v}
            |
            +--@t{testing}
                 |
                 +--@t{testpgm.t,v}
                 +--@t{test2.t,v}
@end example

@cindex History files
@cindex RCS history files
@c The first sentence, about what history files
@c contain, is kind of redundant with our intro to what the
@c repository does in node Repository....
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 @dfn{RCS files}, because the first program to
store files in that format was a version control system
known as @sc{rcs}.  For a full
description of the file format, see the @code{man} page
@cite{rcsfile(5)}, distributed with @sc{rcs}, or the
file @file{doc/RCSFILES} in the @sc{cvs} source
distribution.  This
file format has become very common---many systems other
than @sc{cvs} or @sc{rcs} can at least import history
files in this format.
@c FIXME: Think about including documentation for this
@c rather than citing it?  In the long run, getting
@c this to be a standard (not sure if we can cope with
@c a standards process as formal as IEEE/ANSI/ISO/etc,
@c though...) is the way to go, so maybe citing is
@c better.

The @sc{rcs} files used in @sc{cvs} differ in a few
ways from the standard format.  The biggest difference
is magic branches; for more information see @ref{Magic
branch numbers}.  Also in @sc{cvs} the valid tag names
are a subset of what @sc{rcs} accepts; for @sc{cvs}'s
rules see @ref{Tags}.

@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
@node File permissions
@subsection File permissions
@c -- Move this to @node Creating a repository or similar
@cindex Security, file permissions in repository
@cindex File permissions, general
@cindex Permissions, general
@c FIXME: we need to somehow reflect "permissions in
@c repository" versus "permissions in working
@c directory" in the index entries.
@cindex Group, UNIX file permissions, in repository
@cindex Read-only files, in repository
All @samp{,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.
(On some systems, you also need to set the set-group-ID-on-execution bit
on the repository directories (see chmod(1)) so that newly-created files
and directories get the group-ID of the parent directory rather than
that of the current process.)

@c See also comment in commitinfo node regarding cases
@c which are really awkward with unix groups.

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 @sc{cvs} needs to create lock files
(@pxref{Concurrency}).  You can use LockDir in CVSROOT/config
to put the lock files somewhere other than in the repository
if you want to allow read-only access to some directories
(@pxref{config}).

@c CVS seems to use CVSUMASK in picking permissions for
@c val-tags, but maybe we should say more about this.
@c Like val-tags gets created by someone who doesn't
@c have CVSUMASK set right?
@cindex CVSROOT/val-tags file, and read-only access to projects
@cindex val-tags file, and read-only access to projects
Also note that users must have write access to the
@file{CVSROOT/val-tags} file.  @sc{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 @sc{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.

@cindex CVSUMASK, environment variable
@cindex Umask, for repository files
@sc{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 @code{CVSUMASK}
environment variable, that will control the file
permissions which @sc{cvs} uses in creating directories
and/or files in the repository.  @code{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
@sc{cvs} creates them read-only (see the sections on
watches, @ref{Setting a watch}; -r, @ref{Global
options}; or @code{CVSREAD}, @ref{Environment variables}).
@c FIXME: Need more discussion of which
@c group should own the file in the repository.
@c Include a somewhat detailed example of the usual
@c case where CVSUMASK is 007, the developers are all
@c in a group, and that group owns stuff in the
@c repository.  Need to talk about group ownership of
@c newly-created directories/files (on some unices,
@c such as SunOS4, setting the setgid bit on the
@c directories will make files inherit the directory's
@c group.  On other unices, your mileage may vary.  I
@c can't remember what POSIX says about this, if
@c anything).

Note that using the client/server @sc{cvs}
(@pxref{Remote repositories}), there is no good way to
set @code{CVSUMASK}; the setting on the client machine
has no effect.  If you are connecting with @code{rsh}, you
can set @code{CVSUMASK} in @file{.bashrc} or @file{.cshrc}, as
described in the documentation for your operating
system.  This behavior might change in future versions
of @sc{cvs}; do not rely on the setting of
@code{CVSUMASK} on the client having no effect.
@c FIXME: need to explain what a umask is or cite
@c someplace which does.
@c
@c There is also a larger (largely separate) issue
@c about the meaning of CVSUMASK in a non-unix context.
@c For example, whether there is
@c an equivalent which fits better into other
@c protection schemes like POSIX.6, VMS, &c.
@c
@c FIXME: Need one place which discusses this
@c read-only files thing.  Why would one use -r or
@c CVSREAD?  Why would one use watches?  How do they
@c interact?
@c
@c FIXME: We need to state
@c whether using CVSUMASK removes the need for manually
@c fixing permissions (in fact, if we are going to mention
@c manually fixing permission, we better document a lot
@c better just what we mean by "fix").

Using pserver, you will generally need stricter
permissions on the @sc{cvsroot} directory and
directories above it in the tree; see @ref{Password
authentication security}.

@cindex Setuid
@cindex Setgid
@cindex Security, setuid
@cindex Installed images (VMS)
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.  @sc{cvs} was not written to use such
features and therefore attempting to install @sc{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
@sc{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
(@ref{Password authentication security}).

@node Windows permissions
@subsection File Permission issues specific to Windows
@cindex Windows, and permissions
@cindex File permissions, Windows-specific
@cindex Permissions, Windows-specific

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 @sc{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 @sc{cvs} could be doing
differently in order to avoid the problem.  If you find
something out, please let us know as described in
@ref{BUGS}.

@node Attic
@subsection The attic
@cindex Attic

You will notice that sometimes @sc{cvs} stores an
@sc{rcs} file in the @code{Attic}.  For example, if the
@sc{cvsroot} is @file{/usr/local/cvsroot} and we are
talking about the file @file{backend.c} in the
directory @file{yoyodyne/tc}, then the file normally
would be in

@example
/usr/local/cvsroot/yoyodyne/tc/backend.c,v
@end example

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

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

@noindent
@cindex Dead state
instead.  It should not matter from a user point of
view whether a file is in the attic; @sc{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 @code{dead}.  A
@code{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 @code{dead} state, and a branch revision in a
non-@code{dead} state.
@c Probably should have some more concrete examples
@c here, or somewhere (not sure exactly how we should
@c arrange the discussion of the dead state, versus
@c discussion of the attic).

@node CVS in repository
@subsection The CVS directory in the repository
@cindex CVS directory, in repository

The @file{CVS} directory in each repository directory
contains information such as file attributes (in a file
called @file{CVS/fileattr}.  In the
future additional files may be added to this directory,
so implementations should silently ignore additional
files.

This behavior is implemented only by @sc{cvs} 1.7 and
later; for details see @ref{Watches Compatibility}.

The format of the @file{fileattr} file is a series of entries
of the following form (where @samp{@{} and @samp{@}}
means the text between the braces can be repeated zero
or more times):

@var{ent-type} @var{filename} <tab> @var{attrname} = @var{attrval}
  @{; @var{attrname} = @var{attrval}@} <linefeed>

@var{ent-type} is @samp{F} for a file, in which case the entry specifies the
attributes for that file.

@var{ent-type} is @samp{D},
and @var{filename} empty, to specify default attributes
to be used for newly added files.

Other @var{ent-type} are reserved for future expansion.  @sc{cvs} 1.9 and older
will delete them any time it writes file attributes.
@sc{cvs} 1.10 and later will preserve them.

Note that the order of the lines is not significant;
a program writing the fileattr file may
rearrange them at its convenience.

There is currently no way of quoting tabs or line feeds in the
filename, @samp{=} in @var{attrname},
@samp{;} in @var{attrval}, etc.  Note: some implementations also
don't handle a NUL character in any of the fields, but
implementations are encouraged to allow it.

By convention, @var{attrname} starting with @samp{_} is for an attribute given
special meaning by @sc{cvs}; other @var{attrname}s are for user-defined attributes
(or will be, once implementations start supporting user-defined attributes).

Built-in attributes:

@table @code
@item _watched
Present means the file is watched and should be checked out
read-only.

@item _watchers
Users with watches for this file.  Value is
@var{watcher} > @var{type} @{ , @var{watcher} > @var{type} @}
where @var{watcher} is a username, and @var{type}
is zero or more of edit,unedit,commit separated by
@samp{+} (that is, nothing if none; there is no "none" or "all" keyword).

@item _editors
Users editing this file.  Value is
@var{editor} > @var{val} @{ , @var{editor} > @var{val} @}
where @var{editor} is a username, and @var{val} is
@var{time}+@var{hostname}+@var{pathname}, where
@var{time} is when the @code{cvs edit} command (or
equivalent) happened,
and @var{hostname} and @var{pathname} are for the working directory.
@end table

Example:

@c FIXME: sanity.sh should contain a similar test case
@c so we can compare this example from something from
@c Real Life(TM).  See cvsclient.texi (under Notify) for more
@c discussion of the date format of _editors.
@example
Ffile1 _watched=;_watchers=joe>edit,mary>commit
Ffile2 _watched=;_editors=sue>8 Jan 1975+workstn1+/home/sue/cvs
D _watched=
@end example

@noindent
means that the file @file{file1} should be checked out
read-only.  Furthermore, joe is watching for edits and
mary is watching for commits.  The file @file{file2}
should be checked out read-only; sue started editing it
on 8 Jan 1975 in the directory @file{/home/sue/cvs} on
the machine @code{workstn1}.  Future files which are
added should be checked out read-only.  To represent
this example here, we have shown a space after
@samp{D}, @samp{Ffile1}, and @samp{Ffile2}, but in fact
there must be a single tab character there and no spaces.

@node Locks
@subsection CVS locks in the repository

@cindex #cvs.rfl, technical details
@cindex #cvs.wfl, technical details
@cindex #cvs.lock, technical details
@cindex Locks, cvs, technical details
For an introduction to @sc{cvs} locks focusing on
user-visible behavior, see @ref{Concurrency}.  The
following section is aimed at people who are writing
tools which want to access a @sc{cvs} repository without
interfering with other tools accessing the same
repository.  If you find yourself confused by concepts
described here, like @dfn{read lock}, @dfn{write lock},
and @dfn{deadlock}, you might consult the literature on
operating systems or databases.

@cindex #cvs.tfl
Any file in the repository with a name starting
with @file{#cvs.rfl.} is a read lock.  Any file in
the repository with a name starting with
@file{#cvs.wfl} is a write lock.  Old versions of @sc{cvs}
(before @sc{cvs} 1.5) also created files with names starting
with @file{#cvs.tfl}, but they are not discussed here.
The directory @file{#cvs.lock} serves as a master
lock.  That is, one must obtain this lock fi…