git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
From: Jeff King <peff@peff.net>
To: Wang Yugui <wangyugui@e16-tech.com>
Cc: git@vger.kernel.org
Subject: [PATCH] docs/format-patch: mention handling of merges
Date: Mon, 22 Feb 2021 18:08:16 -0500	[thread overview]
Message-ID: <YDQ5YIeXGiR5nvLH@coredump.intra.peff.net> (raw)
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


  reply	other threads:[~2021-02-22 23:09 UTC|newest]

Thread overview: 10+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-02-22 13:16 git format-patch lost the last part when branch merge Wang Yugui
2021-02-22 22:57 ` Jeff King
2021-02-22 23:08   ` Jeff King [this message]
2021-02-22 23:31     ` [PATCH] docs/format-patch: mention handling of merges Junio C Hamano
2021-02-22 23:40       ` Jeff King
2021-02-23  1:24         ` Junio C Hamano
2021-02-23  1:48           ` Jeff King
2021-02-22 23:25   ` git format-patch lost the last part when branch merge Junio C Hamano
2021-02-24  4:24   ` Elijah Newren
2021-02-24  4:50     ` Jeff King

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=YDQ5YIeXGiR5nvLH@coredump.intra.peff.net \
    --to=peff@peff.net \
    --cc=git@vger.kernel.org \
    --cc=wangyugui@e16-tech.com \
    --subject='Re: [PATCH] docs/format-patch: mention handling of merges' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).