StatCVS Manual

This is the manual for StatCVS , a statistics tool for CVS repositories.

Table of Contents

Prerequisites

To run StatCVS, you need:

  • Java version 1.4 or above. Type java -version on the command line to see your Java version. You can download Java 1.4.2 from Sun's web site. You need the download called ?JRE?.
  • The CVS command-line client for creating CVS logfiles. Both CVS (for Unix) and CVSNT (for Windows) are supported.

Quick Start

It takes three steps to create reports for a CVS module:

  1. Check out a copy of the module from CVS
  2. Create a CVS log for the module
  3. Run StatCVS

Checking out a module from CVS

You can skip this step if you have already checked out a working copy. Typically, the command looks like this (assuming module to be the name of the module):

cvs -d /cvsroot checkout module

Creating a CVS log file

Change into the directory where you have checked out the module, and use the cvs log command to create a log file.

cd module cvs log > logfile.log

Running StatCVS

StatCVS is run using the command java -jar statcvs.jar . It takes two command line parameters:

java -jar statcvs.jar <logfile> <checked-out-module>

For example:

java -jar /path/to/statcvs.jar /path/to/module/logfile.log /path/to/module

This command creates the reports in the current directory. You can now point your browser to the file index.html , which is the table of contents of the report.

Command Line Options

You can tweak the reports and change the behaviour of StatCVS in various ways using command line options.

java -jar statcvs.jar [options] <logfile> <checked-out-module>

A list of all options understood by StatCVS follows.

-output-dir <directory>

Specify an output directory. The reports will be generated in this directory. The directory will be created if it doesn't exist.

-config-file <path to a properties file>

Specify a properties file. For details of options, see section 'Config File' below.

-include <include-pattern-list>

-exclude <exclude-pattern-list>

Specify filters to exclude files from the analysis. A file will be ignored if it doesn't match any of the patterns in include-pattern-list , or if it matches any pattern in exclude-pattern-list .

The patterns are lists of Apache Ant -style wildcard patterns, separated by colons or semicolons. The wildcards are:

  • '?' matches a single character, except '/'
  • '*' matches zero or more characters, except '/'
  • '**' matches zero or more characters, including '/'

For example, src/**/*.java matches all java files in the src directory or its subdirectories. Note that *.java only matches java files in the root directory, because '*' does not match subdirectories. For the same reason, src-* doesn't match files inside the directory src-java , use src-*/** to match them.

One more example:

-include '**/*.c:**/*.h' -exclude 'legacy/**'

This matches all .c and .h files anywhere in the directory tree except those in the legacy directory and its subdirectories.

For more information on Ant's wildcard syntax, see the Patternset section of the Ant manual .

If not specified, all files will be included and no files will be excluded.

Note: Unix users must put the patterns in quotes, or the shell will interfere with the wildcards.

-tags <tags-regularexpression>

Includes information about CVS tags into the reports. Only tags matching the regular expression are included. To include all tags, add -tags '.*' to the command line.

Note: Unix users must put the expression in quotes, or the shell will interfere with the wildcards.

-no-developer <login-name>

Excludes a CVS account name from all developer reports. This is useful to reduce noise from administrative and other non-developer accounts. Multiple accounts can be excluded by adding the option to the command line once for each account.

-title <title>

Specifies a display title to be used in the reports. The name of the CVS module will be used as default if no title is specified.

-css <stylesheet>

Specify a Cascading Style Sheet for the report. This can be a HTTP URL or a local file. A URL will simply be linked in every page of the report. A local file will be copied into the report directory.

-headerUrl <urlToATextFile>

Specify a URL (can be a local file but needs to match URL syntax) for a text file that will be incorporated in all pages just after <body>

-footerUrl <urlToATextFile>

Specify a URL (can be a local file but needs to match URL syntax) for a text file that will be incorporated in all pages just before </body>

-notes <notes-file>

The contents of the specified file will be included at the top of the report's index page. The file should contain a valid block-level HTML fragment, for example:

                        <p> These are development statistics for the <a href="http://statcvs.sf.net/">StatCVS</a> project, created by StatCVS
                        itself. </p> <p> <strong>Note:</strong> This report was generated by an unreleased development version of
                        StatCVS. It might contain features not yet found in the official release. </p>
                    
-viewcvs <viewcvs-url>

Specify the URL of a ViewCVS installation for the module. This must be the URL of the page for the module's root directory. StatCVS will create links to ViewCVS for directories, files and revisions.

-viewvc <viewvc-url>

Specify the URL of a ViewVC installation for the module. This must be the URL of the page for the module's root directory. StatCVS will create links to ViewVC for directories, files and revisions.

-cvsweb <cvsweb-url>

Specify the URL of a cvsweb installation for the module. This must be the URL of the page for the module's root directory. StatCVS will create links to cvsweb for directories, files and revisions.

-chora <chora-url>

Specify the URL of a Chora installation for the module. This must be the URL of the page for the module's root directory. StatCVS will create links to Chora for directories, files and revisions.

-jcvsweb <jcvsweb-url>

Specify the URL of a JCVSWeb installation for the module. This must be the URL of the page for the module's root directory. StatCVS will create links to JCVSWeb for directories, files and revisions.

-bugzilla <bugzilla-url>

Specify the root URL of a Bugzilla installation. In commit messages, this will turn ? Bug #### ? into a link to the appropriate bug.

-mantis <mantis-url>

Specify the root URL of a Mantis bug tracker installation. In commit messages, this will turn ? Bug #### ? into a link to the appropriate bug.

-xdoc

Generate Maven XDoc instead of HTML. This allows Maven and Maven 2 to integrate the reports when it generates the projects Maven site. Reports could be placed, for example, into src/site/statcvs .

-disable-twitter-button

Do not include Twitter "Tweet This" buttons in the output.

-verbose

Output additional progress information.

-debug

Output lots of additional progress information.

-xml

Output the statistics as an XML file called repo-statistics.xml.

-version

Output the version of StatCVS.

-disable-twitter-button

Disable the "Tweet This" buttons.

Setting Start and End Dates

StatCVS doesn't provide options to specify a start and end date for the report. But you can use some options of the cvs log command to achieve the same effect.

Setting a start date

cvs log -d "2002-01-01<" > logfile.log

This will result in a logfile starting at January 1st, 2002.

Setting an end date

If you want to specify an end date, then you also have to check out the module as of this date.

cvs checkout -D 2002-12-31 modulename cd modulename cvs log -d "<2002-12-31" > logfile.log

The example checks out a module and creates a log that ends December 31st, 2002.

Setting both start and end date

You can combine both approaches. This example generates a log for a report of 2002:

cvs checkout -D 2002-12-31 modulename cd modulename cvs log -d "2002-01-01<2002-12-31" > logfile.log

More information on the log -d option can be found in the CVS manual .

Ant Task

StatCVS comes with an Ant task for the Apache Ant build tool.

An example build file:

<?xml version="1.0"?> 
  <project name="Example" default="stats" basedir="."> 
      <target name="stats"> 
         <taskdef name="statcvs" classname="net.sf.statcvs.ant.StatCvsTask" classpath="dist/statcvs.jar"/> 
         <statcvs log="cvs.log" path="." title="StatCVS" outputDir="stats" notes="etc/report-notes.txt" 
                  viewcvs="http://statcvs.cvs.sourceforge.net/statcvs/statcvs" 
                  tags="v.*"
                  configFile="myconfig.properties"
                  disableTwitterButton="false"/> 
      </target>
  </project>
            

The attributes log and path are required. The other attributes are optional, their names correspond to the command line options . The path to statcvs.jar has to be provided in the <taskdef/> 's classpath attribute.

Config File

The config file allows you to set some user or chart configurations.

##
# User Details
# user.[cvsUserName].replacedBy=[new CVS user name] <-- user name that replaces the user (merge!)
#
# user.[cvsUserName].realName=[user real name]
# user.[cvsUserName].url=[user homepage full url]
# user.[cvsUserName].image=[url to user picture]
# user.[cvsUserName].email=[user email]
# user.[cvsUserName].twitterUsername=[Twitter userName]
# user.[cvsUserName].twitterUserId=[user twitter id, an int!] <-- This is more difficult to find, see the Twitter API section
# user.[cvsUserName].twitterIncludeHtml=true/false < -- Typically you'd chose html OR flash
# user.[cvsUserName].twitterIncludeFlash=true/false
##

# Example
user.benoitx.realName=Benoit Xhenseval
user.benoitx.url=http://www.xhenseval.com/benoit
user.benoitx.image=http://www.xhenseval.com/benoit/bx-avatar.jpg
user.benoitx.email=
user.benoitx.twitterUsername=benoitx
user.benoitx.twitterUserId=18722145
user.benoitx.twitterIncludeHtml=true
user.benoitx.twitterIncludeFlash=true

##
# CHART Details
# chart.[chartName].backgroundColor=#AABBCC
# chart.[chartName].plotColor=#AABBCC
# chart.[chartName].lineSize=1
# chart.[chartName].backgroundColor=#AABBCC
# chart.[chartName].width=700
# chart.[chartName].height=500
# chart.[chartName].showShapes=true
# chart.[chartName].filledShapes=true
# chart.[chartName].copyright=[copyright or any other text, placed at the bottom right]
# chart.[chartName].copyrightTextSize=[txt size, default 9]
# chart.[name].chartBackgroundImage.url=[url to an image, eg file:///C:/project/statcvs/site/images/statcvslogo.gif]
# chart.[name].chartBackgroundImage.transparency=[float 0 to 1, defaulted to 0.35]
# chart.[name].plotImage.url=[url to an image, eg file:///C:/project/statcvs/site/images/statcvslogo.gif]
# chart.[name].plotImage.transparency=[float 0 to 1, defaulted to 0.35]
# Chart Names are:
# file_size, file_count, directory_sizes, commitscatterauthors, loc_per_author, directories_loc_timeline, loc_module, loc_small, loc
# activity, activity_time, activity_day, locandchurn
##

# Example
chart.backgroundColor=#FFFFEE
chart.plotColor=#EFEFEF
chart.lineStroke=1.5
chart.width=952
chart.height=596
chart.copyright=(c)StatCVS, 2009+
chart.copyrightTextSize=10
#
chart.activity.height=19

# background image
chart.chartBackgroundImage.url=file:///C:/project/statcvs/site/images/statcvslogo.gif
chart.chartBackgroundImage.transparency=0.40

# background plot
chart.loc.url=file:///C:/project/statcvs/site/images/cervin_zoom.jpg
chart.loc_small.plotImage.url=http://www.appendium.com/openimages/appendium_logo.jpg


##
# CLOUD from Words in Commit comments
#
#cloud.minFrequency=[Min amount of times a word must appear]
#cloud.maxWordNumberInCloud=[Maximum number of words in the cloud, defaulted to 100]
#cloud.maxWordNumberInTable=[Maximum number of words in the table, defaulted to 50]
#cloud.minLengthForWord=[Min number of characters for a word, defaulted to 4]
#cloud.exclusionRegExp=[Regular expression to exclude some words, released with an English version]
##
cloud.minFrequency=5
cloud.maxWordNumberInCloud=100
cloud.minLengthForWord=4
cloud.maxWordNumberInTable=50
cloud.exclusionRegExp=\\d+|an|the|me|my|we|you|he|she|it|are|is|am|will|shall|should|would|had|have|has|was|were|be|been|this|that|there

##
# Modules definitions for the Module statistics pages
# modules=<csv list of IDs>
# module.<ID>.name=<module name>
# module.<ID>.regexp=<regexp1>;<regexp2>
##
modules=A,B,C
module.A.name=Module A
module.A.regexp=**/charts/*.java
module.B.name=Module B
module.B.regexp=**/package1/*.java;**/packageB*/*
module.C.name=Module CSV
module.C.regexp=**/*.csv
			

Limitations

This section lists some limitations and inaccuracies of StatCVS and its reports.

  • Deleted and moved files : Lines of Code counts will be inaccurate for deleted or moved files. When a file is deleted or moved, StatCVS can't track exactly how many lines it had and by whom they were committed.

  • Branches : StatCVS analyzes only the default branch of a repository. Anything on side branches will be ignored. Analyzing side branches is currently not possible.

Further Reading

StatCVS offers a view into CVS repository activity
IBM developerWorks has an article on StatCVS by Tom Copeland. Includes a section on generating reports for several repositories at once and a sidebar on the value (or lack thereof) of LOC as a measure for productivity.