Back to StatSVN's Home or StatSVN on SourceForge

Welcome to StatSVN's wiki!

This is the manual for StatSVN, a statistics tool for Subversion repositories.

Edit

Prerequisites

To run StatSVN, you need:
  • Java version 1.4.x or above. Type java -version on the command line to see your Java version. You can download Java from Sun's website. You need the download called “JRE”.
  • The Subversion command-line client, version 1.3.0 or higher. The binaries need to be on your command-line path when executing StatSVN.

Edit

Quick Start

It takes three steps to create reports for a Subversion module:
  1. Check out a copy of the module from Subversion
  2. Create a log file for the module
  3. Run StatSVN

Edit

Checking out a module from Subversion

You can skip this step if you have already checked out a working copy, whether with the command line utility as shown here or a graphical interface, such as TortoiseSVN, but make sure to run an "svn update" on your working copy or you may not see all your log entries (see this section of the SVN book for more information). Typically, the command looks like this (assuming modulename to be the name of the module):

svn co svn://server/repo/trunk/modulename

Edit

Creating an SVN log file

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

cd checkout_dir
svn log -v --xml > logfile.log

Do not forget the -v option otherwise it will not work. Edit

Running StatSVN

StatSVN is run using the command java -jar statsvn.jar. It takes a bare minimum of two command line parameters:

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

For example:

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

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

Edit

Command Line Options

In addition to the required command line parameters, you can use additional parameters to tweak the reports and change the behaviour of StatSVN.

java -jar statsvn.jar options <logfile> <checked-out-module>

A list of all options understood by StatSVN follows.

Edit

General Options

-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.



-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, seperated by colons or semicolons. The wildcards are:

  • '?' matches a single character
  • '*' matches zero or more characters
  • '**' matches zero or more directories

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.

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.



-cache-dir <directory>


Specify a cache directory for information retrieved from the Subversion server (e.g. line counts). The data will be saved in this directory. The directory will be created if it doesn't exist. By default, the current user directory is used.



-username <subversion_username>

Specify a username to use when connecting to the Subversion server.



-password <subversion_username>

Specify a password to use when connecting to the Subversion server.



-tags <tags-regularexpression>

Includes information about Subverison 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.

Note: Tags are determined by looking at your repository's /tags directory. To be able to use this feature, you must generate the log file from the root of your repository, so that the log contains information from both the /tags and the /trunk. The checked out version does not have to contain the tags directory.



-tags-dir <directory>

Specifies the root directory from which the tags regular expression is evaluated. The default -tags-dir is /tags/



-no-developer <login-name>
Excludes a Subversion 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.


Edit

Report Options

-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/statsvn.



-xml

Generate XML instead of HTML.



-css <stylesheet>

Optional (default varies for html or xdoc). 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.



-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://www.statsvn.org">StatSVN</a>
  project, created by StatSVN itself.
</p>
<p>
  <strong>Note:</strong>
  This report was generated by an unreleased
  development version of StatSVN. It might
  contain features not yet found in the
  official release.
</p>

-title <title>

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



-config-file <path to properties file>

Allows one to replace the source control username with more information such as real name, website, email and avatar icon. See this file for an example.



-charset <charSet>

Specifies the charset to use in HTML or XDOC output. ISO-8859-1 will be used as default if no charset is specified.



-disable-twitter-button

if present, exclude the Twitter "Tweet This" buttons from the output.



Edit

Options for Integration with External Tools

-bugzilla

Specify the URL of a root of a Bugzilla installation. Will replace 'Bug ###' in commit logs with a link to the appropriate bug. (New in StatSVN)



-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. StatSVN will create links to Chora 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. StatSVN will create links to ViewVC for directories, files and revisions.



-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.



-trac <trac-url>

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



Edit

Miscellaneous Options

-debug

Output lots of additional progress information.



-verbose

Output additional progress information.



-version

Output the version of StatSVN.



-dump

Will output the repository content on console and stop



-concurrency-threshold <millisec>

Switch to concurrent svn diff if the first call takes more than the threshold (in milliseconds) (default: 4000)



-threads <int>

How many threads for svn diff (default: 25)



-anonymize

Anonymizes committer names.



Edit

Examples

java -jar statsvn.jar -verbose -title jUCMNav 
      -exclude **/src/urncore/**;**/src/grl/**;**/src/ucm/**;**/src/urn/**;**/src/seg/jUCMNav/model/ucm/** \
      -output-dir ./stats c:\eclipse\workspace\seg.jUCMNav\svn.log c:\eclipse\workspace\seg.jUCMNav

Edit

Config file

The config file allows you to set some user or chart configurations. (option -config-file)

Chart Config

##
# 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

Edit

Setting Start and End Dates

StatSVN doesn't provide options to specify a start and end date for the report, but you can specify a date range in the svn log command to get the same effect.

To get the svn log for a date range, put the dates in brackets and add to the log command like this:
svn log -v --xml -r {2007-02-19}:{2007-02-12} > log.xml

See the dates section of the SVN book for more information on the allowed formats for dates.

Interested in learning more? John Brugge wrote a blog post on this subject.

Edit

Ant Task

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

An example build file:



<?xml version="1.0"?>
<project name="StatSvnAnt" default="main" basedir=".">
  <taskdef name="statsvn" classname="net.sf.statsvn.ant.StatSvnTask" classpath="dist/statsvn.jar" />

<target name="main"> <statsvn path="d:/statsvn" log="d:/statsvn/logfile.log" outputDir="d:/statsvn/stats" title="StatSVN" include="**/*.java" exclude="tests-src/**" notes="d:/statsvn/report-notes.txt"/> </target> </project>

The attributes path and log are required. (Note: path is the directory where the source is located.) The other attributes are optional.

The file statsvn.jar file must be on the Ant classpath, or be specified in the taskdef as above.

Edit

Limitations

This section lists some limitations and inaccuracies of StatSVN 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, StatSVN does not currently track exactly how many lines it had and by whom they were committed. (This was impossible in StatCVS, but is future work in StatSVN.)
  • Branches: StatSVN analyzes anything it is given. Because of the way Subversion treats branches, StatSVN is not limited to a repository's default branch, as StatCVS was. However, there are currently no special features that take into account the most common Subversion repository layout (with /branches and /trunk).
  • Tags: Tags are currently in beta; please see the command line option reference for details on its limitations.

Edit

Further Reading

  • StatCVS offers a view into CVS repository activity
    • IBM developerWorks has an article on StatCVS (StatSVN's parent) 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.

Powered by ScrewTurn Wiki. Some of the icons created by FamFamFam. Site hosted by LavaBlast Franchise Software.