[PATCH] docs/format-patch: mention handling of merges

[Jeff King <peff@peff.net>]

On Mon, Feb 22, 2021 at 05:57:50PM -0500, Jeff King wrote:

> This is expected. Format-patch omits merge commits entirely, as they
> can't be formatted as a simple diff that can be applied.

We don't seem to advertise this very well in the documentation.

I think we should at least do something like the patch below. I do have
a dream that one day we'll be able to represent conflict resolutions
over email, but we're not there yet.

Likewise, it might be reasonable format-patch to issue a warning() when
it is ignoring a merge. Or maybe some people would find that annoying
(e.g., because they don't care about back-merges from upstream that
happened during the development of a topic).

But I think this documentation change is easy and hopefully
uncontroversial.

-- >8 --
Subject: [PATCH] docs/format-patch: mention handling of merges

Format-patch doesn't have a way to format merges in a way that can be
applied by git-am (or any other tool), and so it just omits them.
However, this may be a surprising implication for users who are not well
versed in how the tool works. Let's add a note to the documentation
making this more clear.

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/git-format-patch.txt | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 3e49bf2210..33649098ce 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -36,7 +36,7 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Prepare each commit with its patch in
+Prepare each non-merge commit with its patch in
 one file per commit, formatted to resemble UNIX mailbox format.
 The output of this command is convenient for e-mail submission or
 for use with 'git am'.
@@ -718,6 +718,13 @@ use it only when you know the recipient uses Git to apply your patch.
 $ git format-patch -3
 ------------
 
+CAVEATS
+-------
+
+Note that `format-patch` cannot represent commits with more than one
+parent (i.e., merges) and will silently omit them entirely from its
+output, even if they are part of the requested range.
+
 SEE ALSO
 --------
 linkgit:git-am[1], linkgit:git-send-email[1]
-- 
2.30.1.1033.gd525307ce1