[PATCH 1/2] Add a basic idea section for git-blame.

From

Bo Yang <struggleyb.nku@gmail.com>

Date

Apr 8, 2010, 06:51 UTC

Message-ID

<1270709490-19163-2-git-send-email-struggleyb.nku@gmail.com>

In-Reply-To

<1270709490-19163-1-git-send-email-struggleyb.nku@gmail.com>

Signed-off-by: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Bo Yang <struggleyb.nku@gmail.com>
---
 Documentation/git-blame.txt |   32 ++++++++++++++++++++++++++++++++
 1 files changed, 32 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt
index a27f439..e31b87f 100644
--- a/Documentation/git-blame.txt
+++ b/Documentation/git-blame.txt
@@ -36,6 +36,38 @@ $ git log --pretty=oneline -S'blame_usage'
 ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output
 -----------------------------------------------------------------------------
 
+
+BASIC IDEA
+----------
+
+This section briefly explains the basic idea behind 'git-blame'.  You
+do not have to understand it to use git-blame, but it helps in
+understanding the `-M` and `-C` options.  For the sake of simplicity,
+we assume that history is linear.
+
+A call to `git-blame <rev> -- <file>` works as follows:
+
+- Look at `git diff <rev>^ <rev>` to see what the commit did.
+
+- Discard all `-` lines in the diff, since they are no longer part of
+  `<file>`.
+
+- Take blame for all `+` lines; i.e., the newly added lines according
+  to the diff are attributed to `<rev>`.
+
+- Shift blame for all unchanged lines to the parent; i.e., these lines
+  are attributed as in a call to `git blame <rev>^ -- <file>`.
+
+Note that this does not expend any effort to shift blame of `+`
+lines.  This can be changed with the `-M` and `-C` options.
+
+With `-M`, this command detects same lines of the current blaming code
+inside the current file. And it will shift the blame to the author of
+the original lines instead of author of current blaming code. It does
+the same for `-C` except that it will search across file boundary and
+multiple commits.
+
+
 OPTIONS
 -------
 include::blame-options.txt[]

-- 
1.6.0.4