gitstats: Add a description about the diff module
[git-stats.git] / 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.
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.
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.)
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.)
49 The main entrypoint of GitStats is the '' 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.