source: trunk/doc/readme.txt @ 187

$Id: readme.txt 187 2006-09-06 03:12:29Z peter $

======================================================================
Copyright (C) 2005, 2006 Jari Häkkinen

This file is part of svndigest, http://lev.thep.lu.se/trac/svndigest

svndigest is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.

svndigest is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
USA.
======================================================================


svndigest traverses a directory structure (controlled by subversion)
and calculates developer statistics for all subversion controlled
entries. The result is written to a sub-directory of a user
specifiable target directory (defualt is the current working
directory).

To understand what statistics is calculated by svndigest this
definition is needed: The developer who made the latest change to a
line still in use in the latest revision, is considered as the
contributor of that line regardless of who actually originally created
that line.

The statistics calculated is the number of lines contributed from each
contributing developer in the latest (checked out) revision. Also, the
number of lines still in use from each revision is calculated.

There are many different types of files and for many file types it
does not make sense to define lines. Source code, documentation, and
other human readable files can be treated in single line basis whereas
symbolic links and binary files cannot. svndigest treats binary files
as zero-line files, whereas symbolic links are treated as one-line
files. There is a possiblity to exclude files from the statistics, the
use of the property svndigest:ignore.

Sometimes large test files and xml files are added to the repository
that should not really be counted in the statistics. This is solved
with the svndigest:ignore property. Files with this property are
excluded from statistics. Setting the svndigest:ignore property to a
directory will exclude all siblings to that directory from svndigest
treatment.

svndigest requires the subversion repository to be checked out before
analysis, i.e., svndigest will not run directly against a repository,
and up to date with the repository.


The current flow of the program is.

i) Check that we are working with a WC in subversion control.

ii) Build the requested directory structure ignoring not subversion
   controlled items. During the directory structure creation a check
   is made that the WC is up to date with the repository.

iii) Walk through the directory structure and calculate statistics for
   each entry.

iv) Create the plots and html presentation.