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

[Phillip Wood <phillip.wood123@gmail.com>]

Hi Kristoffer

On 09/02/2026 17:59, Kristoffer Haugsbakk wrote:
> Hi Phillip
> On Mon, Feb 9, 2026, at 17:42, Phillip Wood wrote:
>> On 08/02/2026 00:11, kristofferhaugsbakk@fastmail.com wrote:
>>> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>>>
>>> [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.

Oh, if you use "Index: x" (with a colon) does that mess up the patch 
application?

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

That's a nice concise way of putting it

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

But I think the markup is a distraction from the problem which is that 
the diff is not indented. Also calling it "Github MarkDown" is 
unfortunate as we try not to favor one forge over another and many sites 
support that syntax.


Thanks

Phillip

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