| |
man : cvs
File: cvs.info, Node: Top, Next: Overview, Up: (dir)
CVS--Concurrent Versions System v1.11.1p1
*****************************************
This info manual describes how to use and administer CVS version
1.11.1p1.
* 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
File: cvs.info, Node: Overview, Next: Repository, Prev: Top, Up: Top
1 Overview
**********
This chapter is for people who have never used CVS, and perhaps have
never used version control software before.
If you are already familiar with 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 CVS
* What is CVS not?:: Problems CVS doesn't try to solve
* A sample session:: A tour of basic CVS usage
File: cvs.info, Node: What is CVS?, Next: What is CVS not?, Up: Overview
1.1 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 in a variety of ways, including free download from
the internet. For more information on downloading CVS and other CVS
topics, see:
http://www.cvshome.org/
http://www.loria.fr/~molli/cvs-index.html
There is a mailing list, known as `info-cvs', devoted to CVS. To
subscribe or unsubscribe write to `info-cvs-requestATgnu.org'. 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-requestATgnu.org.
File: cvs.info, Node: What is CVS not?, Next: A sample session, Prev: What is CVS?, Up: Overview
1.2 What is CVS 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, Prev: What is CVS not?, Up: Overview
1.3 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
1.3.1 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
1.3.2 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.
In addition, CVS checks the `$VISUAL' environment variable.
Opinions vary on whether this behavior is desirable and whether future
releases of CVS should check `$VISUAL' or ignore it. You will be OK
either way if you make sure that `$VISUAL' is either unset or set to
the same thing as `$EDITOR'.
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
1.3.3 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) directory `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
1.3.4 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) directory `tc': y
File: cvs.info, Node: Repository, Next: Starting a new project, Prev: Overview, Up: Top
2 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
2.1 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. 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
2.2 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
* CVS in repository:: Additional information in CVS directory
* Locks:: CVS locks control concurrent accesses
* CVSROOT storage:: A few things about CVSROOT are different
File: cvs.info, Node: Repository files, Next: File permissions, Up: Repository storage
2.2.1 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
2.2.2 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
2.2.3 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: CVS in repository, Prev: Windows permissions, Up: Repository storage
2.2.4 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: CVS in repository, Next: Locks, Prev: Attic, Up: Repository storage
2.2.5 The CVS directory in the repository
-----------------------------------------
The `CVS' directory in each repository directory contains information
such as file attributes (in a file called `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 CVS 1.7 and later; for details
see *Note Watches Compatibility::.
The format of the fileattr file is a series of entries of the
following form (where `{' and `}' means the text between the braces can
be repeated zero or more times):
ENT-TYPE FILENAME <tab> ATTRNAME = ATTRVAL {; ATTRNAME = ATTRVAL}
<linefeed>
ENT-TYPE is `F' for a file, in which case the entry specifies the
attributes for that file.
ENT-TYPE is `D', and FILENAME empty, to specify default attributes
to be used for newly added files.
Other ENT-TYPE are reserved for future expansion. CVS 1.9 and older
will delete them any time it writes file attributes. 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 linefeeds in the
filename, `=' in ATTRNAME, `;' in 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, ATTRNAME starting with `_' is for an attribute given
special meaning by CVS; other ATTRNAMEs are for user-defined attributes
(or will be, once implementations start supporting user-defined
attributes).
Builtin attributes:
`_watched'
Present means the file is watched and should be checked out
read-only.
`_watchers'
Users with watches for this file. Value is WATCHER > TYPE { ,
WATCHER > TYPE } where WATCHER is a username, and TYPE is zero or
more of edit,unedit,commit separated by `+' (that is, nothing if
none; there is no "none" or "all" keyword).
`_editors'
Users editing this file. Value is EDITOR > VAL { , EDITOR > VAL }
where EDITOR is a username, and VAL is TIME+HOSTNAME+PATHNAME,
where TIME is when the `cvs edit' command (or equivalent) happened,
and HOSTNAME and PATHNAME are for the working directory.
Example:
Ffile1 _watched=;_watchers=joe>edit,mary>commit
Ffile2 _watched=;_editors=sue>8 Jan 1975+workstn1+/home/sue/cvs
D _watched=
means that the file `file1' should be checked out read-only.
Furthermore, joe is watching for edits and mary is watching for
commits. The file `file2' should be checked out read-only; sue started
editing it on 8 Jan 1975 in the directory `/home/sue/cvs' on the
machine `workstn1'. Future files which are added should be checked out
read-only. To represent this example here, we have shown a space after
`D', `Ffile1', and `Ffile2', but in fact there must be a single tab
character there and no spaces.
File: cvs.info, Node: Locks, Next: CVSROOT storage, Prev: CVS in repository, Up: Repository storage
2.2.6 CVS locks in the repository
---------------------------------
For an introduction to CVS locks focusing on user-visible behavior, see
*Note Concurrency::. The following section is aimed at people who are
writing tools which want to access a CVS repository without interfering
with other tools acessing the same repository. If you find yourself
confused by concepts described here, like "read lock", "write lock",
and "deadlock", you might consult the literature on operating systems
or databases.
Any file in the repository with a name starting with `#cvs.rfl.' is
a read lock. Any file in the repository with a name starting with
`#cvs.wfl' is a write lock. Old versions of CVS (before CVS 1.5) also
created files with names starting with `#cvs.tfl', but they are not
discussed here. The directory `#cvs.lock' serves as a master lock.
That is, one must obtain this lock first before creating any of the
other locks.
To obtain a readlock, first create the `#cvs.lock' directory. This
operation must be atomic (which should be true for creating a directory
under most operating systems). If it fails because the directory
already existed, wait for a while and try again. After obtaining the
`#cvs.lock' lock, create a file whose name is `#cvs.rfl.' followed by
information of your choice (for example, hostname and process
identification number). Then remove the `#cvs.lock' directory to
release the master lock. Then proceed with reading the repository.
When you are done, remove the `#cvs.rfl' file to release the read lock.
To obtain a writelock, first create the `#cvs.lock' directory, as
with a readlock. Then check that there are no files whose names start
with `#cvs.rfl.'. If there are, remove `#cvs.lock', wait for a while,
and try again. If there are no readers, then create a file whose name
is `#cvs.wfl' followed by information of your choice (for example,
hostname and process identification number). Hang on to the
`#cvs.lock' lock. Proceed with writing the repository. When you are
done, first remove the `#cvs.wfl' file and then the `#cvs.lock'
directory. Note that unlike the `#cvs.rfl' file, the `#cvs.wfl' file is
just informational; it has no effect on the locking operation beyond
what is provided by holding on to the `#cvs.lock' lock itself.
Note that each lock (writelock or readlock) only locks a single
directory in the repository, including `Attic' and `CVS' but not
including subdirectories which represent other directories under
version control. To lock an entire tree, you need to lock each
directory (note that if you fail to obtain any lock you need, you must
release the whole tree before waiting and trying again, to avoid
deadlocks).
Note also that CVS expects writelocks to control access to
individual `foo,v' files. RCS has a scheme where the `,foo,' file
serves as a lock, but CVS does not implement it and so taking out a CVS
writelock is recommended. See the comments at rcs_internal_lockfile in
the CVS source code for further discussion/rationale.
File: cvs.info, Node: CVSROOT storage, Prev: Locks, Up: Repository storage
2.2.7 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 (*note checkoutlist::).
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
2.3 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.
The files are stored according to the text file convention for the
system in question. This means that working directories are not
portable between systems with differing conventions for storing text
files. This is intentional, on the theory that the files being managed
by CVS probably will not be portable between such systems either.
`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
If the particular working directory does not correspond to a
directory in the repository, then `Repository' should contain
`CVSROOT/Emptydir'.
`Entries'
This file lists the files and directories in the working directory.
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 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. If there was a conflict, CONFLICT can be set to the
modification time of the file after the file has been written with
conflict markers (*note Conflicts example::). Thus if CONFLICT is
subsequently 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).
The timezone on the timestamp in CVS/Entries (local or universal)
should be the same as the operating system stores for the
timestamp of the file itself. For example, on Unix the file's
timestamp is in universal time (UT), so the timestamp in
CVS/Entries should be too. On VMS, the file's timestamp is in
local time, so CVS on VMS should use local time. This rule is so
that files do not appear to be modified merely because the
timezone changed (for example, to or from summer time).
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.
The lines in the `Entries' file can be in any order.
`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).
Programs which are writing rather than reading can safely ignore
`Entries.Log' if they so choose.
`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
2.4 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.
2.4.1 Editing administrative files
----------------------------------
You edit the administrative files in the same way that you would edit
any other module. Use `cvs checkout CVSROOT' to get a working copy,
edit it, and commit your changes in the normal way.
It is possible to commit an erroneous administrative file. You can
often fix the error and check in a new revision, but sometimes a
particularly bad error in the administrative file makes it impossible
to commit new revisions.
File: cvs.info, Node: Multiple repositories, Next: Creating a repository, Prev: Intro administrative files, Up: Repository
2.5 Multiple repositories
=========================
In some situations it is a good idea to have more than one repository,
for instance if you have two development groups that work on separate
projects without sharing any code. All you have to do to have several
repositories is to specify the appropriate repository, using the
`CVSROOT' environment variable, the `-d' option to CVS, or (once you
have checked out a working directory) by simply allowing CVS to use the
repository that was used to check out the working directory (*note
Specifying a repository::).
The big advantage of having multiple repositories is that they can
reside on different servers. With CVS version 1.10, a single command
cannot recurse into directories from different repositories. With
development versions of CVS, you can check out code from multiple
servers into your working directory. CVS will recurse and handle all
the details of making connections to as many server machines as
necessary to perform the requested command. Here is an example of how
to set up a working directory:
cvs -d server1:/cvs co dir1
cd dir1
cvs -d server2:/root co sdir
cvs update
The `cvs co' commands set up the working directory, and then the
`cvs update' command will contact server2, to update the dir1/sdir
subdirectory, and server1, to update everything else.
File: cvs.info, Node: Creating a repository, Next: Backing up, Prev: Multiple repositories, Up: Repository
2.6 Creating a repository
=========================
To set up a CVS repository, first choose the machine and disk on which
you want to store the revision history of the source files. CPU and
memory requirements are modest, so most machines should be adequate.
For details see *Note Server requirements::.
To estimate disk space requirements, if you are importing RCS files
from another system, the size of those files is the approximate initial
size of your repository, or if you are starting without any version
history, a rule of thumb is to allow for the server approximately three
times the size of the code to be under CVS for the repository (you will
eventually outgrow this, but not for a while). On the machines on
which the developers will be working, you'll want disk space for
approximately one working directory for each developer (either the
entire tree or a portion of it, depending on what each developer uses).
The repository should be accessible (directly or via a networked
file system) from all machines which want to use CVS in server or local
mode; the client machines need not have any access to it other than via
the CVS protocol. It is not possible to use CVS to read from a
repository which one only has read access to; CVS needs to be able to
create lock files (*note Concurrency::).
To create a repository, run the `cvs init' command. It will set up
an empty repository in the CVS root specified in the usual way (*note
Repository::). For example,
cvs -d /usr/local/cvsroot init
`cvs init' is careful to never overwrite any existing files in the
repository, so no harm is done if you run `cvs init' on an already
set-up repository.
`cvs init' will enable history logging; if you don't want that,
remove the history file after running `cvs init'. *Note history file::.
File: cvs.info, Node: Backing up, Next: Moving a repository, Prev: Creating a repository, Up: Repository
2.7 Backing up a repository
===========================
There is nothing particularly magical about the files in the
repository; for the most part it is possible to back them up just like
any other files. However, there are a few issues to consider.
The first is that to be paranoid, one should either not use CVS
during the backup, or have the backup program lock CVS while doing the
backup. To not use CVS, you might forbid logins to machines which can
access the repository, turn off your CVS server, or similar mechanisms.
The details would depend on your operating system and how you have CVS
set up. To lock CVS, you would create `#cvs.rfl' locks in each
repository directory. See *Note Concurrency::, for more on CVS locks.
Having said all this, if you just back up without any of these
precautions, the results are unlikely to be particularly dire.
Restoring from backup, the repository might be in an inconsistent
state, but this would not be particularly hard to fix manually.
When you restore a repository from backup, assuming that changes in
the repository were made after the time of the backup, working
directories which were not affected by the failure may refer to
revisions which no longer exist in the repository. Trying to run CVS
in such directories will typically produce an error message. One way
to get those changes back into the repository is as follows:
* Get a new working directory.
* Copy the files from the working directory from before the failure
over to the new working directory (do not copy the contents of the
`CVS' directories, of course).
* Working in the new working directory, use commands such as `cvs
update' and `cvs diff' to figure out what has changed, and then
when you are ready, commit the changes into the repository.
File: cvs.info, Node: Moving a repository, Next: Remote repositories, Prev: Backing up, Up: Repository
2.8 Moving a repository
=======================
Just as backing up the files in the repository is pretty much like
backing up any other files, if you need to move a repository from one
place to another it is also pretty much like just moving any other
collection of files.
The main thing to consider is that working directories point to the
repository. The simplest way to deal with a moved repository is to
just get a fresh working directory after the move. Of course, you'll
want to make sure that the old working directory had been checked in
before the move, or you figured out some other way to make sure that
you don't lose any changes. If you really do want to reuse the existing
working directory, it should be possible with manual surgery on the
`CVS/Repository' files. You can see *Note Working directory storage::,
for information on the `CVS/Repository' and `CVS/Root' files, but
unless you are sure you want to bother, it probably isn't worth it.
File: cvs.info, Node: Remote repositories, Next: Read-only access, Prev: Moving a repository, Up: Repository
2.9 Remote repositories
=======================
Your working copy of the sources can be on a different machine than the
repository. Using CVS in this manner is known as "client/server"
operation. You run CVS on a machine which can mount your working
directory, known as the "client", and tell it to communicate to a
machine which can mount the repository, known as the "server".
Generally, using a remote repository is just like using a local one,
except that the format of the repository name is:
:METHOD:[[USER][:PASSWORD]@]HOSTNAME[:[PORT]]/path/to/repository
Specifying a password in the repository name is not recommended
during checkout, since this will cause CVS to store a cleartext copy of
the password in each created directory. `cvs login' first instead
(*note Password authentication client::).
The details of exactly what needs to be set up depend on how you are
connecting to the server.
If METHOD is not specified, and the repository name contains `:',
then the default is `ext' or `server', depending on your platform; both
are described in *Note Connecting via rsh::.
* Menu:
* Server requirements:: Memory and other resources for servers
* Connecting via rsh:: Using the `rsh' program to connect
* Password authenticated:: Direct connections using passwords
* GSSAPI authenticated:: Direct connections using GSSAPI
* Kerberos authenticated:: Direct connections with kerberos
* Connecting via fork:: Using a forked `cvs server' to connect
File: cvs.info, Node: Server requirements, Next: Connecting via rsh, Up: Remote repositories
2.9.1 Server requirements
-------------------------
The quick answer to what sort of machine is suitable as a server is
that requirements are modest--a server with 32M of memory or even less
can handle a fairly large source tree with a fair amount of activity.
The real answer, of course, is more complicated. Estimating the
known areas of large memory consumption should be sufficient to
estimate memory requirements. There are two such areas documented
here; other memory consumption should be small by comparison (if you
find that is not the case, let us know, as described in *Note BUGS::,
so we can update this documentation).
The first area of big memory consumption is large checkouts, when
using the CVS server. The server consists of two processes for each
client that it is serving. Memory consumption on the child process
should remain fairly small. Memory consumption on the parent process,
particularly if the network connection to the client is slow, can be
expected to grow to slightly more than the size of the sources in a
single directory, or two megabytes, whichever is larger.
Multiplying the size of each CVS server by the number of servers
which you expect to have active at one time should give an idea of
memory requirements for the server. For the most part, the memory
consumed by the parent process probably can be swap space rather than
physical memory.
The second area of large memory consumption is `diff', when checking
in large files. This is required even for binary files. The rule of
thumb is to allow about ten times the size of the largest file you will
want to check in, although five times may be adequate. For example, if
you want to check in a file which is 10 megabytes, you should have 100
megabytes of memory on the machine doing the checkin (the server
machine for client/server, or the machine running CVS for
non-client/server). This can be swap space rather than physical
memory. Because the memory is only required briefly, there is no
particular need to allow memory for more than one such checkin at a
time.
Resource consumption for the client is even more modest--any machine
with enough capacity to run the operating system in question should
have little trouble.
For information on disk space requirements, see *Note Creating a
repository::.
File: cvs.info, Node: Connecting via rsh, Next: Password authenticated, Prev: Server requirements, Up: Remote repositories
2.9.2 Connecting with rsh
-------------------------
CVS uses the `rsh' protocol to perform these operations, so the remote
user host needs to have a `.rhosts' file which grants access to the
local user.
For example, suppose you are the user `mozart' on the local machine
`toe.example.com', and the server machine is `faun.example.org'. On
faun, put the following line into the file `.rhosts' in `bach''s home
directory:
toe.example.com mozart
Then test that `rsh' is working with
rsh -l bach faun.example.org 'echo $PATH'
Next you have to make sure that `rsh' will be able to find the
server. Make sure that the path which `rsh' printed in the above
example includes the directory containing a program named `cvs' which
is the server. You need to set the path in `.bashrc', `.cshrc', etc.,
not `.login' or `.profile'. Alternately, you can set the environment
variable `CVS_SERVER' on the client machine to the filename of the
server you want to use, for example `/usr/local/bin/cvs-1.6'.
There is no need to edit `inetd.conf' or start a CVS server daemon.
There are two access methods that you use in `CVSROOT' for rsh.
`:server:' specifies an internal rsh client, which is supported only by
some CVS ports. `:ext:' specifies an external rsh program. By default
this is `rsh' but you may set the `CVS_RSH' environment variable to
invoke another program which can access the remote server (for example,
`remsh' on HP-UX 9 because `rsh' is something different). It must be a
program which can transmit data to and from the server without modifying
it; for example the Windows NT `rsh' is not suitable since it by
default translates between CRLF and LF. The OS/2 CVS port has a hack
to pass `-b' to `rsh' to get around this, but since this could
potentially cause problems for programs other than the standard `rsh',
it may change in the future. If you set `CVS_RSH' to `SSH' or some
other rsh replacement, the instructions in the rest of this section
concerning `.rhosts' and so on are likely to be inapplicable; consult
the documentation for your rsh replacement.
Continuing our example, supposing you want to access the module
`foo' in the repository `/usr/local/cvsroot/', on machine
`faun.example.org', you are ready to go:
cvs -d :ext:bachATfaun.org/usr/local/cvsroot checkout foo
(The `bach@' can be omitted if the username is the same on both the
local and remote hosts.)
File: cvs.info, Node: Password authenticated, Next: GSSAPI authenticated, Prev: Connecting via rsh, Up: Remote repositories
2.9.3 Direct connection with password authentication
----------------------------------------------------
The CVS client can also connect to the server using a password
protocol. This is particularly useful if using `rsh' is not feasible
(for example, the server is behind a firewall), and Kerberos also is
not available.
To use this method, it is necessary to make some adjustments on both
the server and client sides.
* Menu:
* Password authentication server:: Setting up the server
* Password authentication client:: Using the client
* Password authentication security:: What this method does and does not do
File: cvs.info, Node: Password authentication server, Next: Password authentication client, Up: Password authenticated
2.9.3.1 Setting up the server for password authentication
.........................................................
First of all, you probably want to tighten the permissions on the
`$CVSROOT' and `$CVSROOT/CVSROOT' directories. See *Note Password
authentication security::, for more details.
On the server side, the file `/etc/inetd.conf' needs to be edited so
`inetd' knows to run the command `cvs pserver' when it receives a
connection on the right port. By default, the port number is 2401; it
would be different if your client were compiled with `CVS_AUTH_PORT'
defined to something else, though. This can also be sepcified in the
CVSROOT variable (*note Remote repositories::) or overridden with the
CVS_CLIENT_PORT environment variable (*note Environment variables::).
If your `inetd' allows raw port numbers in `/etc/inetd.conf', then
the following (all on a single line in `inetd.conf') should be
sufficient:
2401 stream tcp nowait root /usr/local/bin/cvs
cvs -f --allow-root=/usr/cvsroot pserver
You could also use the `-T' option to specify a temporary directory.
The `--allow-root' option specifies the allowable CVSROOT directory.
Clients which attempt to use a different CVSROOT directory will not be
allowed to connect. If there is more than one CVSROOT directory which
you want to allow, repeat the option. (Unfortunately, many versions of
`inetd' have very small limits on the number of arguments and/or the
total length of the command. The usual solution to this problem is to
have `inetd' run a shell script which then invokes CVS with the
necessary arguments.)
If your `inetd' wants a symbolic service name instead of a raw port
number, then put this in `/etc/services':
cvspserver 2401/tcp
and put `cvspserver' instead of `2401' in `inetd.conf'.
Once the above is taken care of, restart your `inetd', or do
whatever is necessary to force it to reread its initialization files.
If you are having trouble setting this up, see *Note Connection::.
Because the client stores and transmits passwords in cleartext
(almost--see *Note Password authentication security::, for details), a
separate CVS password file is generally used, so people don't compromise
their regular passwords when they access the repository. This file is
`$CVSROOT/CVSROOT/passwd' (*note Intro administrative files::). It
uses a colon-separated format, similar to `/etc/passwd' on Unix systems,
except that it has fewer fields: CVS username, optional password, and
an optional system username for CVS to run as if authentication
succeeds. Here is an example `passwd' file with five entries:
anonymous:
bach:ULtgRLXo7NRxs
spwang:1sOp854gDF3DY
melissa:tGX1fS8sun6rY:pubcvs
qproj:XR4EZcEs0szik:pubcvs
(The passwords are encrypted according to the standard Unix
`crypt()' function, so it is possible to paste in passwords directly
from regular Unix `/etc/passwd' files.)
The first line in the example will grant access to any CVS client
attempting to authenticate as user `anonymous', no matter what password
they use, including an empty password. (This is typical for sites
granting anonymous read-only access; for information on how to do the
"read-only" part, see *Note Read-only access::.)
The second and third lines will grant access to `bach' and `spwang'
if they supply their respective plaintext passwords.
The fourth line will grant access to `melissa', if she supplies the
correct password, but her CVS operations will actually run on the
server side under the system user `pubcvs'. Thus, there need not be
any system user named `melissa', but there _must_ be one named `pubcvs'.
The fifth line shows that system user identities can be shared: any
client who successfully authenticates as `qproj' will actually run as
`pubcvs', just as `melissa' does. That way you could create a single,
shared system user for each project in your repository, and give each
developer their own line in the `$CVSROOT/CVSROOT/passwd' file. The CVS
username on each line would be different, but the system username would
be the same. The reason to have different CVS usernames is that CVS
will log their actions under those names: when `melissa' commits a
change to a project, the checkin is recorded in the project's history
under the name `melissa', not `pubcvs'. And the reason to have them
share a system username is so that you can arrange permissions in the
relevant area of the repository such that only that account has
write-permission there.
If the system-user field is present, all password-authenticated CVS
commands run as that user; if no system user is specified, CVS simply
takes the CVS username as the system username and runs commands as that
user. In either case, if there is no such user on the system, then the
CVS operation will fail (regardless of whether the client supplied a
valid password).
The password and system-user fields can both be omitted (and if the
system-user field is omitted, then also omit the colon that would have
separated it from the encrypted password). For example, this would be a
valid `$CVSROOT/CVSROOT/passwd' file:
anonymous::pubcvs
fish:rKa5jzULzmhOo:kfogel
sussman:1sOp854gDF3DY
When the password field is omitted or empty, then the client's
authentication attempt will succeed with any password, including the
empty string. However, the colon after the CVS username is always
necessary, even if the password is empty.
CVS can also fall back to use system authentication. When
authenticating a password, the server first checks for the user in the
`$CVSROOT/CVSROOT/passwd' file. If it finds the user, it will use that
entry for authentication as described above. But if it does not find
the user, or if the CVS `passwd' file does not exist, then the server
can try to authenticate the username and password using the operating
system's user-lookup routines (this "fallback" behavior can be disabled
by setting `SystemAuth=no' in the CVS `config' file, *note config::).
Be aware, however, that falling back to system authentication might be
a security risk: CVS operations would then be authenticated with that
user's regular login password, and the password flies across the
network in plaintext. See *Note Password authentication security:: for
more on this.
Right now, the only way to put a password in the CVS `passwd' file
is to paste it there from somewhere else. Someday, there may be a `cvs
passwd' command.
Unlike many of the files in `$CVSROOT/CVSROOT', it is normal to edit
the `passwd' file in-place, rather than via CVS. This is because of the
possible security risks of having the `passwd' file checked out to
people's working copies. If you do want to include the `passwd' file
in checkouts of `$CVSROOT/CVSROOT', see *Note checkoutlist::.
File: cvs.info, Node: Password authentication client, Next: Password authentication security, Prev: Password authentication server, Up: Password authenticated
2.9.3.2 Using the client with password authentication
.....................................................
To run a CVS command on a remote repository via the
password-authenticating server, one specifies the `pserver' protocol,
optional username, repository host, an optional port number, and path
to the repository. For example:
cvs -d :pserver:faun.example.org:/usr/local/cvsroot checkout someproj
or
CVSROOT=:pserver:bachATfaun.org:2401/usr/local/cvsroot
cvs checkout someproj
However, unless you're connecting to a public-access repository
(i.e., one where that username doesn't require a password), you'll need
to supply a password or "log in" first. Logging in verifies your
password with the repository and stores it in a file. It's done with
the `login' command, which will prompt you interactively for the
password if you didn't supply one as part of $CVSROOT:
cvs -d :pserver:bachATfaun.org:/usr/local/cvsroot login
CVS password:
or
cvs -d :pserver:bach:p4ss30rdATfaun.org:/usr/local/cvsroot login
After you enter the password, CVS verifies it with the server. If
the verification succeeds, then that combination of username, host,
repository, and password is permanently recorded, so future
transactions with that repository won't require you to run `cvs login'.
(If verification fails, CVS will exit complaining that the password
was incorrect, and nothing will be recorded.)
The records are stored, by default, in the file `$HOME/.cvspass'.
That file's format is human-readable, and to a degree human-editable,
but note that the passwords are not stored in cleartext--they are
trivially encoded to protect them from "innocent" compromise (i.e.,
inadvertent viewing by a system administrator or other non-malicious
person).
You can change the default location of this file by setting the
`CVS_PASSFILE' environment variable. If you use this variable, make
sure you set it _before_ `cvs login' is run. If you were to set it
after running `cvs login', then later CVS commands would be unable to
look up the password for transmission to the server.
Once you have logged in, all CVS commands using that remote
repository and username will authenticate with the stored password.
So, for example
cvs -d :pserver:bachATfaun.org:/usr/local/cvsroot checkout foo
should just work (unless the password changes on the server side, in
which case you'll have to re-run `cvs login').
Note that if the `:pserver:' were not present in the repository
specification, CVS would assume it should use `rsh' to connect with the
server instead (*note Connecting via rsh::).
Of course, once you have a working copy checked out and are running
CVS commands from within it, there is no longer any need to specify the
repository explicitly, because CVS can deduce the repository from the
working copy's `CVS' subdirectory.
The password for a given remote repository can be removed from the
`CVS_PASSFILE' by using the `cvs logout' command.
File: cvs.info, Node: Password authentication security, Prev: Password authentication client, Up: Password authenticated
2.9.3.3 Security considerations with password authentication
............................................................
The passwords are stored on the client side in a trivial encoding of
the cleartext, and transmitted in the same encoding. The encoding is
done only to prevent inadvertent password compromises (i.e., a system
administrator accidentally looking at the file), and will not prevent
even a naive attacker from gaining the password.
The separate CVS password file (*note Password authentication
server::) allows people to use a different password for repository
access than for login access. On the other hand, once a user has
non-read-only access to the repository, she can execute programs on the
server system through a variety of means. Thus, repository access
implies fairly broad system access as well. It might be possible to
modify CVS to prevent that, but no one has done so as of this writing.
Note that because the `$CVSROOT/CVSROOT' directory contains `passwd'
and other files which are used to check security, you must control the
permissions on this directory as tightly as the permissions on `/etc'.
The same applies to the `$CVSROOT' directory itself and any directory
above it in the tree. Anyone who has write access to such a directory
will have the ability to become any user on the system. Note that
these permissions are typically tighter than you would use if you are
not using pserver.
In summary, anyone who gets the password gets repository access
(which may imply some measure of general system access as well). The
password is available to anyone who can sniff network packets or read a
protected (i.e., user read-only) file. If you want real security, get
Kerberos.
File: cvs.info, Node: GSSAPI authenticated, Next: Kerberos authenticated, Prev: Password authenticated, Up: Remote repositories
2.9.4 Direct connection with GSSAPI
-----------------------------------
GSSAPI is a generic interface to network security systems such as
Kerberos 5. If you have a working GSSAPI library, you can have CVS
connect via a direct TCP connection, authenticating with GSSAPI.
To do this, CVS needs to be compiled with GSSAPI support; when
configuring CVS it tries to detect whether GSSAPI libraries using
kerberos version 5 are present. You can also use the `--with-gssapi'
flag to configure.
The connection is authenticated using GSSAPI, but the message stream
is _not_ authenticated by default. You must use the `-a' global option
to request stream authentication.
The data transmitted is _not_ encrypted by default. Encryption
support must be compiled into both the client and the server; use the
`--enable-encrypt' configure option to turn it on. You must then use
the `-x' global option to request encryption.
GSSAPI connections are handled on the server side by the same server
which handles the password authentication server; see *Note Password
authentication server::. If you are using a GSSAPI mechanism such as
Kerberos which provides for strong authentication, you will probably
want to disable the ability to authenticate via cleartext passwords.
To do so, create an empty `CVSROOT/passwd' password file, and set
`SystemAuth=no' in the config file (*note config::).
The GSSAPI server uses a principal name of cvs/HOSTNAME, where
HOSTNAME is the canonical name of the server host. You will have to
set this up as required by your GSSAPI mechanism.
To connect using GSSAPI, use `:gserver:'. For example,
cvs -d :gserver:faun.example.org:/usr/local/cvsroot checkout foo
File: cvs.info, Node: Kerberos authenticated, Next: Connecting via fork, Prev: GSSAPI authenticated, Up: Remote repositories
2.9.5 Direct connection with kerberos
-------------------------------------
The easiest way to use kerberos is to use the kerberos `rsh', as
described in *Note Connecting via rsh::. The main disadvantage of
using rsh is that all the data needs to pass through additional
programs, so it may be slower. So if you have kerberos installed you
can connect via a direct TCP connection, authenticating with kerberos.
This section concerns the kerberos network security system, version
4. Kerberos version 5 is supported via the GSSAPI generic network
security interface, as described in the previous section.
To do this, CVS needs to be compiled with kerberos support; when
configuring CVS it tries to detect whether kerberos is present or you
can use the `--with-krb4' flag to configure.
The data transmitted is _not_ encrypted by default. Encryption
support must be compiled into both the client and server; use the
`--enable-encryption' configure option to turn it on. You must then
use the `-x' global option to request encryption.
You need to edit `inetd.conf' on the server machine to run `cvs
kserver'. The client uses port 1999 by default; if you want to use
another port specify it in the `CVSROOT' (*note Remote repositories::)
or the `CVS_CLIENT_PORT' environment variable on the client.
When you want to use CVS, get a ticket in the usual way (generally
`kinit'); it must be a ticket which allows you to log into the server
machine. Then you are ready to go:
cvs -d :kserver:faun.example.org:/usr/local/cvsroot checkout foo
Previous versions of CVS would fall back to a connection via rsh;
this version will not do so.
File: cvs.info, Node: Connecting via fork, Prev: Kerberos authenticated, Up: Remote repositories
2.9.6 Connecting with fork
--------------------------
This access method allows you to connect to a repository on your local
disk via the remote protocol. In other words it does pretty much the
same thing as `:local:', but various quirks, bugs and the like are
those of the remote CVS rather than the local CVS.
For day-to-day operations you might prefer either `:local:' or
`:fork:', depending on your preferences. Of course `:fork:' comes in
particularly handy in testing or debugging `cvs' and the remote
protocol. Specifically, we avoid all of the network-related
setup/configuration, timeouts, and authentication inherent in the other
remote access methods but still create a connection which uses the
remote protocol.
To connect using the `fork' method, use `:fork:' and the pathname to
your local repository. For example:
cvs -d :fork:/usr/local/cvsroot checkout foo
As with `:ext:', the server is called `cvs' by default, or the value
of the `CVS_SERVER' environment variable.
File: cvs.info, Node: Read-only access, Next: Server temporary directory, Prev: Remote repositories, Up: Repository
2.10 Read-only repository access
================================
It is possible to grant read-only repository access to people using the
password-authenticated server (*note Password authenticated::). (The
other access methods do not have explicit support for read-only users
because those methods all assume login access to the repository machine
anyway, and therefore the user can do whatever local file permissions
allow her to do.)
A user who has read-only access can do only those CVS operations
which do not modify the repository, except for certain "administrative"
files (such as lock files and the history file). It may be desirable
to use this feature in conjunction with user-aliasing (*note Password
authentication server::).
Unlike with previous versions of CVS, read-only users should be able
merely to read the repository, and not to execute programs on the
server or otherwise gain unexpected levels of access. Or to be more
accurate, the _known_ holes have been plugged. Because this feature is
new and has not received a comprehensive security audit, you should use
whatever level of caution seems warranted given your attitude concerning
security.
There are two ways to specify read-only access for a user: by
inclusion, and by exclusion.
"Inclusion" means listing that user specifically in the
`$CVSROOT/CVSROOT/readers' file, which is simply a newline-separated
list of users. Here is a sample `readers' file:
melissa
splotnik
jrandom
(Don't forget the newline after the last user.)
"Exclusion" means explicitly listing everyone who has _write_
access--if the file
$CVSROOT/CVSROOT/writers
exists, then only those users listed in it have write access, and
everyone else has read-only access (of course, even the read-only users
still need to be listed in the CVS `passwd' file). The `writers' file
has the same format as the `readers' file.
Note: if your CVS `passwd' file maps cvs users onto system users
(*note Password authentication server::), make sure you deny or grant
read-only access using the _cvs_ usernames, not the system usernames.
That is, the `readers' and `writers' files contain cvs usernames, which
may or may not be the same as system usernames.
Here is a complete description of the server's behavior in deciding
whether to grant read-only or read-write access:
If `readers' exists, and this user is listed in it, then she gets
read-only access. Or if `writers' exists, and this user is NOT listed
in it, then she also gets read-only access (this is true even if
`readers' exists but she is not listed there). Otherwise, she gets
full read-write access.
Of course there is a conflict if the user is listed in both files.
This is resolved in the more conservative way, it being better to
protect the repository too much than too little: such a user gets
read-only access.
File: cvs.info, Node: Server temporary directory, Prev: Read-only access, Up: Repository
2.11 Temporary directories for the server
=========================================
While running, the CVS server creates temporary directories. They are
named
cvs-servPID
where PID is the process identification number of the server. They are
located in the directory specified by the `TMPDIR' environment variable
(*note Environment variables::), the `-T' global option (*note Global
options::), or failing that `/tmp'.
In most cases the server will remove the temporary directory when it
is done, whether it finishes normally or abnormally. However, there
are a few cases in which the server does not or cannot remove the
temporary directory, for example:
* If the server aborts due to an internal server error, it may
preserve the directory to aid in debugging
* If the server is killed in a way that it has no way of cleaning up
(most notably, `kill -KILL' on unix).
* If the system shuts down without an orderly shutdown, which tells
the server to clean up.
In cases such as this, you will need to manually remove the
`cvs-servPID' directories. As long as there is no server running with
process identification number PID, it is safe to do so.
File: cvs.info, Node: Starting a new project, Next: Revisions, Prev: Repository, Up: Top
3 Starting a project with CVS
*****************************
Because renaming files and moving them between directories is somewhat
inconvenient, the first thing you do when you start a new project
should be to think through your file organization. It is not impossible
to rename or move files, but it does increase the potential for
confusion and CVS does have some quirks particularly in the area of
renaming directories. *Note Moving files::.
What to do next depends on the situation at hand.
* Menu:
* Setting up the files:: Getting the files into the repository
* Defining the module:: How to make a module of the files
File: cvs.info, Node: Setting up the files, Next: Defining the module, Up: Starting a new project
3.1 Setting up the files
========================
The first step is to create the files inside the repository. This can
be done in a couple of different ways.
* Menu:
* From files:: This method is useful with old projects
where files already exists.
* From other version control systems:: Old projects where you want to
preserve history from another system.
* From scratch:: Creating a directory tree from scratch.
File: cvs.info, Node: From files, Next: From other version control systems, Up: Setting up the files
3.1.1 Creating a directory tree from a number of files
------------------------------------------------------
When you begin using CVS, you will probably already have several
projects that can be put under CVS control. In these cases the easiest
way is to use the `import' command. An example is probably the easiest
way to explain how to use it. If the files you want to install in CVS
reside in `WDIR', and you want them to appear in the repository as
`$CVSROOT/yoyodyne/RDIR', you can do this:
$ cd WDIR
$ cvs import -m "Imported sources" yoyodyne/RDIR yoyo start
Unless you supply a log message with the `-m' flag, CVS starts an
editor and prompts for a message. The string `yoyo' is a "vendor tag",
and `start' is a "release tag". They may fill no purpose in this
context, but since CVS requires them they must be present. *Note
Tracking sources::, for more information about them.
You can now verify that it worked, and remove your original source
directory.
$ cd ..
$ cvs checkout yoyodyne/RDIR # Explanation below
$ diff -r WDIR yoyodyne/RDIR
$ rm -r WDIR
Erasing the original sources is a good idea, to make sure that you do
not accidentally edit them in WDIR, bypassing CVS. Of course, it would
be wise to make sure that you have a backup of the sources before you
remove them.
The `checkout' command can either take a module name as argument (as
it has done in all previous examples) or a path name relative to
`$CVSROOT', as it did in the example above.
It is a good idea to check that the permissions CVS sets on the
directories inside `$CVSROOT' are reasonable, and that they belong to
the proper groups. *Note File permissions::.
If some of the files you want to import are binary, you may want to
use the wrappers features to specify which files are binary and which
are not. *Note Wrappers::.
File: cvs.info, Node: From other version control systems, Next: From scratch, Prev: From files, Up: Setting up the files
3.1.2 Creating Files From Other Version Control Systems
-------------------------------------------------------
If you have a project which you are maintaining with another version
control system, such as RCS, you may wish to put the files from that
project into CVS, and preserve the revision history of the files.
From RCS
If you have been using RCS, find the RCS files--usually a file
named `foo.c' will have its RCS file in `RCS/foo.c,v' (but it
could be other places; consult the RCS documentation for details).
Then create the appropriate directories in CVS if they do not
already exist. Then copy the files into the appropriate
directories in the CVS repository (the name in the repository must
be the name of the source file with `,v' added; the files go
directly in the appropriate directory of the repository, not in an
`RCS' subdirectory). This is one of the few times when it is a
good idea to access the CVS repository directly, rather than using
CVS commands. Then you are ready to check out a new working
directory.
The RCS file should not be locked when you move it into CVS; if it
is, CVS will have trouble letting you operate on it.
From another version control system
Many version control systems have the ability to export RCS files
in the standard format. If yours does, export the RCS files and
then follow the above instructions.
Failing that, probably your best bet is to write a script that
will check out the files one revision at a time using the command
line interface to the other system, and then check the revisions
into CVS. The `sccs2rcs' script mentioned below may be a useful
example to follow.
From SCCS
There is a script in the `contrib' directory of the CVS source
distribution called `sccs2rcs' which converts SCCS files to RCS
files. Note: you must run it on a machine which has both SCCS and
RCS installed, and like everything else in contrib it is
unsupported (your mileage may vary).
From PVCS
There is a script in the `contrib' directory of the CVS source
distribution called `pvcs_to_rcs' which converts PVCS archives to
RCS files. You must run it on a machine which has both PVCS and
RCS installed, and like everything else in contrib it is
unsupported (your mileage may vary). See the comments in the
script for details.
File: cvs.info, Node: From scratch, Prev: From other version control systems, Up: Setting up the files
3.1.3 Creating a directory tree from scratch
--------------------------------------------
For a new project, the easiest thing to do is probably to create an
empty directory structure, like this:
$ mkdir tc
$ mkdir tc/man
$ mkdir tc/testing
After that, you use the `import' command to create the corresponding
(empty) directory structure inside the repository:
$ cd tc
$ cvs import -m "Created directory structure" yoyodyne/DIR yoyo start
Then, use `add' to add files (and new directories) as they appear.
Check that the permissions CVS sets on the directories inside
`$CVSROOT' are reasonable.
File: cvs.info, Node: Defining the module, Prev: Setting up the files, Up: Starting a new project
3.2 Defining the module
=======================
The next step is to define the module in the `modules' file. This is
not strictly necessary, but modules can be convenient in grouping
together related files and directories.
In simple cases these steps are sufficient to define a module.
1. Get a working copy of the modules file.
$ cvs checkout CVSROOT/modules
$ cd CVSROOT
2. Edit the file and insert a line that defines the module. *Note
Intro administrative files::, for an introduction. *Note
modules::, for a full description of the modules file. You can
use the following line to define the module `tc':
tc yoyodyne/tc
3. Commit your changes to the modules file.
$ cvs commit -m "Added the tc module." modules
4. Release the modules module.
$ cd ..
$ cvs release -d CVSROOT
File: cvs.info, Node: Revisions, Next: Branching and merging, Prev: Starting a new project, Up: Top
4 Revisions
***********
For many uses of CVS, one doesn't need to worry too much about revision
numbers; CVS assigns numbers such as `1.1', `1.2', and so on, and that
is all one needs to know. However, some people prefer to have more
knowledge and control concerning how CVS assigns revision numbers.
If one wants to keep track of a set of revisions involving more than
one file, such as which revisions went into a particular release, one
uses a "tag", which is a symbolic revision which can be assigned to a
numeric revision in each file.
* Menu:
* Revision numbers:: The meaning of a revision number
* Versions revisions releases:: Terminology used in this manual
* Assigning revisions:: Assigning revisions
* Tags:: Tags--Symbolic revisions
* Tagging the working directory:: The cvs tag command
* Tagging by date/tag:: The cvs rtag command
* Modifying tags:: Adding, renaming, and deleting tags
* Tagging add/remove:: Tags with adding and removing files
* Sticky tags:: Certain tags are persistent
File: cvs.info, Node: Revision numbers, Next: Versions revisions releases, Up: Revisions
4.1 Revision numbers
====================
Each version of a file has a unique "revision number". Revision
numbers look like `1.1', `1.2', `1.3.2.2' or even `1.3.2.2.4.5'. A
revision number always has an even number of period-separated decimal
integers. By default revision 1.1 is the first revision of a file.
Each successive revision is given a new number by increasing the
rightmost number by one. The following figure displays a few
revisions, with newer revisions to the right.
+-----+ +-----+ +-----+ +-----+ +-----+
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
+-----+ +-----+ +-----+ +-----+ +-----+
It is also possible to end up with numbers containing more than one
period, for example `1.3.2.2'. Such revisions represent revisions on
branches (*note Branching and merging::); such revision numbers are
explained in detail in *Note Branches and revisions::.
File: cvs.info, Node: Versions revisions releases, Next: Assigning revisions, Prev: Revision numbers, Up: Revisions
4.2 Versions, revisions and releases
====================================
A file can have several versions, as described above. Likewise, a
software product can have several versions. A software product is
often given a version number such as `4.1.1'.
Versions in the first sense are called "revisions" in this document,
and versions in the second sense are called "releases". To avoid
confusion, the word "version" is almost never used in this document.
File: cvs.info, Node: Assigning revisions, Next: Tags, Prev: Versions revisions releases, Up: Revisions
4.3 Assigning revisions
=======================
By default, CVS will assign numeric revisions by leaving the first
number the same and incrementing the second number. For example,
`1.1', `1.2', `1.3', etc.
When adding a new file, the second number will always be one and the
first number will equal the highest first number of any file in that
directory. For example, the current directory contains files whose
highest numbered revisions are `1.7', `3.1', and `4.12', then an added
file will be given the numeric revision `4.1'.
Normally there is no reason to care about the revision numbers--it
is easier to treat them as internal numbers that CVS maintains, and tags
provide a better way to distinguish between things like release 1
versus release 2 of your product (*note Tags::). However, if you want
to set the numeric revisions, the `-r' option to `cvs commit' can do
that. The `-r' option implies the `-f' option, in the sense that it
causes the files to be committed even if they are not modified.
For example, to bring all your files up to revision 3.0 (including
those that haven't changed), you might invoke:
$ cvs commit -r 3.0
Note that the number you specify with `-r' must be larger than any
existing revision number. That is, if revision 3.0 exists, you cannot
`cvs commit -r 1.3'. If you want to maintain several releases in
parallel, you need to use a branch (*note Branching and merging::).
File: cvs.info, Node: Tags, Next: Tagging the working directory, Prev: Assigning revisions, Up: Revisions
4.4 Tags-Symbolic revisions
===========================
The revision numbers live a life of their own. They need not have
anything at all to do with the release numbers of your software
product. Depending on how you use CVS the revision numbers might
change several times between two releases. As an example, some of the
source files that make up RCS 5.6 have the following revision numbers:
ci.c 5.21
co.c 5.9
ident.c 5.3
rcs.c 5.12
rcsbase.h 5.11
rcsdiff.c 5.10
rcsedit.c 5.11
rcsfcmp.c 5.9
rcsgen.c 5.10
rcslex.c 5.11
rcsmap.c 5.2
rcsutil.c 5.10
You can use the `tag' command to give a symbolic name to a certain
revision of a file. You can use the `-v' flag to the `status' command
to see all tags that a file has, and which revision numbers they
represent. Tag names must start with an uppercase or lowercase letter
and can contain uppercase and lowercase letters, digits, `-', and `_'.
The two tag names `BASE' and `HEAD' are reserved for use by CVS. It is
expected that future names which are special to CVS will be specially
named, for example by starting with `.', rather than being named
analogously to `BASE' and `HEAD', to avoid conflicts with actual tag
names.
You'll want to choose some convention for naming tags, based on
information such as the name of the program and the version number of
the release. For example, one might take the name of the program,
immediately followed by the version number with `.' changed to `-', so
that CVS 1.9 would be tagged with the name `cvs1-9'. If you choose a
consistent convention, then you won't constantly be guessing whether a
tag is `cvs-1-9' or `cvs1_9' or what. You might even want to consider
enforcing your convention in the taginfo file (*note user-defined
logging::).
The following example shows how you can add a tag to a file. The
commands must be issued inside your working directory. That is, you
should issue the command in the directory where `backend.c' resides.
$ cvs tag rel-0-4 backend.c
T backend.c
$ cvs status -v backend.c
===================================================================
File: backend.c Status: Up-to-date
Version: 1.4 Tue Dec 1 14:39:01 1992
RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v
Sticky Tag: (none)
Sticky Date: (none)
Sticky Options: (none)
Existing Tags:
rel-0-4 (revision: 1.4)
For a complete summary of the syntax of `cvs tag', including the
various options, see *Note Invoking CVS::.
There is seldom reason to tag a file in isolation. A more common
use is to tag all the files that constitute a module with the same tag
at strategic points in the development life-cycle, such as when a
release is made.
$ cvs tag rel-1-0 .
cvs tag: Tagging .
T Makefile
T backend.c
T driver.c
T frontend.c
T parser.c
(When you give CVS a directory as argument, it generally applies the
operation to all the files in that directory, and (recursively), to any
subdirectories that it may contain. *Note Recursive behavior::.)
The `checkout' command has a flag, `-r', that lets you check out a
certain revision of a module. This flag makes it easy to retrieve the
sources that make up release 1.0 of the module `tc' at any time in the
future:
$ cvs checkout -r rel-1-0 tc
This is useful, for instance, if someone claims that there is a bug in
that release, but you cannot find the bug in the current working copy.
You can also check out a module as it was at any given date. *Note
checkout options::. When specifying `-r' to any of these commands, you
will need beware of sticky tags; see *Note Sticky tags::.
When you tag more than one file with the same tag you can think
about the tag as "a curve drawn through a matrix of filename vs.
revision number." Say we have 5 files with the following revisions:
file1 file2 file3 file4 file5
1.1 1.1 1.1 1.1 /--1.1* <-*- TAG
1.2*- 1.2 1.2 -1.2*-
1.3 \- 1.3*- 1.3 / 1.3
1.4 \ 1.4 / 1.4
\-1.5*- 1.5
1.6
At some time in the past, the `*' versions were tagged. You can
think of the tag as a handle attached to the curve drawn through the
tagged revisions. When you pull on the handle, you get all the tagged
revisions. Another way to look at it is that you "sight" through a set
of revisions that is "flat" along the tagged revisions, like this:
file1 file2 file3 file4 file5
1.1
1.2
1.1 1.3 _
1.1 1.2 1.4 1.1 /
1.2*----1.3*----1.5*----1.2*----1.1 (--- <--- Look here
1.3 1.6 1.3 \_
1.4 1.4
1.5
File: cvs.info, Node: Tagging the working directory, Next: Tagging by date/tag, Prev: Tags, Up: Revisions
4.5 Specifying what to tag from the working directory
=====================================================
The example in the previous section demonstrates one of the most common
ways to choose which revisions to tag. Namely, running the `cvs tag'
command without arguments causes CVS to select the revisions which are
checked out in the current working directory. For example, if the copy
of `backend.c' in working directory was checked out from revision 1.4,
then CVS will tag revision 1.4. Note that the tag is applied
immediately to revision 1.4 in the repository; tagging is not like
modifying a file, or other operations in which one first modifies the
working directory and then runs `cvs commit' to transfer that
modification to the repository.
One potentially surprising aspect of the fact that `cvs tag'
operates on the repository is that you are tagging the checked-in
revisions, which may differ from locally modified files in your working
directory. If you want to avoid doing this by mistake, specify the
`-c' option to `cvs tag'. If there are any locally modified files, CVS
will abort with an error before it tags any files:
$ cvs tag -c rel-0-4
cvs tag: backend.c is locally modified
cvs [tag aborted]: correct the above errors first!
File: cvs.info, Node: Tagging by date/tag, Next: Modifying tags, Prev: Tagging the working directory, Up: Revisions
4.6 Specifying what to tag by date or revision
==============================================
The `cvs rtag' command tags the repository as of a certain date or time
(or can be used to tag the latest revision). `rtag' works directly on
the repository contents (it requires no prior checkout and does not
look for a working directory).
The following options specify which date or revision to tag. See
*Note Common options::, for a complete description of them.
`-D DATE'
Tag the most recent revision no later than DATE.
`-f'
Only useful with the `-D DATE' or `-r TAG' flags. If no matching
revision is found, use the most recent revision (instead of
ignoring the file).
`-r TAG'
Only tag those files that contain existing tag TAG.
The `cvs tag' command also allows one to specify files by revision
or date, using the same `-r', `-D', and `-f' options. However, this
feature is probably not what you want. The reason is that `cvs tag'
chooses which files to tag based on the files that exist in the working
directory, rather than the files which existed as of the given tag/date.
Therefore, you are generally better off using `cvs rtag'. The
exceptions might be cases like:
cvs tag -r 1.4 backend.c
File: cvs.info, Node: Modifying tags, Next: Tagging add/remove, Prev: Tagging by date/tag, Up: Revisions
4.7 Deleting, moving, and renaming tags
=======================================
Normally one does not modify tags. They exist in order to record the
history of the repository and so deleting them or changing their
meaning would, generally, not be what you want.
However, there might be cases in which one uses a tag temporarily or
accidentally puts one in the wrong place. Therefore, one might delete,
move, or rename a tag. Warning: the commands in this section are
dangerous; they permanently discard historical information and it can
difficult or impossible to recover from errors. If you are a CVS
administrator, you may consider restricting these commands with taginfo
(*note user-defined logging::).
To delete a tag, specify the `-d' option to either `cvs tag' or `cvs
rtag'. For example:
cvs rtag -d rel-0-4 tc
deletes the tag `rel-0-4' from the module `tc'.
When we say "move" a tag, we mean to make the same name point to
different revisions. For example, the `stable' tag may currently point
to revision 1.4 of `backend.c' and perhaps we want to make it point to
revision 1.6. To move a tag, specify the `-F' option to either `cvs
tag' or `cvs rtag'. For example, the task just mentioned might be
accomplished as:
cvs tag -r 1.6 -F stable backend.c
When we say "rename" a tag, we mean to make a different name point
to the same revisions as the old tag. For example, one may have
misspelled the tag name and want to correct it (hopefully before others
are relying on the old spelling). To rename a tag, first create a new
tag using the `-r' option to `cvs rtag', and then delete the old name.
This leaves the new tag on exactly the same files as the old tag. For
example:
cvs rtag -r old-name-0-4 rel-0-4 tc
cvs rtag -d old-name-0-4 tc
File: cvs.info, Node: Tagging add/remove, Next: Sticky tags, Prev: Modifying tags, Up: Revisions
4.8 Tagging and adding and removing files
=========================================
The subject of exactly how tagging interacts with adding and removing
files is somewhat obscure; for the most part CVS will keep track of
whether files exist or not without too much fussing. By default, tags
are applied to only files which have a revision corresponding to what
is being tagged. Files which did not exist yet, or which were already
removed, simply omit the tag, and CVS knows to treat the absence of a
tag as meaning that the file didn't exist as of that tag.
However, this can lose a small amount of information. For example,
suppose a file was added and then removed. Then, if the tag is missing
for that file, there is no way to know whether the tag refers to the
time before the file was added, or the time after it was removed. If
you specify the `-r' option to `cvs rtag', then CVS tags the files
which have been removed, and thereby avoids this problem. For example,
one might specify `-r HEAD' to tag the head.
On the subject of adding and removing files, the `cvs rtag' command
has a `-a' option which means to clear the tag from removed files that
would not otherwise be tagged. For example, one might specify this
option in conjunction with `-F' when moving a tag. If one moved a tag
without `-a', then the tag in the removed files might still refer to
the old revision, rather than reflecting the fact that the file had
been removed. I don't think this is necessary if `-r' is specified, as
noted above.
File: cvs.info, Node: Sticky tags, Prev: Tagging add/remove, Up: Revisions
4.9 Sticky tags
===============
Sometimes a working copy's revision has extra data associated with it,
for example it might be on a branch (*note Branching and merging::), or
restricted to versions prior to a certain date by `checkout -D' or
`update -D'. Because this data persists - that is, it applies to
subsequent commands in the working copy - we refer to it as "sticky".
Most of the time, stickiness is an obscure aspect of CVS that you
don't need to think about. However, even if you don't want to use the
feature, you may need to know _something_ about sticky tags (for
example, how to avoid them!).
You can use the `status' command to see if any sticky tags or dates
are set:
$ cvs status driver.c
===================================================================
File: driver.c Status: Up-to-date
Version: 1.7.2.1 Sat Dec 5 19:35:03 1992
RCS Version: 1.7.2.1 /u/cvsroot/yoyodyne/tc/driver.c,v
Sticky Tag: rel-1-0-patches (branch: 1.7.2)
Sticky Date: (none)
Sticky Options: (none)
The sticky tags will remain on your working files until you delete
them with `cvs update -A'. The `-A' option retrieves the version of
the file from the head of the trunk, and forgets any sticky tags,
dates, or options.
The most common use of sticky tags is to identify which branch one
is working on, as described in *Note Accessing branches::. However,
non-branch sticky tags have uses as well. For example, suppose that
you want to avoid updating your working directory, to isolate yourself
from possibly destabilizing changes other people are making. You can,
of course, just refrain from running `cvs update'. But if you want to
avoid updating only a portion of a larger tree, then sticky tags can
help. If you check out a certain revision (such as 1.4) it will become
sticky. Subsequent `cvs update' commands will not retrieve the latest
revision until you reset the tag with `cvs update -A'. Likewise, use
of the `-D' option to `update' or `checkout' sets a "sticky date",
which, similarly, causes that date to be used for future retrievals.
People often want to retrieve an old version of a file without
setting a sticky tag. This can be done with the `-p' option to
`checkout' or `update', which sends the contents of the file to
standard output. For example:
$ cvs update -p -r 1.1 file1 >file1
===================================================================
Checking out file1
RCS: /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v
VERS: 1.1
***************
$
However, this isn't the easiest way, if you are asking how to undo a
previous checkin (in this example, put `file1' back to the way it was
as of revision 1.1). In that case you are better off using the `-j'
option to `update'; for further discussion see *Note Merging two
revisions::.
File: cvs.info, Node: Branching and merging, Next: Recursive behavior, Prev: Revisions, Up: Top
5 Branching and merging
***********************
CVS allows you to isolate changes onto a separate line of development,
known as a "branch". When you change files on a branch, those changes
do not appear on the main trunk or other branches.
Later you can move changes from one branch to another branch (or the
main trunk) by "merging". Merging involves first running `cvs update
-j', to merge the changes into the working directory. You can then
commit that revision, and thus effectively copy the changes onto
another branch.
* Menu:
* Branches motivation:: What branches are good for
* Creating a branch:: Creating a branch
* Accessing branches:: Checking out and updating branches
* Branches and revisions:: Branches are reflected in revision numbers
* Magic branch numbers:: Magic branch numbers
* Merging a branch:: Merging an entire branch
* Merging more than once:: Merging from a branch several times
* Merging two revisions:: Merging differences between two revisions
* Merging adds and removals:: What if files are added or removed?
* Merging and keywords:: Avoiding conflicts due to keyword substitution
File: cvs.info, Node: Branches motivation, Next: Creating a branch, Up: Branching and merging
5.1 What branches are good for
==============================
Suppose that release 1.0 of tc has been made. You are continuing to
develop tc, planning to create release 1.1 in a couple of months.
After a while your customers start to complain about a fatal bug. You
check out release 1.0 (*note Tags::) and find the bug (which turns out
to have a trivial fix). However, the current revision of the sources
are in a state of flux and are not expected to be stable for at least
another month. There is no way to make a bugfix release based on the
newest sources.
The thing to do in a situation like this is to create a "branch" on
the revision trees for all the files that make up release 1.0 of tc.
You can then make modifications to the branch without disturbing the
main trunk. When the modifications are finished you can elect to
either incorporate them on the main trunk, or leave them on the branch.
File: cvs.info, Node: Creating a branch, Next: Accessing branches, Prev: Branches motivation, Up: Branching and merging
5.2 Creating a branch
=====================
You can create a branch with `tag -b'; for example, assuming you're in
a working copy:
$ cvs tag -b rel-1-0-patches
This splits off a branch based on the current revisions in the
working copy, assigning that branch the name `rel-1-0-patches'.
It is important to understand that branches get created in the
repository, not in the working copy. Creating a branch based on
current revisions, as the above example does, will _not_ automatically
switch the working copy to be on the new branch. For information on how
to do that, see *Note Accessing branches::.
You can also create a branch without reference to any working copy,
by using `rtag':
$ cvs rtag -b -r rel-1-0 rel-1-0-patches tc
`-r rel-1-0' says that this branch should be rooted at the revision
that corresponds to the tag `rel-1-0'. It need not be the most recent
revision - it's often useful to split a branch off an old revision (for
example, when fixing a bug in a past release otherwise known to be
stable).
As with `tag', the `-b' flag tells `rtag' to create a branch (rather
than just a symbolic revision name). Note that the numeric revision
number that matches `rel-1-0' will probably be different from file to
file.
So, the full effect of the command is to create a new branch - named
`rel-1-0-patches' - in module `tc', rooted in the revision tree at the
point tagged by `rel-1-0'.
File: cvs.info, Node: Accessing branches, Next: Branches and revisions, Prev: Creating a branch, Up: Branching and merging
5.3 Accessing branches
======================
You can retrieve a branch in one of two ways: by checking it out fresh
from the repository, or by switching an existing working copy over to
the branch.
To check out a branch from the repository, invoke `checkout' with
the `-r' flag, followed by the tag name of the branch (*note Creating a
branch::):
$ cvs checkout -r rel-1-0-patches tc
Or, if you already have a working copy, you can switch it to a given
branch with `update -r':
$ cvs update -r rel-1-0-patches tc
or equivalently:
$ cd tc
$ cvs update -r rel-1-0-patches
It does not matter if the working copy was originally on the main
trunk or on some other branch - the above command will switch it to the
named branch. And similarly to a regular `update' command, `update -r'
merges any changes you have made, notifying you of conflicts where they
occur.
Once you have a working copy tied to a particular branch, it remains
there until you tell it otherwise. This means that changes checked in
from the working copy will add new revisions on that branch, while
leaving the main trunk and other branches unaffected.
To find out what branch a working copy is on, you can use the
`status' command. In its output, look for the field named `Sticky tag'
(*note Sticky tags::) - that's CVS's way of telling you the branch, if
any, of the current working files:
$ cvs status -v driver.c backend.c
===================================================================
File: driver.c Status: Up-to-date
Version: 1.7 Sat Dec 5 18:25:54 1992
RCS Version: 1.7 /u/cvsroot/yoyodyne/tc/driver.c,v
Sticky Tag: rel-1-0-patches (branch: 1.7.2)
Sticky Date: (none)
Sticky Options: (none)
Existing Tags:
rel-1-0-patches (branch: 1.7.2)
rel-1-0 (revision: 1.7)
===================================================================
File: backend.c Status: Up-to-date
Version: 1.4 Tue Dec 1 14:39:01 1992
RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v
Sticky Tag: rel-1-0-patches (branch: 1.4.2)
Sticky Date: (none)
Sticky Options: (none)
Existing Tags:
rel-1-0-patches (branch: 1.4.2)
rel-1-0 (revision: 1.4)
rel-0-4 (revision: 1.4)
Don't be confused by the fact that the branch numbers for each file
are different (`1.7.2' and `1.4.2' respectively). The branch tag is the
same, `rel-1-0-patches', and the files are indeed on the same branch.
The numbers simply reflect the point in each file's revision history at
which the branch was made. In the above example, one can deduce that
`driver.c' had been through more changes than `backend.c' before this
branch was created.
See *Note Branches and revisions:: for details about how branch
numbers are constructed.
File: cvs.info, Node: Branches and revisions, Next: Magic branch numbers, Prev: Accessing branches, Up: Branching and merging
5.4 Branches and revisions
==========================
Ordinarily, a file's revision history is a linear series of increments
(*note Revision numbers::):
+-----+ +-----+ +-----+ +-----+ +-----+
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
+-----+ +-----+ +-----+ +-----+ +-----+
However, CVS is not limited to linear development. The "revision
tree" can be split into "branches", where each branch is a
self-maintained line of development. Changes made on one branch can
easily be moved back to the main trunk.
Each branch has a "branch number", consisting of an odd number of
period-separated decimal integers. The branch number is created by
appending an integer to the revision number where the corresponding
branch forked off. Having branch numbers allows more than one branch
to be forked off from a certain revision.
All revisions on a branch have revision numbers formed by appending
an ordinal number to the branch number. The following figure
illustrates branching with an example.
+-------------+
Branch 1.2.2.3.2 -> ! 1.2.2.3.2.1 !
/ +-------------+
/
/
+---------+ +---------+ +---------+
Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
/ +---------+ +---------+ +---------+
/
/
+-----+ +-----+ +-----+ +-----+ +-----+
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
+-----+ +-----+ +-----+ +-----+ +-----+
!
!
! +---------+ +---------+ +---------+
Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 !
+---------+ +---------+ +---------+
The exact details of how the branch number is constructed is not
something you normally need to be concerned about, but here is how it
works: When CVS creates a branch number it picks the first unused even
integer, starting with 2. So when you want to create a branch from
revision 6.4 it will be numbered 6.4.2. All branch numbers ending in a
zero (such as 6.4.0) are used internally by CVS (*note Magic branch
numbers::). The branch 1.1.1 has a special meaning. *Note Tracking
sources::.
File: cvs.info, Node: Magic branch numbers, Next: Merging a branch, Prev: Branches and revisions, Up: Branching and merging
5.5 Magic branch numbers
========================
This section describes a CVS feature called "magic branches". For most
purposes, you need not worry about magic branches; CVS handles them for
you. However, they are visible to you in certain circumstances, so it
may be useful to have some idea of how it works.
Externally, branch numbers consist of an odd number of dot-separated
decimal integers. *Note Revision numbers::. That is not the whole
truth, however. For efficiency reasons CVS sometimes inserts an extra 0
in the second rightmost position (1.2.4 becomes 1.2.0.4, 8.9.10.11.12
becomes 8.9.10.11.0.12 and so on).
CVS does a pretty good job at hiding these so called magic branches,
but in a few places the hiding is incomplete:
* The magic branch number appears in the output from `cvs log'.
* You cannot specify a symbolic branch name to `cvs admin'.
You can use the `admin' command to reassign a symbolic name to a
branch the way RCS expects it to be. If `R4patches' is assigned to the
branch 1.4.2 (magic branch number 1.4.0.2) in file `numbers.c' you can
do this:
$ cvs admin -NR4patches:1.4.2 numbers.c
It only works if at least one revision is already committed on the
branch. Be very careful so that you do not assign the tag to the wrong
number. (There is no way to see how the tag was assigned yesterday).
File: cvs.info, Node: Merging a branch, Next: Merging more than once, Prev: Magic branch numbers, Up: Branching and merging
5.6 Merging an entire branch
============================
You can merge changes made on a branch into your working copy by giving
the `-j BRANCHNAME' flag to the `update' subcommand. With one `-j
BRANCHNAME' option it merges the changes made between the point where
the branch forked and newest revision on that branch (into your working
copy).
The `-j' stands for "join".
Consider this revision tree:
+-----+ +-----+ +-----+ +-----+
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 ! <- The main trunk
+-----+ +-----+ +-----+ +-----+
!
!
! +---------+ +---------+
Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
+---------+ +---------+
The branch 1.2.2 has been given the tag (symbolic name) `R1fix'. The
following example assumes that the module `mod' contains only one file,
`m.c'.
$ cvs checkout mod # Retrieve the latest revision, 1.4
$ cvs update -j R1fix m.c # Merge all changes made on the branch,
# i.e. the changes between revision 1.2
# and 1.2.2.2, into your working copy
# of the file.
$ cvs commit -m "Included R1fix" # Create revision 1.5.
A conflict can result from a merge operation. If that happens, you
should resolve it before committing the new revision. *Note Conflicts
example::.
If your source files contain keywords (*note Keyword substitution::),
you might be getting more conflicts than strictly necessary. See *Note
Merging and keywords::, for information on how to avoid this.
The `checkout' command also supports the `-j BRANCHNAME' flag. The
same effect as above could be achieved with this:
$ cvs checkout -j R1fix mod
$ cvs commit -m "Included R1fix"
It should be noted that `update -j TAGNAME' will also work but may
not produce the desired result. *Note Merging adds and removals::, for
more.
File: cvs.info, Node: Merging more than once, Next: Merging two revisions, Prev: Merging a branch, Up: Branching and merging
5.7 Merging from a branch several times
=======================================
Continuing our example, the revision tree now looks like this:
+-----+ +-----+ +-----+ +-----+ +-----+
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
+-----+ +-----+ +-----+ +-----+ +-----+
! *
! *
! +---------+ +---------+
Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
+---------+ +---------+
where the starred line represents the merge from the `R1fix' branch
to the main trunk, as just discussed.
Now suppose that development continues on the `R1fix' branch:
+-----+ +-----+ +-----+ +-----+ +-----+
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
+-----+ +-----+ +-----+ +-----+ +-----+
! *
! *
! +---------+ +---------+ +---------+
Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
+---------+ +---------+ +---------+
and then you want to merge those new changes onto the main tru |
