From: Johannes Sixt <j6t@kdbg.org>
Date: Sat, 11 Oct 2025 09:15:13 GMT
Subject: Re: [PATCH] doc: warn against --committer-date-is-author-date
Message-ID: <601b145d-b183-4101-acb3-4a32b2ec4380@kdbg.org>
In-Reply-To: <d17060d9b72.1759952528.git.code@khaugsbakk.name>

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.

> The genesis of this option is 3f01ad66 (am: Add --committer-date-is-
> author-date option, 2009-01-22). The commit message doesn’t give us an
> example of a use case, but the thread starter does:[1]
> 
>     I've a big set of patches in a mbox file: there's sufficient info
>     inside for git-am to work.
> 
>     Yet, each time I do import these, my sha1sums are changing because of
>     different commit dates.
> 
>     I'd like to force the commit date to match the info/date from the time
>     I received the email (and therefore always get back the right
>     sha1sums).
> 
> So the motivation was to treat git-am(1) as an import command that
> creates the same commit IDs given the same base and committer.
> 
> [1]: https://lore.kernel.org/git/46d6db660901221441q60eb90bdge601a7a250c3a247@mail.gmail.com/

> diff --git a/Documentation/git-am.adoc b/Documentation/git-am.adoc
> index 221070de481..c36ae679cfb 100644
> --- a/Documentation/git-am.adoc
> +++ b/Documentation/git-am.adoc
> @@ -156,11 +156,18 @@ Valid <action> for the `--whitespace` option are:
>  	See also linkgit:githooks[5].
>  
>  --committer-date-is-author-date::
> -	By default the command records the date from the e-mail
> -	message as the commit author date, and uses the time of
> -	commit creation as the committer date. This allows the
> -	user to lie about the committer date by using the same
> -	value as the author date.
> +	NOTE: The history walking machinery assumes that commits have
> +	strictly increasing commit timestamps, with some tolerance for
> +	clock skew (see linkgit:git-rev-list[1]). You should only use
> +	this option to lie about the committer date when applying
> +	commits on top of a base which commit is older (in terms of the
> +	commit date) than the oldest patch you are applying.

IMO, "NOTE" is not strong enough, it should be at least "WARNING".

> ++
> +By default the command records the date from the e-mail
> +message as the commit author date, and uses the time of
> +commit creation as the committer date. This allows the
> +user to lie about the committer date by using the same
> +value as the author date.

I would not mind leaving the description first and the warning in the
follow-up paragraph. It would make for a better flow of reading.

Perhaps insert "Do not use this option." as the the first sentence,
either before the description (my preference) or in the warning.

Thank you for picking up this topic.

-- Hannes