gitstats: Add a description about the diff module
authorSverre Rabbelier <sverre@rabbelier.nl>
Mon, 28 Jul 2008 12:49:28 +0000 (28 14:49 +0200)
committerSverre Rabbelier <sverre@rabbelier.nl>
Mon, 28 Jul 2008 20:41:05 +0000 (28 22:41 +0200)
This briefly lists the most useful functions it exports,
it should later be made to include a more detailed
description of what metrics the user should expect this
subcommand to contain.

doc/diff.txt [new file with mode: 0644]

diff --git a/doc/diff.txt b/doc/diff.txt
new file mode 100644 (file)
index 0000000..68cdd5c
--- /dev/null
@@ -0,0 +1,24 @@
+syntax: stats.py diff <options>
+
+The purpose of the diff module is to gather statistics
+about diffs, or related to diffs.
+
+Currently the available metrics in the diff module are the
+following:
+* Determine whether two commit diffs are equal, optionally
+  checking whether they are reverts instead. It is also
+  possible to just look at what lines were changed (and
+  ignore the actual changes).
+
+* Find all commits that are reverted by the specified
+  commit by first retrieving the touched files, and then
+  examining all the commits that that touch the same files.
+
+It also defines the following auxillery functions:
+* Parse a raw commit diff and store it on a hunk-by-hunk
+  basis so that later on it can be examined more carefully
+  by other tools. Line numbers are optionally included so
+  that one can use those. For example, by comparing all the
+  added hunks with the deleted hunks of a second commit,
+  and vise versa, one can check for (partial) reverts.
+