README

   1 GitStats is a metrics framework designed to gather
   2 statistics on git repositories. It is written in python and
   3 uses git-python to access the git binary.
   4
   5 Statistics can be useful in many ways, ranging from
   6 noticing oddities to gaining some insight in how something
   7 works. Git is specialized in storing changes made to a
   8 spicific 'unit' of content. Currently the widespread use
   9 is to store source code in it. This property can be used to
  10 gather statistics about the tracked content. This may seem
  11 strange at first, but as we all learned in school, many
  12 things can be learned from studying history. With git this
  13 history is in the form of changesets and commit messages
  14 that go with these changes. Each change belongs to one
  15 author, although it may have been reviewed by many. (Such
  16 would usually be noted in the commit message.) This means
  17 that for each content repository we have a set of changes
  18 for each author, each accompanied with a message describing
  19 what the change does. The interesting part of these
  20 messages are those that are consistent across commits.
  21
  22 For example, when a commit is subject to peer review before
  23 being comitted, it is not unusual to make note of this in
  24 the commit message. When this is done in a consistent way,
  25 for example by putting 'signed-off-by: ...' at the bottom
  26 of the commit, this can be later on parsed. An easy metric
  27 to gather then would be 'which author has signd off more
  28 commits compared to how many commits they authored'. This
  29 could for example quickly point one at who is a/the
  30 'maintainer' of a repository. (This is because it is common
  31 for the maintainer to sign off all commits before they are
  32 committed.)
  33
  34 The goal of GitStat is to provide a framework for gathering
  35 statistics on a repository. Currently it has quite a few
  36 metrics already in place, but it is designed with
  37 extendability in mind. One can easily re-use (part of) an
  38 existing metric to gather new information. For example,
  39 there is a metric that determines how many changes were
  40 made by a specific author to a specific file. (That is,
  41 take only those changes made by a specific author that
  42 modify the target file, and summarize them.) This metric
  43 could be used in a more elaborate metric that tries to
  44 figure out whom should be contacted when a change is made
  45 to a specific file. (Such a metric could take the top
  46 20% of the authors sorted by their score in the
  47 'changes counting' metric.)
  48
  49 The main entrypoint of GitStats is the 'stats.py' module,
  50 which handles setting up some basic things and then hands
  51 control over to one of the other modules. These other
  52 modules are grouped by git's 'logical units'. Currently
  53 those are 'author', 'branch', 'bug', 'commit', 'diff',
  54 'index', 'matcher', and 'test'. The outliers here are the
  55 'bug', 'matcher', and 'test' modules, they do not really
  56 have counterparts in git itself, while the others do. See
  57 the documentation for each of these modules for an
  58 explanation of their purpose and how to use them.
  59