doc: add caveat about roundtripping format-patch

git-format-patch(1), git-send-email(1), and git-am(1) deal with
formatting commits as patches, sending them (perhaps directly), and
applying them, respectively. Naturally they use a few delimiters to mark
where the commit message ends. This can lead to surprising behavior when
these delimiters are used in the commit message itself.

git-format-patch(1) and git-send-email(1) will accept any commit message
and not warn or error about these delimiters being used.[1]

Moreover, the presence of unindented diffs in the commit message will
cause git-am(1) to apply both the diffs from the commit message as well
as the patch section.[2]

It is unclear whether any commands in this chain will learn to warn
about this. One concern could be that users have learned to rely on
the three-dash line rule to conveniently add extra-commit message
information in the commit message, knowing that git-am(1) will
ignore it.[4]

All of this is covered already, technically, However, we should spell
out the implications.

† 1: There is also git-commit(1) to consider. However, making that
     command warn or error out over such delimiters would be disruptive
     to all Git users who never use email in their workflow.
[2]: Recently patch(1) caused this issue for a project, but it was noted
     that git-am(1) has the same behavior[3]
[3]: i3/i3#6564 (comment)
[4]: https://lore.kernel.org/git/xmqqldh4b5y2.fsf@gitster.g/

Reported-by: Matthias Beyer <mail@beyermatthias.de>
Reported-by: Christoph Anton Mitterer <calestyo@scientia.org>
Reported-by: Matheus Tavares <matheus.tavb@gmail.com>
Reported-by: Chris Packham <judge.packham@gmail.com>
Helped-by: Jakob Haufe <sur5r@sur5r.net>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

Author: LemmingAvalanche

Documentation/format-patch-caveats.adoc

@@ -0,0 +1,39 @@
+Patches produced by linkgit:git-format-patch[1] or
+linkgit:git-send-email[1] are inline. This means that the output of
+these two commands can lead to a different commit message when applied
+with linkgit:git-am[1]. It can also mean that the patch is not applied
+correctly.
+
+The commit message might contain a three-dash line (`---`) which was
+perhaps meant to be a thematic break. That means that the commit message
+will be cut short. The presence of a line starting with "Index: " can
+cause the patch not to be found, giving an error about an empty patch.
+
+Furthermore, the presence of an unindented diff in the commit message
+will not only cut the message short but cause that very diff to be
+applied, along with the patch in the patch section. The commit message
+might for example have a diff in a GitHub MarkDown code fence:
+
+----
+```
+diff ...
+```
+----
+
+The solution for this is to indent the diff instead:
+
+----
+    diff ...
+----
+
+This loss of fidelity might be simple to notice if you are applying
+patches directly from a mailbox. However, a commit authored long ago
+might be applied in a different context, perhaps because many changes
+are being integrated via patch files and the
+linkgit:git-format-patch[1] format is trusted to import changes of a
+Git origin.
+
+One might want to use a general-purpose utility like patch(1) instead,
+given these limitations. However, patch(1) will not only look for
+unindented diffs (like linkgit:git-am[1]) but will try to apply indented
+diffs as well.

Documentation/git-am.adoc

@@ -261,6 +261,9 @@ message.  Any line that is of the form:
 is taken as the beginning of a patch, and the commit log message
 is terminated before the first occurrence of such a line.
 
+This means that the content of the commit message can inadverently
+interrupt the processing (see the <<caveats,CAVEATS>> section below).
+
 When initially invoking `git am`, you give it the names of the mailboxes
 to process.  Upon seeing the first patch that does not apply, it
 aborts in the middle.  You can recover from this in one of two ways:
@@ -283,6 +286,12 @@ commits, like running 'git am' on the wrong branch or an error in the
 commits that is more easily fixed by changing the mailbox (e.g.
 errors in the "From:" lines).
 
+[[caveats]]
+CAVEATS
+-------
+
+include::format-patch-caveats.adoc[]
+
 HOOKS
 -----
 This command can run `applypatch-msg`, `pre-applypatch`,

Documentation/git-format-patch.adoc

@@ -798,6 +798,10 @@ if they are part of the requested range. A simple "patch" does not
 include enough information for the receiving end to reproduce the same
 merge commit.
 
+'''
+
+include::format-patch-caveats.adoc[]
+
 SEE ALSO
 --------
 linkgit:git-am[1], linkgit:git-send-email[1]

Documentation/git-send-email.adoc

@@ -692,6 +692,11 @@ Links of a few such community maintained helpers are:
 	- https://github.com/AdityaGarg8/git-credential-email[git-msgraph]
 	  (cross platform client that can send emails using the Microsoft Graph API)
 
+CAVEATS
+-------
+
+include::format-patch-caveats.adoc[]
+
 SEE ALSO
 --------
 linkgit:git-format-patch[1], linkgit:git-imap-send[1], mbox(5)