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