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

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

❦

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