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

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 8, 2010, 08:00 UTC
Message-ID: <7vmxxe74s2.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1270709490-19163-2-git-send-email-struggleyb.nku@gmail.com>

Bo Yang <struggleyb.nku@gmail.com> writes:

Show 9 quoted lines

> +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>`.

I hate to say it, but this is horrifying; it works quite the other way around.

The name of the game is not "take blame by looking at the diff to see what we introduced"; it is "avoid taking blame at all cost, by looking at the diff to see what we might have inherited from our parents".

A description closer to the truth would be:

 - Look at output of "git diff <rev>^$n <rev>" for each parent ($n runs
   from 1 to number of parents);

 - Ignore all +/- lines.  The context ' ' lines and lines outside of diff
   hunks are known to have been inherited from $n-th parent and they are
   not our fault.  We can happily pass blame for these lines to our
   parent.

 - Do the above for all the parents.  We (grudgingly) take blame for lines
   that we failed to find corresponding lines in our parents.

The -M option affects what happens between the second and the third step. We try to see if the lines that we did not pass blame to <rev>^$n might have come from <rev>^$n by running diff between the remainder and the blob in <rev>^$n *again*. This lets us catch code movement within the blob, hence the name of the option -M.

The -C option affects the choice of the blob in <rev>^$n. Usually, we internally run an equivalent of "git diff -M <rev>^$n <rev>" to notice that the file F that we are analyzing used to be called F' in $n-th parent, and run the diff against it, but -C allows us to check with paths other than that, and additional -C enlarges the search space. This is to notice code movement (with a single -C) or copies (with more -Cs) across paths.

For illustrated description, read the classic:
 
    http://thread.gmane.org/gmane.comp.version-control.git/28826

Almost all the hits in the first page from this query would help, too:

http://search.gmane.org/?query=On+blame%2Fpickaxe&author=Junio+C+Hamano&group=gmane.comp.version-control.git&sort=revdate&DEFAULTOP=and&[=2&xP=blame%09pickaxe&xFILTERS=Gcomp.version-control.git-Ac-Ahamano-Ajunio---A