threads / patch / 64294

patchdocs/git-blame: describe sourceline and resultline

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

## tl;dr

5 messages between Oct 10, 2025 and Oct 14, 2025. Diffs are folded; open one to read it.

replies: 4people: 2as markdown or json

Philip Patsch· Oct 10, 2025, 15:21 UTC · lore

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

Philip Patsch· Oct 10, 2025, 15:21 UTC · re: Philip Patsch · lore

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

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(-)

Show changes to Documentation/git-blame.adoc +7 −2

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

Junio C Hamano· Oct 10, 2025, 18:19 UTC · re: Philip Patsch · lore

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

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.

Show 10 quoted lines

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

Junio C Hamano· Oct 10, 2025, 19:46 UTC · re: Junio C Hamano · lore

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

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

Show 9 quoted lines

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

Philip Patsch· Oct 14, 2025, 13:33 UTC · re: Junio C Hamano · lore

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

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

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

Show 5 quoted lines

> > - 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`)