<document>
	<properties>
		<title>Introduction</title>
	</properties>
	<head>
		<meta name="description" content="StatCVS retrieves information from a CVS repository and generates various tables and charts describing the project development." />

		<meta name="keywords" content="CVS, StatCVS, Statistics, Code Repository, cvs statistics, cvs graphs, java, open source" />
		<meta name="Subject" content="Statistics CVS" />
		<meta name="Copyright" content="StatCVS Team and Appendium Ltd" />
		<meta name="Language" content="English" />
		<meta name="Designer" content="StatCVS Team and Appendium Ltd" />
		<meta name="Distribution" content="Global" />
		<meta name="robots" content="ALL" />
		<meta name="Revisit-After" content="20 Days" />
		<link rel="alternate" type="application/rss+xml" title="ObjectLab Open Source News" href="http://feeds.feedburner.com/ObjectLabOpenSourceNews?format=xml" />
	</head>
	<body>
		<!-- The body of the document contains a number of sections -->
		<section name="StatCVS Manual">
			<p>
				This is the manual for
				<a href="http://statcvs.sf.net/">StatCVS</a>
				, a statistics tool for
				<a href="http://www.cvshome.org/">CVS</a>
				repositories.
			</p>

			<h2>Table of Contents</h2>
			<ul>
				<li>
					<a href="#section_prerequisites">Prerequisites</a>
				</li>
				<li>
					<a href="#section_quickstart">Quick Start</a>
				</li>
				<li>
					<a href="#section_command-line-options">Command Line Options</a>
				</li>
				<li>
					<a href="#section_limiting-dates">Setting a Start and End Date</a>
				</li>
				<li>
					<a href="#section_ant-task">Ant Task</a>
				</li>
				<li>
					<a href="#section_limitations">Limitations</a>
				</li>
				<li>
					<a href="#section_further">Further Reading</a>
				</li>
			</ul>
		</section>

		<a name="section_prerequisites" />
		<section name="Prerequisites">
			<p>To run StatCVS, you need:</p>
			<ul>
				<li>
					<strong>Java version 1.4</strong>
					or above. Type
					<tt>java -version</tt>
					on the command line to see your Java version. You can
					<a href="http://java.sun.com/j2se/1.4.2/download.html">download Java 1.4.2</a>
					from Sun's web site. You need the download called &#8220;JRE&#8221;.
                </li>
                <li>
                    <strong>The CVS command-line client</strong>
                    for creating CVS logfiles. Both
                    <a href="http://www.cvshome.org/">CVS</a>
                    (for Unix) and
                    <a href="http://www.cvsnt.org/">CVSNT</a>
                    (for Windows) are supported.
                </li>
            </ul>
        </section>


        <a name="section_quickstart" />
        <section name="Quick Start">
            <p>It takes three steps to create reports for a CVS module:</p>
            <ol>
                <li>Check out a copy of the module from CVS</li>
                <li>Create a CVS log for the module</li>
                <li>Run StatCVS</li>
            </ol>

            <subsection name="Checking out a module from CVS">
                <p>
                    You can skip this step if you have already checked out a working copy. Typically, the command looks like this (assuming
                    <tt>module</tt>
                    to be the name of the module):
                </p>
                <pre>cvs -d /cvsroot checkout module</pre>
            </subsection>

            <subsection name="Creating a CVS log file">
                <p>
                    Change into the directory where you have checked out the module, and use the
                    <tt>cvs log</tt>
                    command to create a log file.
                </p>
                <pre>cd module cvs log > logfile.log</pre>
            </subsection>

            <subsection name="Running StatCVS">
                <p>
                    StatCVS is run using the command
                    <tt>java -jar statcvs.jar</tt>
                    . It takes two command line parameters:
                </p>
                <pre>java -jar statcvs.jar &lt;logfile&gt; &lt;checked-out-module&gt;</pre>
                <p>For example:</p>
                <pre>java -jar /path/to/statcvs.jar /path/to/module/logfile.log /path/to/module</pre>
                <p>
                    This command creates the reports in the current directory. You can now point your browser to the file
                    <tt>index.html</tt>
                    , which is the table of contents of the report.
                </p>
            </subsection>
        </section>

        <a name="section_command-line-options" />
        <section name="Command Line Options">
            <p>You can tweak the reports and change the behaviour of StatCVS in various ways using command line options.</p>
            <pre>java -jar statcvs.jar [options] &lt;logfile&gt; &lt;checked-out-module&gt;</pre>
            <p>A list of all options understood by StatCVS follows.</p>
            <dl>

                <dt>
                    <tt>-output-dir &lt;directory&gt;</tt>
                </dt>
                <dd>
                    <p>Specify an output directory. The reports will be generated in this directory. The directory will be created if it doesn't exist.</p>
                </dd>

                <dt>
                    <tt>-config-file &lt;path to a properties file&gt;</tt>
                </dt>
                <dd>
                    <p>Specify a properties file. For details of options, see section <a href="#section_config">'Config File'</a> below.</p>
                </dd>

                <dt>
                    <tt>-include &lt;include-pattern-list&gt;</tt>
                    <br />
                    <tt>-exclude &lt;exclude-pattern-list&gt;</tt>
                </dt>
                <dd>
                    <p>
                        Specify filters to exclude files from the analysis. A file will be ignored if it doesn't match any of the patterns in
                        <tt>include-pattern-list</tt>
                        , or if it matches any pattern in
                        <tt>exclude-pattern-list</tt>
                        .
                    </p>
                    <p>
                        The patterns are lists of
                        <a href="http://ant.apache.org/">Apache Ant</a>
                        -style wildcard patterns, separated by colons or semicolons. The wildcards are:
                    </p>
                    <ul>
                        <li>'?' matches a single character, except '/'</li>
                        <li>'*' matches zero or more characters, except '/'</li>
                        <li>'**' matches zero or more characters, including '/'</li>
                    </ul>
                    <p>
                        For example,
                        <tt>src/**/*.java</tt>
                        matches all java files in the
                        <tt>src</tt>
                        directory or its subdirectories. Note that
                        <tt>*.java</tt>
                        only matches java files in the root directory, because '*' does not match subdirectories. For the same reason,
                        <tt>src-*</tt>
                        doesn't match files inside the directory
                        <tt>src-java</tt>
                        , use
                        <tt>src-*/**</tt>
                        to match them.
                    </p>
                    <p>One more example:</p>
                    <pre>-include '**/*.c:**/*.h' -exclude 'legacy/**'</pre>
                    <p>
                        This matches all
                        <tt>.c</tt>
                        and
                        <tt>.h</tt>
                        files anywhere in the directory tree except those in the
                        <tt>legacy</tt>
                        directory and its subdirectories.
                    </p>
                    <p>
                        For more information on Ant's wildcard syntax, see the
                        <a href="http://ant.apache.org/manual/dirtasks.html#patternset">Patternset section of the Ant manual</a>
                        .
                    </p>
                    <p>If not specified, all files will be included and no files will be excluded.</p>
                    <p>
                        <strong>Note:</strong>
                        Unix users
                        <em>must</em>
                        put the patterns in quotes, or the shell will interfere with the wildcards.
                    </p>
                </dd>

                <dt>
                    <tt>-tags &lt;tags-regularexpression&gt;</tt>
                </dt>
                <dd>
                    <p>
                        Includes information about CVS tags into the reports. Only tags matching the regular expression are included. To include
                        <em>all</em>
                        tags, add
                        <tt>-tags '.*'</tt>
                        to the command line.
                    </p>
                    <p>
                        <strong>Note:</strong>
                        Unix users
                        <em>must</em>
                        put the expression in quotes, or the shell will interfere with the wildcards.
                    </p>
                </dd>

                <dt>
                    <tt>-no-developer &lt;login-name&gt;</tt>
                </dt>
                <dd>
                    <p>
                        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.
                    </p>
                </dd>

                <dt>
                    <tt>-title &lt;title&gt;</tt>
                </dt>
                <dd>
                    <p>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.</p>
                </dd>

                <dt>
                    <tt>-css &lt;stylesheet&gt;</tt>
                </dt>
                <dd>
                    <p>
                        Specify a
                        <a href="http://www.w3.org/TR/REC-CSS2/">Cascading Style Sheet</a>
                        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.
                    </p>
                </dd>

                <dt>
                    <tt>-headerUrl &lt;urlToATextFile&gt;</tt>
                </dt>
                <dd>
                    <p>
                        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 &lt;body&gt;
                    </p>
                </dd>

                <dt>
                    <tt>-footerUrl &lt;urlToATextFile&gt;</tt>
                </dt>
                <dd>
                    <p>
                        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 &lt;/body&gt;
                    </p>
                </dd>

                <dt>
                    <tt>-notes &lt;notes-file&gt;</tt>
                </dt>
                <dd>
                    <p>
                        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>
                    <pre>
                        &lt;p&gt; These are development statistics for the &lt;a href="http://statcvs.sf.net/"&gt;StatCVS&lt;/a&gt; project, created by StatCVS
                        itself. &lt;/p&gt; &lt;p&gt; &lt;strong&gt;Note:&lt;/strong&gt; This report was generated by an unreleased development version of
                        StatCVS. It might contain features not yet found in the official release. &lt;/p&gt;
                    </pre>
                </dd>
                <dt>
                    <tt>-viewcvs &lt;viewcvs-url&gt;</tt>
                </dt>
                <dd>
                    <p>
                        Specify the URL of a
                        <a href="http://viewcvs.sourceforge.net/">ViewCVS</a>
                        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.
                    </p>
                </dd>

                <dt>
                    <tt>-viewvc &lt;viewvc-url&gt;</tt>
                </dt>
                <dd>
                    <p>
                        Specify the URL of a
                        <a href="http://www.viewvc.org/">ViewVC</a>
                        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.
                    </p>
                </dd>

                <dt>
                    <tt>-cvsweb &lt;cvsweb-url&gt;</tt>
                </dt>
                <dd>
                    <p>
                        Specify the URL of a
                        <a href="http://www.freebsd.org/projects/cvsweb.html">cvsweb</a>
                        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.
                    </p>
                </dd>

                <dt>
                    <tt>-chora &lt;chora-url&gt;</tt>
                </dt>
                <dd>
                    <p>
                        Specify the URL of a
                        <a href="http://www.horde.org/chora/">Chora</a>
                        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.
                    </p>
                </dd>

                <dt>
                    <tt>-jcvsweb &lt;jcvsweb-url&gt;</tt>
                </dt>
                <dd>
                    <p>
                        Specify the URL of a
                        <a href="http://www.jcvs.org/jcvsweb/">JCVSWeb</a>
                        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.
                    </p>
                </dd>

                <dt>
                    <tt>-bugzilla &lt;bugzilla-url&gt;</tt>
                </dt>
                <dd>
                    <p>
                        Specify the root URL of a
                        <a href="http://www.bugzilla.org/">Bugzilla</a>
                        installation. In commit messages, this will turn &#8220;
                        <tt>Bug ####</tt>
                        &#8221; into a link to the appropriate bug.
                    </p>
                </dd>

                <dt>
                    <tt>-mantis &lt;mantis-url&gt;</tt>
                </dt>
                <dd>
                    <p>
                        Specify the root URL of a
                        <a href="http://www.mantisbt.org/">Mantis bug tracker</a>
                        installation. In commit messages, this will turn &#8220;
                        <tt>Bug ####</tt>
                        &#8221; into a link to the appropriate bug.
                    </p>
                </dd>

                <dt>
                    <tt>-xdoc</tt>
                </dt>
                <dd>
                    <p>
                        Generate
                        <a href="http://maven.apache.org/maven-1.x/plugins/xdoc/">Maven XDoc</a>
                        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
                        <tt>src/site/statcvs</tt>
                        .
                    </p>
                </dd>

                <dt>
                    <tt>-disable-twitter-button</tt>
                </dt>
                <dd>
                    <p>Do not include Twitter "Tweet This" buttons in the output.</p>
                </dd>

                <dt>
                    <tt>-verbose</tt>
                </dt>
                <dd>
                    <p>Output additional progress information.</p>
                </dd>

                <dt>
                    <tt>-debug</tt>
                </dt>
                <dd>
                    <p>Output lots of additional progress information.</p>
                </dd>

                <dt>
                    <tt>-xml</tt>
                </dt>
                <dd>
                    <p>Output the statistics as an XML file called repo-statistics.xml.</p>
                </dd>

                <dt>
                    <tt>-version</tt>
                </dt>
                <dd>
                    <p>Output the version of StatCVS.</p>
                </dd>
                <dt>
                    <tt>-disable-twitter-button</tt>
                </dt>
                <dd>
                    <p>Disable the "Tweet This" buttons.</p>
                </dd>
            </dl>
        </section>

        <a name="section_limiting-dates" />
        <section name="Setting Start and End Dates">

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

            <subsection name="Setting a start date">

                <pre>cvs log -d "2002-01-01&lt;" &gt; logfile.log</pre>

                <p>This will result in a logfile starting at January 1st, 2002.</p>
            </subsection>

            <subsection name="Setting an end date">

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

                <pre>cvs checkout -D 2002-12-31 modulename cd modulename cvs log -d "&lt;2002-12-31" &gt; logfile.log</pre>

                <p>The example checks out a module and creates a log that ends December 31st, 2002.</p>
            </subsection>
        </section>
        <section name="Setting both start and end date">

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

            <pre>cvs checkout -D 2002-12-31 modulename cd modulename cvs log -d "2002-01-01&lt;2002-12-31" &gt; logfile.log</pre>

            <p>
                More information on the
                <tt>log -d</tt>
                option
                <a href="http://www.cvshome.org/docs/manual/cvs-1.11.10/cvs_16.html#SEC143" title="CVS Manual, log options">can be found in the CVS manual</a>
                .
            </p>
        </section>

        <a name="section_ant-task" />
        <section name="Ant Task">

            <p>
                StatCVS comes with an Ant task for the
                <a href="http://ant.apache.org/">Apache Ant</a>
                build tool.
            </p>
            <p>An example build file:</p>
            <pre>
&lt;?xml version="1.0"?&gt; 
  &lt;project name="Example" default="stats" basedir="."&gt; 
      &lt;target name="stats"&gt; 
         &lt;taskdef name="statcvs" classname="net.sf.statcvs.ant.StatCvsTask" classpath="dist/statcvs.jar"/&gt; 
         &lt;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"/&gt; 
      &lt;/target&gt;
  &lt;/project&gt;
            </pre>
            <p>
                The attributes
                <tt>log</tt>
                and
                <tt>path</tt>
                are required. The other attributes are optional, their names correspond to the
                <a href="#section_command-line-options">command line options</a>
                . The path to
                <tt>statcvs.jar</tt>
                has to be provided in the
                <tt>&lt;taskdef/&gt;</tt>
                's
                <tt>classpath</tt>
                attribute.
            </p>
        </section>

        <a name="section_config" />
        <section name="Config File">
        <p>The config file allows you to set some user or chart configurations.</p>
        <p><img src="images/chartExplanation.png"/></p>
        <pre>
##
# User Details
# user.[cvsUserName].replacedBy=[new CVS user name] &lt;-- 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!] &lt;-- This is more difficult to find, see the Twitter API section
# user.[cvsUserName].twitterIncludeHtml=true/false &lt; -- 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=&lt;csv list of IDs&gt;
# module.&lt;ID&gt;.name=&lt;module name&gt;
# module.&lt;ID&gt;.regexp=&lt;regexp1&gt;;&lt;regexp2&gt;
##
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
			</pre>
	</section>


        <a name="section_limitations" />
        <section name="Limitations">

            <p>This section lists some limitations and inaccuracies of StatCVS and its reports.</p>

            <ul>
                <li>
                    <p>
                        <strong>Deleted and moved files</strong>
                        : 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.
                    </p>
                </li>

                <li>
                    <p>
                        <strong>Branches</strong>
                        : StatCVS analyzes only the default branch of a repository. Anything on side branches will be ignored. Analyzing side branches is
                        currently not possible.
                    </p>
                </li>
            </ul>
        </section>

        <a name="section_further" />
        <section name="Further Reading">

            <dl>
                <dt>
                    <a href="http://www-128.ibm.com/developerworks/java/library/j-statcvs/">StatCVS offers a view into CVS repository activity</a>
                </dt>
                <dd>
                    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.
                </dd>
            </dl>

            <p class="footer">$Id: manual.xml,v 1.10 2009/08/22 10:30:42 benoitx Exp $</p>
        </section>

    </body>
</document>