From: Christian Couder Date: Mon, 13 Oct 2025 08:48:53 +0000 (+0200) Subject: doc: git-tag: stop focusing on GPG signed tags X-Git-Tag: v2.52.0-rc0~19^2~4 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=db674095c025870249c5e283ee9cacefad6a8fa9;p=thirdparty%2Fgit.git 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 ` 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 ` 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 Signed-off-by: Christian Couder Signed-off-by: Junio C Hamano --- diff --git a/Documentation/git-tag.adoc b/Documentation/git-tag.adoc index a4b1c0ec05..28d6fe4e1a 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 ` 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 -` is used. When `-u ` 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 ` is used. The signing backend (GPG, X.509, SSH, etc.) is +controlled by the `gpg.format` configuration variable, defaulting to +OpenPGP. When `-u ` 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 :: --local-user=:: - Make a GPG-signed tag, using the given key. + Make a cryptographically signed tag using the given key. The + format of the 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:: specifies how many lines from the annotation, if any, @@ -236,12 +243,23 @@ it in the repository configuration as follows: ------------------------------------- [user] - signingKey = + signingKey = ------------------------------------- +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..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 ----------