doc/readme.txt

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

Generated on Thu Jul 20 08:38:24 2023 (UTC) by svndigest 0.12pre (dev build 1672)