From: Kristoffer Haugsbakk Date: Thu, 20 Nov 2025 16:26:49 +0000 (+0100) Subject: doc: warn against --committer-date-is-author-date X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=fbf3d0669f830b4492070aa33f57dbf2c43fa4c8;p=thirdparty%2Fgit.git doc: warn against --committer-date-is-author-date 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 Signed-off-by: Kristoffer Haugsbakk Acked-by: Johannes Sixt Signed-off-by: Junio C Hamano --- diff --git a/Documentation/git-am.adoc b/Documentation/git-am.adoc index 221070de48..264d21a7de 100644 --- a/Documentation/git-am.adoc +++ b/Documentation/git-am.adoc @@ -161,6 +161,13 @@ Valid 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 956d3048f5..0f808c82b2 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::