English ▾ 主题 ▾ 最新版本 ▾ git-tag 上次更新于 2.46.0

名称

git-tag - 创建、列出、删除或验证用 GPG 签名的标签对象

概要

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> 之一，该命令将创建一个标签对象，并且需要标签消息。 除非指定 -m <msg> 或 -F <file>，否则将启动编辑器供用户键入标签消息。

如果指定了 -m <msg> 或 -F <file> 或 --trailer <token>[=<value>] 并且缺少 -a、-s 和 -u <key-id>，则会假定 -a。

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

当使用 -s 或 -u <key-id> 时，将创建一个 GnuPG 签名标签对象。 当未使用 -u <key-id> 时，当前用户的提交者身份将用于查找用于签名的 GnuPG 密钥。 配置变量 gpg.program 用于指定自定义 GnuPG 二进制文件。

使用 -a、-s 或 -u 创建的标签对象称为“带注释的”标签；它们包含创建日期、标签者姓名和电子邮件、标签消息以及可选的 GnuPG 签名。 而“轻量级”标签只是对象的名称（通常是提交对象）。

带注释的标签用于发布，而轻量级标签用于私有或临时对象标签。 因此，某些用于命名对象的 git 命令（例如 git describe）默认情况下会忽略轻量级标签。

选项

-a
--annotate

创建未签名的带注释的标签对象

-s
--sign

使用默认电子邮件地址的密钥创建一个 GPG 签名标签。 如果存在 tag.gpgSign 配置变量，则标签 GPG 签名的默认行为由该变量控制，否则禁用。 请参阅 git-config[1]。

--no-sign

覆盖设置为强制每个标签都进行签名的 tag.gpgSign 配置变量。

-u <key-id>
--local-user=<key-id>

使用给定的密钥创建一个 GPG 签名标签。

-f
--force

用给定的名称替换现有标签（而不是失败）

-d
--delete

删除具有给定名称的现有标签。

-v
--verify

验证给定标签名称的 GPG 签名。

-n<num>

<num> 指定在使用 -l 时，如果存在注释，则打印注释中的多少行。 暗示 --list。

默认情况下不打印任何注释行。 如果没有给 -n 提供数字，则仅打印第一行。 如果标签未注释，则显示提交消息。

-l
--list

列出标签。 使用可选的 <pattern>...，例如 git tag --list 'v-*'，仅列出与模式匹配的标签。

不带参数运行“git tag”也会列出所有标签。 该模式是 shell 通配符（即，使用 fnmatch(3) 匹配）。 可以给出多个模式； 如果任何一个匹配，则显示该标签。

如果提供了任何其他类似列表的选项（例如 --contains），则此选项是隐式提供的。 有关详细信息，请参阅每个选项的文档。

--sort=<key>

基于给定的键进行排序。 添加前缀 - 以按值的降序排序。 您可以多次使用 --sort=<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>]

仅列出包含指定提交的标签（如果未指定，则为 HEAD）。 暗示 --list。

--no-contains [<commit>]

仅列出不包含指定提交的标签（如果未指定，则为 HEAD）。 暗示 --list。

--merged [<commit>]

仅列出其提交可以从指定提交（如果未指定，则为 HEAD）访问的标签。

--no-merged [<commit>]

仅列出其提交无法从指定提交（如果未指定，则为 HEAD）访问的标签。

--points-at <object>

仅列出给定对象的标签（如果未指定，则为 HEAD）。 暗示 --list。

-m <msg>
--message=<msg>

使用给定的标签消息（而不是提示）。 如果给出了多个 -m 选项，则它们的值将连接为单独的段落。 如果未给出 -a、-s 或 -u <key-id> 中的任何一个，则暗示 -a。

-F <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]) 来定义是否省略重复的预告片，每个预告片在预告片运行中出现的位置以及其他详细信息。 可以使用 --format="%(trailers)" 占位符在 git tag --list 中提取预告片。

-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>

新标签将引用的对象，通常是一个 commit。 默认为 HEAD。

配置

默认情况下，以签名-使用-默认模式 (-s) 使用 *git tag* 将使用您的提交者身份（形式为 您的名字 <your@email.address>）来查找密钥。 如果您想使用其他默认密钥，您可以在存储库配置中指定它，如下所示

[user]
    signingKey = <gpg-key-id>

仅在列出标签时才遵循 pager.tag，即使用 -l 或暗示使用时。 默认是使用分页器。 请参阅 git-config[1]。

讨论

关于重新标记

当您标记了一个错误的 commit 并且想要重新标记时，您应该怎么做？

如果您从未推送任何东西，只需重新标记即可。 使用“-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 的一个重要方面是其分布式特性，这在很大程度上意味着系统中没有固有的“上游”或“下游”。 从表面上看，上面的例子似乎表明标签命名空间归属于上层人员，并且标签仅向下流动，但事实并非如此。 它仅表明使用模式决定了谁对谁的标签感兴趣。

一次性拉取表明提交历史记录现在正在跨越一群人（例如“主要对内核的网络部分感兴趣的人”）和另一群人（例如“集成各种子系统改进的人”）之间的边界。前者可能拥有自己的一组标签（例如“这是网络组提出的用于 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。

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 覆盖。

笔记

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

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

另请参阅

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

GIT

属于 git[1] 套件的一部分

scroll-to-top