Introduction to CVS
cvs is a front end to the rcs (1) revision control system which extends
the notion of revision control from a collection of files in a single
directory to a hierarchical collection of directories consisting of
revision controlled files. These directories and files can be combined
together to form a software release. cvs provides the functions necessary
to manage these software releases and to control the concurrent editing
of source files among multiple software developers.
cvs keeps a single copy of the master sources. This copy is called
the source "repository"; it contains all the information to permit
extracting previous software releases at any time based on either
a symbolic revision tag, or a date in the past.
ESSENTIAL COMMANDS
cvs provides a rich variety of commands (cvs_command in the Synopsis),
each of which often has a wealth of options, to satisfy the many needs
of source management in distributed environments. However, you don't
have to master every detail to do useful work with cvs; in fact, five
commands are sufficient to use (and contribute to) the source repository.
cvs checkout modules...
A necessary preliminary for most cvs work: creates your private copy
of the source for modules (named collections of source; you can also
use a path relative to the source repository here). You can work with
this copy without interfering with others' work. At least one subdirectory
level is always created.
cvs update
Execute this command from within your private source directory when
you wish to update your copies of source files from changes that other
developers have made to the source in the repository.
cvs add file...
Use this command to enroll new files in cvs records of your working
directory. The files will be added to the repository the next time
you run 'cvs commit'. Note: You should use the 'cvs import' command
to bootstrap new sources into the source repository. 'cvs add' is
only used for new files to an already checked out module.
cvs remove file...
Use this command (after erasing any files listed) to declare that
you wish to eliminate files from the repository. The removal does
not affect others until you run 'cvs commit'.
cvs commit file...
Use this command when you wish to "publish" your changes to other
developers, by incorporating them in the source repository.
OPTIONS
The cvs command line can include cvs_options, which apply to the overall
cvs program; a cvs_command, which specifies aparticular action on
the source repository; and command_options and command_arguments to
fully specify what the cvs_command will do.
Warning: you must be careful of precisely where you place options relative
to the cvs_command. The same option can mean different things depending
on whether it is in the cvs_options position (to the left of a cvs
command) or in the command_options position (to the right of a cvs
command).
There are only two situations where you may omit cvs_command: 'cvs
-H' elicits a list of available commands and 'cvs -v ' displays version
information on cvs itself.
CVS OPTIONS
Use these options for overall control of the cvs program:
- H
- Display usage information about the specified cvs_command (but do
not actually execute the command). If you don't specify a command
name, 'cvs -H' displays a summary of all the commands available.
- Q
- Causes the command to be really quiet; the command will generate
output only for serious problems.
- q
- Causes the command to be somewhat quiet; informational messages,
such as reports of recursion through subdirectories, are suppressed.
- b bindir
- Use bindir as the directory where RCS programs are located.
Overrides the setting of the RCSBIN environment variable. This value
should be specified as an absolute pathname.
- d CVS_root_directory
- Use CVS_root_directory as the root directory
pathname of the master RCS source repository. Overrides the setting
of the CVSROOT environment variable. This value should be specified
as an absolute pathname.
- e editor
- Use editor to enter revision log information. Overrides the
setting of the EDITOR environment variable.
- l
- Do not log the cvs_command in the command history (but execute it
anyway). See the description of the history command for information
on command history.
- n
- Do not change any files. Attempt to execute the cvs_command, but
only to issue reports; do not remove, update, or merge any existing
files, or create any new files.
- t
- Trace program execution; display messages showing the steps of cvs
activity. Particularly useful with -n to explore the potential impact
of an unfamiliar command.
- r
- Makes new working files files read only. Same effect as if the
CVSREAD environment variable is set.
- v
- Displays version and copyright information for cvs.
- w
- Makes new working files read write (default). Overrides the setting
of the CVSREAD environment variable.
USAGE
Except when requesting general help with 'cvs -H', you mustspecify
a cvs_command to cvs to performa specific release control function.
Each cvs command accepts its own collection of options and arguments.
However, many options are available across several commands. You can
display a usage summary for each command by specifying the H option
with the command.
CVS COMMAND SUMMARY
Here are brief descriptions of all the cvs commands :
add Add a new file or directory to the repository, pending a 'cvs
commit' on the same file. Can only be done from within sources created
by a previous 'cvs checkout' invocation. Use 'cvs import' to place
whole new hierarchies of sources under cvs control. (Does not directly
affect repository; changes working directory.)
admin Execute RCS control functions on the source repository. (Changes
repository directly; uses working directory without changing it.)
checkout Make a working directory of source files for editing. (Creates
or changes working directory.)
commit Apply to the source repository changes, additions, and deletions
from your working directory. (Changes repository.)
diff Show differences between files in working directory and source
repository, or between two revisions in source repository. (Does not
change either repository or working directory.)
export Prepare copies of a set of source files for shipment off-site.
Differs from 'cvs checkout' in that no cvs administrative directories
are created (and therefore 'cvs commit' cannot be executed from a
directory prepared with 'cvsÊexport'), and a symbolic tag must be
specified. (Does not change repository; creates directory similar
to working directories).
history Show reports on cvs commands that you or others have executed
on a particular file or directory in the source repository. (Does
not change repository or working directory.) History logs are kept
only if enabled by creation of the '$CVSROOT/CVSROOT/history' file;
see cvs(5).
import Incorporate a set of updates from off site into the source
repository, as a "vendor branch". (Changes repository.)
log Display RCS log information. (Does not change repository or working
directory.)
rdiff Prepare a collection of diffs as a patch file between two releases
in the repository. (Does not change repository or working directory.)
release Cancel a 'cvsÊcheckout' abandoning any changes. (Can delete
working directory; no effect on repository.)
remove Remove files from the source repository, pending a 'cvs-commit'
on the same files. (Does not directly affect repository; changes working
directory.)
rtag Explicitly specify a symbolic tag for particular revisions of
files in the source repository. See also 'cvstag'. (Changes repository
directly; does not require or affect working directory.)
status Show current status of files: latest version, versionÊin working
directory, whether working version has been edited and, optionally,
symbolic tags in the RCS file. (Does not change repository or working
directory.)
tag Specify a symbolic tag for files in the repository. Tags the revisions
that were last synchronized with your working directory. (Changes
repository directly; uses working directory without changing it.)
update Bring your working directory up to date with changesfrom the
repository. Merges are performed automatically when possible; a warning
is issued if manualresolution is required for conflicting changes.(Changes
working directory; does not change repository.)
COMMON COMMAND OPTIONS
This section describes the command_options that are available across
several cvs commands. Not all commands support all of these options;
each option is only supported for commands where it makes sense. However,
when a command has one of these options you can count on the same
meaning for the option as in other commands. (Other command options,
which are listed with the individual commands, may have different
meanings from one cvs command to another.) Warning: the history command
is an exception; it supports many options that conflict even with
these standard options.
- D date_spec
- Use the most recent revision no later than date_spec (a
single argument, date description specifying a date in the past).
A wide variety of date formats are supported by the underlying RCS
facilities, similar to those described in co(1), but not exactly the
same. The date_spec is interpreted as being in the local time zone,
unless a specific time zone is specified. The specification is "sticky"
when you use it to make a private copy of a source file; that is,
when you get a working file using -D, cvs records the date you specified,
so that further updates in the same directory will use the same date
(unless you explicitly override it; see the description of the update
command). -D is available with the checkout, diff, history, rdiff,
rtag, and update commands. Examples of valid date specifications include:
<![CDATA[ 1 month ago
2 hours ago
400000 seconds ago
last year
last Monday
yesterday
a fortnight ago
3/31/92 10:00:07 PST
January 23, 1987 10:05pm
22:00 GMT
]]>
- f
- When you specify a particular date or tag to cvs commands, they
normally ignore files that do not contain the tag (or did not exist
on the date) that you specified. Use the -f option if you want files
retrieved even when there is no match for the tag or date. (The most
recent version is used in this situation.) -f is available with these
commands: checkout, export, rdiff, rtag, and update.
- H
- Help; describe the options available for this command. This is
the only option supported for all cvs commands.
- k kflag
- Alter the default RCS processing of keywords; all the k
options described in rcs(1) are available. The -k option is available
with the add, checkout, diff, rdiff, and update commands. Your kflag
specification is "sticky" when you use it to create a private copy
of a source file; that is, when you use this option with the checkout
or update commands, cvs associatesyour selected kflag with the file,
and continues to use it with future update commands on the same file
until you specify otherwise.
- l
- Local; run only in current working directory, rather than recurring
through subdirectories. Available with the following commands: checkout,
commit, diff, export,remove, rdiff, status, tag, and update. Warning:
this is not the same as the overall 'cvs -l' option, which you can
specify to the left of a cvs command!
- n
- Do not run any checkout/commit/tag/ program. (A program can be
specified to run on each of these activities, in the modules database;
this option bypasses it.) Available with the checkout, commit, export,
and rtag commands. Warning: this is not the same as theoverall 'cvs
-n' option, which you can specify to the left of a cvs command!
- P
- Prune (remove) directories that are empty after being updated,
on checkout, or update. Normally, an empty directory (one that is
void of revision controlled files) is left alone. Specifying -P will
cause these directories to be silently removed from your checked out
sources. This does not remove the directory from the repository, only
from your checked out copy. Note that this option is implied by the
-r or -D options of checkout and export.
- p
- Pipe the files retrieved from the repository to standard output,
rather than writing them in the current directory. Available with
the checkout and update commands.
- Q
- Causes the command to be really quiet; the command will generate
output only for serious problems. Available with the following commands:
checkout, import, export, rdiff, rtag, tag, and update.
- q
- Causes the command to be somewhat quiet; informational messages,
such as reports of recursion through subdirectories, are suppressed.
Available with the following commands: checkout, import, export, rtag,
tag and update.
- r tag
- Use the revision specified by the tag argument instead of the
default "head" revision. As well as arbitrary tags defined with the
tag or rtag command, two special tags are always available: 'HEAD'
refers to the most recent version available in the repository, and
'BASE' refers to the revision you last checked out into thecurrent
working directory.
-
- The tag specification is "sticky" when you use thisoption with 'cvs
checkout' or 'cvs update' to make your own copy of a file: cvs remembers
the tag and continues to use it on future update commands, until you
specify otherwise. tag can be either a symbolic or numeric tag, in
RCS fashion. Specifying the -q option alongwith the -r option is often
useful, to suppress the warning messages when the RCS file does not
contain the specified tag. -r is available with the checkout, commit,
diff, history, export, rdiff, rtag, and update commands. Warning:
this is not the same as the overall 'cvs -r' option, which you can
specify to the left of a cvs command!