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

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

Hi Phillip

On Mon, Feb 9, 2026, at 17:42, Phillip Wood wrote:
>[snip]
> On 08/02/2026 00:11, kristofferhaugsbakk@fastmail.com wrote:
>> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>>
>> git-format-patch(1), git-send-email(1), and git-am(1) deal with
>
> I found the mention of git-send-email here and in the documentation a
> bit distracting as it doesn't do any formatting itself - it just runs
> "git format-patch"

Okay, I see now that git-send-email(1) already says that it uses
git-format-patch(1). So we can scratch that command mention. The user
can see from the rest of the git-send-email(1) doc why we have a caveat
about git-format-patch(1).

I first thought that it wouldn’t be obvious why we are talking
about git-format-patch(1) here.

>
>> † 1: There is also git-commit(1) to consider. However, making that
>>       command warn or error out over such delimiters would be disruptive
>>       to all Git users who never use email in their workflow.
>
> This reference is formatted differently to the rest.

Okay, thanks.

I will change to using just one style in the next round. :)

( https://lore.kernel.org/git/doc_am_gitlinks_and_am.messageId.321@msgid.xyz/T/#m38026ad670e866b9ef1a0ef3827fd69316bb1aa3 )

>>[snip]
>> +Patches produced by linkgit:git-format-patch[1] or
>> +linkgit:git-send-email[1] are inline. This means that the output of
>> +these two commands can lead to a different commit message when applied
>> +with linkgit:git-am[1]. It can also mean that the patch is not applied
>> +correctly.
>
> Is this last sentence referring to diffs in the commit message being
> applied? I don't think there are circumstances where the patch itself is
> not applied correctly.

I tested with a line like

    Index x

Yesterday and got an empty patch when running git-am(1). But I couldn’t
reproduce now. I must have made a mistake.

I think this should be changed to:

    It can also mean that the patch that is applied is not the same as
    the one that was generated.

(generated = shorthand for made by git-format-patch(1))

This sentence would then serve as an introduction for the “Furthermore,”
paragraph later.

>>[snip]
>> +----
>> +```
>> +diff ...
>> +```
>> +----
>
> I'm not sure the markdown really adds anything here

I don’t understand? It demonstrates a markup for code which does not use
indentation.

Well, maybe it should be:

    ----
    ```
    diff ...
    ...
    ```
    ----

Or maybe...

    ----
    ```
    diff --git a/example.txt b/example.txt
    ...
    ```
    ----

I’m leaning towards the latter.

>>[snip]
>> +One might want to use a general-purpose utility like patch(1) instead,
>
> "Given these limitations, one might be tempted to ..."?

That’s good. That leads with the problem instead letting it trail off at
the end of the sentence. I’ll use that.

>> +given these limitations. However, patch(1) will not only look for
>> +unindented diffs (like linkgit:git-am[1]) but will try to apply indented
>> +diffs as well.
>
> This is useful context.
>
> Thanks
>
> Phillip

Thanks for taking a look. It’s always appreciated.