From: Patrick Steinhardt <ps@pks.im>
Date: Wed, 08 Oct 2025 07:14:12 GMT
Subject: Re: [PATCH 1/5] doc: git-tag: stop focussing on GPG signed tags
Message-ID: <aOYPRKoexRtYUDsh@pks.im>
In-Reply-To: <20251007122958.1089680-2-christian.couder@gmail.com>

On Tue, Oct 07, 2025 at 02:29:54PM +0200, Christian Couder wrote:
> 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

This is an obvious improvement.

> @@ -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"

Nit: let's rather say "cryptographic signature" here.

> +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

Same here, let's say "cryptographically signed tag".

> @@ -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

Same.

> +	<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.

Same.

> @@ -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.
> +

It might make sense to use a bulleted list here to list the different
available formats. On the other hand, we could just as well refer to
git-config(1) so that we don't have to repeat any of the information
here, but instead have it at a central place.

That might not be worth it though. In the end there aren't too many
different commands that write signed objects.

Overall this change makes a lot of sense to me, thanks!

Patrick