gpg docs: explain better use of ssh.defaultKeyCommand

Using `ssh-add -L` for gpg.ssh.defaultKeyCommand is not a good
recommendation. It might switch keys depending on the order of known
keys and it only supports ssh-* and no ecdsa or other keys.
Clarify that we expect a literal key prefixed by `key::`, give valid
example use cases and refer to `user.signingKey` as the preferred
option.

Signed-off-by: Fabian Stelzer <fs@gigacodes.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/config/gpg.txt b/Documentation/config/gpg.txt
index 86892ada771e802830cd10d3e5ff95bc74355e9e..86f6308c4c051814cc4f32a2d7b5d20aabb276e1 100644 (file)
--- a/Documentation/config/gpg.txt
+++ b/Documentation/config/gpg.txt
@@ -36,9 +36,12 @@ gpg.minTrustLevel::
 
 gpg.ssh.defaultKeyCommand::
        This command that will be run when user.signingkey is not set and a ssh
-       signature is requested. On successful exit a valid ssh public key is
-       expected in the first line of its output. To automatically use the first
-       available key from your ssh-agent set this to "ssh-add -L".
+       signature is requested. On successful exit a valid ssh public key
+       prefixed with `key::` is expected in the first line of its output.
+       This allows for a script doing a dynamic lookup of the correct public
+       key when it is impractical to statically configure `user.signingKey`.
+       For example when keys or SSH Certificates are rotated frequently or
+       selection of the right key depends on external factors unknown to git.
 
 gpg.ssh.allowedSignersFile::
        A file containing ssh public keys which you are willing to trust.