git-am applies commit message diffs

>
> Hi,
>
> I am not sure whether this was already reported, searching the lore did
> not yield anything for me, but I might have overlooked it...
>
> This was just posted on mastodon[0]:
>
>     PSA: Did you know that it’s **unsafe** to put code diffs into your commit messages?
>
>     Like https://
>     github.com/i3/i3/pull/6564 for example
>
>     Such diffs will be applied by patch(1) (also git-am(1)) as part of the code change!
>
>     This is how a sleep(1) made it into i3 4.25-2 in Debian unstable.
>
> TL;DR: If you put a diff in the commit message, that diff will be
> applied by git-am.
>
> This looks clearly like unintended and might be an attack-vector, right?
>

> On Thu, Feb 5, 2026 at 11:50 PM Matthias Beyer <mail@beyermatthias.de> wrote:
> >
> > Hi,
> >
> > I am not sure whether this was already reported, searching the lore did
> > not yield anything for me, but I might have overlooked it...
> >
> > This was just posted on mastodon[0]:
> >
> >     PSA: Did you know that it’s **unsafe** to put code diffs into your commit messages?
> >
> >     Like https://
> >     github.com/i3/i3/pull/6564 for example
> >
> >     Such diffs will be applied by patch(1) (also git-am(1)) as part of the code change!
> >
> >     This is how a sleep(1) made it into i3 4.25-2 in Debian unstable.
> >
> > TL;DR: If you put a diff in the commit message, that diff will be
> > applied by git-am.
> >
> > This looks clearly like unintended and might be an attack-vector, right?
> >
> 
> It is certainly surprising. I am not certain I would consider it an
> attack-vector since you should definitely be reading the commit
> messages before applying, but I could see the fact that its
> unintentional is a problem.
> [...]
>
> > [0]: https://mas.to/@zekjur/116022397626943871

> I don't think there is a way to unambiguously parse the single-stream
> output that format-patch produces. This is a reasonably well-known
> gotcha (at least around here). E.g., some earlier discussions:
>
>    2024:https://lore.kernel.org/git/ca13705ae4817ffba16f97530637411b59c9eb19.camel@scientia.org/
>    2022:https://lore.kernel.org/git/d0b577825124ac684ab304d3a1395f3d2d0708e8.1662333027.git.matheus.bernardino@usp.br/
>    2015:https://lore.kernel.org/git/CAFOYHZC6Qd9wkoWPcTJDxAs9u=FGpHQTkjE-guhwkya0DRVA6g@mail.gmail.com/

> From: Phillip Wood <phillip.wood@dunelm.org.uk>
>
> Messages that contain "---" separator lines will be truncated by
> "git am". This often surprises users so add a check to the sample
> "commit-msg" hook to reject such messages. As it's conceivable that
> someone is using "---" as their comment string we delete any commented
> lines before checking for a separator. The trailing ".*" when matching
> commented lines ensures that if the comment string ends with a "$"
> it is not treated as an anchor.
>
> Signed-off-by: Phillip Wood <phillip.wood@dunelm.org.uk>
> ---
>  templates/hooks/commit-msg.sample | 9 ++++++++-
>  1 file changed, 8 insertions(+), 1 deletion(-)

> diff --git a/templates/hooks/commit-msg.sample b/templates/hooks/commit-msg.sample
> index 099cc58c303..c7a9db88cb9 100755
> --- a/templates/hooks/commit-msg.sample
> +++ b/templates/hooks/commit-msg.sample
> @@ -39,9 +39,16 @@ comment_re="$(
>  		}'
>  )"
>  line="$(sed -n -e "/^${comment_re} -\{8,\} >8 -\{8,\}\$/q
> +		   /^${comment_re}.*/d
> +		   /^---\$/{p;q;}
>  		   /^diff -/{p;q;}
>  		   /^Index: /{p;q;}" "$1")"
> -if test -n "$line"
> +if test "$line" = "---"
> +then
> +	echo >&2 "Message contains a '---' separator line that will confuse"
> +	echo >&2 "'git am'. To fix this indent the '---' line."
> +	ret=1
> +elif test -n "$line"
>  then
>  	echo >&2 "Message contains a diff that will confuse 'git am'."
>  	echo >&2 "To fix this indent the diff."

>>[snip]
>
> I have no qualms about the topic up to the previous step, but I know
> one of the things that I sometimes do will be broken with the change
> in this step, namely, when I know what I want to write below the
> three-dash lines, I would commit with "---" and additional notes
> below it, so that I do not forget during "format-patch".
>
> When the commit is turned into a patch email, possibly with some
> other material like "--notes=<ref>" that adds notes there, the
> resulting message will have two three-dashes lines, but because "am"
> cuts at the first one, and "apply" knows that the garbage lines at
> front, including three-dash lines, do not matter until it sees "^diff",
> this works out perfectly well.
>
> Admittedly, I myself do not send out so many patches as I used to,
> but I suspect that there are others who have discovered this trick
> independently, and they would be unhappy to be interrupted by
> commit-msg hook like this.
>
> A saving grace is that when the user is stopped with this,
> pre-commit hook that inspects the contents to be committed
> have already run successfully, so rerunning with "--no-verify"
> is not with too much risk.  But still, I am not sure if this is a
> good thing to do overall.

>> A saving grace is that when the user is stopped with this,
>> pre-commit hook that inspects the contents to be committed
>> have already run successfully, so rerunning with "--no-verify"
>> is not with too much risk.  But still, I am not sure if this is a
>> good thing to do overall.
>
> Maybe this is not the right tool[1] but perhaps the hook could respect
> an env. variable to disable this check and hint about it in the error
> output?

> I have no qualms about the topic up to the previous step, but I know
> one of the things that I sometimes do will be broken with the change
> in this step, namely, when I know what I want to write below the
> three-dash lines, I would commit with "---" and additional notes
> below it, so that I do not forget during "format-patch".
>
> When the commit is turned into a patch email, possibly with some
> other material like "--notes=<ref>" that adds notes there, the
> resulting message will have two three-dashes lines, but because "am"
> cuts at the first one, and "apply" knows that the garbage lines at
> front, including three-dash lines, do not matter until it sees "^diff",
> this works out perfectly well.
> 
> Admittedly, I myself do not send out so many patches as I used to,
> but I suspect that there are others who have discovered this trick
> independently, and they would be unhappy to be interrupted by
> commit-msg hook like this.

> On Sat, Feb 07, 2026 at 01:27:01PM -0800, Junio C Hamano wrote:
> 
>> I have no qualms about the topic up to the previous step, but I know
>> one of the things that I sometimes do will be broken with the change
>> in this step, namely, when I know what I want to write below the
>> three-dash lines, I would commit with "---" and additional notes
>> below it, so that I do not forget during "format-patch".
>>
>> When the commit is turned into a patch email, possibly with some
>> other material like "--notes=<ref>" that adds notes there, the
>> resulting message will have two three-dashes lines, but because "am"
>> cuts at the first one, and "apply" knows that the garbage lines at
>> front, including three-dash lines, do not matter until it sees "^diff",
>> this works out perfectly well.
>>
>> Admittedly, I myself do not send out so many patches as I used to,
>> but I suspect that there are others who have discovered this trick
>> independently, and they would be unhappy to be interrupted by
>> commit-msg hook like this.
> 
> I do it, too, though not all that often. Once upon a time I had a patch
> to teach git-commit to auto-convert lines after "---" into a note (which
> would then be formatted back out via format-patch). But I found for my
> git.git workflow that just letting the "---" ride along in the commit
> object was simpler and easier (since I don't care about having pristine
> commit objects, as their ultimate fate is to be dropped in favor of what
> is applied upstream).

> > I do it, too, though not all that often. Once upon a time I had a patch
> > to teach git-commit to auto-convert lines after "---" into a note (which
> > would then be formatted back out via format-patch). But I found for my
> > git.git workflow that just letting the "---" ride along in the commit
> > object was simpler and easier (since I don't care about having pristine
> > commit objects, as their ultimate fate is to be dropped in favor of what
> > is applied upstream).
> 
> I do it too occasionally. I had planned just to use "--no-verify" when I did
> that but maybe we should just drop this patch. We could make it configurable
> as Kristoffer suggested, or, as we have the raw message, we could look for a
> special comment like "# allow ---" but I'm not sure I want to spend much
> more time on this. At least "---" only truncates the message rather than
> applying an unwanted patch.

> From: Phillip Wood <phillip.wood@dunelm.org.uk>
> 
> On 06/02/2026 09:03, Jeff King wrote:
> > I don't think there is a way to unambiguously parse the single-stream
> > output that format-patch produces. This is a reasonably well-known
> > gotcha (at least around here). E.g., some earlier discussions:
> >
> >    2024:https://lore.kernel.org/git/ca13705ae4817ffba16f97530637411b59c9eb19.camel@scientia.org/
> >    2022:https://lore.kernel.org/git/d0b577825124ac684ab304d3a1395f3d2d0708e8.1662333027.git.matheus.bernardino@usp.br/
> >    2015:https://lore.kernel.org/git/CAFOYHZC6Qd9wkoWPcTJDxAs9u=FGpHQTkjE-guhwkya0DRVA6g@mail.gmail.com/
> 
> If we cannot improve "git am" perhaps we should update our sample
> "commit-msg" hook to reject messages that will cause problems. Here
> are some patches to do that.

> We could perhaps think about adding a more prominent warning to the
> "git am" and "git format-patch" documentation. The docs for "git am"
> mention that it splits the message on a line starting with "diff -"
> but maybe we should spell out what that means for commit messages that
> include a diff. In principle "git format-patch" could also warn or
> error out if it creates a mail that "git am" cannot import verbatim,
> I don't know how hard that would be in implement.

> On Sat, Feb 07, 2026 at 02:57:59PM +0000, Phillip Wood wrote:
> 
>> From: Phillip Wood <phillip.wood@dunelm.org.uk>
>>
>> On 06/02/2026 09:03, Jeff King wrote:
>>> I don't think there is a way to unambiguously parse the single-stream
>>> output that format-patch produces. This is a reasonably well-known
>>> gotcha (at least around here). E.g., some earlier discussions:
>>>
>>>     2024:https://lore.kernel.org/git/ca13705ae4817ffba16f97530637411b59c9eb19.camel@scientia.org/
>>>     2022:https://lore.kernel.org/git/d0b577825124ac684ab304d3a1395f3d2d0708e8.1662333027.git.matheus.bernardino@usp.br/
>>>     2015:https://lore.kernel.org/git/CAFOYHZC6Qd9wkoWPcTJDxAs9u=FGpHQTkjE-guhwkya0DRVA6g@mail.gmail.com/
>>
>> If we cannot improve "git am" perhaps we should update our sample
>> "commit-msg" hook to reject messages that will cause problems. Here
>> are some patches to do that.
> 
> I'm not entirely opposed to it, but my initial reaction was two bits of
> skepticism:
> 
>    1. I imagine that hardly anybody runs commit-msg hooks in the first
>       place, let alone our sample hook. So I doubt this will get the
>       attention of many people.

> I'd imagine that documentation updates would be more likely to get read
> by users than the sample hook. And a warning in git-commit itself would
> be even more obvious (but fall even more afoul of (2) above). Adding a
> warning to format-patch would help with (2), but at that point it may be
> too late to change the commit message.

>> We could perhaps think about adding a more prominent warning to the
>> "git am" and "git format-patch" documentation. The docs for "git am"
>> mention that it splits the message on a line starting with "diff -"
>> but maybe we should spell out what that means for commit messages that
>> include a diff. In principle "git format-patch" could also warn or
>> error out if it creates a mail that "git am" cannot import verbatim,
>> I don't know how hard that would be in implement.
> 
> I think the patch from Matheus linked above added that format-patch
> check.
> 
> -Peff
> 

> >    2. I'd guess that these days only a small minority of people care
> >       about sending patches by email. So for most people, a warning about
> >       their commit message containing a diff or "---" will be mostly
> >       useless, if not outright confusing.
> 
> People do download patches from github and apply them even if they're not
> using a email based workflow. I'm not entirely clear but I think that's what
> happened in the post Matthias linked to. Though if they're using "patch"
> rather than "git am" to apply them indenting the diff wont help.

> >    2. I'd guess that these days only a small minority of people care
> >       about sending patches by email. So for most people, a warning about
> >       their commit message containing a diff or "---" will be mostly
> >       useless, if not outright confusing.
> 
> People do download patches from github and apply them even if they're not
> using a email based workflow. I'm not entirely clear but I think that's what
> happened in the post Matthias linked to. Though if they're using "patch"
> rather than "git am" to apply them indenting the diff wont help.

> On Fri, Feb 06, 2026 at 09:18:50AM +0100, Matthias Beyer wrote:
> 
> > That said, I am no expert in either C or the git codebase at all, but
> > from what I saw from reading the git-am codebase, it looks like it tries
> > to find the patch by looking for three dashes on a line with a linebreak
> > behind ("---\n").
> 
> Yes, that is how the split is made.
> 
> > From what I read, it looks for that from the first line.
> > What I would think of here is looking for that "patchbreak" from the
> > _end_ of the email rather than from the top, that would have prevented
> > this issue, right?
> 
> The patch itself may legitimately contain "---" on a line by itself (it
> would indicate that the line "--" was removed from a file). That would
> confuse your parser, including in a way that we end up only applying
> part of the diff (everything before that fake "---" becomes commit
> message, and everything after becomes cover-letter material up to the
> next "diff" line).
> 
> I suspect it also creates corner cases with cover-letter material
> (between the "---" and the diff itself) that itself contains any "---"
> marker.
> 
> I don't think there is a way to unambiguously parse the single-stream
> output that format-patch produces. This is a reasonably well-known
> gotcha (at least around here). E.g., some earlier discussions:
> 
>   2024: https://lore.kernel.org/git/ca13705ae4817ffba16f97530637411b59c9eb19.camel@scientia.org/
>   2022: https://lore.kernel.org/git/d0b577825124ac684ab304d3a1395f3d2d0708e8.1662333027.git.matheus.bernardino@usp.br/
>   2015: https://lore.kernel.org/git/CAFOYHZC6Qd9wkoWPcTJDxAs9u=FGpHQTkjE-guhwkya0DRVA6g@mail.gmail.com/
> 
> There are probably more, but it's actually a tricky thing to search for
> in the archive, so I stopped digging. ;)

>
> On Fri, Feb 06, 2026 at 04:03:58AM -0500, Jeff King wrote:
> > On Fri, Feb 06, 2026 at 09:18:50AM +0100, Matthias Beyer wrote:
> >
> > > That said, I am no expert in either C or the git codebase at all, but
> > > from what I saw from reading the git-am codebase, it looks like it tries
> > > to find the patch by looking for three dashes on a line with a linebreak
> > > behind ("---\n").
> >
> > Yes, that is how the split is made.
> >
> > > From what I read, it looks for that from the first line.
> > > What I would think of here is looking for that "patchbreak" from the
> > > _end_ of the email rather than from the top, that would have prevented
> > > this issue, right?
> >
> > The patch itself may legitimately contain "---" on a line by itself (it
> > would indicate that the line "--" was removed from a file). That would
> > confuse your parser, including in a way that we end up only applying
> > part of the diff (everything before that fake "---" becomes commit
> > message, and everything after becomes cover-letter material up to the
> > next "diff" line).
> >
> > I suspect it also creates corner cases with cover-letter material
> > (between the "---" and the diff itself) that itself contains any "---"
> > marker.
> >
> > I don't think there is a way to unambiguously parse the single-stream
> > output that format-patch produces. This is a reasonably well-known
> > gotcha (at least around here). E.g., some earlier discussions:
> >
> >   2024: https://lore.kernel.org/git/ca13705ae4817ffba16f97530637411b59c9eb19.camel@scientia.org/
> >   2022: https://lore.kernel.org/git/d0b577825124ac684ab304d3a1395f3d2d0708e8.1662333027.git.matheus.bernardino@usp.br/
> >   2015: https://lore.kernel.org/git/CAFOYHZC6Qd9wkoWPcTJDxAs9u=FGpHQTkjE-guhwkya0DRVA6g@mail.gmail.com/
> >
> > There are probably more, but it's actually a tricky thing to search for
> > in the archive, so I stopped digging. ;)
>
> Maybe we can't parse it unambiguously. But what we _can_ detect is that
> a patch is ambiguous in the first place, right? So maybe we could extend
> git-am(1) to bail by default with a hint that tells the user that:
>

>   - They ought to double-check the patch.
>
>   - They can override the check with "--accept-ambiguous-patch".
>
> It at least notifies the user that something potentially-fishy is going
> on, even though it still shifts the burden onto the person that applies
> the patch. But I guess that cannot ever be avoided anyway, at least in
> the general case.
>
> Patrick

> On Mon, Feb 9, 2026 at 7:59 AM Patrick Steinhardt <ps@pks.im> wrote:
> >
> > On Fri, Feb 06, 2026 at 04:03:58AM -0500, Jeff King wrote:
> > > On Fri, Feb 06, 2026 at 09:18:50AM +0100, Matthias Beyer wrote:
> > >
> > > > That said, I am no expert in either C or the git codebase at all, but
> > > > from what I saw from reading the git-am codebase, it looks like it tries
> > > > to find the patch by looking for three dashes on a line with a linebreak
> > > > behind ("---\n").
> > >
> > > Yes, that is how the split is made.
> > >
> > > > From what I read, it looks for that from the first line.
> > > > What I would think of here is looking for that "patchbreak" from the
> > > > _end_ of the email rather than from the top, that would have prevented
> > > > this issue, right?
> > >
> > > The patch itself may legitimately contain "---" on a line by itself (it
> > > would indicate that the line "--" was removed from a file). That would
> > > confuse your parser, including in a way that we end up only applying
> > > part of the diff (everything before that fake "---" becomes commit
> > > message, and everything after becomes cover-letter material up to the
> > > next "diff" line).
> > >
> > > I suspect it also creates corner cases with cover-letter material
> > > (between the "---" and the diff itself) that itself contains any "---"
> > > marker.
> > >
> > > I don't think there is a way to unambiguously parse the single-stream
> > > output that format-patch produces. This is a reasonably well-known
> > > gotcha (at least around here). E.g., some earlier discussions:
> > >
> > >   2024: https://lore.kernel.org/git/ca13705ae4817ffba16f97530637411b59c9eb19.camel@scientia.org/
> > >   2022: https://lore.kernel.org/git/d0b577825124ac684ab304d3a1395f3d2d0708e8.1662333027.git.matheus.bernardino@usp.br/
> > >   2015: https://lore.kernel.org/git/CAFOYHZC6Qd9wkoWPcTJDxAs9u=FGpHQTkjE-guhwkya0DRVA6g@mail.gmail.com/
> > >
> > > There are probably more, but it's actually a tricky thing to search for
> > > in the archive, so I stopped digging. ;)
> >
> > Maybe we can't parse it unambiguously. But what we _can_ detect is that
> > a patch is ambiguous in the first place, right? So maybe we could extend
> > git-am(1) to bail by default with a hint that tells the user that:
> >
> 
> I think it might make sense in a breaking change to update format
> patch and git am to have an "unambiguous" mode which would allow
> somehow to unambiguously distinguish between commit message contents
> and patch data. I'm not 100% sure how to do this, and it likely
> requires some sort of breaking changes to both tools to allow
> distinguishing properly between the two points.

> Obviously if you're sending the contents together, a malicious user
> could edit the formatted patch to move or copy whatever the
> "signifier" for patch vs commit separator is... but at least we'd
> prevent the cases where someone accidentally includes diffs without
> intending to.

> That is worth a thought indeed. I guess one of the biggest questions
> here is whether we can introduce such an unambiguous mode in such a way
> that old Git clients/patch(1) would continue to understand them. I
> wouldn't mind much if they would still misinterpret the ambiguous parts.
> But if so, we could make this unambiguous mode the default without a
> breaking change.

>> Obviously if you're sending the contents together, a malicious user
>> could edit the formatted patch to move or copy whatever the
>> "signifier" for patch vs commit separator is... but at least we'd
>> prevent the cases where someone accidentally includes diffs without
>> intending to.
>
> Well, if we had such an unambiguous mode I would say that eventually,
> Git should start to refuse patches that have been generated without this
> mode by default.

>
> Patrick Steinhardt <ps@pks.im> writes:
>
> > That is worth a thought indeed. I guess one of the biggest questions
> > here is whether we can introduce such an unambiguous mode in such a way
> > that old Git clients/patch(1) would continue to understand them. I
> > wouldn't mind much if they would still misinterpret the ambiguous parts.
> > But if so, we could make this unambiguous mode the default without a
> > breaking change.
>
> Yup, if the old versions misinterpret exactly the same way as
> before, then it does not even have to be called "unambiguous mode"
> that is on by default.  I doubt it is possible, though.
>

>
> On Tue, Feb 10, 2026 at 7:47 AM Junio C Hamano <gitster@pobox.com> wrote:
> >
> > Patrick Steinhardt <ps@pks.im> writes:
> >
> > > That is worth a thought indeed. I guess one of the biggest questions
> > > here is whether we can introduce such an unambiguous mode in such a way
> > > that old Git clients/patch(1) would continue to understand them. I
> > > wouldn't mind much if they would still misinterpret the ambiguous parts.
> > > But if so, we could make this unambiguous mode the default without a
> > > breaking change.
> >
> > Yup, if the old versions misinterpret exactly the same way as
> > before, then it does not even have to be called "unambiguous mode"
> > that is on by default.  I doubt it is possible, though.
> >
>
> Hmm. If we add a new unambiguous marker after the ---, old versions
> would see '...' and know to cut the description. New versions would
> wait for <NEW MARKER> and properly ignore any diff/etc prior to this.
>
> Since <NEW MARKER> is after a ---, it would be ignored and not
> inserted as part of the commit message, and because all versions
> universally accept cruft between --- and the diff start, this should
> be acceptable right?

> > Hmm. If we add a new unambiguous marker after the ---, old versions
> > would see '...' and know to cut the description. New versions would
> > wait for <NEW MARKER> and properly ignore any diff/etc prior to this.
> >
> > Since <NEW MARKER> is after a ---, it would be ignored and not
> > inserted as part of the commit message, and because all versions
> > universally accept cruft between --- and the diff start, this should
> > be acceptable right?
> 
> Keeping in mind we'd have to use <NEW MARKER> as something that we
> somehow reject as being a valid part of a commit message somehow, so
> that you can't accidentally insert it, and we'd need to be careful
> about rejecting formatting such a patch, and probably complaining on
> the receiving end if we see multiple markers.. Trickier than it sounds
> I imagine.

> On Tue, Feb 10, 2026 at 06:34:05PM -0800, Jacob Keller wrote:
>
>> > Hmm. If we add a new unambiguous marker after the ---, old versions
>> > would see '...' and know to cut the description. New versions would
>> > wait for <NEW MARKER> and properly ignore any diff/etc prior to this.
>> >
>> > Since <NEW MARKER> is after a ---, it would be ignored and not
>> > inserted as part of the commit message, and because all versions
>> > universally accept cruft between --- and the diff start, this should
>> > be acceptable right?
>>
>> Keeping in mind we'd have to use <NEW MARKER> as something that we
>> somehow reject as being a valid part of a commit message somehow, so
>> that you can't accidentally insert it, and we'd need to be careful
>> about rejecting formatting such a patch, and probably complaining on
>> the receiving end if we see multiple markers.. Trickier than it sounds
>> I imagine.
>
> Yeah, on reading your first message, I wondered if we would run into a
> commit message adding "---" followed by the new marker. If the new
> marker is forbidden, I guess that works. But how ugly is that new marker
> going to be, then? ;) We'll now see it in every email.

> If we are going to modify what format-patch produces, I'd be more
> inclined to have it perform some reversible quoting on the commit
> message so that "---" and "diff" lines are not recognized. And then that
> quoting only has to kick in when a message would be ambiguous, so most
> people wouldn't even see it.

> All that said, if the main goal is just avoiding accidental diffs in
> commit messages (and not worrying about truncation due to "---" in
> messages), there may be a simpler receiver-side solution. If the
> receiver expects the message to be generated by Git, then it will expect
> there to be a "---" line. And we will not expect any diff before then.
> So could we just have a "git am --strict" mode (and perhaps matching
> config option) that always looks for the "---" separator?
>
> It's not foolproof, but I suspect it would help with the worst cases of
> embedded diffs. And it's not that hard to implement.

> > I don't think there is a way to unambiguously parse the single-stream
> > output that format-patch produces. This is a reasonably well-known
> > gotcha (at least around here). E.g., some earlier discussions:
> > 
> >   2024: https://lore.kernel.org/git/ca13705ae4817ffba16f97530637411b59c9eb19.camel@scientia.org/
> >   2022: https://lore.kernel.org/git/d0b577825124ac684ab304d3a1395f3d2d0708e8.1662333027.git.matheus.bernardino@usp.br/
> >   2015: https://lore.kernel.org/git/CAFOYHZC6Qd9wkoWPcTJDxAs9u=FGpHQTkjE-guhwkya0DRVA6g@mail.gmail.com/
> > 
> > There are probably more, but it's actually a tricky thing to search for
> > in the archive, so I stopped digging. ;)
> 
> Maybe we can't parse it unambiguously. But what we _can_ detect is that
> a patch is ambiguous in the first place, right? So maybe we could extend
> git-am(1) to bail by default with a hint that tells the user that:
> 
>   - They ought to double-check the patch.
> 
>   - They can override the check with "--accept-ambiguous-patch".
> 
> It at least notifies the user that something potentially-fishy is going
> on, even though it still shifts the burden onto the person that applies
> the patch. But I guess that cannot ever be avoided anyway, at least in
> the general case.

> From: Phillip Wood <phillip.wood@dunelm.org.uk>
>
> If the body of a commit message contains a diff that is not indented
> then "git am" will treat that diff as part of the patch rather than
> as part of the commit message. This allows it to apply email messages
> that were created by adding a commit message in front of a regular diff
> without adding the "---" separator used by "git format-patch". This
> often surprises users [1-4] so add a check to the sample "commit-msg"
> hook to reject messages that would confuse "git am". Even if a project
> does not use an email based workflow it is not uncommon for people
> to generate patches from it and apply them with "git am". Therefore
> it is still worth discouraging the creation of commit messages that
> would not be applied correctly.
>
> A further source of confusion when applying patches with "git am" is
> the "---" separator that is added by "git format patch". If a commit
> message body contains that line then it will be truncated by "git am".
> As this is often used by patch authors to add some commentary that
> they do not want to end up in the commit message when the patch is
> applied, the hook does not complain about the presence of "---" lines
> in the message.
>
> Detecting if the message contains a diff is complicated by the
> hook being passed the message before it is cleaned up so we need to
> ignore any diffs below the scissors line. There are also two possible
> config keys to check to find the comment character at the start of
> the scissors line. The first paragraph of the commit message becomes
> the email subject header which beings "Subject: " and so does not
> need to be checked. The trailing ".*" when matching commented lines
> ensures that if the comment string ends with a "$" it is not treated
> as an anchor.
>
> [1]
> https://lore.kernel.org/git/bcqvh7ahjjgzpgxwnr4kh3hfkksfruf54refyry3ha7qk7dldf@fij5calmscvm
> [2]
> https://lore.kernel.org/git/ca13705ae4817ffba16f97530637411b59c9eb19.camel@scientia.org/
> [3]
> https://lore.kernel.org/git/d0b577825124ac684ab304d3a1395f3d2d0708e8.1662333027.git.matheus.bernardino@usp.br/
> [4]
> https://lore.kernel.org/git/CAFOYHZC6Qd9wkoWPcTJDxAs9u=FGpHQTkjE-guhwkya0DRVA6g@mail.gmail.com/
>
> Signed-off-by: Phillip Wood <phillip.wood@dunelm.org.uk>
> ---
>  templates/hooks/commit-msg.sample | 54 +++++++++++++++++++++++++++++--
>  1 file changed, 52 insertions(+), 2 deletions(-)
>[snip]

> From: Phillip Wood <phillip.wood@dunelm.org.uk>
>
> If the body of a commit message contains a diff that is not indented
> then "git am" will treat that diff as part of the patch rather than
> as part of the commit message. This allows it to apply email messages
> that were created by adding a commit message in front of a regular diff
> without adding the "---" separator used by "git format-patch". This
> often surprises users [1-4] so add a check to the sample "commit-msg"
> hook to reject messages that would confuse "git am". Even if a project
> does not use an email based workflow it is not uncommon for people
> to generate patches from it and apply them with "git am". Therefore
> it is still worth discouraging the creation of commit messages that
> would not be applied correctly.
>
> A further source of confusion when applying patches with "git am" is
> the "---" separator that is added by "git format patch". If a commit
> message body contains that line then it will be truncated by "git am".
> As this is often used by patch authors to add some commentary that
> they do not want to end up in the commit message when the patch is
> applied, the hook does not complain about the presence of "---" lines
> in the message.

> [1] https://lore.kernel.org/git/bcqvh7ahjjgzpgxwnr4kh3hfkksfruf54refyry3ha7qk7dldf@fij5calmscvm
> [2] https://lore.kernel.org/git/ca13705ae4817ffba16f97530637411b59c9eb19.camel@scientia.org/
> [3] https://lore.kernel.org/git/d0b577825124ac684ab304d3a1395f3d2d0708e8.1662333027.git.matheus.bernardino@usp.br/
> [4] https://lore.kernel.org/git/CAFOYHZC6Qd9wkoWPcTJDxAs9u=FGpHQTkjE-guhwkya0DRVA6g@mail.gmail.com/
>
> Signed-off-by: Phillip Wood <phillip.wood@dunelm.org.uk>
> ---
>  templates/hooks/commit-msg.sample | 54 +++++++++++++++++++++++++++++--
>  1 file changed, 52 insertions(+), 2 deletions(-)
>
> diff --git a/templates/hooks/commit-msg.sample b/templates/hooks/commit-msg.sample
> index b58d1184a9d..f7458efe62f 100755
> --- a/templates/hooks/commit-msg.sample
> +++ b/templates/hooks/commit-msg.sample
> @@ -15,10 +15,60 @@
>  # SOB=$(git var GIT_AUTHOR_IDENT | sed -n 's/^\(.*>\).*$/Signed-off-by: \1/p')
>  # grep -qs "^$SOB" "$1" || echo "$SOB" >> "$1"
>  
> -# This example catches duplicate Signed-off-by lines.
> +# This example catches duplicate Signed-off-by lines and messages that
> +# would confuse 'git am'.
> +
> +ret=0
>  
>  test "" = "$(grep '^Signed-off-by: ' "$1" |
>  	 sort | uniq -c | sed -e '/^[ 	]*1[ 	]/d')" || {
>  	echo >&2 Duplicate Signed-off-by lines.
> -	exit 1
> +	ret=1
>  }
> +
> +comment_re="$(
> +	{
> +		git config --get-regexp "^core\.comment(char|string)\$" ||
> +			echo '#'
> +	} | sed -n -e '
> +		${
> +			s/^[^ ]* //
> +			s|[][*./\]|\\&|g
> +			s/^auto$/[#;@!$%^&|:]/
> +			p
> +		}'
> +)"
> +scissors_line="^${comment_re} -\{8,\} >8 -\{8,\}\$"
> +comment_line="^${comment_re}.*"
> +blank_line='^[ 	]*$'
> +# Disallow lines starting with "diff -" or "Index: " in the body of the
> +# message. Stop looking if we see a scissors line.
> +line="$(sed -n -e "
> +	# Skip comments and blank lines at the start of the file.
> +	/${scissors_line}/q
> +	/${comment_line}/d
> +	/${blank_line}/d
> +	# The first paragraph will become the subject header so
> +	# does not need to be checked.
> +	: subject
> +	n
> +	/${scissors_line}/q
> +	/${blank_line}/!b subject
> +	# Check the body of the message for problematic
> +	# prefixes.
> +	: body
> +	n
> +	/${scissors_line}/q
> +	/${comment_line}/b body
> +	/^diff -/{p;q;}
> +	/^Index: /{p;q;}
> +	b body
> +	" "$1")"
> +if test -n "$line"
> +then
> +	echo >&2 "Message contains a diff that will confuse 'git am'."
> +	echo >&2 "To fix this indent the diff."
> +	ret=1
> +fi
> +
> +exit $ret

> Phillip Wood <phillip.wood123@gmail.com> writes:
> 
>> From: Phillip Wood <phillip.wood@dunelm.org.uk>
>>
>> If the body of a commit message contains a diff that is not indented
>> then "git am" will treat that diff as part of the patch rather than
>> as part of the commit message. This allows it to apply email messages
>> that were created by adding a commit message in front of a regular diff
>> without adding the "---" separator used by "git format-patch". This
>> often surprises users [1-4] so add a check to the sample "commit-msg"
>> hook to reject messages that would confuse "git am". Even if a project
>> does not use an email based workflow it is not uncommon for people
>> to generate patches from it and apply them with "git am". Therefore
>> it is still worth discouraging the creation of commit messages that
>> would not be applied correctly.
>>
>> A further source of confusion when applying patches with "git am" is
>> the "---" separator that is added by "git format patch". If a commit
>> message body contains that line then it will be truncated by "git am".
>> As this is often used by patch authors to add some commentary that
>> they do not want to end up in the commit message when the patch is
>> applied, the hook does not complain about the presence of "---" lines
>> in the message.
> 
> "git format match" -> "git format-patch".

>> The trailing ".*" when matching commented lines
>> ensures that if the comment string ends with a "$" it is not treated
>> as an anchor.
> 
> I am not sure what this means.  Wouldn't these three
> 
> 	sed -e '/^#/d'
> 	sed -e '/^#.*/d'
> 	sed -e '/^#.*$/d'
> 
> work exactly the same way?

>>> The trailing ".*" when matching commented lines
>>> ensures that if the comment string ends with a "$" it is not treated
>>> as an anchor.
>> 
>> I am not sure what this means.  Wouldn't these three
>> 
>> 	sed -e '/^#/d'
>> 	sed -e '/^#.*/d'
>> 	sed -e '/^#.*$/d'
>> 
>> work exactly the same way?
>
> They do, but if the comment string is '$' then these two
>
> 	sed -e '/^$/d'
> 	sed -e '/^$.*/d'
>
> have different meanings

> From: Phillip Wood <phillip.wood@dunelm.org.uk>
>
> This series adds a check to the sample commit-msg hook to reject commit
> messages where the body of the message contains lines starting with
> "diff -" and "Index: ". Such lines confuse "git am".
>
> Changes since V1:
>
>  - Allow subjects to start with "diff -" as they end up in an email
>    header and so do not confuse "git am"
>
>  - Allow "---" lines as they are useful when preparing patches.

> It seems like a good idea to me to improve the format patch output and
> the git am patch splitting to somehow try and detect the end of a
> valid commit message and not treat it as a patch content, but I am
> really uncertain how to go about doing so safely without risking
> backwards compatibility (modifying format-patch to insert a marker
> that properly denotes end of commit would cause issues with older
> versions of git, so we need to use some marker that a well formatted
> patch already does.

> Isn't the format-patch output already unambiguous because the sequence
> of diffs is preceeded by the non-diff statistics section, and only then
> the commit message follows?  It's just not possible to process this
> correctly in one pass because only at the end of the input, you know
> that you have just seen the to-be-applied diffs.

> The other tool to look at is git rebase.  There have been problems with
> the lack of "From " encoding in commit messages in the past, which
> caused rebases to fail due to commit message contents (but I can totally
> imagine that this might have resulted in commit injection with more
> carefully crafted commit messages).

> On Fri, Feb 06, 2026 at 09:59:31AM +0100, Florian Weimer wrote:
>
>> Isn't the format-patch output already unambiguous because the sequence
>> of diffs is preceeded by the non-diff statistics section, and only then
>> the commit message follows?  It's just not possible to process this
>> correctly in one pass because only at the end of the input, you know
>> that you have just seen the to-be-applied diffs.
>
> That diffstat is optional, and not parsed by the receiving format-patch
> at all. Keep in mind that in the world for which it was originally
> designed, people were not necessarily using Git to generate their
> emails. They could be patches emailed by random folks using "diff"
> themselves.

> > On Fri, Feb 06, 2026 at 09:59:31AM +0100, Florian Weimer wrote:
> >
> >> Isn't the format-patch output already unambiguous because the sequence
> >> of diffs is preceeded by the non-diff statistics section, and only then
> >> the commit message follows?  It's just not possible to process this
> >> correctly in one pass because only at the end of the input, you know
> >> that you have just seen the to-be-applied diffs.
> >
> > That diffstat is optional, and not parsed by the receiving format-patch
> > at all. Keep in mind that in the world for which it was originally
> > designed, people were not necessarily using Git to generate their
> > emails. They could be patches emailed by random folks using "diff"
> > themselves.
> 
> Is the git am format that flexible in practice?  I often have trouble
> applying patches with git am that were created with git format-patch
> and have to resort to plain old patch instead.  As a user, I definitely
> get the impression that it's not a type of tool that gets a patch
> out of an email message, no matter what the cost.

> Hi,
>
> I am not sure whether this was already reported, searching the lore did
> not yield anything for me, but I might have overlooked it...
>
> This was just posted on mastodon[0]:
>
>     PSA: Did you know that it’s **unsafe** to put code diffs into your
> commit messages?
>
>     Like https://
>     github.com/i3/i3/pull/6564 for example
>
>     Such diffs will be applied by patch(1) (also git-am(1)) as part of
> the code change!
>
>     This is how a sleep(1) made it into i3 4.25-2 in Debian unstable.
>
> TL;DR: If you put a diff in the commit message, that diff will be
> applied by git-am.
>
> This looks clearly like unintended and might be an attack-vector, right?

> On Fri, 06 Feb 2026 09:43:04 +0100
> "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> wrote:
>
>> Like Jacob said the cure is to use indentation for code blocks.
>
> That doesn't help here as stated by Michael on GH and his Mastodon
> post. Also, to make sure this doesn't get lost:
>
> From patch(1):
>
> ---
> If the entire diff is indented by a consistent amount, if lines end in CRLF,
> or if a diff is encapsulated one or more times by prepending "- " to lines
> starting with "-" as specified by Internet RFC 934, this is taken into account.
> After removing indenting or encapsulation, lines beginning with # are ignored,
> as they are considered to be comments.
> ---

> Hi,
>
> I am not sure whether this was already reported, searching the lore did
> not yield anything for me, but I might have overlooked it...
>
> This was just posted on mastodon[0]:
>
>     PSA: Did you know that it’s **unsafe** to put code diffs into your
> commit messages?
>
>     Like https://
>     github.com/i3/i3/pull/6564 for example
>
>     Such diffs will be applied by patch(1) (also git-am(1)) as part of
> the code change!
>
>     This is how a sleep(1) made it into i3 4.25-2 in Debian unstable.
>
> TL;DR: If you put a diff in the commit message, that diff will be
> applied by git-am.
>
> This looks clearly like unintended and might be an attack-vector, right?

> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> git-format-patch(1), git-send-email(1), and git-am(1) deal with
> formatting commits as patches, sending them (perhaps directly), and
> applying them, respectively. Naturally they use a few delimiters to mark
> where the commit message ends. This can lead to surprising behavior when
> these delimiters are used in the commit message itself.
>
> git-format-patch(1) and git-send-email(1) will accept any commit message
> and not warn or error about these delimiters being used.[1]
>
> Moreover, the presence of unindented diffs in the commit message will
> cause git-am(1) to apply both the diffs from the commit message as well
> as the patch section.[2]
>
> It is unclear whether any commands in this chain will learn to warn
> about this. One concern could be that users have learned to rely on
> the three-dash line rule to conveniently add extra-commit message
> information in the commit message, knowing that git-am(1) will
> ignore it.[4]
>
> All of this is covered already, technically, However, we should spell
> out the implications.
>
> † 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.
> [2]: Recently patch(1) caused this issue for a project, but it was noted
>      that git-am(1) has the same behavior[3]
> [3]: https://github.com/i3/i3/pull/6564#issuecomment-3858381425
> [4]: https://lore.kernel.org/git/xmqqldh4b5y2.fsf@gitster.g/
>
> Reported-by: Matthias Beyer <mail@beyermatthias.de>
> Reported-by: Christoph Anton Mitterer <calestyo@scientia.org>
> Reported-by: Matheus Tavares <matheus.tavb@gmail.com>
> Reported-by: Chris Packham <judge.packham@gmail.com>
> Helped-by: Jakob Haufe <sur5r@sur5r.net>
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> ---
>
> Notes (series):
>     There might be other things to do here. Mention it in gitfaq(5)?
>     
>     § Trailers
>     
>     • Reported-by: Matthias Beyer <mail@beyermatthias.de>
>       • From this thread
>     Reported-by: Christoph Anton Mitterer <calestyo@scientia.org>
>       • From https://lore.kernel.org/git/ca13705ae4817ffba16f97530637411b59c9eb19.camel@scientia.org/T/#u
>     Reported-by: Matheus Tavares <matheus.bernardino@usp.br>
>       • From https://lore.kernel.org/git/d0b577825124ac684ab304d3a1395f3d2d0708e8.1662333027.git.matheus.bernardino@usp.br/#t
>     Reported-by: Chris Packham <judge.packham@gmail.com>
>       • From https://lore.kernel.org/git/CAFOYHZC6Qd9wkoWPcTJDxAs9u=FGpHQTkjE-guhwkya0DRVA6g@mail.gmail.com/
>     
>     (These were all linked in https://lore.kernel.org/git/20260206090358.GA2761602@coredump.intra.peff.net/ )
>     
>     Helped-by: Jakob Haufe <sur5r@sur5r.net>
>       • For the part about patch(1): https://lore.kernel.org/git/f6e4cdb4-ff82-4853-aca5-0c152f287286@app.fastmail.com/T/#mc389dbd2ae02a007cbe57cd16ca4790ecc5a84f7

>>[snip]
>> ---
>>
>> Notes (series):
>>     There might be other things to do here. Mention it in gitfaq(5)?
>>
>>     § Trailers
>>
>>     • Reported-by: Matthias Beyer <mail@beyermatthias.de>
>>       • From this thread
>>     Reported-by: Christoph Anton Mitterer <calestyo@scientia.org>
>>       • From https://lore.kernel.org/git/ca13705ae4817ffba16f97530637411b59c9eb19.camel@scientia.org/T/#u
>>     Reported-by: Matheus Tavares <matheus.bernardino@usp.br>
>>       • From https://lore.kernel.org/git/d0b577825124ac684ab304d3a1395f3d2d0708e8.1662333027.git.matheus.bernardino@usp.br/#t
>>     Reported-by: Chris Packham <judge.packham@gmail.com>
>>       • From https://lore.kernel.org/git/CAFOYHZC6Qd9wkoWPcTJDxAs9u=FGpHQTkjE-guhwkya0DRVA6g@mail.gmail.com/
>>
>>     (These were all linked in https://lore.kernel.org/git/20260206090358.GA2761602@coredump.intra.peff.net/ )
>>
>>     Helped-by: Jakob Haufe <sur5r@sur5r.net>
>>       • For the part about patch(1): https://lore.kernel.org/git/f6e4cdb4-ff82-4853-aca5-0c152f287286@app.fastmail.com/T/#mc389dbd2ae02a007cbe57cd16ca4790ecc5a84f7
>
> The space after three-dash line is to give additional information to
> help readers, but the above does not qualify as one.

> diff --git a/Documentation/format-patch-caveats.adoc b/Documentation/format-patch-caveats.adoc
> new file mode 100644
> index 00000000000..2accf2763fd
> --- /dev/null
> +++ b/Documentation/format-patch-caveats.adoc
> @@ -0,0 +1,39 @@
> +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.

> +The commit message might contain a three-dash line (`---`) which was
> +perhaps meant to be a thematic break. That means that the commit message
> +will be cut short. The presence of a line starting with "Index: " can
> +cause the patch not to be found, giving an error about an empty patch.
> +
> +Furthermore, the presence of an unindented diff in the commit message
> +will not only cut the message short but cause that very diff to be
> +applied, along with the patch in the patch section. The commit message
> +might for example have a diff in a GitHub MarkDown code fence:
> +
> +----
> +```
> +diff ...
> +```
> +----

> +The solution for this is to indent the diff instead:
> +
> +----
> +    diff ...
> +----
> +
> +This loss of fidelity might be simple to notice if you are applying
> +patches directly from a mailbox. However, a commit authored long ago
> +might be applied in a different context, perhaps because many changes
> +are being integrated via patch files and the
> +linkgit:git-format-patch[1] format is trusted to import changes of a
> +Git origin.

> diff --git a/Documentation/git-am.adoc b/Documentation/git-am.adoc
> index 0c94776e296..18f5b950825 100644
> --- a/Documentation/git-am.adoc
> +++ b/Documentation/git-am.adoc
> @@ -259,10 +259,13 @@ message.  Any line that is of the form:
>   * a line that begins with "Index: "
>   
>   is taken as the beginning of a patch, and the commit log message
>   is terminated before the first occurrence of such a line.
>   
> +This means that the content of the commit message can inadverently
> +interrupt the processing (see the <<caveats,CAVEATS>> section below).
> +
>   When initially invoking `git am`, you give it the names of the mailboxes
>   to process.  Upon seeing the first patch that does not apply, it
>   aborts in the middle.  You can recover from this in one of two ways:
>   
>   . skip the current patch by re-running the command with the `--skip`
> @@ -281,10 +284,16 @@ Before any patches are applied, ORIG_HEAD is set to the tip of the
>   current branch.  This is useful if you have problems with multiple
>   commits, like running 'git am' on the wrong branch or an error in the
>   commits that is more easily fixed by changing the mailbox (e.g.
>   errors in the "From:" lines).
>   
> +[[caveats]]
> +CAVEATS
> +-------
> +
> +include::format-patch-caveats.adoc[]
> +
>   HOOKS
>   -----
>   This command can run `applypatch-msg`, `pre-applypatch`,
>   and `post-applypatch` hooks.  See linkgit:githooks[5] for more
>   information.
> diff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc
> index 9a7807ca71a..36851aaf5e1 100644
> --- a/Documentation/git-format-patch.adoc
> +++ b/Documentation/git-format-patch.adoc
> @@ -796,10 +796,14 @@ CAVEATS
>   Note that `format-patch` will omit merge commits from the output, even
>   if they are part of the requested range. A simple "patch" does not
>   include enough information for the receiving end to reproduce the same
>   merge commit.
>   
> +'''
> +
> +include::format-patch-caveats.adoc[]
> +
>   SEE ALSO
>   --------
>   linkgit:git-am[1], linkgit:git-send-email[1]
>   
>   GIT
> diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc
> index ebe8853e9f5..0b118df6498 100644
> --- a/Documentation/git-send-email.adoc
> +++ b/Documentation/git-send-email.adoc
> @@ -690,10 +690,15 @@ Links of a few such community maintained helpers are:
>   	  (cross platform client that can send emails using the ProtonMail API)
>   
>   	- https://github.com/AdityaGarg8/git-credential-email[git-msgraph]
>   	  (cross platform client that can send emails using the Microsoft Graph API)
>   
> +CAVEATS
> +-------
> +
> +include::format-patch-caveats.adoc[]
> +
>   SEE ALSO
>   --------
>   linkgit:git-format-patch[1], linkgit:git-imap-send[1], mbox(5)
>   
>   GIT
> 
> base-commit: 3e0db84c88c57e70ac8be8c196dfa92c5d656fbc

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

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

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

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

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

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

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

>>>[snip]
>>> 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?

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

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

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

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

> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
> 
> git-format-patch(1) and git-am(1) deal with formatting commits as
> patches and applying them, respectively. Naturally they use a few
> delimiters to mark where the commit message ends. This can lead to
> surprising behavior when these delimiters are used in the commit
> message itself.
> 
> git-format-patch(1) will accept any commit message and not warn or error
> about these delimiters being used.[1]
> 
> Especially problematic is the presence of unindented diffs in the commit
> message; the patch machinery will naturally (since the commit message
> has ended) try to apply that diff and everything after it.[2]
> 
> It is unclear whether any commands in this chain will learn to warn
> about this. One concern could be that users have learned to rely on
> the three-dash line rule to conveniently add extra-commit message
> information in the commit message, knowing that git-am(1) will
> ignore it.[4]
> 
> All of this is covered already, technically. However, we should spell
> out the implications.
> 
> † 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.
> † 2: Recently patch(1) caused this issue for a project, but it was noted
>       that git-am(1) has the same behavior[3]
> † 3: https://github.com/i3/i3/pull/6564#issuecomment-3858381425
> † 4: https://lore.kernel.org/git/xmqqldh4b5y2.fsf@gitster.g/
>       https://lore.kernel.org/git/V2_format-patch_caveats.34b@msgid.xyz/
> 
> Reported-by: Matthias Beyer <mail@beyermatthias.de>
> Reported-by: Christoph Anton Mitterer <calestyo@scientia.org>
> Reported-by: Matheus Tavares <matheus.tavb@gmail.com>
> Reported-by: Chris Packham <judge.packham@gmail.com>
> Helped-by: Jakob Haufe <sur5r@sur5r.net>
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> 
> ---
> 
> v2:
> 
> Address feedback from Phillip Wood.
> 
> Cc: Phillip Wood <phillip.wood@dunelm.org.uk>
> 
> • Drop the code blocks with the diffs; the prose speaks for itself, no need
>    to take up space
> • Don’t discuss git-send-email(1). We already know that git-format-patch(1)
>    is the generator. It is mentioned in git-send-email(1).
> • Try to be more clear about the case where someone might be applying a
>    diff. Use the example from Matthias Beyer in:
> 
>        https://lore.kernel.org/git/gfxpnecn2cdtmeiape2d4x5aybuyyqi4c7m6te3khgct34dd44@wqusigna2nsp/
> 
>    Hopefully I explained it correctly?
> • Add a “this goes to show...”... which seems to emphasize the point
>    without being redundant. Hopefully.
> 
> Try to address feedback from Junio C Hamano by adding more nuance: the diff
> in the commit message might be applied as well, or the patch machinery
> might trip on something and fail.
> 
> Finally, in the middle of discussing the three possible cmt. message
> delimiters, I noticed that the three points were drifting apart. So I
> decided to use the list already used in git-am(1) and be done with it in
> one place.
> 
> ---
> 
> It seems that the section break in git-format-patch(1) does not get
> applied in the man output (according to `Documentation/doc-diff`
> apparently)? Maybe this is the wrong construct? I couldn’t find any
> other thematic breaks here (though there are several variations).
> ---
>   Documentation/format-patch-caveats.adoc       | 36 +++++++++++++++++++
>   .../format-patch-end-of-commit-message.adoc   |  3 ++
>   Documentation/git-am.adoc                     | 15 ++++++--
>   Documentation/git-format-patch.adoc           |  4 +++
>   Documentation/git-send-email.adoc             |  5 +++
>   5 files changed, 60 insertions(+), 3 deletions(-)
>   create mode 100644 Documentation/format-patch-caveats.adoc
>   create mode 100644 Documentation/format-patch-end-of-commit-message.adoc
> 
> 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[]
> +
> +ifndef::git-am[]
> +Any line that is of the form:
> +
> +include::format-patch-end-of-commit-message.adoc[]
> +
> +will terminate the commit message and cause the patch machinery to start
> +searching for patches to apply.
> +endif::git-am[]
> +
> +Note that this is especially problematic for unindented diffs that occur
> +in the commit message; the diff in the commit message might get applied
> +along with the patch section, or the patch application machinery might
> +trip up because the patch target doesn't apply. This could for example
> +be caused by a diff in a GitHub Markdown code block.
> +
> +This loss of fidelity might be simple to notice if you are applying
> +patches directly from a mailbox. However, changes originating from Git
> +could be applied in bulk, in which case this would be much harder to
> +notice. This could for example be a Linux distribution which uses patch
> +files to apply changes on top of the commits from the upstream
> +repositories. This goes to show that this behavior does not only impact
> +email workflows.
> +
> +Given these limitations, one might be tempted to use a general-purpose
> +utility like patch(1) instead. However, patch(1) will not only look for
> +unindented diffs (like linkgit:git-am[1]) but will try to apply indented
> +diffs as well.
> diff --git a/Documentation/format-patch-end-of-commit-message.adoc b/Documentation/format-patch-end-of-commit-message.adoc
> new file mode 100644
> index 00000000000..47399ae7266
> --- /dev/null
> +++ b/Documentation/format-patch-end-of-commit-message.adoc
> @@ -0,0 +1,3 @@
> +* three-dashes and end-of-line, or
> +* a line that begins with "diff -", or
> +* a line that begins with "Index: "
> diff --git a/Documentation/git-am.adoc b/Documentation/git-am.adoc
> index 0c94776e296..756dfd722b9 100644
> --- a/Documentation/git-am.adoc
> +++ b/Documentation/git-am.adoc
> @@ -231,10 +231,11 @@ applying.
>   --allow-empty::
>   	After a patch failure on an input e-mail message lacking a patch,
>   	create an empty commit with the contents of the e-mail message
>   	as its log message.
>   
> +[[discussion]]
>   DISCUSSION
>   ----------
>   
>   The commit author name is taken from the "From: " line of the
>   message, and commit author date is taken from the "Date: " line
> @@ -252,17 +253,18 @@ where the patch begins.  Excess whitespace at the end of each
>   line is automatically stripped.
>   
>   The patch is expected to be inline, directly following the
>   message.  Any line that is of the form:
>   
> -* three-dashes and end-of-line, or
> -* a line that begins with "diff -", or
> -* a line that begins with "Index: "
> +include::format-patch-end-of-commit-message.adoc[]
>   
>   is taken as the beginning of a patch, and the commit log message
>   is terminated before the first occurrence of such a line.
>   
> +This means that the contents of the commit message can inadvertently
> +interrupt the processing (see the <<caveats,CAVEATS>> section below).
> +
>   When initially invoking `git am`, you give it the names of the mailboxes
>   to process.  Upon seeing the first patch that does not apply, it
>   aborts in the middle.  You can recover from this in one of two ways:
>   
>   . skip the current patch by re-running the command with the `--skip`
> @@ -281,10 +283,17 @@ Before any patches are applied, ORIG_HEAD is set to the tip of the
>   current branch.  This is useful if you have problems with multiple
>   commits, like running 'git am' on the wrong branch or an error in the
>   commits that is more easily fixed by changing the mailbox (e.g.
>   errors in the "From:" lines).
>   
> +[[caveats]]
> +CAVEATS
> +-------
> +
> +:git-am: 1
> +include::format-patch-caveats.adoc[]
> +
>   HOOKS
>   -----
>   This command can run `applypatch-msg`, `pre-applypatch`,
>   and `post-applypatch` hooks.  See linkgit:githooks[5] for more
>   information.
> diff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc
> index 9a7807ca71a..36851aaf5e1 100644
> --- a/Documentation/git-format-patch.adoc
> +++ b/Documentation/git-format-patch.adoc
> @@ -796,10 +796,14 @@ CAVEATS
>   Note that `format-patch` will omit merge commits from the output, even
>   if they are part of the requested range. A simple "patch" does not
>   include enough information for the receiving end to reproduce the same
>   merge commit.
>   
> +'''
> +
> +include::format-patch-caveats.adoc[]
> +
>   SEE ALSO
>   --------
>   linkgit:git-am[1], linkgit:git-send-email[1]
>   
>   GIT
> diff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc
> index ebe8853e9f5..0b118df6498 100644
> --- a/Documentation/git-send-email.adoc
> +++ b/Documentation/git-send-email.adoc
> @@ -690,10 +690,15 @@ Links of a few such community maintained helpers are:
>   	  (cross platform client that can send emails using the ProtonMail API)
>   
>   	- https://github.com/AdityaGarg8/git-credential-email[git-msgraph]
>   	  (cross platform client that can send emails using the Microsoft Graph API)
>   
> +CAVEATS
> +-------
> +
> +include::format-patch-caveats.adoc[]
> +
>   SEE ALSO
>   --------
>   linkgit:git-format-patch[1], linkgit:git-imap-send[1], mbox(5)
>   
>   GIT
> 
> Interdiff against v1:
>    diff --git a/Documentation/format-patch-caveats.adoc b/Documentation/format-patch-caveats.adoc
>    index 2accf2763fd..c666d709742 100644
>    --- a/Documentation/format-patch-caveats.adoc
>    +++ b/Documentation/format-patch-caveats.adoc
>    @@ -1,39 +1,36 @@
>    -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.
>    +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[]
>     
>    -The commit message might contain a three-dash line (`---`) which was
>    -perhaps meant to be a thematic break. That means that the commit message
>    -will be cut short. The presence of a line starting with "Index: " can
>    -cause the patch not to be found, giving an error about an empty patch.
>    +ifndef::git-am[]
>    +Any line that is of the form:
>     
>    -Furthermore, the presence of an unindented diff in the commit message
>    -will not only cut the message short but cause that very diff to be
>    -applied, along with the patch in the patch section. The commit message
>    -might for example have a diff in a GitHub MarkDown code fence:
>    +include::format-patch-end-of-commit-message.adoc[]
>     
>    -----
>    -```
>    -diff ...
>    -```
>    -----
>    +will terminate the commit message and cause the patch machinery to start
>    +searching for patches to apply.
>    +endif::git-am[]
>     
>    -The solution for this is to indent the diff instead:
>    -
>    -----
>    -    diff ...
>    -----
>    +Note that this is especially problematic for unindented diffs that occur
>    +in the commit message; the diff in the commit message might get applied
>    +along with the patch section, or the patch application machinery might
>    +trip up because the patch target doesn't apply. This could for example
>    +be caused by a diff in a GitHub Markdown code block.
>     
>     This loss of fidelity might be simple to notice if you are applying
>    -patches directly from a mailbox. However, a commit authored long ago
>    -might be applied in a different context, perhaps because many changes
>    -are being integrated via patch files and the
>    -linkgit:git-format-patch[1] format is trusted to import changes of a
>    -Git origin.
>    +patches directly from a mailbox. However, changes originating from Git
>    +could be applied in bulk, in which case this would be much harder to
>    +notice. This could for example be a Linux distribution which uses patch
>    +files to apply changes on top of the commits from the upstream
>    +repositories. This goes to show that this behavior does not only impact
>    +email workflows.
>     
>    -One might want to use a general-purpose utility like patch(1) instead,
>    -given these limitations. However, patch(1) will not only look for
>    +Given these limitations, one might be tempted to use a general-purpose
>    +utility like patch(1) instead. However, patch(1) will not only look for
>     unindented diffs (like linkgit:git-am[1]) but will try to apply indented
>     diffs as well.
>    diff --git a/Documentation/format-patch-end-of-commit-message.adoc b/Documentation/format-patch-end-of-commit-message.adoc
>    new file mode 100644
>    index 00000000000..47399ae7266
>    --- /dev/null
>    +++ b/Documentation/format-patch-end-of-commit-message.adoc
>    @@ -0,0 +1,3 @@
>    +* three-dashes and end-of-line, or
>    +* a line that begins with "diff -", or
>    +* a line that begins with "Index: "
>    diff --git a/Documentation/git-am.adoc b/Documentation/git-am.adoc
>    index 18f5b950825..756dfd722b9 100644
>    --- a/Documentation/git-am.adoc
>    +++ b/Documentation/git-am.adoc
>    @@ -231,10 +231,11 @@ applying.
>     --allow-empty::
>     	After a patch failure on an input e-mail message lacking a patch,
>     	create an empty commit with the contents of the e-mail message
>     	as its log message.
>     
>    +[[discussion]]
>     DISCUSSION
>     ----------
>     
>     The commit author name is taken from the "From: " line of the
>     message, and commit author date is taken from the "Date: " line
>    @@ -252,18 +253,16 @@ where the patch begins.  Excess whitespace at the end of each
>     line is automatically stripped.
>     
>     The patch is expected to be inline, directly following the
>     message.  Any line that is of the form:
>     
>    -* three-dashes and end-of-line, or
>    -* a line that begins with "diff -", or
>    -* a line that begins with "Index: "
>    +include::format-patch-end-of-commit-message.adoc[]
>     
>     is taken as the beginning of a patch, and the commit log message
>     is terminated before the first occurrence of such a line.
>     
>    -This means that the content of the commit message can inadverently
>    +This means that the contents of the commit message can inadvertently
>     interrupt the processing (see the <<caveats,CAVEATS>> section below).
>     
>     When initially invoking `git am`, you give it the names of the mailboxes
>     to process.  Upon seeing the first patch that does not apply, it
>     aborts in the middle.  You can recover from this in one of two ways:
>    @@ -288,10 +287,11 @@ errors in the "From:" lines).
>     
>     [[caveats]]
>     CAVEATS
>     -------
>     
>    +:git-am: 1
>     include::format-patch-caveats.adoc[]
>     
>     HOOKS
>     -----
>     This command can run `applypatch-msg`, `pre-applypatch`,
> 
> Range-diff against v1:
> 1:  4bed8f55b98 ! 1:  c54f394bb33 doc: add caveat about roundtripping format-patch
>      @@ Metadata
>        ## Commit message ##
>           doc: add caveat about roundtripping format-patch
>       
>      -    git-format-patch(1), git-send-email(1), and git-am(1) deal with
>      -    formatting commits as patches, sending them (perhaps directly), and
>      -    applying them, respectively. Naturally they use a few delimiters to mark
>      -    where the commit message ends. This can lead to surprising behavior when
>      -    these delimiters are used in the commit message itself.
>      +    git-format-patch(1) and git-am(1) deal with formatting commits as
>      +    patches and applying them, respectively. Naturally they use a few
>      +    delimiters to mark where the commit message ends. This can lead to
>      +    surprising behavior when these delimiters are used in the commit
>      +    message itself.
>       
>      -    git-format-patch(1) and git-send-email(1) will accept any commit message
>      -    and not warn or error about these delimiters being used.[1]
>      +    git-format-patch(1) will accept any commit message and not warn or error
>      +    about these delimiters being used.[1]
>       
>      -    Moreover, the presence of unindented diffs in the commit message will
>      -    cause git-am(1) to apply both the diffs from the commit message as well
>      -    as the patch section.[2]
>      +    Especially problematic is the presence of unindented diffs in the commit
>      +    message; the patch machinery will naturally (since the commit message
>      +    has ended) try to apply that diff and everything after it.[2]
>       
>           It is unclear whether any commands in this chain will learn to warn
>           about this. One concern could be that users have learned to rely on
>      @@ Commit message
>           information in the commit message, knowing that git-am(1) will
>           ignore it.[4]
>       
>      -    All of this is covered already, technically, However, we should spell
>      +    All of this is covered already, technically. However, we should spell
>           out the implications.
>       
>           † 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.
>      -    [2]: Recently patch(1) caused this issue for a project, but it was noted
>      +    † 2: Recently patch(1) caused this issue for a project, but it was noted
>                that git-am(1) has the same behavior[3]
>      -    [3]: https://github.com/i3/i3/pull/6564#issuecomment-3858381425
>      -    [4]: https://lore.kernel.org/git/xmqqldh4b5y2.fsf@gitster.g/
>      +    † 3: https://github.com/i3/i3/pull/6564#issuecomment-3858381425
>      +    † 4: https://lore.kernel.org/git/xmqqldh4b5y2.fsf@gitster.g/
>      +         https://lore.kernel.org/git/V2_format-patch_caveats.34b@msgid.xyz/
>       
>           Reported-by: Matthias Beyer <mail@beyermatthias.de>
>           Reported-by: Christoph Anton Mitterer <calestyo@scientia.org>
>      @@ Commit message
>           Helped-by: Jakob Haufe <sur5r@sur5r.net>
>           Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
>       
>      +    ---
>      +
>      +    v2:
>      +
>      +    Address feedback from Phillip Wood.
>      +
>      +    Cc: Phillip Wood <phillip.wood@dunelm.org.uk>
>      +
>      +    • Drop the code blocks with the diffs; the prose speaks for itself, no need
>      +      to take up space
>      +    • Don’t discuss git-send-email(1). We already know that git-format-patch(1)
>      +      is the generator. It is mentioned in git-send-email(1).
>      +    • Try to be more clear about the case where someone might be applying a
>      +      diff. Use the example from Matthias Beyer in:
>      +
>      +          https://lore.kernel.org/git/gfxpnecn2cdtmeiape2d4x5aybuyyqi4c7m6te3khgct34dd44@wqusigna2nsp/
>      +
>      +      Hopefully I explained it correctly?
>      +    • Add a “this goes to show...”... which seems to emphasize the point
>      +      without being redundant. Hopefully.
>      +
>      +    Try to address feedback from Junio C Hamano by adding more nuance: the diff
>      +    in the commit message might be applied as well, or the patch machinery
>      +    might trip on something and fail.
>      +
>      +    Finally, in the middle of discussing the three possible cmt. message
>      +    delimiters, I noticed that the three points were drifting apart. So I
>      +    decided to use the list already used in git-am(1) and be done with it in
>      +    one place.
>      +
>      +    ---
>      +
>      +    It seems that the section break in git-format-patch(1) does not get
>      +    applied in the man output (according to `Documentation/doc-diff`
>      +    apparently)? Maybe this is the wrong construct? I couldn’t find any
>      +    other thematic breaks here (though there are several variations).
>      +
>        ## Documentation/format-patch-caveats.adoc (new) ##
>       @@
>      -+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.
>      -+
>      -+The commit message might contain a three-dash line (`---`) which was
>      -+perhaps meant to be a thematic break. That means that the commit message
>      -+will be cut short. The presence of a line starting with "Index: " can
>      -+cause the patch not to be found, giving an error about an empty patch.
>      ++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[]
>       +
>      -+Furthermore, the presence of an unindented diff in the commit message
>      -+will not only cut the message short but cause that very diff to be
>      -+applied, along with the patch in the patch section. The commit message
>      -+might for example have a diff in a GitHub MarkDown code fence:
>      ++ifndef::git-am[]
>      ++Any line that is of the form:
>       +
>      -+----
>      -+```
>      -+diff ...
>      -+```
>      -+----
>      ++include::format-patch-end-of-commit-message.adoc[]
>       +
>      -+The solution for this is to indent the diff instead:
>      ++will terminate the commit message and cause the patch machinery to start
>      ++searching for patches to apply.
>      ++endif::git-am[]
>       +
>      -+----
>      -+    diff ...
>      -+----
>      ++Note that this is especially problematic for unindented diffs that occur
>      ++in the commit message; the diff in the commit message might get applied
>      ++along with the patch section, or the patch application machinery might
>      ++trip up because the patch target doesn't apply. This could for example
>      ++be caused by a diff in a GitHub Markdown code block.
>       +
>       +This loss of fidelity might be simple to notice if you are applying
>      -+patches directly from a mailbox. However, a commit authored long ago
>      -+might be applied in a different context, perhaps because many changes
>      -+are being integrated via patch files and the
>      -+linkgit:git-format-patch[1] format is trusted to import changes of a
>      -+Git origin.
>      ++patches directly from a mailbox. However, changes originating from Git
>      ++could be applied in bulk, in which case this would be much harder to
>      ++notice. This could for example be a Linux distribution which uses patch
>      ++files to apply changes on top of the commits from the upstream
>      ++repositories. This goes to show that this behavior does not only impact
>      ++email workflows.
>       +
>      -+One might want to use a general-purpose utility like patch(1) instead,
>      -+given these limitations. However, patch(1) will not only look for
>      ++Given these limitations, one might be tempted to use a general-purpose
>      ++utility like patch(1) instead. However, patch(1) will not only look for
>       +unindented diffs (like linkgit:git-am[1]) but will try to apply indented
>       +diffs as well.
>       
>      + ## Documentation/format-patch-end-of-commit-message.adoc (new) ##
>      +@@
>      ++* three-dashes and end-of-line, or
>      ++* a line that begins with "diff -", or
>      ++* a line that begins with "Index: "
>      +
>        ## Documentation/git-am.adoc ##
>      -@@ Documentation/git-am.adoc: message.  Any line that is of the form:
>      +@@ Documentation/git-am.adoc: applying.
>      + 	create an empty commit with the contents of the e-mail message
>      + 	as its log message.
>      +
>      ++[[discussion]]
>      + DISCUSSION
>      + ----------
>      +
>      +@@ Documentation/git-am.adoc: line is automatically stripped.
>      + The patch is expected to be inline, directly following the
>      + message.  Any line that is of the form:
>      +
>      +-* three-dashes and end-of-line, or
>      +-* a line that begins with "diff -", or
>      +-* a line that begins with "Index: "
>      ++include::format-patch-end-of-commit-message.adoc[]
>      +
>        is taken as the beginning of a patch, and the commit log message
>        is terminated before the first occurrence of such a line.
>        
>      -+This means that the content of the commit message can inadverently
>      ++This means that the contents of the commit message can inadvertently
>       +interrupt the processing (see the <<caveats,CAVEATS>> section below).
>       +
>        When initially invoking `git am`, you give it the names of the mailboxes
>      @@ Documentation/git-am.adoc: commits, like running 'git am' on the wrong branch or
>       +CAVEATS
>       +-------
>       +
>      ++:git-am: 1
>       +include::format-patch-caveats.adoc[]
>       +
>        HOOKS
> 
> base-commit: 3e0db84c88c57e70ac8be8c196dfa92c5d656fbc

>[snip]
> @@ -796,10 +796,14 @@ CAVEATS
>  Note that `format-patch` will omit merge commits from the output, even
>  if they are part of the requested range. A simple "patch" does not
>  include enough information for the receiving end to reproduce the same
>  merge commit.
>
> +'''
> +
> +include::format-patch-caveats.adoc[]
> +
>  SEE ALSO
>  --------
>[snip]
>     +
>     +    It seems that the section break in git-format-patch(1) does not get
>     +    applied in the man output (according to `Documentation/doc-diff`
>     +    apparently)? Maybe this is the wrong construct? I couldn’t find any
>     +    other thematic breaks here (though there are several variations).
>     +
>[snip]

> kristofferhaugsbakk@fastmail.com writes:
> 
>> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>> ...
>> All of this is covered already, technically. However, we should spell
>> out the implications.
> 
> I've read the new text (without formatting, I have to admit) again,
> and did not see anything questionable.  Nicely written.
> 
> Shall we mark this for 'next'?

> On 12/02/2026 23:19, Junio C Hamano wrote:
>> kristofferhaugsbakk@fastmail.com writes:
>>
>>> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>>> ...
>>> All of this is covered already, technically. However, we should spell
>>> out the implications.
>>
>> I've read the new text (without formatting, I have to admit) again,
>> and did not see anything questionable.  Nicely written.
>>
>> Shall we mark this for 'next'?
>
> I'm happy with this version - thanks for working on it Kristoffer

> On 12/02/2026 23:19, Junio C Hamano wrote:
>> kristofferhaugsbakk@fastmail.com writes:
>> 
>>> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>>> ...
>>> All of this is covered already, technically. However, we should spell
>>> out the implications.
>> 
>> I've read the new text (without formatting, I have to admit) again,
>> and did not see anything questionable.  Nicely written.
>> 
>> Shall we mark this for 'next'?
>
> I'm happy with this version - thanks for working on it Kristoffer
>
> Phillip

> While it's nice to see it getting documented (thanks for that)...
> wouldn't it be even better to actually fix the underlying issue? :-)
>
> I mean it's all but guaranteed that everyone reads this,... and IMO the
> problem might even be exploited security wise.