Document better -D option
[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 The [details] tell git which changesets are of interest; the [options] can
24 be:
25
26         -a      If a patch contains signoff lines from both Andrew Morton 
27                 and Linus Torvalds, omit Linus's.
28
29         -c file Specify the name of the gitdm configuration file.  
30                 By default, "./gitdm.config" is used.
31
32         -d      Omit the developer reports, giving employer information
33                 only. 
34
35         -D      Rather than create the usual statistics, create a 
36         file (datelc) providing lines changed per day, where the first column
37         displays the changes happened only on that day and the second sums
38         the day it happnened with the previous ones. This option is suitable
39         for feeding to a tool like gnuplot.
40
41         -h file Generate HTML output to the given file
42
43         -l num  Only list the top <num> entries in each report.
44
45         -o file Write text output to the given file (default is stdout).
46
47         -r pat  Only generate statistics for changes to files whose 
48                 name matches the given regular expression.
49
50         -s      Ignore Signed-off-by lines which match the author of 
51                 each patch.
52
53         -u      Group all unknown developers under the "(Unknown)"
54                 employer. 
55
56         -z      Dump out the hacker database to "database.dump".
57
58 A typical command line used to generate the "who write 2.6.x" LWN articles
59 looks like:
60
61     git log -p -M v2.6.19..v2.6.20 | \
62         gitdm -u -s -a -o results -h results.html
63
64
65 CONFIGURATION FILE
66
67 The main purpose of the configuration file is to direct the mapping of
68 email addresses onto employers.  Please note that the config file parser is
69 exceptionally stupid and unrobust at this point, but it gets the job done.  
70
71 Blank lines and lines beginning with "#" are ignored.  Everything else
72 specifies a file with some sort of mapping:
73
74 EmailAliases file
75
76         Developers often post code under a number of different email
77         addresses, but it can be desirable to group them all together in
78         the statistics.  An EmailAliases file just contains a bunch of
79         lines of the form:
80
81                 alias@address  canonical@address
82
83         Any patches originating from alias@address will be treated as if
84         they had come from canonical@address.
85
86
87 EmailMap file
88
89         Map email addresses onto employers.  These files contain lines
90         like:
91
92                 [user@]domain  employer  [< yyyy-mm-dd]
93
94         If the "user@" portion is missing, all email from the given domain
95         will be treated as being associated with the given employer.  If a
96         date is provided, the entry is only valid up to that date;
97         otherwise it is considered valid into the indefinite future.  This
98         feature can be useful for properly tracking developers' work when
99         they change employers but do not change email addresses.
100
101
102 GroupMap file employer
103
104         This is a variant of EmailMap provided for convenience; it contains
105         email addresses only, all of which are associated with the given
106         employer.
107
108 OTHER TOOLS
109
110 A few other tools have been added to this repository:
111
112   treeplot
113         Reads a set of commits, then generates a graphviz file charting the
114         flow of patches into the mainline.  Needs to be smarter, but, then,
115         so does everything else in this directory.
116
117   findoldfiles
118         Simple brute-force crawler which outputs the names of any files
119         which have not been touched since the original (kernel) commit.
120
121   committags
122         I needed to be able to quickly associate a given commit with the
123         major release which contains it.  First attempt used 
124         "git tags --contains="; after it ran for a solid week, I concluded
125         there must be a better way.  This tool just reads through the repo,
126         remembering tags, and creating a Python dictionary containing the
127         association.  The result is an ugly 10mb pickle file, but, even so,
128         it's still a better way.
129
130   linetags
131         Crawls through a directory hierarchy, counting how many lines of
132         code are associated with each major release.  Needs the pickle file
133         from committags to get the job done.
134
135
136 NOTES AND CREDITS
137
138 Gitdm was written by Jonathan Corbet; many useful contributions have come
139 from Greg Kroah-Hartman.
140
141 Please note that this tool is provided in the hope that it will be useful,
142 but it is not put forward as an example of excellence in design or
143 implementation.  Hacking on gitdm tends to stop the moment it performs
144 whatever task is required of it at the moment.  Patches to make it less
145 hacky, less ugly, and more robust are welcome.
146
147 Jonathan Corbet
148 corbet@lwn.net