设置和配置
获取和创建项目
基本快照
分支与合并
共享和更新项目
检查和比较
打补丁
调试
电子邮件
外部系统
服务器管理
指南
管理
底层命令
- 2.46.1 → 2.50.1 无更改
-
2.46.0
2024-07-29
- 2.45.1 → 2.45.4 无更改
-
2.45.0
2024-04-29
- 2.44.1 → 2.44.4 无更改
-
2.44.0
2024-02-23
- 2.42.1 → 2.43.7 无变更
-
2.42.0
2023-08-21
- 2.41.1 → 2.41.3 无更改
-
2.41.0
2023-06-01
- 2.39.1 → 2.40.4 无更改
-
2.39.0
2022-12-12
- 2.35.1 → 2.38.5 无变化
-
2.35.0
2022-01-24
- 2.31.1 → 2.34.8 无变更
-
2.31.0
2021-03-15
- 2.29.1 → 2.30.9 无变更
-
2.29.0
2020-10-19
- 2.27.1 → 2.28.1 无变更
-
2.27.0
2020-06-01
- 2.25.1 → 2.26.3 无更改
-
2.25.0
2020-01-13
- 2.23.1 → 2.24.4 无更改
-
2.23.0
2019-08-16
- 2.21.1 → 2.22.5 无变更
-
2.21.0
2019-02-24
- 2.19.3 → 2.20.5 无更改
-
2.19.2
2018-11-21
- 2.19.1 无更改
-
2.19.0
2018-09-10
- 2.18.1 → 2.18.5 无更改
-
2.18.0
2018-06-21
- 2.17.1 → 2.17.6 无更改
-
2.17.0
2018-04-02
- 2.15.4 → 2.16.6 无变更
-
2.14.6
2019-12-06
-
2.13.7
2018-05-22
-
2.12.5
2017-09-22
-
2.11.4
2017-09-22
-
2.10.5
2017-09-22
-
2.9.5
2017-07-30
- 2.8.6 无更改
-
2.7.6
2017-07-30
-
2.6.7
2017-05-05
- 2.5.6 无更改
-
2.4.12
2017-05-05
- 2.2.3 → 2.3.10 无更改
-
2.1.4
2014-12-17
-
2.0.5
2014-12-17
概要
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> 时,将创建一个 GnuPG 签名的标签对象。如果未使用 -u
<key-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>
-
`<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])可用于定义是否省略重复的尾注、每个尾注在尾注序列中的位置以及其他详细信息。尾注可以在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。
配置
默认情况下,处于默认签名模式 (-s) 的 git tag 将使用您的提交者身份(形式为 Your Name <your@email.address>)来查找密钥。如果您想使用不同的默认密钥,可以在仓库配置中按如下方式指定
[user] signingKey = <gpg-key-id>
pager.tag
仅在列出标签时受尊重,即在使用或隐含 -l
时。默认是使用分页器。参阅 git-config[1]。
讨论
关于重新打标签
当您给错误的提交打上标签并想重新打标签时,该怎么做?
如果您从未将任何内容推送到远程,只需重新打标签即可。使用 “-f” 替换旧标签。然后就完成了。
但是,如果您已将内容推送到远程(或其他人可以直接读取您的仓库),那么其他人将已经看到了旧标签。在这种情况下,您可以执行以下两项操作之一
-
理智的做法。承认您犯了错误,然后使用一个不同的名称。其他人已经看到了一个标签名称,如果您继续使用相同的名称,则可能会出现两个人都有“版本 X”,但实际上他们拥有 不同 的“X”的情况。所以只需将其称为“X.1”即可完成。
-
疯狂的做法。您确实想将新版本也称为“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 版本普遍使用而提议的第三个候选发布版本”)。后者通常对前一个组内部使用的详细标签不感兴趣(这就是“内部”的含义)。这就是为什么在这种情况下不自动跟踪标签是可取的。
很可能在网络领域的人员之间,他们可能希望交换其组内部的标签,但在该工作流程中,他们很可能通过远程跟踪分支来跟踪彼此的进展。同样,自动跟踪此类标签的启发式方法是一件好事。
日期格式
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
。
注意事项
当组合多个 --contains
和 --no-contains
过滤器时,只显示包含至少一个 --contains
提交且不包含任何 --no-contains
提交的引用。
当组合多个 --merged
和 --no-merged
过滤器时,只显示至少可从一个 --merged
提交访问且不可从任何 --no-merged
提交访问的引用。