source: branches/replacing_gnuplot/doc/readme.txt @ 866

Last change on this file since 866 was 857, checked in by Jari Häkkinen, 12 years ago

Merged trunk changes -r844:855 to replacing_gnuplot branch.

  • 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.9 KB
RevLine 
[3]1$Id: readme.txt 857 2009-11-19 15:28:56Z jari $
[845]2{{{
3Copyright (C) 2005 Jari Häkkinen
[857]4Copyright (C) 2006, 2007, 2008 Jari Häkkinen, Peter Johansson
5Copyright (C) 2009 Peter Johansson
[3]6
[845]7This file is part of svndigest, http://dev.thep.lu.se/svndigest
8
9svndigest is free software; you can redistribute it and/or modify it
10under the terms of the GNU General Public License as published by the
11Free Software Foundation; either version 3 of the License, or (at your
12option) any later version.
13
14svndigest is distributed in the hope that it will be useful, but
15WITHOUT ANY WARRANTY; without even the implied warranty of
16MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17General Public License for more details.
18
19You should have received a copy of the GNU General Public License
20along with svndigest. If not, see <http://www.gnu.org/licenses/>.
21}}}
22
23
[341]24= About svndigest =
[84]25
[341]26Svndigest traverses a directory structure (controlled by subversion)
[149]27and calculates developer statistics for all subversion controlled
[187]28entries. The result is written to a sub-directory of a user
[188]29specifiable target directory (default is the current working
[185]30directory).
[3]31
[341]32== Statistics ==
33
[149]34To understand what statistics is calculated by svndigest this
35definition is needed: The developer who made the latest change to a
[185]36line still in use in the latest revision, is considered as the
37contributor of that line regardless of who actually originally created
38that line.
[3]39
[188]40For each developer svndigest calculates the number of contributed
[189]41lines in the latest (checked out) revision. Svndigest calculates for
42each revision, by checking when each line was last changed, how many
43lines each developer had contributed at that specific revision and
[341]44still are in use.
[3]45
[784]46see also: http://dev.thep.lu.se/svndigest/wiki/StatsType
[495]47
[341]48== Different linetypes ==
[188]49
[524]50Svndigest parses each file to decide whether a line is ''code'',
51''comment'', or ''other''. Depending on the file name different
[341]52parsing modes are used, which means different sets of rules what is
[524]53''code'' or ''comment'' are employed. Common for all modes is that
[341]54comment blocks are identified by a start code (e.g. '/*' in a C file)
55and a stop code (e.g. '*/' in a C file). If a line contains
[505]56visible characters being outside comment blocks, the line is
[341]57considered to be ''code''. Otherwise, if the line contains
58alphanumeric characters inside a comment block, the line is considered
59to be a line of ''comment''. Otherwise the line is considered to be
[524]60''other''.
[188]61
[526]62From svndigest 0.7, it is possible to configure which rules are used
63for different files. For more on how to configure svndigest see
64below. If no configuration file is given or no rules are given, a set
65of default rules are used. For files named `*.h`, for example, rules
66allowing to detect comments as either `// ... \n` or `/*
67... */`. These rules can be set in the configuration file using a
[525]68one-liner like:
[188]69
[524]70`*.h = "//":"\n"  ;  "/*":"*/"`
[342]71
[525]72The first string (`*.h`) is a file-name-pattern describing which files
[524]73this rule will be used on. The second block, `"//":"\n"`, is the first
74rule saying one way to mark comments is to start with a ''start
75code'', `//`, and end with an ''end code'', `\n`. The start and end
76codes are surrounded by `""` and separated by `:`. Similarily, the
[525]77second block describes that comments also could come as `/* ... */`.
[524]78
[525]79For a more detailed illustration, please have a look at `config` that
80can be found in directory `.svndigest`, and the svndigest screenshots
[784]81that can be reached through http://dev.thep.lu.se/svndigest/.
[525]82
[526]83Sometimes it might be useful if a file could be parsed as though it
84was going under a different name. It could, for example, be useful if
85files named `Makefile.in` could be parsed as `Makefile` or files named
86`test_repo.sh.in` could be parsed as though it was named
87`test_repo.sh`. More generally, it would be useful if files named
88`<file-name-pattern>.in` could be parsed as though it was named
89`<file-name-pattern>`. For this reason it is possible to set rules on
90how a filename should be interpreted (see section
91[file-name-dictionary] in configuration file). Default behaviour is
92that there is only one such a rule in use, namely the one described
93above that trailing `.in` in file names are discarded.
94
95
[845]96== Caching Statistics ==
97
98To avoid retrieving the same data repeatedly from the repository,
99statistics is cahed in files located in `.svndigest`. Subsequent
100svndigest runs read the cache files and retrieve information from the
101repository only for the revisions that have been committed since the
102cache file was created. Obviously, it is important that the cache
103files reflect the history of the current working copy. If that is not
104the case, for example, if you have switched working copy using `svn
105switch`, you can make svndigest ignore the cache through option
106`--ignore-cache`.
107
108
[341]109== Different file types ==
[188]110
[46]111There are many different types of files and for many file types it
[3]112does not make sense to define lines. Source code, documentation, and
[185]113other human readable files can be treated in single line basis whereas
114symbolic links and binary files cannot. svndigest treats binary files
[361]115and symbolic links as zero-line files. There is a possibility to
116exclude files from the statistics, the use of the property
[784]117svndigest:ignore.
[3]118
[189]119Sometimes large test files and XML files are added to the repository
[185]120that should not really be counted in the statistics. This is solved
121with the svndigest:ignore property. Files with this property are
[187]122excluded from statistics. Setting the svndigest:ignore property to a
[185]123directory will exclude all siblings to that directory from svndigest
124treatment.
[3]125
[784]126To set the property on file `FILE`, issue `svn propset
127svndigest:ignore "" FILE`. For more detailed information refer to
128http://svnbook.red-bean.com/.
129
[351]130== Configuration ==
131
[439]132The configuration file may be used to define various behaviors for
[351]133svndigest. By default svndigest looks for a config file named `config`
134in directory `<root-dir>/.svndigest` (<root-dir> is directory set by
135option `--root`). If no such file is found, svndigest behaves as
136default. Which file to be used as config file may also be set with
137option `--config-file`. To update an old config file you can use the
138option `--generate-config`. With this option set the used
139configuration will be written to standard output. If new variables has
140been added to configuration of svndigest, these variables will be
141written with default values. Note: if you have added a comment (e.g. a
[353]142subversion keyword) to your old config file, this will not be
[351]143inherited to the new config file. To preserve such a comment you must
144merge the new config file with the old config file manually.
145
[348]146== Copyright update ==
147
148Using the option `--copyright` svndigest will try to update the
149copyright statement in each of the parsed files. The copyright
150statement is detected as the first line containing `Copyright
151(C)`. The copyright statement block is defined to start at this line
152and ends with the first following line containing no alphanumerical
[444]153characters (excluding `prefix` string preceeding `Copyright (C)`). This
[349]154copyright statement block is replaced with a new copyright statement
155generated from analyzing `svn log`. An author is considered to have
[348]156copyright of the file if (s)he has modified the file and thereby
157occurs in the log. For an example of the format of the generated
[351]158copyright statement, please have a look at the bottom of this file. By
159default the `svn user name` of the author is printed in the copyright
160statement. This may be overridden by setting a `copyright-alias` in
161the config file. In svndigest, e.g., user name `jari` is set to
162copyright-alias ''Jari Häkkinen'' and user name `peter` is set to
163copyright-alias ''Peter Johansson''. If two (or several) authors are
164given the same copyright-alias they are considered as one person in
165the copyright statement (i.e. their alias is not repeated). This may
166be useful if you want to give copyright to an organization rather than
167to individual developers.
[348]168
[352]169== TracLinks ==
170
171From svndigest 0.6 there is support for TracLinks. The root trac
172location may be set in the configuration, in which case various links
173to the trac site will be included in the resulting report. This
174includes links from revision number to the corresponding revision at
175the trac site, and various kinds of links are detected in the messages
176in `Recent Log`.
177
[341]178== Prerequisites ==
[3]179
[341]180Svndigest runs against a working copy (WC), i.e., svndigest will not
181run directly against a repository. Svndigest requires that the WC is
182pristine before running the analysis, i.e., no files are allowed to be
183modified. We also recommend that the WC is in synch with the
184repository. Issue `svn update` before running svndigest.
[185]185
[341]186== Flow of the program ==
[3]187The current flow of the program is.
188
[341]189  * Check that we are working with a WC in subversion control.
[3]190
[520]191  * Build the requested directory structure ignoring not subversion
192    controlled items. During the directory structure creation a check
193    is made that the WC is up to date with the repository.
[3]194
[341]195  * Walk through the directory structure and calculate statistics for
196    each entry.
[3]197
[341]198  * Create the plots and HTML presentation.
199
Note: See TracBrowser for help on using the repository browser.