From: kristofferhaugsbakk@fastmail.com Date: Wed, 08 Oct 2025 19:45:20 GMT Subject: [PATCH] doc: warn against --committer-date-is-author-date Message-ID: In-Reply-To: <6af09726-e3bf-4903-87ae-9524ad334678@kdbg.org> From: Kristoffer Haugsbakk 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 Signed-off-by: Kristoffer Haugsbakk --- 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 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