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

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

[Philip Patsch]

The manpage did not make clean what source and resultlines
refer to. This simple adjustment should remove that confusion.

Based on the question and answer on this Stackoverflow page:
https://stackoverflow.com/questions/49370690/what-is-sourceline-resultline-in-git-blame-incremental-output

I was not able to `make man` because of docbook xsl verification
issues unfortunately.

Philip Patsch (1):
  docs/git-blame: describe sourceline and resultline

 Documentation/git-blame.adoc | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

-- 
2.49.0

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

[Philip Patsch]

The manpage did not make clean what source and resultlines
refer to. This simple adjustment should remove that confusion.

Based on the question and answer on this Stackoverflow page:
https://stackoverflow.com/questions/49370690/what-is-sourceline-resultline-in-git-blame-incremental-output

Signed-off-by: Philip Patsch <philip@decentsoftwa.re>
---
 Documentation/git-blame.adoc | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-blame.adoc b/Documentation/git-blame.adoc
index e438d28625..870d0de0a5 100644
--- a/Documentation/git-blame.adoc
+++ b/Documentation/git-blame.adoc
@@ -113,8 +113,10 @@ In this format, each line is output after a header; the
 header at the minimum has the first line which has:
 
 - 40-byte SHA-1 of the commit the line is attributed to;
-- the line number of the line in the original file;
-- the line number of the line in the final file;
+- the line number of the line in the original file,
+  from when the commit was made;
+- the line number of the line in the final file,
+  from the current state of the file;
 - on a line that starts a group of lines from a different
   commit than the previous one, the number of lines in this
   group.  On subsequent lines this field is absent.
@@ -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
-- 
2.49.0

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

[Junio C Hamano]

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

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

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> 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>;

Sorry; "starting <rev>" was what I meant.

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

[Philip Patsch]

On Friday, October 10th, 2025 at 9:46 PM, Junio C Hamano <gitster@pobox.com> wrote:

> 
> 
> Junio C Hamano gitster@pobox.com writes:
 
> > - the line number in the file, where the line is found in the
> > stating <rev>;
> 
> 
> Sorry; "starting <rev>" was what I meant.

Now that I look at it again, we never in the manpage define what a plain `<rev>` means if it is given? Am I missing something here?

We have `--reverse`, but e.g. neither `--since` nor `<rev>` appear in the list of options (`--since` is mentioned further down in `SPECIFYING RANGES`)