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

From: Patrick Steinhardt <[email-masked]>
Date: Wed, 8 Oct 2025 13:48:07 +0200

On Wed, Oct 08, 2025 at 11:52:44AM +0200, Christian Couder wrote:
> On Wed, Oct 8, 2025 at 11:21 AM Patrick Steinhardt <[email-masked]> 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
> > > @@ -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.

Yeah, I'm fine with referring to git-config(1). I mostly want to avoid
that we have N locations that we need to update every time something
changes here, as those are bound to become stale.

Maybe a solution would be to only point out the config keys without
going into much detail what the respective values are? In that case we
woulds imply refer to git-config(1) and call it a day.

Patrick