How dangerous is --committer-date-is-author-date these days?

How dangerous is --committer-date-is-author-date these days?

[Johannes Sixt]

The option --committer-date-is-author-date of git-rebase rewrites the
committer dates like its name suggests. It is not uncommon that commits
are rearranged and cherry-picked. Then, as a consequence, author dates
are not decreasing when walking back in history. Now, if such a history
with a non-monotonic author date is rebased one final time with
--committer-date-is-author-date, this creates a history with
non-monotonic committer dates. I recall that this is not a good thing to
have since it can confuse our history walker.

- Why do we have --committer-date-is-author-date in a porcelain command?
- Should we remove it?
- Should we require an explicit --force instead of implying it?
- Should we issue a big warning about the consequences?

Here is the discussion that introduced the option git-rebase:
rebase -i: support --committer-date-is-author-date
https://lore.kernel.org/git/20200817174004.92455-4-phillip.wood123@gmail.com/

I am asking this here after I have participated in this Stackoverflow
question, where git rebase --committer-date-is-author-date was suggested
as a solution to "rewrite name and email, but not timestamps".
https://stackoverflow.com/questions/79024409

-- Hannes

Re: How dangerous is --committer-date-is-author-date these days?

[Phillip Wood]

Hi Johannes

On 28/09/2024 07:59, Johannes Sixt wrote:
> The option --committer-date-is-author-date of git-rebase rewrites the
> committer dates like its name suggests. It is not uncommon that commits
> are rearranged and cherry-picked. Then, as a consequence, author dates
> are not decreasing when walking back in history. Now, if such a history
> with a non-monotonic author date is rebased one final time with
> --committer-date-is-author-date, this creates a history with
> non-monotonic committer dates. I recall that this is not a good thing to
> have since it can confuse our history walker.
> 
> - Why do we have --committer-date-is-author-date in a porcelain command?

Support was added to the sequencer to reduce the differences between the 
two rebase backends in the hope that one day we'll be able to remove the 
apply based backend. Support was added to the shell based rebase in 
570ccad33e (rebase: add options passed to git-am, 2009-03-18), there is 
not much discussion in the commit message or mailing list thread [1] 
about the motivation for adding this support.

[1] 
https://lore.kernel.org/git/1237409629-4289-1-git-send-email-barra_cuda@katamail.com/

> - Should we remove it?

It is only a problem when re-arranging commits - even then I think the 
commit walk machinery has some tolerance to commit dates that do not 
increase monotonically in order accommodate clocks that are out of sync. 
It is perfectly fine for non-interactive rebases (or just squashing 
fixups) so removing it seems like throwing out the baby with the bathwater.

> - Should we require an explicit --force instead of implying it?

I think we'd want a convincing reason to change the behavior - the other 
options that require the history to be rewritten all imply "--force" 
rather than requiring the user to pass it separately.

> - Should we issue a big warning about the consequences?

It would certainly be worth adding a warning to the documentation. To 
issue a warning at run-time would require us to check that the commits 
are actually being re-arranged as there are plenty of reasons to use 
"--interactive" without changing the order of commits.

Best Wishes

Phillip

Re: How dangerous is --committer-date-is-author-date these days?

[Phillip Wood]

On 28/09/2024 10:49, Phillip Wood wrote:
>> - Should we remove it?
> 
> It is only a problem when re-arranging commits 

Of course it's also a problem if one is rebasing onto a commit that is 
newer than the commits that are being rebased. That makes it more of a 
concern, though the option has existed since 2009 and I don't recall 
anyone complaining about the effects of using it. We should certainly 
spell out the potential problems in the documentation.

Best Wishes

Phillip

Re: How dangerous is --committer-date-is-author-date these days?

[Kristoffer Haugsbakk]

As a Git user, I don’t understand why some people want to fiddle with
this field in rewrite operations.  It’s very hidden (apparently you have
to use something like `git log --format=fuller` to reveal it).

I can’t speak for power users.  But regular users?  Well I see questions
about being very deliberate about setting this field on rewrite
operations on StackOverflow (at least one time).  But I can only guess
*why* they are particular about it (this part is often not explained).
And I don’t know if they know the true “spirit” behind the field.
Maybe they are of the impression that committer date and author date
*ought to* be the same?

Of course the aforementioned patch by Philip[1] was done in order to
make the available options between the two rebase backends consistent.
This option `--committer-date-is-author-date` was first added in
3f01ad66549 (am: Add --committer-date-is-author-date option,
2009-01-22).  The email that I could find[2] for the patch has no
follow-up replies.

That option was added to git-am(1).  So not a rewrite operation.  Rather
a “lie” (as it was documented on that commit).

Which ties me back to the “regular user” point: most people don’t use
email workflows.  So adding commits from email is not something they do.
Surely most uses of this option is in git-rebase(1).  And most users
might take for a given that author=committer.  In turn also that
committer-date=author-date.

Again for those who care enough to hunt down this long (words) option.

🔗 1: https://lore.kernel.org/git/20200817174004.92455-4-phillip.wood123@gmail.com/
🔗 2: https://lore.kernel.org/git/20090124101750.6117@nanako3.lavabit.com/

-- 
Kristoffer Haugsbakk

Re: How dangerous is --committer-date-is-author-date these days?

[Junio C Hamano]

"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:

> As a Git user, I don’t understand why some people want to fiddle with
> this field in rewrite operations.  It’s very hidden (apparently you have
> to use something like `git log --format=fuller` to reveal it).

FWIW, as a Git user, I don't, either.

It is justifiable for "rebase -i" to be aware of the option, merely
because the underlying "git am" had it.  I think "--ignore-date"
option falls into a similar bucket, but it is of lessor evil between
the two (at least I can see a legitimate reasoning behind use of
that option).

> I can’t speak for power users.  But regular users?  Well I see questions
> about being very deliberate about setting this field on rewrite
> operations on StackOverflow (at least one time).  But I can only guess
> *why* they are particular about it (this part is often not explained).
> And I don’t know if they know the true “spirit” behind the field.

Very nicely said.  There _might_ be a legitimate reason to futz with
the committer date, but I do not think of a good reason why it makes
sense to replace it with the author date.  They are separate fields
because they mean different things---your mention of "true spirit"
is spot-on.

> That option was added to git-am(1).  So not a rewrite operation.  Rather
> a “lie” (as it was documented on that commit).

Yes, I do not offhand see a reason why the option should exist.  I
won't be the person who says "no, it is valuable, do not touch it"
if somebody proposes to drop it (from all places) at a major version
boundary.

Thanks.

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

[kristofferhaugsbakk]

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

❦

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/

Suggested-by: Johannes Sixt <j6t@kdbg.org>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    Topic name: kh/committer-author-date
    
    Topic summary: "--committer-date-is-author-date" can create a history
    with commit timestamps that are not strictly increasing. That doesn't
    play well with the revision walking machinery. Warn against that.
    
    (See https://lore.kernel.org/git/cover.1759873165.git.me@ttaylorr.com/ )
    
    -----
    
    I thought about marking it as deprecated but eventually found out why it
    was added. And it wasn’t for some (still unknown) dedication or
    not-explained *want* to keep the committer date and author date in synch
    just-because (as I thought[1]).
    
    Hannes asked[2] why it is a porcelain option? (You can after all script
    the same behavior with a little effort.) Personally I think the Git
    porcelain is not shy about providing facilities for crafting made-up
    histories to its users. And I personally think that’s a good thing.
    
    This does seem to indicate that this option doesn’t make much sense for
    git-rebase(1) though, no? Given that it will `--force-rebase`, i.e. will
    force new commit IDs.
    
    🔗 1: https://lore.kernel.org/git/93041214-4774-49eb-b8bd-24648134cded@app.fastmail.com/
    🔗 2: https://lore.kernel.org/git/6af09726-e3bf-4903-87ae-9524ad334678@kdbg.org/

 Documentation/git-am.adoc     | 17 ++++++++++++-----
 Documentation/git-rebase.adoc | 14 +++++++++++---
 2 files changed, 23 insertions(+), 8 deletions(-)

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.
++
+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.
 
 --ignore-date::
 	By default the command records the date from the e-mail
diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc
index 956d3048f5a..336ee90f7e3 100644
--- a/Documentation/git-rebase.adoc
+++ b/Documentation/git-rebase.adoc
@@ -504,9 +504,17 @@ merge backend;;
 See also INCOMPATIBLE OPTIONS below.
 
 --committer-date-is-author-date::
-	Instead of using the current time as the committer date, use
-	the author date of the commit being rebased as the committer
-	date. This option implies `--force-rebase`.
+	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 commit you are applying (in
+	terms of the author date).
++
+Instead of using the current time as the committer date, use
+the author date of the commit being rebased as the committer
+date. This option implies `--force-rebase`.
 
 --ignore-date::
 --reset-author-date::

base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0
-- 
2.51.0.352.g356bc2d8d49

Re: How dangerous is --committer-date-is-author-date these days?

[SZEDER Gábor]

On Mon, Sep 30, 2024 at 04:49:32PM +0200, Kristoffer Haugsbakk wrote:
> As a Git user, I don’t understand why some people want to fiddle with
> this field in rewrite operations.  It’s very hidden (apparently you have
> to use something like `git log --format=fuller` to reveal it).

FWIW, GitHub and similar sites display only the committer date.

> I can’t speak for power users.  But regular users?  Well I see questions
> about being very deliberate about setting this field on rewrite
> operations on StackOverflow (at least one time).  But I can only guess
> *why* they are particular about it (this part is often not explained).

Perhaps they prefer to see the author date even on GitHub, and try to
work around its shortcomings.

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

[Phillip Wood]

Hi Kristoffer

On 08/10/2025 20:45, kristofferhaugsbakk@fastmail.com wrote:
> 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).
> 
> ❦

What's this?

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

That seems like a reasonable thing for "git am" to do. I'd be interested 
to know what the rationale was for adding it to "git rebase". In 
retrospect I feel it was a mistake to port this option over to the 
sequencer just to match what the am based rebase did.>
> [1]: https://lore.kernel.org/git/46d6db660901221441q60eb90bdge601a7a250c3a247@mail.gmail.com/
> 
>      I thought about marking it as deprecated but eventually found out why it
>      was added. And it wasn’t for some (still unknown) dedication or
>      not-explained *want* to keep the committer date and author date in synch
>      just-because (as I thought[1]).

We should maybe think about deprecating it for "git rebase" though as it 
is a lot less clear that it is sensible there. If you're rebasing a 
branch then there is a very high likely hood that the upstream committer 
dates of the commits the branch is being rebased onto will be newer that 
the author dates of the commits in your branch.

I've left a couple of comments below
> 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]).

Is there a particuaar section of the rev-list man page you had in mind 
here? I had a quick look and I couldn't see anything about clock skew.

>  You should only use
> +	this option to lie about the committer date when applying

s/lie/override/ ?

> +	commits on top of a base which commit is older (in terms of the
> +	commit date) than the oldest patch you are applying.
> ++
> +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.
>   
>   --ignore-date::
>   	By default the command records the date from the e-mail
> diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc
> index 956d3048f5a..336ee90f7e3 100644
> --- a/Documentation/git-rebase.adoc
> +++ b/Documentation/git-rebase.adoc
> @@ -504,9 +504,17 @@ merge backend;;
>   See also INCOMPATIBLE OPTIONS below.
>   
>   --committer-date-is-author-date::
> -	Instead of using the current time as the committer date, use
> -	the author date of the commit being rebased as the committer
> -	date. This option implies `--force-rebase`.
> +	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

The comments above apply here as well. In addition s/applying 
commits/rebasing commits/ for this command I think.

> +	commit date) than the oldest commit you are applying (in
> +	terms of the author date).

We should also warn against using this option when rearranging commits 
with "git rebase -i" as well.

Thanks for working on this, it is a very good idea to add a warning to 
the documentation for this option. I'm going to be off the list for the 
next 10 days or so, I'll look at any re-roll when I return.

Thanks

Phillip

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

[Kristoffer Haugsbakk]

On Thu, Oct 9, 2025, at 15:46, Phillip Wood wrote:
> On 08/10/2025 20:45, kristofferhaugsbakk@fastmail.com wrote:
>>[snip]
>>
>> ❦
>
> What's this?

A thematic break.

>
>> 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]
>>
>>[snip quote]
>>
>> 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.
>
> That seems like a reasonable thing for "git am" to do. I'd be interested
> to know what the rationale was for adding it to "git rebase". In
> retrospect I feel it was a mistake to port this option over to the
> sequencer just to match what the am based rebase did.

There isn’t any more discussion on the patch:

https://lore.kernel.org/git/1237399558-27289-3-git-send-email-barra_cuda@katamail.com/

>> [1]: https://lore.kernel.org/git/46d6db660901221441q60eb90bdge601a7a250c3a247@mail.gmail.com/
>>
>>      I thought about marking it as deprecated but eventually found out why it
>>      was added. And it wasn’t for some (still unknown) dedication or
>>      not-explained *want* to keep the committer date and author date in synch
>>      just-because (as I thought[1]).
>
> We should maybe think about deprecating it for "git rebase" though as it
> is a lot less clear that it is sensible there. If you're rebasing a
> branch then there is a very high likely hood that the upstream committer
> dates of the commits the branch is being rebased onto will be newer that
> the author dates of the commits in your branch.

That makes sense. If there is no use case then it should be deprecated.

I could mark it as such in the next version.

Anyone else have an opinion on this?

>
> I've left a couple of comments below
>> 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]).
>
> Is there a particuaar section of the rev-list man page you had in mind
> here? I had a quick look and I couldn't see anything about clock skew.

No, I just thought linking to the “history walking command” was apropos.
I’ll remove it in the next version.

>
>>  You should only use
>> +	this option to lie about the committer date when applying
>
> s/lie/override/ ?

I’ll make that change.

>>[snip]
>> diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc
>> index 956d3048f5a..336ee90f7e3 100644
>> --- a/Documentation/git-rebase.adoc
>> +++ b/Documentation/git-rebase.adoc
>> @@ -504,9 +504,17 @@ merge backend;;
>>   See also INCOMPATIBLE OPTIONS below.
>>
>>   --committer-date-is-author-date::
>> -	Instead of using the current time as the committer date, use
>> -	the author date of the commit being rebased as the committer
>> -	date. This option implies `--force-rebase`.
>> +	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
>
> The comments above apply here as well. In addition s/applying
> commits/rebasing commits/ for this command I think.

Okay, thanks.

>
>> +	commit date) than the oldest commit you are applying (in
>> +	terms of the author date).
>
> We should also warn against using this option when rearranging commits
> with "git rebase -i" as well.

Okay but what does that mean? Should this “note” call out `-i`
specifically? And if so why is that?

> Thanks for working on this, it is a very good idea to add a warning to
> the documentation for this option. I'm going to be off the list for the
> next 10 days or so, I'll look at any re-roll when I return.

Thanks for the review!

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

[Kristoffer Haugsbakk]

On Thu, Oct 9, 2025, at 16:31, Kristoffer Haugsbakk wrote:
>> We should maybe think about deprecating it for "git rebase" though as it
>> is a lot less clear that it is sensible there. If you're rebasing a
>> branch then there is a very high likely hood that the upstream committer
>> dates of the commits the branch is being rebased onto will be newer that
>> the author dates of the commits in your branch.
>
> That makes sense. If there is no use case then it should be deprecated.
>
> I could mark it as such in the next version.
>
> Anyone else have an opinion on this?
>

By the way. I thought of adding a stderr warning when using this option
on git-rebase(1). But I don’t think I’ve seen that used in this program
before. If so, why is that? That’s more in your face than just adding it
to the documentation.

Is it about people parsing stderr, maybe..?

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

[Junio C Hamano]

Phillip Wood <phillip.wood123@gmail.com> writes:

>>  You should only use
>> +	this option to lie about the committer date when applying
>
> s/lie/override/ ?

It cannot be "fixing an earlier mistake by overriding the correct
data".  It is deliberately using a data that does not match the
reality to replace what was recorded, so in this case, "lie" would
be the proper characterization, I would think.

>>   --committer-date-is-author-date::
>> -	Instead of using the current time as the committer date, use
>> -	the author date of the commit being rebased as the committer
>> -	date. This option implies `--force-rebase`.
>> +	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
>
> The comments above apply here as well. In addition s/applying 
> commits/rebasing commits/ for this command I think.
>
>> +	commit date) than the oldest commit you are applying (in
>> +	terms of the author date).
>
> We should also warn against using this option when rearranging commits 
> with "git rebase -i" as well.

True.

> Thanks for working on this, it is a very good idea to add a warning to 
> the documentation for this option. I'm going to be off the list for the 
> next 10 days or so, I'll look at any re-roll when I return.

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

[Kristoffer Haugsbakk]

On Thu, Oct 9, 2025, at 23:41, Junio C Hamano wrote:
> Phillip Wood <phillip.wood123@gmail.com> writes:
>
>>>  You should only use
>>> +	this option to lie about the committer date when applying
>>
>> s/lie/override/ ?
>
> It cannot be "fixing an earlier mistake by overriding the correct
> data".  It is deliberately using a data that does not match the
> reality to replace what was recorded, so in this case, "lie" would
> be the proper characterization, I would think.

Okay. I don’t think he was saying “fix” but just the more neutral
“override”.

I was more confused last year[1] about the use-case here, in turn more
dismissive; I thought that it was just a vanity thing. I’m all for
dictating what the author date is since that’s my judgement to make, and
moreover such fiddling is naturally tempered by common sense. (Did I
author this between one month ago and now: yes, because I originally
wrote it one month ago and then amended it three times in this
timestamp. Did I author this *three months* ago: No, I hadn’t even
thought about it at that point. That’s just a lie).

It’s easy to have a common sense for the authoring date because everyone
knows of “authoring”. It’s more difficult for people to have common
sense for the commit date if they don’t know what “committer” is for.

I guess I like the pointed “lie” in this case because uncareful lying
can cause technical issues. So you better sharpen your senses and have a
real reason for doing it.

🔗 1: https://lore.kernel.org/git/93041214-4774-49eb-b8bd-24648134cded@app.fastmail.com/

>
>[snip]

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

[Junio C Hamano]

"Kristoffer Haugsbakk" <code@khaugsbakk.name> writes:

> On Thu, Oct 9, 2025, at 16:31, Kristoffer Haugsbakk wrote:
>>> We should maybe think about deprecating it for "git rebase" though as it
>>> is a lot less clear that it is sensible there. If you're rebasing a
>>> branch then there is a very high likely hood that the upstream committer
>>> dates of the commits the branch is being rebased onto will be newer that
>>> the author dates of the commits in your branch.
>>
>> That makes sense. If there is no use case then it should be deprecated.
>>
>> I could mark it as such in the next version.
>>
>> Anyone else have an opinion on this?
>>
>
> By the way. I thought of adding a stderr warning when using this option
> on git-rebase(1). But I don’t think I’ve seen that used in this program
> before. If so, why is that? That’s more in your face than just adding it
> to the documentation.
>
> Is it about people parsing stderr, maybe..?

Standard error stream would be buried in other progress things, and
it won't be seen if you are "rebase -i" interactive, in which case
the first thing you see is a full-screen editor with list of
instructions (where we _could_ add new warning text).

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

[Kristoffer Haugsbakk]

On Thu, Oct 9, 2025, at 23:58, Junio C Hamano wrote:
> "Kristoffer Haugsbakk" <code@khaugsbakk.name> writes:
>> By the way. I thought of adding a stderr warning when using this option
>> on git-rebase(1). But I don’t think I’ve seen that used in this program
>> before. If so, why is that? That’s more in your face than just adding it
>> to the documentation.
>>
>> Is it about people parsing stderr, maybe..?
>
> Standard error stream would be buried in other progress things, and
> it won't be seen if you are "rebase -i" interactive, in which case
> the first thing you see is a full-screen editor with list of
> instructions
>
> (where we _could_ add new warning text).

Ooh, that sounds interesting. >:)

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

[Johannes Sixt]

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

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

[Kristoffer Haugsbakk]

Good afternoon Hannes

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)?
2. What is a better way to achieve this goal? (assuming (1) is true)

   It seemed to me that you might as well use the author date.  Unless
   setting max Unix time would be better?  Then at least you will never
   manage to apply something on top of something with a newer commit
   timestamp.

† 1: Since this is not what git-am(1) is designed for

>>[snip]
>> +	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".

Thanks.  I’ll do that.

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

Okay.  My thought process was that this was important enough to
front-load for readers.  But regarding flow: the reader can see the
all-caps keyword and skip the paragraph easily if they want/on repeated
reads.

But I’m perfectly fine with leaving it in the second paragraph.

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.

> 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.
But let’s see.

You preferred option sounds good to me.

You say “first sentence” so I guess we’re not making a one-sentence
paragraph.  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: ...

Thanks for the review.

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

[Kristoffer Haugsbakk]

On Thu, Oct 16, 2025, at 16:13, Kristoffer Haugsbakk wrote:
> Good afternoon Hannes
>
> 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)?
> 2. What is a better way to achieve this goal? (assuming (1) is true)
>
>    It seemed to me that you might as well use the author date.  Unless
>    setting max Unix time would be better?  Then at least you will never
>    manage to apply something on top of something with a newer commit
>    timestamp.

To clarify.  My plan for v2 was to deprecate this option for
git-rebase(1) but not for git-am(1).

>
> † 1: Since this is not what git-am(1) is designed for
>[snip]

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

[Johannes Sixt]

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

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

[Kristoffer Haugsbakk]

On Thu, Oct 16, 2025, at 17:28, Johannes Sixt wrote:
> 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??

Okay, a good question. :) The part about that request that I have
thought about before was using git-am(1) to apply patches to the same
base commit and get the same hash.  Which would mean fixing both the
committer (to some dummy name) and the committer date.  Then someone can
use git-am(1) and patches for transport.

But with this scheme you need to be the same committer.  And why would
the same committer need to apply the same patches to the same base
multiple times?  Indeed. :)

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

Okay, then we can scratch that idea (point № 1).  In turn the second
point becomes irrelevant.

Context for others: Junio’s reply to that request:

https://lore.kernel.org/git/7vljt26fp9.fsf@gitster.siamese.dyndns.org/

Aside: It seems like we can make a more straightforward change if we all
agree that this option does not belong to either of these commands.  I
would not mind that outcome at all.

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

Thanks.

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

[Junio C Hamano]

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.

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

[Kristoffer Haugsbakk]

On Thu, Oct 16, 2025, at 18:23, Junio C Hamano wrote:
> Johannes Sixt <j6t@kdbg.org> writes:
>>[snip]
>> 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".

I agree with just warning.

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

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

This option could create a commit history which violates the assumption
that commits have non-decreasing commit timestamps. Warn against that in
both git-am(1) and git-rebase(1).

The genesis of this option is from git-am(1) and was added in
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).

[1]: https://lore.kernel.org/git/46d6db660901221441q60eb90bdge601a7a250c3a247@mail.gmail.com/

So the motivation was to treat git-am(1) as an import command that
creates the same commit IDs.

Putting aside the question of whether you should be using git-am(1) for
importing commits, this approach is problematic:

• you still need to apply the commits to the same base if you want the
  same hashes; and
• you need the same committer.

And if you expect the same committer, why is this person applying the
same patches multiple times with the goal of making *identical* commits?

That was all for git-am(1).

It was added to git-rebase(1) in 570ccad3 (rebase: add options passed to
git-am, 2009-03-18)[2] in order to plug options that could not be sent
on to git-am(1). At this point the utility of the option graduated to
making no sense; a use case for `git rebase --committer-date-is-author-
date` is still yet to be found.

Just warn against using this option on both commands and remind the user
to consider whether they really need it.

† 2: See also 7573cec5 (rebase -i: support
     --committer-date-is-author-date, 2020-08-17) for the commit for the
     merge backend

Suggested-by: Johannes Sixt <j6t@kdbg.org>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    Topic name: kh/committer-author-date
    
    Topic summary: "--committer-date-is-author-date" can create a history
    with commit timestamps that are not strictly increasing. That doesn't
    play well with the revision walking machinery. Warn against that.
    
    (See https://lore.kernel.org/git/cover.1759873165.git.me@ttaylorr.com/ )
    
    -----
    
    v2:
    
    Add sentence “You should consider if you really need to use this option.”
    in front of “[make sure you] only use this option to ...”.
    
    The problem here is whether to:
    
    1. Go over the history of why it exists
    2. Say don’t use it
    3. Prod them to think about why they are using it
    
    Opt for (3) in the spirit of giving the user the rope they may think
    they need, just with a reminder to consider what they are actually
    trying to achieve.[0]
    
    There was a discussion about deprecating it. But this version still
    just warns.[0]
    
    And:
    
    • Commit message: Drop “legitimate uses” after reviewer feedback and
      discussion. The message goes into why the reported use case does not make
      enough sense
    • Use `WARNING` as a callout instead of `NOTE`[1]
    • Put the warning paragraph second/last[2]
    • Commit message: Use “override” instead of “lie”.[3] Either works but
      “override” is more neutral[4] and not less forthright.
    • Drop “clock skew” and git-rev-list(1) mention[5]
    • Commit message: Tweak “The genesis” paragraph: “is from git-am(1)” since
      most of the explanation goes over the git-am(1) option
    • Use “non-decreasing commit timestamps”. I guess “strictly increasing”
      means that the commit timestamps need to be greater for each.  But a commit
      B that follows A can have the same timestamp, that’s ok.
    • s/applying commits/rebasing commits/ in git-rebase(1)[6]
    
    🔗 0: https://lore.kernel.org/git/xmqqbjm695p4.fsf@gitster.g/#t
    🔗 1: https://lore.kernel.org/git/601b145d-b183-4101-acb3-4a32b2ec4380@kdbg.org/
    🔗 2: https://lore.kernel.org/git/601b145d-b183-4101-acb3-4a32b2ec4380@kdbg.org/
    🔗 3: https://lore.kernel.org/git/3a8dfd13-982d-4c83-b675-1e9a63bb6ab0@gmail.com/
    🔗 4: https://lore.kernel.org/git/6a921119-6fba-4f82-916f-d80d3f46d54d@app.fastmail.com/
    🔗 5: https://lore.kernel.org/git/3a8dfd13-982d-4c83-b675-1e9a63bb6ab0@gmail.com/
    🔗 6: https://lore.kernel.org/git/3a8dfd13-982d-4c83-b675-1e9a63bb6ab0@gmail.com/
    
    v1:
    
    I thought about marking it as deprecated but eventually found out why it
    was added. And it wasn’t for some (still unknown) dedication or
    not-explained *want* to keep the committer date and author date in synch
    just-because (as I thought[1]).
    
    Hannes asked[2] why it is a porcelain option? (You can after all script
    the same behavior with a little effort.) Personally I think the Git
    porcelain is not shy about providing facilities for crafting made-up
    histories to its users. And I personally think that’s a good thing.
    
    This does seem to indicate that this option doesn’t make much sense for
    git-rebase(1) though, no? Given that it will `--force-rebase`, i.e. will
    force new commit IDs.
    
    🔗 1: https://lore.kernel.org/git/93041214-4774-49eb-b8bd-24648134cded@app.fastmail.com/
    🔗 2: https://lore.kernel.org/git/6af09726-e3bf-4903-87ae-9524ad334678@kdbg.org/

 Documentation/git-am.adoc     | 7 +++++++
 Documentation/git-rebase.adoc | 7 +++++++
 2 files changed, 14 insertions(+)

diff --git a/Documentation/git-am.adoc b/Documentation/git-am.adoc
index 221070de481..264d21a7de7 100644
--- a/Documentation/git-am.adoc
+++ b/Documentation/git-am.adoc
@@ -161,6 +161,13 @@ Valid <action> for the `--whitespace` option are:
 	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.
++
+WARNING: The history walking machinery assumes that commits have
+non-decreasing commit timestamps. You should consider if you really need
+to use this option. Then you should only use this option to override 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.
 
 --ignore-date::
 	By default the command records the date from the e-mail
diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc
index 956d3048f5a..0f808c82b28 100644
--- a/Documentation/git-rebase.adoc
+++ b/Documentation/git-rebase.adoc
@@ -507,6 +507,13 @@ See also INCOMPATIBLE OPTIONS below.
 	Instead of using the current time as the committer date, use
 	the author date of the commit being rebased as the committer
 	date. This option implies `--force-rebase`.
++
+WARNING: The history walking machinery assumes that commits have
+non-decreasing commit timestamps. You should consider if you really need
+to use this option. Then you should only use this option to override the
+committer date when rebasing commits on top of a base which commit is
+older (in terms of the commit date) than the oldest commit you are
+applying (in terms of the author date).
 
 --ignore-date::
 --reset-author-date::

Interdiff against v1:
  diff --git a/Documentation/git-am.adoc b/Documentation/git-am.adoc
  index c36ae679cfb..264d21a7de7 100644
  --- a/Documentation/git-am.adoc
  +++ b/Documentation/git-am.adoc
  @@ -156,18 +156,18 @@ Valid <action> for the `--whitespace` option are:
   	See also linkgit:githooks[5].
   
   --committer-date-is-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.
  +	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.
   +
  -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.
  +WARNING: The history walking machinery assumes that commits have
  +non-decreasing commit timestamps. You should consider if you really need
  +to use this option. Then you should only use this option to override 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.
   
   --ignore-date::
   	By default the command records the date from the e-mail
  diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc
  index 336ee90f7e3..0f808c82b28 100644
  --- a/Documentation/git-rebase.adoc
  +++ b/Documentation/git-rebase.adoc
  @@ -504,17 +504,16 @@ merge backend;;
   See also INCOMPATIBLE OPTIONS below.
   
   --committer-date-is-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 commit you are applying (in
  -	terms of the author date).
  +	Instead of using the current time as the committer date, use
  +	the author date of the commit being rebased as the committer
  +	date. This option implies `--force-rebase`.
   +
  -Instead of using the current time as the committer date, use
  -the author date of the commit being rebased as the committer
  -date. This option implies `--force-rebase`.
  +WARNING: The history walking machinery assumes that commits have
  +non-decreasing commit timestamps. You should consider if you really need
  +to use this option. Then you should only use this option to override the
  +committer date when rebasing commits on top of a base which commit is
  +older (in terms of the commit date) than the oldest commit you are
  +applying (in terms of the author date).
   
   --ignore-date::
   --reset-author-date::

Range-diff against v1:
1:  d17060d9b72 ! 1:  203a9b9db2c doc: warn against --committer-date-is-author-date
    @@ Metadata
      ## Commit message ##
         doc: warn against --committer-date-is-author-date
     
    -    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).
    +    This option could create a commit history which violates the assumption
    +    that commits have non-decreasing commit timestamps. Warn against that in
    +    both git-am(1) and git-rebase(1).
     
    -    ❦
    -
    -    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]
    +    The genesis of this option is from git-am(1) and was added in
    +    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.
    @@ Commit message
             I received the email (and therefore always get back the right
             sha1sums).
     
    +    [1]: https://lore.kernel.org/git/46d6db660901221441q60eb90bdge601a7a250c3a247@mail.gmail.com/
    +
         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.
    +    creates the same commit IDs.
     
    -    [1]: https://lore.kernel.org/git/46d6db660901221441q60eb90bdge601a7a250c3a247@mail.gmail.com/
    +    Putting aside the question of whether you should be using git-am(1) for
    +    importing commits, this approach is problematic:
    +
    +    • you still need to apply the commits to the same base if you want the
    +      same hashes; and
    +    • you need the same committer.
    +
    +    And if you expect the same committer, why is this person applying the
    +    same patches multiple times with the goal of making *identical* commits?
    +
    +    That was all for git-am(1).
    +
    +    It was added to git-rebase(1) in 570ccad3 (rebase: add options passed to
    +    git-am, 2009-03-18)[2] in order to plug options that could not be sent
    +    on to git-am(1). At this point the utility of the option graduated to
    +    making no sense; a use case for `git rebase --committer-date-is-author-
    +    date` is still yet to be found.
    +
    +    Just warn against using this option on both commands and remind the user
    +    to consider whether they really need it.
    +
    +    † 2: See also 7573cec5 (rebase -i: support
    +         --committer-date-is-author-date, 2020-08-17) for the commit for the
    +         merge backend
     
         Suggested-by: Johannes Sixt <j6t@kdbg.org>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
    @@ Notes (series)
     
         v2:
     
    -    • Deprecate in addition to warning
    +    Add sentence “You should consider if you really need to use this option.”
    +    in front of “[make sure you] only use this option to ...”.
    +
    +    The problem here is whether to:
    +
    +    1. Go over the history of why it exists
    +    2. Say don’t use it
    +    3. Prod them to think about why they are using it
    +
    +    Opt for (3) in the spirit of giving the user the rope they may think
    +    they need, just with a reminder to consider what they are actually
    +    trying to achieve.[0]
    +
    +    There was a discussion about deprecating it. But this version still
    +    just warns.[0]
    +
    +    And:
    +
    +    • Commit message: Drop “legitimate uses” after reviewer feedback and
    +      discussion. The message goes into why the reported use case does not make
    +      enough sense
         • Use `WARNING` as a callout instead of `NOTE`[1]
         • Put the warning paragraph second/last[2]
    -    • Use “override” instead of “lie”.[3] Either works but “override” is
    -      more neutral[4] and not less forthright.
    +    • Commit message: Use “override” instead of “lie”.[3] Either works but
    +      “override” is more neutral[4] and not less forthright.
         • Drop “clock skew” and git-rev-list(1) mention[5]
    -
    +    • Commit message: Tweak “The genesis” paragraph: “is from git-am(1)” since
    +      most of the explanation goes over the git-am(1) option
    +    • Use “non-decreasing commit timestamps”. I guess “strictly increasing”
    +      means that the commit timestamps need to be greater for each.  But a commit
    +      B that follows A can have the same timestamp, that’s ok.
    +    • s/applying commits/rebasing commits/ in git-rebase(1)[6]
    +
    +    🔗 0: https://lore.kernel.org/git/xmqqbjm695p4.fsf@gitster.g/#t
         🔗 1: https://lore.kernel.org/git/601b145d-b183-4101-acb3-4a32b2ec4380@kdbg.org/
         🔗 2: https://lore.kernel.org/git/601b145d-b183-4101-acb3-4a32b2ec4380@kdbg.org/
         🔗 3: https://lore.kernel.org/git/3a8dfd13-982d-4c83-b675-1e9a63bb6ab0@gmail.com/
         🔗 4: https://lore.kernel.org/git/6a921119-6fba-4f82-916f-d80d3f46d54d@app.fastmail.com/
         🔗 5: https://lore.kernel.org/git/3a8dfd13-982d-4c83-b675-1e9a63bb6ab0@gmail.com/
    +    🔗 6: https://lore.kernel.org/git/3a8dfd13-982d-4c83-b675-1e9a63bb6ab0@gmail.com/
     
         v1:
     
    @@ Notes (series)
     
      ## Documentation/git-am.adoc ##
     @@ Documentation/git-am.adoc: 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.
    + 	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.
     ++
    -+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.
    ++WARNING: The history walking machinery assumes that commits have
    ++non-decreasing commit timestamps. You should consider if you really need
    ++to use this option. Then you should only use this option to override 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.
      
      --ignore-date::
      	By default the command records the date from the e-mail
     
      ## Documentation/git-rebase.adoc ##
    -@@ Documentation/git-rebase.adoc: merge backend;;
    - See also INCOMPATIBLE OPTIONS below.
    - 
    - --committer-date-is-author-date::
    --	Instead of using the current time as the committer date, use
    --	the author date of the commit being rebased as the committer
    --	date. This option implies `--force-rebase`.
    -+	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 commit you are applying (in
    -+	terms of the author date).
    +@@ Documentation/git-rebase.adoc: See also INCOMPATIBLE OPTIONS below.
    + 	Instead of using the current time as the committer date, use
    + 	the author date of the commit being rebased as the committer
    + 	date. This option implies `--force-rebase`.
     ++
    -+Instead of using the current time as the committer date, use
    -+the author date of the commit being rebased as the committer
    -+date. This option implies `--force-rebase`.
    ++WARNING: The history walking machinery assumes that commits have
    ++non-decreasing commit timestamps. You should consider if you really need
    ++to use this option. Then you should only use this option to override the
    ++committer date when rebasing commits on top of a base which commit is
    ++older (in terms of the commit date) than the oldest commit you are
    ++applying (in terms of the author date).
      
      --ignore-date::
      --reset-author-date::

base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0
-- 
2.52.0.10.g08704017180

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

[Johannes Sixt]

Thank you, this round looks good to me!

-- Hannes

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

[Phillip Wood]

Hi Kristoffer

This looks good, I appreciate the detail in the commit message. Sorry 
I've only just got round to looking at it.

Thanks

Phillip

On 20/11/2025 16:26, kristofferhaugsbakk@fastmail.com wrote:
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
> 
> This option could create a commit history which violates the assumption
> that commits have non-decreasing commit timestamps. Warn against that in
> both git-am(1) and git-rebase(1).
> 
> The genesis of this option is from git-am(1) and was added in
> 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).
> 
> [1]: https://lore.kernel.org/git/46d6db660901221441q60eb90bdge601a7a250c3a247@mail.gmail.com/
> 
> So the motivation was to treat git-am(1) as an import command that
> creates the same commit IDs.
> 
> Putting aside the question of whether you should be using git-am(1) for
> importing commits, this approach is problematic:
> 
> • you still need to apply the commits to the same base if you want the
>    same hashes; and
> • you need the same committer.
> 
> And if you expect the same committer, why is this person applying the
> same patches multiple times with the goal of making *identical* commits?
> 
> That was all for git-am(1).
> 
> It was added to git-rebase(1) in 570ccad3 (rebase: add options passed to
> git-am, 2009-03-18)[2] in order to plug options that could not be sent
> on to git-am(1). At this point the utility of the option graduated to
> making no sense; a use case for `git rebase --committer-date-is-author-
> date` is still yet to be found.
> 
> Just warn against using this option on both commands and remind the user
> to consider whether they really need it.
> 
> † 2: See also 7573cec5 (rebase -i: support
>       --committer-date-is-author-date, 2020-08-17) for the commit for the
>       merge backend
> 
> Suggested-by: Johannes Sixt <j6t@kdbg.org>
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> ---
> 
> Notes (series):
>      Topic name: kh/committer-author-date
>      
>      Topic summary: "--committer-date-is-author-date" can create a history
>      with commit timestamps that are not strictly increasing. That doesn't
>      play well with the revision walking machinery. Warn against that.
>      
>      (See https://lore.kernel.org/git/cover.1759873165.git.me@ttaylorr.com/ )
>      
>      -----
>      
>      v2:
>      
>      Add sentence “You should consider if you really need to use this option.”
>      in front of “[make sure you] only use this option to ...”.
>      
>      The problem here is whether to:
>      
>      1. Go over the history of why it exists
>      2. Say don’t use it
>      3. Prod them to think about why they are using it
>      
>      Opt for (3) in the spirit of giving the user the rope they may think
>      they need, just with a reminder to consider what they are actually
>      trying to achieve.[0]
>      
>      There was a discussion about deprecating it. But this version still
>      just warns.[0]
>      
>      And:
>      
>      • Commit message: Drop “legitimate uses” after reviewer feedback and
>        discussion. The message goes into why the reported use case does not make
>        enough sense
>      • Use `WARNING` as a callout instead of `NOTE`[1]
>      • Put the warning paragraph second/last[2]
>      • Commit message: Use “override” instead of “lie”.[3] Either works but
>        “override” is more neutral[4] and not less forthright.
>      • Drop “clock skew” and git-rev-list(1) mention[5]
>      • Commit message: Tweak “The genesis” paragraph: “is from git-am(1)” since
>        most of the explanation goes over the git-am(1) option
>      • Use “non-decreasing commit timestamps”. I guess “strictly increasing”
>        means that the commit timestamps need to be greater for each.  But a commit
>        B that follows A can have the same timestamp, that’s ok.
>      • s/applying commits/rebasing commits/ in git-rebase(1)[6]
>      
>      🔗 0: https://lore.kernel.org/git/xmqqbjm695p4.fsf@gitster.g/#t
>      🔗 1: https://lore.kernel.org/git/601b145d-b183-4101-acb3-4a32b2ec4380@kdbg.org/
>      🔗 2: https://lore.kernel.org/git/601b145d-b183-4101-acb3-4a32b2ec4380@kdbg.org/
>      🔗 3: https://lore.kernel.org/git/3a8dfd13-982d-4c83-b675-1e9a63bb6ab0@gmail.com/
>      🔗 4: https://lore.kernel.org/git/6a921119-6fba-4f82-916f-d80d3f46d54d@app.fastmail.com/
>      🔗 5: https://lore.kernel.org/git/3a8dfd13-982d-4c83-b675-1e9a63bb6ab0@gmail.com/
>      🔗 6: https://lore.kernel.org/git/3a8dfd13-982d-4c83-b675-1e9a63bb6ab0@gmail.com/
>      
>      v1:
>      
>      I thought about marking it as deprecated but eventually found out why it
>      was added. And it wasn’t for some (still unknown) dedication or
>      not-explained *want* to keep the committer date and author date in synch
>      just-because (as I thought[1]).
>      
>      Hannes asked[2] why it is a porcelain option? (You can after all script
>      the same behavior with a little effort.) Personally I think the Git
>      porcelain is not shy about providing facilities for crafting made-up
>      histories to its users. And I personally think that’s a good thing.
>      
>      This does seem to indicate that this option doesn’t make much sense for
>      git-rebase(1) though, no? Given that it will `--force-rebase`, i.e. will
>      force new commit IDs.
>      
>      🔗 1: https://lore.kernel.org/git/93041214-4774-49eb-b8bd-24648134cded@app.fastmail.com/
>      🔗 2: https://lore.kernel.org/git/6af09726-e3bf-4903-87ae-9524ad334678@kdbg.org/
> 
>   Documentation/git-am.adoc     | 7 +++++++
>   Documentation/git-rebase.adoc | 7 +++++++
>   2 files changed, 14 insertions(+)
> 
> diff --git a/Documentation/git-am.adoc b/Documentation/git-am.adoc
> index 221070de481..264d21a7de7 100644
> --- a/Documentation/git-am.adoc
> +++ b/Documentation/git-am.adoc
> @@ -161,6 +161,13 @@ Valid <action> for the `--whitespace` option are:
>   	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.
> ++
> +WARNING: The history walking machinery assumes that commits have
> +non-decreasing commit timestamps. You should consider if you really need
> +to use this option. Then you should only use this option to override 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.
>   
>   --ignore-date::
>   	By default the command records the date from the e-mail
> diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc
> index 956d3048f5a..0f808c82b28 100644
> --- a/Documentation/git-rebase.adoc
> +++ b/Documentation/git-rebase.adoc
> @@ -507,6 +507,13 @@ See also INCOMPATIBLE OPTIONS below.
>   	Instead of using the current time as the committer date, use
>   	the author date of the commit being rebased as the committer
>   	date. This option implies `--force-rebase`.
> ++
> +WARNING: The history walking machinery assumes that commits have
> +non-decreasing commit timestamps. You should consider if you really need
> +to use this option. Then you should only use this option to override the
> +committer date when rebasing commits on top of a base which commit is
> +older (in terms of the commit date) than the oldest commit you are
> +applying (in terms of the author date).
>   
>   --ignore-date::
>   --reset-author-date::
> 
> Interdiff against v1:
>    diff --git a/Documentation/git-am.adoc b/Documentation/git-am.adoc
>    index c36ae679cfb..264d21a7de7 100644
>    --- a/Documentation/git-am.adoc
>    +++ b/Documentation/git-am.adoc
>    @@ -156,18 +156,18 @@ Valid <action> for the `--whitespace` option are:
>     	See also linkgit:githooks[5].
>     
>     --committer-date-is-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.
>    +	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.
>     +
>    -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.
>    +WARNING: The history walking machinery assumes that commits have
>    +non-decreasing commit timestamps. You should consider if you really need
>    +to use this option. Then you should only use this option to override 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.
>     
>     --ignore-date::
>     	By default the command records the date from the e-mail
>    diff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc
>    index 336ee90f7e3..0f808c82b28 100644
>    --- a/Documentation/git-rebase.adoc
>    +++ b/Documentation/git-rebase.adoc
>    @@ -504,17 +504,16 @@ merge backend;;
>     See also INCOMPATIBLE OPTIONS below.
>     
>     --committer-date-is-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 commit you are applying (in
>    -	terms of the author date).
>    +	Instead of using the current time as the committer date, use
>    +	the author date of the commit being rebased as the committer
>    +	date. This option implies `--force-rebase`.
>     +
>    -Instead of using the current time as the committer date, use
>    -the author date of the commit being rebased as the committer
>    -date. This option implies `--force-rebase`.
>    +WARNING: The history walking machinery assumes that commits have
>    +non-decreasing commit timestamps. You should consider if you really need
>    +to use this option. Then you should only use this option to override the
>    +committer date when rebasing commits on top of a base which commit is
>    +older (in terms of the commit date) than the oldest commit you are
>    +applying (in terms of the author date).
>     
>     --ignore-date::
>     --reset-author-date::
> 
> Range-diff against v1:
> 1:  d17060d9b72 ! 1:  203a9b9db2c doc: warn against --committer-date-is-author-date
>      @@ Metadata
>        ## Commit message ##
>           doc: warn against --committer-date-is-author-date
>       
>      -    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).
>      +    This option could create a commit history which violates the assumption
>      +    that commits have non-decreasing commit timestamps. Warn against that in
>      +    both git-am(1) and git-rebase(1).
>       
>      -    ❦
>      -
>      -    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]
>      +    The genesis of this option is from git-am(1) and was added in
>      +    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.
>      @@ Commit message
>               I received the email (and therefore always get back the right
>               sha1sums).
>       
>      +    [1]: https://lore.kernel.org/git/46d6db660901221441q60eb90bdge601a7a250c3a247@mail.gmail.com/
>      +
>           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.
>      +    creates the same commit IDs.
>       
>      -    [1]: https://lore.kernel.org/git/46d6db660901221441q60eb90bdge601a7a250c3a247@mail.gmail.com/
>      +    Putting aside the question of whether you should be using git-am(1) for
>      +    importing commits, this approach is problematic:
>      +
>      +    • you still need to apply the commits to the same base if you want the
>      +      same hashes; and
>      +    • you need the same committer.
>      +
>      +    And if you expect the same committer, why is this person applying the
>      +    same patches multiple times with the goal of making *identical* commits?
>      +
>      +    That was all for git-am(1).
>      +
>      +    It was added to git-rebase(1) in 570ccad3 (rebase: add options passed to
>      +    git-am, 2009-03-18)[2] in order to plug options that could not be sent
>      +    on to git-am(1). At this point the utility of the option graduated to
>      +    making no sense; a use case for `git rebase --committer-date-is-author-
>      +    date` is still yet to be found.
>      +
>      +    Just warn against using this option on both commands and remind the user
>      +    to consider whether they really need it.
>      +
>      +    † 2: See also 7573cec5 (rebase -i: support
>      +         --committer-date-is-author-date, 2020-08-17) for the commit for the
>      +         merge backend
>       
>           Suggested-by: Johannes Sixt <j6t@kdbg.org>
>           Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
>      @@ Notes (series)
>       
>           v2:
>       
>      -    • Deprecate in addition to warning
>      +    Add sentence “You should consider if you really need to use this option.”
>      +    in front of “[make sure you] only use this option to ...”.
>      +
>      +    The problem here is whether to:
>      +
>      +    1. Go over the history of why it exists
>      +    2. Say don’t use it
>      +    3. Prod them to think about why they are using it
>      +
>      +    Opt for (3) in the spirit of giving the user the rope they may think
>      +    they need, just with a reminder to consider what they are actually
>      +    trying to achieve.[0]
>      +
>      +    There was a discussion about deprecating it. But this version still
>      +    just warns.[0]
>      +
>      +    And:
>      +
>      +    • Commit message: Drop “legitimate uses” after reviewer feedback and
>      +      discussion. The message goes into why the reported use case does not make
>      +      enough sense
>           • Use `WARNING` as a callout instead of `NOTE`[1]
>           • Put the warning paragraph second/last[2]
>      -    • Use “override” instead of “lie”.[3] Either works but “override” is
>      -      more neutral[4] and not less forthright.
>      +    • Commit message: Use “override” instead of “lie”.[3] Either works but
>      +      “override” is more neutral[4] and not less forthright.
>           • Drop “clock skew” and git-rev-list(1) mention[5]
>      -
>      +    • Commit message: Tweak “The genesis” paragraph: “is from git-am(1)” since
>      +      most of the explanation goes over the git-am(1) option
>      +    • Use “non-decreasing commit timestamps”. I guess “strictly increasing”
>      +      means that the commit timestamps need to be greater for each.  But a commit
>      +      B that follows A can have the same timestamp, that’s ok.
>      +    • s/applying commits/rebasing commits/ in git-rebase(1)[6]
>      +
>      +    🔗 0: https://lore.kernel.org/git/xmqqbjm695p4.fsf@gitster.g/#t
>           🔗 1: https://lore.kernel.org/git/601b145d-b183-4101-acb3-4a32b2ec4380@kdbg.org/
>           🔗 2: https://lore.kernel.org/git/601b145d-b183-4101-acb3-4a32b2ec4380@kdbg.org/
>           🔗 3: https://lore.kernel.org/git/3a8dfd13-982d-4c83-b675-1e9a63bb6ab0@gmail.com/
>           🔗 4: https://lore.kernel.org/git/6a921119-6fba-4f82-916f-d80d3f46d54d@app.fastmail.com/
>           🔗 5: https://lore.kernel.org/git/3a8dfd13-982d-4c83-b675-1e9a63bb6ab0@gmail.com/
>      +    🔗 6: https://lore.kernel.org/git/3a8dfd13-982d-4c83-b675-1e9a63bb6ab0@gmail.com/
>       
>           v1:
>       
>      @@ Notes (series)
>       
>        ## Documentation/git-am.adoc ##
>       @@ Documentation/git-am.adoc: 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.
>      + 	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.
>       ++
>      -+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.
>      ++WARNING: The history walking machinery assumes that commits have
>      ++non-decreasing commit timestamps. You should consider if you really need
>      ++to use this option. Then you should only use this option to override 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.
>        
>        --ignore-date::
>        	By default the command records the date from the e-mail
>       
>        ## Documentation/git-rebase.adoc ##
>      -@@ Documentation/git-rebase.adoc: merge backend;;
>      - See also INCOMPATIBLE OPTIONS below.
>      -
>      - --committer-date-is-author-date::
>      --	Instead of using the current time as the committer date, use
>      --	the author date of the commit being rebased as the committer
>      --	date. This option implies `--force-rebase`.
>      -+	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 commit you are applying (in
>      -+	terms of the author date).
>      +@@ Documentation/git-rebase.adoc: See also INCOMPATIBLE OPTIONS below.
>      + 	Instead of using the current time as the committer date, use
>      + 	the author date of the commit being rebased as the committer
>      + 	date. This option implies `--force-rebase`.
>       ++
>      -+Instead of using the current time as the committer date, use
>      -+the author date of the commit being rebased as the committer
>      -+date. This option implies `--force-rebase`.
>      ++WARNING: The history walking machinery assumes that commits have
>      ++non-decreasing commit timestamps. You should consider if you really need
>      ++to use this option. Then you should only use this option to override the
>      ++committer date when rebasing commits on top of a base which commit is
>      ++older (in terms of the commit date) than the oldest commit you are
>      ++applying (in terms of the author date).
>        
>        --ignore-date::
>        --reset-author-date::
> 
> base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0

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

[Kristoffer Haugsbakk]

On Wed, Nov 26, 2025, at 17:02, Phillip Wood wrote:
> Hi Kristoffer
>
> This looks good, I appreciate the detail in the commit message. Sorry
> I've only just got round to looking at it.

Thanks Johannes, Phillip.