[PATCH] docs/format-patch: mention handling of merges
- From
Jeff King <peff@peff.net>
- Date
- Feb 22, 2021, 23:08 UTC
- Message-ID
- <YDQ5YIeXGiR5nvLH@coredump.intra.peff.net>
- In-Reply-To
- <YDQ27qbbblPfLCpU@coredump.intra.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