Cvsplot v1.3

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. As an example, the following graph was generated using cvsplot, which plots the history of the jBoss project's CVS repository.

The latest version of cvsplot can be obtained from: http://prdownloads.sourceforge.net/cvsplot/cvsplot-1.3.tar.gz

Note: this project used to be known as cvsstat, however another unrelated script by this name already exists, so the project name was changed to cvsplot.

Generating Statistics

A simple invocation would be:

cvsplot.pl -cvsdir ~/product -linedata linedata.txt -filedata filedata.txt
	

This effectively retrieves cvs history information for all CVS controlled files located in the ~/product directory, and stores the results 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.

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 ~/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 ~/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 ~/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 ~/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" directory which exists as a sub-directory located in ~/product, then the following command could be issued:

cvsplot.pl -cvsdir ~/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 ~/product -linedata linedata.txt \
           -filedata filedata.txt -exclude '^kernel' \
           -include '\.java$' -include '\.c$' -include '\.h$' \
           -branch RELEASE1
	

Generating Graphical Plots

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 jpg, gif and postscript.

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

cvsplot.pl -cvsdir ~/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. Similarily 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 ~/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 ~/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

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.

Project Information

Comments