CVS--Concurrent Versions System - Reference manual for CVS commands (2024)

Go to the previous, next section.

This appendix describes how to invoke CVS, anddescribes in detail those subcommands of CVS whichare not fully described elsewhere. To look up aparticular subcommand, see section Index.

Overall structure of CVS commands

The overall format of all CVS commands is:

cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ]

cvs: The name of the CVS program.
cvs_options: Some options that affect all sub-commands of CVS. These aredescribed below.
cvs_command: One of several different sub-commands. Some of the commands havealiases that can be used instead; those aliases are noted in thereference manual for that command. There are only two situationswhere you may omit `cvs_command': `cvs -H' elicits alist of available commands, and `cvs -v' displays versioninformation on CVS itself.
command_options: Options that are specific for the command.
command_args: Arguments to the commands.

There is unfortunately some confusion betweencvs_options and command_options.`-l', when given as a cvs_option, onlyaffects some of the commands. When it is given as acommand_option is has a different meaning, andis accepted by more commands. In other words, do nottake the above categorization too seriously. Look atthe documentation instead.

Default options and the ~/.cvsrc file

There are some command_options that are used sooften that you might have set up an alias or some othermeans to make sure you always specify that option. Oneexample (the one that drove the implementation of the.cvsrc support, actually) is that many people find thedefault output of the `diff' command to be veryhard to read, and that either context diffs or unidiffsare much easier to understand.

The `~/.cvsrc' file is a way that you can adddefault options to cvs_commands within cvs,instead of relying on aliases or other shell scripts.

The format of the `~/.cvsrc' file is simple. Thefile is searched for a line that begins with the samename as the cvs_command being executed. If amatch is found, then the remainder of the line is splitup (at whitespace characters) into separate options andadded to the command arguments before anyoptions from the command line.

If a command has two names (e.g., checkout andco), the official name, not necessarily the oneused on the command line, will be used to match againstthe file. So if this is the contents of the user's`~/.cvsrc' file:

log -Ndiff -uupdate -Pco -P

the command `cvs checkout foo' would have the`-P' option added to the arguments, as well as`cvs co foo'.

With the example file above, the output from `cvsdiff foobar' will be in unidiff format. `cvs diff-c foobar' will provide context diffs, as usual.Getting "old" format diffs would be slightly morecomplicated, because diff doesn't have an optionto specify use of the "old" format, so you would need`cvs -f diff foobar'.

In place of the command name you can use cvs tospecify global options (see section Global options). Forexample the following line in `.cvsrc'

cvs -z6

causes CVS to use compression level 6

Global options

The available `cvs_options' (that are given to theleft of `cvs_command') are:

-b bindir: Use bindir as the directory where RCS programs arelocated. Overrides the setting of the $RCSBIN environmentvariable and any precompiled directory. This parameter should bespecified as an absolute pathname.
-d cvs_root_directory: Use cvs_root_directory as the root directorypathname of the repository. Overrides the setting ofthe $CVSROOT environment variable. See section The Repository.
-e editor: Use editor to enter revision log information. Overrides thesetting of the $CVSEDITOR and $EDITOR environment variables.
-f: Do not read the `~/.cvsrc' file. Thisoption is most often used because of thenon-orthogonality of the CVS option set. Forexample, the `cvs log' option `-N' (turn offdisplay of tag names) does not have a correspondingoption to turn the display on. So if you have`-N' in the `~/.cvsrc' entry for `log',you may need to use `-f' to show the tag names.
-H: Display usage information about the specified `cvs_command'(but do not actually execute the command). If you don't specifya command name, `cvs -H' displays a summary of all thecommands available.
-l: Do not log the cvs_command in the command history (but execute itanyway). See section history--Show status of files and users, 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.
-Q: Cause the command to be really quiet; the command will onlygenerate output for serious problems.
-q: Cause the command to be somewhat quiet; informational messages,such as reports of recursion through subdirectories, aresuppressed.
-r: Make new working files files read-only. Same effectas if the $CVSREAD environment variable is set(see section All environment variables which affect CVS). The default is tomake working files writable, unless watches are on(see section Mechanisms to track who is editing files).
-s variable=value: Set a user variable (see section Expansions in administrative files).
-t: Trace program execution; display messages showing the steps ofCVS activity. Particularly useful with `-n' to explore thepotential impact of an unfamiliar command.
-v: Display version and copyright information for CVS.
-w: Make new working files read-write. Overrides thesetting of the $CVSREAD environment variable.Files are created read-write by default, unless $CVSREAD isset or `-r' is given.
-z gzip-level: Set the compression level. Only has an effect on theCVS client.

Common command options

This section describes the `command_options' thatare available across several CVS commands. Theseoptions are always given to the right of`cvs_command'. Not allcommands support all of these options; each option isonly supported for commands where it makes sense.However, when a command has one of these options youcan almost always count on the same behavior of theoption as in other commands. (Other command options,which are listed with the individual commands, may havedifferent behavior from one CVS command to the other).

Warning: the `history' command is an exception; it supportsmany options that conflict even with these standard options.

-D date_spec

Use the most recent revision no later than date_spec.date_spec is a single argument, a date descriptionspecifying a date in the past.

The specification is sticky when you use it to make aprivate copy of a source file; that is, when you get a workingfile using `-D', CVS records the date you specified, so thatfurther updates in the same directory will use the same date(for more information on sticky tags/dates, see section Sticky tags).

A wide variety of date formats are supported by the underlyingRCS facilities, similar to those described in co(1), but notexactly the same. The date_spec is interpreted as beingin the local timezone, unless a specific timezone is specified.Examples of valid date specifications include:

 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

`-D' is available with the checkout,diff, export, history,rdiff, rtag, and update commands.(The history command uses this option in aslightly different way; see section history options).

Remember to quote the argument to the `-D'flag so that your shell doesn't interpret spaces asargument separators. A command using the `-D'flag can look like this:

$ cvs diff -D "1 hour ago" cvs.texinfo

-f

When you specify a particular date or tag to CVS commands, theynormally ignore files that do not contain the tag (or did notexist prior to the date) that you specified. Use the `-f' optionif you want files retrieved even when there is no match for thetag or date. (The most recent revision of the filewill be used).

`-f' is available with these commands: checkout,export, rdiff, rtag, and update.

Warning: The commit command also has a`-f' option, but it has a different behavior forthat command. See section commit options.

-H

Help; describe the options available for this command. This isthe only option supported for all CVS commands.

-k kflag

Alter the default RCS processing of keywords.See section Keyword substitution, for the meaning ofkflag. Your kflag specification issticky when you use it to create a private copyof a source file; that is, when you use this optionwith the checkout or update commands,CVS associates your selected kflag with thefile, and continues to use it with future updatecommands on the same file until you specify otherwise.

The `-k' option is available with the add,checkout, diff andupdate commands.

-l

Local; run only in current working directory, rather thanrecursing through subdirectories.

Warning: this is not the sameas the overall `cvs -l' option, which you can specify to theleft of a cvs command!

Available with the following commands: checkout,commit, diff, export, log,remove, rdiff, rtag,status, tag, and update.

-m message

Use message as log information, instead ofinvoking an editor.

Available with the following commands: add,commit and import.

-n

Do not run any checkout/commit/tag program. (A program can bespecified to run on each of these activities, in the modulesdatabase (see section The modules file); this option bypasses it).

Warning: this is not the same as the overall `cvs -n'option, which you can specify to the left of a cvs command!

Available with the checkout, commit, export,and rtag commands.

-P

Prune (remove) directories that are empty after being updated, oncheckout, 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 silentlyremoved from your checked-out sources. This does not remove thedirectory 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. Availablewith the checkout and update commands.

-W

Specify file names that should be filtered. You canuse this option repeatedly. The spec can be a filename pattern of the same type that you can specify inthe `.cvswrappers' file.Avaliable with the following commands: import,and update.

-r tag

Use the revision specified by the tag argument instead of thedefault head revision. As well as arbitrary tags definedwith the tag or rtag command, two special tags arealways available: `HEAD' refers to the most recent versionavailable in the repository, and `BASE' refers to therevision you last checked out into the current working directory.

The tag specification is sticky when you use this optionwith checkout or update to make your owncopy of a file: CVS remembers the tag and continues to use it onfuture update commands, until you specify otherwise (for more informationon sticky tags/dates, see section Sticky tags). Thetag can be either a symbolic or numeric tag.See section Tags--Symbolic revisions.

Specifying the `-q' global option along with the`-r' command option is often useful, to suppressthe warning messages when the RCS history filedoes not contain the specified tag.

Warning: this is not the same as the overall `cvs -r' option,which you can specify to the left of a cvs command!

`-r' is available with the checkout, commit,diff, history, export, rdiff,rtag, and update commands.

add--Add a new file/directory to the repository

Synopsis: add [-k kflag] [-m 'message'] files...
Requires: repository, working directory.
Changes: working directory.
Synonym: new

Use the add command to create a new file or directory in the source repository. The files or directories specified with addmust already exist in the current directory (which must have beencreated with the checkout command). To add a whole new directoryhierarchy to the source repository (for example, files receivedfrom a third-party vendor), use the import commandinstead. See section import--Import sources into CVS, using vendor branches.

If the argument to add refers to an immediatesub-directory, the directory is created at the correct place inthe source repository, and the necessary CVS administrationfiles are created in your working directory. If the directoryalready exists in the source repository, add still createsthe administration files in your version of the directory.This allows you to use add to add a particular directoryto your private sources even if someone else created thatdirectory after your checkout of the sources. You can do thefollowing:

$ mkdir new_directory$ cvs add new_directory$ cvs update new_directory

An alternate approach using update might be:

$ cvs update -d new_directory

(To add any available new directories to your working directory,it's probably simpler to use checkout (see section checkout--Check out sources for editing)or `update -d' (see section update--Bring work tree in sync with repository)).

The added files are not placed in the source repository until youuse commit to make the change permanent. Doing anadd on a file that was removed with the removecommand will resurrect the file, unless a commit commandintervened.See section Removing files from a module, for an example.

Unlike most other commands add never recurses downdirectories. It cannot yet handle relative paths. Instead of

$ cvs add foo/bar.c

you have to do

$ cd foo$ cvs add bar.c

add options

There are only two options you can give to `add':

-k kflag

This option specifies the default way that this filewill be checked out. The kflag argument(see section Substitution modes) is stored in the RCSfile and can be changed with admin -k(see section admin options). See section Handling binary files, forinformation on using this option for binary files.

-m description

Using this option, you can give a description for the file. Thisdescription appears in the history log (if it is enabled,see section The history file). It will also be saved in the RCS historyfile inside the repository when the file is committed. Thelog 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 beused. You will not be prompted for a description.

add examples

To add the file `backend.c' to the repository, with adescription, the following can be used.

$ cvs add -m "Optimizer and code generation passes." backend.c$ cvs commit -m "Early version. Not yet compilable." backend.c

admin--Administration front end for rcs

Requires: repository, working directory.
Changes: repository.
Synonym: rcs

This is the CVS interface to assorted administrative RCSfacilities, documented in rcs(1). admin simply passesall its options and arguments to the rcs command; it doesno filtering or other processing. This command does workrecursively, however, so extreme care should be used.

If there is a group whose name matches a compiled invalue which defaults to cvsadmin, only membersof that group can use cvs admin. To disallowcvs admin for all users, create a group with nousers in it.

admin options

Not all valid rcs options are useful togetherwith CVS. Some even makes it impossible to useCVS until you undo the effect!

This description of the available options is based onthe `rcs(1)' man page, but modified to suitreaders that are more interrested in CVS thanRCS.

-Aoldfile

Might not work together with CVS. Append theaccess list of oldfile to the access list of theRCS file.

-alogins

Might not work together with CVS. Append thelogin names appearing in the comma-separated listlogins to the access list of the RCS file.

-b[rev]

When used with bare RCS, thisoption sets the default branch to rev; inCVS sticky tags (see section Sticky tags) are a betterway to decide which branch you want to work on. WithCVS, this option can be used to control behaviorwith respect to the vendor branch.

-cstring

Useful with CVS. Sets the comment leader tostring. The comment leader is printed beforeevery log message line generated by the keyword$Log$ (see section Keyword substitution).This is useful for programming languages withoutmulti-line comments. RCS initially guesses thevalue of the comment leader from the file nameextension when the file is first committed.

-e[logins]

Might not work together with CVS. Erase the loginnames appearing in the comma-separated listlogins from the access list of the RCS file. Iflogins is omitted, erase the entire access list.

-I

Run interactively, even if the standard input is not aterminal.

-i

Useless with CVS. When using bare RCS, thisis used to create and initialize a new RCS file,without depositing a revision.

-ksubst

Useful with CVS. Set the default keywordsubstitution to subst. See section Keyword substitution. Giving an explicit `-k' option tocvs update, cvs export, or cvscheckout overrides this default.

-l[rev]

Lock the revision with number rev. If a branchis given, lock the latest revision on that branch. Ifrev is omitted, lock the latest revision on thedefault branch.

This can be used in conjunction with the`rcslock.pl' script in the `contrib'directory of the CVS source distribution toprovide reserved checkouts (where only one user can beediting a given file at a time). See the comments inthat file for details (and see the `README' filein that directory for disclaimers about the unsupportednature of contrib). According to comments in thatfile, locking must set to strict (which is the default).

-L

Set locking to strict. Strict locking means that theowner of an RCS file is not exempt from locking forcheckin. For use with CVS, strict locking must beset; see the discussion under the `-l' option above.

-mrev:msg

Replace the log message of revision rev withmsg.

-Nname[:[rev]]

Act like `-n', except override any previousassignment of name.

-nname[:[rev]]

Associate the symbolic name name with the branchor revision rev. It is normally better to use`cvs tag' or `cvs rtag' instead. Delete thesymbolic name if both `:' and rev areomitted; otherwise, print an error message ifname is already associated with another number.If rev is symbolic, it is expanded beforeassociation. A rev consisting of a branch numberfollowed by a `.' stands for the current latestrevision in the branch. A `:' with an emptyrev stands for the current latest revision on thedefault branch, normally the trunk. For example,`rcs -nname: RCS/*' associates name with thecurrent latest revision of all the named RCS files;this contrasts with `rcs -nname:$ RCS/*' whichassociates name with the revision numbersextracted from keyword strings in the correspondingworking files.

-orange

Potentially useful, but dangerous, with CVS (see below).Deletes (outdates) the revisions given byrange. A range consisting of a single revisionnumber means that revision. A range consisting of abranch number means the latest revision on that branch.A range of the form `rev1:rev2' meansrevisions rev1 to rev2 on the same branch,`:rev' means from the beginning of thebranch containing rev up to and includingrev, and `rev:' means from revisionrev to the end of the branch containingrev. None of the outdated revisions may havebranches or locks.

Due to the way CVS handles branches revcannot be specified symbolically if it is a branch.See section Magic branch numbers, for an explanation.

Make sure that no-one has checked out a copy of therevision you outdate. Strange things will happen if hestarts to edit it and tries to check it back in. Forthis reason, this option is not a good way to take backa bogus commit; commit a new revision undoing the boguschange instead (see section Merging differences between any two revisions).

-q

Run quietly; do not print diagnostics.

-sstate[:rev]

Useful with CVS. Set the state attribute of therevision rev to state. If rev is abranch number, assume the latest revision on thatbranch. If rev is omitted, assume the latestrevision on the default branch. Any identifier isacceptable for state. A useful set of states is`Exp' (for experimental), `Stab' (forstable), and `Rel' (for released). By default,the state of a new revision is set to `Exp' whenit is created. The state is visible in the output fromcvs log (see section log--Print out 'rlog' information for files), and in the`$'Log$ and `$'State$ keywords(see section Keyword substitution). Note that CVSuses the dead state for its own purposes; totake a file to or from the dead state usecommands like cvs remove and cvs add, notcvs admin -s.

-t[file]

Useful with CVS. Write descriptive text from thecontents of the named file into the RCS file,deleting the existing text. The file pathnamemay not begin with `-'. If file is omitted,obtain the text from standard input, terminated byend-of-file or by a line containing `.' by itself.Prompt for the text if interaction is possible; see`-I'. The descriptive text can be seen in theoutput from `cvs log' (see section log--Print out 'rlog' information for files).

-t-string

Similar to `-tfile'. Write descriptive textfrom the string into the RCS file, deletingthe existing text.

-U

Set locking to non-strict. Non-strict locking meansthat the owner of a file need not lock a revision forcheckin. For use with CVS, strict locking must beset; see the discussion under the `-l' optionabove.

-u[rev]

See the option `-l' above, for a discussion ofusing this option with CVS. Unlock the revisionwith number rev. If a branch is given, unlockthe latest revision on that branch. If rev isomitted, remove the latest lock held by the caller.Normally, only the locker of a revision may unlock it.Somebody else unlocking a revision breaks the lock.This causes a mail message to be sent to the originallocker. The message contains a commentary solicitedfrom the breaker. The commentary is terminated byend-of-file or by a line containing . by itself.

-Vn

Emulate RCS version n. Use -Vn to makean RCS file acceptable to RCS version nby discarding information that would confuse versionn.

-xsuffixes

Useless with CVS. Use suffixes tocharacterize RCS files.

admin examples

Outdating is dangerous

First, an example of how not to use theadmin command. It is included to stress thefact that this command can be quite dangerous unlessyou know exactly what you are doing.

The `-o' option can be used to outdate old revisionsfrom the history file. If you are short on disc this optionmight help you. But think twice before using it--there is noway short of restoring the latest backup to undo this command!

The next line is an example of a command that you wouldnot like to execute.

$ cvs admin -o:R_1_02 .

The above command will delete all revisions up to, andincluding, the revision that corresponds to the tagR_1_02. But beware! If there are files that have notchanged between R_1_02 and R_1_03 the file will havethe same numerical revision number assigned tothe tags R_1_02 and R_1_03. So not only will it beimpossible to retrieve R_1_02; R_1_03 will also have tobe restored from the tapes!

Comment leaders

If you use the $Log$ keyword and you donot agree with the guess for comment leader thatCVS has done, you can enforce your will withcvs admin -c. This might be suitable fornroff source:

$ cvs admin -c'.\" ' *.man$ rm *.man$ cvs update

The two last steps are to make sure that you get theversions with correct comment leaders in your workingfiles.

checkout--Check out sources for editing

Synopsis: checkout [options] modules...
Requires: repository.
Changes: working directory.
Synonyms: co, get

Make a working directory containing copies of thesource files specified by modules. You must executecheckout before using most of the other CVScommands, since most of them operate on your workingdirectory.

The modules part of the command are eithersymbolic names for somecollection of source directories and files, or paths todirectories or files in the repository. The symbolicnames are defined in the `modules' file.See section The modules file.

Depending on the modules you specify, checkout mayrecursively create directories and populate them withthe appropriate source files. You can then edit thesesource files at any time (regardless of whether othersoftware developers are editing their own copies of thesources); update them to include new changes applied byothers to the source repository; or commit your work asa permanent change to the source repository.

Note that checkout is used to createdirectories. The top-level directory created is alwaysadded to the directory where checkout isinvoked, and usually has the same name as the specifiedmodule. In the case of a module alias, the createdsub-directory may have a different name, but you can besure that it will be a sub-directory, and thatcheckout will show the relative path leading toeach file as it is extracted into your private workarea (unless you specify the `-Q' global option).

The files created by checkout are createdread-write, unless the `-r' option to CVS(see section Global options) is specified, theCVSREAD environment variable is specified(see section All environment variables which affect CVS), or a watch is ineffect for that file (see section Mechanisms to track who is editing files).

Running checkout on a directory that was alreadybuilt by a prior checkout is also permitted, andhas the same effect as specifying the `-d' optionto the update command, that is, any newdirectories that have been created in the repositorywill appear in your work area. See section update--Bring work tree in sync with repository.

checkout options

These standard options are supported by checkout(see section Common command options, for a complete description ofthem):

-D date: Use the most recent revision no later than date.This option is sticky, and implies `-P'. Seesection Sticky tags, for more information on sticky tags/dates.
-f: Only useful with the `-D date' or `-rtag' flags. If no matching revision is found,retrieve the most recent revision (instead of ignoringthe file).
-k kflag: Process RCS keywords according to kflag. Seeco(1). This option is sticky; future updates ofthis file in this working directory will use the samekflag. The status command can be viewedto see the sticky options. See section status--Display status information on checked out files.
-l: Local; run only in current working directory.
-n: Do not run any checkout program (as specifiedwith the `-o' option in the modules file;see section The modules file).
-P: Prune empty directories.
-p: Pipe files to the standard output.
-r tag: Use revision tag. This option is sticky, and implies `-P'.See section Sticky tags, for more information on sticky tags/dates.

In addition to those, you can use these special commandoptions with checkout:

-A

Reset any sticky tags, dates, or `-k' options.See section Sticky tags, for more information on sticky tags/dates.

-c

Copy the module file, sorted, to the standard output,instead of creating or modifying any files ordirectories in your working directory.

-d dir

Create a directory called dir for the workingfiles, instead of using the module name. Unless youalso use `-N', the paths created under dirwill be as short as possible.

-j tag

With two `-j' options, merge changes from therevision specified with the first `-j' option tothe revision specified with the second `j' option,into the working directory.

With one `-j' option, merge changes from theancestor revision to the revision specified with the`-j' option, into the working directory. Theancestor revision is the common ancestor of therevision which the working directory is based on, andthe revision specified in the `-j' option.

In addition, each -j option can contain an optionaldate specification which, when used with branches, canlimit the chosen revision to one within a specificdate. An optional date is specified by adding a colon(:) to the tag:`-jSymbolic_Tag:Date_Specifier'.

See section Merging.

-N

Only useful together with `-d dir'. With thisoption, CVS will not shorten module paths in yourworking directory. (Normally, CVS shortens paths asmuch as possible when you specify an explicit targetdirectory).

-s

Like `-c', but include the status of all modules,and sort it by the status string. See section The modules file, forinfo about the `-s' option that is used inside themodules file to set the module status.

checkout examples

Get a copy of the module `tc':

$ cvs checkout tc

Get a copy of the module `tc' as it looked one dayago:

$ cvs checkout -D yesterday tc

commit--Check files into the repository

Version 1.3 Synopsis: commit [-lnR] [-m 'log_message' |-f file] [-r revision] [files...]
Version 1.3.1 Synopsis: commit [-lnRf] [-m 'log_message' |-F file] [-r revision] [files...]
Requires: working directory, repository.
Changes: repository.
Synonym: ci

Warning: The `-f file' option willprobably be renamed to `-F file', and `-f'will be given a new behavior in future releases of CVS.

Use commit when you want to incorporate changesfrom your working source files into the sourcerepository.

If you don't specify particular files to commit, all ofthe files in your working current directory areexamined. commit is careful to change in therepository only those files that you have reallychanged. By default (or if you explicitly specify the`-R' option), files in subdirectories are alsoexamined and committed if they have changed; you canuse the `-l' option to limit commit to thecurrent directory only.

commit verifies that the selected files are upto date with the current revisions in the sourcerepository; it will notify you, and exit withoutcommitting, if any of the specified files must be madecurrent first with update (see section update--Bring work tree in sync with repository).commit does not call the update commandfor you, but rather leaves that for you to do when thetime is right.

When all is well, an editor is invoked to allow you toenter a log message that will be written to one or morelogging programs (see section The modules file, and see section Loginfo)and placed in the RCS history file inside therepository. This log message can be retrieved with thelog command; See section log--Print out 'rlog' information for files. You can specify thelog message on the command line with the `-mmessage' option, and thus avoid the editor invocation,or use the `-f file' option to specifythat the argument file contains the log message.

commit options

These standard options are supported by commit(see section Common command options, for a complete description ofthem):

-l: Local; run only in current working directory.
-n: Do not run any module program.
-R: Commit directories recursively. This is on by default.
-r revision: Commit to revision. revision must beeither a branch, or a revision on the main trunk thatis higher than any existing revision number. Youcannot commit to a specific revision on a branch.

commit also supports these options:

-F file

This option is present in CVS releases 1.3-s3 andlater. Read the log message from file, insteadof invoking an editor.

-f

This option is present in CVS 1.3-s3 and later releasesof CVS. Note that this is not the standard behavior ofthe `-f' option as defined in See section Common command options.

Force CVS to commit a new revision even if you haven'tmade any changes to the file. If the current revisionof file is 1.7, then the following two commandsare equivalent:

$ cvs commit -f file$ cvs commit -r 1.8 file

-f file

This option is present in CVS releases 1.3, 1.3-s1 and1.3-s2. Note that this is not the standard behavior ofthe `-f' option as defined in See section Common command options.

Read the log message from file, insteadof invoking an editor.

-m message

Use message as the log message, instead ofinvoking an editor.

commit examples

New major release number

When you make a major release of your product, youmight want the revision numbers to track your majorrelease number. You should normally not care aboutthe revision numbers, but this is a thing that manypeople want to do, and it can be done without doing anyharm.

To bring all your files up to the RCS revision 3.0(including those that haven't changed), you might do:

$ cvs commit -r 3.0

Note that it is generally a bad idea to try to make theRCS revision number equal to the current release numberof your product. You should think of the revisionnumber as an internal number that the CVS packagemaintains, and that you generally never need to caremuch about. Using the tag and rtagcommands you can give symbolic names to the releasesinstead. See section tag--Add a symbolic tag to checked out versions of files and See section rtag--Add a symbolic tag to a module.

Note that the number you specify with `-r' must belarger than any existing revision number. That is, ifrevision 3.0 exists, you cannot `cvs commit-r 1.3'.

Committing to a branch

You can commit to a branch revision (one that has aneven number of dots) with the `-r' option. Tocreate a branch revision, use the `-b' optionof the rtag or tag commands (see section tag--Add a symbolic tag to checked out versions of filesor see section rtag--Add a symbolic tag to a module). Then, either checkout orupdate can be used to base your sources on thenewly created branch. From that point on, allcommit changes made within these working sourceswill be automatically added to a branch revision,thereby not disturbing main-line development in anyway. For example, if you had to create a patch to the1.2 version of the product, even though the 2.0 versionis already under development, you might do:

$ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module$ cvs checkout -r FCS1_2_Patch product_module$ cd product_module[[ hack away ]]$ cvs commit

This works automatically since the `-r' option issticky.

Creating the branch after editing

Say you have been working on some extremelyexperimental software, based on whatever revision youhappened to checkout last week. If others in yourgroup would like to work on this software with you, butwithout disturbing main-line development, you couldcommit your change to a new branch. Others can thencheckout your experimental stuff and utilize the fullbenefit of CVS conflict resolution. The scenario mightlook like:

[[ hacked sources are present ]]$ cvs tag -b EXPR1$ cvs update -r EXPR1$ cvs commit

The update command will make the `-rEXPR1' option sticky on all files. Note that yourchanges to the files will never be removed by theupdate command. The commit willautomatically commit to the correct branch, because the`-r' is sticky. You could also do like this:

[[ hacked sources are present ]]$ cvs tag -b EXPR1$ cvs commit -r EXPR1

but then, only those files that were changed by youwill have the `-r EXPR1' sticky flag. If you hackaway, and commit without specifying the `-r EXPR1'flag, some files may accidentally end up on the maintrunk.

To work with you on the experimental change, otherswould simply do

$ cvs checkout -r EXPR1 whatever_module

diff--Run diffs between revisions

Synopsis: diff [-l] [rcsdiff_options] [[-r rev1 | -D date1] [-r rev2 | -D date2]] [files...]
Requires: working directory, repository.
Changes: nothing.

The diff command is used to compare differentrevisions of files. The default action is to compareyour working files with the revisions they were basedon, and report any differences that are found.

If any file names are given, only those files arecompared. If any directories are given, all filesunder them will be compared.

The exit status will be 0 if no differences were found,1 if some differences were found, and 2 if any erroroccurred.

diff options

These standard options are supported by diff(see section Common command options, for a complete description ofthem):

-D date: Use the most recent revision no later than date.See `-r' for how this affects the comparison.
CVS can be configured to pass the `-D' optionthrough to rcsdiff (which in turn passes it onto diff. GNU diff uses `-D' as a way toput cpp-style `#define' statements around the outputdifferences. There is no way short of testing tofigure out how CVS was configured. In the defaultconfiguration CVS will use the `-D date' option.
-k kflag: Process RCS keywords according to kflag. Seeco(1).
-l: Local; run only in current working directory.
-R: Examine directories recursively. This option is on bydefault.
-r tag: Compare with revision tag. Zero, one or two`-r' options can be present. With no `-r'option, the working file will be compared with therevision it was based on. With one `-r', thatrevision will be compared to your current working file.With two `-r' options those two revisions will becompared (and your working file will not affect theoutcome in any way).
One or both `-r' options can be replaced by a`-D date' option, described above.

Any other options that are found are passed through torcsdiff, which in turn passes them todiff. The exact meaning of the options dependson which diff you are using. The long optionsintroduced in GNU diff 2.0 are not yet supported inCVS. See the documentation for your diff to seewhich options are supported.

diff examples

The following line produces a Unidiff (`-u' flag)between revision 1.14 and 1.19 of`backend.c'. Due to the `-kk' flag nokeywords are substituted, so differences that only dependon keyword substitution are ignored.

$ cvs diff -kk -u -r 1.14 -r 1.19 backend.c

Suppose the experimental branch EXPR1 was based on aset of files tagged RELEASE_1_0. To see what hashappened on that branch, the following can be used:

$ cvs diff -r RELEASE_1_0 -r EXPR1

A command like this can be used to produce a contextdiff between two releases:

$ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs

If you are maintaining ChangeLogs, a command like the followingjust before you commit your changes may help you writethe ChangeLog entry. All local modifications that havenot yet been committed will be printed.

$ cvs diff -u | less

export--Export sources from CVS, similar to checkout

Synopsis: export [-flNn] [-r rev|-D date] [-k subst] [-d dir] module...
Requires: repository.
Changes: current directory.

This command is a variant of checkout; use itwhen you want a copy of the source for module withoutthe CVS administrative directories. For example, youmight use export to prepare source for shipmentoff-site. This command requires that you specify adate or tag (with `-D' or `-r'), so that youcan count on reproducing the source you ship to others.

One often would like to use `-kv' with cvsexport. This causes any RCS keywords to beexpanded such that an import done at some other sitewill not lose the keyword revision information. But beaware that doesn't handle an export containing binaryfiles correctly. Also be aware that after having used`-kv', one can no longer use the identcommand (which is part of the RCS suite--seeident(1)) which looks for RCS keyword strings. Ifyou want to be able to use ident you must notuse `-kv'.

export options

These standard options are supported by export(see section Common command options, for a complete description ofthem):

-D date: Use the most recent revision no later than date.
-f: If no matching revision is found, retrieve the mostrecent revision (instead of ignoring the file).
-l: Local; run only in current working directory.
-n: Do not run any checkout program.
-R: Export directories recursively. This is on by default.
-r tag: Use revision tag.

In addition, these options (that are common tocheckout and export) are also supported:

-d dir: Create a directory called dir for the workingfiles, instead of using the module name. Unless youalso use `-N', the paths created under dirwill be as short as possible.
-k subst: Set keyword expansion mode (see section Substitution modes).
-N: Only useful together with `-d dir'. With thisoption, CVS will not shorten module paths in yourworking directory. (Normally, CVS shortens paths asmuch as possible when you specify an explicit targetdirectory.)

history--Show status of files and users

Synopsis: history [-report] [-flags] [-options args] [files...]
Requires: the file `$CVSROOT/CVSROOT/history'
Changes: nothing.

CVS can keep a history file that tracks each use of thecheckout, commit, rtag,update, and release commands. You canuse history to display this information invarious formats.

Logging must be enabled by creating the file`$CVSROOT/CVSROOT/history'.

Warning: history uses `-f', `-l',`-n', and `-p' in ways that conflict with thenormal use inside CVS (see section Common command options).

history options

Several options (shown above as `-report') control whatkind of report is generated:

-c

Report on each time commit was used (i.e., each timethe repository was modified).

-e

Everything (all record types); equivalent to specifying`-xMACFROGWUT'.

-m module

Report on a particular module. (You can meaningfullyuse `-m' more than once on the command line.)

-o

Report on checked-out modules.

-T

Report on all tags.

-x type

Extract a particular set of record types type from the CVShistory. The types are indicated by single letters,which you may specify in combination.

Certain commands have a single record type:

F: release
O: checkout
T: rtag

One of four record types may result from an update:

C: A merge was necessary but collisions weredetected (requiring manual merging).
G: A merge was necessary and it succeeded.
U: A working file was copied from the repository.
W: The working copy of a file was deleted duringupdate (because it was gone from the repository).

One of three record types results from commit:

A: A file was added for the first time.
M: A file was modified.
R: A file was removed.

The options shown as `-flags' constrain or expandthe report without requiring option arguments:

-a: Show data for all users (the default is to show dataonly for the user executing history).
-l: Show last modification only.
-w: Show only the records for modifications done from thesame working directory where history isexecuting.

The options shown as `-options args' constrain the reportbased on an argument:

-b str: Show data back to a record containing the stringstr in either the module name, the file name, orthe repository path.
-D date: Show data since date. This is slightly differentfrom the normal use of `-D date', whichselects the newest revision older than date.
-p repository: Show data for a particular source repository (youcan specify several `-p' options on the same commandline).
-r rev: Show records referring to revisions since the revisionor tag named rev appears in individual RCSfiles. Each RCS file is searched for the revision ortag.
-t tag: Show records since tag tag was last added to the thehistory file. This differs from the `-r' flagabove in that it reads only the history file, not theRCS files, and is much faster.
-u name: Show records for user name.

import--Import sources into CVS, using vendor branches

Synopsis: import [-options] repository vendortag releasetag...
Requires: Repository, source distribution directory.
Changes: repository.

Use import to incorporate an entire sourcedistribution from an outside source (e.g., a sourcevendor) into your source repository directory. You canuse this command both for initial creation of arepository, and for wholesale updates to the modulefrom the outside source. See section Tracking third-party sources, fora discussion on this subject.

The repository argument gives a directory name(or a path to a directory) under the CVS root directoryfor repositories; if the directory did not exist,import creates it.

When you use import for updates to source that has beenmodified in your source repository (since a priorimport), it will notify you of any files that conflictin the two branches of development; use `checkout-j' to reconcile the differences, as import instructsyou to do.

If CVS decides a file should be ignored(see section Ignoring files via cvsignore), it does not import it and prints`I ' followed by the filename

If the file `$CVSROOT/CVSROOT/cvswrappers' exists,any file whose names match the specifications in thatfile will be treated as packages and the appropriatefiltering will be performed on the file/directorybefore being imported, See section The cvswrappers file.

The outside source is saved in a first-level RCSbranch, by default 1.1.1. Updates are leaves of thisbranch; for example, files from the first importedcollection of source will be revision 1.1.1.1, thenfiles from the first imported update will be revision1.1.1.2, and so on.

At least three arguments are required.repository is needed to identify the collectionof source. vendortag is a tag for the entirebranch (e.g., for 1.1.1). You must also specify atleast one releasetag to identify the files atthe leaves created each time you execute import.

import options

This standard option is supported by import(see section Common command options, for a complete description):

-m message: Use message as log information, instead ofinvoking an editor.

There are three additional special options.

-b branch: Specify a first-level branch other than 1.1.1. Unlessthe `-b branch' flag is given, revisions willalways be made to the branch 1.1.1--even if avendortag that matches another branch is given!What happens in that case, is that the tag will bereset to 1.1.1. Warning: This behavior might changein the future.
-k subst: Indicate the RCS keyword expansion mode desired. Thissetting will apply to all files created during theimport, but not to any files that previously existed inthe repository. See section Substitution modes for alist of valid `-k' settings.
-I name: Specify file names that should be ignored duringimport. You can use this option repeatedly. To avoidignoring any files at all (even those ignored bydefault), specify `-I !'.
name can be a file name pattern of the same typethat you can specify in the `.cvsignore' file.See section Ignoring files via cvsignore.
-W spec: Specify file names that should be filtered duringimport. You can use this option repeatedly.
spec can be a file name pattern of the same typethat you can specify in the `.cvswrappers'file. See section The cvswrappers file.

import examples

See section Tracking third-party sources, and See section Creating a directory tree from a number of files.

log--Print out 'rlog' information for files

Synopsis: log [-l] rlog-options [files...]
Requires: repository, working directory.
Changes: nothing.
Synonym: rlog

Display log information for files. log callsthe RCS utility rlog, which prints all availableinformation about the RCS history file. This includesthe location of the RCS file, the head revision(the latest revision on the trunk), all symbolic names (tags)and some other things. For each revision, the revisionnumber, the author, the number of lines added/deleted andthe log message are printed. All times are displayed inCoordinated Universal Time (UTC). (Other parts of CVSprint times in the local timezone).

log options

Only one option is interpreted by CVS and not passed on to rlog:

-l: Local; run only in current working directory. (Defaultis to run recursively).

By default, rlog prints all information that isavailable. All other options (including those thatnormally behave differently) are passed through torlog and restrict the output. See rlog(1) for acomplete description of options. This incomplete list(which is a slightly edited extract from rlog(1)) listsall options that are useful in conjunction with CVS.

Please note: There can be no space between the optionand its argument, since rlog parses its optionsin a different way than CVS.

-b

Print information about the revisions on the defaultbranch, normally the highest branch on the trunk.

-ddates

Print information about revisions with a checkindate/time in the range given by thesemicolon-separated list of dates. The following tableexplains the available range formats:

d1<d2
d2>d1: Select the revisions that were deposited betweend1 and d2 inclusive.
<d
d>: Select all revisions dated d or earlier.
d<
>d: Select all revisions dated d or later.
d: Select the single, latest revision dated d orearlier.

The date/time strings d, d1, and d2are in the free format explained in co(1). Quoting isnormally necessary, especially for < and >. Note thatthe separator is a semicolon (;).

-hPrint only the RCS pathname, working pathname, head,default branch, access list, locks, symbolic names, andsuffix.

-NDo not print the list of tags for this file. Thisoption can be very useful when your site uses a lot oftags, so rather than "more"'ing over 3 pages of taginformation, the log information is presented withouttags at all.

-RPrint only the name of the RCS history file.

-rrevisionsPrint information about revisions given in thecomma-separated list revisions of revisions andranges. The following table explains the availablerange formats:

rev1:rev2: Revisions rev1 to rev2 (which must be onthe same branch).
:rev: Revisions from the beginning of the branch up toand including rev.
rev:: Revisions starting with rev to the end of thebranch containing rev.
branch: An argument that is a branch means all revisions onthat branch. You can unfortunately not specify asymbolic branch here. You must specify the numericbranch number. See section Magic branch numbers, for anexplanation.
branch1:branch2: A range of branches means all revisionson the branches in that range.
branch.: The latest revision in branch.

A bare `-r' with no revisions means the latestrevision on the default branch, normally the trunk.

-sstatesPrint information about revisions whose stateattributes match one of the states given in thecomma-separated list states.

-tPrint the same as `-h', plus the descriptive text.

-wloginsPrint information about revisions checked in by userswith login names appearing in the comma-separated listlogins. If logins is omitted, the user'slogin is assumed.

rlog prints the intersection of the revisionsselected with the options `-d', `-l',`-s', and `-w', intersected with the union ofthe revisions selected by `-b' and `-r'.

log examples

Contributed examples are gratefully accepted.

rdiff---'patch' format diffs between releases

rdiff [-flags] [-V vn] [-r t|-D d [-r t2|-D d2]] modules...
Requires: repository.
Changes: nothing.
Synonym: patch

Builds a Larry Wall format patch(1) file between tworeleases, that can be fed directly into the patchprogram to bring an old release up-to-date with the newrelease. (This is one of the few CVS commands thatoperates directly from the repository, and doesn'trequire a prior checkout.) The diff output is sent tothe standard output device.

You can specify (using the standard `-r' and`-D' options) any combination of one or tworevisions or dates. If only one revision or date isspecified, the patch file reflects differences betweenthat revision or date and the current head revisions inthe RCS file.

Note that if the software release affected is containedin more than one directory, then it may be necessary tospecify the `-p' option to the patch command whenpatching the old sources, so that patch is able to findthe files that are located in other directories.

rdiff options

These standard options are supported by rdiff(see section Common command options, for a complete description ofthem):

-D date: Use the most recent revision no later than date.
-f: If no matching revision is found, retrieve the mostrecent revision (instead of ignoring the file).
-l: Local; don't descend subdirectories.
-r tag: Use revision tag.

In addition to the above, these options are available:

-c: Use the context diff format. This is the default format.
-s: Create a summary change report instead of a patch. Thesummary includes information about files that werechanged or added between the releases. It is sent tothe standard output device. This is useful for findingout, for example, which files have changed between twodates or revisions.
-t: A diff of the top two revisions is sent to the standardoutput device. This is most useful for seeing what thelast change to a file was.
-u: Use the unidiff format for the context diffs.This option is not available if your diff does notsupport the unidiff format. Remember that old versionsof the patch program can't handle the unidiffformat, so if you plan to post this patch to the netyou should probably not use `-u'.
-V vn: Expand RCS keywords according to the rules current inRCS version vn (the expansion format changed withRCS version 5).

rdiff examples

Suppose you receive mail from foo@bar.com asking for anupdate from release 1.2 to 1.4 of the tc compiler. Youhave no such patches on hand, but with CVS that caneasily be fixed with a command such as this:

$ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \$$ Mail -s 'The patches you asked for' foo@bar.com

Suppose you have made release 1.3, and forked a branchcalled `R_1_3fix' for bugfixes. `R_1_3_1'corresponds to release 1.3.1, which was made some timeago. Now, you want to see how much development has beendone on the branch. This command can be used:

$ cvs patch -s -r R_1_3_1 -r R_1_3fix module-namecvs rdiff: Diffing module-nameFile ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6File foo.c,v changed from revision 1.52.2.3 to 1.52.2.4File bar.h,v changed from revision 1.29.2.1 to 1.2

release--Indicate that a Module is no longer in use

release [-d] directories...
Requires: Working directory.
Changes: Working directory, history log.

This command is meant to safely cancel the effect of`cvs checkout'. Since CVS doesn't lock files, itisn't strictly necessary to use this command. You canalways simply delete your working directory, if youlike; but you risk losing changes you may haveforgotten, and you leave no trace in the CVS historyfile (see section The history file) that you've abandoned yourcheckout.

Use `cvs release' to avoid these problems. Thiscommand checks that no uncommitted changes arepresent; that you are executing it from immediatelyabove a CVS working directory; and that the repositoryrecorded for your files is the same as the repositorydefined in the module database.

If all these conditions are true, `cvs release'leaves a record of its execution (attesting to yourintentionally abandoning your checkout) in the CVShistory log.

release options

The release command supports one command option:

-d: Delete your working copy of the file if the releasesucceeds. If this flag is not given your files willremain in your working directory.
Warning: The release command uses`rm -r `module'' to delete your file. Thishas the very serious side-effect that any directorythat you have created inside your checked-out sources,and not added to the repository (using the addcommand; see section add--Add a new file/directory to the repository) will be silently deleted--evenif it is non-empty!

release output

Before release releases your sources it willprint a one-line message for any file that is notup-to-date.

Warning: Any new directories that you havecreated, but not added to the CVS directory hierarchywith the add command (see section add--Add a new file/directory to the repository) will besilently ignored (and deleted, if `-d' isspecified), even if they contain files.

U file: There exists a newer revision of this file in therepository, and you have not modified your local copyof the file.
A file: The file has been added to your private copy of thesources, but has not yet been committed to therepository. If you delete your copy of the sourcesthis file will be lost.
R file: The file has been removed from your private copy of thesources, but has not yet been removed from therepository, since you have not yet committed theremoval. See section commit--Check files into the repository.
M file: The file is modified in your working directory. Theremight also be a newer revision inside the repository.
? file: file is in your working directory, but does notcorrespond to anything in the source repository, and isnot in the list of files for CVS to ignore (see thedescription of the `-I' option, andsee section Ignoring files via cvsignore). If you remove your workingsources, this file will be lost.
Note that no warning message like this is printed forspurious directories that CVS encounters. Thedirectory, and all its contents, are silently ignored.

release examples

Release the module, and delete your local working copyof the files.

$ cd .. # You must stand immediately above the # sources when you issue `cvs release'.$ cvs release -d tcYou have [0] altered files in this repository.Are you sure you want to release (and delete) module `tc': y$

rtag--Add a symbolic tag to a module

rtag [-falnR] [-b] [-d] [-r tag | -Ddate] symbolic_tag modules...
Requires: repository.
Changes: repository.
Synonym: rfreeze

You can use this command to assign symbolic tags toparticular, explicitly specified source revisions inthe repository. rtag works directly on therepository contents (and requires no prior checkout).Use tag instead (see section tag--Add a symbolic tag to checked out versions of files), to base theselection of revisions on the contents of yourworking directory.

If you attempt to use a tag name that already exists,CVS will complain and not overwrite that tag. Usethe `-F' option to force the new tag value.

rtag options

These standard options are supported by rtag(see section Common command options, for a complete description ofthem):

-D date: Tag the most recent revision no later than date.
-f: Only useful with the `-D date' or `-r tag'flags. If no matching revision is found, use the mostrecent revision (instead of ignoring the file).
-F: Overwrite an existing tag of the same name on adifferent revision. This option is new in CVS1.4. The old behavior is matched by `cvs tag -F'.
-l: Local; run only in current working directory.
-n: Do not run any tag program that was specified with the`-t' flag inside the `modules' file.(see section The modules file).
-R: Commit directories recursively. This is on by default.
-r tag: Only tag those files that contain tag. This canbe used to rename a tag: tag only the files identifiedby the old tag, then delete the old tag, leaving thenew tag on exactly the same files as the old tag.

In addition to the above common options, these optionsare available:

-a: Use the `-a' option to have rtag look in the`Attic' (see section Removing files from a module) for removed filesthat contain the specified tag. The tag is removed fromthese files, which makes it convenient to re-use asymbolic tag as development continues (and files getremoved from the up-coming distribution).
-b: Make the tag a branch tag. See section Branches.
-d: Delete the tag instead of creating it.
In general, tags (often the symbolic names of softwaredistributions) should not be removed, but the `-d'option is available as a means to remove completelyobsolete symbolic names if necessary (as might be thecase for an Alpha release, or if you mistagged amodule).

status--Display status information on checked out files

status [-lR] [-v] [files...]
Requires: working directory, repository.
Changes: nothing.

Display a brief report on the current status of fileswith respect to the source repository, including anysticky tags, dates, or `-k' options.

You can also use this command to determine thepotential impact of a `cvs update' on your workingsource directory--but remember that things mightchange in the repository before you run update.

status options

These standard options are supported by status(see section Common command options, for a complete description ofthem):

-l: Local; run only in current working directory.
-R: Commit directories recursively. This is on by default.

There is one additional option:

-v: Verbose. In addition to the information normallydisplayed, print all symbolic tags, together with thenumerical value of the revision or branch they referto.

tag--Add a symbolic tag to checked out versions of files

tag [-lR] [-b] [-c] [-d] symbolic_tag [files...]
Requires: working directory, repository.
Changes: repository.
Synonym: freeze

Use this command to assign symbolic tags to the nearestrepository versions to your working sources. The tagsare applied immediately to the repository, as withrtag, but the versions are supplied implicitly by theCVS records of your working files' history rather thanapplied explicitly.

One use for tags is to record a snapshot of thecurrent sources when the software freeze date of aproject arrives. As bugs are fixed after the freezedate, only those changed sources that are to be part ofthe release need be re-tagged.

The symbolic tags are meant to permanently record whichrevisions of which files were used in creating asoftware distribution. The checkout andupdate commands allow you to extract an exactcopy 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.

This command can also be used to delete a symbolic tag,or to create a branch. See the options section below.

If you attempt to use a tag name that already exists,CVS will complain and not overwrite that tag. Usethe `-F' option to force the new tag value.

tag options

These standard options are supported by tag(see section Common command options, for a complete description ofthem):

-F: Overwrite an existing tag of the same name on adifferent revision. This option is new in CVS1.4. The old behavior is matched by `cvs tag -F'.
-l: Local; run only in current working directory.
-R: Commit directories recursively. This is on by default.

Two special options are available:

-b: The -b option makes the tag a branch tag(see section Branches), allowing concurrent, isolateddevelopment. This is most useful for creating a patchto a previously released software distribution.
-c: The -c option checks that all files which are to be tagged areunmodified. This can be used to make sure that you can reconstruct thecurrent file contents.
-d: Delete a tag.
If you use `cvs tag -d symbolic_tag', the symbolictag you specify is deleted instead of being added.Warning: Be very certain of your ground before youdelete a tag; doing this permanently discards somehistorical information, which may later turn out tobe valuable.

update--Bring work tree in sync with repository

update [-AdflPpR] [-d] [-r tag|-D date] files...
Requires: repository, working directory.
Changes: working directory.

After you've run checkout to create your private copyof source from the common repository, other developerswill continue changing the central source. From timeto time, when it is convenient in your developmentprocess, you can use the update command fromwithin your working directory to reconcile your workwith any revisions applied to the source repositorysince your last checkout or update.

update options

These standard options are available with update(see section Common command options, for a complete description ofthem):

-D date: Use the most recent revision no later than date.This option is sticky, and implies `-P'.See section Sticky tags, for more information on sticky tags/dates.
-f: Only useful with the `-D date' or `-rtag' flags. If no matching revision is found,retrieve the most recent revision (instead of ignoringthe file).
-k kflag: Process RCS keywords according to kflag. Seeco(1). This option is sticky; future updates ofthis file in this working directory will use the samekflag. The status command can be viewedto see the sticky options. See section status--Display status information on checked out files.
-l: Local; run only in current working directory. See section Recursive behavior.
-P: Prune empty directories.
-p: Pipe files to the standard output.
-R: Operate recursively. This is on by default.See section Recursive behavior.
-r tag: Retrieve revision tag. This option is sticky,and implies `-P'.See section Sticky tags, for more information on sticky tags/dates.

These special options are also available withupdate.

-A

Reset any sticky tags, dates, or `-k' options.See section Sticky tags, for more information on sticky tags/dates.

-d

Create any directories that exist in the repository ifthey're missing from the working directory. Normally,update acts only on directories and files thatwere already enrolled in your working directory.

This is useful for updating directories that werecreated in the repository since the initial checkout;but it has an unfortunate side effect. If youdeliberately avoided certain directories in therepository when you created your working directory(either through use of a module name or by listingexplicitly the files and directories you wanted on thecommand line), then updating with `-d' will createthose directories, which may not be what you want.

-I name

Ignore files whose names match name (in yourworking directory) during the update. You can specify`-I' more than once on the command line to specifyseveral files to ignore. Use `-I !' to avoidignoring any files at all. See section Ignoring files via cvsignore, for otherways to make CVS ignore some files.

-Wspec

Specify file names that should be filtered duringupdate. You can use this option repeatedly.

spec can be a file name pattern of the same typethat you can specify in the `.cvswrappers'file. See section The cvswrappers file.

-jrevision

With two `-j' options, merge changes from therevision specified with the first `-j' option tothe revision specified with the second `j' option,into the working directory.

See section Merging.

update output

update keeps you informed of its progress byprinting a line for each file, preceded by onecharacter indicating the status of the file:

U file

The file was brought up to date with respect to therepository. This is done for any file that exists inthe repository but not in your source, and for filesthat you haven't changed but are not the most recentversions available in the repository.

A file

The file has been added to your private copy of thesources, and will be added to the source repositorywhen you run commit on the file. This is areminder to you that the file needs to be committed.

R file

The file has been removed from your private copy of thesources, and will be removed from the source repositorywhen you run commit on the file. This is areminder to you that the file needs to be committed.

M file

The file is modified in your working directory.

`M' can indicate one of two states for a fileyou're working on: either there were no modificationsto the same file in the repository, so that your fileremains as you last saw it; or there were modificationsin the repository as well as in your copy, but theywere merged successfully, without conflict, in yourworking directory.

CVS will print some messages if it merges your work,and a backup copy of your working file (as it lookedbefore you ran update) will be made. The exactname of that file is printed while update runs.

C file

A conflict was detected while trying to merge yourchanges to file with changes from the sourcerepository. file (the copy in your workingdirectory) is now the output of the rcsmerge(1) commandon the two revisions; an unmodified copy of your fileis also in your working directory, with the name`.#file.revision' where revisionis the RCS revision that your modified file startedfrom. (Note that some systems automatically purgefiles that begin with `.#' if they have not beenaccessed for a few days. If you intend to keep a copyof your original file, it is a very good idea to renameit.)

? file

file is in your working directory, but does notcorrespond to anything in the source repository, and isnot in the list of files for CVS to ignore (see thedescription of the `-I' option, andsee section Ignoring files via cvsignore).

Note that no warning message like this is printed forspurious directories that CVS encounters. Thedirectory, and all its contents, are silently ignored.

update examples

The following line will display all files which are notup-to-date without actually change anything in yourworking directory. It can be used to check what hasbeen going on with the project.

$ cvs -n -q update

Go to the previous, next section.