Department of Earth System Science zender@uci.edu
University of California Voice: (949) 824-2987
Irvine, CA  92697-3100 Fax: (949) 824-3256

Contents

1 General Points

This document describes the CVS commands I consider to be most useful in general, with working examples from a number of specific modules. After the generic commands in Section  2.2, the examples proceed in order of increasing complexity.

1.0.1 Abbreviations

The following abbreviations are used: CWD means the working copy of the CVS module in and beneath the Current Working Directory; mdl = module name; fl = file name; brnch = branch tag; vrs = version name (which can be a branch tag).

1.0.2 CVS Keywords

Only “cvs commit”, “cvs tag”, and “cvs rtag” change the repository. All other CVS commands change, if anything, the contents of the CWD only, and so are recoverable. CVS commands should be executed from the top level of the CWD. In this case, the module name mdl may be optional at the end of the command (because CVS finds the module name by looking in the “CVS” subdirectory mdl/CVS). Executing CVS commands from one level above the module requires specification of the module name so that CVS knows where to find mdl/CVS.

In addition to the usual RCS keywords (Header, Date, …), CVS defines the keyword Name. The string “$Name$” expands to include the tag specified when the module was checked out, e.g., “cvs co -r ccm3_5_22 ccm” produces “$Name:ccm3_5_22 $” but “cvs co ccm” produces “$Name:$” for two reasons. First, no tag was specified with the checkout so the default ccm module, i.e., the main trunk, is retrieved. The main trunk has no default tag name, so the keyword value is an empty string. Second, checking out the main trunk never expands “$Name$”, but checking out a branch, any branch, does. Branch tags are sticky, so a branch always has an associated tag name. The rest of the RCS keywords expand to their usual meanings regardless of whether the module is a tagged version or branch. To explicitly turn off CVS keyword expansion when checking out a module (recommended to avoid unnecessary conflicts due to CVS metadata changes), use the “-kk” option instead of the default, “-kkv”. The -k options are sticky, meaning they apply to any derived files as well.

1.0.3 CVS Errors

Occasionally CVS does not perform as expected. Two errors are particularly frequent, and easy to fix. The first is that, when asked to commit files to the repository, CVS complains that some subset of the files is out-of-date, and asks you to fix this before it proceeds. This is, in fact, not an error, but very helpful behavior by CVS telling you that somehow your working directory is out of date with respect to the repository. Some versions of CVS will commit those files that are modified but not commit those that are out of date. Other versions of CVS will not commit any file until all files in the CWD are current. In this case, simply perform a “cvs update” before attempting to “cvs commit” again. This should solve the problem.

The second error occurs when CVS attempts to modify the repository, e.g., during a “cvs commit” operation, and it complains that it has never heard of any of the files, e.g., “cvsbin commit: nothing known about ‘to’”. If this occurs on the CGD Sun network, it might be because you have used simply cvs rather than cvsbin as the CVS command. Check this and try your command again.

1.0.4 CVS Debugging

When attempting to solve problems with CVS, try using the “-t” switch so CVS will trace its execution.

1.0.5 CVS Environment Variables

CVS makes use of several environment variables.

1.0.6 CVS Administration

In order to execute the cvs admin command, the user must be a member of the cvsadmin group, if it exists.

It took five years since I began using CVS in 1998 before I needed to learn how to use CVS administrative commands to repair repositories. On July 30, 2003 the laptop I was using ran out of power and somehow wrote binary garbage into every file that emacs was visiting. I only lost a few hours of work, and it seemed like time to backup everything I was working on. That made things a little worse because I incidentally committed the binary garbage to CVS. How did I remove the binary garbage from the repository?

2 Modules

To create a CVS repository, use

The following subsections present specific examples for both generic and CGD-related modules. Many of the same examples are used for different modules, so that the examples might differ only in the name of the target module, and sometimes not at all (e.g., “cvs co”). The goal has been to keep the examples self-contained for each module, at the expense of document length and redundancy. The examples are drawn from modules in active use in CGD. Table  1 summarizes the three repositories used in the examples.

Most of the examples do not explicitly specify the repository (with the -d argument). This is because most commands are executed within, rather than above, the CWD. Table  1 should be consulted when the repository to use is in doubt.

2.1 CVS Server Issues

A precise discussion of setting up a CVS server is given at http://www.korayguclu.de/index.php?&file=linux.cvs.pserver.xml. The CVS documentation describes the necessary modifications to the internet daemon configuration file /etc/inetd.conf. RedHat Linux uses a more powerful and complex (some call this sophisticated) daemon, xinetd (pronounced “zy-net-d”), configured in /etc/xinetd.conf. On RedHat systems, CVS password server services are controlled by a file called cvspserver located in /etc/xinetd.Dachau’s.

The CVS documentation specifies how to configure the port number (2401), socket_type, and server_args flags. Internet daemon services (i.e., inetd or xinetd) should be started automatically, in, say, system runlevel 3.

2.1.1 Read-only Access

Place the readers, writers, and passwd file in the directory $CVSROOT/CVSROOT.

Add the user cvspub to the system. Do not give the user a home directory or interactive access.

Once read-only services work, outside users may check out modules by logging in as the anonymous user.

2.2 Generic Modules

2.2.1 Import an existing directory

Import files in directory mdl to create new CVS module mdl. The keywords “zender” (vendor tag) and “mdl-0_1” (release tag) are used for initial module tags.

2.2.2 Import RCS files

Edit the CVS repository to create the appropriate source directories. Make sure all RCS files are unlocked, then copy them into the CVS repository.

2.2.3 Checkout

Checkout module mdl. A -d argument before the verb specifies the CVS repository to use (instead of $CVSROOT). By default, a module mdl is placed in the mdl directory of the CWD. A -d argument after the verb specifies an arbitrary directory for the module. The -kk option suppresses RCS keyword expansion (e.g., of “$Header:: $”), thereby minimizing the number of conflicts during a future cvs update. Note that co is a synonym for checkout—the two are interchangeable.

2.2.4 Add

Schedule file fl for addition to the repository. Actual addition takes effect with the next “cvs commit” command.
cvs add fl

2.2.5 Remove

Schedule file fl for removal from the repository. Actual removal takes effect with the next “cvs commit” command.
cvs remove fl

2.2.6 Query

Show changes of CWD relative to repository. Option -n specifies that no changes to the repository will occur.
cvs -n update

2.2.7 Diff

Show changes relative to particular versions, tags, or times.

2.2.8 Commit

Commit changes beneath CWD. The commit verb accepts optional filename arguments for file-by-file (rather than entire module) commits.

2.2.9 Tag

Tag CWD with mdl-1_0. Option -c causes tag to verify that files beneath CWD are not modified relative to the repository. This ensures the repository has all the information needed to exactly reproduce the CWD from the tag name in the future (with, e.g., “cvs co -r mdl1_0 mdl”.

2.2.10 Rtag

“Repository” tag (rtag) the module with tag_nm. Verb rtag, as opposed to tag, operates on the repository, not the CWD. Does this only tag those portions of the repository in and beneath the CWD? (fxm). By default, rtag tags the most recent version of the module. This can be overridden with -D date option. Use (rtag) with caution on branches, because it will update the main repository as well (fxm).
cvs rtag tag_nm

2.2.11 Release

Release module mdl and delete its working directories. CVS prompts the user whether to actually delete the directory:
cvs release -d mdl # From level above CWD

2.2.12 Update

Update the CWD for mdl so that it reflects the latest version of the repository. One, and only one, -j option, “-j vrs”, updates the CWD of mdl to the latest revision of the ancestor of vrs. The ancestor is the model from which the vrs branch split. Given two -j options, “-j vrs1 -j vrs2”, the update command takes the differences (uses diff) between version vrs1 and version vrs2 and applies them (uses patch) to the CWD. The -kk option suppresses RCS keyword expansion, thereby minimizing the number of conflicts during an update. For this reason, it is wise to use cvs co -kk mdl before using cvs update.

2.3 C++ Module

The C++ module c++ was imported using “cvs import -m "Imported sources" c++ zender c++-1_0”.

2.3.1 Checkout

Checkout the latest version of the C++ module.

2.3.2 Commit

Commit C++ CWD to remote repository. One of the nicest feature about CVS is that it knows about remote repositories, so commands like commit and update need no extra arguments.

2.4 NCO Module

The NCO module nco was imported using “cvs import -m "Imported sources" nco zender nco-1_0”.

2.4.1 Checkout

Checkout the latest version of the NCO module.

2.4.2 Update

Update a remote module (i.e., at home) to the current NCAR NCO repository.

2.5 CRM Module

The CRM module crm was created as a branch of CCM version 3.5.22. First, we defined module crm by editing the /fs/cgd/csm/models/CVS.REPOS/CVSROOT/modules file to contain the following lines:

Finally, we executed the following commands to create the CRM branch of the CCM:

Note that we used tag rather than rtag in the above because only tag allows one to tag a specified subset of the files in a given module. In this case, the desired subset was the CCM files which are also required by the CRM, but no others (this excluded superfluous files, e.g., vdiff.F). All work on the CRM module is actually performed on this ccm_brnch_crm branch of the CRM, rather than the CRM main trunk This methodology, i.e., working on the branch rather than the main trunk, is also used for the Dust module component of CCM, MATCH, and MOZART described in Sections  2.6, 2.7, and 2.8 respectively.

2.5.1 Create Distribution

Release a new CRM. This process uses many CVS commands. First, make sure the crm module in the repository is up-to-date, so that the CWD can be exactly reproduced. Second, release the module. Third, check out the CRM with the -kk option. Fourth, difference the CWD with the most recent branch tag. This difference file shows the differences between the releases. Do these differences make sense? Fifth, tag the module. Sixth, execute the distribution script.

2.5.2 Update to newer CCM version

Update the CWD to a newer CCM version. This process uses many CVS commands. First, checkout a clean copy of the CRM branch into the CWD. Second, difference the pre-merged CRM from its current CCM base. This difference file shows all the CRM-specific modifications to the current CCM base code. Third, update the CWD to the desired CCM version. Given two -j options, (“-j ccm3_5_22 -j ccm3_6_0”), the update command takes the differences (uses diff) from CCM version ccm3_5_22 to CCM version ccm3_6_0 and applies them (uses patch) to the CWD. Fourth, examine and fix the conflicts caused by this merge. Use, e.g., “cvs status” to locate conflicts. Make sure to compile, test, and generate new *.out files for the updated model. This ensures that any new source files will be included in Srcfiles and Depends. Also, it is important to compile with “-DSINGLE_SOURCE_FILE” option. This verifies that any new files merged into, and needed by, the CRM are accounted for. Unfortunately, there is no simple way to ensure that superfluous source files have not crept into the CRM. Fifth, difference the post-merged CRM from the new CCM base. This difference file shows all the CRM-specific modifications to the new CCM base code. Sixth, difference the two difference files. This file highlights conflicts caused by the merge process and, hopefully, any mistakes CVS made in performing the update. Seventh, commit the updated code to the head of the branch. Eighth, if desired, tag the branch as a new release of CRM.

2.5.3 Checkout

Checkout the latest version of the CRM. By default, the crm module is placed in the crm directory of the CWD. A -d argument after the verb specifies an arbitrary directory.

2.5.4 Export

Export the latest version of the module crm from CCM branch ccm_brnch_crm into directory /data/zender/crm-1.1 and prepare a compressed tarfile distribution. The export command strips all the CVS directories from the output. This is most useful for creating distributions for public release. Using -kkv instead of -kv would expand CVS keywords into keywords plus values.

2.5.5 Tag

Tag CWD with ccm3_6_brnchT_crm2_0. Option -c causes tag to verify that files beneath CWD are not modified relative to the repository. This ensures the repository has all the information needed to exactly reproduce the CWD from the tag name in the future. Note it is wise to tag only modules which have been checked out with the -kk option. This prevents large numbers of trivial differences between tagged versions.
cvs tag -c ccm3_6_brnchT_crm2_0

2.5.6 Remote Checkout

Checkout the latest version of the CRM from home. The first -d option specifies the remote repository. The second -d option specifies the name of the directory to place the module in. The final argument, crm, is the name of the module to checkout. For unknown reasons this command erroneously places the src directories one level too high in most cases. This is apparently a CVS bug fixed in later versions of CVS.

Here is a workaround for the above problem:

2.6 CCM-Dust Module

The module ccm_dst comprises the sub-modules ccm and dst. Thus ccm_dst is the complete CCM with the dust modifications. Code modifications related to dust appear in the usual files in src (e.g., file physics/aphys.F). Most of the dust physics are isolated in the new directory src/dust. The branch ccm_brnch_dst was created as a branch of CCM version 3.5.22. First, we defined module ccm_dst by editing the /fs/cgd/csm/models/CVS.REPOS/CVSROOT/modules file to contain the following lines:

Finally, we executed the following commands to create the Dust branch of the CCM:

2.6.1 Checkout

Checkout the latest version of the CCM-Dust module. A -d argument after the verb specifies an arbitrary directory for the module.

2.6.2 Query

Show which files in CWD have changed relative to the most recent committed version in the Dust repository. Then show precisely what has changed for file dstmbl.F.

The result of cvs -n update is a list of files which differ from the repository. Each file is prefixed by a code. The most common codes are C (for conflicts), M (local modifications newer than repository), and U (local file needs updating). Conflicts

The precise differences relative to the repository are shown with

Show which files in CWD have changed relative to version mdl-1_0 in the CCM repository. Then show precisely what has changed for file Makefile.

2.6.3 Release

Release the current Dust module and check out a new working copy.

2.6.4 Tag

Note that tagging in the CCM repository invokes error checking modules and, by default, launches windows which request one line summaries on the local machine. Attempting to tag from behind a firewall or proxy can thus result in failure because the windows are unable to open on the requested console. In this case, the tagging must be done from goldhill.cgd.ucar.edu, and the user’s DISPLAY must be set to NONE

This problem does not arise when tagging from an unfiltered IP address.

Tag CWD with ccm3_6_brnchT_dst1_2. Option -c causes tag to verify that files beneath CWD are not modified relative to the repository. This ensures the repository has all the information needed to exactly reproduce the CWD from the tag name in the future.

2.6.5 Update

Update the CWD to a newer CCM version.

2.7 MATCH-Dust Module

The module match_dst comprises the sub-modules match and dst. Thus match_dst is the complete MATCH with the dust modifications. Code modifications related to dust appear in the usual files in src (e.g., file physlic.F). Most of the dust physics are isolated in new files in the dst directory, e.g., dstmbl.F. The branch match_dst-0 was created as a branch of MATCH Spitfire version 3.2.9. First, we defined module match_dst by editing the /fs/cgd/csm/people/eaton/CVS/CVSROOT/modules file to contain the following lines:

The dust source directory in the MATCH repository is actually a symbolic link to the dust source in the CSM repository:

Next, we added a MATCH tag to the CCM branch of the Dust module.

This enabled us to check out both MATCH and Dust at the same time in preparation for the next step, creating the MATCH-Dust branch. Note that in order to apply MATCH tags to files in the CCM repository, we had to disconnect the CCM-Dust module from the default CCM tag syntax checking routines. Finally, we created and tagged the MATCH-Dust branch.

In the preceding command, MATCH_SPITFIRE-3_2_9 is the pre-existing tag associated with all files that were placed in the new match_brnch_dst branch of the match_dst module. Originally, we left the MATCH_SPITFIRE-3_2_9 tag on the files in the dst directory, but this caused problems when merging changes to the main trunk of the MATCH into MATCH-Dust. The tag caused CVS to think that the Dust-specific files were parts of MATCH_SPITFIRE-3_2_9, and thus CVS tried to remove them when updating to a later version on the main trunk. Thus, we later removed the MATCH_SPITFIRE-3_2_9 tag from all the files in the dst directory.

2.7.1 Changes to standard MATCH repository

Once these commands were completed, we slightly altered the architecture of the MATCH-Dust repository to facilitate CCM-style compiling methods (i.e., compile from list of directories rather than list of individual files plus directories). match_brnch_dst was created from the MATCH 3.2 repository, and these commands were used to modify the standard MATCH repository:

To create a dust branch from the standard MATCH 4.X repository, the following changes to the standard directory structure would be required:

2.7.2 Checkout

Checkout the latest version of the MATCH-Dust module. A -d argument after the verb specifies an arbitrary directory for the module.

2.7.3 Tag

Tag CWD with match-3_2_10-dst-1_3. Option -c causes tag to verify that files beneath CWD are not modified relative to the repository. This ensures the repository has all the information needed to exactly reproduce the CWD from the tag name in the future. Be sure this version compiles before tagging it.

2.7.4 Merge CCM changes into CCM-Dust

Merge changes to main CCM trunk into the CCM-Dust branch. Merging main trunk changes into CCM-Dust should never change the dst directory itself, but should alter the contents of src/physics, src/control, etc. This example merges the changes from CCM version ccm3_6 to CCM version ccm3_6_6 into CCM-Dust version ccm3_6_brnchT_dst-0_9_6, which is then tagged as ccm3_6_6_brnchT_dst-0_9_6.

2.7.5 Merge MATCH changes into MATCH-Dust

Merge changes to main MATCH trunk into the MATCH-Dust branch. Merging main trunk changes into MATCH-Dust should never change the dst directory itself, but should alter the contents of src, readers, etc. This example merges the changes from MATCH version match3_2_10_scyc1_0 to MATCH version match3_3_20 into MATCH-Dust version match-3_2_10-dst-1_4a, which is then tagged as match-3_3_20-dst-1_4a.

2.7.6 Merge MATCH-Dust changes into CCM-Dust

Merge changes to the MATCH-Dust branch into the CCM-Dust branch. A simple “cvs update” does not work because the changes are on different branches. This example merges the changes from MATCH-Dust version match-3_2_9-dst-1_2 to MATCH-Dust version match-3_2_10-dst-1_4 into CCM-Dust version ccm3_6_brnchT_dst1_2, which is then tagged as ccm3_6_brnchT_dst1_4.

2.7.7 Merge CCM-Dust changes into MATCH-Dust

Merge changes to the CCM-Dust branch into the MATCH-Dust branch. A simple “cvs update” does not work because the changes are on different branches. This example merges the changes from CCM-Dust version match-3_2_9-dst-1_0 to CCM-Dust version ccm3_6_brnchT_dst1_2 into MATCH-Dust version match-3_2_9-dst-1_0, which should then be tagged as match-3_2_9-dst-1_2.

2.8 MOZART-Dust Module

The module mozart_dst comprises the sub-modules mozart and dst. Thus mozart_dst is the complete MOZART with the dust modifications. The MOZART Dust implementation was created well after MATCH-Dust, and uses most of the same directory structure. Thus, the CVS commands for manipulating the MOZART-Dust model are directly analogous to those described in Section  2.7, with the following exceptions.

2.8.1 Field names

By default, MOZART archives both instantaneous values of constituents mixing ratios. These are given the names assigned in the code, e.g., DSTQ01. MOZART can also be told to archive time-averaged values of these constituent fields. Time-averaged constituent fields are assigned names based on there constituent index in the model, e.g., TRA01.