Skip to contentSkip to conversation

Why is AuthorDate displayed on git-blame?

PATCH New נעם סולוביצ'יק 5 participants 10 messages Aug 5, 2020 – Aug 8, 2020 Documentation

lore
Share & tools
lore
#0 lore raw

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?

#1 lore raw
Quoted 4 lines · נעם סולוביצ'יק

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.

Quoted 8 lines

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

#2 lore raw
Quoted 1 line · Junio C Hamano

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.

#3 lore raw
Quoted 1 line · Raymond E. Pasco

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.

#4 lore raw
Quoted 4 lines · Noam Soloveichik

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.

Quoted 3 lines

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.

Quoted 6 lines

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.

#5 lore raw
In reply to Raymond E. Pasco
Quoted 8 lines · Raymond E. Pasco

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.

#6 lore raw

PATCH 1/1 blame-options.txt: document --first-parent option

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

---
 Documentation/blame-options.txt | 6 ++++++
 1 file changed, 6 insertions(+)
Documentation/blame-options.txt +6 -0
index 5d122db6e9..88750af7ae 100644
@@ -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.
Signature · 1 line
2.28.0
#7 lore raw
In reply to Junio C Hamano
Quoted 5 lines · Junio C Hamano
Quoted 3 lines · Raymond E. Pasco

Perhaps the following
adaptation:

Quoted 8 lines
Quoted 5 lines

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

#8 lore raw
In reply to נעם סולוביצ'יק
Quoted 10 lines · נעם סולוביצ'יק

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.

Quoted 8 lines

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.

Signature · 1 line
brian m. carlson: Houston, Texas, US
#9 lore raw
Quoted 2 lines · brian m. carlson

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