/contrib/cvs/man/cvs.1
Unknown | 2212 lines | 2211 code | 1 blank | 0 comment | 0 complexity | 4dd2ce683c24d5bd9a8ddaa95b146ef3 MD5 | raw file
Possible License(s): MPL-2.0-no-copyleft-exception, BSD-3-Clause, LGPL-2.0, LGPL-2.1, BSD-2-Clause, 0BSD, JSON, AGPL-1.0, GPL-2.0
- \fBimport\fR.
- .\" $FreeBSD$
- .de Id
- .ds Rv \\$3
- .ds Dt \\$4
- ..
- .TH CVS 1 "\*(Dt"
- .\" Full space in nroff; half space in troff
- .de SP
- .if n .sp
- .if t .sp .5
- ..
- .\" quoted command
- .de `
- .RB ` "\|\\$1\|" '\\$2
- ..
- .SH "NAME"
- cvs \- Concurrent Versions System
- .SH "SYNOPSIS"
- .TP
- \fBcvs\fP [ \fIcvs_options\fP ]
- .I cvs_command
- [
- .I command_options
- ] [
- .I command_args
- ]
- .SH "NOTE"
- This manpage is a summary of some of the features of
- .B cvs
- but it may no longer be kept up-to-date.
- For more current and in-depth documentation, please consult the
- Cederqvist manual (via the
- .B info cvs
- command or otherwise,
- as described in the SEE ALSO section of this manpage).
- .SH "DESCRIPTION"
- .IX "revision control system" "\fLcvs\fR"
- .IX cvs "" "\fLcvs\fP \- concurrent versions system"
- .IX "concurrent versions system \- \fLcvs\fP"
- .IX "release control system" "cvs command" "" "\fLcvs\fP \- concurrent versions system"
- .IX "source control system" "cvs command" "" "\fLcvs\fP \- concurrent versions system"
- .IX revisions "cvs command" "" "\fLcvs\fP \- source control"
- CVS is a version control system, which allows you to keep old versions
- of files (usually source code), keep a log of who, when, and why
- changes occurred, etc., like RCS or SCCS. Unlike the simpler systems,
- CVS does not just operate on one file at a time or one directory at a
- time, but operates on hierarchical collections of directories
- consisting of version controlled files. CVS helps to manage releases
- and to control the concurrent editing of source files among multiple
- authors. CVS allows triggers to enable/log/control various
- operations and works well over a wide area network.
- .SP
- .B 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.
- .SH "ESSENTIAL COMMANDS"
- .B cvs
- provides a rich variety of commands (\fIcvs_command\fP 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
- .BR cvs ;
- in fact, five commands are sufficient to use (and contribute to)
- the source repository.
- .TP
- \fBcvs checkout\fP \fImodules\fP\|.\|.\|.
- A necessary preliminary for most \fBcvs\fP work: creates your private
- copy of the source for \fImodules\fP (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.
- .TP
- .B cvs update
- Execute this command from \fIwithin\fP 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.
- .TP
- \fBcvs add\fP \fIfile\fP\|.\|.\|.
- Use this command to enroll new files in \fBcvs\fP 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.
- .TP
- \fBcvs remove\fP \fIfile\fP\|.\|.\|.
- 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".
- .TP
- \fBcvs commit\fP \fIfile\fP\|.\|.\|.
- Use this command when you wish to ``publish'' your changes to other
- developers, by incorporating them in the source repository.
- .SH "OPTIONS"
- The
- .B cvs
- command line can include
- .IR cvs_options ,
- which apply to the overall
- .B cvs
- program; a
- .IR cvs_command ,
- which specifies a particular action on the source repository; and
- .I command_options
- and
- .I command_arguments
- to fully specify what the
- .I cvs_command
- will do.
- .SP
- .I Warning:
- you must be careful of precisely where you place options relative to the
- .IR cvs_command .
- The same option can mean different things depending on whether it
- is in the
- .I cvs_options
- position (to the left of a
- .B cvs
- command) or in the
- .I command_options
- position (to the right of a
- .B cvs
- command).
- .SP
- There are only two situations where you may omit
- .IR cvs_command :
- .` "cvs \-H"
- or
- .` "cvs --help"
- elicits a list of available commands, and
- .` "cvs \-v"
- or
- .` "cvs --version"
- displays version information on \fBcvs\fP itself.
- .SP
- .SH "CVS OPTIONS"
- As of release 1.6,
- .B cvs
- supports
- .SM GNU
- style long options as well as short options. Only
- a few long options are currently supported, these are listed in
- brackets after the short options whose functions they duplicate.
- .SP
- Use these options to control the overall
- .B cvs
- program:
- .TP
- .B \-H [ --help ]
- Display usage information about the specified
- .I 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.
- .TP
- .B \-Q
- Causes the command to be
- .I really
- quiet; the command will generate output only for serious problems.
- .TP
- .B \-q
- Causes the command to be somewhat quiet; informational messages, such
- as reports of recursion through subdirectories, are suppressed.
- .TP
- \fB\-b\fP \fIbindir\fP
- Use
- .I bindir
- as the directory where
- .SM RCS
- programs are located (CVS 1.9 and older).
- Overrides the setting of the
- .SM RCSBIN
- environment variable.
- This value should be specified as an absolute pathname.
- .TP
- \fB\-d\fP \fICVS_root_directory\fP
- Use
- .I CVS_root_directory
- as the root directory pathname of the master
- source repository.
- Overrides the setting of the
- .SM CVSROOT
- environment variable.
- This value should be specified as an absolute pathname.
- .TP
- \fB\-e\fP \fIeditor\fP
- Use
- .I editor
- to enter revision log information.
- Overrides the setting of the
- .SM CVSEDITOR\c
- ,
- .SM VISUAL\c
- , and
- .SM EDITOR
- environment variables.
- .TP
- .B \-f
- Do not read the
- .B cvs
- startup file (\fI~/.cvsrc\fP).
- .TP
- .B \-n
- Do not change any files. Attempt to execute the
- .IR cvs_command ,
- but only to issue reports; do not remove, update, or merge any
- existing files, or create any new files.
- .TP
- .B \-t
- Trace program execution; display messages showing the steps of
- .B cvs
- activity. Particularly useful with
- .B \-n
- to explore the potential impact of an unfamiliar command.
- .TP
- .B \-r
- Makes new working files read-only.
- Same effect as if the
- .SM CVSREAD
- environment variable is set.
- .TP
- .B \-R
- Turns on read-only repository mode. This allows one to check out from a
- read-only repository, such as within an anoncvs server, or from a CDROM
- repository.
- Same effect as if the
- .SM CVSREADONLYFS
- environment variable is set. Using
- .B \-R
- can also considerably speed up checkout's over NFS.
- .TP
- .B \-v [ --version ]
- Displays version and copyright information for
- .BR cvs .
- .TP
- .B \-w
- Makes new working files read-write (default).
- Overrides the setting of the
- .SM CVSREAD
- environment variable.
- .TP
- .B \-g
- Forces group-write perms on working files. This option is typically
- used when you have multiple users sharing a single checked out source
- tree, allowing them to operate their shells with a less dangerous umask.
- To use this feature, create a directory to hold the checked-out source
- tree, set it to a private group, and set up the directory such that
- files created under it inherit the group id of the directory. This occurs
- automatically with FreeBSD. With SysV you must typically set the SGID bit
- on the directory. The users who are to share the checked out tree must
- be placed in that group. Note that the sharing of a single checked-out
- source tree is very different from giving several users access to a common
- CVS repository. Access to a common CVS repository already maintains shared
- group-write perms and does not require this option.
- To use the option transparently, simply place the line 'cvs -g' in your
- ~/.cvsrc file. Doing this is not recommended unless you firewall all your
- source checkouts within a private group or within a private mode 0700
- directory.
- .TP
- .B \-x
- Encrypt all communication between the client and the server. As of
- this writing, this is only implemented when using a Kerberos
- connection.
- .TP
- \fB\-z\fP \fIcompression\-level\fP
- When transferring files across the network use
- .B gzip
- with compression level \fIcompression\-level\fP to compress and
- de-compress data as it is transferred. Requires the presence of
- the
- .SM GNU
- .B gzip
- program in the current search path at both ends of the link.
- .SH "USAGE"
- Except when requesting general help with
- .` "cvs \-H",
- you must specify a
- .I cvs_command
- to
- .B cvs
- to select a specific release control function to perform.
- Each
- .B 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
- .B \-H
- option with the command.
- .SH "CVS STARTUP FILE"
- Normally, when CVS starts up, it reads the
- .I .cvsrc
- file from the home directory of the user reading it. This startup
- procedure can be turned off with the
- .B \-f
- flag.
- .SP
- The
- .I .cvsrc
- file lists CVS commands with a list of arguments, one command per
- line. For example, the following line in \fI.cvsrc\fP:
- .SP
- diff \-c
- .SP
- will mean that the
- .` "cvs diff"
- command will always be passed the \-c option in addition to any
- other options that are specified in the command line (in this case
- it will have the effect of producing context sensitive diffs for
- all executions of
- .` "cvs diff"
- ).
- .SP
- Global options are specified using the \fBcvs\fP keyword. For example,
- the following:
- .SP
- cvs \-q
- .SP
- will mean that all
- .` "cvs"
- commands will behave as thought he \-q global option had been supplied.
- .SH "CVS COMMAND SUMMARY"
- Here are brief descriptions of all the
- .B cvs
- commands:
- .TP
- .B 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
- .B cvs
- control.
- (Does not directly affect repository; changes
- working directory.)
- .TP
- .B admin
- Execute
- control functions on the source repository. (Changes
- repository directly; uses working directory without changing it.)
- .TP
- .B checkout
- Make a working directory of source files for editing. (Creates or changes
- working directory.)
- .TP
- .B commit
- Apply to the source repository changes, additions, and deletions from your
- working directory. (Changes repository.)
- .TP
- .B 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.)
- .TP
- .B export
- Prepare copies of a set of source files for shipment off site.
- Differs from
- .` "cvs checkout"
- in that no
- .B 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).
- .TP
- .B history
- Show reports on
- .B 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
- .BR cvs ( 5 ).
- .TP
- .B import
- Incorporate a set of updates from off-site into the source repository,
- as a ``vendor branch''. (Changes repository.)
- .TP
- .B init
- Initialize a repository by adding the CVSROOT subdirectory and some default
- control files. You must use this command or initialize the repository in
- some other way before you can use it.
- .TP
- .B log
- Display
- log information.
- (Does not change repository or working directory.)
- .TP
- .B rdiff
- Prepare a collection of diffs as a patch file between two releases in
- the repository. (Does not change repository or working directory.)
- .TP
- .B release
- Cancel a
- .` "cvs checkout",
- abandoning any changes.
- (Can delete working directory; no effect on repository.)
- .TP
- .B remove
- Remove files from the source repository, pending a
- .` "cvs commit"
- on the same files. (Does not directly affect repository;
- changes working directory.)
- .TP
- .B rtag
- Explicitly specify a symbolic tag for particular revisions of files in the
- source repository. See also
- .` "cvs tag".
- (Changes repository directly; does not require or affect
- working directory.)
- .TP
- .B status
- Show current status of files: latest version, version in working
- directory, whether working version has been edited and, optionally,
- symbolic tags in the
- .SM RCS
- file. (Does not change
- repository or working directory.)
- .TP
- .B tag
- Specify a symbolic tag for files in the repository. By default, tags
- the revisions
- that were last synchronized with your working directory. (Changes
- repository directly; uses working directory without changing it.)
- .TP
- .B update
- Bring your working directory up to date with changes from the
- repository. Merges are performed automatically when possible; a
- warning is issued if manual resolution is required for conflicting
- changes. (Changes working directory; does not change repository.)
- .SH "COMMON COMMAND OPTIONS"
- This section describes the
- .I command_options
- that are available across several
- .B 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
- .B cvs
- command to another.)
- .I "Warning:"
- the
- .B history
- command is an exception;
- it supports many options that conflict
- even with these standard options.
- .TP
- \fB\-D\fP \fIdate_spec\fP
- Use the most recent revision no later than \fIdate_spec\fP (a single
- argument, date description specifying a date in the
- past). A wide variety of date formats are supported, in particular
- ISO ("1972-09-24 20:05") or Internet ("24 Sep 1972 20:05").
- The \fIdate_spec\fP is interpreted as being in the local timezone, unless a
- specific timezone 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 \fB\-D\fP, \fBcvs\fP 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 \fBupdate\fP command).
- .B \-D
- is available with the
- .BR checkout ", " diff ", " history ", " export ", "
- .BR rdiff ", " rtag ", and "
- .B update
- commands.
- Examples of valid date specifications include:
- .in +1i
- .ft B
- .nf
- 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
- .fi
- .ft P
- .in -1i
- .TP
- .B \-f
- When you specify a particular date or tag to \fBcvs\fP commands, they
- normally ignore files that do not contain the tag (or did not exist on
- the date) that you specified. Use the \fB\-f\fP 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.)
- .B \-f
- is available with these commands:
- .BR checkout ", " export ", "
- .BR rdiff ", " rtag ", and " update .
- .TP
- \fB\-k\fP \fIkflag\fP
- Alter the default
- processing of keywords.
- The \fB\-k\fP option is available with the
- .BR add ", " checkout ", " diff ", " rdiff ", " export ", and "
- BR update
- commands. Your \fIkflag\fP 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 \fBcheckout\fP or \fBupdate\fP commands,
- \fBcvs\fP associates your selected \fIkflag\fP with the file, and
- continues to use it with future \fBupdate\fP commands on the same file
- until you specify otherwise.
- .SP
- Some of the more useful \fIkflag\fPs are \-ko and \-kb (for binary files),
- and \-kv which is useful for an
- .B export
- where you wish to retain keyword information after an
- .B import
- at some other site.
- .TP
- .B \-l
- Local; run only in current working directory, rather than recurring through
- subdirectories. Available with the following commands:
- .BR checkout ", " commit ", " diff ", "
- .BR export ", " remove ", " rdiff ", " rtag ", "
- .BR status ", " tag ", and " update .
- .TP
- .B \-n
- Do
- .I not
- run any
- .BR checkout / commit / tag / update
- program. (A program can be specified to run on each of these
- activities, in the modules database; this option bypasses it.)
- Available with the
- .BR checkout ", " export ", and "
- .B rtag
- commands.
- .I Warning:
- this is not the same
- as the overall
- .` "cvs \-n"
- option, which you can specify to the
- .I left
- of a
- .B cvs
- command!
- .TP
- .B \-P
- Prune (remove) directories that are empty after being updated, on
- .BR checkout ", or " update .
- Normally, an empty directory (one that is void of revision-controlled
- files) is left alone.
- Specifying
- .B \-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
- .B \-r
- or
- .B \-D
- options of
- .BR checkout " and " export .
- .TP
- .B \-T
- Create/Update CVS/Template by copying it from the (local) repository.
- This option is useful for developers maintaining a local cvs repository
- but committing to a remote repository. By maintaining CVS/Template the
- remote commits will still be able to bring up the proper template in the
- commit editor session.
- Available with the
- .BR checkout " and " update
- commands.
- .TP
- .B \-p
- Pipe the files retrieved from the repository to standard output,
- rather than writing them in the current directory. Available with the
- .BR checkout " and " update
- commands.
- .TP
- \fB\-r\fP \fItag\fP
- Use the revision specified by the
- .I tag
- argument instead of the default ``head'' revision. As well as
- arbitrary tags defined with the \fBtag\fP or \fBrtag\fP 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 the current working
- directory.
- .SP
- The \fItag\fP specification is ``sticky'' when you use
- this option with
- .` "cvs checkout"
- or
- .` "cvs update"
- to
- make your own copy of a file: \fBcvs\fP remembers the \fItag\fP and
- continues to use it on future \fBupdate\fP commands, until you specify
- otherwise.
- .I tag
- can be either a symbolic or numeric tag.
- When a command expects a specific revision,
- the name of a branch is interpreted as the most recent
- revision on that branch.
- Specifying the
- .B \-q
- global option along with the
- .B \-r
- command option is often useful, to suppress the warning messages when the
- .SM RCS
- file does not contain the specified tag.
- .B \-r
- is available with the
- .BR annotate ", " checkout ", "
- .BR commit ", " diff ", " history ", " export ", " rdiff ", "
- .BR rtag ", and " update
- commands.
- .I Warning:
- this is not the same
- as the overall
- .` "cvs \-r"
- option, which you can specify to the
- .I left
- of a
- .B cvs
- command!
- .SH "CVS COMMANDS"
- Here (finally) are details on all the
- .B cvs
- commands and the options each accepts. The summary lines at the top
- of each command's description highlight three kinds of things:
- .TP 1i
- \ \ \ \ Command Options and Arguments
- Special options are described in detail below; common command options
- may appear only in the summary line.
- .TP 1i
- \ \ \ \ Working Directory, or Repository?
- Some \fBcvs\fP commands require a working directory to operate; some
- require a repository. Also, some commands \fIchange\fP the
- repository, some change the working directory, and some change
- nothing.
- .TP 1i
- \ \ \ \ Synonyms
- Many commands have synonyms, which you may find easier to
- remember (or type) than the principal name.
- .PP
- .TP
- \fBadd\fP [\fB\-k\fP \fIkflag\fP] [\fB\-m '\fP\fImessage\fP\fB'\fP] \fIfiles.\|.\|.\fP
- .I Requires:
- repository, working directory.
- .br
- .I Changes:
- working directory.
- .br
- .I Synonym:
- .B new
- .br
- Use the
- .B add
- command to create a new file or directory in the
- source repository.
- The files or directories specified with
- .B add
- must already exist in the current directory (which must have been created
- with the
- .B checkout
- command).
- To add a whole new directory hierarchy to the source repository
- (for example, files received from a third-party vendor), use the
- .` "cvs import"
- command instead.
- .SP
- If the argument to
- .` "cvs add"
- refers to an immediate sub-directory, the directory is
- created at the correct place in the
- source repository, and the necessary
- .B cvs
- administration files are created in your working directory.
- If the directory already exists in the source repository,
- .` "cvs add"
- still creates the administration files in your version of the directory.
- This allows you to use
- .` "cvs add"
- to add a particular directory to your private sources even if
- someone else created that directory after your
- .B checkout
- of the sources. You can do the following:
- .SP
- .in +1i
- .ft B
- .nf
- example% mkdir new_directory
- example% cvs add new_directory
- example% cvs update new_directory
- .fi
- .ft P
- .in -1i
- .SP
- An alternate approach using
- .` "cvs update"
- might be:
- .SP
- .in +1i
- .ft B
- .nf
- example% cvs update -d new_directory
- .fi
- .ft P
- .in -1i
- .SP
- (To add \fIany available\fP new directories to your working directory, it's
- probably simpler to use
- .` "cvs checkout"
- or
- .` "cvs update -d".)
- .SP
- The added files are not placed in the
- source repository until you use
- .` "cvs commit"
- to make the change permanent.
- Doing a
- .` "cvs add"
- on a file that was removed with the
- .` "cvs remove"
- command will resurrect the file, if no
- .` "cvs commit"
- command intervened.
- .SP
- You will have the opportunity to specify a logging message, as usual,
- when you use
- .` "cvs commit"
- to make the new file permanent. If you'd like to have another
- logging message associated with just
- .I creation
- of the file (for example, to describe the file's purpose), you can
- specify it with the
- .` "\-m \fImessage\fP"
- option to the
- .B add
- command.
- .SP
- The
- .` "-k kflag"
- option specifies the default way that this
- file will be checked out.
- The
- .` "kflag"
- argument is stored in the
- .SM RCS
- file and can be changed with
- .` "cvs admin".
- Specifying
- .` "-ko"
- is useful for checking in binaries that
- shouldn't have
- keywords expanded.
- .TP
- \fBadmin\fP [\fIrcs-options\fP] \fIfiles.\|.\|.\fP
- .I Requires:
- repository, working directory.
- .br
- .I Changes:
- repository.
- .br
- .I Synonym:
- .B rcs
- .br
- This is the
- .B cvs
- interface to assorted administrative
- facilities, similar to
- .BR rcs ( 1 ).
- This command works recursively, so extreme care should be
- used.
- .TP
- \fBcheckout\fP [\fBoptions\fP] \fImodules\fP.\|.\|.
- .I Requires:
- repository.
- .br
- .I Changes:
- working directory.
- .br
- .I Synonyms:
- .BR co ", " get
- .br
- Make a working directory containing copies of the source files specified by
- .IR modules .
- You must execute
- .` "cvs checkout"
- before using most of the other
- .B cvs
- commands, since most of them operate on your working directory.
- .SP
- \fImodules\fP are either symbolic names (themselves defined as the
- module
- .` "modules"
- in the source repository; see
- .BR cvs ( 5 ))
- for some collection of source directories and files, or paths to
- directories or files in the repository.
- .SP
- Depending on the
- .I modules
- you specify,
- .B checkout
- may recursively create directories and populate them with the appropriate
- source files.
- You can then edit these source files at any time (regardless of whether
- other software developers are editing their own copies of the sources);
- update them to include new changes applied by others to the source
- repository; or commit your work as a permanent change to the
- repository.
- .SP
- Note that
- .B checkout
- is used to create directories.
- The top-level directory created is always added to the directory
- where
- .B checkout
- is invoked, and usually has the same name as the specified
- .IR module .
- In the case of a
- .I module
- alias, the created sub-directory may have a different name, but you can be
- sure that it will be a sub-directory, and that
- .B checkout
- will show the relative path leading to each file as it is extracted into
- your private work area (unless you specify the
- .B \-Q
- global option).
- .SP
- Running
- .` "cvs checkout"
- on a directory that was already built by a prior
- .B checkout
- is also permitted, and
- has the same effect as specifying the
- .B \-d
- option to the
- .B update
- command described below.
- .SP
- The
- .I options
- permitted with
- .` "cvs checkout"
- include the standard command options
- .BR \-P ", " \-f ", "
- .BI \-k " kflag"
- \&,
- .BR \-l ", " \-n ", " \-p ", "
- .BR \-r
- .IR tag ", and"
- .BI \-D " date"\c
- \&.
- .SP
- In addition to those, you can use these special command options
- with
- .BR checkout :
- .SP
- Use the
- .B \-A
- option to reset any sticky tags, dates, or
- .B \-k
- options. (If you get a working file using one of the
- \fB\-r\fP, \fB\-D\fP, or \fB\-k\fP options, \fBcvs\fP remembers the
- corresponding tag, date, or \fIkflag\fP and continues using it on
- future updates; use the \fB\-A\fP option to make \fBcvs\fP forget these
- specifications, and retrieve the ``head'' version of the file).
- Does not reset sticky
- .B \-k
- options on modified files.
- .SP
- The
- .BI \-j " branch"
- option merges the changes made between the
- resulting revision and the revision that it is based on (e.g., if
- the tag refers to a branch,
- .B cvs
- will merge all changes made in that branch into your working file).
- .SP
- With two \fB-j\fP options,
- .B cvs
- will merge in the changes between the two respective revisions.
- This can be used to ``remove'' a certain delta from your working file.
- .SP
- In addition, each \fB-j\fP option can contain on optional date
- specification which, when used with branches, can limit the chosen
- revision to one within a specific date.
- An optional date is specified by adding a colon (:) to the tag.
- An example might be what
- .` "cvs import"
- tells you to do when you have
- just imported sources that have conflicts with local changes:
- .SP
- .in +1i
- .ft B
- .nf
- example% cvs checkout -jTAG:yesterday -jTAG module
- .fi
- .ft P
- .in -1i
- .SP
- Use the
- .B \-N
- option with
- .` "\-d \fIdir\fP"
- to avoid shortening module paths in your working directory. (Normally, \fBcvs\fP shortens paths as much as possible when you specify an explicit target directory.)
- .SP
- Use the
- .B \-c
- option to copy the module file, sorted, to the standard output,
- instead of creating or modifying any files or directories in your
- working directory.
- .SP
- Use the
- .BI \-d " dir"
- option to create a directory called
- .I dir
- for the working files, instead of using the module name. Unless you
- also use \fB\-N\fP, the paths created under \fIdir\fP will be as short
- as possible.
- .SP
- Use the
- .B \-s
- option to display per-module status information stored with
- the
- .B \-s
- option within the modules file.
- .TP
- \fBcommit\fP [\fB\-lR\fP] [\fB\-m\fP '\fIlog_message\fP' | \fB\-F\fP \fIfile\fP] [\fB\-r\fP \fIrevision\fP] [\fIfiles.\|.\|.\fP]
- .I Requires:
- working directory, repository.
- .br
- .I Changes:
- repository.
- .br
- .I Synonym:
- .B ci
- .br
- Use
- .` "cvs commit"
- when you want to incorporate changes from your working source
- files into the general source repository.
- .SP
- If you don't specify particular \fIfiles\fP to commit, all
- of the files in your working current directory are examined.
- .B commit
- is careful to change in the repository only those files that you have
- really changed. By default (or if you explicitly specify the
- .B \-R
- option), files
- in subdirectories are also examined and committed if they have
- changed; you can use the
- .B \-l
- option to limit
- .B commit
- to the current directory only.
- Sometimes you may want to force a file to be committed even though it
- is unchanged; this is achieved with the
- .B \-f
- flag, which also has the effect of disabling recursion (you can turn
- it back on with
- .B \-R
- of course).
- .SP
- .B commit
- verifies that the selected files are up to date with the current revisions
- in the source repository; it will notify you, and exit without
- committing, if any of the specified files must be made current first
- with
- .` "cvs update".
- .B commit
- does not call the
- .B update
- command for you, but rather leaves that for you to do when
- the time is right.
- .SP
- When all is well, an editor is invoked to allow you to enter a log
- message that will be written to one or more logging programs and placed in the
- source repository file.
- You can instead specify the log message on the command line with the
- .B \-m
- option, thus suppressing the editor invocation, or use the
- .B \-F
- option to specify that the argument \fIfile\fP contains the log message.
- .SP
- The
- .B \-r
- option can be used to commit to a particular symbolic or numeric revision.
- For example, to bring all your files up to the
- revision ``3.0'' (including those that haven't changed), you might do:
- .SP
- .in +1i
- .ft B
- .nf
- example% cvs commit -r3.0
- .fi
- .ft P
- .in -1i
- .SP
- .B cvs
- will only allow you to commit to a revision that is on the main trunk (a
- revision with a single dot).
- However, you can also commit to a branch revision (one that has an even
- number of dots) with the
- .B \-r
- option.
- To create a branch revision, one typically use the
- .B \-b
- option of the
- .BR rtag " or " tag
- commands.
- Then, either
- .BR checkout " or " update
- can be used to base your sources on the newly created branch.
- From that point on, all
- .B commit
- changes made within these working sources will be automatically added
- to a branch revision, thereby not perturbing main-line development in any
- way.
- For example, if you had to create a patch to the 1.2 version of the
- product, even though the 2.0 version is already under development, you
- might do:
- .SP
- .in +1i
- .ft B
- .nf
- example% cvs rtag -b -rFCS1_2 FCS1_2_Patch product_module
- example% cvs checkout -rFCS1_2_Patch product_module
- example% cd product_module
- [[ hack away ]]
- example% cvs commit
- .fi
- .ft P
- .in -1i
- .SP
- Say you have been working on some extremely experimental software, based on
- whatever revision you happened to checkout last week.
- If others in your group would like to work on this software with you, but
- without disturbing main-line development, you could commit your change to a
- new branch.
- Others can then checkout your experimental stuff and utilize the full
- benefit of
- .B cvs
- conflict resolution.
- The scenario might look like:
- .SP
- .in +1i
- .ft B
- .nf
- example% cvs tag -b EXPR1
- example% cvs update -rEXPR1
- [[ hack away ]]
- example% cvs commit
- .fi
- .ft P
- .in -1i
- .SP
- Others would simply do
- .` "cvs checkout -rEXPR1 whatever_module"
- to work with you on the experimental change.
- .TP
- \fBdiff\fP [\fB\-kl\fP] [\fIformat_options\fP] [[\fB\-r\fP \fIrev1\fP | \fB\-D\fP \fIdate1\fP | \fB\-j\fP \fIrev1:date1\fP] [\fB\-r\fP \fIrev2\fP | \fB\-D\fP \fIdate2\fP | \fB\-j\fP \fIrev2:date2\fP]] [\fIfiles.\|.\|.\fP]
- .I Requires:
- working directory, repository.
- .br
- .I Changes:
- nothing.
- .br
- You can compare your working files with revisions in the source
- repository, with the
- .` "cvs diff"
- command. If you don't specify a particular revision, your files
- are compared with the revisions they were based on. You can also use
- the standard
- .B cvs
- command option
- .B \-r
- to specify a particular revision to compare your files with. Finally,
- if you use
- .B \-r
- twice, you can see differences between two revisions in the
- repository.
- You can also specify
- .B \-D
- options to diff against a revision (on the head branch) in the past, and
- you can also specify
- .B \-j
- options to diff against a revision relative to a branch tag in the past.
- The
- .B \-r
- and
- .B \-D
- and
- .B \-j
- options can be mixed together with at most two options ever specified.
- .SP
- See
- .` "cvs --help diff"
- for a list of supported
- .IR format_options .
- .SP
- If you don't specify any files,
- .B diff
- will display differences for all those files in the current directory
- (and its subdirectories, unless you use the standard option
- .BR \-l )
- that
- differ from the corresponding revision in the source repository
- (i.e. files that
- .I you
- have changed), or that differ from the revision specified.
- .TP
- \fBexport\fP [\-\fBf\|lNnQq\fP] \fB\-r\fP \fIrev\fP\||\|\fB\-D\fP \fIdate\fP [\fB\-d\fP \fIdir\fP] [\fB\-k\fP \fIkflag\fP] \fImodule\fP.\|.\|.
- .I Requires:
- repository.
- .br
- .I Changes:
- current directory.
- .br
- This command is a variant of
- .` "cvs checkout";
- use it when you want a copy of the source for \fImodule\fP
- without the \fBcvs\fP administrative directories. For example, you
- might use
- .` "cvs export"
- to prepare source for shipment
- off-site. This command \fIrequires\fP that you specify a date or tag
- (with \fB\-D\fP or \fB\-r\fP), so that you can count on reproducing
- the source you ship to others.
- .SP
- The only non-standard options are
- .` "\-d \fIdir\fP"
- (write the
- source into directory \fIdir\fP) and
- .` "\-N"
- (don't shorten
- module paths).
- These have the same meanings as the same options in
- .` "cvs checkout".
- .SP
- The
- .B \-kv
- option is useful when
- .B export
- is used.
- This causes any
- keywords to be expanded such that an
- .B import
- done at some other site will not lose the keyword revision information.
- Other \fIkflag\fPs may be used with
- .` "cvs export"
- and are described in
- .BR co ( 1 ).
- .TP
- \fBhistory\fP [\fB\-\fP\fIreport\fP] [\fB\-\fP\fIflags\fP] [\fB\-\fP\fIoptions args\fP] [\fIfiles\fP.\|.\|.]
- .I Requires:
- the file
- .` "$CVSROOT/CVSROOT/history"
- .br
- .I Changes:
- nothing.
- .br
- \fBcvs\fP keeps a history file that tracks each use of the
- \fBcheckout\fP, \fBcommit\fP, \fBrtag\fP, \fBupdate\fP, and \fBrelease\fP
- commands. You can use
- .` "cvs history"
- to display this
- information in various formats.
- .SP
- .I Warning:
- .` "cvs history"
- uses
- .` "\-f",
- .` "\-l",
- .` "\-n",
- and
- .` "\-p"
- in ways that conflict with the
- descriptions in
- .SM
- COMMON COMMAND OPTIONS\c
- \&.
- .SP
- Several options (shown above as \fB\-\fP\fIreport\fP) control what
- kind of report is generated:
- .TP 1i
- .B \ \ \ \ \ \ \-c
- Report on each time \fBcommit\fP was used (i.e., each time the
- repository was modified).
- .TP 1i
- \fB\ \ \ \ \ \ \-m\fP \fImodule\fP
- Report on a particular \fImodule\fP. (You can meaningfully use
- \fB\-m\fP more than once on the command line.)
- .TP 1i
- .B \ \ \ \ \ \ \-o
- Report on checked-out modules.
- .TP 1i
- .B \ \ \ \ \ \ \-T
- Report on all tags.
- .TP 1i
- \fB\ \ \ \ \ \ \-x\fP \fItype\fP
- Extract a particular set of record types \fIX\fP from the \fBcvs\fP
- history. The types are indicated by single letters, which you may
- specify in combination.
- Certain commands have a single record type: \fBcheckout\fP (type `O'),
- \fBrelease\fP (type `F'), and \fBrtag\fP (type `T'). One of four
- record types may result from an \fBupdate\fP: `W', when the working copy
- of a file is deleted during update (because it was gone from the
- repository); `U', when a working file was copied from the
- repository; `G', when a merge was necessary and it succeeded; and 'C',
- when a merge was necessary but collisions were detected (requiring
- manual merging). Finally, one of three record types results from
- \fBcommit\fP: `M', when a file was modified; `A', when a file is first
- added; and `R', when a file is removed.
- .TP 1i
- .B \ \ \ \ \ \ \-e
- Everything (all record types); equivalent to specifying
- .` "\-xMACFROGWUT".
- .TP 1i
- \fB\ \ \ \ \ \ \-z\fP \fIzone\fP
- Use time zone
- .I zone
- when outputting history records.
- The zone name
- .B LT
- stands for local time;
- numeric offsets stand for hours and minutes ahead of UTC.
- For example,
- .B +0530
- stands for 5 hours and 30 minutes ahead of (i.e. east of) UTC.
- .PP
- .RS .5i
- The options shown as \fB\-\fP\fIflags\fP constrain the report without
- requiring option arguments:
- .RE
- .TP 1i
- .B \ \ \ \ \ \ \-a
- Show data for all users (the default is to show data only for the user
- executing
- .` "cvs history").
- .TP 1i
- .B \ \ \ \ \ \ \-l
- Show last modification only.
- .TP 1i
- .B \ \ \ \ \ \ \-w
- Show only the records for modifications done from the same working
- directory where
- .` "cvs history"
- is executing.
- .PP
- .RS .5i
- The options shown as \fB\-\fP\fIoptions args\fP constrain the report
- based on an argument:
- .RE
- .TP 1i
- \fB\ \ \ \ \ \ \-b\fP \fIstr\fP
- Show data back to a record containing the string \fIstr\fP in either
- the module name, the file name, or the repository path.
- .TP 1i
- \fB\ \ \ \ \ \ \-D\fP \fIdate\fP
- Show data since \fIdate\fP.
- .TP 1i
- \fB\ \ \ \ \ \ \-p\fP \fIrepository\fP
- Show data for a particular source repository (you can specify several
- \fB\-p\fP options on the same command line).
- .TP 1i
- \fB\ \ \ \ \ \ \-r\fP \fIrev\fP
- Show records referring to revisions since the revision or tag
- named \fIrev\fP appears in individual RCS files.
- Each
- .SM RCS
- file is searched for the revision or tag.
- .TP 1i
- \fB\ \ \ \ \ \ \-t\fP \fItag\fP
- Show records since tag \fItag\fP was last added to the history file.
- This differs from the \fB-r\fP flag above in that it reads
- only the history file, not the
- .SM RCS
- files, and is much faster.
- .TP 1i
- \fB\ \ \ \ \ \ \-u\fP \fIname\fP
- Show records for user \fIname\fP.
- .PP
- .TP
- \fBimport\fP [\fB\-\fP\fIoptions\fP] \fIrepository vendortag releasetag\fP.\|.\|.
- .I Requires:
- Repository, source distribution directory.
- .br
- .I Changes:
- repository.
- .br
- Use
- .` "cvs import"
- to incorporate an entire source
- distribution from an outside source (e.g., a source vendor) into your
- source repository directory. You can use this command both for
- initial creation of a repository, and for wholesale updates to the
- module form the outside source.
- .SP
- The \fIrepository\fP argument gives a directory name (or a path to a
- directory) under the CVS root directory for repositories; if the
- directory did not exist, \fBimport\fP creates it.
- .SP
- When you use \fBimport\fP for updates to source that has been modified in your
- source repository (since a prior \fBimport\fP), it
- will notify you of any files that conflict in the two branches of
- development; use
- .` "cvs checkout -j"
- to reconcile the differences, as \fBimport\fP instructs you to do.
- .SP
- By default, certain file names are ignored during
- .` "cvs import":
- names associated with
- .SM CVS
- administration, or with other common source control systems; common
- names for patch files, object files, archive files, and editor backup
- files; and other names that are usually artifacts of assorted utilities.
- For an up to date list of ignored file names, see the Cederqvist manual (as
- described in the SEE ALSO section of this manpage).
- .SP
- The outside source is saved in a first-level
- branch, by default
- .` "1.1.1".
- Updates are leaves of this
- branch; for example, files from the first imported collection of
- source will be revision
- .` "1.1.1.1",
- then files from the first
- imported update will be revision
- .` "1.1.1.2",
- and so on.
- .SP
- At least three arguments are required. \fIrepository\fP is needed to
- identify the collection of source. \fIvendortag\fP is a tag for the
- entire branch (e.g., for
- .` "1.1.1").
- You must also specify at
- least one \fIreleasetag\fR to uniquely identify the files at
- the leaves created each time you execute
- .` "cvs import".
- The
- \fIreleasetag\fR should be new, not previously existing in the
- repository file, and uniquely identify the imported release.
- .SP
- One of the standard
- .B cvs
- command options is available: \fB\-m\fP
- \fImessage\fP. If you do not specify a logging message with
- \fB\-m\fP, your editor is invoked (as with \fBcommit\fP) to allow you
- to enter one.
- .SP
- There are three additional special options.
- .SP
- Use
- .` "\-d"
- to specify that each file's time of last modification should be used
- for the checkin date and time.
- .SP
- Use
- .` "\-b \fIbranch\fP"
- to specify a first-level branch other
- than
- .` "1.1.1".
- .SP
- Use
- .` "\-I \fIname\fP"
- to specify file names that should be
- ignored during \fBimport\fP. You can use this option repeatedly.
- To avoid ignoring any files at all (even those ignored by default),
- specify
- .` "\-I !".
- .TP
- \fBlog\fP [\fB\-l\fP] \fIrlog-options [files\fP\|.\|.\|.]
- .I Requires:
- repository, working directory.
- .br
- .I Changes:
- nothing.
- .br
- .I Synonym:
- .B rlog
- .br
- Display log information for \fIfiles\fP.
- Among the more useful options are \fB\-h\fP
- to display only the header (including tag definitions, but omitting
- most of the full log); \fB\-r\fP to select logs on particular
- revisions or ranges of revisions; and \fB\-d\fP to select particular
- dates or date ranges. See
- .BR rlog ( 1 )
- for full explanations.
- This command is recursive by default, unless the
- .B \-l
- option is specified.
- .TP
- \fBrdiff\fP [\fB\-\fP\fIflags\fP] [\fB\-V\fP \fIvn\fP] [\fB\-r\fP \fIt\fP|\fB\-D\fP \fId\fP [\fB\-r\fP \fIt2\fP|\fB\-D\fP \fId2\fP]] \fImodules\|.\|.\|.\fP
- .I Requires:
- repository.
- .br
- .I Changes:
- nothing.
- .br
- .I Synonym:
- .B patch
- .br
- Builds a Larry Wall format
- .BR patch ( 1 )
- file between two releases, that can be fed directly into the
- .B patch
- program to bring an old release up-to-date with the new release.
- (This is one of the few \fBcvs\fP commands that operates directly from
- the repository, and doesn't require a prior
- .BR checkout .)
- The diff output is sent to the standard output device.
- You can specify (using the standard \fB\-r\fP and \fB\-D\fP options)
- any combination of one or two revisions or dates.
- If only one revision or date is specified, the
- patch file reflects differences between that revision or date and the
- current ``head'' revisions in the
- .SM RCS
- file.
- .SP
- Note that if the software release affected
- is contained in more than one directory, then it may be necessary to
- specify the
- .B \-p
- option to the
- .B patch
- command when patching the old sources, so that
- .B patch
- is able to find the files that are located in other directories.
- .SP
- The standard option \fIflags\fP \fB\-f\fP, and \fB\-l\fP
- are available with this command. There are also several
- special option flags:
- .SP
- If you use the
- .B \-s
- option, no patch output is produced.
- Instead, a summary of the changed or added files between the two
- releases is sent to the standard output device.
- This is useful for finding out, for example, which files have changed
- between two dates or revisions.
- .SP
- If you use the
- .B \-t
- option, a diff of the top two revisions is sent to the standard output device.
- This is most useful for seeing what the last change to a file was.
- .SP
- If you use the
- .B \-u
- option, the patch output uses the newer ``unidiff'' format for context
- diffs.
- .SP
- You can use
- .B \-c
- to explicitly specify the
- .` "diff \-c"
- form of context diffs
- (which is the default), if you like.
- .TP
- \fBrelease\fP [\fB\-dQq\fP] \fImodules\fP\|.\|.\|.
- .I Requires:
- Working directory.
- .br
- .I Changes:
- Working directory, history log.
- .br
- This command is meant to safely cancel the effect of
- .` "cvs checkout".
- Since
- .B cvs
- doesn't lock files, it isn't strictly necessary to use this command.
- You can always simply delete your working directory, if you
- like; but you risk losing changes you may have forgotten, and you
- leave no trace in the
- .B cvs
- history file that you've abandoned your checkout.
- .SP
- Use
- .` "cvs release"
- to avoid these problems. This command
- checks that no un-committed changes are present; that you are
- executing it from immediately above, or inside, a \fBcvs\fP working
- directory; and that the repository recorded for your files is the same
- as the repository defined in the module database.
- .SP
- If all these conditions are true,
- .` "cvs release"
- leaves a
- record of its execution (attesting to your intentionally abandoning
- your checkout) in the
- .B cvs
- history log.
- .SP
- You can use the \fB\-d\fP flag to request that your working copies of
- the source files be deleted if the \fBrelease\fP succeeds.
- .TP
- \fBremove\fP [\fB\-lR\fP] [\fIfiles\|.\|.\|.\fP]
- .I Requires:
- Working directory.
- .br
- .I Changes:
- Working directory.
- .br
- .I Synonyms:
- .BR rm ", " delete
- .br
- Use this command to declare that you wish to remove \fIfiles\fP from
- the source repository. Like most
- .B cvs
- commands,
- .` "cvs remove"
- works on files in your working
- directory, not directly on the repository. As a safeguard, it also
- requires that you first erase the specified files from your working
- directory.
- .SP
- The files are not actually removed until you apply your changes to the
- repository with
- .BR commit ;
- at that point, the corresponding
- .SM RCS
- files in the source repository are
- .I moved
- into the
- .` "Attic"
- directory (also within the source repository).
- .SP
- This command is recursive by default, scheduling all physically removed
- files that it finds for removal by the next
- .BR commit .
- Use the
- .B \-l
- option to avoid this recursion, or just specify that actual files that you
- wish remove to consider.
- .TP
- \fBrtag\fP [\fB\-f\|alnRQq\fP] [\fB\-b\fP] [\fB\-d\fP] [\fB\-r\fP \fItag\fP | \fB\-D\fP \fIdate\fP] \fIsymbolic_tag\fP \fImodules\|.\|.\|.\fP
- .I Requires:
- repository.
- .br
- .I Changes:
- repository.
- .br
- .I Synonym:
- .B rfreeze
- .br
- You can use this command to assign symbolic tags to particular,
- explicitly specified source versions in the repository.
- .` "cvs rtag"
- works directly on the repository contents (and requires no
- prior
- .BR checkout ).
- Use
- .` "cvs tag"
- instead, to base the selection of
- versions to tag on the contents of your working directory.
- .SP
- In general, tags (often the symbolic names of software distributions)
- should not be removed, but the
- .B \-d
- option is available as a means to remove completely obsolete symbolic names
- if necessary (as might be the case for an Alpha release, say).
- .SP
- .` "cvs rtag"
- will not move a tag that already exists. With the \fB\-F\fP option,
- however,
- .` "cvs rtag"
- will re-locate any instance of \fIsymbolic_tag\fP that already exists
- on that file to the new repository versions. Without the \fB\-F\fP
- option, attempting to use
- .` "cvs rtag"
- to apply a tag that already exists on that file will produce an error
- message.
- .SP
- The \fB-b\fP option makes the tag a ``branch'' tag, allowing
- concurrent, isolated development.
- This is most useful for creating a patch to a previously released software
- distribution.
- .SP
- You can use the standard \fB\-r\fP and \fB\-D\fP options to tag only those
- files that already contain a certain tag. This method would be used
- to rename a tag: tag only the files identified by the old tag, then delete the
- old tag, leaving the new tag on exactly the same files as the old tag.
- .SP
- .B rtag
- executes recursively by default, tagging all subdirectories of
- \fImodules\fP you specify in the argument. You can restrict its
- operation to top-level directories with the standard \fB\-l\fP option;
- or you can explicitly request recursion with \fB\-R\fP.
- .SP
- The modules database can specify a program to execute whenever a tag
- is specified; a typical use is to send electronic mail to a group of
- interested parties. If you want to bypass that program, use the
- standard \fB\-n\fP option.
- .SP
- Use the
- .B \-a
- option to have
- .B rtag
- look in the
- .` "Attic"
- for removed files that contain the specified tag.
- The tag is removed from these files, which makes it convenient to re-use a
- symbolic tag as development continues (and files get removed from the
- up-coming distribution).
- .TP
- \fBstatus\fP [\fB\-lRqQ\fP] [\fB\-v\fP] [\fIfiles\fP\|.\|.\|.]
- .I Requires:
- working directory, repository.
- .br
- .I Changes:
- nothing.
- .br
- Display a brief report on the current status of \fIfiles\fP with
- respect to the source repository, including any ``sticky'' tags,
- dates, or \fB\-k\fP options. (``Sticky'' options will restrict how
- .` "cvs update"
- operates until you reset them; see the
- description of
- .` "cvs update \-A\|.\|.\|.".)
- .SP
- You can also use this command to anticipate the potential impact of a
- .` "cvs update"
- on your working source directory. If you do
- not specify any \fIfiles\fP explicitly, reports are shown for all
- files that \fBcvs\fP has placed in your working directory. You can
- limit the scope of this search to the current directory itself (not
- its subdirectories) with the standard \fB\-l\fP option flag; or you
- can explicitly request recursive status reports with the \fB\-R\fP
- option.
- .SP
- The
- .B \-v
- option causes the symbolic tags for the
- .SM RCS
- file to be displayed as well.
- .TP
- \fBtag\fP [\fB\-lQqR\fP] [\fB\-F\fP] [\fB\-b\fP] [\fB\-d\fP] [\fB\-r\fP \fItag\fP | \fB\-D\fP \fIdate\fP] [\fB\-f\fP] \fIsymbolic_tag\fP [\fIfiles\fP\|.\|.\|.\|]
- .I Requires:
- working directory, repository.
- .br
- .I Changes:
- repository.
- .br
- .I Synonym:
- .B freeze
- .br
- Use this command to assign symbolic tags to the nearest repository
- versions to your working sources. The tags are applied immediately to
- the repository, as with \fBrtag\fP.
- .SP
- One potentially surprising aspect of the fact that \fBcvs tag\fP
- operates on the repository is that you are tagging the checked-in
- revisions, which may differ from locally modified files in your working
- directory. If you want to avoid doing this by mistake, specify the
- \fB-c\fP option to \fBcvs tag\fP. If there are any locally modified files, CVS
- will abort with an error before it tags any files.
- .SP
- One use for tags is to record a ``snapshot'' of the current sources
- when the software freeze date of a project arrives. As bugs are fixed
- after the freeze date, only those changed sources that are to be part
- of the release need be re-tagged.
- .SP
- The symbolic tags are meant to permanently record which revisions of which
- files were used in creating a software distribution.
- The
- .BR checkout ,
- .B export
- and
- .B update
- commands allow you to extract an exact copy of a tagged release at any time in
- the future, regardless of whether files have been changed, added, or removed
- since the release was tagged.
- .SP
- You can use the standard \fB\-r\fP and \fB\-D\fP options to tag only those
- files that already contain a certain tag. This method would be used
- to rename a tag: tag only the files identified by the old tag, then delete the
- old tag, leaving the new tag on exactly the same files as the old tag.
- .SP
- Specifying the \fB\-f\fP flag in addition to the \fB\-r\fP or \fB\-D\fP
- flags will tag those files named on the command line even if they do not
- contain the old tag or did not exist on the specified date.
- .SP
- By default (without a \fB\-r\fP or \fB\-D\fP flag)
- the versions to be tagged are supplied
- implicitly by the \fBcvs\fP records of your working files' history
- rather than applied explicitly.
- .SP
- If you use
- .` "cvs tag \-d \fIsymbolic_tag\fP\|.\|.\|.",
- the
- symbolic tag you specify is
- .I deleted
- instead of being added. \fIWarning\fP: Be very certain of your ground
- before you delete a tag; doing this effectively discards some
- historical information, which may later turn out to have been valuable.
- .SP
- .` "cvs tag"
- will not move a tag that already exists. With the \fB\-F\fP option,
- however,
- .` "cvs tag"
- will re-locate any instance of \fIsymbolic_tag\fP that already exists
- on that file to the new repository versions. Without the \fB\-F\fP
- option, attempting to use
- .` "cvs tag"
- to apply a tag that already exists on that file will produce an error
- message.
- .SP
- The \fB-b\fP option makes the tag a ``branch'' tag, allowing
- concurrent, isolated development.
- This is most useful for creating a patch to a previously released software
- distribution.
- .SP
- Normally,
- .B tag
- executes recursively through subdirectories; you can prevent this by
- using the standard \fB\-l\fP option, or specify the recursion
- explicitly by using \fB\-R\fP.
- .TP
- \fBupdate\fP [\fB\-ACdf\|lPpQqR\fP] [\fB\-d\fP] [\fB\-r\fP \fItag\fP|\fB\-D\fP \fIdate\fP] \fIfiles\|.\|.\|.\fP
- .I Requires:
- repository, working directory.
- .br
- .I Changes:
- working directory.
- .br
- After you've run
- .B checkout
- to create your private copy of source from the common repository,
- other developers will continue changing the central source. From time
- to time, when it is convenient in your development process, you can
- use the
- .B update
- command
- from within your working directory to reconcile your work with any
- revisions applied to the source repository since your last
- .B checkout
- or
- .BR update .
- .SP
- .B update
- keeps you informed of its progress by printing a line for each file,
- prefaced with one of the characters
- .` "U P A R M C ?"
- to indicate the status of the file:
- .TP 1i
- \fBU\fP \fIfile\fP
- The file was brought \fIup to date\fP with respect to the repository.
- This is done for any file that exists in the repository but not in your
- working directory, and for files that you haven't changed but are not the most
- recent versions available in the repository.
- .TP 1i
- \fBP\fP \fIfile\fP
- Like \fBU\fP, but the CVS server sends a patch instead of an entire file.
- This accomplishes the same thing as \fBU\fP using less bandwidth.
- .TP 1i
- \fBA\fP \fIfile\fP
- The file has been \fIadded\fP to your private copy of the sources, and
- will be added to the
- source repository when you run
- .` "cvs commit"
- on the file.
- This is a reminder to you that the file needs to be committed.
- .TP 1i
- \fBR\fP \fIfile\fP
- The file has been \fIremoved\fP from your private copy of the sources, and
- will be removed from the
- source repository when you run
- .` "cvs commit"
- on the file.
- This is a reminder to you that the file needs to be committed.
- .TP 1i
- \fBM\fP \fIfile\fP
- The file is \fImodified\fP in your working directory.
- .` "M"
- can indicate one of two states for a file you're working on: either
- there were no modifications to the same file in the repository, so
- that your file remains as you last saw it; or there were modifications
- in the repository as well as in your copy, but they were
- \fImerged\fP successfully, without conflict, in your working
- directory.
- .TP 1i
- \fBC\fP \fIfile\fP
- A \fIconflict\fP was detected while trying to merge your changes to
- \fIfile\fP with changes from the source repository. \fIfile\fP (the
- copy in your working directory) is now the result of merging
- the two versions; an unmodified copy of your file is also
- in your working directory, with the name `\fB.#\fP\fIfile\fP\fB.\fP\fIversion\fP',
- where
- .I version
- is the
- revision that your modified file started from.
- (Note that some systems automatically purge files that begin with
- \&
- .` ".#"
- if they have not been accessed for a few days.
- If you intend to keep a copy of your original file, it is a very good
- idea to rename it.)
- .TP 1i
- \fB?\fP \fIfile\fP
- \fIfile\fP is in your working directory, but does not correspond to
- anything in the source repository, and is not in the list of files
- for \fBcvs\fP to ignore (see the description of the \fB\-I\fP option).
- .PP
- .RS .5i
- .SP
- Use the
- .B \-A
- option to reset any sticky tags, dates, or
- .B \-k
- options. (If you get a working copy of a file by using one of the
- \fB\-r\fP, \fB\-D\fP, or \fB\-k\fP options, \fBcvs\fP remembers the
- corresponding tag, date, or \fIkflag\fP and continues using it on
- future updates; use the \fB\-A\fP option to make \fBcvs\fP forget these
- specifications, and retrieve the ``head'' version of the file).
- .SP
- The \fB\-j\fP\fIbranch\fP option
- merges the changes made between the
- resulting revision and the revision that it is based on (e.g., if
- the tag refers to a branch,
- .B cvs
- will merge all changes made in
- that branch into your working file).
- .SP
- With two \fB-j\fP options,
- .B cvs
- will merge in the changes between the two respective revisions.
- This can be used to ``remove'' a certain delta from your working file.
- E.g., If the file foo.c is based on
- revision 1.6 and I want to remove the changes made between 1.3 and
- 1.5, I might do:
- .SP
- .in +1i
- .ft B
- .nf
- example% cvs update -j1.5 -j1.3 foo.c # note the order...
- .fi
- .ft P
- .in -1i
- .SP
- In addition, each \fB-j\fP option can contain on optional date
- specification which, when used with branches, can limit the chosen
- revision to one within a specific date.
- An optional date is specified by adding a colon (:) to the tag.
- .SP
- .in +1i
- .ft B
- .nf
- -jSymbolic_Tag:Date_Specifier
- .fi
- .ft P
- .in -1i
- .SP
- Use the
- .B \-d
- option to create any directories that exist in the repository if they're
- missing from the working directory. (Normally, update acts only on
- directories and files that were already enrolled in your
- working directory.) This is useful for updating directories
- that were created in the repository since the initial
- \fBcheckout\fP; but it has an unfortunate side effect. If you
- deliberately avoided certain directories in the repository when you
- created your working directory (either through use of a module name or by
- listing explicitly the files and directories you wanted on the
- command line), then updating with
- .B \-d
- will create those directories, which may not be what you want.
- .SP
- Use \fB\-I\fP \fIname\fP to ignore files whose names match \fIname\fP
- (in your working directory) during the update. You can specify
- \fB\-I\fP more than once on the command line to specify several files
- to ignore. By default,
- \fBupdate\fP ignores files whose names match certain patterns; for
- an up to date list of ignored file names, see the Cederqvist manual (as
- described in the SEE ALSO section of this manpage).
- .SP
- Use
- .` "\-I !"
- to avoid ignoring any files at all.
- .SP
- Use the
- .` "\-C"
- option to overwrite locally modified files with clean copies from
- the repository (the modified file is saved in
- `\fB.#\fP\fIfile\fP\fB.\fP\fIrevision\fP', however).
- .SP
- The standard \fBcvs\fP command options \fB\-f\fP, \fB\-k\fP,
- \fB\-l\fP, \fB\-P\fP, \fB\-p\fP, and \fB\-r\fP
- are also available with \fBupdate\fP.
- .RE
- .SH "FILES"
- For more detailed information on
- .B cvs
- supporting files, see
- .BR cvs ( 5 ).
- .LP
- .I
- Files in home directories:
- .TP
- \&.cvsrc
- The
- .B cvs
- initialization file. Lines in this file can be used to specify default
- options for each
- .B cvs
- command. For example the line
- .` "diff \-c"
- will ensure that
- .` "cvs diff"
- is always passed the
- .B \-c
- option in addition to any other options passed on the command line.
- .TP
- \&.cvswrappers
- Specifies wrappers to be used in addition to those specified in the
- CVSROOT/cvswrappers file in the repository.
- .LP
- .I
- Files in working directories:
- .TP
- CVS
- A directory of \fBcvs\fP administrative files.
- .I
- Do not delete.
- .TP
- CVS/Entries
- List and status of files in your working directory.
- .TP
- CVS/Entries.Backup
- A backup of
- .` "CVS/Entries".
- .TP
- CVS/Entries.Static
- Flag: do not add more entries on
- .` "cvs update".
- .TP
- CVS/Root
- Pathname to the repository (
- .SM CVSROOT
- ) location at the time of checkout. This file is used instead
- of the
- .SM CVSROOT
- environment variable if the environment variable is not
- set. A warning message will be issued when the contents of this
- file and the
- .SM CVSROOT
- environment variable differ. The file may be over-ridden by the
- presence of the
- .SM CVS_IGNORE_REMOTE_ROOT
- environment variable.
- .TP
- CVS/Repository
- Pathname to the corresponding directory in the source repository.
- .TP
- CVS/Tag
- Contains the per-directory ``sticky'' tag or date information.
- This file is created/updated when you specify
- .B \-r
- or
- .B \-D
- to the
- .B checkout
- or
- .B update
- commands, and no files are specified.
- .TP
- CVS/Checkin.prog
- Name of program to run on
- .` "cvs commit".
- .TP
- CVS/Update.prog
- Name of program to run on
- .` "cvs update".
- .LP
- .I
- Files in source repositories:
- .TP
- $CVSROOT/CVSROOT
- Directory of global administrative files for repository.
- .TP
- CVSROOT/commitinfo,v
- Records programs for filtering
- .` "cvs commit"
- requests.
- .TP
- CVSROOT/cvswrappers,v
- Records
- .B cvs
- wrapper commands to be used when checking files into and out of the
- repository. Wrappers allow the file or directory to be processed
- on the way in and out of CVS. The intended uses are many, one
- possible use would be to reformat a C file before the file is checked
- in, so all of the code in the repository looks the same.
- .TP
- CVSROOT/editinfo,v
- Records programs for editing/validating
- .` "cvs commit"
- log entries.
- .TP
- CVSROOT/history
- Log file of \fBcvs\fP transactions.
- .TP
- CVSROOT/loginfo,v
- Records programs for piping
- .` "cvs commit"
- log entries.
- .TP
- CVSROOT/modules,v
- Definitions for modules in this repository.
- .TP
- CVSROOT/rcsinfo,v
- Records pathnames to templates used during a
- .` "cvs commit"
- operation.
- .TP
- CVSROOT/taginfo,v
- Records programs for validating/logging
- .` "cvs tag"
- and
- .` "cvs rtag"
- operations.
- .TP
- MODULE/Attic
- Directory for removed source files.
- .TP
- #cvs.lock
- A lock directory created by
- .B cvs
- when doing sensitive changes to the
- source repository.
- .TP
- #cvs.tfl.\fIpid\fP
- Temporary lock file for repository.
- .TP
- #cvs.rfl.\fIpid\fP
- A read lock.
- .TP
- #cvs.wfl.\fIpid\fP
- A write lock.
- .SH "ENVIRONMENT"
- .TP
- .SM CVSROOT
- Should contain the full pathname to the root of the
- .B cvs
- source repository (where the
- .SM RCS
- files are kept). This information must be available to \fBcvs\fP for
- most commands to execute; if
- .SM CVSROOT
- is not set, or if you wish to override it for one invocation, you can
- supply it on the command line:
- .` "cvs \-d \fIcvsroot cvs_command\fP\|.\|.\|."
- You may not need to set
- .SM CVSROOT
- if your \fBcvs\fP binary has the right path compiled in.
- .TP
- .SM CVSREAD
- If this is set,
- .B checkout
- and
- .B update
- will try hard to make the files in your working directory read-only.
- When this is not set, the default behavior is to permit modification
- of your working files.
- .TP
- .SM CVSREADONLYFS
- If this is set, the
- .B \-R
- option is assumed, and
- .B cvs
- operates in read-only repository mode.
- .TP
- .SM RCSBIN
- Specifies the full pathname where to find
- .SM RCS
- programs, such as
- .BR co ( 1 )
- and
- .BR ci ( 1 )
- (CVS 1.9 and older).
- .TP
- .SM CVSEDITOR
- Specifies the program to use for recording log messages during
- .BR commit .
- If not set, the
- .SM VISUAL
- and
- .SM EDITOR
- environment variables are tried (in that order).
- If neither is set, a system-dependent default editor (e.g.,
- .BR vi )
- is used.
- .TP
- .SM CVS_CLIENT_PORT
- If this variable is set then
- .B cvs
- will use this port in
- \fIpserver mode\fP
- rather than the default port (cvspserver 2401).
- .TP
- .SM CVS_IGNORE_REMOTE_ROOT
- If this variable is set then
- .B cvs
- will ignore all references to remote repositories in the CVS/Root file.
- .TP
- .SM CVS_OPTIONS
- Specifies a set of default options for
- .B cvs.
- These options are interpreted before the startup file (\fI~/.cvsrc\fP) is read
- and can be overridden by explicit command line parameters.
- .TP
- .SM CVS_RSH
- .B cvs
- uses the contents of this variable to determine the name of the
- remote shell command to use when starting a
- .B cvs
- server. If this variable is not set then
- .` "ssh"
- is used.
- .TP
- .SM CVS_SERVER
- .B cvs
- uses the contents of this variable to determine the name of the
- .B cvs
- server command. If this variable is not set then
- .` "cvs"
- is used.
- .TP
- .SM CVSWRAPPERS
- This variable is used by the
- .` "cvswrappers"
- script to determine the name of the wrapper file, in addition to the
- wrappers defaults contained in the repository
- .SM (CVSROOT/cvswrappers)
- and the user's home directory (~/.cvswrappers).
- .SH "AUTHORS"
- .TP
- Dick Grune
- Original author of the
- .B cvs
- shell script version posted to
- .B comp.sources.unix
- in the volume6 release of December, 1986.
- Credited with much of the
- .B cvs
- conflict resolution algorithms.
- .TP
- Brian Berliner
- Coder and designer of the
- .B cvs
- program itself in April, 1989, based on the original work done by Dick.
- .TP
- Jeff Polk
- Helped Brian with the design of the
- .B cvs
- module and vendor branch support and author of the
- .BR checkin ( 1 )
- shell script (the ancestor of
- .` "cvs import").
- .TP
- And many others too numerous to mention here.
- .SH "SEE ALSO"
- The most comprehensive manual for CVS is
- Version Management with CVS by Per Cederqvist et al. Depending on
- your system, you may be able to get it with the
- .B info cvs
- command or it may be available as cvs.ps (postscript), cvs.texinfo
- (texinfo source), or cvs.html.
- .SP
- For CVS updates, more information on documentation, software related
- to CVS, development of CVS, and more, see:
- .in +1i
- .B http://cvs.nongnu.org
- .in -1i
- .SP
- .BR ci ( 1 ),
- .BR co ( 1 ),
- .BR cvs ( 5 ),
- .BR cvsbug ( 8 ),
- .BR diff ( 1 ),
- .BR grep ( 1 ),
- .BR patch ( 1 ),
- .BR rcs ( 1 ),
- .BR rcsdiff ( 1 ),
- .BR rcsmerge ( 1 ),
- .BR rlog ( 1 ).