Documentation: "git am" should point to "git format-patch"

Documentation: "git am" should point to "git format-patch"

[Kai Grossjohann]

The man page of "git format-patch" already mentions that its output
can be consumed by "git am".  I suggest to add a similar remark to the
man page of "git am" to mention that it consumes output from "git
format-patch".

I read the output of "git format-patch --help" and "git am --help",
using git version 2.40.0 installed via Homebrew on macOS 13.2.1
(22D68).

Kai

Re: Documentation: "git am" should point to "git format-patch"

[Junio C Hamano]

Kai Grossjohann <kai.grossjohann@gmail.com> writes:

> The man page of "git format-patch" already mentions that its output
> can be consumed by "git am".  I suggest to add a similar remark to the
> man page of "git am" to mention that it consumes output from "git
> format-patch".

There were two reasons we didn't do this.  As "git am" is designed
to grok e-mailed patches, not necessarily taken out of a Git
repostiory or even if it came from a Git repository not necessarily
produced with format-patch, we didn't want to single it out as the
"blessed" input producer to the command.  Also, in the original
workflow that "git am" was invented for, the user of "am" was
expected to be a different person than the users of "format-patch".

But I think that it is a very safe change to make in 2023.  Thanks
to the effort by many contributors, Git ended up becoming a bit more
popular than we initially thought it would be, and "format-patch",
which took me a few weeks to pursuade Linus to take in 2005, seems
to have become the de-facto standard tool to produce patch e-mails.

Interestingly, the documentation for "git apply", which is listed in
SEE ALSO section of "git am" documentation, does mention "am" and
"format-patch" as two things that are related but different from
"apply" in an early part.


 Documentation/git-am.txt | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git c/Documentation/git-am.txt w/Documentation/git-am.txt
index 0c1dfb3c98..900be198b1 100644
--- c/Documentation/git-am.txt
+++ w/Documentation/git-am.txt
@@ -24,7 +24,9 @@ DESCRIPTION
 -----------
 Splits mail messages in a mailbox into commit log message,
 authorship information and patches, and applies them to the
-current branch.
+current branch. You could think of it as a reverse operation
+of linkgit:git-format-patch[1] run on a branch with a straight
+history without merges.
 
 OPTIONS
 -------
@@ -273,7 +275,8 @@ include::config/am.txt[]
 
 SEE ALSO
 --------
-linkgit:git-apply[1].
+linkgit:git-apply[1],
+linkgit:git-format-patch[1].
 
 GIT
 ---