From: Christian Couder <christian.couder@gmail.com>
Date: Wed, 08 Oct 2025 09:52:44 GMT
Subject: Re: [PATCH 1/5] doc: git-tag: stop focussing on GPG signed tags
Message-ID: <CAP8UFD0UJt+L9Ri4VyWJ-1M4Si2q=i5xG_=a315G9m1NFvXnQA@mail.gmail.com>
In-Reply-To: <aOYPRKoexRtYUDsh@pks.im>

On Wed, Oct 8, 2025 at 11:21 AM Patrick Steinhardt <ps@pks.im> wrote:
>
> 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.

[...]

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

OK, I will make this change in V2.

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

It's a bit cumbersome to have to say "cryptographic" or
"cryptographically" everywhere though. Maybe saying it a few times at
the beginning is enough?

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

What should we say about each format though?

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

I think this CONFIGURATION section should talk only briefly about the
most important config options and refer to the git-config(1) doc for
details and less important config options. So I am not sure what you
suggest exactly about this.

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

Thanks.