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

On Mon, Feb 22, 2021 at 03:31:53PM -0800, Junio C Hamano wrote:

Jeff King [off-list ref] writes:

quoted

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.
...
+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.

I think "cannot represent" is a little bit misleading, unless we
expect the readers already know what we are trying to say (in which
case there is no point in documenting this).  Perhaps something like
this might clarify a bit, though.

    Note that `format-patch` omits merge commits from the output,
    because it is impossible to turn a merge commit into a simple
    "patch" in such a way that allows receiving end to reproduce the
    same merge commit.

That seems worse to me, because "it is impossible" implies that this
can never be changed. But I don't think that's true. We might one day
output something useful for merges.

I think one could argue that any merge information (including conflict
resolution) works against the root notion of format-patch, which is a
set of changes that can be applied on a range of basesa. But even that I
would be hesitant to commit to (since --base exists now). And certainly
it's more subtlety than I'd want to get in to for this note. :)

I almost softened it to "cannot yet represent". Does that read better to
your (or worse)? Likewise, I considered adding a note at the end along
the lines of "this may change in the future", though I suspect we'd only
do so in combination with a command-line option.

-Peff