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

From: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
Date: Feb 9, 2026, 17:59 UTC
Message-ID: <c70adde6-e3db-4a46-bb29-a19d7aba8c7e@app.fastmail.com>
In-Reply-To: <bf5d1e84-2a59-4e1b-a524-c8b251dbae70@gmail.com>

Hi Phillip

On Mon, Feb 9, 2026, at 17:42, Phillip Wood wrote:

Show 9 quoted lines

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

Show 6 quoted lines

>
>> † 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 )

Show 10 quoted lines

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

Show 8 quoted lines

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

Show 9 quoted lines

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