Essential CVS/Appendixes/Administrator's Tools
(Initial conversion from Docbook)
(Initial conversion from Docbook)
Revision as of 12:36, 7 March 2008
CVS is an open source program, and all the information necessary to interface to it or change it is freely available. It is also a very popular system. The combination of these two factors means that a wide variety of programs and tools have been written for CVS.
The tools in this appendix range from a port of CVS to the Windows NT operating system, to a small tool to mail log messages automatically. Other programs include several different viewers to display the contents of the repository with an HTTP server and a useful program that implements access-control lists.
The CVS license allows you to modify the CVS code and distribute the modified code. Several variants are provided by developers who have produced expansions of CVS for specific purposes.
CVS/MVS is a port of CVS for the MVS (Multiple Virtual Storage) mainframe operating system, also known as OS/390 and zOS. CVS/MVS requires MVS with POSIX configured, and the HFS (Heirarchical File System).
CVS/MVS is a port of both the server and the command-line client.
CVS/MVS is available at http://cvsmvs.dccmn.com/.
CVSNT is an alternative CVS server for Windows NT and later, Unix, and Linux. It includes a command-line client as well as the server, and the client can be used with some of the integration tools described in Appendix A.
As well as running on Windows operating systems, CVSNT provides an additional access method, sspi, that authenticates using NT domain passwords. It also allows you to lock branches to specific developers and has a Windows-style installation script. However, CVSROOT scripts that rely on a Unix-like shell environment may not work under CVSNT.
CVSNT is available at http://www.cvsnt.org.
Meta-CVS is an expansion of CVS that adds versioning for directories, supports symbolic links and file metadata, automatically sets the keyword-expansion mode for certain file types (such as .png files) to binary, and improves the user interface for branching and merging. It also improves the way CVS handles file addition and removal conflicts and changes the way vendor branches are used.
Meta-CVS is a variation of the client code and operates from a standard CVS repository. It changes the data stored in the repository, so you can't have a team on the same project with a mixture of Meta-CVS and standard CVS users.
Meta-CVS is available from http://users.footprints.net/~kaz/mcvs.html.
Often, you may want to develop a CVS project and publish the files for display or download. You can publish the resulting files with a build script or a script in one of the CVSROOT files. Alternatively, you can use one of the tools in this section, all of which display CVS project files.
Some of the tools in this section display the repository; others export files from the repository for publication. Some retrieve the difference between the revision they have and the latest revision in the repository, then patch the revision they have and display the final files.
Chora provides the ability to view or download the files in a CVS repository using a web browser. It integrates with the other web tools available at http://www.horde.org. The CVS integration is stored in a single library, so you can customize the rest of the display.
In file mode, every revision of a file is displayed along with log messages and you also have the ability to display the differences between revisions. File mode also offers a color-coded branch view.
Chora is available from http://www.horde.org/chora/.
CVSup is a tool for distributing files across a network. It can be used with most file types and understands CVS project files. If desired, it can use zlib compression to reduce network load.
If CVSup is working from CVS files, it distributes the differences rather than the files as a whole, saving bandwidth and minimizing the network load. It also understands tags and distributes specific tagged versions if configured to do so.
CVSup is available from http://www.cvsup.org.
This tool publishes CVS files using FTP. It was developed for web sites that use CVS for content management, but for which the administrator of the server requires that updates be made using the FTP protocol.
CVSviaFTP does not start an FTP session automatically; it needs to be wrapped in a script that manages login and other specifics of your FTP site. However, it is useful when you are managing content across an FTP link.
CVSviaFTP is available from http://www.siber.org/cvs-via-ftp/.
CVSweb is one of several tools that allow a CVS repository to be accessed using a web browser. It allows only viewing or downloading, not the ability to change files.
CVSweb allows you to view a directory, an individual file, any revision of a file, the difference (as reported by the diff command) between the current and previous revisions, or an annotated view of a file.
There are two versions of CVSweb: one available from http://www.freebsd.org/projects/cvsweb.html, and another from http://stud.fh-heilbronn.de/~zeller/cgi/cvsweb.cgi/.
CVS Web Client
CVS Web Client is one of several tools that allow a CVS repository to be accessed using a web browser. It is a variation of CVSweb that allows a limited ability to edit the repository from the browser.
Unfortunately, CVS Web Client is no longer supported, and the documentation is sparse.
CVS Web Client is available from http://www.mrjc.com/twiki/bin/view/Cvswebclient/WebHome.
jCVS Servlet allows a CVS repository to be accessed using a web browser. It displays the directory structure, file revisions, differences between revisions, and the content of files. The interface is configurable.
jCVS Servlet also provides a Java API, so it can be called from other Java programs.
jCVS Servlet is available from http://www.jcvs.org. It is a Java Servlet, requiring a web server that can run Java Servlets.
SandWeb is one of several tools that allow a CVS repository to be accessed using a web browser. It's intended to be independent of the version control system, but the alpha release works only with CVS.
SandWeb is more than a viewer; it provides the ability to add, delete, and edit text files, and it commits the changes automatically. In time, it may become an effective HTML client for CVS.
SandWeb is available from http://sandweb.sourceforge.net/.
ViewCVS started out as a modification of CVSweb, and it performs the same basic tasks. In addition, ViewCVS allows queries, supports virtual hosts, and has configurable page layouts.
ViewCVS requires Python, and the query support requires an SQL database.
ViewCVS is available from http://viewcvs.sourceforge.net/.
CVS log messages often contain useful information for project managers, programmers, and other CVS users. There are many tools that manipulate log messages, including tools to create a change log automatically, mail log messages, and change the format of log messages. These tools are most useful if you and your development team enter meaningful log messages.
CHalogen is a change-log generator that relies on the CVS project files being tagged at each significant stage of the project. It generates a change log that displays the changes between tag points. The generated change log is in HTML format.
CHalogen can run as a CGIscript or from the command line.
CHalogen is available from http://www.softwarebee.de/products/chalogen/.
clmerge is a script that merges conflicts in a GNU-style change log. The change log is sent to the standard output, so the script output should usually be redirected to a file. This script is useful as a postprocessor to change log generation programs.
clmerge is available from the contrib directory in the CVS source code.
commit_prep and log_accum
These scripts are designed to work together. commit_prep ensures that the Id keyword is present in the file and checks the version number of the keyword. It prevents older revisions from being copied into the sandbox and replacing an existing revision. It also records information for log_accum .
log_accum consolidates the log messages from a single commit of multiple directories and mails the resulting consolidated log messages — including a consolidated list of which files were added, removed, and modified — to a specified address.
These scripts should be called from the scripting files in the CVSROOT directory.
commit_prep and log_accum are available from the contrib directory in the CVS source code.
cvs2cl.pl runs cvs log and converts the output to a GNU-style change log. Duplicate messages on the same date are merged. cvs2cl.pl runs from the command line and can be included in automated scripts. There are many configuration arguments, producing a variety of output formats.
cvs2cl.pl is available from http://www.red-bean.com/cvs2cl/.
cvs2html converts the output from cvs log to a frame-based set of HTML pages. In addition to log information, the pages display color-coded diffs between revisions.
cvs2html is available from http://cvs.sslug.dk/cvs2html/.
cvs-exp is a cvs log postprocessor that creates a chronological log file across a project. It also displays a tree structure of the branches and tags in a more human-readable format than cvs log provides.
cvs-exp is available from http://www.cs.rice.edu/~ssiyer/code/cvs-exp/.
This script mails the log information provided with a CVS commit to a specified address. It includes status information for each changed file, as well as the log message and information on which files were changed. The log script should be called from the loginfo file in the CVSROOT directory.
log is available from the contrib directory in the CVS source code.
mfpipe either mails log information to a specified address or pipes the mail information into a file. This script should be called from the loginfo file in the CVSROOT directory.
mfpipe is available from the contrib directory in the CVS source code.
rcs2log is a script that creates a GNU change log from the RCS project files in the CVS repository. It has a variety of formatting arguments and recurses through the local directories. It was originally written for RCS.
rcs2log is available from the contrib directory in the CVS source code.
The tools described in this section provide metadata about the CVS project files or use existing file metadata to provide additional functionality. Using these tools, you can search your log comments or your repository, see a graph showing the rate of file accesses over the past week, or find out who changed which files most recently.
CVS Monitor is a specialized CVS client that displays module and file information, graphic summaries of user activity within modules, change logs, file histories, and other information. It runs as a CGI script and presents its output in a web browser.
CVS Monitor is available from http://ali.as/devel/cvsmonitor/.
CVSPlot is a Perl script that plots statistics from a CVS project, such as the number of lines of data or the number of files in a module. It generates the results as a text file or as a .png graph that models the change over time.
CVSPlot is called from the command line and can be used in a script. It allows you to specify the period of time and the file types you are interested in. It requires Perl, and to plot graphically it also requires gnuplot.
CVSPlot is available from http://cvsstat.sourceforge.net/.
CVSSearch runs keyword searches on the comments stored as a result of file commits. Its output includes not only every comment that contains keywords you specify, but also filenames and links to the code that matches the comment.
Recent versions of CVSSearch allow you to search your code as well as your log comments. CVSSearch requires a web server and operates as CGI code.
CVSSearch is available from http://cvssearch.sourceforge.net/.
cvsstat and cvschk
These scripts display the status of project files. cvsstat shows which files have been modified locally, which files have been modified in the repository by other users, and which files are up-to-date. cvschk is a similar script for the local sandbox and does not search the repository.
cvsstat and cvschk are available from http://cvs.sslug.dk/cvs2html/.
If you want to use CVS with a project that is currently being stored in a version control system other than CVS, you need to convert the files from the other system to CVS. Fortunately, scripts to do just that are available on the Internet and in the CVS source distribution.
The rcs-to-cvs script checks RCS files in to CVS. It also checks in files that didn't previously have source control. It starts by checking whether the current directory's subdirectories exist in the repository; then it commits the files. Files that do not already exist in the repository are checked in as revision 1.1.
rcs-to-cvs is available from the contrib directory in the CVS source code.
rcs2sccs and sccs2rcs
These scripts convert between RCS and SCCS version control. Note that rcs2sccs supports only one level of branching. Both scripts retain as much of the file metadata as possible.
rcs2sccs and sccs2rcs are available from the contrib directory in the CVS source code.
VSS2CVS is a Perl script to synchronize Visual Source Safe and CVS repositories. It is intended to convert from one source control system to the other and may need modification if you want to try to use both systems simultaneously.
VSS2CVS runs on Windows machines and requires a Perl interpreter (such as ActivePerl) and two utilities that are available with Cygwin.
VSS2CVS is available from http://www.laine.org/cvs/vss2cvs/.
pvcs2rcs reads files from Merant PVCS version control and writes a copy of those files using RCS version control. It acts recursively and leaves the PVCS archive unchanged.
pvcs2rcs is available from the contrib directory in the CVS source code.
The tools described in this section are too unique to be categorized easily. However, they are very useful. They range from a tool to clear out old data from the history file, to a tool to mount the repository as a filesystem.
This script removes most of the old records from the history file in the CVSROOT directory in the repository. It keeps records of file modification, addition, and removal, keeps the last change to each tag, and removes everything else. This effectively compresses the history file by removing most of the outdated data.
cln_hist is available from the contrib directory in the CVS source code.
This script implements access-control lists within CVS. It must be the only script in the commitinfo file in the CVSROOT directory and should be set as DEFAULT so it is called by all files. The script permits access control based on the username, project directories, and branches within the projects.
cvs_acls is available from the contrib directory in the CVS source code.
CVSCheck provides status information for files in the current sandbox. Its output is more concise than the output of cvs status or cvs log, so it's a handy tool for checking status in large sandbox directories.
CVSCheck is available from the contrib directory in the CVS source code.
CVSFS is a tool for mounting a CVS repository as a filesystem. It works only with the pserver access method (as of CVS 1.1.9). By default, it displays the current (HEAD) revision of the trunk of any file. Its main use is reading a repository, and it can be useful as a build tool.
CVSFS is available from http://sourceforge.net/projects/cvsfs/.
CVS2vendor allows you to add a vendor branch to a project you created without using cvs import to make a vendor branch. It moves the project to a new repository directory, but it preserves tags and change records. The branch revision of each file on the vendor branch is given the same timestamp as revision 1.1 of that file.
CVS2vendor is available from the contrib directory in the CVS source code.
The descend script is obsolete for use with most CVS commands, but it may be useful in obscure situations. It permits you to descend through a directory tree recursively, running an arbitrary command at each point.
descend is available from the contrib directory in the CVS source code.
rcslock is described in Chapter 5. It enables you to lock files so that only the developer who holds the file lock can commit a file. This is especially useful when you have binary files or other files that cannot be merged.
rcslock is available from the contrib directory in the CVS source code.