source: trunk/doc/readme.txt @ 525

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

improved text a bit

  • 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 525 2007-12-25 03:06:14Z 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
[519]25see also: http://trac.thep.lu.se/svndigest/wiki/StatsType
[495]26
[341]27== Different linetypes ==
[188]28
[524]29Svndigest parses each file to decide whether a line is ''code'',
30''comment'', or ''other''. Depending on the file name different
[341]31parsing modes are used, which means different sets of rules what is
[524]32''code'' or ''comment'' are employed. Common for all modes is that
[341]33comment blocks are identified by a start code (e.g. '/*' in a C file)
34and a stop code (e.g. '*/' in a C file). If a line contains
[505]35visible characters being outside comment blocks, the line is
[341]36considered to be ''code''. Otherwise, if the line contains
37alphanumeric characters inside a comment block, the line is considered
38to be a line of ''comment''. Otherwise the line is considered to be
[524]39''other''.
[188]40
[525]41From svndigest 0.7, it is possible to set the configuration file which
42rules are used for different files. For more on how to configure
43svndigest see below. If no configuration file is given or no rules are
44given, a set of default rules are used. For files named `*.h`, for
45example, rules allowing to detect comments as either `// ... \n` or
46`/* ... */`. These rules can be set in the configuration file using a
47one-liner like:
[188]48
[524]49`*.h = "//":"\n"  ;  "/*":"*/"`
[342]50
[525]51The first string (`*.h`) is a file-name-pattern describing which files
[524]52this rule will be used on. The second block, `"//":"\n"`, is the first
53rule saying one way to mark comments is to start with a ''start
54code'', `//`, and end with an ''end code'', `\n`. The start and end
55codes are surrounded by `""` and separated by `:`. Similarily, the
[525]56second block describes that comments also could come as `/* ... */`.
[524]57
[525]58For a more detailed illustration, please have a look at `config` that
59can be found in directory `.svndigest`, and the svndigest screenshots
60that can be reached through http://trac.thep.lu.se/svndigest/.
61
[341]62== Different file types ==
[188]63
[46]64There are many different types of files and for many file types it
[3]65does not make sense to define lines. Source code, documentation, and
[185]66other human readable files can be treated in single line basis whereas
67symbolic links and binary files cannot. svndigest treats binary files
[361]68and symbolic links as zero-line files. There is a possibility to
69exclude files from the statistics, the use of the property
70svndigest:ignore.
[3]71
[189]72Sometimes large test files and XML files are added to the repository
[185]73that should not really be counted in the statistics. This is solved
74with the svndigest:ignore property. Files with this property are
[187]75excluded from statistics. Setting the svndigest:ignore property to a
[185]76directory will exclude all siblings to that directory from svndigest
77treatment.
[3]78
[351]79== Configuration ==
80
[439]81The configuration file may be used to define various behaviors for
[351]82svndigest. By default svndigest looks for a config file named `config`
83in directory `<root-dir>/.svndigest` (<root-dir> is directory set by
84option `--root`). If no such file is found, svndigest behaves as
85default. Which file to be used as config file may also be set with
86option `--config-file`. To update an old config file you can use the
87option `--generate-config`. With this option set the used
88configuration will be written to standard output. If new variables has
89been added to configuration of svndigest, these variables will be
90written with default values. Note: if you have added a comment (e.g. a
[353]91subversion keyword) to your old config file, this will not be
[351]92inherited to the new config file. To preserve such a comment you must
93merge the new config file with the old config file manually.
94
[348]95== Copyright update ==
96
97Using the option `--copyright` svndigest will try to update the
98copyright statement in each of the parsed files. The copyright
99statement is detected as the first line containing `Copyright
100(C)`. The copyright statement block is defined to start at this line
101and ends with the first following line containing no alphanumerical
[444]102characters (excluding `prefix` string preceeding `Copyright (C)`). This
[349]103copyright statement block is replaced with a new copyright statement
104generated from analyzing `svn log`. An author is considered to have
[348]105copyright of the file if (s)he has modified the file and thereby
106occurs in the log. For an example of the format of the generated
[351]107copyright statement, please have a look at the bottom of this file. By
108default the `svn user name` of the author is printed in the copyright
109statement. This may be overridden by setting a `copyright-alias` in
110the config file. In svndigest, e.g., user name `jari` is set to
111copyright-alias ''Jari Häkkinen'' and user name `peter` is set to
112copyright-alias ''Peter Johansson''. If two (or several) authors are
113given the same copyright-alias they are considered as one person in
114the copyright statement (i.e. their alias is not repeated). This may
115be useful if you want to give copyright to an organization rather than
116to individual developers.
[348]117
[352]118== TracLinks ==
119
120From svndigest 0.6 there is support for TracLinks. The root trac
121location may be set in the configuration, in which case various links
122to the trac site will be included in the resulting report. This
123includes links from revision number to the corresponding revision at
124the trac site, and various kinds of links are detected in the messages
125in `Recent Log`.
126
[341]127== Prerequisites ==
[3]128
[341]129Svndigest runs against a working copy (WC), i.e., svndigest will not
130run directly against a repository. Svndigest requires that the WC is
131pristine before running the analysis, i.e., no files are allowed to be
132modified. We also recommend that the WC is in synch with the
133repository. Issue `svn update` before running svndigest.
[185]134
[341]135== Flow of the program ==
[3]136The current flow of the program is.
137
[341]138  * Check that we are working with a WC in subversion control.
[3]139
[520]140  * Build the requested directory structure ignoring not subversion
141    controlled items. During the directory structure creation a check
142    is made that the WC is up to date with the repository.
[3]143
[341]144  * Walk through the directory structure and calculate statistics for
145    each entry.
[3]146
[341]147  * Create the plots and HTML presentation.
148
149----------------------------------------------------------------------
150{{{
151Copyright (C) 2005 Jari Häkkinen
152Copyright (C) 2006 Jari Häkkinen, Peter Johansson
153Copyright (C) 2007 Peter Johansson
154
[519]155This file is part of svndigest, http://trac.thep.lu.se/svndigest
[341]156
157svndigest is free software; you can redistribute it and/or modify it
158under the terms of the GNU General Public License as published by the
159Free Software Foundation; either version 2 of the License, or (at your
160option) any later version.
161
162svndigest is distributed in the hope that it will be useful, but
163WITHOUT ANY WARRANTY; without even the implied warranty of
164MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
165General Public License for more details.
166
167You should have received a copy of the GNU General Public License
168along with this program; if not, write to the Free Software
169Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
170USA.
171}}}
172
173
Note: See TracBrowser for help on using the repository browser.