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

名称

git-tag - 创建、列出、删除或验证使用GPG签名的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>`中的一个，该命令会创建一个 '标签' 对象，并要求提供一个标签信息。 除非给出-m <信息>或-F <文件>`，否则会启动一个编辑器，让用户输入标签信息。

If -m <msg> or -F <file> or --trailer <token>[=<value>] is given and -a, -s, and -u <key-id> are absent, -a is implied.

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

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

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

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

选项

-a
--annotate

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

-s
--sign

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

--no-sign

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

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

制作一个GPG签名的标签，使用给定的密钥。

-f
--force

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

-d
--delete

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

-v
--verify

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

-n<num>

<数字>指定在使用-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 <令牌>[(=|:)<值>]

Specify a (<token>, <value>) pair that should be applied as a trailer. (e.g. git tag --trailer "Custom-Key: value" will add a "Custom-Key" trailer to the tag message.) The trailer.* configuration variables (git-interpret-trailers[1]) can be used to define if a duplicated trailer is omitted, where in the run of trailers each trailer would appear, and other details. The trailers can be extracted in git tag --list, using --format="%(trailers)" placeholder.

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

pager.tag`只在列出标签时被尊重，即使用或暗示使用-l`时。默认是使用分页器。 参见 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

The standard date format as described by RFC 2822, for example 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 时覆盖。

注释

当组合多个 --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