| 1 | The output from linkgit:git-format-patch[1] can lead to a different |
| 2 | commit message when applied with linkgit:git-am[1]. The patch that is |
| 3 | applied may also be different from the one that was generated, or patch |
| 4 | application may fail outright. |
| 5 | ifdef::git-am[] |
| 6 | See the <<discussion,DISCUSSION>> section above for the syntactic rules. |
| 7 | endif::git-am[] |
| 8 | |
| 9 | ifndef::git-am[] |
| 10 | include::format-patch-end-of-commit-message.adoc[] |
| 11 | endif::git-am[] |
| 12 | |
| 13 | Note that this is especially problematic for unindented diffs that occur |
| 14 | in the commit message; the diff in the commit message might get applied |
| 15 | along with the patch section, or the patch application machinery might |
| 16 | trip up because the patch target doesn't apply. This could for example |
| 17 | be caused by a diff in a Markdown code block. |
| 18 | |
| 19 | The solution for this is to indent the diff or other text that could |
| 20 | cause problems. |
| 21 | |
| 22 | This loss of fidelity might be simple to notice if you are applying |
| 23 | patches directly from a mailbox. However, changes originating from Git |
| 24 | could be applied in bulk, in which case this would be much harder to |
| 25 | notice. This could for example be a Linux distribution which uses patch |
| 26 | files to apply changes on top of the commits from the upstream |
| 27 | repositories. This goes to show that this behavior does not only impact |
| 28 | email workflows. |
| 29 | |
| 30 | Given these limitations, one might be tempted to use a general-purpose |
| 31 | utility like `patch`(1) instead. However, `patch`(1) will not only look for |
| 32 | unindented diffs (like linkgit:git-am[1]) but will try to apply indented |
| 33 | diffs as well. |