OS/2 Professional

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / unix / doc / cvs.man < prev next >

Wrap

Text File | 1992-01-14 | 48KB | 988 lines

NAME cvs - Concurrent Versions System SYNOPSIS cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ] DESCRIPTION cvs is a front end to the rcs(l) revision control system which extends the notion of revision control from a collec- tion of files in a single directory to a hierarchical col- lection of directories consisting of revision controlled files. These directories and files can be combined together to form a software release. cvs provides the functions necessary to manage these software releases and to control the concurrent editing of source files among multiple software developers. The following list summarizes some of the strong points of cvs: + Only a single copy of the master sources exist. This copy is called the source ``repository'' and, through administrative actions, contains all the information to extract previous software releases at any time based on either a symbolic revision tag, or a date in the past. + Individual software developers check out private copies of the sources into their personal work space. These private sources can be edited at any time and checked back into the source repository as a permanent change. cvs takes special care to ensure that a file is up-to- date with the current revision in the source repository before allowing it to be added as a permanent change. + There is a facility for software developers to bring their private copies of the sources up-to-date with the currently checked in revisions, while at the same time preserving any modifications that have been made to their private sources. This allows multiple developers to be concurrently working on the same source files without regard for what the other guy is doing. Note that this is the biggest change from the way most other revision control systems, like RCS or SCCS work, which allow only one developer to ever be changing a file, since the file must be checked out as ``locked'' for the exclusive use of that person. cvs instead never applies an RCS lock to a checked out file until the moment before it is to be checked back in as a per- manent change. Concurrency checks are performed on the soon-to-be checked in file and the file must be up-to- date before it can be made permanent. In this way, cvs allows individuals the freedom to change any file at will, and provides the tools necessary to point out, if not resolve, any conflicts that may be generated by allowing this extra, and necessary, freedom. + cvs has direct support for tracking source releases from third-party vendors. The checkin(l) program is used to initially setup the source repository. The branch support of RCS is used to build the vendor release as a branch off the main (local) RCS trunk. Once this is done, developers can check out files and make local changes to the vendor's source distribution. The act of checking in a local change to a vendor's source distribution moves the RCS branch from tracking the third-party vendor's release to the main (local) RCS trunk so that the local version of the file is used forever more. When a new version of the vendor's source distribution (or even a minor version consisting of a small subset of files) arrives, the checkin program is used again to add the new vendor release to the already existing source repository. For files that have not been changed locally, the new file from the vendor becomes the current revision. For files that have been modi- fied locally, checkin warns that the file must be merged manually with the new vendor release. The join command of cvs is a useful tool that aids this manual merge process (see below). + A vendor release or a local release can be given a sym- bolic tag name that is stored directly in the RCS files. This tag can be used at any time in the future to get an exact copy of any previous release. With equal ease, one can also extract an exact copy of the source files as of any arbitrary date in the past as well. + All changes that are made to the source repository are carefully logged in a file, notesfile, or news data- base, which can be used to produce release notices. cvs can be configured to send log updates through one or more filter programs, based on a regular expression match on the directory that is being changed. This allows multiple related or unrelated projects to exist within a single cvs source repository tree, with each different project sending their checkin reports to a unique log device for the project. + There is support for a simple, yet powerful, ``module'' database. This database can be used to apply names to collections of directories and files as a matter of convenience when checking out smaller pieces of a larger software distribution. This allows one to checkout the ``diff'' program, for example, without ever requiring the knowledge that the sources to ``diff'' actually reside in the ``bin/diff'' directory. The module database also has limited support for an aliasing capability. This is useful for programs that share sources from completely disjoint directories. The aliasing feature can also be used to limit a named release to a certain collection of directories and files, to only work with pieces of the source found in the entire source repository. + There is direct support for determining which files have changed since a previous release, or from a par- ticular date. As well, cvs can create a patch(l) for- mat output file which can be used to bring a previously released software distribution current with the newest release. One can create a patch file between two tagged revisions, between a revision and some date in the past, between two dates, or between a date or revi- sion and the current ``head'' revision. The remainder of this manual page will document how all these actions can be done using the cvs program. OPTIONS cvs accepts a number of options that override the current setting of the recognized environment variables. -r Checks out files read-only. Same effect as if the CVSREAD environment variable is set. -w Checks out files read-write (default). Overrides the setting of the CVSREAD environment variable. -v Outputs version and copyright information for cvs, then exits. -d CVS_root_directory Use CVS_root_directory as the root directory pathname of the master RCS source repository. Overrides the setting of the CVSROOT environment variable. -b bindir Use bindir as the directory to find RCS programs within. Overrides the setting of the RCSBIN environ- ment variable. -e editor Use editor for editing revision log information. Over- rides the setting of the EDITOR environment variable. -H Displays usage information about the specified cvs_command without actually executing said command. USAGE A cvs_command must be specified to cvs which drives the specific release control function that is performed. Each cvs command accepts options and arguments unique to the com- mand. The usage statements for each command can be displayed by specifying the -H option to the command. The available commands are listed below along with a description of their function. Command options unique to the command are described in this section with the command description. Common command options are described fully in the following section. checkout [-Qqlfnp] [-c] [-r tag|-D date_spec] modules... Checks out the source files defined by modules. This command is used to get a private copy of the current sources that can be edited and processed by most of the other cvs commands. checkout must be done before many of the other cvs commands are used, since most of them operate on checked out sources. Depending on the modules specified, checkout may recur- sively create directories and populate them with the appropriate source files. These source files can then be edited at any time (regardless of whether other software developers are editing their private copies of the sources), updated to include new changes checked into the source repository, or committed as a permanent change to the RCS repository. Note that checkout is used to create directories. The top-level directory created is always added to the working directory where checkout is invoked, and usu- ally has the same name as the specified module. In the case of a module alias, the created sub-directory may have a different name, but you can be sure that it will be a sub-directory, and that checkout will show the relative path leading to each file as it is extracted into your private work area, unless the -Q option is specified. Running checkout on a directory that was already built by checkout is also OK. This has the same effect as specifying the -d option to the update command described below. The -c option ``cat''s the module file, sorted, to the standard output, and does not cause any files or direc- tories to be checked out. co can be specified instead of checkout to save some typing. See the MODULES section below for a complete description of modules. update [-Qqlfp] [-d] [-r tag|-D date_spec] files... After checkout is run, directories and files have been extracted from the source repository for your personal editing. At any time that is convenient in your development process, the update command can be run from within the directory that contains the checked out sources to bring those sources current with any revi- sions that have been checked into the source repository since they were last checked out or updated. Normally, update brings the current directory up-to- date, then descends any sub-directories, bringing them up-to-date as well. This can be overridden by specify- ing a list of files that should only be updated, or by using the -l option which causes update to only process the current directory, ignoring any sub-directories. If any special options were initially specified to checkout when the source were initially checked out, these exact options should be specified to update as well to keep the sources consistent with the way they were originally checked out. For example, checking out sources by specifying the ``-r V1_0'' option will check out the revisions associated with the V1_0 release tag. A subsequent update that does not specify this exact -r option as well will revert to updating the sources with the current revisions as stored in the source reposi- tory, rather than those revisions associated with the V1_0 release. For a complete description of the algorithm that update uses to bring your source up-to-date, refer to the CON- FLICT RESOLUTION section below. commit [-fn] [-a] [-m 'log_message'] [- r revision] [files...] At any point, changes that you have made to your private copies of the sources may be committed to the source repository as a permanent change. commit does not do a recursive commit, so each individual directory must be checked in separately, even if the changes were related. commit verifies that the selected files are up-to-date with the current revisions in the source repository and will abort without committing if any of the specified files must be made current first with the update com- mand. With the -a option, all relevant files of the current directory are examined. commit is careful to only check in those files that have really changed. Note that commit does not update the out-of-date files for you, but rather leaves that for you to do when the time is right. An RCS identification string ($Id) must exist in the modified files that are to be checked in. If the iden- tification string cannot be found in any of the files, commit will prompt you for verification before proceed- ing. This prompt is bypassed if the -f option has been specified. When all is well, an editor is invoked for the purpose of entering a log message that will be written to one or more logging programs and placed in the RCS source repository file. The log message may be specified on the command line with the -m option, thus suppressing the editor invocation. ci can be specified instead of commit to save some typ- ing. diff [rcsdiff_options] [files...] Your checked out files can be diffed against the origi- nal revisions they were based upon with the diff com- mand. See rcsdiff(l) for a list of accepted options. If no files are specified, diff will only ``diff'' those files in the current directory that are different than the checked out revision (i.e. ones that you have changed), or that are different than a specified revi- sion. If files are specified, only those files are diffed. Two revisions may be specified as well. In which case your private sources are not diffed at all. Instead, the two revisions specified are diffed. log [rlog_options] [files...] To display revision log information equivalent to the rlog(l) program, the log command is used. See rlog(l) for a list of accepted options. If no files are speci- fied, log will run an rlog (with the arguments asa specified) on every file under cvs control in the current directory. If files are specified, the log information of only those files is displayed. status [files...] Displays three lines of information for each of its argument files, one for the user file (line 1), one for the newest RCS file showing the current ``head'' revi- sion number (line 3), and one for the RCS file both derive from showing the date it was last updated (line 2). add [-m 'message'] files... To permanently create a new file or directory in the RCS source repository, the add command is used. The files or directories specified to add must already exist in the current directory (which must have been created with the checkout command). For adding a whole new directory hierarchy to the source repository that was received from a third-party vendor, see the checkin(l) program for how to do this. If the argument refers to an immediate sub-directory, the directory is created at the correct place in the RCS source repository and the necessary cvs administra- tion files are created within the argument directory. It is not considered an error if the RCS source reposi- tory directory already exists. Thus, to add a direc- tory to your private sources that was created after you had done your checkout of the sources, you can do the following: example% mkdir new_directory example% cvs add new_directory example% cvs update new_directory For each added file, a description of the file's pur- pose is read from the terminal in RCS fashion, unless the -m option is specified, in which case the argument message is used instead. This description will become a permanent part of the created RCS file. The added files are not placed in the RCS source repo- sitory until they are committed as a permanent change. Doing an add on a file that has been removed with the remove command will resurrect the file, unless it has already been committed. remove files... Marks the specified files as removed on purpose from the current directory in the source repository. The specified files must no longer exist in the current directory when the remove command is issued. The files are not actually removed until they are committed, at which point their respective RCS files in the source depository are moved into the Attic directory within the source repository. To restore a committed removed file to the present version requires an administrator to physically move the RCS file out of the Attic and back into its parent directory. join [-Qqf] [-r tag|-D date_spec] files... The intended purpose of the join command is to perform the logical merge of a new vendor release installed with the checkin(l) command with locally modified files from a previous vendor release. The checkin program will inform you that a vendor file has been locally modified and it is up to you to resolve the two branches of development (local and vendor) into a uni- fied revision that will be committed as a permanent change to the source repository on the main (local) trunk. The join command will usually be used with the -r option to specify the vendor tag that is to be merged with the local changes. This merge is handled by RCS and the resultant file is placed in the current directory (within your private work space) and any con- flicts during the merge are displayed. After correcting any conflicts during the merge, commit the joined file as usual with a modified file, and the result (with a bit of work, perhaps) should be a working combination of the local changes and the vendor changes. The following commands do their work entirely within the RCS source repository and, as such, do not require that a checkout be done first. These commands are usually of interest only to the person responsible for the release pro- cedures of a software package. See the MODULE SUPPORT sec- tion below for a full description of what a module is. modules... patch [-Qqlf] [-s|-t] [-r tag|-D date_spec [-r tag|- D date_spec]] Builds a Larry Wall format patch(l) file between two releases that can be fed directly into the patch pro- gram to bring an old release up-to-date with the new release. The diff output is sent to the standard out- put device. Note that any combination of one or two revisions or dates may be specified. If only one revi- sion or date is specified, the patch is made between that revision or date and the current ``head'' revi- sions in the RCS file. Note that if the software release that is being patched is contained in more than one directory, then it may be necessary to specify the -p option to the patch(l) com- mand when patching the old sources, so that patch(l) is able to find the files that are located in other direc- tories. If the -s option is specified, a patch file is not pro- duced. Instead, a description of the changed or added files between the two releases is sent to the standard output device. This is useful for finding out, for example, which files have changed between two dates or revisions. If the -t option is specified, a diff of the top two revisions is sent to the standard output device. This is most useful for seeing what the last change to a file was. tag [-Qqlfn] [-d] [-r tag|- D date_spec] symbolic_tag modules... Sources in the repository can have a symbolic tag asso- ciated with them. This allows one to ``snapshot'' the current sources when the software freeze date of a pro- ject arrives, and as bugs are fixed after the freeze date, only those changed sources that are to be part of the release need be re-tagged. The symbolic tags are meant to permanently record which revisions of which files were used in creating a software distribution. The functionality provided with the checkout and update commands allow one to extract an exact copy of this release at any time in the future, regardless of whether files have been added or removed since the release was tagged. So in general, these symbolic names of software distributions should not be removed, but the -d option is provided as a means to remove completely obsolete symbolic names if necessary (as might be the case for an Alpha release, say). It is also possible to only tag files that already contain a certain tag. This method would be used to rename a tag - tag only the files with the old tag, then delete the old tag leaving the new tag which would tag the exact same files as the old tag. COMMAND OPTIONS The following options are common to more than one of the cvs commands, and are explained in detail here once, for brev- ity. -Q Causes the command to be really quiet. -q Causes the command to be somewhat quiet. -l Causes the command to not be recursive. Only the specified directory will be processed. -f Forces the specified tag to match. Normally, when a tag is specified with the -r option and the RCS file does not contain the tag, the ``head'' revision for the RCS file is returned. When the -f option is specified, any RCS file that does not contain the specified tag is ignored. This is useful for extracting an exact copy of a previously tagged release. -n Causes the command not to run any checkout/commit/tag program as specified in the modules database. -p On checkout or update, prune directories that are empty after being updated. This is useful for extracting an exact copy of a previously release, especially when combined with the -f option. -r tag Causes the command to use the revision specified by the tag argument instead of the usual ``head'' revision. The tag can be either a symbolic or numeric tag, in RCS fashion, except in the case of the commit command, in which case the tag must be a numeric one. Specifying the -q option along with the -r option is often useful, to suppress the warning messages when the RCS file does not contain the specified tag. -D date_spec Causes the command to use the revision that was checked in at or before the specified date_spec argument. The date_spec is a single argument, free form date descrip- tion specifying a date in the past. This option implies the -f option. See the EXAMPLES section for useful examples of how the -D option can be used. CONFLICT RESOLUTION The algorithm used by checkout and update is described in this section. The output generated, unless the -Q option is specified, consists of the following lines to describe exactly how your private sources are being brought up-to- date with the RCS source repository. U file The specified file was copied directly out of its respective RCS file from the source repository. This is done because the condition of your user file matches one of the following: + The user file did not exist in your private sources, whether it was because you removed it, or because someone added it to the source repository. + The file did exist, but you did not change it and a different revision was matched in the RCS file, be it by the default ``head'' match, or via the -r or -D options. M file The specified file has been modified locally by you. Use the diff command to see the actual changes that you have made. A file The specified file has been added to your private copy of the sources, and will be added to the RCS source repository when the file is committed. This is a rem- inder to you that the file needs to be committed. R file The specified file has been removed from your private copy of the sources, and will be removed from the RCS source repository when the file is committed. This is a reminder to you that the file needs to be committed. C files The specified file was modified locally by you, and while doing the update, it was determined that a later revision had been checked into the respective RCS file. As a result, cvs performs an rcsmerge(l), which com- bines the changes made to the RCS file with the changes that you have made to your version of the file. If there were any lines in conflict during the merge (i.e. the other developer changed the same line that you have changed), then the C is displayed to show that the file must be manually corrected. This merge process delimits the lines in conflict using lines beginning with ``>>>>>>>'' and ``<<<<<<<'', so it is easy to find the conflicts within your merged file. Note that your original, modified file is preserved in a backup file within the same directory that the file existed. The backup file has the form ``.#file.version'', where the version is the RCS revi- sion that your modified file was based upon. Note that some systems automatically purge files that begin with .# if they have not been accessed in roughly three days. Thus, if you intend to keep a copy of your ori- ginal file, I strongly suggest that it be renamed. If the merge process proceeded without any conflicts, an M is displayed instead of a C. It is still a wise idea to diff(1) the original version before the merge, contained in the backup file, with the merged version to verify that the merged changes make sense with your changes. MODULE SUPPORT The checkout, patch, and tag commands all accept module names as arguments. The module database is stored as an ndbm(3) format database within the CVSROOT.adm directory of your CVSROOT source repository. The remainder of this sec- tion considers how the checkout command operates on the modules database. The operations for the other commands that use the database are similar, except that they do not create any files or directories in your work space, as checkout does. The above commands search the module database for each module argument. If the module database does not exist, or if the argument does not have a matching key in the module database, the argument is processed as follows: 1. The value of the CVSROOT environment variable is prepended to the argument to form a full path name. 2. If the full path name does not exist, either as a directory or as a file with an RCS ,v extension, the argument module cannot be resolved and the command con- tinues, processing any remaining argument modules. 3. If the full path name refers to a directory, the direc- tories leading up to the directory are created, start- ing from the current working directory, and the direc- tory is populated with the correct files, ready for your editing satisfaction. If available, and the -l option was not specified, sub-directories are created and populated as well, until the entire directory hierarchy of the specified module argument is recon- structed in your work space. 4. If the full path name, combined with an RCS ,v suffix exists, only that file is extracted. The directories leading up to where the argument module resides are created, if necessary, and the leaf directory is popu- lated with the single source file. It should be clear from reading the above algorithm that the module database is not required to extract or process whole directory hierarchies, or even individual files. However, the addition of the module database allows a high degree of flexibility to be added to the structure or naming of pieces of software within the CVSROOT source hierarchy. The easi- est way to demonstrate the usefulness of the module database is by example. And so, one follows: # # Sample CVS Modules file # # Three different line formats are valid: # key -a aliases... # key [options] directory # key [options] directory files... # # Where "options" are composed of: # -i prog Run "prog" on checkin of files # -o prog Run "prog" on "checkout" of files # -t prog Run "prog" on tagging of files # # Convenient aliases world -a . # CVSROOT.adm support CVSROOT -i /usr/local/bin/mkmodules CVSROOT.adm CVSROOT.adm -i /usr/local/bin/mkmodules CVSROOT.adm modules -i /usr/local/bin/mkmodules CVSROOT.adm modules loginfo -i /usr/local/bin/mkmodules CVSROOT.adm loginfo # The "sys" entry exists only to make symbolic links after checkout sys -o sys/tools/make_links sys # Sub-directories of "bin" awk bin/awk csh bin/csh diff bin/diff make bin/make sed bin/sed sh bin/sh # Programs that live in "bin" cat bin Makefile cat.c chgrp bin Makefile chgrp.c chmod bin Makefile chmod.c cmp bin Makefile cmp.c cp bin Makefile cp.c date bin Makefile date.c dd bin Makefile dd.c The format of the modules file is also described in the above example. The -a option in the database indicates that the key is an alias, and that the right-hand side of the alias is to be interpreted by the command exactly as if it had been specified as arguments on the command line for the command. The -o option indicates that the specified program is to be run on checkout. The key for the entry is passed as the sole argument to the program. The -i option indi- cates that the specified program is to be run on commit. The full pathname of the respective source repository direc- tory is passed as the sole argument to the program. The -t option indicates that the specified program is to be run on tag. The key for the entry is passed as the sole argument to the program. As an example, the command example% cvs checkout awk will create the ``awk'' directory in your current working directory, if necessary, and populate it with the current revisions of the files in the ``$CVSROOT/bin/awk'' direc- tory. The command example% cvs checkout date will create the ``date'' directory and populate with exactly the two files ``Makefile'' and ``date.c'' from the ``$CVSROOT/bin/awk'' directory. VENDOR BRANCH SUPPORT The branch support of RCS is used to provide a convenient method of tracking the changes made to a vendor's source distribution. When a source distribution is received from a vendor, the first step is to run the checkin(l) program to place the vendor's files under CVS control. checkin(l) arranges that the RCS files produced from the vendor's source distribution are initially setup to track the 1.1.1 branch of the RCS file. When a commit is done to one of these files, making permanent some local change, the RCS file is changed to track the normal ``trunk'' branch, con- tinuing the local changes to the vendor's sources. When a new version of the vendor's source distribution is received, checkin is used again to add the new files to CVS. checkin again adds the files to the (now already existing) 1.1.1 branch of the RCS file. This time, however, checkin issues a warning when a new version of a locally modified file is updated by the vendor's source distribution. It is your responsibility to then use the join command of cvs to merge the vendor's changes with your local changes. See the description of the join command above. The -r and -D options of the checkout and update commands work ``as expected'' with the vendor branch support. In particular, the -D option to check out based on a date in the past follows the current default branch to find a match for the specified date. If a match cannot be found on the default branch, the 1.1.1 vendor branch is searched. This allows checking out based on a date to work regardless of when local changes are made to the file. LOGGING SUPPORT When committing a change to the source repository, a confi- gurable logging support file, loginfo, is consulted in the $CVSROOT/CVSROOT.adm directory. An example of the file is as follows: # The "loginfo" file is used to control where "cvs commit" # log information is sent. The first entry on a line is a # regular expression which is tested against the directory # that the change is being made to, relative to the # $CVSROOT. If a match is found, then the remainder of the # line is a filter program that should expect log information # on its standard input. # # The filter program may use one and only one % modifier (ala # printf). If %s is specified in the filter program, a brief # title is included (enclosed in single quotes) showing the # modified file names. # # If the repository name does not match any of the regular # expressions in this file, the "DEFAULT" line is used, if it # is specified. # DEFAULT /usr/local/bin/nfpipe -t %s utils.updates ^diag /usr/local/bin/nfpipe -t %s diag.updates ^local /usr/local/bin/nfpipe -t %s local.updates ^perf /usr/local/bin/nfpipe -t %s perf.updates ^sys /usr/local/bin/nfpipe -t %s kernel.updates In addition, ``ALL'' can be specified as a special regular expression which always matches, but does not change the behaviour of when the ``DEFAULT'' branch is taken. All matches for the regular expression are executed. This log- ging feature allows for multiple groups and logging programs to share a single CVS source repository. EXAMPLES Using the example modules and loginfo files shown above, this section shows some sample commands and describes their functions. example% cvs checkout csh example% cd csh example% make This command retrieves the current revision of the ``csh'' sources and places them within the ``csh'' directory. The ``make'' command within that directory will then build the ``csh'' executable. example% cvs checkout -rSunOS csh example% cd csh example% make These commands get the current SunOS revision of ``csh'' and builds the executable. example% cvs checkout date example% cd date example% make date These commands checkout the current revision of the ``date'' command, along with the Makefile that is required to build the ``date'' executable. The ``make'' command includes the target ``date'', since this Makefile is used to build much more than just ``date'' by default. example% cvs checkout -q sys Gets a copy of the current kernel sources, including the entire kernel directory hierarchy. The -q option suppresses the message displayed as each directory is descended. example% cvs checkout -p -q -f -rSunOS sys Gets an exact copy of the current revision SunOS kernel sources. The -f option forces only files that have the ``SunOS'' tag to be retrieved, not including files locally added to the kernel sources. The -p option prunes empty directories, thereby not including directories that have been locally added to the kernel source hierarchy. example% cvs checkout -p -D 'August 10, 1989 14:40' sys The exact copy of the kernel sources as of the specified date and time is retrieved. The date is a free-form strings, as specified in rcs(l). example% cvs diff -c example% cvs commit -a -m 'fixed NULL pointer dereference' The diff command displays a context diff of all the changes that you have made to the sources within the current direc- tory. Only those files thaty you have changed are displayed. The commit command makes these changes permanent within the source repository so that others can benefit from your fix. example% cvs diff -c -rSunOS file.c example% cvs diff -c -r1.9 -r1.11 file.c example% cvs diff -c -r1.22 file.c Examples of how the diff command can be used. The first example displays the differences between the SunOS version of the file and your checked out version. The second exam- ple shows the differences between two specific revisions of the RCS file. The final example diffs the currently checked out file against a specific revision of the RCS file. example% cvs tag PrismaOS1_0 csh example% cvs tag PrismaOS1_0 bin example% cvs tag test_kernel sys example% cvs tag -d test_kernel sys example% cvs tag -q -f -rSunOS SUNOS . example% cvs tag -D 'June 30, 1989' JUNE_KERNEL sys FILES CVS.adm A directory created by the checkout command within each directory that contains checked out source files. This directory holds all the cvs administration files for an individual's private copy of the sources. In general, these files should not be edited by hand. cvs will do that for you. Be sure to never remove this directory if you have source files that have been modified and need to be committed in the directory that the CVS.adm directory administrates. The files contained in this directory are described below. CVS.adm/Entries Contains the list of files that have been checked out in the current directory along with the revision number that each checked out file is up-to-date with and a timestamp that is used to quickly determine if a file has been possibly modified or not. CVS.adm/Entries.Backup A backup of the previous CVS.adm/Entries file, just in case of catastrophe. CVS.adm/Entries.Static The existence of this file tells cvs to only use the files contained in the CVS.adm/Entries file when gen- erating the list of source files for this directory. This allows selected files from a directory in the source repository to be checked out and manipulated without requiring that the entire source directory be used. CVS.adm/Mod After doing an update command, this file reflects the current list of modified source files for the direc- tory. CVS.adm/Repository Holds the pathname to the respective directory in the source repository that these files refer to. This is usually a relative pathname, with the value of the CVSROOT environment tacked on the front to produce a full pathname. If the pathname in the CVS.adm/Repository file is already a full pathname, the CVSROOT value is not tacked on. CVS.adm/Checkin.prog Contains one line which specifies the program that is to be run when any files in the current directory are checked in to the source repository with the commit command. The particular use of this is to rebuild the ``modules'' database after a new revision is checked in - see mkmodules(l). The following files or directories are created directly in the source repository directories as needed. CVSROOT.adm A directory that should exist in the top-most directory as defined by the CVSROOT environment variable. This directory contains administrations files that define the global actions for the entire source repository beginning at CVSROOT . The files used directly by cvs in this directory are described below, though you are free to add others as you see fit. CVSROOT.adm/modules,v The RCS file which defines the modules supported within this source repository. The format is as specified in the MODULE SUPPORT section above for more information. CVSROOT.adm/loginfo,v The RCS file that contains the descriptions of which programs to pipe log messages into when committing files. See the LOGGING SUPPORT section above for more information. Attic When RCS files are removed with the remove command, the actual RCS file is moved into the Attic directory where it will remain until someone uses the add command to restore it as a needed source file. #cvs.lock A lock directory created by cvs when doing sensitive changes to the RCS source repository. #cvs.tfl.pid A lock file created just to test the waters of the RCS source repository directory before committing files. #cvs.rfl.pid A read lock created when doing the update command. A commit done by some other user will wait until all readers have finished using the directory before proceeding. #cvs.wfl.pid A write lock created by commit to cause any other updates in the same source repository directory to block until the commit has completed. ENVIRONMENT VARIABLES CVSROOT Must be set for most commands. Should contain the full pathname to the root of the cvs source repository, that is, where the RCS files are kept. CVSREAD If this is set, checkout and update will try hard to make your private checked out sources read-only. When this is not set, the default behaviour is to make read-write files. RCSBIN Specifies the full pathname where to find RCS programs, such as co(l) and ci(l). If not set, the default is /usr/local/bin. EDITOR Specifies the editor to use when doing a commit. If not set, the default editor used is /usr/ucb/vi. AUTHORS Dick Grune Original author of the cvs shell script version posted to comp.sources.unix in the volume6 release of December, 1986. Credited with much of the cvs conflict resolution algorithms. Brian Berliner Coder and designer of the cvs program itself in April, 1989, based on the original work done by Dick. Jeff Polk Helped Brian with the design of the cvs module and ven- dor branch support and author of the checkin(l) shell script. SEE ALSO checkin(l), ci(l), co(l), diff(1), grep(1), mkmodules(l), ndbm(3), patch(l), rcs(l), rcsdiff(l), rcsmerge(l), rlog(l), rm(1), sort(1). BUGS