source: trunk/doc/readme.txt @ 809

Last change on this file since 809 was 768, checked in by Peter Johansson, 13 years ago

Merged patch release 0.6.7 to trunk. Delta 0.6.7 - 0.6.6

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