From: Johannes Sixt <j6t@kdbg.org>
Date: Thu, 16 Oct 2025 15:28:33 GMT
Subject: Re: [PATCH] doc: warn against --committer-date-is-author-date
Message-ID: <8b7df500-4ddd-4aa4-bc67-b1b345c806e6@kdbg.org>
In-Reply-To: <52fd63c0-cd43-4ae8-af3e-f3fae02eaabf@app.fastmail.com>

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

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.

> Note: Not relevant here but in case there were more than one paragraph
> on this option already: should the WARNING be the final paragraph? Or in
> the second paragraph? (Like an imporant aside interruption after the
> introduction.) I think the final one but just clarifying.

It certainly depends on the case. I think I would begin by putting the
warning last and then judge whether a better place is warranted.

>> Perhaps insert "Do not use this option." as the the first sentence,
>> either before the description (my preference) or in the warning.
> 
> Regarding reading flow, this seems more back-and-forth than this patch.

Fair enough.

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

-- Hannes