source: branches/0.6-stable/doc/readme.txt @ 456

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

fixed typo

  • 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: 7.7 KB
RevLine 
[3]1$Id: readme.txt 432 2007-07-07 00:12:29Z peter $
2
[341]3= About svndigest =
[84]4
[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
[185]9directory).
[3]10
[341]11== Statistics ==
12
[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.
[3]18
[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.
[3]24
[341]25== Different linetypes ==
[188]26
[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
38used:
[188]39
[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''
[188]65
[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/test_repo.sh.in` that is parsed using the shell-mode rules.
70
[341]71== Different file types ==
[188]72
[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
[361]77and symbolic links as zero-line files. There is a possibility to
78exclude files from the statistics, the use of the property
79svndigest:ignore.
[3]80
[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
86treatment.
[3]87
[351]88== Configuration ==
89
[432]90The configuration file may be used to define various behaviors for
[351]91svndigest. By default svndigest looks for a config file named `config`
92in directory `<root-dir>/.svndigest` (<root-dir> is directory set by
93option `--root`). If no such file is found, svndigest behaves as
94default. Which file to be used as config file may also be set with
95option `--config-file`. To update an old config file you can use the
96option `--generate-config`. With this option set the used
97configuration will be written to standard output. If new variables has
98been added to configuration of svndigest, these variables will be
99written with default values. Note: if you have added a comment (e.g. a
[353]100subversion keyword) to your old config file, this will not be
[351]101inherited to the new config file. To preserve such a comment you must
102merge the new config file with the old config file manually.
103
[348]104== Copyright update ==
105
106Using the option `--copyright` svndigest will try to update the
107copyright statement in each of the parsed files. The copyright
108statement is detected as the first line containing `Copyright
109(C)`. The copyright statement block is defined to start at this line
110and ends with the first following line containing no alphanumerical
111characters (i.e. line is treated as `other` in statistics). This
[349]112copyright statement block is replaced with a new copyright statement
113generated from analyzing `svn log`. An author is considered to have
[348]114copyright of the file if (s)he has modified the file and thereby
115occurs in the log. For an example of the format of the generated
[351]116copyright statement, please have a look at the bottom of this file. By
117default the `svn user name` of the author is printed in the copyright
118statement. This may be overridden by setting a `copyright-alias` in
119the config file. In svndigest, e.g., user name `jari` is set to
120copyright-alias ''Jari Häkkinen'' and user name `peter` is set to
121copyright-alias ''Peter Johansson''. If two (or several) authors are
122given the same copyright-alias they are considered as one person in
123the copyright statement (i.e. their alias is not repeated). This may
124be useful if you want to give copyright to an organization rather than
125to individual developers.
[348]126
[352]127== TracLinks ==
128
129From svndigest 0.6 there is support for TracLinks. The root trac
130location may be set in the configuration, in which case various links
131to the trac site will be included in the resulting report. This
132includes links from revision number to the corresponding revision at
133the trac site, and various kinds of links are detected in the messages
134in `Recent Log`.
135
[341]136== Prerequisites ==
[3]137
[341]138Svndigest runs against a working copy (WC), i.e., svndigest will not
139run directly against a repository. Svndigest requires that the WC is
140pristine before running the analysis, i.e., no files are allowed to be
141modified. We also recommend that the WC is in synch with the
142repository. Issue `svn update` before running svndigest.
[185]143
[341]144== Flow of the program ==
[3]145The current flow of the program is.
146
[341]147  * Check that we are working with a WC in subversion control.
[3]148
[341]149  * Build the requested directory structure ignoring not subversion
150    controlled items. During the directory structure creation a check
151    is made that the WC is up to date with the repository.
[3]152
[341]153  * Walk through the directory structure and calculate statistics for
154    each entry.
[3]155
[341]156  * Create the plots and HTML presentation.
157
158----------------------------------------------------------------------
159{{{
160Copyright (C) 2005 Jari Häkkinen
161Copyright (C) 2006 Jari Häkkinen, Peter Johansson
162Copyright (C) 2007 Peter Johansson
163
164This file is part of svndigest, http://lev.thep.lu.se/trac/svndigest
165
166svndigest is free software; you can redistribute it and/or modify it
167under the terms of the GNU General Public License as published by the
168Free Software Foundation; either version 2 of the License, or (at your
169option) any later version.
170
171svndigest is distributed in the hope that it will be useful, but
172WITHOUT ANY WARRANTY; without even the implied warranty of
173MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
174General Public License for more details.
175
176You should have received a copy of the GNU General Public License
177along with this program; if not, write to the Free Software
178Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
179USA.
180}}}
181
182
Note: See TracBrowser for help on using the repository browser.