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

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 22, 2021, 23:31 UTC
Message-ID: <xmqqv9aj65na.fsf@gitster.g>
In-Reply-To: <YDQ5YIeXGiR5nvLH@coredump.intra.peff.net>

Jeff King <peff@peff.net> writes:

Show 14 quoted lines

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