doc: git-tag: stop focusing on GPG signed tags

It looks like the documentation of `git tag` is focused a bit too
much on GPG signed tags.

This starts with the "NAME" section where the command is described
with:

"Create, list, delete or verify a tag object signed with GPG"

while for example `git branch` is described with simply:

"List, create, or delete branches"

This could give the false impression that `git tag` only works with
tag objects, not with lightweight tags, and that tag objects are
always GPG signed.

In the "DESCRIPTION" section, it looks like only "GnuPG signed tag
objects" can be created by the `-s` and `-u <key-id>` options, and it
seems `gpg.program` can only specify a "custom GnuPG binary".

This goes on in the "OPTIONS" section too, especially about the `-s`
and `-u <key-id>` options.

The "CONFIGURATION" section also doesn't talk about how to configure
the command to work with X.509 and SSH signatures.

Let's rework all that to make sure users have a more accurate and
balanced view of what the command can do.

Helped-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-tag.adoc b/Documentation/git-tag.adoc
index a4b1c0ec05a6c956d90016ac526358b8b2604c65..28d6fe4e1a63acfb62749dab63089fa22082f3ff 100644 (file)
--- a/Documentation/git-tag.adoc
+++ b/Documentation/git-tag.adoc
@@ -3,7 +3,7 @@ git-tag(1)
 
 NAME
 ----
-git-tag - Create, list, delete or verify a tag object signed with GPG
+git-tag - Create, list, delete or verify tags
 
 
 SYNOPSIS
@@ -38,15 +38,17 @@ and `-a`, `-s`, and `-u <key-id>` are absent, `-a` is implied.
 Otherwise, a tag reference that points directly at the given object
 (i.e., a lightweight tag) is created.
 
-A GnuPG signed tag object will be created when `-s` or `-u
-<key-id>` is used.  When `-u <key-id>` is not used, the
-committer identity for the current user is used to find the
-GnuPG key for signing.         The configuration variable `gpg.program`
-is used to specify custom GnuPG binary.
+A cryptographically signed tag object will be created when `-s` or
+`-u <key-id>` is used. The signing backend (GPG, X.509, SSH, etc.) is
+controlled by the `gpg.format` configuration variable, defaulting to
+OpenPGP. When `-u <key-id>` is not used, the committer identity for
+the current user is used to find the key for signing. The
+configuration variable `gpg.program` is used to specify a custom
+signing binary.
 
 Tag objects (created with `-a`, `-s`, or `-u`) are called "annotated"
 tags; they contain a creation date, the tagger name and e-mail, a
-tagging message, and an optional GnuPG signature. Whereas a
+tagging message, and an optional cryptographic signature. Whereas a
 "lightweight" tag is simply a name for an object (usually a commit
 object).
 
@@ -64,10 +66,12 @@ OPTIONS
 
 -s::
 --sign::
-       Make a GPG-signed tag, using the default e-mail address's key.
-       The default behavior of tag GPG-signing is controlled by `tag.gpgSign`
-       configuration variable if it exists, or disabled otherwise.
-       See linkgit:git-config[1].
+       Make a cryptographically signed tag, using the default signing
+       key. The signing backend used depends on the `gpg.format`
+       configuration variable. The default key is determined by the
+       backend. For GPG, it's based on the committer's email address,
+       while for SSH it may be a specific key file or agent
+       identity. See linkgit:git-config[1].
 
 --no-sign::
        Override `tag.gpgSign` configuration variable that is
@@ -75,7 +79,10 @@ OPTIONS
 
 -u <key-id>::
 --local-user=<key-id>::
-       Make a GPG-signed tag, using the given key.
+       Make a cryptographically signed tag using the given key. The
+       format of the <key-id> and the backend used depend on the
+       `gpg.format` configuration variable. See
+       linkgit:git-config[1].
 
 -f::
 --force::
@@ -87,7 +94,7 @@ OPTIONS
 
 -v::
 --verify::
-       Verify the GPG signature of the given tag names.
+       Verify the cryptographic signature of the given tags.
 
 -n<num>::
        <num> specifies how many lines from the annotation, if any,
@@ -236,12 +243,23 @@ it in the repository configuration as follows:
 
 -------------------------------------
 [user]
-    signingKey = <gpg-key-id>
+    signingKey = <key-id>
 -------------------------------------
 
+The signing backend can be chosen via the `gpg.format` configuration
+variable, which defaults to `openpgp`. See linkgit:git-config[1]
+for a list of other supported formats.
+
+The path to the program used for each signing backend can be specified
+with the `gpg.<format>.program` configuration variable. For the
+`openpgp` backend, `gpg.program` can be used as a synonym for
+`gpg.openpgp.program`. See linkgit:git-config[1] for details.
+
 `pager.tag` is only respected when listing tags, i.e., when `-l` is
 used or implied. The default is to use a pager.
-See linkgit:git-config[1].
+
+See linkgit:git-config[1] for more details and other configuration
+variables.
 
 DISCUSSION
 ----------