From: Elijah Newren Date: Fri, 24 Oct 2025 02:03:08 GMT Subject: Re: [PATCH v3 1/5] doc: git-tag: stop focusing on GPG signed tags Message-ID: In-Reply-To: <20251013084857.1646783-2-christian.couder@gmail.com> On Mon, Oct 13, 2025 at 4:49 AM Christian Couder wrote: > > 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 > --- > 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..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 > ---------- > -- > 2.51.0.438.g6987fc0bae Looks like some nice clarifications & corrections.