source: trunk/doc/readme.txt @ 693

Last change on this file since 693 was 693, checked in by Jari Häkkinen, 13 years ago

Fixes #339. Change to GPLv3.

  • 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: 8.3 KB
RevLine 
[3]1$Id: readme.txt 693 2008-09-11 20:42:56Z jari $
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
[687]25see also: http://dev.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
[526]41From svndigest 0.7, it is possible to configure which rules are used
42for different files. For more on how to configure svndigest see
43below. If no configuration file is given or no rules are given, a set
44of default rules are used. For files named `*.h`, for example, rules
45allowing to detect comments as either `// ... \n` or `/*
46... */`. These rules can be set in the configuration file using a
[525]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
[687]60that can be reached through http://dev.thep.lu.se/svndigest/.
[525]61
[526]62Sometimes it might be useful if a file could be parsed as though it
63was going under a different name. It could, for example, be useful if
64files named `Makefile.in` could be parsed as `Makefile` or files named
65`test_repo.sh.in` could be parsed as though it was named
66`test_repo.sh`. More generally, it would be useful if files named
67`<file-name-pattern>.in` could be parsed as though it was named
68`<file-name-pattern>`. For this reason it is possible to set rules on
69how a filename should be interpreted (see section
70[file-name-dictionary] in configuration file). Default behaviour is
71that there is only one such a rule in use, namely the one described
72above that trailing `.in` in file names are discarded.
73
74
[341]75== Different file types ==
[188]76
[46]77There are many different types of files and for many file types it
[3]78does not make sense to define lines. Source code, documentation, and
[185]79other human readable files can be treated in single line basis whereas
80symbolic links and binary files cannot. svndigest treats binary files
[361]81and symbolic links as zero-line files. There is a possibility to
82exclude files from the statistics, the use of the property
83svndigest:ignore.
[3]84
[189]85Sometimes large test files and XML files are added to the repository
[185]86that should not really be counted in the statistics. This is solved
87with the svndigest:ignore property. Files with this property are
[187]88excluded from statistics. Setting the svndigest:ignore property to a
[185]89directory will exclude all siblings to that directory from svndigest
90treatment.
[3]91
[351]92== Configuration ==
93
[439]94The configuration file may be used to define various behaviors for
[351]95svndigest. By default svndigest looks for a config file named `config`
96in directory `<root-dir>/.svndigest` (<root-dir> is directory set by
97option `--root`). If no such file is found, svndigest behaves as
98default. Which file to be used as config file may also be set with
99option `--config-file`. To update an old config file you can use the
100option `--generate-config`. With this option set the used
101configuration will be written to standard output. If new variables has
102been added to configuration of svndigest, these variables will be
103written with default values. Note: if you have added a comment (e.g. a
[353]104subversion keyword) to your old config file, this will not be
[351]105inherited to the new config file. To preserve such a comment you must
106merge the new config file with the old config file manually.
107
[348]108== Copyright update ==
109
110Using the option `--copyright` svndigest will try to update the
111copyright statement in each of the parsed files. The copyright
112statement is detected as the first line containing `Copyright
113(C)`. The copyright statement block is defined to start at this line
114and ends with the first following line containing no alphanumerical
[444]115characters (excluding `prefix` string preceeding `Copyright (C)`). This
[349]116copyright statement block is replaced with a new copyright statement
117generated from analyzing `svn log`. An author is considered to have
[348]118copyright of the file if (s)he has modified the file and thereby
119occurs in the log. For an example of the format of the generated
[351]120copyright statement, please have a look at the bottom of this file. By
121default the `svn user name` of the author is printed in the copyright
122statement. This may be overridden by setting a `copyright-alias` in
123the config file. In svndigest, e.g., user name `jari` is set to
124copyright-alias ''Jari Häkkinen'' and user name `peter` is set to
125copyright-alias ''Peter Johansson''. If two (or several) authors are
126given the same copyright-alias they are considered as one person in
127the copyright statement (i.e. their alias is not repeated). This may
128be useful if you want to give copyright to an organization rather than
129to individual developers.
[348]130
[352]131== TracLinks ==
132
133From svndigest 0.6 there is support for TracLinks. The root trac
134location may be set in the configuration, in which case various links
135to the trac site will be included in the resulting report. This
136includes links from revision number to the corresponding revision at
137the trac site, and various kinds of links are detected in the messages
138in `Recent Log`.
139
[341]140== Prerequisites ==
[3]141
[341]142Svndigest runs against a working copy (WC), i.e., svndigest will not
143run directly against a repository. Svndigest requires that the WC is
144pristine before running the analysis, i.e., no files are allowed to be
145modified. We also recommend that the WC is in synch with the
146repository. Issue `svn update` before running svndigest.
[185]147
[341]148== Flow of the program ==
[3]149The current flow of the program is.
150
[341]151  * Check that we are working with a WC in subversion control.
[3]152
[520]153  * Build the requested directory structure ignoring not subversion
154    controlled items. During the directory structure creation a check
155    is made that the WC is up to date with the repository.
[3]156
[341]157  * Walk through the directory structure and calculate statistics for
158    each entry.
[3]159
[341]160  * Create the plots and HTML presentation.
161
162----------------------------------------------------------------------
163{{{
164Copyright (C) 2005 Jari Häkkinen
165Copyright (C) 2006 Jari Häkkinen, Peter Johansson
166Copyright (C) 2007 Peter Johansson
167
[687]168This file is part of svndigest, http://dev.thep.lu.se/svndigest
[341]169
170svndigest is free software; you can redistribute it and/or modify it
171under the terms of the GNU General Public License as published by the
[693]172Free Software Foundation; either version 3 of the License, or (at your
[341]173option) any later version.
174
175svndigest is distributed in the hope that it will be useful, but
176WITHOUT ANY WARRANTY; without even the implied warranty of
177MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
178General Public License for more details.
179
180You should have received a copy of the GNU General Public License
[693]181along with svndigest. If not, see <http://www.gnu.org/licenses/>.
[341]182}}}
Note: See TracBrowser for help on using the repository browser.