Version Management
with
CVS
for CVS 1.10
Per Cederqvist et al
Copyright (C) 1992, 1993 Signum Support AB
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.
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.
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.cyclic.com/ 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-request@gnu.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 section Dealing with bugs in CVS or this manual. To subscribe send mail to bug-cvs-request@gnu.org.
CVS can do a lot of things for you, but it does not try to be everything for everyone.
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 section How your build system interacts with CVS, for more information on doing builds
in conjunction with CVS.
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 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.
commitinfo file. I haven't
heard a lot about projects trying to do that or whether
there are subtle gotchas, however.
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 (see section The 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'.
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. See section Multiple developers, for an explanation.
When you have checked that the compiler is still compilable you decide to make a new version of `backend.c'. This will store your new `backend.c' in the repository and make it available to anyone else who is using that same repository.
$ cvs commit backend.c
CVS starts an editor, to allow you to enter a log message. You type in "Added an optimization pass.", save the temporary file, and exit the editor.
The environment variable $CVSEDITOR determines
which editor is started. If $CVSEDITOR is not
set, then if the environment variable $EDITOR is
set, it will be used. If both $CVSEDITOR and
$EDITOR are not set then there is a default
which will vary with your operating system, for example
vi for unix or notepad for Windows
NT/95.
When CVS starts the editor, it includes a list of
files which are modified. For the CVS client,
this list is based on comparing the modification time
of the file against the modification time that the file
had when it was last gotten or updated. Therefore, if
a file's modification time has changed but its contents
have not, it will show up as modified. The simplest
way to handle this is simply not to worry about it--if
you proceed with the commit CVS will detect that
the contents are not modified and treat it as an
unmodified file. The next update will clue
CVS in to the fact that the file is unmodified,
and it will reset its stored timestamp so that the file
will not show up in future editor sessions.
If you want to avoid starting an editor you can specify the log message on the command line using the `-m' flag instead, like this:
$ cvs commit -m "Added an optimization pass" backend.c
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 (see section release--Indicate that a Module is no longer in use):
$ cd .. $ cvs release -d tc M driver.c ? tc You have [1] altered files in this repository. Are you sure you want to release (and delete) module `tc': n ** `release' aborted by user choice.
The release command checks that all your modifications have been
committed. If history logging is enabled it also makes a note in the
history file. See section The 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. See section Ignoring files via cvsignore,
for information about how to make that warning go away.
See section 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.
You do not remember modifying `driver.c', so you want to see what has happened to that file.
$ cd tc $ cvs diff driver.c
This command runs diff to compare the version of `driver.c'
that you checked out with your working copy. When you see the output
you remember that you added a command line option that enabled the
optimization pass. You check it in, and release the module.
$ cvs commit -m "Added an optimization pass" driver.c Checking in driver.c; /usr/local/cvsroot/tc/driver.c,v <-- driver.c new revision: 1.2; previous revision: 1.1 done $ cd .. $ cvs release -d tc ? tc You have [0] altered files in this repository. Are you sure you want to release (and delete) module `tc': y
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 section 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.
There are several ways to tell CVS
where to find the repository. You can name the
repository on the command line explicitly, with the
-d (for "directory") option:
cvs -d /usr/local/cvsroot checkout yoyodyne/tc
Or you can set the $CVSROOT environment
variable to an absolute path to the root of the
repository, `/usr/local/cvsroot' in this example.
To set $CVSROOT, csh and tcsh
users should have this line in their `.cshrc' or
`.tcshrc' files:
setenv CVSROOT /usr/local/cvsroot
sh and bash users should instead have these lines in their
`.profile' or `.bashrc':
CVSROOT=/usr/local/cvsroot export CVSROOT
A repository specified with -d will
override the $CVSROOT environment variable.
Once you've checked a working copy out from the
repository, it will remember where its repository is
(the information is recorded in the
`CVS/Root' file in the working copy).
The -d option and the `CVS/Root' file both
override the $CVSROOT environment variable. If
-d option differs from `CVS/Root', the
former is used (and specifying -d will cause
`CVS/Root' to be updated). Of course, for proper
operation they should be two ways of referring to the
same repository.
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 (see section Several developers simultaneously attempting to run CVS) or you might need to deal with the file permissions appropriate for 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 section Magic branch numbers. Also in CVS the valid tag names are a subset of what RCS accepts; for CVS's rules see section Tags--Symbolic revisions.
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 (see section Several developers simultaneously attempting to run CVS).
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, section Telling CVS to watch certain files; -r, section Global options; or CVSREAD, section All environment variables which affect CVS).
Note that using the client/server CVS
(see section 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 section Security considerations with password authentication.
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 (section Security considerations with password authentication).
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 section Dealing with bugs in CVS or this manual.
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.
The `CVS' directory in each repository directory contains information such as file attributes (in a file called `CVS/fileattr'; see fileattr.h in the CVS source distribution for more documentation). 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 section Using watches with old versions of CVS.
For an introduction to CVS locks focusing on user-visible behavior, see section Several developers simultaneously attempting to run CVS. 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.
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 (see section Dealing with bugs in CVS or this manual). To add your own files to the files to be updated in this fashion, you can add them to the `checkoutlist' administrative file.
By default, the `modules' file behaves as
described above. If the modules file is very large,
storing it as a flat text file may make looking up
modules slow (I'm not sure whether this is as much of a
concern now as when CVS first evolved this
feature; I haven't seen benchmarks). Therefore, by
making appropriate edits to the CVS source code
one can store the modules file in a database which
implements the ndbm interface, such as Berkeley
db or GDBM. If this option is in use, then the modules
database will be stored in the files `modules.db',
`modules.pag', and/or `modules.dir'.
For information on the meaning of the various administrative files, see section Reference manual for Administrative files.
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.
cvs -d :local:/usr/local/cvsroot checkout yoyodyne/tc`Root' will contain
:local:/usr/local/cvsrootand `Repository' will contain either
/usr/local/cvsroot/yoyodyne/tcor
yoyodyne/tc
/name/revision/timestamp[+conflict]/options/tagdatewhere `[' and `]' are not part of the entry, but instead indicate that the `+' and conflict marker are optional. name is the name of the file within the directory. revision is the revision that the file in the working derives from, or `0' for an added file, or `-' followed by a revision for a removed file. timestamp is the timestamp of the file at the time that CVS created it; if the timestamp differs with the actual modification time of the file it means the file has been modified. It is in Universal Time (UT), stored in the format used by the ISO C asctime() function (for example, `Sun Apr 7 01:29:26 1996'). One may write a string which is not in that format, for example, `Result of merge', to indicate that the file should always be considered to be modified. This is not a special case; to see whether a file is modified a program should take the timestamp of the file and simply do a string compare with timestamp. conflict indicates that there was a conflict; if it is the same as the actual modification time of the file it means that the user has obviously not resolved the conflict. options contains sticky options (for example `-kb' for a binary file). tagdate contains `T' followed by a tag name, or `D' for a date, followed by a sticky tag or date. Note that if timestamp contains a pair of timestamps separated by a space, rather than a single timestamp, you are dealing with a version of CVS earlier than CVS 1.5 (not documented here). If the first character of a line in `Entries' is `D', then it indicates a subdirectory. `D' on a line all by itself indicates that the program which wrote the `Entries' file does record subdirectories (therefore, if there is such a line and no other lines beginning with `D', one knows there are no subdirectories). Otherwise, the line looks like:
D/name/filler1/filler2/filler3/filler4where 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.
update command with the
`-d' option, which will get the additional files
and remove `Entries.Static'.
edit or unedit) which have not yet been
sent to the server. Its format is not yet documented
here.
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.
Bname/rev/expansionwhere expansion should be ignored, to allow for future expansion.
The directory `$CVSROOT/CVSROOT' contains some administrative files. See section Reference manual for 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. See section The modules file, for a full explanation of all the available features.
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.
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
(see section Telling CVS where your repository is).
The big advantage of having multiple repositories is that they can reside on different servers. The big disadvantage is that you cannot have a single CVS command recurse into directories which comes from different repositories. Generally speaking, if you are thinking of setting up several repositories on the same machine, you might want to consider using several directories within the same repository.
None of the examples in this manual show multiple repositories.
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 section Server requirements.
To estimate disk space requirements, if you are importing RCS files from another system, the size of those files is the approximate initial size of your repository, or if you are starting without any version history, a rule of thumb is to allow for the server approximately three times the size of the code to be under CVS for the repository (you will eventually outgrow this, but not for a while). On the machines on which the developers will be working, you'll want disk space for approximately one working directory for each developer (either the entire tree or a portion of it, depending on what each developer uses).
The repository should be accessable (directly or via a networked file system) from all machines which want to use CVS in server or local mode; the client machines need not have any access to it other than via the CVS protocol. It is not possible to use CVS to read from a repository which one only has read access to; CVS needs to be able to create lock files (see section Several developers simultaneously attempting to run CVS).
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
(see section The 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. See section The history file.
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 section Several developers simultaneously attempting to run CVS, 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:
cvs update and cvs diff to figure out
what has changed, and then when you are ready, commit
the changes into the 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 section How data is stored in the working directory, 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.
Your working copy of the sources can be on a different machine than the repository. Using CVS in this manner is known as client/server operation. You run CVS on a machine which can mount your working directory, known as the client, and tell it to communicate to a machine which can mount the repository, known as the server. Generally, using a remote repository is just like using a local one, except that the format of the repository name is:
:method:user@hostname:/path/to/repository
The details of exactly what needs to be set up depend on how you are connecting to the server.
If method is not specified, and the repository
name contains `:', then the default is ext
or server, depending on your platform; both are
described in section Connecting with rsh.
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 section Dealing with bugs in CVS or this manual, 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 section Creating a repository.
CVS uses the `rsh' protocol to perform these operations, so the remote user host needs to have a `.rhosts' file which grants access to the local user.
For example, suppose you are the user `mozart' on the local machine `toe.grunge.com', and the server machine is `chainsaw.yard.com'. On chainsaw, put the following line into the file `.rhosts' in `bach''s home directory:
toe.grunge.com mozart
Then test that rsh is working with
rsh -l bach chainsaw.yard.com 'echo $PATH'
Next you have to make sure that rsh will be able
to find the server. Make sure that the path which
rsh printed in the above example includes the
directory containing a program named cvs which
is the server. You need to set the path in
`.bashrc', `.cshrc', etc., not `.login'
or `.profile'. Alternately, you can set the
environment variable CVS_SERVER on the client
machine to the filename of the server you want to use,
for example `/usr/local/bin/cvs-1.6'.
There is no need to edit inetd.conf or start a
CVS server daemon.
There are two access methods that you use in CVSROOT
for rsh. :server: specifies an internal rsh
client, which is supported only by some CVS ports.
:ext: specifies an external rsh program. By
default this is rsh but you may set the
CVS_RSH environment variable to invoke another
program which can access the remote server (for
example, remsh on HP-UX 9 because rsh is
something different). It must be a program which can
transmit data to and from the server without modifying
it; for example the Windows NT rsh is not
suitable since it by default translates between CRLF
and LF. The OS/2 CVS port has a hack to pass `-b'
to rsh to get around this, but since this could
potentially cause problems for programs other than the
standard rsh, it may change in the future. If
you set CVS_RSH to SSH or some other rsh
replacement, the instructions in the rest of this
section concerning `.rhosts' and so on are likely
to be inapplicable; consult the documentation for your rsh
replacement.
Continuing our example, supposing you want to access the module `foo' in the repository `/usr/local/cvsroot/', on machine `chainsaw.yard.com', you are ready to go:
cvs -d :ext:bach@chainsaw.yard.com:/usr/local/cvsroot checkout foo
(The `bach@' can be omitted if the username is the same on both the local and remote hosts.)
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.
First of all, you probably want to tighten the permissions on the `$CVSROOT' and `$CVSROOT/CVSROOT' directories. See section Security considerations with password authentication, for more details.
On the server side, the file `/etc/inetd.conf'
needs to be edited so inetd knows to run the
command cvs pserver when it receives a
connection on the right port. By default, the port
number is 2401; it would be different if your client
were compiled with CVS_AUTH_PORT defined to
something else, though.
If your inetd allows raw port numbers in
`/etc/inetd.conf', then the following (all on a
single line in `inetd.conf') should be sufficient:
2401 stream tcp nowait root /usr/local/bin/cvs cvs --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.
If your inetd wants a symbolic service
name instead of a raw port number, then put this in
`/etc/services':
cvspserver 2401/tcp
and put cvspserver instead of
2401 in `inetd.conf'.
Once the above is taken care of, restart your
inetd, or do whatever is necessary to force it
to reread its initialization files.
Because the client stores and transmits passwords in cleartext (almost--see section Security considerations with password authentication, for details), a separate CVS password file may be used, so people don't compromise their regular passwords when they access the repository. This file is `$CVSROOT/CVSROOT/passwd' (see section The administrative files). Its format is similar to `/etc/passwd', except that it only has two or three fields, username, password, and optional username for the server to use. For example:
bach:ULtgRLXo7NRxs cwang:1sOp854gDF3DY
The password is encrypted according to the standard
Unix crypt() function, so it is possible to
paste in passwords directly from regular Unix
`passwd' files.
When authenticating a password, the server first checks
for the user in the CVS `passwd' file. If it
finds the user, it compares against that password. If
it does not find the user, or if the CVS
`passwd' file does not exist, then the server
tries to match the password using the system's
user-lookup routine (using the system's user-lookup
routine can be disabled by setting SystemAuth=no
in the config file, see section The CVSROOT/config configuration file). When using the CVS
`passwd' file, the server runs as the
username specified in the third argument in the
entry, or as the first argument if there is no third
argument (in this way CVS allows imaginary
usernames provided the CVS `passwd' file
indicates corresponding valid system usernames). In
any case, CVS will have no privileges which the
(valid) user would not have.
It is possible to "map" cvs-specific usernames onto system usernames (i.e., onto system login names) in the `$CVSROOT/CVSROOT/passwd' file by appending a colon and the system username after the password. For example:
cvs:ULtgRLXo7NRxs:kfogel generic:1sOp854gDF3DY:spwang anyone:1sOp854gDF3DY:spwang
Thus, someone remotely accessing the repository on `chainsaw.yard.com' with the following command:
cvs -d :pserver:cvs@chainsaw.yard.com:/usr/local/cvsroot checkout foo
would end up running the server under the system identity kfogel, assuming successful authentication. However, the remote user would not necessarily need to know kfogel's system password, as the `$CVSROOT/CVSROOT/passwd' file might contain a different password, used only for CVS. And as the example above indicates, it is permissible to map multiple cvs usernames onto a single system username.
This feature is designed to allow people repository access without full system access (in particular, see section Read-only repository access); however, also see section Security considerations with password authentication. Any sort of repository access very likely implies a degree of general system access as well.
Right now, the only way to put a password in the
CVS `passwd' file is to paste it there from
somewhere else. Someday, there may be a cvs
passwd command.
Before connecting to the server, the client must log
in with the command cvs login. Logging in
verifies a password with the server, and also records
the password for later transactions with the server.
The cvs login command needs to know the
username, server hostname, and full repository path,
and it gets this information from the repository
argument or the CVSROOT environment variable.
cvs login is interactive -- it prompts for a
password:
cvs -d :pserver:bach@chainsaw.yard.com:/usr/local/cvsroot login CVS password:
The password is checked with the server; if it is
correct, the login succeeds, else it fails,
complaining that the password was incorrect.
Once you have logged in, you can force CVS to connect directly to the server and authenticate with the stored password:
cvs -d :pserver:bach@chainsaw.yard.com:/usr/local/cvsroot checkout foo
The `:pserver:' is necessary because without it,
CVS will assume it should use rsh to
connect with the server (see section Connecting with rsh).
(Once you have a working copy checked out and are
running CVS commands from within it, there is no
longer any need to specify the repository explicitly,
because CVS records it in the working copy's
`CVS' subdirectory.)
Passwords are stored by default in the file `$HOME/.cvspass'. Its format is human-readable, but don't edit it unless you know what you are doing. The passwords are not stored in cleartext, but are trivially encoded to protect them from "innocent" compromise (i.e., inadvertently being seen by a system administrator who happens to look at that file).
The password for the currently choosen remote repository
can be removed from the CVS_PASSFILE by using the
cvs logout command.
The CVS_PASSFILE environment variable overrides
this default. If you use this variable, make sure you
set it before cvs login is run. If you
were to set it after running cvs login, then
later CVS commands would be unable to look up the
password for transmission to the server.
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 (see section Setting up the server for password authentication) allows people to use a different password for repository access than for login access. On the other hand, once a user has non-read-only access to the repository, she can execute programs on the server system through a variety of means. Thus, repository access implies fairly broad system access as well. It might be possible to modify CVS to prevent that, but no one has done so as of this writing. Furthermore, there may be other ways in which having access to CVS allows people to gain more general access to the system; no one has done a careful audit.
Note that because the `$CVSROOT/CVSROOT' directory contains `passwd' and other files which are used to check security, you must control the permissions on this directory as tightly as the permissions on `/etc'. The same applies to the `$CVSROOT' directory itself and any directory above it in the tree. Anyone who has write access to such a directory will have the ability to become any user on the system. Note that these permissions are typically tighter than you would use if you are not using pserver.
In summary, anyone who gets the password gets repository access, and some measure of general system access as well. The password is available to anyone who can sniff network packets or read a protected (i.e., user read-only) file. If you want real security, get Kerberos.
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 section Setting up the server for password authentication. 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
(see section The CVSROOT/config configuration file).
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:chainsaw.yard.com:/usr/local/cvsroot checkout foo
The easiest way to use kerberos is to use the kerberos
rsh, as described in section Connecting with 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 CVS_CLIENT_PORT environment
variable on the client.
When you want to use CVS, get a ticket in the
usual way (generally kinit); it must be a ticket
which allows you to log into the server machine. Then
you are ready to go:
cvs -d :kserver:chainsaw.yard.com:/usr/local/cvsroot checkout foo
Previous versions of CVS would fall back to a connection via rsh; this version will not do so.
It is possible to grant read-only repository access to people using the password-authenticated server (see section Direct connection with password authentication). (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 (see section Setting up the server for password authentication).
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 (see section Setting up the server for password authentication), 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.
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 (see section All environment variables which affect CVS), the `-T' global option (see section 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:
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.
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. See section Moving and renaming files.
What to do next depends on the situation at hand.
The first step is to create the files inside the repository. This can be done in a couple of different ways.
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. See section Tracking third-party sources, for more information about them.
You can now verify that it worked, and remove your original source directory.
$ cd .. $ mv dir dir.orig $ cvs checkout yoyodyne/dir # Explanation below $ diff -r dir.orig yoyodyne/dir $ rm -r dir.orig
Erasing the original sources is a good idea, to make sure that you do not accidentally edit them in dir, bypassing CVS. Of course, it would be wise to make sure that you have a backup of the sources before you remove them.
The checkout command can either take a module
name as argument (as it has done in all previous
examples) or a path name relative to $CVSROOT,
as it did in the example above.
It is a good idea to check that the permissions CVS sets on the directories inside `$CVSROOT' are reasonable, and that they belong to the proper groups. See section 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. See section The cvswrappers file.
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.
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.
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.
$ cvs checkout CVSROOT/modules $ cd CVSROOT
tc yoyodyne/tc
$ cvs commit -m "Added the tc module." modules
$ cd .. $ cvs release -d CVSROOT
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.
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 (see section Branching and merging); such revision numbers are explained in detail in section Branches and revisions.
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.
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
(see section Tags--Symbolic revisions). 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 (see section Branching and merging).
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 (see section User-defined logging).
The following example shows how you can add a tag to a file. The commands must be issued inside your working copy of the module. 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)
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. See section 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. See section checkout options.
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
Sometimes a working copy's revision has extra data associated with it, for example it might be on a branch (see section 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
section 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.
Many times you will want to retrieve an old version of
a file without setting a sticky tag. The way to do
that is with the `-p' option to checkout or
update, which sends the contents of the file to
standard output. For example, suppose you have a file
named `file1' which existed as revision 1.1, and
you then removed it (thus adding a dead revision 1.2).
Now suppose you want to add it again, with the same
contents it had previously. Here is how to do it:
$ cvs update -p -r 1.1 file1 >file1 =================================================================== Checking out file1 RCS: /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v VERS: 1.1 *************** $ cvs add file1 cvs add: re-adding file file1 (in place of dead revision 1.2) cvs add: use 'cvs commit' to add this file permanently $ cvs commit -m test Checking in file1; /tmp/cvs-sanity/cvsroot/first-dir/file1,v <-- file1 new revision: 1.3; previous revision: 1.2 done $
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.
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 (see section Tags--Symbolic revisions) 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.
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 section 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'.
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 (see section 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' (see section 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 section Branches and revisions for details about how branch numbers are constructed.
Ordinarily, a file's revision history is a linear series of increments (see section 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 (see section Magic branch numbers). The branch 1.1.1 has a special meaning. See section Tracking third-party sources.
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. See section 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:
cvs log.
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).
You can merge changes made on a branch into your working copy by giving
the `-j branch' flag to the update command. With one
`-j branch' option it merges the changes made between the
point where the branch forked and newest revision on that branch (into
your working copy).
+-----+ +-----+ +-----+ +-----+
! 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. See section Conflicts example.
The checkout command also supports the `-j branch' flag. The
same effect as above could be achieved with this:
$ cvs checkout -j R1fix mod $ cvs commit -m "Included R1fix"
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 trunk. If you just use the cvs update -j
R1fix m.c command again, CVS will attempt to
merge again the changes which you have already merged,
which can have undesirable side effects.
So instead you need to specify that you only want to merge the changes on the branch which have not yet been merged into the trunk. To do that you specify two `-j' options, and CVS merges the changes from the first revision to the second revision. For example, in this case the simplest way would be
cvs update -j 1.2.2.2 -j R1fix m.c # Merge changes from 1.2.2.2 to the
# head of the R1fix branch
The problem with this is that you need to specify the 1.2.2.2 revision manually. A slightly better approach might be to use the date the last merge was done:
cvs update -j R1fix:yesterday -j R1fix m.c
Better yet, tag the R1fix branch after every merge into the trunk, and then use that tag for subsequent merges:
cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c
With two `-j revision' flags, the update
(and checkout) command can merge the differences
between any two revisions into your working file.
$ cvs update -j 1.5 -j 1.3 backend.c
will remove all changes made between revision 1.3 and 1.5. Note the order of the revisions!
If you try to use this option when operating on multiple files, remember that the numeric revisions will probably be very different between the various files that make up a module. You almost always use symbolic tags rather than revision numbers when operating on multiple files.
If the changes which you are merging involve removing
or adding some files, update -j will reflect
such additions or removals.
For example:
cvs update -A touch a b c cvs add a b c ; cvs ci -m "added" a b c cvs tag -b branchtag cvs update -r branchtag touch d ; cvs add d rm a ; cvs rm a cvs ci -m "added d, removed a" cvs update -A cvs update -jbranchtag
After these commands are executed and a `cvs commit' is done, file `a' will be removed and file `d' added in the main branch.
Almost all of the subcommands of CVS work recursively when you specify a directory as an argument. For instance, consider this directory structure:
$HOME
|
+--tc
| |
+--CVS
| (internal CVS files)
+--Makefile
+--backend.c
+--driver.c
+--frontend.c
+--parser.c
+--man
| |
| +--CVS
| | (internal CVS files)
| +--tc.1
|
+--testing
|
+--CVS
| (internal CVS files)
+--testpgm.t
+--test2.t
If `tc' is the current working directory, the following is true:
cvs update testing/testpgm.t testing/test2.t
tc module
If no arguments are given to update it will
update all files in the current working directory and
all its subdirectories. In other words, `.' is a
default argument to update. This is also true
for most of the CVS subcommands, not only the
update command.
The recursive behavior of the CVS subcommands can be turned off with the `-l' option. Conversely, the `-R' option can be used to force recursion if `-l' is specified in `~/.cvsrc' (see section Default options and the ~/.cvsrc file).
$ cvs update -l # Don't update files in subdirectories
In the course of a project, one will often add new files. Likewise with removing or renaming, or with directories. The general concept to keep in mind in all these cases is that instead of making an irreversible change you want CVS to record the fact that a change has taken place, just as with modifying an existing file. The exact mechanisms to do this in CVS vary depending on the situation.
To add a new file to a directory, follow these steps.
You can also use the add command to add a new
directory.
Unlike most other commands, the add command is
not recursive. You cannot even type `cvs add
foo/bar'! Instead, you have to
$ cd foo $ cvs add bar
-k kflag] [-m message] files ...
Schedule files to be added to the repository.
The files or directories specified with add must
already exist in the current directory. To add a whole
new directory hierarchy to the source repository (for
example, files received from a third-party vendor), use
the import command instead. See section import--Import sources into CVS, using vendor branches.
The added files are not placed in the source repository
until you use commit to make the change
permanent. Doing an add on a file that was
removed with the remove command will undo the
effect of the remove, unless a commit
command intervened. See section Removing files, for an
example.
The `-k' option specifies the default way that this file will be checked out; for more information see section Substitution modes.
The `-m' option specifies a description for the
file. This description appears in the history log (if
it is enabled, see section The history file). It will also be
saved in the version history inside the repository when
the file is committed. The log command displays
this description. The description can be changed using
`admin -t'. See section admin--Administration. If you omit the
`-m description' flag, an empty string will
be used. You will not be prompted for a description.
For example, the following commands add the file `backend.c' to the repository:
$ cvs add backend.c $ cvs commit -m "Early version. Not yet compilable." backend.c
When you add a file it is added only on the branch which you are working on (see section Branching and merging). You can later merge the additions to another branch if you want (see section Merging can add or remove files).
Modules change. New files are added, and old files disappear. Still, you want to be able to retrieve an exact copy of old releases.
Here is what you can do to remove a file, but remain able to retrieve old revisions:
status or update command. If you remove
the file without committing your changes, you will of
course not be able to retrieve the file as it was
immediately before you deleted it.
rm.
When you commit the removal of the file, CVS
records the fact that the file no longer exists. It is
possible for a file to exist on only some branches and
not on others, or to re-add another file with the same
name later. CVS will correctly create or not create
the file, based on the `-r' and `-D' options
specified to checkout or update.
Schedule file(s) to be removed from the repository (files which have not already been removed from the working directory are not processed). This command does not actually remove the file from the repository until you commit the removal. For a full list of options, see section Quick reference to CVS commands.
Here is an example of removing several files:
$ cd test $ rm *.c $ cvs remove cvs remove: Removing . cvs remove: scheduling a.c for removal cvs remove: scheduling b.c for removal cvs remove: use 'cvs commit' to remove these files permanently $ cvs ci -m "Removed unneeded files" cvs commit: Examining . cvs commit: Committing .
As a convenience you can remove the file and cvs
remove it in one step, by specifying the `-f'
option. For example, the above example could also be
done like this:
$ cd test $ cvs remove -f *.c cvs remove: scheduling a.c for removal cvs remove: scheduling b.c for removal cvs remove: use 'cvs commit' to remove these files permanently $ cvs ci -m "Removed unneeded files" cvs commit: Examining . cvs commit: Committing .
If you execute remove for a file, and then
change your mind before you commit, you can undo the
remove with an add command.
$ ls CVS ja.h oj.c $ rm oj.c $ cvs remove oj.c cvs remove: scheduling oj.c for removal cvs remove: use 'cvs commit' to remove this file permanently $ cvs add oj.c U oj.c cvs add: oj.c, version 1.1.1.1, resurrected
If you realize your mistake before you run the
remove command you can use update to
resurrect the file:
$ rm oj.c $ cvs update oj.c cvs update: warning: oj.c was lost U oj.c
When you remove a file it is removed only on the branch which you are working on (see section Branching and merging). You can later merge the removals to another branch if you want (see section Merging can add or remove files).
In concept removing directories is somewhat similar to removing files--you want the directory to not exist in your current working directories, but you also want to be able to retrieve old releases in which the directory existed.
The way that you remove a d