Cvsplot v1.6.1

Cvsplot is used for collecting statistics from CVS controlled files.
Simple statistics such as how the total number of files and lines of
code change against time.

A simple invocation would be:

cvsplot.pl -cvsdir :ext:cvsbox:/usr/local/cvsroot -rlog product \
           -linedata linedata.txt -filedata filedata.txt

This effectively retrieves cvs history information for all CVS
controlled files in the "product" module from the CVS repository.  The
-cvsdir argument is the same as the CVSROOT environment variable.  The
results are stored into the linedata.txt and filedata.txt files in a
simple text format.  Each line consists of a data point (corresponding
to a CVS commit), which includes the date of the commit, and the
corresponding number.

For linedata.txt, this number represents the total number of lines
for active files that exist in the repository up until that date.  For
filedata.txt, this represents the total number of files that exists in
the repository up until that date.  Note files which have been
indicated as binary to CVS are ignored.

If the period of interest is well defined, then it is possible to trim
the statistics reported by optionally specifying start and/or end
dates.  For example, if we are only interested in statistics starting
from the 28th March, 2001, then the following can be entered:

cvsplot.pl -cvsdir /usr/local/cvsroot -rlog product -linedata linedata.txt \
           -filedata filedata.txt -start "28th March, 2001"

The -end option is used to specify the final date, for example:

cvsplot.pl -cvsdir /usr/local/cvsroot -rlog product -linedata linedata.txt \
           -filedata filedata.txt -start "28th March, 2001" \
           -end "2nd May, 2001"

The date formats supported are very flexible, as the Date::Manip perl
module is used for date parsing and manipulation.  The above command
could have also been expressed as:

cvsplot.pl -cvsdir /usr/local/cvsroot -rlog product -linedata linedata.txt \
           -filedata filedata.txt -start "2001/03/28" \
           -end "2001/05/02"

It is possible to specify filesets in order to restrict what statistics
are generated.  For example, assuming we are only interested in C
files, header files and java files, the following command could be
specified:

cvsplot.pl -cvsdir /usr/local/cvsroot -rlog product -linedata linedata.txt \
           -filedata filedata.txt -include '\.java$' -include '\.c$' \
           -include '\.h$'

The argument given to the -include option is in the syntax of a perl
regular expression.  To avoid shell expansion, single quotes must be
used.  It is also possible to specify files that should not be
included.  Assuming we are interested in java and C files, but don't
want to run statistics down the "kernel" sub-directory, then the
following command could be issued:

cvsplot.pl -cvsdir /usr/local/cvsroot -rlog product -linedata linedata.txt \
           -filedata filedata.txt -exclude '^kernel' \
           -include '\.java$' -include '\.c$' -include '\.h$'

The order of the -exclude and -include options is important.
Whenever cvsplot examines a file, it runs through the list of -exclude
and -include options in the order specified on the command line.  If
the filename matches a -exclude option, it is skipped.  If a filename
matches a -include option, it includes the file when collecting
statistics.  If no -include or -exclude options have been specified,
then the default behaviour is to include all files.  If -include or
-exclude options have been specified, and a file doesn't match any of
the include or exclude patterns, then it is *not* included when
collecting statistics.

The -include and -exclude options and semantics were based on the
--include and --exclude options from rsync.

It is also possible to provide a specific CVS branch in which to
gather statistics.  The above command can be run against the
RELEASE1 branch as follows:

cvsplot.pl -cvsdir /usr/local/cvsroot -rlog product -linedata linedata.txt \
           -filedata filedata.txt -exclude '^kernel' \
           -include '\.java$' -include '\.c$' -include '\.h$' \
           -branch RELEASE1

In addition to generating statistics into a text file, it is also
possible to generate plots as a png file, assuming gnuplot is
installed on your system.  I run cvsplot.pl in a cron job so that my
team's statistics are updated nightly on our internal web-server.
Gnuplot supports many other file formats, such as png, gif, jpg and
postscript.

To generate png files which will plot the statistics, the -gnuplot
options are specified:

cvsplot.pl -cvsdir /usr/local/cvsroot -rlog product -linedata linedata.txt \
           -filedata filedata.txt -gnuplotfiledata filedata.png \
           -gnuplotlinedata linedata.png

The filedata.png file presents the statistics in filedata.txt as a png
file generated by gnuplot.  Similarly for linedata.png.  For gnuplot
users, it is possible to specify the "terminal parameters" sent to
gnuplot when generating the plots.  For example, to generate the plots
as a postscript eps using Times-Roman font, the following could be
specified:

cvsplot.pl -cvsdir /usr/local/cvsroot -rlog product -linedata linedata.txt \
           -filedata filedata.txt -gnuplotfiledata filedata.eps \
           -gnuplotlinedata linedata.eps \
           -gnuplotsetterm "post eps 'Times-Roman'"

Its also possible to specify general gnuplot commands (separated by
semi-colons) which will get executed before the final "plot" commands
to generate the graphs.  One possibility might be to change the
formatting of the x values, from their default %m/%y (month/year)
format, such as %d/%m (day/month) and to set the title of the graph:

cvsplot.pl -cvsdir /usr/local/cvsroot -rlog product -linedata linedata.txt \
           -filedata filedata.txt -gnuplotfiledata filedata.eps \
           -gnuplotlinedata linedata.eps \
           -gnuplotsetterm "post eps 'Times-Roman'" \
           -gnuplotcommand "set format x '%d/%m'; set title 'CVS History'"

The above commands use the "cvs rlog" command, to retrieve the
relevant information.  This command is properly implemented in CVS
versions >= 1.11.1.  If you have an older version of CVS, you can still
use cvsplot, however you need a checked out version of the module you
want to gather statistics from (to run "cvs log" against).  Make sure
the checkout is done without the -P flag, and those directories which
are pruned will be excluded from the statistics, which is not what you
want.  The only difference in command syntax is the argument to
-cvsdir refers to your checked out sandbox, and the -rlog command is
omitted.  For example, the previous command would be the following,
assuming the product module was checked out in the ~/product
directory.

cvsplot.pl -cvsdir ~/product -linedata linedata.txt \
           -filedata filedata.txt -gnuplotfiledata filedata.eps \
           -gnuplotlinedata linedata.eps \
           -gnuplotsetterm "post eps 'Times-Roman'" \
           -gnuplotcommand "set format x '%d/%m'; set title 'CVS History'"

----------------------------------------------------------------------

Requirements:

Cvsplot uses the Date::Manip perl module, which can be obtained from:
http://search.cpan.org/search?dist=DateManip

Gnuplot comes with most Linux distributions, and can be found at
http://www.gnuplot.org.  If the -gnuplot* options are not used, then
its not necessary to install gnuplot.

----------------------------------------------------------------------

Updates:

Updates can be found from http://cvsplot.sourceforge.net.

Comments:

Please send comments to sits@users.sourceforge.net
Thank you!


