Re: [PATCH 1/1] docs/git-blame: describe sourceline and resultline

[Junio C Hamano <gitster@pobox.com>]

Philip Patsch <philip@decentsoftwa.re> writes:

>  - 40-byte SHA-1 of the commit the line is attributed to;
> +- the line number of the line in the original file,
> +  from when the commit was made;

Sorry, but "from when the commit was made" does not really add
anything meaningful at least to me.  Which commit does "the commit"
refer to in this sentence in the first place?

> +- the line number of the line in the final file,
> +  from the current state of the file;

We avoided to say "current" here because the state you are trying to
explain (i.e., the commit that has a file each of whose lines you
are trying to find the origin of) may not be current at all (e.g.,
"In the code that was current five years ago, we had this helper
function.  Where did it come from?").  "git blame --help" says
"start annotating from the given revision" in its very early part of
the doucumentation, so it might make it easier to understand if this
"final state" were referred to as the "annotated state"?

Perhaps this is easier to understand?

 - 40-byte SHA-1 of the commit the line is attributed to;

 - the line number in the file in the above blamed commit, where the
   line came from;

 - the line number in the file, where the line is found in the
   stating <rev>;

I dunno.

Regardless, the first one that is SHA-1 centric should probably be
updated in this age where SHA-256 repositories are reality.  Perhaps
replace the "40-byte" thing with something like

 - the hex object name of the commit the line is attributed to

but that would be a separate topic.

The same comment wrt "current" and "original" applies to the other
hunk.

Thanks.


> @@ -214,6 +216,9 @@ annotated.
>  	<40-byte-hex-sha1> <sourceline> <resultline> <num-lines>
>  +
>  Line numbers count from 1.
> ++
> +<sourceline> is where this line shows up in the original source commit.
> +<resultline> is where this line shows up in the current state of the file.
>  
>  . The first time that a commit shows up in the stream, it has various
>    other information about it printed out with a one-word tag at the