From: Christian Couder <christian.couder@gmail•com>
To: git@vger•kernel.org
Cc: Junio C Hamano <gitster@pobox•com>,
Patrick Steinhardt <ps@pks•im>, Elijah Newren <newren@gmail•com>,
Jeff King <peff@peff•net>,
"brian m . carlson" <sandals@crustytoothpaste•net>,
Johannes Schindelin <Johannes.Schindelin@gmx•de>,
Todd Zullinger <tmz@pobox•com>,
Collin Funk <collin.funk1@gmail•com>,
Christian Couder <christian.couder@gmail•com>,
Christian Couder <chriscool@tuxfamily•org>
Subject: [PATCH v2 1/5] doc: git-tag: stop focusing on GPG signed tags
Date: Thu, 9 Oct 2025 14:24:53 +0200 [thread overview]
Message-ID: <20251009122457.1273701-2-christian.couder@gmail.com> (raw)
In-Reply-To: <20251009122457.1273701-1-christian.couder@gmail.com>
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>
---
Documentation/git-tag.adoc | 48 ++++++++++++++++++++++++++------------
1 file changed, 33 insertions(+), 15 deletions(-)
diff --git a/Documentation/git-tag.adoc b/Documentation/git-tag.adoc
index a4b1c0ec05..3519e5b9b2 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,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 signature of the given tag names.
-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
----------
--
2.51.0.438.g6987fc0bae
next prev parent reply other threads:[~2025-10-09 12:25 UTC|newest]
Thread overview: 52+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-10-07 12:29 [PATCH 0/5] fast-import: start controlling how tag signatures are handled Christian Couder
2025-10-07 12:29 ` [PATCH 1/5] doc: git-tag: stop focussing on GPG signed tags Christian Couder
2025-10-08 7:14 ` Patrick Steinhardt
2025-10-08 9:52 ` Christian Couder
2025-10-08 11:48 ` Patrick Steinhardt
2025-10-07 12:29 ` [PATCH 2/5] lib-gpg: allow tests with the GPGSM prereq first Christian Couder
2025-10-08 7:14 ` Patrick Steinhardt
2025-10-08 9:42 ` Christian Couder
2025-10-09 1:29 ` Collin Funk
2025-10-09 2:37 ` Todd Zullinger
2025-10-09 12:29 ` Christian Couder
2025-10-09 18:18 ` Junio C Hamano
2025-10-09 12:30 ` Christian Couder
2025-10-07 12:29 ` [PATCH 3/5] t9350: properly count annotated tags Christian Couder
2025-10-08 7:14 ` Patrick Steinhardt
2025-10-08 10:00 ` Christian Couder
2025-10-07 12:29 ` [PATCH 4/5] fast-export: handle all kinds of tag signatures Christian Couder
2025-10-08 7:14 ` Patrick Steinhardt
2025-10-08 10:02 ` Christian Couder
2025-10-09 12:33 ` Christian Couder
2025-10-07 12:29 ` [PATCH 5/5] fast-import: add '--signed-tags=<mode>' option Christian Couder
2025-10-08 7:14 ` Patrick Steinhardt
2025-10-08 10:50 ` Christian Couder
2025-10-08 11:53 ` Patrick Steinhardt
2025-10-09 12:24 ` [PATCH v2 0/5] fast-import: start controlling how tag signatures are handled Christian Couder
2025-10-09 12:24 ` Christian Couder [this message]
2025-10-10 1:19 ` [PATCH v2 1/5] doc: git-tag: stop focusing on GPG signed tags Junio C Hamano
2025-10-10 7:06 ` Christian Couder
2025-10-09 12:24 ` [PATCH v2 2/5] lib-gpg: allow tests with GPGSM or GPGSSH prereq first Christian Couder
2025-10-10 6:49 ` Patrick Steinhardt
2025-10-10 14:09 ` Todd Zullinger
2025-10-10 16:22 ` Junio C Hamano
2025-10-11 2:14 ` Todd Zullinger
2025-10-12 0:15 ` Junio C Hamano
2025-10-09 12:24 ` [PATCH v2 3/5] t9350: properly count annotated tags Christian Couder
2025-10-09 12:24 ` [PATCH v2 4/5] fast-export: handle all kinds of tag signatures Christian Couder
2025-10-09 12:24 ` [PATCH v2 5/5] fast-import: add '--signed-tags=<mode>' option Christian Couder
2025-10-09 21:35 ` [PATCH v2 0/5] fast-import: start controlling how tag signatures are handled Junio C Hamano
2025-10-13 8:48 ` [PATCH v3 " Christian Couder
2025-10-13 8:48 ` [PATCH v3 1/5] doc: git-tag: stop focusing on GPG signed tags Christian Couder
2025-10-24 2:03 ` Elijah Newren
2025-10-13 8:48 ` [PATCH v3 2/5] lib-gpg: allow tests with GPGSM or GPGSSH prereq first Christian Couder
2025-10-13 8:48 ` [PATCH v3 3/5] t9350: properly count annotated tags Christian Couder
2025-10-24 2:03 ` Elijah Newren
2025-10-13 8:48 ` [PATCH v3 4/5] fast-export: handle all kinds of tag signatures Christian Couder
2025-10-24 2:03 ` Elijah Newren
2025-10-13 8:48 ` [PATCH v3 5/5] fast-import: add '--signed-tags=<mode>' option Christian Couder
2025-10-24 2:03 ` Elijah Newren
2025-10-24 9:27 ` Christian Couder
2025-10-24 15:03 ` Junio C Hamano
2025-10-13 9:09 ` [PATCH v3 0/5] fast-import: start controlling how tag signatures are handled Christian Couder
2025-10-24 2:06 ` Elijah Newren
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20251009122457.1273701-2-christian.couder@gmail.com \
--to=christian.couder@gmail$(echo .)com \
--cc=Johannes.Schindelin@gmx$(echo .)de \
--cc=chriscool@tuxfamily$(echo .)org \
--cc=collin.funk1@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitster@pobox$(echo .)com \
--cc=newren@gmail$(echo .)com \
--cc=peff@peff$(echo .)net \
--cc=ps@pks$(echo .)im \
--cc=sandals@crustytoothpaste$(echo .)net \
--cc=tmz@pobox$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox