Git fork

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 <key-id>` 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 <key-id>` 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 <ps@pks.im>
Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

authored by

Christian Couder and committed by
Junio C Hamano
db674095 15eff6b7

+33 -15
+33 -15
Documentation/git-tag.adoc
··· 3 3 4 4 NAME 5 5 ---- 6 - git-tag - Create, list, delete or verify a tag object signed with GPG 6 + git-tag - Create, list, delete or verify tags 7 7 8 8 9 9 SYNOPSIS ··· 38 38 Otherwise, a tag reference that points directly at the given object 39 39 (i.e., a lightweight tag) is created. 40 40 41 - A GnuPG signed tag object will be created when `-s` or `-u 42 - <key-id>` is used. When `-u <key-id>` is not used, the 43 - committer identity for the current user is used to find the 44 - GnuPG key for signing. The configuration variable `gpg.program` 45 - is used to specify custom GnuPG binary. 41 + A cryptographically signed tag object will be created when `-s` or 42 + `-u <key-id>` is used. The signing backend (GPG, X.509, SSH, etc.) is 43 + controlled by the `gpg.format` configuration variable, defaulting to 44 + OpenPGP. When `-u <key-id>` is not used, the committer identity for 45 + the current user is used to find the key for signing. The 46 + configuration variable `gpg.program` is used to specify a custom 47 + signing binary. 46 48 47 49 Tag objects (created with `-a`, `-s`, or `-u`) are called "annotated" 48 50 tags; they contain a creation date, the tagger name and e-mail, a 49 - tagging message, and an optional GnuPG signature. Whereas a 51 + tagging message, and an optional cryptographic signature. Whereas a 50 52 "lightweight" tag is simply a name for an object (usually a commit 51 53 object). 52 54 ··· 64 66 65 67 -s:: 66 68 --sign:: 67 - Make a GPG-signed tag, using the default e-mail address's key. 68 - The default behavior of tag GPG-signing is controlled by `tag.gpgSign` 69 - configuration variable if it exists, or disabled otherwise. 70 - See linkgit:git-config[1]. 69 + Make a cryptographically signed tag, using the default signing 70 + key. The signing backend used depends on the `gpg.format` 71 + configuration variable. The default key is determined by the 72 + backend. For GPG, it's based on the committer's email address, 73 + while for SSH it may be a specific key file or agent 74 + identity. See linkgit:git-config[1]. 71 75 72 76 --no-sign:: 73 77 Override `tag.gpgSign` configuration variable that is ··· 75 79 76 80 -u <key-id>:: 77 81 --local-user=<key-id>:: 78 - Make a GPG-signed tag, using the given key. 82 + Make a cryptographically signed tag using the given key. The 83 + format of the <key-id> and the backend used depend on the 84 + `gpg.format` configuration variable. See 85 + linkgit:git-config[1]. 79 86 80 87 -f:: 81 88 --force:: ··· 87 94 88 95 -v:: 89 96 --verify:: 90 - Verify the GPG signature of the given tag names. 97 + Verify the cryptographic signature of the given tags. 91 98 92 99 -n<num>:: 93 100 <num> specifies how many lines from the annotation, if any, ··· 236 243 237 244 ------------------------------------- 238 245 [user] 239 - signingKey = <gpg-key-id> 246 + signingKey = <key-id> 240 247 ------------------------------------- 241 248 249 + The signing backend can be chosen via the `gpg.format` configuration 250 + variable, which defaults to `openpgp`. See linkgit:git-config[1] 251 + for a list of other supported formats. 252 + 253 + The path to the program used for each signing backend can be specified 254 + with the `gpg.<format>.program` configuration variable. For the 255 + `openpgp` backend, `gpg.program` can be used as a synonym for 256 + `gpg.openpgp.program`. See linkgit:git-config[1] for details. 257 + 242 258 `pager.tag` is only respected when listing tags, i.e., when `-l` is 243 259 used or implied. The default is to use a pager. 244 - See linkgit:git-config[1]. 260 + 261 + See linkgit:git-config[1] for more details and other configuration 262 + variables. 245 263 246 264 DISCUSSION 247 265 ----------