gitstats: Add a description about the commit 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 13:51:17 +0000 (28 15:51 +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/commit.txt [new file with mode: 0644]

diff --git a/doc/commit.txt b/doc/commit.txt
new file mode 100644 (file)
index 0000000..9daecc5
--- /dev/null
@@ -0,0 +1,44 @@
+syntax: stats.py commit <options>
+
+The purpose of the commit module is to gather statistics
+about commits, or related to commits, with the exception
+of things related to diffs (only retrieving the raw diff is
+in this module).
+
+Currently the available metrics in the author module are
+the following:
+* Find all the commits that touched the same paths as the
+  specified commit. This is implemented by passing the
+  result of the 'paths touched' auxillary function to the
+  'commits that touched' auxillary function. See below.
+
+* Retrieve the diff of a commit, either with or without
+  context, and optionally ignoring whitespace changes. This
+  method also works for the root commit (by making use of
+  the '--root' option to 'diff tree'.
+
+* Show only commits of which the commit message, and/or the
+  commit diff, match a specific regexp.  This is a simple
+  reimplementation of 'git log -S' and 'git log --grep'. It
+  is preferable to instead use the options native to
+  'git log', than to use this slower version.
+  Note: the regexps for the 'commit message' and the
+  'commit diff' may be different.
+
+It also defines the following auxillary functions:
+* Print a commit in a 'readable' way, this is by default
+  'git log -1 --name-only'. By the way of an environmental
+  variable ('GIT_STATS_PRETTY_PRINT'), it can be made to
+  instead use 'git log -1 --prety=oneline' by setting the
+  variable to 'online'.
+
+* Retrieve all the paths that a specific commit touches,
+  this is used internally to limit the commits that have
+  to be searched when looking for a merge. That is done by
+  passing the output of this method to the one described
+  below.
+
+* Find all commits that touched a list of files, optionally
+  treating the paths as relative to the current working
+  directory.
+