doc/gitstats-bug.txt

   1 syntax: stats.py bug <options>
   2
   3 The purpose of the bug module is to gather statistics on
   4 bugfixes within the content, and to aggregate this
   5 information to provide with a report of the last N commits.
   6
   7 The metrics used in this module are:
   8 * Does a commit belong to a specific branch. This can be
   9 used, for example, to mark commits on a maintenance as
  10 bugfixes with 99% reliability. Whenever multiple refs point
  11 to the same commit though, the first ref passed by
  12 'git for-each-ref' will be listed if that commit is the one
  13 the searched commit belongs to. As such, you need to make
  14 sure your regexp catches those refs.
  15
  16 * Does a commit fully revert another one. That is, if you
  17 make a commit, and then revert it, the revert will be
  18 detected as having reverted the earlier commit.
  19
  20 * Does the commit message match a certain regexp. For
  21 example, if it contains the word "fixes", mark it as a fix.
  22
  23 * Does the commit diff match a specified regexp. A change
  24 from "test_expect_failure" -> "test_expect_success" could
  25 indicate that the commit is a bugfix.
  26
  27 - (not tweaked yet) Does a commit partially revert another
  28 one. This needs some tweaking, otherwise small changes are
  29 quickly seen as similar. (If you have two unrelated
  30 one-liners, and you set it to ignore one difference...)
  31
  32 You have to configure a few things to get useful results.
  33 Configuration is trivially done with:
  34 'git config GitStats.key value'. It is also possible to
  35 override most options on the command-line when running the
  36 metric. The *_rating settings can be set to any integer,
  37 the relevance is in their value relative to one another.
  38 The value of each *_rating setting should represent how
  39 confident you are that a commit is a bugfix when that
  40 specific metric returns a positive result.
  41
  42 The following options are available:
  43 * 'GitStats.branch_filter', this defines the regexp that,
  44 when matched, indicates that a branch is a maintenance
  45 branch. When not set, the branch check will be skipped.
  46 Example value: 'maint'
  47
  48 * 'GitStats.branch_filter_rating', the amount by which the
  49 'bugfix rating' should be increased when the above filter
  50 matches on a certain commit.
  51
  52 * 'GitStats.debug', whether to enable debug information.
  53
  54 * 'GitStats.diff_filter', this defines the regexp that,
  55 when matched, indicates that a commit is a bugfix.
  56 Example value: 'test_expect_failure'
  57
  58 * 'GitStats.diff_filter_rating', the amount by which the
  59 'bugfix rating' should be increased when the above filter
  60 matches on a certain commit.
  61
  62 * 'GitStats.msg_filter', this defines the regexp that,
  63 when matched, indicates that a commit is a bugfix.
  64 Example value: 'fixes'
  65
  66 * 'GitStats.msg_filter_rating', the amount by which the
  67 'bugfix rating' should be increased when the above filter
  68 matches on a certain commit.
  69
  70 * 'GitStats.ignore_parents', when set, the ancestry of each
  71 commit will be retrieved during the 'belongs to' metric,
  72 which cuts down execution time by a lot on large repo's,
  73 but causes a slow down on small repo's. When unset, it
  74 defaults to disabled for repo's with less than 1000
  75 commits, and is enabled for those larger than 1000.
  76
  77 * 'GitStats.limit', the amount of commits that should be
  78 examined by default by 'stats.py bug -a', this defaults
  79 to 10, but can be set to a higher value for small repo's.
  80 Example value: For large repositories large value's might
  81 result in slow execution, the default value is pretty
  82 sane for such cases. Smaller repositories might benefit
  83 from setting it to a high value, or disabling it (by
  84 setting it to 0).
  85
  86 * 'GitStats.revert_rating', the amount by which the
  87 'bugfix rating' should be increased when the above filter
  88 matches on a certain commit.
  89
  90 Currently the available metrics in the bug module are the
  91 following:
  92 * Determine whether a specific commit is a bugfix based on
  93   other metrics. When one of the metrics is 'positive',
  94   that is, it's return value indicates that the examined
  95   commit is a bugfix, the 'bugfix rating' is increased by
  96   a pre-configured amount. This amount can be specified per
  97   metric, and can be set to '0' to ignore it.
  98
  99 * Aggregate the above metric over the past N commits. Also,
 100   when running the above metric on more than one commit,
 101   cache the result of calls to the git binary so that the
 102   execution time is reduced. This means that the execution
 103   time is not directly proportional to the size of the
 104   repository. (Instead, there is a fixed 'start up' cost,
 105   after which there is a 'per commit' cost, which is
 106   relatively low.)
 107
 108 This module does not define any auxiliary functions.
 109