Merge branch 'refactoring' of git://gitorious.org/mining-tools/gitdm into german
[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 file (datelc.csv)
42             providing lines changed per day, where the first column displays
43             the changes happened only on that day and the second sums the day it
44             happnened with the previous ones. This option is suitable for
45             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     -p prefix Dump out the database categorized by changeset and by file type.
56             It requires -n, otherwise it is not possible to get separated results.
57
58         -r pat  Only generate statistics for changes to files whose 
59                 name matches the given regular expression.
60
61         -s      Ignore Signed-off-by lines which match the author of 
62                 each patch.
63
64         -t      Generate a report by type of contribution (code, documentation, etc.).
65             It requires -n, otherwise this option is ignored silently.
66
67
68         -u      Group all unknown developers under the "(Unknown)"
69                 employer. 
70
71     -x file  Export raw statistics as CSV.
72
73     -w  Aggregate the data by weeks instead of months in the
74         CSV file when -x is used.
75
76         -z      Dump out the hacker database to "database.dump".
77
78 A typical command line used to generate the "who write 2.6.x" LWN articles
79 looks like:
80
81     git log -p -M v2.6.19..v2.6.20 | \
82         gitdm -u -s -a -o results -h results.html
83
84 or:
85
86     git log --numstat -M v2.6.19..v2.6.20 | \
87         gitdm -u -s -a -n -o results -h results.html
88
89 CONFIGURATION FILE
90
91 The main purpose of the configuration file is to direct the mapping of
92 email addresses onto employers.  Please note that the config file parser is
93 exceptionally stupid and unrobust at this point, but it gets the job done.  
94
95 Blank lines and lines beginning with "#" are ignored.  Everything else
96 specifies a file with some sort of mapping:
97
98 EmailAliases file
99
100         Developers often post code under a number of different email
101         addresses, but it can be desirable to group them all together in
102         the statistics.  An EmailAliases file just contains a bunch of
103         lines of the form:
104
105                 alias@address  canonical@address
106
107         Any patches originating from alias@address will be treated as if
108         they had come from canonical@address.
109
110     It may happen that some people set their git user data in the
111     following form: "joe.hacker@acme.org <Joe Hacker>". The 
112     "Joe Hacker" is then considered as the email... but gitdm says
113     it is a "Funky" email. An alias line in the following form can
114     be used to alias these commits aliased to the correct email
115     address:
116
117         "Joe Hacker" joe.hacker@acme.org
118
119
120 EmailMap file
121
122         Map email addresses onto employers.  These files contain lines
123         like:
124
125                 [user@]domain  employer  [< yyyy-mm-dd]
126
127         If the "user@" portion is missing, all email from the given domain
128         will be treated as being associated with the given employer.  If a
129         date is provided, the entry is only valid up to that date;
130         otherwise it is considered valid into the indefinite future.  This
131         feature can be useful for properly tracking developers' work when
132         they change employers but do not change email addresses.
133
134
135 GroupMap file employer
136
137         This is a variant of EmailMap provided for convenience; it contains
138         email addresses only, all of which are associated with the given
139         employer.
140
141 VirtualEmployer name
142     nn% employer1
143     ...
144 end
145
146         This construct (which appears in the main configuration file)
147         allows causes the creation of a fake employer with the given
148         "name".  It directs that any contributions attributed to that
149         employer should be split to other (real) employers using the given
150         percentages.  The functionality works, but is primitive - there is,
151         for example, no check to ensure that the percentages add up to
152         something rational.
153
154 FileTypeMap file
155
156         Map file names/extensions onto file types.  These files contain lines
157         like:
158
159                 order <type1>,<type2>,...,<typeN>
160
161                 filetype <type> <regex>
162                 ...
163
164         This construct allows fine graned reports by type of contribution
165         (build, code, image, multimedia, documentation, etc.)
166
167         Order is important because it is possible to have overlapping between
168         filenames.  For instance, ltmain.sh fits better as 'build' instead of
169         'code' (the filename instead of '\.sh$').  The first element in order
170         has precedence over the next ones.
171
172
173 OTHER TOOLS
174
175 A few other tools have been added to this repository:
176
177   treeplot
178         Reads a set of commits, then generates a graphviz file charting the
179         flow of patches into the mainline.  Needs to be smarter, but, then,
180         so does everything else in this directory.
181
182   findoldfiles
183         Simple brute-force crawler which outputs the names of any files
184         which have not been touched since the original (kernel) commit.
185
186   committags
187         I needed to be able to quickly associate a given commit with the
188         major release which contains it.  First attempt used 
189         "git tags --contains="; after it ran for a solid week, I concluded
190         there must be a better way.  This tool just reads through the repo,
191         remembering tags, and creating a Python dictionary containing the
192         association.  The result is an ugly 10mb pickle file, but, even so,
193         it's still a better way.
194
195   linetags
196         Crawls through a directory hierarchy, counting how many lines of
197         code are associated with each major release.  Needs the pickle file
198         from committags to get the job done.
199
200
201 NOTES AND CREDITS
202
203 Gitdm was written by Jonathan Corbet; many useful contributions have come
204 from Greg Kroah-Hartman.
205
206 Please note that this tool is provided in the hope that it will be useful,
207 but it is not put forward as an example of excellence in design or
208 implementation.  Hacking on gitdm tends to stop the moment it performs
209 whatever task is required of it at the moment.  Patches to make it less
210 hacky, less ugly, and more robust are welcome.
211
212 Jonathan Corbet
213 corbet@lwn.net