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 commandline when running the
  36 metric.
  37
  38 The following optiosn are available:
  39 * 'GitStats.branch_filter', this defines the regexp that,
  40 when matched, indicates that a branch is a maintenance
  41 branch. When not set, the branch check will be skipped.
  42
  43 * 'GitStats.branch_filter_rating', the amount by which the
  44 'bugfix rating' should be increased when the above filter
  45 matches on a certain commit.
  46
  47 * 'GitStats.debug', whether to enable debug information.
  48
  49 * 'GitStats.diff_filter', this defines the regexp that,
  50 when matched, indicates that a commit is a bugfix.
  51
  52 * 'GitStats.diff_filter_rating', the amount by which the
  53 'bugfix rating' should be increased when the above filter
  54 matches on a certain commit.
  55
  56 * 'GitStats.msg_filter', this defines the regexp that,
  57 when matched, indicates that a commit is a bugfix.
  58
  59 * 'GitStats.msg_filter_rating', the amount by which the
  60 'bugfix rating' should be increased when the above filter
  61 matches on a certain commit.
  62
  63 * 'GitStats.ignore_parents', when set, the ancestry of each
  64 commit will be retrieved during the 'belongs to' metric,
  65 which cuts down execution time by a lot on large repo's,
  66 but causes a slow down on small repo's. When unset, it
  67 defaults to disabled for repo's with less than 1000
  68 commits, and is enabled for those larger than 1000.
  69
  70 * 'GitStats.limit', the amount of commits that should be
  71 examined by default by 'stats.py bug -a', this defaults
  72 to 10, but can be set to a higher value for small repo's.
  73
  74 * 'GitStats.revert_rating', the amount by which the
  75 'bugfix rating' should be increased when the above filter
  76 matches on a certain commit.
  77
  78 Currently the available metrics in the bug module are the
  79 following:
  80 * Determine whether a specific commit is a bugfix based on
  81   other metrics. When one of the metrics is 'positive',
  82   that is, it's return value indicates that the examined
  83   commit is a bugfix, the 'bugfix rating' is increased by
  84   a pre-configured amount. This amount can be specified per
  85   metric, and can be set to '0' to ignore it.
  86
  87 * Aggregate the above metric over the past N commits. Also,
  88   when running the above metric on more than one commit,
  89   cache the result of calls to the git binary so that the
  90   execution time is reduced. This means that the execution
  91   time is not directly proportional to the size of the
  92   repository. (Instead, there is a fixed 'start up' cost,
  93   after which there is a 'per commit' cost, which is
  94   relatively low.)
  95
  96 This module does not define any auxillery functions.
  97