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

[Junio C Hamano <gitster@pobox.com>]

Johannes Sixt <j6t@kdbg.org> writes:

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

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