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

From: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
Date: Feb 9, 2026, 23:11 UTC
Message-ID: <80bbe45f-2c9e-465f-87aa-c7cb64175ccb@app.fastmail.com>
In-Reply-To: <xmqqikc534mk.fsf@gitster.g>

On Mon, Feb 9, 2026, at 23:59, Junio C Hamano wrote:

Show 18 quoted lines

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

Show 5 quoted lines

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