source: branches/0.8-stable/doc/readme.txt @ 1185

Last change on this file since 1185 was 1185, checked in by Peter Johansson, 11 years ago


  • 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: 11.9 KB
[3]1$Id: readme.txt 1185 2010-08-26 04:30:08Z peter $
[978]3Copyright (C) 2005 Jari Häkkinen
4Copyright (C) 2006, 2007, 2008 Jari Häkkinen, Peter Johansson
[1017]5Copyright (C) 2009, 2010 Peter Johansson
[813]7This file is part of svndigest,
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.
14svndigest is distributed in the hope that it will be useful, but
15WITHOUT ANY WARRANTY; without even the implied warranty of
17General Public License for more details.
19You should have received a copy of the GNU General Public License
20along with svndigest. If not, see <>.
[341]24= About svndigest =
[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
[341]32== Statistics ==
[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.
[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.
[687]46see also:
[341]48== Different linetypes ==
[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
[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:
[524]70`*.h = "//":"\n"  ;  "/*":"*/"`
[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 `/* ... */`.
[526]79Sometimes it might be useful if a file could be parsed as though it
80was going under a different name. It could, for example, be useful if
81files named `` could be parsed as `Makefile` or files named
82`` could be parsed as though it was named
83``. More generally, it would be useful if files named
84`<file-name-pattern>.in` could be parsed as though it was named
85`<file-name-pattern>`. For this reason it is possible to set rules on
86how a filename should be interpreted (see section
87[file-name-dictionary] in configuration file). Default behaviour is
88that there is only one such a rule in use, namely the one described
89above that trailing `.in` in file names are discarded.
[833]92== Caching Statistics ==
94To avoid retrieving the same data repeatedly from the repository,
[959]95statistics is cached in files located in `.svndigest`. Subsequent
[833]96svndigest runs read the cache files and retrieve information from the
97repository only for the revisions that have been committed since the
98cache file was created. Obviously, it is important that the cache
99files reflect the history of the current working copy. If that is not
100the case, for example, if you have switched working copy using `svn
101switch`, you can make svndigest ignore the cache through option
[1122]102`--ignore-cache`. From svndigest 0.8 the cache file contains
103information on the configuration (e.g. codons) used to create the
104statistics.  If that configuration is different from the current one,
105the cache file is ignored and statistics is retrieved from repository.
[341]108== Different file types ==
[46]110There are many different types of files and for many file types it
[3]111does not make sense to define lines. Source code, documentation, and
[185]112other human readable files can be treated in single line basis whereas
113symbolic links and binary files cannot. svndigest treats binary files
[361]114and symbolic links as zero-line files. There is a possibility to
115exclude files from the statistics, the use of the property
[189]118Sometimes large test files and XML files are added to the repository
[185]119that should not really be counted in the statistics. This is solved
120with the svndigest:ignore property. Files with this property are
[187]121excluded from statistics. Setting the svndigest:ignore property to a
[185]122directory will exclude all siblings to that directory from svndigest
[711]125To set the property on file `FILE`, issue `svn propset
126svndigest:ignore "" FILE`. For more detailed information refer to
[351]129== Configuration ==
[439]131The configuration file may be used to define various behaviors for
[351]132svndigest. By default svndigest looks for a config file named `config`
133in directory `<root-dir>/.svndigest` (<root-dir> is directory set by
134option `--root`). If no such file is found, svndigest behaves as
135default. Which file to be used as config file may also be set with
[1103]136option `--config-file`. This option can also be used to avoid picking
137up a configuration file in `<root-dir>/.svndigest`; issue
138`--config-file=/dev/null` and the default configuration will be
139used. To update an old config file you can use the option
140`--generate-config`. With this option set the used configuration
141will be written to standard output. If new variables has
[351]142been added to configuration of svndigest, these variables will be
143written with default values. Note: if you have added a comment (e.g. a
[353]144subversion keyword) to your old config file, this will not be
[351]145inherited to the new config file. To preserve such a comment you must
146merge the new config file with the old config file manually.
[970]148The color used for each author in plots and blame output can be
149configured in section [author-color] in config file. The format of the
150color string is a 6-digit hexadecimal number in which each color (red,
151green and blue) is decribed by 2 digits, i.e. each color is described
152by a value between 0 and 255 in hexadecimal format. It is also allowed
153to set the color with a 3-digit hexadecimal number in which case, for
154example, 'a5b' would be equivalent to 'aa55bb'.
[1009]156The format of images in the report can be configured in section
157[image]. Allowed formats are `png`, `svg`, and `none` where the latter
158implies that images are not created.
[348]160== Copyright update ==
162Using the option `--copyright` svndigest will try to update the
163copyright statement in each of the parsed files. The copyright
164statement is detected as the first line containing `Copyright
165(C)`. The copyright statement block is defined to start at this line
166and ends with the first following line containing no alphanumerical
[444]167characters (excluding `prefix` string preceeding `Copyright (C)`). This
[349]168copyright statement block is replaced with a new copyright statement
169generated from analyzing `svn log`. An author is considered to have
[348]170copyright of the file if (s)he has modified the file and thereby
171occurs in the log. For an example of the format of the generated
[351]172copyright statement, please have a look at the bottom of this file. By
173default the `svn user name` of the author is printed in the copyright
174statement. This may be overridden by setting a `copyright-alias` in
175the config file. In svndigest, e.g., user name `jari` is set to
[980]176copyright-alias ''Jari Häkkinen'' and user name `peter` is set to
[351]177copyright-alias ''Peter Johansson''. If two (or several) authors are
178given the same copyright-alias they are considered as one person in
179the copyright statement (i.e. their alias is not repeated). This may
180be useful if you want to give copyright to an organization rather than
181to individual developers.
[352]183== TracLinks ==
185From svndigest 0.6 there is support for TracLinks. The root trac
186location may be set in the configuration, in which case various links
187to the trac site will be included in the resulting report. This
188includes links from revision number to the corresponding revision at
189the trac site, and various kinds of links are detected in the messages
190in `Recent Log`.
[341]192== Prerequisites ==
[341]194Svndigest runs against a working copy (WC), i.e., svndigest will not
195run directly against a repository. Svndigest requires that the WC is
196pristine before running the analysis, i.e., no files are allowed to be
197modified. We also recommend that the WC is in synch with the
198repository. Issue `svn update` before running svndigest.
[341]200== Flow of the program ==
[3]201The current flow of the program is.
[341]203  * Check that we are working with a WC in subversion control.
[520]205  * Build the requested directory structure ignoring not subversion
206    controlled items. During the directory structure creation a check
207    is made that the WC is up to date with the repository.
[341]209  * Walk through the directory structure and calculate statistics for
210    each entry.
[341]212  * Create the plots and HTML presentation.
[959]214= Copy Cache =
216As explained above, statistics are cached during a run and svndigest
217only communicates with the server to retrieve statistics of the
218activity since last run. Subsequent runs are much faster why it is
219prefereble to run svndigest in a wc with recent cache available.
221Sometimes it is useful to copy the cache from one wc to another, and
222an easy way to do this is to use the tool `svndigest-copy-cache`,
223which is shipped with svndigest. A common use case is when creating,
224say, a release branch from the trunk, in which case you likely will
225have two working copies to follow the two branches. If you want to run
226svndigest on both of them and you want to avoid the first expensive
227run (without cache) you can copy the cache from the trunk wc to the
228release-branch wc.
230As explained in the caching section, it is important that the cache
231reflects a revision that belong to the history of the wc. So, for
232example, when creating a branch it is crucial to copy the cache from
233the trunk wc to the new branch wc before running svndigest on trunk
234wc. Otherwise the cache will contain information about changesets that
235were committed after the new branch were forked out. This will not
236only be untrue as these changesets are not in the line of history of
237the branch, but it will also cause problems for svndigest when
238calculating the statistics of the most recent revisons and result is
239undefined due to inconsistency between the cache and the log. For an
240example of how `svndigest-copy-cache` may be used please refer to the
241ReleaseProcedure of svndigest.
243`svndigest-copy-cache` copies the cache file from `ROOT` tree to the
244corresponding directory in `TARGET` tree. The tree structure of the
245two working copies must be identical because `svndigest-copy-cache`
246will not create any directories in `TARGET` tree except that
247`.svndigest` directories are created when necessary.
249Also, `svndigest-copy-cache` is ignorant about svn wc and will parse
[1185]250through `ROOT` directory and all its sub-directories, looking for
[959]251svndigest cache files, regardless whether they belong to the same svn
252working copy or not. Therefore, having other svn wc in subdirectories
253of `ROOT` might give an unexpected result.
Note: See TracBrowser for help on using the repository browser.