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

名称

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

概述

git tag [-a | -s | -u <键-id>] [-f] [-m <信息> | -F <文件>] [-e]
	<标签名> [<提交> | <对象>]
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签名的标签，使用默认电子邮件地址的密钥。 标签GPG签名的默认行为由`tag.gpgSign`配置变量控制（如果存在），否则禁用。 参见 git-config[1]。

--no-sign

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

-u <key-id>
--local-user=<key-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=<键>选项，在这种情况下，最后一个键成为主键。也支持 "version:refname "或 "v:refname"（标签名被视为版本）。"version:refname "的排序顺序也可以由 "versionort.senffix "配置变量影响。 支持的键与`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 [<commit>]

只列出包含指定提交内容的标签（如果没有指定则为当前分支）。暗指`--list`。

--no-contains [<commit>]

只列出包含指定提交内容的标签（如果没有指定则为当前分支）。暗指`--list`。

--merged [<commit>]

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

--no-merged [<commit>]

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

--points-at <object>

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

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

Use the given tag message (instead of prompting). If multiple -m options are given, their values are concatenated as separate paragraphs. Implies -a if none of -a, -s, or -u <key-id> is given.

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

Take the tag message from the given file. Use - to read the message from the standard input. Implies -a if none of -a, -s, or -u <key-id> is given.

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

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

<tagname>

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

<commit>
<对象>

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

配置

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

[user]
    signingKey = <gpg-key_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。

Sorry for the inconvenience.

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

在下列情况下自动进行

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

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

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

Linus，请从这里拉取

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

以获得以下更新...

成为：

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

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

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

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

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

On Backdating Tags

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

要设置未来标签对象中使用的日期，请设置环境变量GIT_COMMITTER_DATE（见后面关于可能数值的讨论；最常见的形式是 "YYY-MM-DD HH:MM"）。

For example:

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

日期格式

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

Git 内部格式

It is <unix timestamp> <time zone offset>, where <unix timestamp> is the number of seconds since the UNIX epoch. <time zone offset> is a positive or negative offset from UTC. For example CET (which is 1 hour ahead of UTC) is +0100.

RFC 2822

由 RFC 2822 描述的标准电子邮件格式，例如 Thu, 07 Apr 2005 22:13:13 +0200。

ISO 8601

Time and date specified by the ISO 8601 standard, for example 2005-04-07T22:13:13. The parser accepts a space instead of the T character as well. Fractional parts of a second will be ignored, for example 2005-04-07T22:13:13.019 will be treated as 2005-04-07T22:13:13.

Note
 此外，日期部分还接受以下格式：YYYY.MM.DD，MM/DD/YYYY 和 DD.MM.YYYY。

文件

$GIT_DIR/TAG_EDITMSG

This file contains the message of an in-progress annotated tag. If git tag exits due to an error before creating an annotated tag then the tag message that has been provided by the user in an editor session will be available in this file, but may be overwritten by the next invocation of git tag.

NOTES

当组合多个"---包含 "和"---不包含 "过滤器时，只显示至少包含一个"---包含 "的提交，并且不包含"---不包含 "的提交的参考。

当结合多个 "合并 "和 "未合并 "过滤器时，只显示至少有一个 "合并 "提交和没有 "未合并 "提交的引用。

参见

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

GIT

属于 git[1] 文档

scroll-to-top