简体中文 ▾ 主题 ▾ 最新版本 ▾ git-tag 最后更新于 2.52.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>]

指定一个（<token>, <value>）对，该对将作为尾部添加。（例如，git tag --trailer "Custom-Key: value" 将向标签消息添加一个“Custom-Key”尾部。） trailer.* 配置变量（git-interpret-trailers[1]）可用于定义是否省略重复的尾部、每个尾部在尾部序列中的位置以及其他细节。尾部可以在 git tag --list 中提取，使用 --format="%(trailers)" 占位符。

-e
--edit

允许进一步编辑通过 -F 从文件和通过命令行 -m 获取的消息。

--cleanup=<mode>

设置如何清理标签消息。<mode> 可以是 verbatim、whitespace 和 strip 之一。strip 模式是默认的。verbatim 模式不更改消息，whitespace 仅删除前导/尾随空白行，而 strip 删除空白行和注释。

--create-reflog

为标签创建 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。

配置

默认情况下，git tag 在签名默认模式（-s）下会使用您的提交者身份（形式为 Your Name <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] 获取详细信息。

pager.tag 仅在列出标签时（即使用或隐含 -l 时）生效。默认使用分页器。

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

讨论

关于重新打标签

当您错误地打了一个标签，并想重新打标签时，您应该怎么做？

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

但是，如果您已推送内容（或其他人可以直接读取您的存储库），那么其他人将已经看到旧标签。在这种情况下，您可以执行以下两项操作之一：

  1. 明智的做法。承认您搞砸了，然后使用不同的名称。其他人已经看到一个标签名称，如果您保留相同的名称，您可能会遇到这种情况：两个人都有“版本 X”，但他们实际上拥有*不同的*“X”。所以只需称之为“X.1”即可。

  2. 愚蠢的做法。您确实想将新版本也称为“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）。您通常需要来自对方的标签。

另一方面，如果您正在获取，因为您想要一个一次性的合并，您通常不希望从中获取标签。这种情况更多发生在接近顶层的人身上，但不仅限于他们。普通人在互相拉取时，不一定希望自动获取对方的私有锚点标签。

通常，邮件列表上的“请拉取”消息只提供两个信息：一个存储库 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 的一个重要方面是其分布式特性，这意味着系统中不存在固有的“上游”或“下游”。表面上看，上面的例子可能表明标签命名空间由高层人士拥有，并且标签只向下流动，但事实并非如此。它只表明使用模式决定了谁对谁的标签感兴趣。

一次性拉取是提交历史现在正在跨越一个圈子的人（例如，“主要对内核网络部分感兴趣的人”）到另一个圈子的人（例如，“整合各种子系统改进的人”）的边界的标志。后者通常对前者组内部使用的详细标签不感兴趣（这就是“内部”的含义）。这就是为什么在这种情况下不希望自动跟随标签。

也许网络领域的人员希望交换他们内部的标签，但在那种工作流程中，他们很可能通过远程跟踪分支来跟踪彼此的进度。再次，自动跟随此类标签的启发式方法是件好事。

关于回溯标签

如果您从其他 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。

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

Git[1] 套件的一部分