Version Management
with
CVS
for CVS 1.9
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 section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" and this permission notice may be included in translations approved by the Free Software Foundation instead of in the original English.
Up to this point, one of the weakest parts of CVS has been the documentation. CVS is a complex program. Previous versions of the manual were written in the manual page format, which is not really well suited for such a complex program.
When writing this manual, I had several goals in mind:
This manual was contributed by Signum Support AB in Sweden. Signum is yet another in the growing list of companies that support free software. You are free to copy both this manual and the CVS program. See section GNU GENERAL PUBLIC LICENSE, for the details. Signum Support offers support contracts and binary distribution for many programs, such as CVS, GNU Emacs, the GNU C compiler and others. Write to us for more information.
Signum Support AB Box 2044 S-580 02 Linkoping Sweden Email: info@signum.se Phone: +46 (0)13 - 21 46 00 Fax: +46 (0)13 - 21 47 00
Another company selling support for CVS is Cyclic
Software, web: http://www.cyclic.com/, email:
info@cyclic.com.
CVS is a complex system. You will need to read the manual to be able to use all of its capabilities. There are dangers that can easily be avoided if you know about them, and this manual tries to warn you about them. This checklist is intended to help you avoid the dangers without reading the entire manual. If you intend to read the entire manual you can skip this table.
admin command
admin command can cause
CVS to cease working. See section admin--Administration front end for rcs, before trying
to use it.
Roland Pesch, Cygnus Support <pesch@cygnus.com> wrote the manual pages which were distributed with CVS 1.3. Appendix A and B contain much text that was extracted from them. He also read an early draft of this manual and contributed many ideas and corrections.
The mailing-list info-cvs is sometimes
informative. I have included information from postings
made by the following persons:
David G. Grubbs <dgg@think.com>.
Some text has been extracted from the man pages for RCS.
The CVS FAQ by David G. Grubbs has provided useful material. The FAQ is no longer maintained, however, and this manual about the closest thing there is to a successor (with respect to documenting how to use CVS, at least).
In addition, the following persons have helped by telling me about mistakes I've made: Roxanne Brunskill <rbrunski@datap.ca>, Kathy Dyer <dyer@phoenix.ocf.llnl.gov>, Karl Pingle <pingle@acuson.com>, Thomas A Peterson <tap@src.honeywell.com>, Inge Wallin <ingwa@signum.se>, Dirk Koschuetzki <koschuet@fmi.uni-passau.de> and Michael Brown <brown@wi.extrel.com>.
This manual is known to have room for improvement. Here is a list of known deficiencies:
I hope that you will find this manual useful, despite the above-mentioned shortcomings.
Linkoping, October 1993 Per Cederqvist
CVS is a version control system. Using it, you can record the history of your source files.
For example, bugs sometimes creep in when software is modified, and you might not detect the bug until a long time after you make the modification. With CVS, you can easily retrieve old versions to see exactly which change caused the bug. This can sometimes be a big help.
You could of course save every version of every file you have ever created. This would however waste an enormous amount of disk space. CVS stores all the versions of a file in a single file in a clever way that only stores the differences between versions.
CVS also helps you if you are part of a group of people working on the same project. It is all too easy to overwrite each others' changes unless you are extremely careful. Some editors, like GNU Emacs, try to make sure that the same file is never modified by two people at the same time. Unfortunately, if someone is using another editor, that safeguard will not work. CVS solves this problem by insulating the different developers from each other. Every developer works in his own directory, and CVS merges the work when each developer is done.
CVS started out as a bunch of shell scripts written by
Dick Grune, posted to comp.sources.unix in the volume 6
release of December, 1986. While no actual code from
these shell scripts is present in the current version
of CVS much of the CVS conflict resolution algorithms
come from them.
In April, 1989, Brian Berliner designed and coded CVS. Jeff Polk later helped Brian with the design of the CVS module and vendor branch support.
You can get CVS via anonymous ftp from a number of sites, for instance prep.ai.mit.edu in `pub/gnu'.
There is a mailing list, known as info-cvs,
devoted to CVS. To subscribe or
unsubscribe
send a message to
info-cvs-request@prep.ai.mit.edu. Please be
specific about your email address. As of May 1996,
subscription requests are handled by a busy human
being, so you cannot expect to be added or removed
immediately. The usenet group
comp.software.config-mgmt is also a suitable
place for CVS discussions (along with other
configuration management systems).
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 depencies which
make uses.
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.
CVS stores all files in a centralized repository (see section The Repository).
The repository contains directories and files, in an arbitrary tree. The modules feature can be used to group together a set of directories or files into a single entity (see section The modules file). A typical usage is to define one module per project.
Each version of a file has a unique revision number. Revision numbers look like `1.1', `1.2', `1.3.2.2' or even `1.3.2.2.4.5'. A revision number always has an even number of period-separated decimal integers. By default revision 1.1 is the first revision of a file. Each successive revision is given a new number by increasing the rightmost number by one. The following figure displays a few revisions, with newer revisions to the right.
+-----+ +-----+ +-----+ +-----+ +-----+
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
+-----+ +-----+ +-----+ +-----+ +-----+
CVS is not limited to linear development. The revision tree can be split into branches, where each branch is a self-maintained line of development. Changes made on one branch can easily be moved back to the main trunk.
Each branch has a branch number, consisting of an odd number of period-separated decimal integers. The branch number is created by appending an integer to the revision number where the corresponding branch forked off. Having branch numbers allows more than one branch to be forked off from a certain revision.
All revisions on a branch have revision numbers formed by appending an ordinal number to the branch number. The following figure illustrates branching with an example.
+-------------+
Branch 1.2.2.3.2 -> ! 1.2.2.3.2.1 !
/ +-------------+
/
/
+---------+ +---------+ +---------+ +---------+
Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !----! 1.2.2.4 !
/ +---------+ +---------+ +---------+ +---------+
/
/
+-----+ +-----+ +-----+ +-----+ +-----+
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
+-----+ +-----+ +-----+ +-----+ +-----+
!
!
! +---------+ +---------+ +---------+
Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 !
+---------+ +---------+ +---------+
The exact details of how the branch number is constructed is not something you normally need to be concerned about, but here is how it works: When CVS creates a branch number it picks the first unused even integer, starting with 2. So when you want to create a branch from revision 6.4 it will be numbered 6.4.2. All branch numbers ending in a zero (such as 6.4.0) are used internally by CVS (see section Magic branch numbers). The branch 1.1.1 has a special meaning. See section Tracking third-party sources.
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.
This section describes a typical work-session using CVS. It assumes that a repository is set up (see section The Repository).
Suppose you are working on a simple compiler. The source consists of a handful of C files and a `Makefile'. The compiler is called `tc' (Trivial Compiler), and the repository is set up so that there is a module called `tc'.
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'.
$ cvs commit backend.c
CVS starts an editor, to allow you to enter a log message. You type in "Added an optimization pass.", save the temporary file, and exit the editor.
The environment variable $CVSEDITOR determines
which editor is started. If $CVSEDITOR is not
set, then if the environment variable $EDITOR is
set, it will be used. If both $CVSEDITOR and
$EDITOR are not set then the editor defaults to
vi. If you want to avoid the overhead of
starting an editor you can specify the log message on
the command line using the `-m' flag instead, like
this:
$ cvs commit -m "Added an optimization pass" backend.c
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, and then work on that copy. When you've finished a set of changes, you check (or commit) them back into the repository. The repository then contains the changes which you have made, as well as recording exactly what you changed, when you changed it, and other such information.
CVS can access a repository by a variety of
means. It might be on the local computer, or it might
be on a computer across the room or across the world.
To distinguish various ways to access a repository, the
repository name can start with an access method.
For example, the access method :local: means to
access a repository directory, so the repository
:local:/usr/local/cvsroot means that the
repository is in `/usr/local/cvsroot' on the
computer running CVS. For information on other
access methods, see section Remote repositories.
If the access method is omitted, then if the repository
does not contain `:', then :local: is
assumed. If it does contain `:' than either
:ext: or :server: is assumed. For
example, if you have a local repository in
`/usr/local/cvsroot', you can use
/usr/local/cvsroot instead of
:local:/usr/local/cvsroot. But if (under
Windows NT, for example) your local repository is
`c:\src\cvsroot', then you must specify the access
method, as in :local:c:\src\cvsroot.
The repository is split in two parts. `$CVSROOT/CVSROOT' contains administrative files for CVS. The other directories contain the actual user-defined modules.
There are a couple of different ways to tell CVS
where to find the repository. You can name the
repository on the command line explicitly, with the
-d (for "directory") option:
cvs -d /usr/local/cvsroot checkout yoyodyne/tc
Or you can set the $CVSROOT environment
variable to an absolute path to the root of the
repository, `/usr/local/cvsroot' in this example.
To set $CVSROOT, all csh and tcsh
users should have this line in their `.cshrc' or
`.tcshrc' files:
setenv CVSROOT /usr/local/cvsroot
sh and bash users should instead have these lines in their
`.profile' or `.bashrc':
CVSROOT=/usr/local/cvsroot export CVSROOT
A repository specified with -d will
override the $CVSROOT environment variable.
Once you've checked a working copy out from the
repository, it will remember where its repository is
(the information is recorded in the
`CVS/Root' file in the working copy).
The -d option and the `CVS/Root' file both
override the $CVSROOT environment variable. If
-d option differs from `CVS/Root', the
former is used (and specifying -d will cause
`CVS/Root' to be updated). Of course, for proper
operation they should be two ways of referring to the
same repository.
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. This
file format has become very common--many systems other
than CVS or RCS can at least import history
files in this format.
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, though).
CVS tries to set up reasonable file permissions
for new directories that are added inside the tree, but
you must fix the permissions manually when a new
directory should have different permissions than its
parent directory. If you set the CVSUMASK
environment variable that will control the file
permissions which CVS uses in creating directories
and/or files in the repository. CVSUMASK does
not affect the file permissions in the working
directory; such files have the permissions which are
typical for newly created files, except that sometimes
CVS creates them read-only (see the sections on
watches, section Telling CVS to watch certain files; -r, section Global options; or CVSREAD, section All environment variables which affect CVS).
Since CVS was not written to be run setuid, it is unsafe to try to run it setuid. You cannot use the setuid features of RCS together with CVS.
The directory `$CVSROOT/CVSROOT' contains some administrative files. See section Reference manual for the 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, choose a directory with ample disk space available for the revision history of the source files. It 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.
Your working copy of the sources can be on a different machine than the repository. 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.
CVS uses the `rsh' protocol to perform these operations, so the remote user host needs to have a `.rhosts' file which grants access to the local user.
For example, suppose you are the user `mozart' on the local machine `anklet.grunge.com', and the server machine is `chainsaw.brickyard.com'. On chainsaw, put the following line into the file `.rhosts' in `bach''s home directory:
anklet.grunge.com mozart
Then test that rsh is working with
rsh -l bach chainsaw.brickyard.com 'echo $PATH'
Next you have to make sure that rsh will be able
to find the server. Make sure that the path which
rsh printed in the above example includes the
directory containing a program named cvs which
is the server. You need to set the path in
`.bashrc', `.cshrc', etc., not `.login'
or `.profile'. Alternately, you can set the
environment variable CVS_SERVER on the client
machine to the filename of the server you want to use,
for example `/usr/local/bin/cvs-1.6'.
There is no need to edit inetd.conf or start a
CVS server daemon.
There are two access methods that you use in CVSROOT
for rsh. :server: specifies an internal rsh
client, which is supported only by some CVS ports.
:ext: specifies an external rsh program. By
default this is rsh but you may set the
CVS_RSH environment variable to invoke another
program which can access the remote server (for
example, remsh on HP-UX 9 because rsh is
something different). It must be a program which can
transmit data to and from the server without modifying
it; for example the Windows NT rsh is not
suitable since it by default translates between CRLF
and LF. The OS/2 CVS port has a hack to pass `-b'
to rsh to get around this, but since this could
potentially cause programs for programs other than the
standard rsh, it may change in the future. If
you set CVS_RSH to SSH or some other rsh
replacement, the instructions in the rest of this
section concerning `.rhosts' and so on are likely
to be incorrect; consult the documentation for your rsh
replacement.
Continuing our example, supposing you want to access the module `foo' in the repository `/usr/local/cvsroot/', on machine `chainsaw.brickyard.com', you are ready to go:
cvs -d :ext:bach@chainsaw.brickyard.com:/usr/local/cvsroot checkout foo
(The `bach@' can be omitted if the username is the same on both the local and remote hosts.)
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.
On the server side, the file `/etc/inetd.conf'
needs to be edited so inetd knows to run the
command cvs pserver when it receives a
connection on the right port. By default, the port
number is 2401; it would be different if your client
were compiled with CVS_AUTH_PORT defined to
something else, though.
If your inetd allows raw port numbers in
`/etc/inetd.conf', then the following (all on a
single line in `inetd.conf') should be sufficient:
2401 stream tcp nowait root /usr/local/bin/cvs cvs -b /usr/local/bin pserver
The `-b' option specifies the directory which contains the RCS binaries on the server. You could also use the `-T' option to specify a temporary directory.
If your inetd wants a symbolic service
name instead of a raw port number, then put this in
`/etc/services':
cvspserver 2401/tcp
and put cvspserver instead of
2401 in `inetd.conf'.
Once the above is taken care of, restart your
inetd, or do whatever is necessary to force it
to reread its initialization files.
Because the client stores and transmits passwords in cleartext (almost--see 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 fields, username and password. For example:
bach:ULtgRLXo7NRxs cwang:1sOp854gDF3DY
The password is encrypted according to the standard
Unix crypt() function, so it is possible to
paste in passwords directly from regular Unix
`passwd' files.
When authenticating a password, the server first checks for the user in the CVS `passwd' file. If it finds the user, it compares against that password. If it does not find the user, or if the CVS `passwd' file does not exist, then the server tries to match the password using the system's user-lookup routine. When using the CVS `passwd' file, the server runs under as the username specified in the the third argument in the entry, or as the first argument if there is no third argument (in this way CVS allows imaginary usernames provided the CVS `passwd' file indicates corresponding valid system usernames). In any case, CVS will have no privileges which the (valid) user would not have.
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.brickyard.com:/usr/local/cvsroot login CVS password:
The password is checked with the server; if it is
correct, the login succeeds, else it fails,
complaining that the password was incorrect.
Once you have logged in, you can force CVS to connect directly to the server and authenticate with the stored password:
cvs -d :pserver:bach@chainsaw.brickyard.com:/usr/local/cvsroot checkout foo
The `:pserver:' is necessary because without it,
CVS will assume it should use rsh to
connect with the server (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 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 CVS_PASSWORD environment variable overrides
all stored passwords. If it is set, CVS
will use it for all password-authenticated
connections.
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 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; noone has done a careful audit.
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.
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.
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.brickyard.com:/user/local/cvsroot checkout foo
Previous versions of CVS would fall back to a connection via rsh; this version will not 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 $ ls -R yoyodyne $ 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
When more than one person works on a software project
things often get complicated. Often, two people try to
edit the same file simultaneously. One solution, known
as file locking or reserved checkouts, is
to allow only one person to edit each file at a time.
This is the only solution with some version control
systems, including RCS and SCCS. CVS
doesn't have a very nice implementation of reserved
checkouts (yet) but there are ways to get it working
(for example, see the cvs admin -l command in
section admin options). It also may be possible to use
the watches features described below, together with
suitable procedures (not enforced by software), to
avoid having two people edit at the same time.
The default model with CVS is known as unreserved checkouts. In this model, developers can edit their own working copy of a file simultaneously. The first person that commits his changes has no automatic way of knowing that another has started to edit it. Others will get an error message when they try to commit the file. They must then use CVS commands to bring their working copy up to date with the repository revision. This process is almost automatic.
CVS also supports mechanisms which facilitate various kinds of communcation, without actually enforcing rules like reserved checkouts do.
The rest of this chapter describes how these various models work, and some of the issues involved in choosing between them.
Based on what operations you have performed on a
checked out file, and what operations others have
performed to that file in the repository, one can
classify a file in a number of states. The states, as
reported by the status command, are:
add, and not yet
committed your changes.
remove, and not yet
committed your changes.
update rather than
checkout to get that newer revision.
update command gave a conflict. You need to
resolve the conflict as described in section Conflicts example.
add.
To help clarify the file status, status also
reports the Working revision which is the
revision that the file in the working directory derives
from, and the Repository revision which is the
latest revision in the repository for the branch in
use.
For information on the options to status, see
section status--Display status information on checked out files. For information on its Sticky tag
and Sticky date output, see section Sticky tags.
For information on its Sticky options output,
see the `-k' option in section update options.
When you want to update or merge a file, use the update
command. For files that are not up to date this is roughly equivalent
to a checkout command: the newest revision of the file is
extracted from the repository and put in your working copy of the
module.
Your modifications to a file are never lost when you
use update. If no newer revision exists,
running update has no effect. If you have
edited the file, and a newer revision is available,
CVS will merge all changes into your working copy.
For instance, imagine that you checked out revision 1.4 and started
editing it. In the meantime someone else committed revision 1.5, and
shortly after that revision 1.6. If you run update on the file
now, CVS will incorporate all changes between revision 1.4 and 1.6 into
your file.
If any of the changes between 1.4 and 1.6 were made too
close to any of the changes you have made, an
overlap occurs. In such cases a warning is
printed, and the resulting file includes both
versions of the lines that overlap, delimited by
special markers.
See section update--Bring work tree in sync with repository, for a complete description of the
update command.
Suppose revision 1.4 of `driver.c' contains this:
#include <stdio.h>
void main()
{
parse();
if (nerr == 0)
gencode();
else
fprintf(stderr, "No code generated.\n");
exit(nerr == 0 ? 0 : 1);
}
Revision 1.6 of `driver.c' contains this:
#include <stdio.h>
int main(int argc,
char **argv)
{
parse();
if (argc != 1)
{
fprintf(stderr, "tc: No args expected.\n");
exit(1);
}
if (nerr == 0)
gencode();
else
fprintf(stderr, "No code generated.\n");
exit(!!nerr);
}
Your working copy of `driver.c', based on revision 1.4, contains this before you run `cvs update':
#include <stdlib.h>
#include <stdio.h>
void main()
{
init_scanner();
parse();
if (nerr == 0)
gencode();
else
fprintf(stderr, "No code generated.\n");
exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
}
You run `cvs update':
$ cvs update driver.c RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v retrieving revision 1.4 retrieving revision 1.6 Merging differences between 1.4 and 1.6 into driver.c rcsmerge warning: overlaps during merge cvs update: conflicts found in driver.c C driver.c
CVS tells you that there were some conflicts. Your original working file is saved unmodified in `.#driver.c.1.4'. The new version of `driver.c' contains this:
#include <stdlib.h>
#include <stdio.h>
int main(int argc,
char **argv)
{
init_scanner();
parse();
if (argc != 1)
{
fprintf(stderr, "tc: No args expected.\n");
exit(1);
}
if (nerr == 0)
gencode();
else
fprintf(stderr, "No code generated.\n");
<<<<<<< driver.c
exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
=======
exit(!!nerr);
>>>>>>> 1.6
}
Note how all non-overlapping modifications are incorporated in your working copy, and that the overlapping section is clearly marked with `<<<<<<<', `=======' and `>>>>>>>'.
You resolve the conflict by editing the file, removing the markers and the erroneous line. Suppose you end up with this file:
#include <stdlib.h>
#include <stdio.h>
int main(int argc,
char **argv)
{
init_scanner();
parse();
if (argc != 1)
{
fprintf(stderr, "tc: No args expected.\n");
exit(1);
}
if (nerr == 0)
gencode();
else
fprintf(stderr, "No code generated.\n");
exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
}
You can now go ahead and commit this as revision 1.7.
$ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c Checking in driver.c; /usr/local/cvsroot/yoyodyne/tc/driver.c,v <-- driver.c new revision: 1.7; previous revision: 1.6 done
For your protection, CVS will refuse to check in a
file if a conflict occurred and you have not resolved
the conflict. Currently to resolve a conflict, you
must change the timestamp on the file, and must also
insure that the file contains no conflict markers. If
your file legitimately contains conflict markers (that
is, occurrences of `>>>>>>> ' at the start of a
line that don't mark a conflict), then CVS has
trouble handling this and you need to start hacking on
the CVS/Entries file or other such workarounds.
If you use release 1.04 or later of pcl-cvs (a GNU Emacs front-end for CVS) you can use an Emacs package called emerge to help you resolve conflicts. See the documentation for pcl-cvs.
It is often useful to inform others when you commit a new revision of a file. The `-i' option of the `modules' file, or the `loginfo' file, can be used to automate this process. See section The modules file. See section Loginfo. You can use these features of CVS to, for instance, instruct CVS to mail a message to all developers, or post a message to a local newsgroup.
If several developers try to run CVS at the same time, one may get the following message:
[11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo
CVS will try again every 30 seconds, and either continue with the operation or print the message again, if it still needs to wait. If a lock seems to stick around for an undue amount of time, find the person holding the lock and ask them about the cvs command they are running. If they aren't running a cvs command, look for and remove files starting with `#cvs.tfl', `#cvs.rfl', or `#cvs.wfl' from the repository.
Note that these locks are to protect CVS's internal data structures and have no relationship to the word lock in the sense used by RCS---which refers to reserved checkouts (see section Multiple developers).
Any number of people can be reading from a given repository at a time; only when someone is writing do the locks prevent other people from reading or writing.
One might hope for the following property
If someone commits some changes in one cvs command, then an update by someone else will either get all the changes, or none of them.
but CVS does not have this property. For example, given the files
a/one.c a/two.c b/three.c b/four.c
if someone runs
cvs ci a/two.c b/three.c
and someone else runs cvs update at the same
time, the person running update might get only
the change to `b/three.c' and not the change to
`a/two.c'.
For many groups, use of CVS in its default mode is perfectly satisfactory. Users may sometimes go to check in a modification only to find that another modification has intervened, but they deal with it and proceed with their check in. Other groups prefer to be able to know who is editing what files, so that if two people try to edit the same file they can choose to talk about who is doing what when rather than be surprised at check in time. The features in this section allow such coordination, while retaining the ability of two developers to edit the same file at the same time.
For maximum benefit developers should use cvs
edit (not chmod) to make files read-write to
edit them, and cvs release (not rm) to
discard a working directory which is no longer in use,
but CVS is not able to enforce this behavior.
To enable the watch features, you first specify that certain files are to be watched.
-l] files ...
Specify that developers should run cvs edit
before editing files. CVS will create working
copies of files read-only, to remind developers
to run the cvs edit command before working on
them.
If files includes the name of a directory, CVS
arranges to watch all files added to the corresponding
repository directory, and sets a default for files
added in the future; this allows the user to set
notification policies on a per-directory basis. The
contents of the directory are processed recursively,
unless the -l option is given.
If files is omitted, it defaults to the current directory.
-l] files ...
Do not provide notification about work on files. CVS will create working copies of files read-write.
The files and -l arguments are processed as for cvs
watch on.
You can tell CVS that you want to receive
notifications about various actions taken on a file.
You can do this without using cvs watch on for
the file, but generally you will want to use cvs
watch on, so that developers use the cvs edit
command.
-a action] [-l] files ...
Add the current user to the list of people to receive notification of work done on files.
The -a option specifies what kinds of events CVS should notify
the user about. action is one of the following:
edit
cvs edit command (described
below) to a file.
unedit
cvs unedit command (described
below) or the cvs release command to a file, or has deleted
the file and allowed cvs update to recreate it.
commit
all
none
cvs edit,
described below.)
The -a option may appear more than once, or not at all. If
omitted, the action defaults to all.
The files and -l option are processed as for the
cvs watch commands.
-a action] [-l] files ...
Remove a notification request established using cvs watch add;
the arguments are the same. If the -a option is present, only
watches for the specified actions are removed.
When the conditions exist for notification, CVS
calls the `notify' administrative file. Edit
`notify' as one edits the other administrative
files (see section The administrative files). This
file follows the usual conventions for administrative
files (see section The common syntax), where each line is a regular
expression followed by a command to execute. The
command should contain a single ocurrence of `%s'
which will be replaced by the user to notify; the rest
of the information regarding the notification will be
supplied to the command on standard input. The
standard thing to put in the notify file is the
single line:
ALL mail %s -s \"CVS notification\"
This causes users to be notified by electronic mail.
Note that if you set this up in the straightforward way, users receive notifications on the server machine. One could of course write a `notify' script which directed notifications elsewhere, but to make this easy, CVS allows you to associate a notification address for each user. To do so create a file `users' in `CVSROOT' with a line for each user in the format user:value. Then instead of passing the name of the user to be notified to `notify', CVS will pass the value (normally an email address on some other machine).
Since a file which is being watched is checked out
read-only, you cannot simply edit it. To make it
read-write, and inform others that you are planning to
edit it, use the cvs edit command. Some systems
call this a checkout, but CVS uses that term
for obtaining a copy of the sources (see section Getting the source), an operation which those systems call a
get or a fetch.
Prepare to edit the working files files. CVS makes the
files read-write, and notifies users who have requested
edit notification for any of files.
The cvs edit command accepts the same options as the
cvs watch add command, and establishes a temporary watch for the
user on files; CVS will remove the watch when files are
unedited or committed. If the user does not wish to
receive notifications, she should specify -a none.
The files and -l option are processed as for the cvs
watch commands.
Normally when you are done with a set of changes, you
use the cvs commit command, which checks in your
changes and returns the watched files to their usual
read-only state. But if you instead decide to abandon
your changes, or not to make any changes, you can use
the cvs unedit command.
-l] files ...
Abandon work on the working files files, and revert them to the
repository versions on which they are based. CVS makes those
files read-only for which users have requested notification using
cvs watch on. CVS notifies users who have requested unedit
notification for any of files.
The files and -l option are processed as for the
cvs watch commands.
If watches are not in use, the unedit command
probably does not work, and the way to revert to the
repository version is to remove the file and then use
cvs update to get a new copy. The meaning is
not precisely the same; removing and updating may also
bring in some changes which have been made in the
repository since the last time you updated.
When using client/server CVS, you can use the
cvs edit and cvs unedit commands even if
CVS is unable to succesfully communicate with the
server; the notifications will be sent upon the next
successful CVS command.
-l] files ...
List the users currently watching changes to files. The report includes the files being watched, and the mail address of each watcher.
The files and -l arguments are processed as for the
cvs watch commands.
-l] files ...
List the users currently working on files. The report includes the mail address of each user, the time when the user began working with the file, and the host and path of the working directory containing the file.
The files and -l arguments are processed as for the
cvs watch commands.
If you use the watch features on a repository, it creates `CVS' directories in the repository and stores the information about watches in that directory. If you attempt to use CVS 1.6 or earlier with the repository, you get an error message such as
cvs update: cannot open CVS/Entries for reading: No such file or directory
and your operation will likely be aborted. To use the
watch features, you must upgrade all copies of CVS
which use that repository in local or server mode. If
you cannot upgrade, use the watch off and
watch remove commands to remove all watches, and
that will restore the repository to a state which
CVS 1.6 can cope with.
Reserved and unreserved checkouts each have pros and cons. Let it be said that a lot of this is a matter of opinion or what works given different groups' working styles, but here is an attempt to briefly describe the issues. There are many ways to organize a team of developers. CVS does not try to enforce a certain organization. It is a tool that can be used in several ways.
Reserved checkouts can be very counter-productive. If two persons want to edit different parts of a file, there may be no reason to prevent either of them from doing so. Also, it is common for someone to take out a lock on a file, because they are planning to edit it, but then forget to release the lock.
People, especially people who are familiar with reserved checkouts, often wonder how often conflicts occur if unreserved checkouts are used, and how difficult they are to resolve. The experience with many groups is that they occur rarely and usually are relatively straightforward to resolve.
The rarity of serious conflicts may be surprising, until one realizes that they occur only when two developers disagree on the proper design for a given section of code; such a disagreement suggests that the team has not been communicating properly in the first place. In order to collaborate under any source management regimen, developers must agree on the general design of the system; given this agreement, overlapping changes are usually straightforward to merge.
In some cases unreserved checkouts are clearly inappropriate. If no merge tool exists for the kind of file you are managing (for example word processor files or files edited by Computer Aided Design programs), and it is not desirable to change to a program which uses a mergeable data format, then resolving conflicts is going to be unpleasant enough that you generally will be better off to simply avoid the conflicts instead, by using reserved checkouts.
The watches features described above in section Mechanisms to track who is editing files can be considered to be an intermediate model between reserved checkouts and unreserved checkouts. When you go to edit a file, it is possible to find out who else is editing it. And rather than having the system simply forbid both people editing the file, it can tell you what the situation is and let you figure out whether it is a problem in that particular case or not. Therefore, for some groups it can be considered the best of both the reserved checkout and unreserved checkout worlds.
So far, all revisions shown in this manual have been on the main trunk of the revision tree, i.e., all revision numbers have been of the form x.y. One useful feature, especially when maintaining several releases of a software product at once, is the ability to make branches on the revision tree. Tags, symbolic names for revisions, will also be introduced in this chapter.
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 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 contain characters such as `%' or
`=', rather than being named analogously to
BASE and HEAD, to avoid conflicts with
actual tag names.
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 release-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 /usr/local/cvsroot/yoyodyne/tc/backend.c,v
Sticky Tag: (none)
Sticky Date: (none)
Sticky Options: (none)
Existing Tags:
release-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 release-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 release-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
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 select to either incorporate them on the main trunk, or leave them on the branch.
The rtag command can be used to create a branch.
The rtag command is much like tag, but it
does not require that you have a working copy of the
module. See section rtag--Add a symbolic tag to a module. (You can also use the tag
command; see section tag--Add a symbolic tag to checked out versions of files).
$ cvs rtag -b -r release-1-0 release-1-0-patches tc
The `-b' flag makes rtag create a branch
(rather than just a symbolic revision name). `-r
release-1-0' says that this branch should be rooted at the node (in
the revision tree) that corresponds to the tag
`release-1-0'. Note that the numeric revision number that matches
`release-1-0' will probably be different from file to file. The
name of the new branch is `release-1-0-patches', and the
module affected is `tc'.
To fix the problem in release 1.0, you need a working copy of the branch you just created.
$ cvs checkout -r release-1-0-patches tc
$ 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 /usr/local/cvsroot/yoyodyne/tc/driver.c,v
Sticky Tag: release-1-0-patches (branch: 1.7.2)
Sticky Date: (none)
Sticky Options: (none)
Existing Tags:
release-1-0-patches (branch: 1.7.2)
release-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 /usr/local/cvsroot/yoyodyne/tc/backend.c,v
Sticky Tag: release-1-0-patches (branch: 1.4.2)
Sticky Date: (none)
Sticky Options: (none)
Existing Tags:
release-1-0-patches (branch: 1.4.2)
release-1-0 (revision: 1.4)
release-0-4 (revision: 1.4)
As the output from the status command shows the branch
number is created by adding a digit at the tail of the revision number
it is based on. (If `release-1-0' corresponds to revision 1.4, the
branch's revision number will be 1.4.2. For obscure reasons CVS always
gives branches even numbers, starting at 2.
See section Revision numbers).
The `-r release-1-0-patches' flag that was given
to checkout in the previous example
is sticky, that is, it will apply to subsequent commands
in this directory. If you commit any modifications, they are
committed on the branch. You can later merge the modifications into
the main trunk. See section Merging.
You can use the status command to see what
sticky tags or dates are set:
$ vi driver.c # Fix the bugs
$ cvs commit -m "Fixed initialization bug" driver.c
Checking in driver.c;
/usr/local/cvsroot/yoyodyne/tc/driver.c,v <-- driver.c
new revision: 1.7.2.1; previous revision: 1.7
done
$ cvs status -v 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 /usr/local/cvsroot/yoyodyne/tc/driver.c,v
Sticky Tag: release-1-0-patches (branch: 1.7.2)
Sticky Date: (none)
Sticky Options: (none)
Existing Tags:
release-1-0-patches (branch: 1.7.2)
release-1-0 (revision: 1.7)
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.
Sticky tags are not just for branches. 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 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 $
You can include the changes made between any two revisions into your working copy, by merging. You can then commit that revision, and thus effectively copy the changes onto another branch.
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
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:
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.
$ cvs update -l # Don't update files in subdirectories
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 from a module, 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 front end for rcs. 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 Branches). 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 of the module.
Here is what you can do to remove a file from a module, 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.
-lR] files ...
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. The `-R' option (the default) specifies that it will recurse into subdirectories; `-l' specifies that it will not.
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 .
If you change your mind you can easily resurrect the
file before you commit it, using the 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 added only on the branch which you are working on (see section Branches). You can later merge the additions to another branch if you want (see section Merging can add or remove files).
If you modify a program to better fit your site, you probably want to include your modifications when the next release of the program arrives. CVS can help you with this task.
In the terminology used in CVS, the supplier of the program is called a vendor. The unmodified distribution from the vendor is checked in on its own branch, the vendor branch. CVS reserves branch 1.1.1 for this use.
When you modify the source and commit it, your revision will end up on the main trunk. When a new release is made by the vendor, you commit it on the vendor branch and copy the modifications onto the main trunk.
Use the import command to create and update
the vendor branch. After a successful import
the vendor branch is made the `head' revision, so
anyone that checks out a copy of the file gets that
revision. When a local modification is committed it is
placed on the main trunk, and made the `head'
revision.
Use the import command to check in the sources
for the first time. When you use the import
command to track third-party sources, the vendor
tag and release tags are useful. The
vendor tag is a symbolic name for the branch
(which is always 1.1.1, unless you use the `-b
branch' flag---See section import options). The
release tags are symbolic names for a particular
release, such as `FSF_0_04'.
Suppose you use wdiff (a variant of diff
that ignores changes that only involve whitespace), and
are going to make private modifications that you want
to be able to use even when new releases are made in
the future. You start by importing the source to your
repository:
$ tar xfz wdiff-0.04.tar.gz $ cd wdiff-0.04 $ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04
The vendor tag is named `FSF_DIST' in the above example, and the only release tag assigned is `WDIFF_0_04'.
When a new release of the source arrives, you import it into the
repository with the same import command that you used to set up
the repository in the first place. The only difference is that you
specify a different release tag this time.
$ tar xfz wdiff-0.05.tar.gz $ cd wdiff-0.05 $ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF_DIST WDIFF_0_05
For files that have not been modified locally, the newly created
revision becomes the head revision. If you have made local
changes, import will warn you that you must merge the changes
into the main trunk, and tell you to use `checkout -j' to do so.
$ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff
The above command will check out the latest revision of `wdiff', merging the changes made on the vendor branch `FSF_DIST' since yesterday into the working copy. If any conflicts arise during the merge they should be resolved in the normal way (see section Conflicts example). Then, the modified files may be committed.
Using a date, as suggested above, assumes that you do not import more than one release of a product per day. If you do, you can always use something like this instead:
$ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff
In this case, the two above commands are equivalent.
Use the `-k' wrapper option to tell import which files are binary. See section The cvswrappers file.
Moving files to a different directory or renaming them is not difficult, but some of the ways in which this works may be non-obvious. (Moving or renaming a directory is even harder. See section Moving and renaming directories).
The examples below assume that the file old is renamed to new.
The normal way to move a file is to copy old to new, and then issue the normal CVS commands to remove old from the repository, and add new to it. (Both old and new could contain relative paths, for example `foo/bar.c').
$ mv old new $ cvs remove old $ cvs add new $ cvs commit -m "Renamed old to new