Usenet 1994 January/usenetsourcesnewsgroupsinfomagicjanuary1994.iso/sources/unix/volume22/cvs-berliner/part07

Internet Message Format | 1990-06-07 | 44.4 KB

Subject:  v22i021:  Brian Berliner's concurrent RCS system, Part07/07
Newsgroups: comp.sources.unix
Approved: [e-mail]
X-Checksum-Snefru: 5dbeee2d bb9a7889 34c14a7f e6f60bbf

Submitted-by: Brian Berliner <[e-mail]>
Posting-number: Volume 22, Issue 21
Archive-name: cvs-berliner/part07

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file".  To overwrite existing
# files, type "sh file -c".  You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#        "End of archive 7 (of 7)."
# Contents:  man/cvs.man
# Wrapped by [e-mail] on Thu May  3 16:59:07 1990
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'man/cvs.man' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'man/cvs.man'\"
else
echo shar: Extracting \"'man/cvs.man'\" \(42351 characters\)
sed "s/^X//" >'man/cvs.man' <<'END_OF_FILE'
X.\"
X.\"    $Id: cvs.man,v 1.5 89/11/20 00:11:16 berliner Exp $
X.\"
X.TH CVS L "20 July 1989"
X.\" Full space in nroff; half space in troff
X.de SP
X.if n .sp
X.if t .sp .5
X..
X.SH "NAME"
Xcvs \- Concurrent Versions System
X.SH "SYNOPSIS"
X.B cvs
X[
X.I cvs_options
X]
X.I cvs_command
X[
X.I command_options
X] [
X.I command_args
X]
X.SH "DESCRIPTION"
X.IX "revision control system" "\fLcvs\fR"
X.IX  cvs  ""  "\fLcvs\fP \(em concurrent versions system"
X.IX  "concurrent versions system \(em \fLcvs\fP"
X.IX  "release control system"  "cvs command"  ""  "\fLcvs\fP \(em concurrent versions system"
X.IX  "source control system"  "cvs command"  ""  "\fLcvs\fP \(em concurrent versions system"
X.IX  revisions  "cvs command"  ""  "\fLcvs\fP \(em source control"
X.B cvs
Xis a front end to the
X.BR rcs (l)
Xrevision control system which extends
Xthe notion of revision control from a collection of files in a single
Xdirectory to a hierarchical collection of directories consisting of
Xrevision controlled files.
XThese directories and files can be combined together to form a software
Xrelease.
X.B cvs
Xprovides the functions necessary to manage these software releases and to
Xcontrol the concurrent editing of source files among multiple software
Xdevelopers.
X.LP
XThe following list summarizes some of the strong points of
X.BR cvs :
X.TP
X\(bu
XOnly a single copy of the master sources exist.
XThis copy is called the source ``repository'' and, through administrative
Xactions, contains all the information to extract previous software releases
Xat any time based on either a symbolic revision tag, or a date in the past.
X.TP
X\(bu
XIndividual software developers check out private copies of the sources into
Xtheir personal work space.
XThese private sources can be edited at any time and checked back into the
Xsource repository as a permanent change.
X.B cvs
Xtakes special care to ensure that a file is up-to-date with the current
Xrevision in the source repository before allowing it to be added as a
Xpermanent change.
X.TP
X\(bu
XThere is a facility for software developers to bring their private copies
Xof the sources up-to-date with the currently checked in revisions, while at
Xthe same time preserving any modifications that have been made to their
Xprivate sources.
XThis allows multiple developers to be concurrently working on the same
Xsource files without regard for what the other guy is doing.
X.SP
XNote that this is the biggest change from the way most other revision
Xcontrol systems, like
X.SM RCS
Xor
X.SM SCCS
Xwork, which allow only one developer to ever be changing a file, since the
Xfile must be checked out as ``locked'' for the exclusive use of that person.
X.B cvs
Xinstead never applies an
X.SM RCS
Xlock to a checked out file until the moment before it is to be checked back
Xin as a permanent change.
XConcurrency checks are performed on the soon-to-be checked in file and the
Xfile must be up-to-date before it can be made permanent.
XIn this way,
X.B cvs
Xallows individuals the freedom to change any file at will, and provides the
Xtools necessary to point out, if not resolve, any conflicts that may be
Xgenerated by allowing this extra, and necessary, freedom.
X.TP
X\(bu
X.B cvs
Xhas direct support for tracking source releases from third-party vendors.
XThe
X.BR checkin (l)
Xprogram is used to initially setup the source repository.
XThe branch support of
X.SM RCS
Xis used to build the vendor release as a branch off the main (local)
X.SM RCS
Xtrunk.
XOnce this is done, developers can check out files and make local changes to
Xthe vendor's source distribution.
XThe act of checking in a local change to a vendor's source distribution
Xmoves the
X.SM RCS
Xbranch from tracking the third-party vendor's release to the main (local)
XRCS trunk so that
Xthe local version of the file is used forever more.
X.SP
XWhen a new version of the vendor's source distribution (or even a minor
Xversion consisting of a small subset of files) arrives, the
X.B checkin
Xprogram is used again to add the new vendor release to the already existing
Xsource repository.
XFor files that have not been changed locally, the new file from the
Xvendor becomes the current revision.
XFor files that have been modified locally,
X.B checkin
Xwarns that the file must be merged manually with the new vendor release.
XThe
X.B join
Xcommand of
X.B cvs
Xis a useful tool that aids this manual merge process (see below).
X.TP
X\(bu
XA vendor release or a local release can be given a symbolic tag name that
Xis stored directly in the
X.SM RCS
Xfiles.
XThis tag can be used at any time in the future to get an exact copy of any
Xprevious release.
XWith equal ease, one can also extract an exact copy of the source files as
Xof any arbitrary date in the past as well.
X.TP
X\(bu
XAll changes that are made to the source repository are carefully logged in
Xa file, notesfile, or news database, which can be used to produce release
Xnotices.
X.B cvs
Xcan be configured to send log updates through one or more filter programs,
Xbased on a regular expression match on the directory that is being changed.
XThis allows multiple related or unrelated projects to exist within a single
X.B cvs
Xsource repository tree, with each different project sending their checkin
Xreports to a unique log device for the project.
X.TP
X\(bu
XThere is support for a simple, yet powerful, ``module'' database.
XThis database can be used to apply names to collections of directories and
Xfiles as a matter of convenience when checking out smaller pieces of a
Xlarger software distribution.
XThis allows one to checkout the ``diff'' program, for example, without
Xever requiring the knowledge that the sources to ``diff'' actually reside
Xin the ``bin/diff'' directory.
X.SP
XThe module database also has limited support for an aliasing capability.
XThis is useful for programs that share sources from completely disjoint
Xdirectories.
XThe aliasing feature can also be used to limit a named release to a certain
Xcollection of directories and files, to only work with pieces of the source
Xfound in the entire source repository.
X.TP
X\(bu
XThere is direct support for determining which files have changed since a
Xprevious release, or from a particular date.
XAs well,
X.B cvs
Xcan create a
X.BR patch (l)
Xformat output file which can be used to bring a previously released
Xsoftware distribution current with the newest release.
XOne can create a patch file between two tagged revisions, between a
Xrevision and some date in the past, between two dates, or between a date or
Xrevision and the current ``head'' revision.
X.LP
XThe remainder of this manual page will document how all these actions can
Xbe done using the
X.B cvs
Xprogram.
X.SH "OPTIONS"
X.B cvs
Xaccepts a number of options that override the current setting of the
Xrecognized environment variables.
X.TP
X.B \-r
XChecks out files read-only.
XSame effect as if the
X.SM CVSREAD
Xenvironment variable is set.
X.TP
X.B \-w
XChecks out files read-write (default).
XOverrides the setting of the
X.SM CVSREAD
Xenvironment variable.
X.TP
X.B \-v
XOutputs version and copyright information for
X.BR cvs ,
Xthen exits.
X.TP
X\fB-d\fP \fICVS_root_directory\fP
XUse
X.I CVS_root_directory
Xas the root directory pathname of the master
X.SM RCS
Xsource repository.
XOverrides the setting of the
X.SM CVSROOT
Xenvironment variable.
X.TP
X\fB-b\fP \fIbindir\fP
XUse
X.I bindir
Xas the directory to find
X.SM RCS
Xprograms within.
XOverrides the setting of the
X.SM RCSBIN
Xenvironment variable.
X.TP
X\fB-e\fP \fIeditor\fP
XUse
X.I editor
Xfor editing revision log information.
XOverrides the setting of the
X.SM EDITOR
Xenvironment variable.
X.TP
X.B \-H
XDisplays usage information about the specified
X.I cvs_command
Xwithout actually executing said command.
X.SH "USAGE"
XA
X.I cvs_command
Xmust be specified to
X.B cvs
Xwhich drives the specific release control function that is performed.
XEach
X.B cvs
Xcommand accepts options and arguments unique to the command.
XThe usage statements for each command can be displayed by specifying the
X.B \-H
Xoption to the command.
X.LP
XThe available commands are listed below along with a description of their
Xfunction.
XCommand options unique to the command are described in this section with
Xthe command description.
XCommon command options are described fully in the following section.
X.TP
X\fBcheckout\fP [\fB-Qqlfnp\fP] [\fB-c\fP] [\fB-r\fP \fItag\fP|\fB-D\fP \fIdate_spec\fP] \fImodules\fP...
XChecks out the source files defined by
X.IR modules .
XThis command is used to get a private copy of the current sources that can
Xbe edited and processed by most of the other
X.B cvs
Xcommands.
X.B checkout
Xmust be done before many of the other
X.B cvs
Xcommands are used, since most of them operate on checked out sources.
X.SP
XDepending on the
X.I modules
Xspecified,
X.B checkout
Xmay recursively create directories and populate them with the appropriate
Xsource files.
XThese source files can then be edited at any time (regardless of whether
Xother software developers are editing their private copies of the sources),
Xupdated to include new changes checked into the source repository, or
Xcommitted as a permanent change to the
X.SM RCS
Xrepository.
X.SP
XNote that
X.B checkout
Xis used to create directories.
XThe top-level directory created is always added to the working directory
Xwhere
X.B checkout
Xis invoked, and usually has the same name as the specified
X.IR module .
XIn the case of a
X.I module
Xalias, the created sub-directory may have a different name, but you can be
Xsure that it will be a sub-directory, and that
X.B checkout
Xwill show the relative path leading to each file as it is extracted into
Xyour private work area, unless the
X.B \-Q
Xoption is specified.
X.SP
XRunning
X.B checkout
Xon a directory that was already built by
X.B checkout
Xis also OK.
XThis has the same effect as specifying the
X.B \-d
Xoption to the
X.B update
Xcommand described below.
X.SP
XThe
X.B \-c
Xoption ``cat''s the module file, sorted, to the standard output, and does
Xnot cause any files or directories to be checked out.
X.SP
X.B co
Xcan be specified instead of
X.B checkout
Xto save some typing.
XSee the
X.SM MODULES
Xsection below for a complete description of modules.
X.TP
X\fBupdate\fP [\fB-Qqlfp\fP] [\fB-d\fP] [\fB-r\fP \fItag\fP|\fB-D\fP \fIdate_spec\fP] \fIfiles...\fP
XAfter
X.B checkout
Xis run, directories and files have been extracted from the source
Xrepository for your personal editing.
XAt any time that is convenient in your development process, the
X.B update
Xcommand can be run
X.I "from within the directory that contains the checked out sources"
Xto bring those sources current with any revisions that have been checked
Xinto the source repository since they were last checked out or
X.BR update d.
X.SP
XNormally,
X.B update
Xbrings the current directory up-to-date, then descends any sub-directories,
Xbringing them up-to-date as well.
XThis can be overridden by specifying a list of files that should only be
Xupdated, or by using the
X.B \-l
Xoption which causes
X.B update
Xto only process the current directory, ignoring any sub-directories.
X.SP
XIf any special options were initially specified to
X.B checkout
Xwhen the source were initially checked out, these exact options should be
Xspecified to
X.B update
Xas well to keep the sources consistent with the way they were originally
Xchecked out.
XFor example, checking out sources by specifying the ``\fB-r V1_0\fP''
Xoption will check out the revisions associated with the
X.B V1_0
Xrelease tag.
XA subsequent
X.B update
Xthat does \fInot\fP specify this exact
X.B \-r
Xoption as well will revert to updating the sources with the current
Xrevisions as stored in the source repository, rather than those revisions
Xassociated with the
X.B V1_0
Xrelease.
X.SP
XFor a complete description of the algorithm that
X.B update
Xuses to bring your source up-to-date, refer to the
X.SM "\fBCONFLICT RESOLUTION\fP"
Xsection below.
X.TP
X\fBcommit\fP [\fB-fn\fP] [-a] [\fB-m\fP '\fIlog_message\fP'] [\fB-r\fP \fIrevision\fP] [\fIfiles...\fP]
XAt any point, changes that you have made to your private copies of the
Xsources may be
X.BR commit ted
Xto the source repository as a permanent change.
X.B commit
Xdoes not do a recursive
X.BR commit ,
Xso each individual directory must be checked in separately, even if the
Xchanges were related.
X.SP
X.B commit
Xverifies that the selected files are up-to-date with the current revisions
Xin the source repository and will abort without committing if any of the
Xspecified files must be made current first with the
X.B update
Xcommand.
XWith the
X.B \-a
Xoption, all relevant files of the current directory are examined.
X.B commit
Xis careful to only check in those files that have really changed.
XNote that
X.B commit
Xdoes not
X.B update
Xthe out-of-date files for you, but rather leaves that for you to do when
Xthe time is right.
X.SP
XAn
X.SM RCS
Xidentification string ($\&Id\&) must exist in the modified files that are
Xto be checked in.
XIf the identification string cannot be found in any of the files,
X.B commit
Xwill prompt you for verification before proceeding.
XThis prompt is bypassed if the
X.B \-f
Xoption has been specified.
X.SP
XWhen all is well, an editor is invoked for the purpose of entering a log
Xmessage that will be written to one or more logging programs and placed in the
X.SM RCS
Xsource repository file.
XThe log message may be specified on the command line with the
X.B \-m
Xoption, thus suppressing the editor invocation.
X.SP
X.B ci
Xcan be specified instead of
X.B commit
Xto save some typing.
X.TP
X\fBdiff\fP [\fIrcsdiff_options\fP] [\fIfiles...\fP]
XYour checked out files can be diffed against the original revisions they
Xwere based upon with the
X.B diff
Xcommand.
XSee
X.BR rcsdiff (l)
Xfor a list of accepted options.
XIf no files are specified,
X.B diff
Xwill only ``diff'' those files in the current directory that
Xare different than the checked out revision (i.e. ones that
X.I you
Xhave changed), or that are different than a specified revision.
XIf files are specified, only those files are diffed.
X.SP
XTwo revisions may be specified as well.
XIn which case your private sources are not diffed at all.
XInstead, the two revisions specified are diffed.
X.TP
X\fBlog\fP [\fIrlog_options\fP] [\fIfiles...\fP]
XTo display revision log information equivalent to the
X.BR rlog (l)
Xprogram, the
X.B log
Xcommand is used.
XSee
X.BR rlog (l)
Xfor a list of accepted options.
XIf no files are specified,
X.B log
Xwill run an
X.B rlog
X(with the arguments asa specified)
Xon every file under
X.B cvs
Xcontrol in the current directory.
XIf files are specified, the log information of only those files is displayed.
X.TP
X\fBstatus\fP [\fIfiles...\fP]
XDisplays three lines of information for each of its argument files, one for
Xthe user file (line 1), one for the newest
X.SM RCS
Xfile showing the current ``head'' revision number (line 3),
Xand one for the
X.SM RCS
Xfile both derive from showing the date it was last updated (line 2).
X.TP
X\fBadd\fP [\fB-m\fP '\fImessage\fP'] \fIfiles...\fP
XTo permanently create a new file or directory in the
X.SM RCS
Xsource repository, the
X.B add
Xcommand is used.
XThe files or directories specified to
X.B add
Xmust already exist in the current directory (which must have been created
Xwith the
X.B checkout
Xcommand).
XFor adding a whole new directory hierarchy to the source repository
Xthat was received from a third-party vendor, see the
X.BR checkin (l)
Xprogram for how to do this.
X.SP
XIf the argument refers to an immediate sub-directory, the directory is
Xcreated at the correct place in the
X.SM RCS
Xsource repository and the necessary
X.B cvs
Xadministration files are created within the argument directory.
XIt is not considered an error if the
X.SM RCS
Xsource repository directory already exists.
XThus, to add a directory to your private sources that was created after you
Xhad done your
X.B checkout
Xof the sources, you can do the following:
X.SP
X.in +1i
X.ft B
X.nf
Xexample% mkdir new_directory
Xexample% cvs add new_directory
Xexample% cvs update new_directory
X.fi
X.ft P
X.in -1i
X.SP
XFor each added file, a description of the file's purpose is read from the
Xterminal in
X.SM RCS
Xfashion, unless the
X.B \-m
Xoption is specified, in which case the argument
X.I message
Xis used instead.
XThis description will become a permanent part of the created
X.SM RCS
Xfile.
X.SP
XThe added files are not placed in the
X.SM RCS
Xsource repository until they are
X.BR commit ted
Xas a permanent change.
XDoing an
X.B add
Xon a file that has been removed with the
X.B remove
Xcommand will resurrect the file, unless it has already been
X.BR commit ted.
X.TP
X\fBremove\fP \fIfiles...\fP
XMarks the specified files as removed on purpose from the current directory
Xin the source repository.
XThe specified files must no longer exist in the current directory when the
X.B remove
Xcommand is issued.
XThe files are not actually removed until they are
X.BR commit ted,
Xat which point their respective
X.SM RCS
Xfiles in the source depository are
X.I moved
Xinto the
X.I Attic
Xdirectory within the source repository.
XTo restore a committed removed file to the present version requires an
Xadministrator to physically
X.I move
Xthe
X.SM RCS
Xfile out of the
X.I Attic
Xand back into its parent directory.
X.TP
X\fBjoin\fP [\fB-Qqf\fP] [\fB-r\fP \fItag\fP|\fB-D\fP \fIdate_spec\fP] \fIfiles...\fP
XThe intended purpose of the
X.B join
Xcommand is to perform the logical merge of a new vendor release installed
Xwith the
X.BR checkin (l)
Xcommand with locally modified files from a previous vendor release.
XThe
X.B checkin
Xprogram will inform you that a vendor file has been locally modified and it
Xis up to
X.I you
Xto resolve the two branches of development (local and vendor) into a
Xunified revision that will be
X.BR commit ted
Xas a permanent change to the source repository on the main (local) trunk.
XThe
X.B join
Xcommand will usually be used with the
X.B \-r
Xoption to specify the vendor tag that is to be merged with the local
Xchanges.
XThis merge is handled by
X.SM RCS
Xand the resultant file is placed in the current directory (within your
Xprivate work space) and any conflicts during the merge are displayed.
X.SP
XAfter correcting any conflicts during the merge,
X.B commit
Xthe joined file as usual with a modified file, and the result (with a bit
Xof work, perhaps) should be a working combination of the local changes and
Xthe vendor changes.
X.LP
XThe following commands do their work entirely within the
X.SM RCS
Xsource repository and, as such, do not require that a
X.B checkout
Xbe done first.
XThese commands are usually of interest only to the person responsible for
Xthe release procedures of a software package.
XSee the
X.SM "\fBMODULE SUPPORT\fP"
Xsection below for a full description of what a
X.I module
Xis.
X.TP
X\fBpatch\fP [\fB-Qqlf\fP] [\fB-s\fP|\fB-t\fP] [\fB-r\fP \fItag\fP|\fB-D\fP \fIdate_spec\fP [\fB-r\fP \fItag\fP|\fB-D\fP \fIdate_spec\fP]] \fImodules...\fP
XBuilds a Larry Wall format
X.BR patch (l)
Xfile between two releases that can be fed directly into the
X.B patch
Xprogram to bring an old release up-to-date with the new release.
XThe diff output is sent to the standard output device.
XNote that any combination of one or two revisions or dates may be specified.
XIf only one revision or date is specified, the
X.B patch
Xis made between that revision or date and the current ``head'' revisions in
Xthe
X.SM RCS
Xfile.
X.SP
XNote that if the software release that is being
X.BR patch ed
Xis contained in more than one directory, then it may be necessary to
Xspecify the
X.B \-p
Xoption to the
X.BR patch (l)
Xcommand when patching the old sources, so that
X.BR patch (l)
Xis able to find the files that are located in other directories.
X.SP
XIf the
X.B \-s
Xoption is specified, a patch file is not produced.
XInstead, a description of the changed or added files between the two
Xreleases is sent to the standard output device.
XThis is useful for finding out, for example, which files have changed
Xbetween two dates or revisions.
X.SP
XIf the
X.B \-t
Xoption is specified, a diff of the top two revisions is sent to the
Xstandard output device.
XThis is most useful for seeing what the last change to a file was.
X.TP
X\fBtag\fP [\fB-Qqlfn\fP] [\fB-d\fP] [\fB-r\fP \fItag\fP|\fB-D\fP \fIdate_spec\fP] \fIsymbolic_tag\fP \fImodules...\fP
XSources in the repository can have a symbolic tag associated with them.
XThis allows one to ``snapshot'' the current sources when the software
Xfreeze date of a project arrives, and as bugs are fixed after the freeze
Xdate, only those changed sources that are to be part of the release need be
Xre-tagged.
X.SP
XThe symbolic tags are meant to permanently record which revisions of which
Xfiles were used in creating a software distribution.
XThe functionality provided with the
X.B checkout
Xand
X.B update
Xcommands allow one to extract an exact copy of this release at any time in
Xthe future, regardless of whether files have been
X.BR add ed
Xor
X.BR remove d
Xsince the release was
X.BR tag ged.
XSo in general, these symbolic names of software distributions should not be
Xremoved, but the
X.B \-d
Xoption is provided as a means to remove completely obsolete symbolic names
Xif necessary (as might be the case for an Alpha release, say).
XIt is also possible to only tag files that already contain a certain tag.
XThis method would be used to rename a tag \(em tag only the files with the
Xold tag, then delete the old tag leaving the new tag which would tag the
Xexact same files as the old tag.
X.SH "COMMAND OPTIONS"
XThe following options are common to more than one of the
X.B cvs
Xcommands, and are explained in detail here once, for brevity.
X.TP
X.B \-Q
XCauses the command to be
X.I really
Xquiet.
X.TP
X.B \-q
XCauses the command to be somewhat quiet.
X.TP
X.B \-l
XCauses the command to not be recursive.
XOnly the specified directory will be processed.
X.TP
X.B \-f
XForces the specified tag to match.
XNormally, when a tag is specified with the
X.B \-r
Xoption and the
X.SM RCS
Xfile does not contain the tag, the ``head'' revision for the
X.SM RCS
Xfile is returned.
XWhen the
X.B \-f
Xoption is specified, any
X.SM RCS
Xfile that does not contain the specified tag is ignored.
XThis is useful for extracting an exact copy of a previously tagged release.
X.TP
X.B \-n
XCauses the command
X.I not
Xto run any
X.BR checkout / commit / tag
Xprogram as specified in the modules database.
X.TP
X.B \-p
XOn
X.BR checkout " or " update ,
Xprune directories that are empty after being updated.
XThis is useful for extracting an exact copy of a previously release,
Xespecially when combined with the
X.B \-f
Xoption.
X.TP
X\fB-r\fP \fItag\fP
XCauses the command to use the revision specified by the
X.I tag
Xargument instead of the usual ``head'' revision.
XThe
X.I tag
Xcan be either a symbolic or numeric tag, in
X.SM RCS
Xfashion,
Xexcept in the case of the
X.B commit
Xcommand, in which case the
X.I tag
Xmust be a numeric one.
XSpecifying the
X.B \-q
Xoption along with the
X.B \-r
Xoption is often useful, to suppress the warning messages when the
X.SM RCS
Xfile does not contain the specified tag.
X.TP
X\fB-D\fP \fIdate_spec\fP
XCauses the command to use the revision that was checked in at or before the
Xspecified
X.I date_spec
Xargument.
XThe
X.I date_spec
Xis a single argument, free form date description specifying a date in the
Xpast.
XThis option implies the
X.B \-f
Xoption.
XSee the
X.SM "\fBEXAMPLES\fP"
Xsection for useful examples of how the
X.B \-D
Xoption can be used.
X.SH "CONFLICT RESOLUTION"
XThe algorithm used by
X.BR checkout " and " update
Xis described in this section.
XThe output generated, unless the
X.B \-Q
Xoption is specified, consists of the following lines to describe exactly
Xhow your private sources are being brought up-to-date with the
X.SM RCS
Xsource repository.
X.TP
X\fBU\fP \fIfile\fP
XThe specified file was copied directly out of its respective
X.SM RCS
Xfile from the source repository.
XThis is done because the condition of your user file matches one of the
Xfollowing:
X.in 1.5i
X.ti -.5i
X\(bu    The user file did not exist in your private sources, whether it was
Xbecause you removed it, or because someone added it to the source repository.
X.ti -.5i
X\(bu    The file did exist, but you did not change it and a different
Xrevision was matched in the
X.SM RCS
Xfile, be it by the default ``head'' match, or via the
X.B \-r
Xor
X.B \-D
Xoptions.
X.TP
X\fBM\fP \fIfile\fP
XThe specified file has been modified locally by you.
XUse the
X.B diff
Xcommand to see the actual changes that you have made.
X.TP
X\fBA\fP \fIfile\fP
XThe specified file has been added to your private copy of the sources, and
Xwill be added to the
X.SM RCS
Xsource repository when the file is
X.BR commit ted.
XThis is a reminder to you that the file needs to be committed.
X.TP
X\fBR\fP \fIfile\fP
XThe specified file has been removed from your private copy of the sources, and
Xwill be removed from the
X.SM RCS
Xsource repository when the file is
X.BR commit ted.
XThis is a reminder to you that the file needs to be committed.
X.TP
X\fBC\fP \fIfiles\fP
XThe specified file was modified locally by you, and while doing the
X.BR update ,
Xit was determined that a later revision had been checked into the respective
X.SM RCS
Xfile.
XAs a result,
X.B cvs
Xperforms an
X.BR rcsmerge (l),
Xwhich combines the changes made to the
X.SM RCS
Xfile with the changes that you have made to your version of the file.
XIf there were any lines in conflict during the merge (i.e. the other
Xdeveloper changed the same line that you have changed), then the
X.B C
Xis displayed to show that the file must be manually corrected.
X.SP
XThis merge process delimits the lines in conflict using lines beginning with
X``>>>>>>>'' and ``<<<<<<<'', so it is easy to find the conflicts within
Xyour merged file.
XNote that your original, modified file is preserved in a backup file within
Xthe same directory that the file existed.
XThe backup file has the form ``\fB.#\fP\fIfile\fP\fB.\fP\fIversion\fP'',
Xwhere the
X.I version
Xis the
X.SM RCS
Xrevision that your modified file was based upon.
XNote that some systems automatically purge files that begin with
X.B .#
Xif they have not been accessed in roughly three days.
XThus, if you intend to keep a copy of your original file, I strongly
Xsuggest that it be renamed.
X.SP
XIf the merge process proceeded without any conflicts, an
X.B M
Xis displayed instead of a
X.BR C .
XIt is still a wise idea to
X.BR diff (1)
Xthe original version before the merge, contained in the backup file, with
Xthe merged version to verify that the merged changes make sense with your
Xchanges.
X.SH "MODULE SUPPORT"
XThe
X.BR checkout ", " patch ", and " tag
Xcommands all accept
X.I module
Xnames as arguments.
XThe module database is stored as an
X.BR ndbm (3)
Xformat database within the
X.SM CVSROOT.adm
Xdirectory of your
X.SM CVSROOT
Xsource repository.
XThe remainder of this section considers how the
X.B checkout
Xcommand operates on the modules database.
XThe operations for the other commands that use the database are similar,
Xexcept that they do not create any files or directories in your work space, as
X.B checkout
Xdoes.
X.LP
XThe above commands search the module database for each module argument.
XIf the module database does not exist, or if the argument does not have a
Xmatching key in the module database, the argument is processed as follows:
X.TP
X1.
XThe value of the
X.SM CVSROOT
Xenvironment variable is prepended to the argument to form a full path name.
X.TP
X2.
XIf the full path name does not exist, either as a directory or as a file
Xwith an
X.SM RCS
X.B ,v
Xextension, the argument module cannot be resolved and the command
Xcontinues, processing any remaining argument modules.
X.TP
X3.
XIf the full path name refers to a directory, the directories leading up to
Xthe directory are created, starting from the current working directory, and
Xthe directory is populated with the correct files, ready for your editing
Xsatisfaction.
XIf available, and the
X.B \-l
Xoption was not specified, sub-directories are created and populated as
Xwell, until the entire directory hierarchy of the specified module argument
Xis reconstructed in your work space.
X.TP
X4.
XIf the full path name, combined with an
X.SM RCS
X.B ,v
Xsuffix exists, only that file is extracted.
XThe directories leading up to where the argument module resides are
Xcreated, if necessary, and the leaf directory is populated with the single
Xsource file.
X.LP
XIt should be clear from reading the above algorithm that the module
Xdatabase is not required to extract or process whole directory hierarchies,
Xor even individual files.
XHowever, the addition of the module database allows a high degree of
Xflexibility to be added to the structure or naming of pieces of software
Xwithin the
X.SM CVSROOT
Xsource hierarchy.
XThe easiest way to demonstrate the usefulness of the module database is by
Xexample.
XAnd so, one follows:
X.LP
X.RS
X.ne 42
X.nf
X#
X# Sample CVS Modules file
X#
X# Three different line formats are valid:
X#    key     -a    aliases...
X#    key [options] directory
X#    key [options] directory files...
X#
X# Where "options" are composed of:
X#    -i prog        Run "prog" on checkin of files
X#    -o prog        Run "prog" on "checkout" of files
X#    -t prog        Run "prog" on tagging of files
X#
X
X# Convenient aliases
Xworld        -a .
X
X# CVSROOT.adm support
XCVSROOT    -i /usr/local/bin/mkmodules CVSROOT.adm
XCVSROOT.adm    -i /usr/local/bin/mkmodules CVSROOT.adm
Xmodules        -i /usr/local/bin/mkmodules CVSROOT.adm modules
Xloginfo        -i /usr/local/bin/mkmodules CVSROOT.adm loginfo
X
X# The "sys" entry exists only to make symbolic links after checkout
Xsys        -o sys/tools/make_links sys
X
X# Sub-directories of "bin"
Xawk        bin/awk
Xcsh        bin/csh
Xdiff        bin/diff
Xmake        bin/make
Xsed        bin/sed
Xsh        bin/sh
X
X# Programs that live in "bin"
Xcat        bin Makefile cat.c
Xchgrp        bin Makefile chgrp.c
Xchmod        bin Makefile chmod.c
Xcmp        bin Makefile cmp.c
Xcp        bin Makefile cp.c
Xdate        bin Makefile date.c
Xdd        bin Makefile dd.c
X.fi
X.RE
X.LP
XThe format of the
X.I modules
Xfile is also described in the above example.
XThe
X.B \-a
Xoption in the database indicates that the key is an alias, and that the
Xright-hand side of the alias is to be interpreted by the command
X.I exactly
Xas if it had been specified as arguments on the command line for the command.
XThe
X.B \-o
Xoption indicates that the specified program is to be run on
X.BR checkout .
XThe key for the entry is passed as the sole argument to the program.
XThe
X.B \-i
Xoption indicates that the specified program is to be run on
X.BR commit .
XThe full pathname of the respective source repository directory
Xis passed as the sole argument to the program.
XThe
X.B \-t
Xoption indicates that the specified program is to be run on
X.BR tag .
XThe key for the entry is passed as the sole argument to the program.
X.LP
XAs an example, the command
X.SP
X.in +1i
X.ft B
X.nf
Xexample% cvs checkout awk
X.fi
X.ft P
X.in -1i
X.SP
Xwill create the ``awk'' directory in your current working directory, if
Xnecessary, and populate it with the current revisions of the
Xfiles in the ``\c
X.SM $CVSROOT\c
X/bin/awk'' directory.
XThe command
X.SP
X.in +1i
X.ft B
X.nf
Xexample% cvs checkout date
X.fi
X.ft P
X.in -1i
X.SP
Xwill create the ``date'' directory and populate with exactly the two files
X``Makefile'' and ``date.c'' from the ``\c
X.SM $CVSROOT\c
X/bin/awk'' directory.
X.SH "VENDOR BRANCH SUPPORT"
XThe branch support of
X.SM RCS
Xis used to provide a convenient method of tracking the changes
Xmade to a vendor's source distribution.
XWhen a source distribution is received from a vendor, the first step is to
Xrun the
X.BR checkin (l)
Xprogram to place the vendor's files under
X.SM CVS
Xcontrol.
X.BR checkin (l)
Xarranges that the
X.SM RCS
Xfiles produced from the vendor's source distribution are initially setup to
Xtrack the 1.1.1 branch of the
X.SM RCS
Xfile.
XWhen a
X.B commit
Xis done to one of these files, making permanent some local change, the
X.SM RCS
Xfile is changed to track the normal ``trunk'' branch, continuing the local
Xchanges to the vendor's sources.
X.LP
XWhen a new version of the vendor's source distribution is received,
X.B checkin
Xis used again to add the new files to
X.SM CVS.
X.B checkin
Xagain adds the files to the (now already existing) 1.1.1 branch of the
X.SM RCS
Xfile.
XThis time, however,
X.B checkin
Xissues a warning when a new version of a locally modified file is updated
Xby the vendor's source distribution.
XIt is your responsibility to then use the
X.B join
Xcommand of
X.B cvs
Xto merge the vendor's changes with your local changes.
XSee the description of the
X.B join
Xcommand above.
X.LP
XThe
X.B \-r
Xand
X.B \-D
Xoptions of the
X.B checkout
Xand
X.B update
Xcommands work ``as expected'' with the vendor branch support.
XIn particular, the
X.B \-D
Xoption to check out based on a date in the past follows the current default
Xbranch to find a match for the specified date.
XIf a match cannot be found on the default branch, the 1.1.1 vendor
Xbranch is searched.
XThis allows checking out based on a date to work regardless of when
Xlocal changes are made to the file.
X.SH "LOGGING SUPPORT"
XWhen
X.BR commit ting
Xa change to the source repository, a configurable logging support file,
X.IR loginfo ,
Xis consulted in the $\c
X.SM CVSROOT\c
X/\c
X.SM CVSROOT.adm
Xdirectory.
XAn example of the file is as follows:
X.LP
X.RS
X.ne 22
X.nf
X# The "loginfo" file is used to control where "cvs commit"
X# log information is sent.  The first entry on a line is a
X# regular expression which is tested against the directory
X# that the change is being made to, relative to the
X# $CVSROOT.  If a match is found, then the remainder of the
X# line is a filter program that should expect log information
X# on its standard input.
X#
X# The filter program may use one and only one % modifier (ala
X# printf).  If %s is specified in the filter program, a brief
X# title is included (enclosed in single quotes) showing the
X# modified file names.
X#
X# If the repository name does not match any of the regular
X# expressions in this file, the "DEFAULT" line is used, if it
X# is specified.
X#
XDEFAULT    /usr/local/bin/nfpipe -t %s utils.updates
X^diag        /usr/local/bin/nfpipe -t %s diag.updates
X^local        /usr/local/bin/nfpipe -t %s local.updates
X^perf        /usr/local/bin/nfpipe -t %s perf.updates
X^sys        /usr/local/bin/nfpipe -t %s kernel.updates
X.fi
X.RE
X.LP
XIn addition, ``ALL'' can be specified as a special regular expression which
Xalways matches, but does not change the behaviour of when the ``DEFAULT''
Xbranch is taken.
XAll matches for the regular expression are executed.
XThis logging feature allows for multiple groups and logging programs to
Xshare a single
X.SM CVS
Xsource repository.
X.SH "EXAMPLES"
XUsing the example
X.I modules
Xand
X.I loginfo
Xfiles shown above, this section shows some sample commands and describes
Xtheir functions.
X.SP
X.in +1i
X.ft B
X.nf
Xexample% cvs checkout csh
Xexample% cd csh
Xexample% make
X.fi
X.ft P
X.in -1i
X.SP
XThis command retrieves the current revision of the ``csh'' sources and
Xplaces them within the ``csh'' directory.
XThe ``make'' command within that directory will then build the ``csh''
Xexecutable.
X.SP
X.in +1i
X.ft B
X.nf
Xexample% cvs checkout -rSunOS csh
Xexample% cd csh
Xexample% make
X.fi
X.ft P
X.in -1i
X.SP
XThese commands get the current SunOS revision of ``csh'' and builds the
Xexecutable.
X.SP
X.in +1i
X.ft B
X.nf
Xexample% cvs checkout date
Xexample% cd date
Xexample% make date
X.fi
X.ft P
X.in -1i
X.SP
XThese commands checkout the current revision of the ``date'' command, along
Xwith the Makefile that is required to build the ``date'' executable.
XThe ``make'' command includes the target ``date'', since this Makefile is
Xused to build much more than just ``date'' by default.
X.SP
X.in +1i
X.ft B
X.nf
Xexample% cvs checkout -q sys
X.fi
X.ft P
X.in -1i
X.SP
XGets a copy of the current kernel sources, including the entire kernel
Xdirectory hierarchy.
XThe
X.B \-q
Xoption suppresses the message displayed as each directory is descended.
X.SP
X.in +1i
X.ft B
X.nf
Xexample% cvs checkout -p -q -f -rSunOS sys
X.fi
X.ft P
X.in -1i
X.SP
XGets an
X.I exact
Xcopy of the current revision SunOS kernel sources.
XThe
X.B \-f
Xoption forces only files that have the ``SunOS'' tag to be retrieved, not
Xincluding files locally added to the kernel sources.
XThe
X.B \-p
Xoption prunes empty directories, thereby not including directories that
Xhave been locally added to the kernel source hierarchy.
X.SP
X.in +1i
X.ft B
X.nf
Xexample% cvs checkout -p -D 'August 10, 1989 14:40' sys
X.fi
X.ft P
X.in -1i
X.SP
XThe exact copy of the kernel sources as of the specified date and time is
Xretrieved.
XThe date is a free-form strings, as specified in
X.BR rcs (l).
X.SP
X.in +1i
X.ft B
X.nf
Xexample% cvs diff -c
Xexample% cvs commit -a -m 'fixed NULL pointer dereference'
X.fi
X.ft P
X.in -1i
X.SP
XThe
X.B diff
Xcommand displays a context diff of all the changes that you have made to
Xthe sources within the current directory.
XOnly those files thaty you have changed are displayed.
XThe
X.B commit
Xcommand makes these changes permanent within the source repository so that
Xothers can benefit from your fix.
X.SP
X.in +1i
X.ft B
X.nf
Xexample% cvs diff -c -rSunOS file.c
Xexample% cvs diff -c -r1.9 -r1.11 file.c
Xexample% cvs diff -c -r1.22 file.c
X.fi
X.ft P
X.in -1i
X.SP
XExamples of how the
X.B diff
Xcommand can be used.
XThe first example displays the differences between the SunOS version of the
Xfile and your checked out version.
XThe second example shows the differences between two specific revisions of
Xthe
X.SM RCS
Xfile.
XThe final example diffs the currently checked out file against a specific
Xrevision of the
X.SM RCS
Xfile.
X.SP
X.in +1i
X.ft B
X.nf
Xexample% cvs tag PrismaOS1_0 csh
Xexample% cvs tag PrismaOS1_0 bin
Xexample% cvs tag test_kernel sys
Xexample% cvs tag -d test_kernel sys
Xexample% cvs tag -q -f -rSunOS SUNOS .
Xexample% cvs tag -D 'June 30, 1989' JUNE_KERNEL sys
X.fi
X.ft P
X.in -1i
X.SP
X
X.SH "FILES"
X.TP
XCVS.adm
XA directory created by the
X.B checkout
Xcommand within each directory that contains checked out source files.
XThis directory holds all the
X.B cvs
Xadministration files for an individual's private copy of the sources.
XIn general, these files should not be edited by hand.
X.B cvs
Xwill do that for you.
XBe sure to
X.I never
Xremove this directory if you have source files that have been modified and
Xneed to be committed in the directory that the
XCVS.adm
Xdirectory administrates.
XThe files contained in this directory are described below.
X.TP
XCVS.adm/Entries
XContains the list of files that have been checked out in the current
Xdirectory along with the revision number that each checked out file is
Xup-to-date with and a timestamp that is used to quickly determine if a file
Xhas been possibly modified or not.
X.TP
XCVS.adm/Entries.Backup
XA backup of the previous
XCVS.adm/Entries
Xfile, just in case of catastrophe.
X.TP
XCVS.adm/Entries.Static
XThe existence of this file tells
X.B cvs
Xto only use the files contained in the
XCVS.adm/Entries
Xfile when generating the list of source files for this directory.
XThis allows selected files from a directory in the source repository to be
Xchecked out and manipulated without requiring that the entire source
Xdirectory be used.
X.TP
XCVS.adm/Mod
XAfter doing an
X.B update
Xcommand, this file reflects the current list of modified source files for
Xthe directory.
X.TP
XCVS.adm/Repository
XHolds the pathname to the respective directory in the source repository
Xthat these files refer to.
XThis is usually a relative pathname, with the value of the
X.SM CVSROOT
Xenvironment tacked on the front to produce a full pathname.
XIf the pathname in the
XCVS.adm/Repository
Xfile is already a full pathname, the
X.SM CVSROOT
Xvalue is not tacked on.
X.TP
XCVS.adm/Checkin.prog
XContains one line which specifies the program that is to be run when any
Xfiles in the current directory are checked in to the source repository with the
X.B commit
Xcommand.
XThe particular use of this is to rebuild the ``modules'' database after a
Xnew revision is checked in \(em see
X.BR mkmodules (l).
X.LP
XThe following files or directories are created directly in the source
Xrepository directories as needed.
X.TP
XCVSROOT.adm
XA directory that should exist in the top-most directory as defined by the
X.SM CVSROOT
Xenvironment variable.
XThis directory contains administrations files that define the global
Xactions for the entire source repository beginning at
X.SM CVSROOT .
XThe files used directly by
X.B cvs
Xin this directory are described below, though you are free to add others as
Xyou see fit.
X.TP
XCVSROOT.adm/modules,v
XThe
X.SM RCS
Xfile which defines the
X.I modules
Xsupported within this source repository.
XThe format is as specified in the
X.SM "\fBMODULE SUPPORT\fP"
Xsection above for more information.
X.TP
XCVSROOT.adm/loginfo,v
XThe
X.SM RCS
Xfile that contains the descriptions of which programs to pipe log messages
Xinto when
X.BR commit ting
Xfiles.
XSee the
X.SM "\fBLOGGING SUPPORT\fP"
Xsection above for more information.
X.TP
XAttic
XWhen
X.SM RCS
Xfiles are removed with the
X.B remove
Xcommand, the actual
X.SM RCS
Xfile is moved into the Attic directory where it will remain until someone
Xuses the
X.B add
Xcommand to restore it as a needed source file.
X.TP
X#cvs.lock
XA lock directory created by
X.B cvs
Xwhen doing sensitive changes to the
X.SM RCS
Xsource repository.
X.TP
X#cvs.tfl.\fIpid\fP
XA lock file created just to test the waters of the
X.SM RCS
Xsource repository directory before committing files.
X.TP
X#cvs.rfl.\fIpid\fP
XA read lock created when doing the
X.B update
Xcommand.
XA
X.B commit
Xdone by some other user will wait until all readers have finished using the
Xdirectory before proceeding.
X.TP
X#cvs.wfl.\fIpid\fP
XA write lock created by
X.B commit
Xto cause any other
X.BR update s
Xin the same source repository directory to block until the commit has
Xcompleted.
X.SH "ENVIRONMENT VARIABLES"
X.TP
X.SM CVSROOT
XMust be set for most commands.
XShould contain the full pathname to the root of the
X.B cvs
Xsource repository, that is, where the
X.SM RCS
Xfiles are kept.
X.TP
X.SM CVSREAD
XIf this is set,
X.B checkout
Xand
X.B update
Xwill try hard to make your private checked out sources read-only.
XWhen this is not set, the default behaviour is to make read-write files.
X.TP
X.SM RCSBIN
XSpecifies the full pathname where to find
X.SM RCS
Xprograms, such as
X.BR co (l)
Xand
X.BR ci (l).
XIf not set, the default is
X.BR /usr/local/bin .
X.TP
X.SM EDITOR
XSpecifies the editor to use when doing a
X.BR commit .
XIf not set, the default editor used is
X.BR /usr/ucb/vi .
X.SH "AUTHORS"
X.TP
XDick Grune
XOriginal author of the
X.B cvs
Xshell script version posted to
X.B comp.sources.unix
Xin the volume6 release of December, 1986.
XCredited with much of the
X.B cvs
Xconflict resolution algorithms.
X.TP
XBrian Berliner
XCoder and designer of the
X.B cvs
Xprogram itself in April, 1989, based on the original work done by Dick.
X.TP
XJeff Polk
XHelped Brian with the design of the
X.B cvs
Xmodule and vendor branch support and author of the
X.BR checkin (l)
Xshell script.
X.SH "SEE ALSO"
X.BR checkin (l),
X.BR ci (l),
X.BR co (l),
X.BR diff (1),
X.BR grep (1),
X.BR mkmodules (l),
X.BR ndbm (3),
X.BR patch (l),
X.BR rcs (l),
X.BR rcsdiff (l),
X.BR rcsmerge (l),
X.BR rlog (l),
X.BR rm (1),
X.BR sort (1).
X.SH "BUGS"
END_OF_FILE
if test 42351 -ne `wc -c <'man/cvs.man'`; then
    echo shar: \"'man/cvs.man'\" unpacked with wrong size!
fi
# end of 'man/cvs.man'
fi
echo shar: End of archive 7 \(of 7\).
cp /dev/null ark7isdone
MISSING=""
for I in 1 2 3 4 5 6 7 ; do
    if test ! -f ark${I}isdone ; then
    MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 7 archives.
    rm -f ark[1-9]isdone
else
    echo You still need to unpack the following archives:
    echo "        " ${MISSING}
fi
##  End of shell archive.
exit 0
exit 0 # Just in case...