From 2fdfa0c4b33d363d246f4238822699801d325595 Mon Sep 17 00:00:00 2001 From: Sverre Rabbelier Date: Sun, 27 Jul 2008 20:26:17 +0200 Subject: [PATCH] gitstats: Add a description about the branch 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/branch.txt | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 doc/branch.txt diff --git a/doc/branch.txt b/doc/branch.txt new file mode 100644 index 0000000..62ef971 --- /dev/null +++ b/doc/branch.txt @@ -0,0 +1,35 @@ +syntax: stats.py branch + +The purpose of the branch module is to gather statistics +about branches, or related to branches. + +Currently the available metrics in the branch module are +the following: +* Which of the branch head does a commit belong to + What this metric does is walk down the ancestry of the + target commit and increase the 'dilution' by one or each + merge it finds. The exception applies that when following + the 'primary' parent of the merge (e.g., the branch + recorded as the one the merge commit was made on), the + dilution is not increased. As such, if the target commit + is made on a branch, and then later on it's dilution + is calculated, it will have 0 dilution for that branch. + The branch with the lowest dilution is deemed to be the + branch that the commit belongs to most. + Note: In git there is no 'main' branch, as such any and + all branches branches that 'branched off' after the + target commit will also have dilution 0. + +It also defines the following auxillery functions: +* Retreive the name of a commit if it is a the head of a + branch. This can be seen as the reverse of 'rev-parse' + for branch heads. This is used internally to provide the + user with a sensible name when telling them which branch + a commit belongs to. + +* List all the branches that contain a specific commit, + optionally searching through remote branches as well as + optionally not filtering at all. This is used internally + to not search through branches that do not contain the + target commit. + -- 2.11.4.GIT