From 9f225a4ad339d411c1c8c827664ad2205811c878 Mon Sep 17 00:00:00 2001 From: Sverre Rabbelier Date: Mon, 28 Jul 2008 14:49:28 +0200 Subject: [PATCH] gitstats: Add a description about the commit module 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 | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 doc/commit.txt diff --git a/doc/commit.txt b/doc/commit.txt new file mode 100644 index 0000000..9daecc5 --- /dev/null +++ b/doc/commit.txt @@ -0,0 +1,44 @@ +syntax: stats.py commit + +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. + -- 2.11.4.GIT