Re: [PATCH v2] doc: add caveat about roundtripping format-patch

["Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com>]

On Mon, Feb 9, 2026, at 23:59, Junio C Hamano wrote:
> kristofferhaugsbakk@fastmail.com writes:
>
>> diff --git a/Documentation/format-patch-caveats.adoc b/Documentation/format-patch-caveats.adoc
>> new file mode 100644
>> index 00000000000..c666d709742
>> --- /dev/null
>> +++ b/Documentation/format-patch-caveats.adoc
>> @@ -0,0 +1,36 @@
>> +Patches produced by linkgit:git-format-patch[1] are inline. This means
>> +that the output from that command can lead to a different commit message
>> +when applied with linkgit:git-am[1]. It can also mean that the patch
>> +that is applied is not the same as the one that was generated, or that
>> +the patch application fails outright.
>> +ifdef::git-am[]
>> +See the <<discussion,DISCUSSION>> section above for the syntactic rules.
>> +endif::git-am[]
>
> It is news to me that adjective "inline" has such a meaning.

The original intent was to emphasize that the commit message and the
patch being in the same “string” means that there has to be some
delimiter. And that can trip things up since there is no escaping.

But you’re right. This part can be dropped. It is already clear that we
are talking about delimiters that can occur in the commit message.

>
> Whenever I see somebody writes "X. This means Y", I try to see if it
> makes the result easier to understand to more people by just saying
> "Y" without mentioning X, and to me, this is such an occasion.  I'd
> rather see that sentence, plus "This means", taken away.

So write it like this:

    The output from git-patch-format(1) can lead to a different commit
    message ...

I’ll make that change.