From: Kristoffer Haugsbakk Date: Mon, 09 Feb 2026 17:59:12 GMT Subject: Re: [PATCH] doc: add caveat about roundtripping format-patch Message-ID: In-Reply-To: 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 >> >> 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.