source: trunk/doc/readme.txt

Last change on this file was 1551, checked in by Peter Johansson, 9 years ago

closes #518. svncopyright now works on characters rather than lines. That implies old cache files are obsolete and will be ignored from this revision.

  • 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: 12.3 KB
RevLine 
[3]1$Id: readme.txt 1551 2012-11-03 05:03:36Z peter $
[813]2{{{
[978]3Copyright (C) 2005 Jari Häkkinen
4Copyright (C) 2006, 2007, 2008 Jari Häkkinen, Peter Johansson
[1551]5Copyright (C) 2009, 2010, 2011, 2012 Peter Johansson
[3]6
[813]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
[1252]23= Content =
[813]24
[1252]25This manual describes how to use the three programs included in the
26svndigest package:
27
28  * svndigest
[1258]29  * svncopyright
[1252]30  * svndigest-copy-cache
31
[341]32= About svndigest =
[84]33
[341]34Svndigest traverses a directory structure (controlled by subversion)
[149]35and calculates developer statistics for all subversion controlled
[187]36entries. The result is written to a sub-directory of a user
[188]37specifiable target directory (default is the current working
[185]38directory).
[3]39
[1252]40=== Statistics ===
[341]41
[149]42To understand what statistics is calculated by svndigest this
43definition is needed: The developer who made the latest change to a
[185]44line still in use in the latest revision, is considered as the
45contributor of that line regardless of who actually originally created
46that line.
[3]47
[188]48For each developer svndigest calculates the number of contributed
[189]49lines in the latest (checked out) revision. Svndigest calculates for
50each revision, by checking when each line was last changed, how many
51lines each developer had contributed at that specific revision and
[341]52still are in use.
[3]53
[687]54see also: http://dev.thep.lu.se/svndigest/wiki/StatsType
[495]55
[1252]56=== Different linetypes ===
[188]57
[524]58Svndigest parses each file to decide whether a line is ''code'',
59''comment'', or ''other''. Depending on the file name different
[341]60parsing modes are used, which means different sets of rules what is
[524]61''code'' or ''comment'' are employed. Common for all modes is that
[341]62comment blocks are identified by a start code (e.g. '/*' in a C file)
63and a stop code (e.g. '*/' in a C file). If a line contains
[505]64visible characters being outside comment blocks, the line is
[341]65considered to be ''code''. Otherwise, if the line contains
66alphanumeric characters inside a comment block, the line is considered
67to be a line of ''comment''. Otherwise the line is considered to be
[524]68''other''.
[188]69
[526]70From svndigest 0.7, it is possible to configure which rules are used
71for different files. For more on how to configure svndigest see
72below. If no configuration file is given or no rules are given, a set
73of default rules are used. For files named `*.h`, for example, rules
74allowing to detect comments as either `// ... \n` or `/*
75... */`. These rules can be set in the configuration file using a
[525]76one-liner like:
[188]77
[524]78`*.h = "//":"\n"  ;  "/*":"*/"`
[342]79
[525]80The first string (`*.h`) is a file-name-pattern describing which files
[524]81this rule will be used on. The second block, `"//":"\n"`, is the first
82rule saying one way to mark comments is to start with a ''start
83code'', `//`, and end with an ''end code'', `\n`. The start and end
84codes are surrounded by `""` and separated by `:`. Similarily, the
[525]85second block describes that comments also could come as `/* ... */`.
[524]86
[526]87Sometimes it might be useful if a file could be parsed as though it
88was going under a different name. It could, for example, be useful if
89files named `Makefile.in` could be parsed as `Makefile` or files named
90`test_repo.sh.in` could be parsed as though it was named
91`test_repo.sh`. More generally, it would be useful if files named
92`<file-name-pattern>.in` could be parsed as though it was named
93`<file-name-pattern>`. For this reason it is possible to set rules on
94how a filename should be interpreted (see section
95[file-name-dictionary] in configuration file). Default behaviour is
96that there is only one such a rule in use, namely the one described
97above that trailing `.in` in file names are discarded.
98
99
[1252]100=== Caching Statistics ===
[833]101
102To avoid retrieving the same data repeatedly from the repository,
[959]103statistics is cached in files located in `.svndigest`. Subsequent
[833]104svndigest runs read the cache files and retrieve information from the
105repository only for the revisions that have been committed since the
106cache file was created. Obviously, it is important that the cache
107files reflect the history of the current working copy. If that is not
108the case, for example, if you have switched working copy using `svn
109switch`, you can make svndigest ignore the cache through option
[1122]110`--ignore-cache`. From svndigest 0.8 the cache file contains
111information on the configuration (e.g. codons) used to create the
112statistics.  If that configuration is different from the current one,
113the cache file is ignored and statistics is retrieved from repository.
[833]114
115
[1252]116=== Different file types ===
[188]117
[46]118There are many different types of files and for many file types it
[3]119does not make sense to define lines. Source code, documentation, and
[185]120other human readable files can be treated in single line basis whereas
121symbolic links and binary files cannot. svndigest treats binary files
[361]122and symbolic links as zero-line files. There is a possibility to
123exclude files from the statistics, the use of the property
[711]124svndigest:ignore.
[3]125
[189]126Sometimes large test files and XML files are added to the repository
[185]127that should not really be counted in the statistics. This is solved
128with the svndigest:ignore property. Files with this property are
[187]129excluded from statistics. Setting the svndigest:ignore property to a
[185]130directory will exclude all siblings to that directory from svndigest
131treatment.
[3]132
[711]133To set the property on file `FILE`, issue `svn propset
134svndigest:ignore "" FILE`. For more detailed information refer to
135http://svnbook.red-bean.com/.
136
[1252]137=== Configuration ===
[351]138
[439]139The configuration file may be used to define various behaviors for
[351]140svndigest. By default svndigest looks for a config file named `config`
141in directory `<root-dir>/.svndigest` (<root-dir> is directory set by
142option `--root`). If no such file is found, svndigest behaves as
143default. Which file to be used as config file may also be set with
[1103]144option `--config-file`. This option can also be used to avoid picking
145up a configuration file in `<root-dir>/.svndigest`; issue
146`--config-file=/dev/null` and the default configuration will be
147used. To update an old config file you can use the option
148`--generate-config`. With this option set the used configuration
149will be written to standard output. If new variables has
[351]150been added to configuration of svndigest, these variables will be
151written with default values. Note: if you have added a comment (e.g. a
[353]152subversion keyword) to your old config file, this will not be
[351]153inherited to the new config file. To preserve such a comment you must
154merge the new config file with the old config file manually.
155
[970]156The color used for each author in plots and blame output can be
157configured in section [author-color] in config file. The format of the
158color string is a 6-digit hexadecimal number in which each color (red,
159green and blue) is decribed by 2 digits, i.e. each color is described
160by a value between 0 and 255 in hexadecimal format. It is also allowed
161to set the color with a 3-digit hexadecimal number in which case, for
162example, 'a5b' would be equivalent to 'aa55bb'.
163
[1009]164The format of images in the report can be configured in section
165[image]. Allowed formats are `png`, `svg`, and `none` where the latter
166implies that images are not created.
167
[1373]168In section [output] you can adjust the size of the report. Default a
169Blame Information page is created for every file, which can be turned
170of using the 'blame-information' option. To decrease the size even
171more, option 'file' can be set to 'no' which means output will only be
172generated for directories.
173
174Section [svn-props] allows you to set properties on files (or
175directories). It is, for example, possible to set property
176'svndigest:ignore' on all files named `COPYING` using the following line
177
178COPYING = svndigest:ignore
179
180The format of this section is the same as in section [auto-props] in a
181subversion config file.
182
[1252]183=== TracLinks ===
[348]184
[352]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`.
191
[1252]192=== Prerequisites ===
[3]193
[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.
[185]199
[1252]200= About svncopyright =
[959]201
[1252]202svncopyright updates the copyright statement in subversion controlled
203files. The program detects the copyright statement and replaces it
[1551]204with a copyright statement calculated from repository statistics.
[1252]205
206The copyright statement is detected as the first line containing the
207string given in configuation variable `copyright-string` (default
208'`Copyright (C)`'). The copyright statement ends with the first
209following line containing no alphanumerical characters excluding the
210''prefix'' string that preceeds '`copyright-string`'. This copyright
211statement block is replaced with a new copyright statement generated
212from analyzing `svn blame output`. An author is considered to have
[1551]213copyright of the file if (s)he has added a non-whitespace character
[1252]214(excluding copyright statements). For an example of the format of the
215generated copyright statement, please have a look at the top of this
[1551]216file.
[1252]217
218By default the `svn user name` of the author is printed in the
219copyright statement. This may be overridden by setting a
220'`copyright-alias`' in the config file. In svndigest, for example,
221user name `jari` is set to copyright-alias ''Jari Häkkinen'' and user
222name `peter` is set to copyright-alias ''Peter Johansson''. If two (or
223several) authors are given the same copyright-alias they are
224considered as one person in the copyright statement (i.e. their alias
225is not repeated). This may be useful if you want to give copyright to
226an organization rather than to individual developers.
227
[1280]228Files and directories that have `svndigest:ignore` or
229`svncopyright:ignore` set are excluded from the copyright update.
230
[1252]231= About svndigest-copy-cache =
232
[959]233As explained above, statistics are cached during a run and svndigest
234only communicates with the server to retrieve statistics of the
235activity since last run. Subsequent runs are much faster why it is
236prefereble to run svndigest in a wc with recent cache available.
237
238Sometimes it is useful to copy the cache from one wc to another, and
239an easy way to do this is to use the tool `svndigest-copy-cache`,
240which is shipped with svndigest. A common use case is when creating,
241say, a release branch from the trunk, in which case you likely will
242have two working copies to follow the two branches. If you want to run
243svndigest on both of them and you want to avoid the first expensive
244run (without cache) you can copy the cache from the trunk wc to the
245release-branch wc.
246
247As explained in the caching section, it is important that the cache
248reflects a revision that belong to the history of the wc. So, for
249example, when creating a branch it is crucial to copy the cache from
250the trunk wc to the new branch wc before running svndigest on trunk
251wc. Otherwise the cache will contain information about changesets that
252were committed after the new branch were forked out. This will not
253only be untrue as these changesets are not in the line of history of
254the branch, but it will also cause problems for svndigest when
255calculating the statistics of the most recent revisons and result is
256undefined due to inconsistency between the cache and the log. For an
257example of how `svndigest-copy-cache` may be used please refer to the
258ReleaseProcedure of svndigest.
259
260`svndigest-copy-cache` copies the cache file from `ROOT` tree to the
261corresponding directory in `TARGET` tree. The tree structure of the
262two working copies must be identical because `svndigest-copy-cache`
263will not create any directories in `TARGET` tree except that
264`.svndigest` directories are created when necessary.
Note: See TracBrowser for help on using the repository browser.