Guide to CVS for FMS Users and Developers
This document provides a brief description of CVS and some specifics on how it
is implemented for FMS. For more details on CVS, see the
CVS homepage, which contains
a CVS Manual.
The online slides from Amy Langenhorst's
lunchtime seminar
also serve as a CVS tutorial. There are graphical user interfaces (tkcvs,
tkdiff) available
for browsing local code, as well as a
web interface
to the repository. Note that these interfaces are only available for users internal
to GFDL.
CVS (Concurrent Versions System) is a version control system. It maintains all files
as history files, whereby the complete history of all files is recorded. These files
exist in a directory tree called a repository. The root of the CVS repository for
FMS is /home/fms/cvs. fms is a user on the GFDL computer system, and this user id
is assigned to one or more people who act as super-users of the FMS repository.
To extract files from the repository it is necessary to specify both a grouping
of files and the particular historical revisions of each file. This is done with
the use of CVS modules, tags and branches.
CVS Modules:
A CVS module (not to be confused with FORTRAN modules) is a grouping of history files. Although files can be extracted individually, it is usually done by specifying a CVS module. A number of modules have been defined for FMS. The module definitions are maintained by the FMS super-user and are periodically updated. For the FMS we use modules to group files needed for various modeling efforts, as well as to group subsets of such files. A description of the FMS module definitions can be found on the Module Descriptions page.
CVS Tags:
A CVS tag is a text label associated with one version of a file of source code. Although the version of each history file can be specified on a file by file basis via a revision number, it is normally done by specifying a revision tag or a branch tag. A revision tag can only be associated with one version of a file, while a branch tag indicates the newest version of the file on that branch, which may change over time (see below). A single tag can be placed on a particular revision of each history file of a module so as to define a compatible set of revisions. For FMS, we use tags to define successive releases of source code and code documentation. Note that the words "version" and "revision" may be used interchangeably in the context of CVS.
CVS Branches:
Branches are lines of development that diverge from the primary line of development. Each branch is associated with a branch tag. By specifying a branch tag, one will obtain the latest revision of each file associated with that line of development. Note that the result of obtaining code via a branch tag may change over time as the developer checks in new versions of a file. For FMS, developers normally create their own branches off of the most recent release. If a developers code is accepted the FMS super-user will create new revisions on the main line of development which are equivalent to those of the developers branch.
If you are not an FMS developer, please skip to the General Formatting of CVS Commands section.
Branch Creation Summary For FMS Developers
The FMS developers have been assigned a UNIX group (the "f" group) in order to work with the CVS repository. If you have a GFDL account and wish to join the "f" group, please send a request to the FMS super-user or fms@gfdl.noaa.gov .
When checking in new versions to the repository, remember that it is important to start from the right version. For example, if you have modified galway code, you should start with a cvs-controlled directory where galway code is checked out (not fez code or havana code.) Also remember that if you want your code included in a future release, you should start with the latest version if possible. See the FMS "latest" webpage for more details.
Using cvs status -v filename before and after each command below will inform you what cvs is doing in each command below, and will help you notice if something is going wrong. Click on the individual cvs commands below for more details on the specific commands.
To check in modified files on a new branch: |
|
setenv CVSROOT /home/fms/cvs cvs tag -b tagname_$user files cvs update -r tagname_$user files cvs ci files |
|
To check in modified files on your existing branch: |
|
cvs status files #verify status=locally modified #and sticky tag=your branch cvs ci files |
|
To add new files to the repository on a branch: |
|
newgrp f setenv CVSROOT /home/fms/cvs cvs co directory-name cvs tag -b tagname_$user directory-name cvs update -r tagname_$user directory-name #copy in the new files cvs add directory-name/new-files cvs ci directory-name/new-files |
|
To remove a file from the repository on a branch: |
|
setenv CVSROOT /home/fms/cvs |
|
General Information and Formatting of CVS Commands:
setenv CVSROOT /home/fms/cvs |
Setting this environment variable tells CVS the location of the repository.
You should set this before you issue any CVS commands. If the FMS repository
is the only repository you regularly use, you may wish to put this line
in your .cshrc.
|
cvs -H [command] |
Use the -H option for help with any CVS command. For example, "cvs -H
checkout" will print a help message for "cvs checkout".
|
cvs [command] [file or directory] |
This is the general format of cvs commands. For the checkout command,
the directory or file paths specified must be relative to CVSROOT. For
commands other than checkout, the directory or file paths specified
must be relative to the current working directory.
|
Commands which do not modify the repository:
Checkout Command:cvs checkout -r (tag, branch, or revision number) (module, directory, or file) |
|
Example: cvs co -r damascus fms_bgrid_am2
Checkout the damascus revisions of all files comprising the AM2 module.
You may use "co" as an alias for "checkout".
|
|
Description:
Checks out (extracts) a particular revision of all files comprising
a module, or recursively checkout files in the repository starting at
"directory", or checkout a single file. If checkout is done by specifying
a directory then the path specified must be relative to CVSROOT. Note
that "cvs co" is equivalent to "cvs checkout". Be careful if you check
out with a revision number, because CVS makes the revision number the
working tag (or "sticky tag") for the file, so CVS will have no way
to know if any new revisions have been checked into the repository on
the tag or branch you had been working with previously. In this case,
CVS will always tell you the file is up to date when a "cvs status"
command is issued.
|
FMS Considerations:
Two files, path_names and path_names.html are created when files are
checked out of the FMS repository. The first contains a listing of relative
path names to all the checked out source code files. The second is an
html file containing links to all the documentation files that have
been checked out. path_names is often used in combination with the make
file utility mkmf.
|
Update Command:cvs update -r (tag, branch, or revision number) (directory or file) |
|
Example: cvs update -r damascus_bugfixes
`/home/fms/bin/list_files_with_tag damascus_bugfixes`
Update only those files that have the tag "damascus_bugfixes", preserving
the working copies of those files that do not.
|
|
Description:
Replaces or merges working files with the specified revisions, but does
so without destroying modifications to working files. A critical feature
of CVS is that it will never modifications that have not been checked
in.
This command can easily have unintended results when used by those who are not familiar with it. To avoid this one must understand how it functions in these three scenarios.
|
FMS Considerations:
When update results in new files being checked out, the paths to those
files will be added to path_names and/or path_names.html. See
checkout.
The utility /home/fms/bin/list_files_with_tag can be used with update to prevent the removal of files that do not have the specified tag or branch. |
Diff Command:cvs diff (directory or file) |
|
Example: cvs diff strat_cloud.f90
Show updates made to the working copy of strat_cloud.f90 since it was
checked out.
cvs diff -kb -rbombay strat_cloud.f90
Show differences between the working copy of strat_cloud.f90 and the
bombay revision. The "-kb" argument tells cvs to ignore the differences
in the keywords, such as $Id: cvsguide.html,v 1.1 2004/02/04 22:20:04
fms Exp $.
cvs diff -rdamascus -rdamascus_bugfixes atmos_coupled.f90
Show the updates made to atmos_coupled.f90 to correct a damascus bug.
When given two revisions, the differences between the two revisions
are calculated. In this case the state of the working copy is irrelevant.
|
|
Description:
Shows differences between the working copy of a file and the revision
indicated by the sticky tag. This is useful to remind yourself of what
updates you have made since checking out a file. The default form of
the output is that of the unix diff command. Graphical diff utilities
available for use with FMS include
tkdiff
and the diff available from the
web
CVS interface. Tkdiff accepts the same arguments as cvs diff; simply
substitute "tkdiff" for "cvs diff".
|
FMS Considerations:
|
Commands which modify the repository:
Tag Command:cvs tag [-b] (branch name) (directory or file) |
|
Example: cvs tag -b maroon_sak atmos_param/strat_cloud
Create a branch called "maroon_sak" off of the currently checked out
revisions for every file in the directory "atmos_param/strat_cloud".
cvs tag maroon_sak atmos_param/strat_cloud/strat_cloud.f90
Create a revision tag called "maroon_sak" on the currently checked out
revision of atmos_param/strat_cloud/strat_cloud.f90.
|
|
Description:
Creates a branch for one or more files. The branch will be off the revision
indicated by the sticky tag.
Note that the tag command only adds the tag to the list of valid tags
for the file; it does not indicate to CVS that your local code should
be on that tag or branch. You must explicitly use
cvs update
to move your code to the new tag or branch.
|
FMS Considerations:
For files in the FMS repository, branch names must contains the string
"_$user", where $user is the user's id. For example, Steve Klein's user
id is sak. He can create a branch called "maroon_sak", but not "maroon".
Users are only allowed to check in to branches containing their id.
|
Commit Command:cvs commit (directory or file) |
|
Example: cvs ci strat_cloud.f90
Check in a new revision of strat_cloud.f90. You may abbreviate "commit"
as "ci", which stands for "Check In".
|
|
Description:
Checks new modifications of files into the repository. The Sticky Tag
determines to which branch the file(s) will be checked into. If the
Sticky Tag is not the desired branch then
cvs update
must be executed to put the file on the desired branch prior to commit.
|
FMS Considerations:
Files must be checked into a branch. The branch name must contain the
string _$user (see
tag -b).
Checking in files will invoke a script that brings up a log message
template (in the vi editor). Although it is not enforced that the user
enter a log message, it is stongly suggested.
|
Add Command:cvs add (directory or file) |
|
Example: cvs add mpp_update_domains2D.h
Put mpp_update_domains2D.h under CVS control. To be followed by: "cvs
ci mpp_update_domains2D.h".
|
|
Description:
Put a new file under CVS control that was not previously in the repository.
This command does not immediately add the new file to the repository;
it must be followed up with
cvs ci.
|
FMS Considerations:
|
Remove Command:cvs remove (directory or file) |
|
Example: rm mpp_update_domains2D.h
cvs remove mpp_update_domains2D.h
Removes mpp_update_domains2D.h from the head of the CVS trunk or branch.
Old versions will still be accessible with the appropriate tags. To
be followed by: "cvs
ci mpp_update_domains2D.h".
|
|
Description:
Remove a file from the head of the CVS trunk or branch. The file will
not be completely erased from the repository, as old versions will still
be accessible with the appropriate tags. You must first do a unix remove
of the file in your working directory. This command does not immediately
remove the file from the repository; it must be followed up with
cvs ci.
|
FMS Considerations:
|
Detailed Branch Example
The main line of development is called the trunk, and its revision numbers take the form: 1.N Branches have more than 3 digits.
strat_cloud.f90 antwerp bombay calgary 1.1 ------> 1.2 --------------------------------------------------------------------> 1.3 | | +--maroon_sak--> 1.2.2.1--> 1.2.2.2--> 1.2.2.3--> 1.2.2.4--> 1.2.2.5--> 1.2.2.6 strat_cloud.doc.html bombay antwerp calgary 1.1 ----------> 1.2 strat_cloud.tech.ps antwerp bombay calgary 1.1 ------------------------> 1.2 | | +--maroon_sak--> 1.1.4.1 --> 1.1.4.2
- He first checks out the bombay release of a CVS module that includes
strat_cloud.f90, and goes to that directory:
cvs co -r bombay fms_bgrid_amip cd atmos_param/strat_cloud
- There he edits the files until he has an acceptable new versions which he wants to check in on a branch. Before checking them in, he must verify with the FMS super-user that permissions in the repository will allow him to check the files in.
- To check the files into the repository, he creates a branch for all
three files in this directory:
cvs tag -b maroon_sak
Executing cvs commands like "tag" without listing specific files tags all the files in the current directory. He could have created a branch on a subset of files by explicity listing them as arguments to the tag command, as in "cvs tag -b maroon_sak strat_cloud.f90". - Prior to checking in any revisions on this branch, the "Sticky Tag"
on these files must changed to the branch name. This is done with the update
command:
cvs update -r maroon_sak
Again, a subset of files may be listed. - He checks the code into the repository on the branch:
cvs ci strat_cloud.f90
This command invokes an editor which brings up a log message template. After entering information on this template, he quits the editor and his working copy is checked in as the first revision on his branch. - He repeats this process, checking in working revisions as desired, until he arrives at what he believes to be a useful enhancement of strat_cloud.f90. Because he has modified the source code, he reviews his documentation files. He finds that strat_cloud.ps needs updating but strat_cloud.doc.html does not. He works on strat_cloud.ps, checking in one intermediate revision.
- Prior to the calgary release, he notifies the FMS super-user that he wants his branched files included in the release. His modifications are reviewed by the super_user for adherance to FSM specifications. If no further modifications are needed then the super-user checks in new revisions on the main line of development that are equivalent to those at the head of the maroon_sak branch, and puts the calgary tag on them.
CVS Related Utilities
tkdiff: |
|
GUI interface to CVS diff that can be used to examine differences among
revisions and your working copy graphically.
|
alias tkdiff "/home/fms/bin/tkdiff" tkdiff [-r tag1] [-r tag2] [file]
Tkdiff accepts the same arguments as
cvs diff.
For more information, see the tkdiff
homepage.
|
tkcvs: |
|
GUI interface to CVS. The graphical interface to viewing the revision
tree is especially useful; use "tkcvs -log file" to enter this mode.
|
alias tkcvs "/home/fms/bin/tkcvs" tkcvs tkcvs -log file
For more information, see the
tkcvs homepage.
|
Web CVS: |
|
Web Interface to the FMS repository.
|
http://cobweb.gfdl.noaa.gov/fms-cgi-bin/cvsweb.cgi/FMS/
For more information, see the
cvsweb homepage.
|
list_files_with_tag: |
|
List all files in a source tree that can be checked out with a given
tag name.
|
set files = `home/fms/bin/list_files_with_tag [tag]` echo $files #look at the list of files cvs update -r [tag] $files
This allows cvs to update only those files that have revisions with
the given tag.
|
list_paths: |
|
|
Typically called from the directory containing source code
via:
/home/fms/bin/list_paths *
This will create two files:
|