[PATCH 2/2] docs: demonstrate difference between 'am' and 'apply'

[Emily Shaffer <emilyshaffer@google.com>]

Some users skimmed past the note in 'git help apply' mentioning 'git
am' and weren't sure how to retain commit details. An example
illustrating the difference between the two shows this information in
another way, so users who prefer to be shown rather than told can
discover the difference too.

Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
---

Notes:
    In this change, I wasn't sure about a few things:
    
    - Should the comments on the snippets live outside of the blockquote instead?
    - Should 'git reset' be included in the snippets, so that users don't try to
      paste without thinking?
    - Should the example go underneath the options list?
    
    Anyway, we got internal feedback that the description in 'git help am' wasn't
    very noticeable. I'm not sure I agree, but it's true that some folks grok
    examples more easily than they grok prose, so we figured it probably couldn't
    hurt to provide both.
    
     - Emily

 Documentation/git-am.txt    | 58 +++++++++++++++++++++++++++++++++++++
 Documentation/git-apply.txt | 55 +++++++++++++++++++++++++++++++++++
 2 files changed, 113 insertions(+)

diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index 38c0852139..e64f3f10e3 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -24,6 +24,64 @@ Splits mail messages in a mailbox into commit log message,
 authorship information and patches, and applies them to the
 current branch.
 
+This command applies patches as commits. Use linkgit:git-apply[1] to apply
+patches to the worktree without creating commits.
+
+EXAMPLE
+-------
+....
+# our sample patch, generated with 'git format-patch'
+$ cat ~/0001-README-add-more-text.patch
+From f9e01d7538c9d58b48500732b4f98f40f6ad845e Mon Sep 17 00:00:00 2001
+From: A U Thor <author@example.com>
+Date: Fri, 16 Oct 2020 13:14:42 -0700
+Subject: [PATCH] README: add more text
+
+Some additional context.
+
+Signed-off-by: A U Thor <author@example.com>
+---
+ README | 2 +-
+ 1 file changed, 1 insertion(+), 1 deletion(-)
+
+diff --git a/README b/README
+index cd08755..cfdf4e7 100644
+--- a/README
++++ b/README
+@@ -1 +1 @@
+-Hello world!
++Hello world! This is an example.
+--
+2.29.0.rc1.297.gfa9743e501
+
+# use 'git am' to create a new commit with details from the patch
+$ git status
+On branch main
+nothing to commit, working tree clean
+$ git am ~/0001-README-add-more-text.patch
+Applying: README: add more text
+$ git status
+On branch main
+nothing to commit, working tree clean
+$ git log --oneline
+dd6a400 (HEAD -> main) README: add more text
+90b59fb base commit
+
+# use 'git apply' to apply to the worktree without creating a commit.
+$ git status
+On branch main
+nothing to commit, working tree clean
+$ git apply ~/0001-README-add-more-text.patch
+$ git status
+On branch main
+Changes not staged for commit:
+  (use "git add <file>..." to update what will be committed)
+  (use "git restore <file>..." to discard changes in working directory)
+	modified:   README
+
+no changes added to commit (use "git add" and/or "git commit -a")
+....
+
 OPTIONS
 -------
 (<mbox>|<Maildir>)...::
diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
index 91d9a8601c..38e9d8f713 100644
--- a/Documentation/git-apply.txt
+++ b/Documentation/git-apply.txt
@@ -32,6 +32,61 @@ This command applies the patch but does not create a commit.  Use
 linkgit:git-am[1] to create commits from patches generated by
 linkgit:git-format-patch[1] and/or received by email.
 
+EXAMPLE
+-------
+....
+# our sample patch, generated with 'git format-patch'
+$ cat ~/0001-README-add-more-text.patch
+From f9e01d7538c9d58b48500732b4f98f40f6ad845e Mon Sep 17 00:00:00 2001
+From: A U Thor <author@example.com>
+Date: Fri, 16 Oct 2020 13:14:42 -0700
+Subject: [PATCH] README: add more text
+
+Some additional context.
+
+Signed-off-by: A U Thor <author@example.com>
+---
+ README | 2 +-
+ 1 file changed, 1 insertion(+), 1 deletion(-)
+
+diff --git a/README b/README
+index cd08755..cfdf4e7 100644
+--- a/README
++++ b/README
+@@ -1 +1 @@
+-Hello world!
++Hello world! This is an example.
+--
+2.29.0.rc1.297.gfa9743e501
+
+# use 'git apply' to apply to the worktree without creating a commit.
+$ git status
+On branch main
+nothing to commit, working tree clean
+$ git apply ~/0001-README-add-more-text.patch
+$ git status
+On branch main
+Changes not staged for commit:
+  (use "git add <file>..." to update what will be committed)
+  (use "git restore <file>..." to discard changes in working directory)
+	modified:   README
+
+no changes added to commit (use "git add" and/or "git commit -a")
+
+# use 'git am' to create a new commit with details from the patch
+$ git status
+On branch main
+nothing to commit, working tree clean
+$ git am ~/0001-README-add-more-text.patch
+Applying: README: add more text
+$ git status
+On branch main
+nothing to commit, working tree clean
+$ git log --oneline
+dd6a400 (HEAD -> main) README: add more text
+90b59fb base commit
+....
+
 OPTIONS
 -------
 <patch>...::
-- 
2.28.0.rc0.142.g3c755180ce-goog