Re: [PATCH] doc: warn against --committer-date-is-author-date

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 16, 2025, 16:23 UTC
Message-ID: <xmqqbjm695p4.fsf@gitster.g>
In-Reply-To: <8b7df500-4ddd-4aa4-bc67-b1b345c806e6@kdbg.org>

Johannes Sixt <j6t@kdbg.org> writes:

Show 28 quoted lines

> Am 16.10.25 um 16:13 schrieb Kristoffer Haugsbakk:
>> On Sat, Oct 11, 2025, at 11:15, Johannes Sixt wrote:
>>> Am 08.10.25 um 21:45 schrieb kristofferhaugsbakk@fastmail.com:
>>>> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>>>>
>>>> This option has legitimate uses but could create a commit history which
>>>> violates the assumption that commits are strictly increasing in terms of
>>>> commit timestamps. Warn against that in both git-am(1) and git-rebase(1).
>>>
>>> I think that the discussion has meanwhile converged insofar that we do
>>> not think that the option has a legitimate use case. Rather, it was
>>> introduced to solve one particular problem case (that is cited below),
>>> but with a solution that was misguided and not well thought through.
>> 
>> Okay if this was the cited example:
>> 
>> https://lore.kernel.org/git/46d6db660901221441q60eb90bdge601a7a250c3a247@mail.gmail.com/
>> 
>> Then we can clarify with two questions:
>> 
>> 1. Is the use case itself reasonable, i.e. abusing[1] git-am(1) to
>>    pseudo-import commits (modulo the committer)?
>
> The cited example talks about a set of patches and expects them to
> create the same object IDs each time they are imported. This expectation
> only makes sense when the import happens on the same base commit. But
> then, why in the world would one want to import the same patches
> multiple times??

Only when the person is trying to make sure what they are about to send out _will_ apply cleanly to the intended base, I would guess. And that person would be using an unstable implementation of "git am", perhaps who is futzing with it. Otherwise there is no reason for such an expectation. Perhaps back when such a request was made, fast-export/fast-import pair was not know to the requestor?

> A mailbox full of patches is not a suitable storage form for commits.
> This particular use-case for git-am just does not make sense.

I would think so, too.

Show 15 quoted lines

>> Like this?
>> 
>>     Do not use this option. By default the command records the date from
>>     the e-mail ...
>> 
>>     WARNING: ...
>> 
>> In that case I think parentheses makes it read better:
>> 
>>     (Do not use this option.) By default the command records the date from
>>     the e-mail ...
>> 
>>     WARNING: ...
> I do not like the latter. If you do not like the former, I wouldn't mind
> not adding the sentence. The warning should be sufficient.

But stepping back a bit, if we truly want to discourage the use of it, perhaps we should officially deprecate and schedule it for removal? If we are *not* brave enough to back such a move, then perhaps we ourselves are not yet convinced that this should be discouraged?

My preference is to stop at describing, in WARNING or NOTES, what the use case that triggered the addition of this option was and declaring that the use case does not make any sense (your "who would apply the same series twice on the same base? just keep the result on a branch and reuse" would be fine), but without saying "Do not use this option". In other words, the message is "We'd give a long rope that we do not think is very useful, but it is up to you to get yourself tangled in it".

Thanks.