Why is AuthorDate displayed on git-blame?

Why is AuthorDate displayed on git-blame?

[נעם סולוביצ'יק]

Hey everybody, I wonder about the decision behind git-blame and
git-annotate date that is being shown.

If I understand correctly, the AuthorDate is displayed, and I'd like
to challenge that decision. Consider the following case:

A feature branch having commits authored last week, but merged to the
main branch just today. And to the sake of discussion, let's say that
the branch has a bug.

When someone encounters the bug on the main branch, he would probably
want to know when it was introduced - the date when the bug started
to affect him. However, git-blame only shows him when the bug was
originally authored, in our case - *last-week*, which is confusing
since the main branch was working just fine back then.

So I wonder why was AuthorDate the date chosen to be displayed under
git-blame?

Re: Why is AuthorDate displayed on git-blame?

[Junio C Hamano]

נעם סולוביצ'יק  <inoamsol@gmail.com> writes:

> A feature branch having commits authored last week, but merged to the
> main branch just today. And to the sake of discussion, let's say that
> the branch has a bug.
>
> When someone encounters the bug on the main branch, he would probably
> want to know when it was introduced - the date when the bug started
> to affect him. However, git-blame only shows him when the bug was
> originally authored, in our case - *last-week*, which is confusing
> since the main branch was working just fine back then.
>
> So I wonder why was AuthorDate the date chosen to be displayed under
> git-blame?

Quite honestly, the left-hand side of "git blame" output is not all
that useful, as the usual workflow is to use "blame" to only to
identify a commit (or a set of commits) and from there, any detailed
information of problematic commits will be inspected with "git show"
or equivalent, so in that sense, "git blame -s" could be the most
useful output format.

It should be trivial to add an option to show the commit date
instead, so in that sense, the answer to the immediate question "why
author date?" is "just because we chose to show it; you are welcome
to send in a patch to add an option to show committer date".  

However, your question has another ingredient that is much more
interesting.  If you are interested only at the level of changes to
the primary integration branch, showing either author or committer
date of the ultimately responsible individual commit that was
brought in by a merge of a topic branch to the integration branch is
not useful at all for your purpose.  You need to find out which
merge brought the change to the integraiton branch and you do not
care which individual commit on the side branch that was merged.

IOW, what you would want is a "git blame --first-parent".

Re: Why is AuthorDate displayed on git-blame?

[Raymond E. Pasco]

On Tue Aug 4, 2020 at 8:40 PM EDT, Junio C Hamano wrote:
> IOW, what you would want is a "git blame --first-parent".

This exists (because blame takes rev-list options) and works as expected
(because blame.c handles this case), but is not documented. We could
include rev-list-options.txt, but this wouldn't be accurate because
blame does some of its own commit walking. Perhaps the following
adaptation:

--first-parent::
	Follow only the first parent commit upon seeing a merge
	commit. This option can be used to determine when a line
	was introduced to a particular integration branch, rather
	than when it was introduced to the history overall.

Re: Why is AuthorDate displayed on git-blame?

[Noam Soloveichik]

On 06/08/2020 9:57, Raymond E. Pasco wrote:
> On Tue Aug 4, 2020 at 8:40 PM EDT, Junio C Hamano wrote: > --first-parent:: Follow only the first parent commit upon seeing a > merge commit. This option can be used to determine when a line was > introduced to a particular integration branch, rather than when it > was introduced to the history overall.
I want to make sure I understand your proposal correctly -
--first-parent would still show AuthorDate, but of the
*merge-commit*, and not the commit that introduced the line of code
to the history overall.

If so, it's going to get the job done for commits which are applied
by a merge-commit. Although I wonder what --first-parent would
display for commits which are applied *not* by a merge.

Consider the linux kernel, where some of its commits are merge
commits from pull requests, and some are applied patches: with
different AuthorDate and CommitDate. For those commits, AuthorDate
represents the date the patch was originally sent to review, not when
it was introduced to the integration branch, which is represented by
the CommitDate, which leads to inconsistencies.

Re: Why is AuthorDate displayed on git-blame?

[Raymond E. Pasco]

On Thu Aug 6, 2020 at 11:19 AM EDT, Noam Soloveichik wrote:
> I want to make sure I understand your proposal correctly -
> --first-parent would still show AuthorDate, but of the
> *merge-commit*, and not the commit that introduced the line of code
> to the history overall.

To be clear, I'm not proposing anything but surfacing a useful feature
that already exists in the documentation.

> If so, it's going to get the job done for commits which are applied
> by a merge-commit. Although I wonder what --first-parent would
> display for commits which are applied *not* by a merge.

--first-parent commands don't care about merges, except that they never
follow the second or later parents of a merge. blame just tries to find
the earliest commit that had this version of some line in it; if it only
follows first parents then that will often end up being a merge (if
you're on an integration branch) but doesn't have to be.

> Consider the linux kernel, where some of its commits are merge
> commits from pull requests, and some are applied patches: with
> different AuthorDate and CommitDate. For those commits, AuthorDate
> represents the date the patch was originally sent to review, not when
> it was introduced to the integration branch, which is represented by
> the CommitDate, which leads to inconsistencies.

I honestly don't make use of dates in my workflow at all, so I don't
really have an opinion on date issues. The author date is marginally
more interesting to me, but only marginally and only really in projects
that use email (where the author date "git am" records is the date on
the email the patch came in).

Of course an option to choose which author/date pair (author or
committer) to annotate the file with would be a fine addition benefiting
people who do look at the dates. I use first-parent histories all the
time, however, and I'd like to see this useful existing blame option
documented.

Re: Why is AuthorDate displayed on git-blame?

[Junio C Hamano]

"Raymond E. Pasco" <ray@ameretat.dev> writes:

> Perhaps the following
> adaptation:
>
> --first-parent::
> 	Follow only the first parent commit upon seeing a merge
> 	commit. This option can be used to determine when a line
> 	was introduced to a particular integration branch, rather
> 	than when it was introduced to the history overall.

Yup.  We somehow forgot to document it when we did 95a4fb0e (blame:
handle --first-parent, 2015-09-15).  The text reads well.

Care to make it into a patch?

Thanks.

[PATCH] blame-options.txt: document --first-parent option

[Raymond E. Pasco]

blame/annotate have supported --first-parent since commit 95a4fb0eac
("blame: handle --first-parent"). This adds a blurb on that option to
the documentation.

Signed-off-by: Raymond E. Pasco <ray@ameretat.dev>
---
 Documentation/blame-options.txt | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt
index 5d122db6e9..88750af7ae 100644
--- a/Documentation/blame-options.txt
+++ b/Documentation/blame-options.txt
@@ -36,6 +36,12 @@ include::line-range-format.txt[]
 	START.  `git blame --reverse START` is taken as `git blame
 	--reverse START..HEAD` for convenience.
 
+--first-parent::
+	Follow only the first parent commit upon seeing a merge
+	commit. This option can be used to determine when a line
+	was introduced to a particular integration branch, rather
+	than when it was introduced to the history overall.
+
 -p::
 --porcelain::
 	Show in a format designed for machine consumption.
-- 
2.28.0

Re: Why is AuthorDate displayed on git-blame?

[Jeff King]

On Thu, Aug 06, 2020 at 11:17:31AM -0700, Junio C Hamano wrote:

> "Raymond E. Pasco" <ray@ameretat.dev> writes:
> 
> > Perhaps the following
> > adaptation:
> >
> > --first-parent::
> > 	Follow only the first parent commit upon seeing a merge
> > 	commit. This option can be used to determine when a line
> > 	was introduced to a particular integration branch, rather
> > 	than when it was introduced to the history overall.
> 
> Yup.  We somehow forgot to document it when we did 95a4fb0e (blame:
> handle --first-parent, 2015-09-15).  The text reads well.

My fault. I think I imagined it would just be included along with other
rev-list options, but the text above makes it clear why we'd want to
talk specifically about how it applies to blame.

-Peff

Re: Why is AuthorDate displayed on git-blame?

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 1943 bytes --]

On 2020-08-05 at 00:18:43, נעם סולוביצ'יק wrote:
> Hey everybody, I wonder about the decision behind git-blame and
> git-annotate date that is being shown.
> 
> If I understand correctly, the AuthorDate is displayed, and I'd like
> to challenge that decision. Consider the following case:
> 
> A feature branch having commits authored last week, but merged to the
> main branch just today. And to the sake of discussion, let's say that
> the branch has a bug.
> 
> When someone encounters the bug on the main branch, he would probably
> want to know when it was introduced - the date when the bug started
> to affect him. However, git-blame only shows him when the bug was
> originally authored, in our case - *last-week*, which is confusing
> since the main branch was working just fine back then.
> 
> So I wonder why was AuthorDate the date chosen to be displayed under
> git-blame?

I can't speak for the original author of this, and I think Junio's
answer explains this well, but I'd like to add an additional thought on
why the current behavior is useful.

For me, I am primarily interested in using blame to find information
about the party most knowledgable about the subsystem or area, or to
find a commit that introduced a change (possibly so I can read its
commit message or pull request).  I'm less likely to use blame to, well,
blame people.  Consequently, it's often helpful for me to know about
when the code was written, since that tells me more about the author and
their situation than the committer information does.

For a project like Git, the committer information would not be very
interesting to me, since Junio, while very competent, is not the expert
for every line in the codebase.  Since we're displaying the author name,
we might as well display the author timestamp as well.

I'm in favor of an option for this, though.
-- 
brian m. carlson: Houston, Texas, US

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 263 bytes --]

Re: Why is AuthorDate displayed on git-blame?

[Junio C Hamano]

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> ....  Since we're displaying the author name,
> we might as well display the author timestamp as well.

Ah, yes, I did forget this important aspect.  The date goes with the
name, so it would be awkward to show committer timestamp together
with the author name.