简体中文 ▾ Topics ▾ Latest version ▾ git-tag last updated in 2.52.0

名称

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

概述

git tag' [-a | -s | -u <密钥ID>] [-f] [-m <信息> | -F <文件>] [-e]
	[(--trailer <标签>[(=|:)<值>])…​]
	<标签名> [<提交> | <对象>]
git tag' -d <标签名>…​
git tag' [-n[<数字>]] -l [--contains <提交>] [--no-contains <提交>]
	[--points-at <对象>] [--column[=<选项>] | --no-column]
	[--create-reflog] [--sort=<键>] [--format=<格式>]
	[--merged <提交>] [--no-merged <提交>] [<模式>…​]
git tag' -v [--format=<format>] <标签名>…​

描述

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

除非给出`-f`，否则命名的标签必须还不存在。

如果传递了 -a、 -s 或 -u <key-id>`中的一个，该命令会创建一个 '标签' 对象，并要求提供一个标签信息。 除非给出-m <信息>或-F <文件>`，否则会启动一个编辑器，让用户输入标签信息。

如果给定了`-m <消息>或-F <文件>，并且没有-a`、-s`和-u <键-id>，则默认为-a`。

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

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

标签对象（用`-a`、-s`或-u`创建）被称为 "注释 "标签；它们包含创建日期、标签者姓名和电子邮件、标签信息和可选的GnuPG签名。而 "轻量级 "标签只是一个对象（通常是一个提交对象）的名称。

注释性标签是用来发布的，而轻量级标签则是用于私人或临时对象的标签。由于这个原因，一些命名对象的git命令（如`git describe`）默认会忽略轻量级标签。

选项

-a
--annotate

制作一个无符号、有注释的标签对象

-s
--sign

使用默认签名密钥创建一个带加密签名的标签。所用签名后端取决于 gpg.format 配置变量。默认密钥由后端决定。对 GPG 来说，它基于提交者的电子邮件地址；对 SSH 来说，则可能是特定密钥文件或代理身份。详见 git-config[1]。

--no-sign

覆盖`tag.gpgSign`配置变量，该变量被设置为强制每一个标签都被签名。

-u <键 ID>
--local-user=<键 ID>

使用给定密钥创建一个带加密签名的标签。<key-id> 的格式以及所用后端取决于 gpg.format 配置变量。详见 git-config[1]。

-f
--force

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

-d
--delete

删除给定名字的现存标签。

-v
--verify

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

-l<数量>

<数字>指定在使用-l时打印多少行注释，-l 是指 --list。

默认是不打印任何注释行。 如果没有给 -n 加上数字，则只打印第一行。 如果标签没有注释，则会显示提交信息。

-l
--list

列出标签。使用可选的`<模式>…​，例如`git tag --list 'v-*'，只列出符合模式的标签。

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

如果提供任何其他类似列表的选项，如`--contains`，则隐含地提供该选项。详情请参见这些选项的文档。

--sort=<键>

根据给定的键进行排序。 前缀 - 表示按照数值的降序排序。你可以多次使用 --sort=<键> 选项，在这种情况下，最后一个键成为主键。也支持 version:refname 或 v:refname（标签名被视为版本）。version:refname 的排序顺序也可以由 versionsort.suffix 配置变量影响。 支持的键与 git for-each-ref 中的相同。 排序顺序默认为 tag.sort 变量的配置值（如果存在的话），否则为词法顺序。见 git-config[1]。

--color[=<when>]

尊重`--format`选项中指定的任何颜色。<什么时候>`字段必须是`always、never`或`auto`之一（如果没有<什么时候>，则表现为`always）。

-i
--ignore-case

排序和过滤标签不区分大小写。

--omit-empty

在格式化的引用后不打印换行，因为格式化的引用会扩展为空字符串。

--column[=<选项>]
--no-column

在列中显示标签列表。选项语法见配置变量`column.tag`。--column 和 --no-column 没有选项，分别等同于’永远’和’从不'。

这个选项只适用于列出没有注释线的标签。

--contains [<提交>]

只列出包含指定提交的分支（如果没有指定则为HEAD）。意味着 --list。

--no-contains [<提交>]

只列出不包含指定提交的分支（如果不指定则为HEAD）。意味着 --list。

--merged [<提交>]

只列出其提交可以从指定提交（如果没有指定则为`HEAD`）到达的标签。

--no-merged [<提交>]

只列出其提交可以从指定提交（如果没有指定则为`HEAD`）到达的标签。

--points-at <对象>

只列出给定对象的标签（如果没有指定则为 HEAD）。暗指`--list`。

-m <消息>
--message=<msg>

使用给定的标签信息（而不是提示）。 如果给出多个 -m 选项，它们的值将作为单独的段落连接起来。 如果未给出 -a、-s 或 -u <键 ID> 选项，则默认为 -a。

-F <文件>
--file=<文件>

从给定文件中获取标签信息。 使用 - 从标准输入读取信息。 如果未给出 -a 、-s 或 -u <键 ID> 则默认为 -a。

--trailer <令牌>[(=|:)<值>]

指定一个（<token>, <value>）对，应该作为拖车应用。(例如，`git commit --trailer "Signed-off-by:C O Mitter / <committer@example.com>" --trailer "Helped-by:C O Mitter / <committer@example.com>"`将在提交信息中加入 "Signed-off-by "预告片和 "Helped-by "预告片。) `trailer.*`配置变量（git-interpret-trailers[1]）可以用来定义是否省略重复的拖车，每个拖车会出现在拖车运行的哪个位置，以及其他细节。

-e
--edit

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

--cleanup=<模式>

这个选项设置了标签信息的清理方式。 '<模式>'可以是`verbatim`（逐字记录）、whitespace（空白）和`strip`（剥离）中的一个。 其中，`strip`模式是默认的。`verbatim`模式完全不改变信息，`whitespace`只删除前导/后导的空白行，`strip`同时删除空白和注释。

--create-reflog

为标签创建一个引用日志。要全局性地启用标签的引用日志，请参见 git-config[1] 中的 core.logAllRefUpdates。 否定形式的 --no-create-reflog 会覆盖先前的 --create-reflog ，但目前不会否定 core.logAllRefUpdates 的设置。

--format <格式>

一个字符串，从正在显示的标签引用和它所指向的对象中插值`%(fieldname)'。 其格式与git-for-each-ref[1]相同。 当未指定时，默认为`%(refname:strip=2)`。

<标签名>

要创建、删除或描述的标签的名称。 新标签名必须通过 git-check-ref-format[1] 定义的所有检查。 其中一些检查可能限制了标签名称中允许的字符。

<提交>
<对象>

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

配置

默认情况下，sign-with-default模式下的`git tag`（-s）会使用你的提交者身份（形式为`你的名字<your@email.address>`）来寻找一个密钥。 如果你想使用一个不同的默认密钥，你可以在仓库配置中指定它，如下：

[user]
    signingKey = <GPG 键 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]。

更多细节及其他配置变量请参见 git-config[1]。

讨论

关于重新打标签

当你标记了一个错误的提交，而你想重新标签时，你应该怎么做？

如果你从未推送到其他地方，只需重新标签。使用"-f "来替换旧的标签。然后你就完成了。

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

  1. 理智的做法是。 只要承认你搞砸了，并使用一个不同的名字。其他人已经看到了一个标签名称，如果你保持相同的名称，你可能会出现这样的情况：两个人都有 "X版"，但他们实际上有 "不同 "的 "X"。 所以，只要叫它 "X.1 "就可以了。

  2. 疯狂的做法。 你真的想把新版本也称为 "X"，⌊尽管⌉别人已经看到了旧版本。所以就再用`git tag -f`，就好像你还没有发布过旧版本一样。

然而，Git*不会*（也不应该）背着用户改变标签。所以如果有人已经得到了旧的标签，在你的树上做 "git pull "不应该让他们覆盖旧的标签。

如果有人从你那里得到一个发布标签，你不能通过更新你自己的标签来为他们改变标签。这是一个很大的安全问题，因为人们必须能够信任他们的标签名。 如果你真的想做一件疯狂的事情，你需要承认这一点，并告诉人们你搞砸了。你可以通过发布一个非常公开的公告来做到这一点，比如说：

好吧，我搞砸了，我推送了一个标签为X的早期版本。
然后修复了一些东西，又把这个*修复的*目录树重新标签为X。

如果你得到了错误的标签，并希望得到新的标签，
请删除旧的标签，并通过以下方式获取新的标签：

	git tag -d X
	git fetch origin tag X

以获得我的最新标签。

你可以通过以下方式测试你的标签

	git rev-parse X

如果你有新的版本，应该返回0123456789abcdef。

不便之处，敬请原谅。

这看起来是不是有点复杂？它*应该*是这样的。自动 "修复 "它是不可能的。 人们需要知道他们的标签可能已经被改变。

在下列情况下自动进行

如果你在跟踪别人的树目录，你很可能在使用远程跟踪的分支（例如：refs/remotes/origin/master）。 你通常希望得到另一端的标签。

另一方面，如果你是因为想从别人那里获得一次性合并而取的，你通常不希望从那里获得标签。 这种情况更经常发生在接近高层的人身上，但不限于他们。 普通人从对方那里取东西时，不一定想从对方那里自动获得私人锚点标签。

通常，邮件列表上的 "请拉"信息只提供了两条信息：一个 仓库URL 和一个分支名称；这被设计成可以轻松地剪切和粘贴在 "git fetch "命令行的末尾：

Linus，请从这里拉取

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

以获得以下更新...

成为：

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

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

Git 的一个重要方面是它的分布式性质，这很大程度上意味着系统中没有固有的 "上游 "或 "下游"。 从表面上看，上面的例子似乎表明标签命名空间是由上层人士拥有的，而标签只能向下流动，但事实并非如此。 它只是表明，使用模式决定了谁对谁的标签感兴趣。

一次性拉取是一个标志，表明一个提交历史正在跨越一个圈子（例如 "主要对内核的网络部分感兴趣的人"）和另一个圈子（例如 "整合各种子系统改进的人"）之间的界限，后者可能有自己的一套标签（例如 "这是网络组的第三个候选版本，将在2.6.21版本中被建议用于一般消费"）。 后者通常对前一组内部使用的详细标签不感兴趣（这就是 "内部 "的意思）。 这就是为什么在这种情况下最好不要自动跟随标签。

在这个网络知州，他们可能想交换他们小组内部的标签，但在那个工作流程中，他们很可能是通过有远程跟踪的分支来跟踪对方的进展。 同样，自动跟踪这种标签的启发式方法也是一个好东西。

关于回溯标签

如果你从另一个VCS导入了一些修改，并想为你工作的主要版本添加标签，能够指定嵌入标签对象内部的日期是很有用的；标签对象中的这种数据会产生影响，例如，gitweb界面中标签的排序。

要设置未来标签对象中使用的日期，请设置环境变量GIT_COMMITTER_DATE（见后面关于可能数值的讨论；最常见的形式是 "YYY-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 时间戳> <时区偏移量>，其中 <unix 时间戳> 是自 UNIX epoch 以来的秒数。 <时区偏移量> 是相对于 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 。

Note
 此外，日期部分还接受以下格式：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 签名。在自动化脚本中使用该选项可能会导致大量标签被签名。因此，使用 agent 来避免多次输入 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] 文档