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