README

   1
   2    Copyright 2008 Sverre Rabbelier <sverre@rabbelier.nl>
   3
   4    Licensed under the Apache License, Version 2.0 (the "License");
   5    you may not use this file except in compliance with the License.
   6    You may obtain a copy of the License at
   7
   8        http://www.apache.org/licenses/LICENSE-2.0
   9
  10    Unless required by applicable law or agreed to in writing, software
  11    distributed under the License is distributed on an "AS IS" BASIS,
  12    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13    See the License for the specific language governing permissions and
  14    limitations under the License.
  15
  16 All files licensed under the Apache License, Version 2.0.
  17
  18 GitStats is a metrics framework designed to gather
  19 statistics on git repositories. It is written in python and
  20 uses git-python to access the git binary.
  21
  22 Statistics can be useful in many ways, ranging from
  23 noticing oddities to gaining some insight in how something
  24 works. Git is specialized in storing changes made to a
  25 spicific 'unit' of content. Currently the widespread use
  26 is to store source code in it. This property can be used to
  27 gather statistics about the tracked content. This may seem
  28 strange at first, but as we all learned in school, many
  29 things can be learned from studying history. With git this
  30 history is in the form of changesets and commit messages
  31 that go with these changes. Each change belongs to one
  32 author, although it may have been reviewed by many. (Such
  33 would usually be noted in the commit message.) This means
  34 that for each content repository we have a set of changes
  35 for each author, each accompanied with a message describing
  36 what the change does. The interesting part of these
  37 messages are those that are consistent across commits.
  38
  39 For example, when a commit is subject to peer review before
  40 being comitted, it is not unusual to make note of this in
  41 the commit message. When this is done in a consistent way,
  42 for example by putting 'signed-off-by: ...' at the bottom
  43 of the commit, this can be later on parsed. An easy metric
  44 to gather then would be 'which author has signd off more
  45 commits compared to how many commits they authored'. This
  46 could for example quickly point one at who is a/the
  47 'maintainer' of a repository. (This is because it is common
  48 for the maintainer to sign off all commits before they are
  49 committed.)
  50
  51 The goal of GitStat is to provide a framework for gathering
  52 statistics on a repository. Currently it has quite a few
  53 metrics already in place, but it is designed with
  54 extendability in mind. One can easily re-use (part of) an
  55 existing metric to gather new information. For example,
  56 there is a metric that determines how many changes were
  57 made by a specific author to a specific file. (That is,
  58 take only those changes made by a specific author that
  59 modify the target file, and summarize them.) This metric
  60 could be used in a more elaborate metric that tries to
  61 figure out whom should be contacted when a change is made
  62 to a specific file. (Such a metric could take the top
  63 20% of the authors sorted by their score in the
  64 'changes counting' metric.)
  65
  66 The main entrypoint of GitStats is the 'stats.py' module,
  67 which handles setting up some basic things and then hands
  68 control over to one of the other modules. These other
  69 modules are grouped by git's 'logical units'. Currently
  70 those are 'author', 'branch', 'bug', 'commit', 'diff',
  71 'index', 'matcher', and 'test'. The outliers here are the
  72 'bug', 'matcher', and 'test' modules, they do not really
  73 have counterparts in git itself, while the others do. See
  74 the documentation for each of these modules for an
  75 explanation of their purpose and how to use them.
  76