Cvsplot v1.6.5

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

Note, if using perl 5.8, the DateManip module contains characters that
are non UTF-8 characters.  All invocations of cvsplot.pl should be
done with the LANG environment variable set to "C".  With the bash
shell, this would be:

LANG=C cvsplot.pl ...

The above command 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.  

Its also possible to generate plots which combine both the line and
file data into a single plot, using the -gnuplotlinefiledata switch.

cvsplot.pl -cvsdir /usr/local/cvsroot -rlog product -linedata linedata.txt \
           -filedata filedata.txt -gnuplotfiledata filedata.png \
           -gnuplotlinedata linedata.png \
           -gnuplotlinefiledata linefiledata.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'"

Finally, for large plots, it is definately worth trying the -linestyle
option, as this can dramatically improve readability.

For platforms (such as windows) where gnuplot may not be in the
standard PATH, and/or has a different name, the -gnuplot option can be
used to specify the full path to the gnuplot binary.

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

Requirements:

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

Cvsplot also uses the String::ShellQuote module for robustly handling
files with funny characters.  It can be obtained from:
http://search.cpan.org/search?dist=ShellQuote

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!


