Git

git-tag 最新更新于 2.55.0

名称

git-tag - 创建、列出、删除或验证标签

概要

git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]
	[(--trailer <token>[(=|:)<value>])…]
	<tagname> [<commit> | <object>]
git tag -d <tagname>…
git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]
	[--points-at <object>] [--column[=<options>] | --no-column]
	[--create-reflog] [--sort=<key>] [--format=<format>]
	[--merged <commit>] [--no-merged <commit>] [<pattern>…]
git tag -v [--format=<format>] <tagname>…

描述

在 refs/tags/ 中添加一个标签引用，除非提供了 -d/-l/-v 来删除、列出或验证标签。

除非指定了 -f，否则指定的标签名必须尚不存在。

如果传递了 -a、-s 或 -u <key-id> 之一，该命令会创建一个 tag（标签）对象，并且需要一条标签信息。除非指定了 -m <msg> 或 -F <file>，否则会启动一个编辑器供用户输入标签信息。

如果指定了 -m <msg>、-F <file> 或 --trailer <token>[=<value>]，且未指定 -a、-s 和 -u <key-id>，则隐式启用 -a。

否则，将创建一个直接指向给定对象（即轻量标签）的标签引用。

当使用 -s 或 -u <key-id> 时，将创建一个加密签名的标签对象。签名后端（GPG、X.509、SSH 等）受 gpg.format 配置变量控制，默认为 OpenPGP。未使用 -u <key-id> 时，使用当前用户的提交者身份来查找签名密钥。配置变量 gpg.program 用于指定自定义签名二进制文件。

标签对象（通过 -a、-s 或 -u 创建）被称为“附注”标签；它们包含创建日期、标签创建者的姓名和电子邮件、一条标签信息以及一个可选的加密签名。而“轻量”标签仅仅是一个对象的名称（通常是一个提交对象）。

附注标签用于发布，而轻量标签用于私人或临时对象标签。因此，某些用于命名对象的 git 命令（如 git describe）默认会忽略轻量标签。

选项

-a
--annotate: 创建一个未签名的附注标签对象
-s
--sign: 使用默认签名密钥创建加密签名的标签。使用的签名后端取决于 gpg.format 配置变量。默认密钥由后端决定。对于 GPG，它基于提交者的电子邮件地址，而对于 SSH，它可能是特定的密钥文件或代理身份。参见 git-config[1]。
--no-sign: 覆盖设置为强制对每个标签进行签名的 tag.gpgSign 配置变量。
-u <key-id>
--local-user=<key-id>: 使用给定的密钥制作加密签名的标签。<key-id> 的格式和使用的后端取决于 gpg.format 配置变量。参见 git-config[1]。
-f
--force: 替换已存在的同名标签（而不是报错失败）
-d
--delete: 删除具有给定名称的现有标签。
-v
--verify: 验证给定标签的加密签名。
-n<num>: <num> 指定在使用 -l 时打印附注的行数（如果有）。隐式启用 --list。

默认不打印任何附注行。如果没有为 -n 指定数字，则仅打印第一行。如果标签未附注，则显示提交信息。
-l
--list: 列出标签。配合可选的 <pattern>...（例如 git tag --list v-*'），仅列出与模式匹配的标签。

在不带参数的情况下运行 git tag 也会列出所有标签。该模式是 shell 通配符（即使用 fnmatch(3) 进行匹配）。可以指定多个模式；如果其中任何一个匹配，则显示该标签。

如果提供了任何其他类似列表的选项（如 --contains），则会隐式提供此选项。详情请参阅这些选项各自的文档。
--sort=<key>: 根据给定的键进行排序。前缀 - 表示按值的降序排序。您可以多次使用 --sort=<key> 选项，在这种情况下，最后一个 <key> 将成为主键。还支持“version:refname”或“v:refname”（标签名被视为版本）。“version:refname”排序顺序也可能受到“versionsort.suffix”配置变量的影响。支持的键与 git for-each-ref 中的相同。排序顺序默认采用为 tag.sort 变量配置的值（如果存在），否则采用字典顺序。参见 git-config[1]。
--color[=<when>]: 遵守 --format 选项中指定的颜色。<when> 字段必须是 always、never 或 auto 之一（如果未提供 <when>，则表现为如同指定了 always）。
-i
--ignore-case: 对标签进行排序和过滤时不区分大小写。
--omit-empty: 在格式化引用中，如果格式扩展为空字符串，则不在其后打印换行符。
--column[=<options>]
--no-column: 以列的形式显示标签列表。有关选项语法，请参阅配置变量 column.tag。不带选项的 --column 和 --no-column 分别相当于 always 和 never。

此选项仅适用于在没有附注行的情况下列出标签。
--contains [<commit>]: 仅列出包含 <commit> 的标签（如果未指定，则默认为 HEAD）。隐式启用 --list。
--no-contains [<commit>]: 仅列出不包含 <commit> 的标签（如果未指定，则默认为 HEAD）。隐式启用 --list。
--merged [<commit>]: 仅列出其提交可从 <commit> 可达的标签（如果未指定，则默认为 HEAD）。
--no-merged [<commit>]: 仅列出其提交从 <commit> 不可达的标签（如果未指定，则默认为 HEAD）。
--points-at [<object>]: 仅列出指向 <object> 的标签（如果未指定，则默认为 HEAD）。隐式启用 --list。
-m <msg>
--message=<msg>: 使用 <msg>（而不是提示输入）。如果给出了多个 -m 选项，它们的值将合并为独立的段落。如果未给出 -a、-s 或 -u <key-id> 中的任何一个，则隐式启用 -a。
-F <file>
--file=<file>: 从 <file> 中获取标签信息。使用 - 从标准输入中读取标签信息。如果未给出 -a、-s 或 -u <key-id> 中的任何一个，则隐式启用 -a。
--trailer <token>[(=|:)<value>]: 指定一个应用作尾注（trailer）的 (<token>, <value>) 键值对。（例如，git tag --trailer "Custom-Key: value" 会将 "Custom-Key" 尾注添加到标签信息中。）trailer.* 配置变量（git-interpret-trailers[1]）可用于定义是否省略重复的尾注、每个尾注在尾注序列中的出现位置以及其他细节。可以使用 --format="%(trailers)" 占位符在 git tag --list 中提取尾注。
-e
--edit: 允许进一步编辑使用 -F 从文件中获取或使用 -m 从命令行提供的信息。
--cleanup=<mode>: 设置如何清理标签信息。<mode> 可以是 verbatim（逐字）、whitespace（空白字符）和 strip（去除）之一。strip 模式为默认设置。verbatim 模式完全不改变信息，whitespace 仅删除开头/结尾的空白行，而 strip 则会同时删除空白行和注释。
--create-reflog: 为标签创建引用日志（reflog）。若要在全局启用标签的引用日志，请参见 git-config[1] 中的 core.logAllRefUpdates。否定形式 --no-create-reflog 仅会覆盖先前的 --create-reflog，但目前不会否定 core.logAllRefUpdates 的设置。
--format=<format>: 一个字符串，用于从正在显示的标签引用及其指向的对象中插入 %(fieldname)。格式与 git-for-each-ref[1] 相同。未指定时，默认值为 %(refname:strip=2)。
<tagname>: 要创建、删除或描述的标签名称。新标签名称必须通过 git-check-ref-format[1] 定义的所有检查。其中某些检查可能会限制标签名称中允许的字符。
<commit>
<object>: 新标签将指向的对象，通常是一个提交。默认为 HEAD。

配置

默认情况下，处于默认签名模式（-s）下的 git tag 将使用您的提交者身份（格式为 您的姓名 <your@email.address>）来查找密钥。如果您想使用不同的默认密钥，可以在仓库配置中进行如下指定

[user]
    signingKey = <key-id>

可以通过 gpg.format 配置变量来选择签名后端，该变量默认为 openpgp。请参见 git-config[1] 以获取其他受支持格式的列表。

可以使用 gpg.<format>.program 配置变量指定用于每个签名后端的程序路径。对于 openpgp 后端，gpg.program 可以用作 gpg.openpgp.program 的同义词。有关详细信息，请参阅 git-config[1]。

仅在列出标签时（即使用或隐式启用 -l 时）才会遵守 pager.tag。默认是使用分页器。

有关更多详细信息和其他配置变量，请参阅 git-config[1]。

讨论

关于重新打标签

当您标记了错误的提交并希望重新标记时，您应该怎么做？

如果您从未推送过任何内容，只需重新打标签即可。使用 -f 替换旧标签。这样就完成了。

但如果您已经推送了内容（或者其他人可以直接读取您的仓库），那么其他人就已经看到了旧标签。在这种情况下，您可以选择以下两种做法之一

理智的做法。承认自己搞砸了，并使用一个不同的名称。其他人已经看到了这个标签名，如果您坚持使用相同的名称，可能会出现两个人都有“版本 X”，但他们实际拥有的 “X” 却*不同*的情况。因此，直接将其命名为“X.1”即可。
疯狂的做法。*即使*其他人已经看到了旧版本，您也确实想将新版本命名为“X”。因此，只需再次使用 git tag -f，就像您还没有发布旧版本一样。

然而，Git **不会**（也不应该）背着用户更改标签。因此，如果有人已经获取了旧标签，在您的树上执行 git pull 不应该直接覆盖他们的旧标签。

如果有人从您那里获取了发布标签，您不能仅通过更新自己的标签来为他们更改该标签。这是一个很大的安全问题，因为人们必须能够信任他们的标签名称。如果您真的想做疯狂的事，就需要承认这一点，并告诉大家您搞砸了。您可以通过发表非常公开的声明来做到这一点，声明内容如下：

Ok, I messed up, and I pushed out an earlier version tagged as X. I
then fixed something, and retagged the *fixed* tree as X again.

If you got the wrong tag, and want the new one, please delete
the old one and fetch the new one by doing:

	git tag -d X
	git fetch origin tag X

to get my updated tag.

You can test which tag you have by doing

	git rev-parse X

which should return 0123456789abcdef.. if you have the new version.

Sorry for the inconvenience.

这看起来有点复杂吗？它**本来就应该**这样。自动去“修复”它绝对是不正确的。人们需要知道他们的标签可能已被更改。

关于自动跟从

如果您正在跟从别人的树，您很可能使用的是远程跟踪分支（例如 refs/remotes/origin/master）。您通常会希望获取另一端的标签。

另一方面，如果您进行获取（fetch）是因为您想要与别人的代码进行一次性合并，您通常不希望获取那里的标签。这种情况在接近顶层开发的人群中发生得更频繁，但不仅限于他们。普通人在相互拉取（pull）时，并不一定希望自动获取对方的私有锚点标签。

通常，邮件列表上的“please pull”（请拉取）信息只提供两部分信息：仓库 URL 和分支名称；这旨在方便剪切和粘贴到 git fetch 命令行末尾

Linus, please pull from

	git://git..../proj.git master

to get the following updates...

变成

$ git pull git://git..../proj.git master

在这种情况下，您不希望自动跟从对方的标签。

Git 的一个重要方面在于其分布式特性，这很大程度上意味着系统中没有固有的“上游”或“下游”。从表面上看，上述例子似乎表明标签命名空间归上层人群所有，且标签仅向下流，但事实并非如此。它只说明了使用模式决定了谁对谁的标签感兴趣。

一次性拉取（one-shot pull）表明，提交历史现在正跨越两个圈子的界限：一个圈子（例如“主要对内核网络部分感兴趣的人”）可能拥有自己的一套标签（例如“这是网络组提议在 2.6.21 版本中供通用消费的第三个发布候选版”），另一个圈子（例如“集成各种子系统改进的人”）。后者通常对前者内部使用的详细标签不感兴趣（这就是“内部”的意思）。这就是为什么在这种情况下最好不要自动跟从标签。

在网络组人员中，他们可能确实希望交换其组内的内部标签，但在该工作流中，他们很可能通过远程跟踪分支来跟踪彼此的进展。同样，自动跟从这些标签的启发式机制是一件好事。

关于回溯标签日期

如果您从其他版本控制系统（VCS）导入了一些更改，并希望为您工作的重要发布版本添加标签，那么能够指定要嵌入标签对象内部的日期会非常有用；标签对象中的此类数据会影响（例如）gitweb 界面中标签的排序。

若要设置未来标签对象中使用的日期，请设置环境变量 GIT_COMMITTER_DATE（参见后面对可能值的讨论；最常见的格式为 "YYYY-MM-DD HH:MM"）。

例如

$ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1

日期格式

GIT_AUTHOR_DATE 和 GIT_COMMITTER_DATE 环境变量支持以下日期格式：

Git 内部格式

格式为 <unix-timestamp> <time-zone-offset>，其中 <unix-timestamp> 是自 UNIX 纪元以来的秒数。<time-zone-offset> 是相对于 UTC 的正或负偏移量。例如，CET（比 UTC 早 1 小时）是 +0100。

在 <unix 时间戳> 前面加上 @（例如，@0 +0000）会更安全，这会强制 Git 将其解释为原始时间戳。对于小于 100,000,000 的值（不足 9 位数字），这是必需的，以避免与其他日期格式（如 YYYYMMDD）混淆。

RFC 2822

RFC 2822 所描述的标准日期格式，例如 Thu, 07 Apr 2005 22:13:13 +0200。

ISO 8601

由 ISO 8601 标准指定的日期和时间，例如 2005-04-07T22:13:13。解析器也接受用空格代替 T 字符。小数秒将被忽略，例如 2005-04-07T22:13:13.019 将被视为 2005-04-07T22:13:13。

注意	此外，日期部分支持以下格式：`YYYY.MM.DD`、`MM/DD/YYYY` 和 `DD.MM.YYYY`。

文件

$GIT_DIR/TAG_EDITMSG: 该文件包含正在编辑的附注标签的信息。如果 git tag 在创建附注标签之前因错误退出，则用户在编辑器会话中提供的标签信息将保存在此文件中，但可能会被下一次调用 git tag 时覆盖。

配置

本节中以下所有内容均从 git-config[1] 文档中选择性地包含。内容与彼处相同：

tag.forceSignAnnotated: 一个布尔值，用于指定创建的附注标签是否应进行 GPG 签名。如果在命令行中指定了 --annotate，则其优先级高于此选项。
tag.sort: 此变量控制 git-tag 显示标签时的排序顺序。在未提供 --sort=<value> 选项时，将使用此变量的值作为默认值。
tag.gpgSign: 一个布尔值，用于指定是否应进行 GPG 签名。在自动化脚本中运行此选项时，可能会导致大量标签被签名。因此，使用代理以避免多次输入 GPG 密码会更方便。请注意，此选项不会影响由 -u <keyid> 或 --local-user=<keyid> 选项启用的标签签名行为。

注意事项

当组合多个 --contains 和 --no-contains 过滤器时，仅显示至少包含一个 --contains 提交且不包含任何 --no-contains 提交的引用。

当组合多个 --merged 和 --no-merged 过滤器时，仅显示至少一个 --merged 提交可达且不被任何 --no-merged 提交可达的引用。

另请参阅

git-check-ref-format[1]. git-config[1].

Git[1] 套件的一部分

设置和配置

获取和创建项目

基本快照

分支与合并

共享和更新项目

检查和比较

打补丁

调试

电子邮件

外部系统

服务器管理

指南

管理

底层命令

名称

概要

描述

选项

配置

讨论