[PATCH 1/5] doc: git-tag: stop focussing on GPG signed tags

From: Christian Couder <christian.couder@gmail.com>
Date: Oct 7, 2025, 12:29 UTC
Message-ID: <20251007122958.1089680-2-christian.couder@gmail.com>
In-Reply-To: <20251007122958.1089680-1-christian.couder@gmail.com>

It looks like the documentation of `git tag` is focussed 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" 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.

Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
---
 Documentation/git-tag.adoc | 52 +++++++++++++++++++++++++-------------
 1 file changed, 35 insertions(+), 17 deletions(-)

diff --git a/Documentation/git-tag.adoc b/Documentation/git-tag.adoc
index a4b1c0ec05..9117754ffb 100644
--- 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,17 +38,18 @@ 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
-"lightweight" tag is simply a name for an object (usually a commit
-object).
+tagging message, and an optional signature. Whereas a "lightweight"
+tag is simply a name for an object (usually a commit object).
 
 Annotated tags are meant for release while lightweight tags are meant
 for private or temporary object labels. For this reason, some git
@@ -64,10 +65,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 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 +78,9 @@ OPTIONS
 
 -u <key-id>::
 --local-user=<key-id>::
-	Make a GPG-signed tag, using the given key.
+	Make a 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 +92,7 @@ OPTIONS
 
 -v::
 --verify::
-	Verify the GPG signature of the given tag names.
+	Verify the signature of the given tag names.
 
 -n<num>::
 	<num> specifies how many lines from the annotation, if any,
@@ -236,12 +241,25 @@ it in the repository configuration as follows:
 
 -------------------------------------
 [user]
-    signingKey = <gpg-key-id>
+    signingKey = <key-id>
 -------------------------------------
 
+The signing backend is controlled by the `gpg.format` configuration
+variable, which defaults to `openpgp` for GPG signing. To sign tags
+using other technologies like X.509 or SSH, set this variable to
+`x509` or `ssh` respectively.
+
+You can also specify the path to the signing program for each
+format. The `gpg.program` variable (or its synonym
+`gpg.openpgp.program`) is used for the OpenPGP backend. For other
+backends, the configuration is `gpg.<format>.program`, for example
+`gpg.ssh.program` for SSH signing.
+
 `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
 ----------

-- 
2.51.0.438.g6987fc0bae