source: trunk/doc/readme.txt

Last change on this file was 1635, checked in by Peter Johansson, 6 months ago

updating copyright statements using 0.11pre (using character-based assessment rather than line-based).

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