source: trunk/doc/readme.txt @ 342

Last change on this file since 342 was 342, checked in by Peter Johansson, 14 years ago

adding info on ignoring '.in'

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
  • Property svn:mime-type set to text/x-trac-wiki
File size: 5.2 KB
[3]1$Id: readme.txt 342 2007-05-19 11:38:43Z peter $
[341]3= About svndigest =
[341]5Svndigest traverses a directory structure (controlled by subversion)
[149]6and calculates developer statistics for all subversion controlled
[187]7entries. The result is written to a sub-directory of a user
[188]8specifiable target directory (default is the current working
[341]11== Statistics ==
[149]13To understand what statistics is calculated by svndigest this
14definition is needed: The developer who made the latest change to a
[185]15line still in use in the latest revision, is considered as the
16contributor of that line regardless of who actually originally created
17that line.
[188]19For each developer svndigest calculates the number of contributed
[189]20lines in the latest (checked out) revision. Svndigest calculates for
21each revision, by checking when each line was last changed, how many
22lines each developer had contributed at that specific revision and
[341]23still are in use.
[341]25== Different linetypes ==
[341]27Svndigest parses each file to detect whether lines are `code`,
28`comment`, or `other`. Depending on the file name, different
29parsing modes are used, which means different sets of rules what is
30`code` or `comment` are employed. Common for all modes is that
31comment blocks are identified by a start code (e.g. '/*' in a C file)
32and a stop code (e.g. '*/' in a C file). If a line contains
33alphanumeric characters being outside comment blocks, the line is
34considered to be ''code''. Otherwise, if the line contains
35alphanumeric characters inside a comment block, the line is considered
36to be a line of ''comment''. Otherwise the line is considered to be
37`other`. At the time being the following comment identifiers are
[341]40 * cc-mode
41   * files: *.c, *.cc, *.cpp, *.cxx, *.h, *.hh, *.hpp, and *.java
42   * identifier: /* <comment> */
43   * identifier: // <comment> end-of-line
44 * m4-mode
45   * files: *.ac *.am *.m4
46   * identifier: dnl <comment> end-of-line
47   * identifier: # <comment> end-of-line
48 * shell-mode
49   * files: *.sh *.pl *.pm *config bootstrap Makefile
50   * identifier: # <comment> end-of-line
51 * tex-mode
52   * files: *.tex *.m
53   * identifier: % <comment> end-of-line
54 * jsp-mode
55   * files: *.jsp
56   * identifier: <!-- <comment> -->
57   * identifier: <%-- <comment> --%>
58 * sgml-mode
59   * files: *.sgml, *.html, *.shtml, *.xml, *.xsl, *.xsd, *.css, and *.rss
60   * identifier: <!-- <comment> -->
61 * text-mode
62   * files: all files not matching any other mode
63   * identifier: not applicable. All text is considered comments,
64     i.e., lines are either ''comments'' or ''other''
[342]66There is one exception to these rules. If the files name ends with
67`.in`, the trailing `.in` is ignored and the file name rules above are
68applied on the remaining part of the file name. An example is
69`test/` that is parsed using the shell-mode rules.
[341]71== Different file types ==
[46]73There are many different types of files and for many file types it
[3]74does not make sense to define lines. Source code, documentation, and
[185]75other human readable files can be treated in single line basis whereas
76symbolic links and binary files cannot. svndigest treats binary files
77as zero-line files, whereas symbolic links are treated as one-line
[188]78files. There is a possibility to exclude files from the statistics, the
[185]79use of the property svndigest:ignore.
[189]81Sometimes large test files and XML files are added to the repository
[185]82that should not really be counted in the statistics. This is solved
83with the svndigest:ignore property. Files with this property are
[187]84excluded from statistics. Setting the svndigest:ignore property to a
[185]85directory will exclude all siblings to that directory from svndigest
[341]88== Prerequisites ==
[341]90Svndigest runs against a working copy (WC), i.e., svndigest will not
91run directly against a repository. Svndigest requires that the WC is
92pristine before running the analysis, i.e., no files are allowed to be
93modified. We also recommend that the WC is in synch with the
94repository. Issue `svn update` before running svndigest.
[341]96== Flow of the program ==
[3]97The current flow of the program is.
[341]99  * Check that we are working with a WC in subversion control.
[341]101  * Build the requested directory structure ignoring not subversion
102    controlled items. During the directory structure creation a check
103    is made that the WC is up to date with the repository.
[341]105  * Walk through the directory structure and calculate statistics for
106    each entry.
[341]108  * Create the plots and HTML presentation.
112Copyright (C) 2005 Jari Häkkinen
113Copyright (C) 2006 Jari Häkkinen, Peter Johansson
114Copyright (C) 2007 Peter Johansson
116This file is part of svndigest,
118svndigest is free software; you can redistribute it and/or modify it
119under the terms of the GNU General Public License as published by the
120Free Software Foundation; either version 2 of the License, or (at your
121option) any later version.
123svndigest is distributed in the hope that it will be useful, but
124WITHOUT ANY WARRANTY; without even the implied warranty of
126General Public License for more details.
128You should have received a copy of the GNU General Public License
129along with this program; if not, write to the Free Software
130Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
Note: See TracBrowser for help on using the repository browser.