{"thread":{"id":"59430","subject":"Documentation: \"git am\" should point to \"git format-patch\"","startedAt":"2023-03-21T16:41:22Z","lastAt":"2023-03-21T17:27:12Z","messageCount":2,"participants":["Kai Grossjohann","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"473848","messageId":"CAFmGgWVVdgQj_gzcDw4Lyzt1aBc-7oyt8=JT3GskHegUu+8sTg@mail.gmail.com","threadId":"59430","inReplyTo":null,"subject":"Documentation: \"git am\" should point to \"git format-patch\"","fromName":"Kai Grossjohann","fromEmail":"kai.grossjohann@gmail.com","sentAt":"2023-03-21T16:40:32Z","receivedAt":"2023-03-21T16:41:22Z","isPatch":false,"sender":{"key":"kai.grossjohann@gmail.com","avatar":null},"body":"The man page of \"git format-patch\" already mentions that its output\ncan be consumed by \"git am\".  I suggest to add a similar remark to the\nman page of \"git am\" to mention that it consumes output from \"git\nformat-patch\".\n\nI read the output of \"git format-patch --help\" and \"git am --help\",\nusing git version 2.40.0 installed via Homebrew on macOS 13.2.1\n(22D68).\n\nKai\n"},{"id":"473854","messageId":"xmqq1qlij9qr.fsf@gitster.g","threadId":"59430","inReplyTo":"CAFmGgWVVdgQj_gzcDw4Lyzt1aBc-7oyt8=JT3GskHegUu+8sTg@mail.gmail.com","subject":"Re: Documentation: \"git am\" should point to \"git format-patch\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-03-21T17:27:08Z","receivedAt":"2023-03-21T17:27:12Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Kai Grossjohann <kai.grossjohann@gmail.com> writes:\n\n> The man page of \"git format-patch\" already mentions that its output\n> can be consumed by \"git am\".  I suggest to add a similar remark to the\n> man page of \"git am\" to mention that it consumes output from \"git\n> format-patch\".\n\nThere were two reasons we didn't do this.  As \"git am\" is designed\nto grok e-mailed patches, not necessarily taken out of a Git\nrepostiory or even if it came from a Git repository not necessarily\nproduced with format-patch, we didn't want to single it out as the\n\"blessed\" input producer to the command.  Also, in the original\nworkflow that \"git am\" was invented for, the user of \"am\" was\nexpected to be a different person than the users of \"format-patch\".\n\nBut I think that it is a very safe change to make in 2023.  Thanks\nto the effort by many contributors, Git ended up becoming a bit more\npopular than we initially thought it would be, and \"format-patch\",\nwhich took me a few weeks to pursuade Linus to take in 2005, seems\nto have become the de-facto standard tool to produce patch e-mails.\n\nInterestingly, the documentation for \"git apply\", which is listed in\nSEE ALSO section of \"git am\" documentation, does mention \"am\" and\n\"format-patch\" as two things that are related but different from\n\"apply\" in an early part.\n\n\n Documentation/git-am.txt | 7 +++++--\n 1 file changed, 5 insertions(+), 2 deletions(-)\n\ndiff --git c/Documentation/git-am.txt w/Documentation/git-am.txt\nindex 0c1dfb3c98..900be198b1 100644\n--- c/Documentation/git-am.txt\n+++ w/Documentation/git-am.txt\n@@ -24,7 +24,9 @@ DESCRIPTION\n -----------\n Splits mail messages in a mailbox into commit log message,\n authorship information and patches, and applies them to the\n-current branch.\n+current branch. You could think of it as a reverse operation\n+of linkgit:git-format-patch[1] run on a branch with a straight\n+history without merges.\n \n OPTIONS\n -------\n@@ -273,7 +275,8 @@ include::config/am.txt[]\n \n SEE ALSO\n --------\n-linkgit:git-apply[1].\n+linkgit:git-apply[1],\n+linkgit:git-format-patch[1].\n \n GIT\n ---\n"}]}