git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
* Why is AuthorDate displayed on git-blame?
@ 2020-08-05  0:18 נעם סולוביצ'יק
  2020-08-05  0:40 ` Junio C Hamano
  2020-08-05  1:59 ` brian m. carlson
  0 siblings, 2 replies; 10+ messages in thread
From: נעם סולוביצ'יק @ 2020-08-05  0:18 UTC (permalink / raw)
  To: git

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?

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: Why is AuthorDate displayed on git-blame?
  2020-08-05  0:18 Why is AuthorDate displayed on git-blame? נעם סולוביצ'יק
@ 2020-08-05  0:40 ` Junio C Hamano
  2020-08-06  6:57   ` Raymond E. Pasco
  2020-08-05  1:59 ` brian m. carlson
  1 sibling, 1 reply; 10+ messages in thread
From: Junio C Hamano @ 2020-08-05  0:40 UTC (permalink / raw)
  To: נעם
	סולוביצ'יק
  Cc: git

נעם סולוביצ'יק  <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".







^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: Why is AuthorDate displayed on git-blame?
  2020-08-05  0:18 Why is AuthorDate displayed on git-blame? נעם סולוביצ'יק
  2020-08-05  0:40 ` Junio C Hamano
@ 2020-08-05  1:59 ` brian m. carlson
  2020-08-05 16:08   ` Junio C Hamano
  1 sibling, 1 reply; 10+ messages in thread
From: brian m. carlson @ 2020-08-05  1:59 UTC (permalink / raw)
  To: נעם
	סולוביצ'יק
  Cc: git

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

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: Why is AuthorDate displayed on git-blame?
  2020-08-05  1:59 ` brian m. carlson
@ 2020-08-05 16:08   ` Junio C Hamano
  0 siblings, 0 replies; 10+ messages in thread
From: Junio C Hamano @ 2020-08-05 16:08 UTC (permalink / raw)
  To: brian m. carlson
  Cc: נעם
	סולוביצ'יק,
	git

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


^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: Why is AuthorDate displayed on git-blame?
  2020-08-05  0:40 ` Junio C Hamano
@ 2020-08-06  6:57   ` Raymond E. Pasco
  2020-08-06 15:19     ` Noam Soloveichik
  2020-08-06 18:17     ` Junio C Hamano
  0 siblings, 2 replies; 10+ messages in thread
From: Raymond E. Pasco @ 2020-08-06  6:57 UTC (permalink / raw)
  To: Junio C Hamano,
	נעם
	סולוביצ'יק
  Cc: git

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.

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: Why is AuthorDate displayed on git-blame?
  2020-08-06  6:57   ` Raymond E. Pasco
@ 2020-08-06 15:19     ` Noam Soloveichik
  2020-08-06 18:13       ` Raymond E. Pasco
  2020-08-06 18:17     ` Junio C Hamano
  1 sibling, 1 reply; 10+ messages in thread
From: Noam Soloveichik @ 2020-08-06 15:19 UTC (permalink / raw)
  To: Raymond E. Pasco, Junio C Hamano; +Cc: git


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.

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: Why is AuthorDate displayed on git-blame?
  2020-08-06 15:19     ` Noam Soloveichik
@ 2020-08-06 18:13       ` Raymond E. Pasco
  0 siblings, 0 replies; 10+ messages in thread
From: Raymond E. Pasco @ 2020-08-06 18:13 UTC (permalink / raw)
  To: Noam Soloveichik, Junio C Hamano; +Cc: git

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.

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: Why is AuthorDate displayed on git-blame?
  2020-08-06  6:57   ` Raymond E. Pasco
  2020-08-06 15:19     ` Noam Soloveichik
@ 2020-08-06 18:17     ` Junio C Hamano
  2020-08-06 18:52       ` [PATCH] blame-options.txt: document --first-parent option Raymond E. Pasco
  2020-08-08  0:35       ` Why is AuthorDate displayed on git-blame? Jeff King
  1 sibling, 2 replies; 10+ messages in thread
From: Junio C Hamano @ 2020-08-06 18:17 UTC (permalink / raw)
  To: Raymond E. Pasco
  Cc: נעם
	סולוביצ'יק,
	git

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


^ permalink raw reply	[flat|nested] 10+ messages in thread

* [PATCH] blame-options.txt: document --first-parent option
  2020-08-06 18:17     ` Junio C Hamano
@ 2020-08-06 18:52       ` Raymond E. Pasco
  2020-08-08  0:35       ` Why is AuthorDate displayed on git-blame? Jeff King
  1 sibling, 0 replies; 10+ messages in thread
From: Raymond E. Pasco @ 2020-08-06 18:52 UTC (permalink / raw)
  To: Junio C Hamano; +Cc: git, Noam Soloveichik, 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


^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: Why is AuthorDate displayed on git-blame?
  2020-08-06 18:17     ` Junio C Hamano
  2020-08-06 18:52       ` [PATCH] blame-options.txt: document --first-parent option Raymond E. Pasco
@ 2020-08-08  0:35       ` Jeff King
  1 sibling, 0 replies; 10+ messages in thread
From: Jeff King @ 2020-08-08  0:35 UTC (permalink / raw)
  To: Junio C Hamano
  Cc: Raymond E. Pasco,
	נעם
	סולוביצ'יק,
	git

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

^ permalink raw reply	[flat|nested] 10+ messages in thread

end of thread, other threads:[~2020-08-08  0:35 UTC | newest]

Thread overview: 10+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-08-05  0:18 Why is AuthorDate displayed on git-blame? נעם סולוביצ'יק
2020-08-05  0:40 ` Junio C Hamano
2020-08-06  6:57   ` Raymond E. Pasco
2020-08-06 15:19     ` Noam Soloveichik
2020-08-06 18:13       ` Raymond E. Pasco
2020-08-06 18:17     ` Junio C Hamano
2020-08-06 18:52       ` [PATCH] blame-options.txt: document --first-parent option Raymond E. Pasco
2020-08-08  0:35       ` Why is AuthorDate displayed on git-blame? Jeff King
2020-08-05  1:59 ` brian m. carlson
2020-08-05 16:08   ` Junio C Hamano

git@vger.kernel.org list mirror (unofficial, one of many)

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V1 git git/ https://public-inbox.org/git \
		git@vger.kernel.org
	public-inbox-index git

Example config snippet for mirrors.
Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/inbox.comp.version-control.git
	nntp://ie5yzdi7fg72h7s4sdcztq5evakq23rdt33mfyfcddc5u3ndnw24ogqd.onion/inbox.comp.version-control.git
	nntp://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/inbox.comp.version-control.git
	nntp://news.gmane.io/gmane.comp.version-control.git
 note: .onion URLs require Tor: https://www.torproject.org/

code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git