Added option to get the stats from numstat instead of diff
[mining-tools:gitdm.git] / README
1 The code in this directory makes up the "git data miner," a simple hack
2 which attempts to figure things out from the revision history in a git
3 repository. 
4
5
6 INSTALLING GITDM
7
8 gitdm is a python script and doesn't need to be proper installed like other
9 normal programs. You just have to adjust your PATH variable, pointing it to
10 the directory of gitdm or alternatively create a symbolic link of the script
11 inside /usr/bin.
12
13 Before actually run gitdm you may want also to update the configuration file
14 (gitdm.config) with the needed information.
15
16
17 RUNNING GITDM
18
19 Run it like this:
20
21    git log -p -M [details] | gitdm [options]
22
23 Alternatively, you can run with:
24
25    git log --numstat -M [details] | gitdm -n [options]
26
27 The [details] tell git which changesets are of interest; the [options] can
28 be:
29
30         -a      If a patch contains signoff lines from both Andrew Morton 
31                 and Linus Torvalds, omit Linus's.
32
33         -b dir  Specify the base directory to fetch the configuration files.
34
35         -c file Specify the name of the gitdm configuration file.  
36                 By default, "./gitdm.config" is used.
37
38         -d      Omit the developer reports, giving employer information
39                 only. 
40
41         -D      Rather than create the usual statistics, create a 
42         file (datelc) providing lines changed per day, where the first column
43         displays the changes happened only on that day and the second sums
44         the day it happnened with the previous ones. This option is suitable
45         for feeding to a tool like gnuplot.
46
47         -h file Generate HTML output to the given file
48
49         -l num  Only list the top <num> entries in each report.
50
51     -n  Use --numstat instead of generated patches to get the statistics.
52
53         -o file Write text output to the given file (default is stdout).
54
55         -r pat  Only generate statistics for changes to files whose 
56                 name matches the given regular expression.
57
58         -s      Ignore Signed-off-by lines which match the author of 
59                 each patch.
60
61         -u      Group all unknown developers under the "(Unknown)"
62                 employer. 
63
64     -x file  Export raw statistics as CSV.
65
66     -w  Aggregate the data by weeks instead of months in the
67         CSV file when -x is used.
68
69         -z      Dump out the hacker database to "database.dump".
70
71 A typical command line used to generate the "who write 2.6.x" LWN articles
72 looks like:
73
74     git log -p -M v2.6.19..v2.6.20 | \
75         gitdm -u -s -a -o results -h results.html
76
77 or:
78
79     git log --numstat -M v2.6.19..v2.6.20 | \
80         gitdm -u -s -a -n -o results -h results.html
81
82 CONFIGURATION FILE
83
84 The main purpose of the configuration file is to direct the mapping of
85 email addresses onto employers.  Please note that the config file parser is
86 exceptionally stupid and unrobust at this point, but it gets the job done.  
87
88 Blank lines and lines beginning with "#" are ignored.  Everything else
89 specifies a file with some sort of mapping:
90
91 EmailAliases file
92
93         Developers often post code under a number of different email
94         addresses, but it can be desirable to group them all together in
95         the statistics.  An EmailAliases file just contains a bunch of
96         lines of the form:
97
98                 alias@address  canonical@address
99
100         Any patches originating from alias@address will be treated as if
101         they had come from canonical@address.
102
103     It may happen that some people set their git user data in the
104     following form: "joe.hacker@acme.org <Joe Hacker>". The 
105     "Joe Hacker" is then considered as the email... but gitdm says
106     it is a "Funky" email. An alias line in the following form can
107     be used to alias these commits aliased to the correct email
108     address:
109
110         "Joe Hacker" joe.hacker@acme.org
111
112
113 EmailMap file
114
115         Map email addresses onto employers.  These files contain lines
116         like:
117
118                 [user@]domain  employer  [< yyyy-mm-dd]
119
120         If the "user@" portion is missing, all email from the given domain
121         will be treated as being associated with the given employer.  If a
122         date is provided, the entry is only valid up to that date;
123         otherwise it is considered valid into the indefinite future.  This
124         feature can be useful for properly tracking developers' work when
125         they change employers but do not change email addresses.
126
127
128 GroupMap file employer
129
130         This is a variant of EmailMap provided for convenience; it contains
131         email addresses only, all of which are associated with the given
132         employer.
133
134 VirtualEmployer name
135     nn% employer1
136     ...
137 end
138
139         This construct (which appears in the main configuration file)
140         allows causes the creation of a fake employer with the given
141         "name".  It directs that any contributions attributed to that
142         employer should be split to other (real) employers using the given
143         percentages.  The functionality works, but is primitive - there is,
144         for example, no check to ensure that the percentages add up to
145         something rational.
146
147
148 OTHER TOOLS
149
150 A few other tools have been added to this repository:
151
152   treeplot
153         Reads a set of commits, then generates a graphviz file charting the
154         flow of patches into the mainline.  Needs to be smarter, but, then,
155         so does everything else in this directory.
156
157   findoldfiles
158         Simple brute-force crawler which outputs the names of any files
159         which have not been touched since the original (kernel) commit.
160
161   committags
162         I needed to be able to quickly associate a given commit with the
163         major release which contains it.  First attempt used 
164         "git tags --contains="; after it ran for a solid week, I concluded
165         there must be a better way.  This tool just reads through the repo,
166         remembering tags, and creating a Python dictionary containing the
167         association.  The result is an ugly 10mb pickle file, but, even so,
168         it's still a better way.
169
170   linetags
171         Crawls through a directory hierarchy, counting how many lines of
172         code are associated with each major release.  Needs the pickle file
173         from committags to get the job done.
174
175
176 NOTES AND CREDITS
177
178 Gitdm was written by Jonathan Corbet; many useful contributions have come
179 from Greg Kroah-Hartman.
180
181 Please note that this tool is provided in the hope that it will be useful,
182 but it is not put forward as an example of excellence in design or
183 implementation.  Hacking on gitdm tends to stop the moment it performs
184 whatever task is required of it at the moment.  Patches to make it less
185 hacky, less ugly, and more robust are welcome.
186
187 Jonathan Corbet
188 corbet@lwn.net