rsalz@uunet.uu.net (Rich Salz) (05/04/90)
Submitted-by: Brian Berliner <berliner@prisma.com> 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 rsalz@litchi.bbn.com 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... -- Please send comp.sources.unix-related mail to rsalz@uunet.uu.net. Use a domain-based address or give alternate paths, or you may lose out.