[PATCH] Documentation: clarify signature verification

[The Fox in the Shell <KellerFuchs@hashbang.sh>]

Hi,

I encountered some issues with the git documentation while modifying
my deployment scripts to enforce that the tree being fetched was
signed by a trusted key.

It was unclear which commits needed to be signed (in the case of `git
merge`) and what were the criteria for the signature to be considered
valid.

Here is a patch proposal.

Signed-off-by: The Fox in the Shell <KellerFuchs@hashbang.sh>
---
 Documentation/merge-options.txt  | 4 +++-
 Documentation/pretty-formats.txt | 4 ++--
 Documentation/pretty-options.txt | 4 ++--
 3 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt
index f08e9b8..edd50bf 100644
--- a/Documentation/merge-options.txt
+++ b/Documentation/merge-options.txt
@@ -89,8 +89,10 @@ option can be used to override --squash.
 
 --verify-signatures::
 --no-verify-signatures::
-	Verify that the commits being merged have good and trusted GPG signatures
+	Verify that the commits being merged have good and valid GPG signatures
 	and abort the merge in case they do not.
+	For instance, when running `git merge --verify-signature remote/branch`,
+	only the head commit on `remote/branch` needs to be signed.
 
 --summary::
 --no-summary::
diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 671cebd..29b19b9 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -143,8 +143,8 @@ ifndef::git-rev-list[]
 - '%N': commit notes
 endif::git-rev-list[]
 - '%GG': raw verification message from GPG for a signed commit
-- '%G?': show "G" for a Good signature, "B" for a Bad signature, "U" for a good,
-  untrusted signature and "N" for no signature
+- '%G?': show "G" for a good (valid) signature, "B" for a bad signature,
+  "U" for a good signature with unknown validity and "N" for no signature
 - '%GS': show the name of the signer for a signed commit
 - '%GK': show the key used to sign a signed commit
 - '%gD': reflog selector, e.g., `refs/stash@{1}`
diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt
index 54b88b6..62cbae2 100644
--- a/Documentation/pretty-options.txt
+++ b/Documentation/pretty-options.txt
@@ -78,5 +78,5 @@ being displayed. Examples: "--notes=foo" will show only notes from
 endif::git-rev-list[]
 
 --show-signature::
-	Check the validity of a signed commit object by passing the signature
-	to `gpg --verify` and show the output.
+	Check the validity of a signed commit object, by passing the signature
+	to `gpg --verify`, and show the output.
-- 
2.1.4