git tag用法详解

1 功能

git tag：用来创建、查看、删除、校验(GPG 校验)本地的 tag，创建、删除 tag 到远程仓库

2 概述

查看 git 版本：git -v/--version

git 1.x 版本参数：

git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>]
           <tagname> [<commit> | <object>]
git tag -d <tagname>...
git tag [-n[<num>]] -l [--contains <commit>] [--points-at <object>]
        [--column[=<options>] | --no-column] [<pattern>...]
        [<pattern>...]
git tag -v <tagname>...

git 2.x 版本新增参数：

git tag  [--create-reflog] [--sort=<key>] [--format=<format>]
		    [--merged <commit>] [--no-merged <commit>] [<pattern>…​]

3 参数详解

默认是新增 tag，只有指定-d/-l/-v 参数时是删除/查看/校验 tag

3.1 新增 tag

git tag <tagname>：创建一个不带任何注解的的标签，标签默认指向当前 HEAD 的 commit

git tag <tagname> <commit>：用指定的 commit 创建标签

-a, --annotate：创建一个带注解的标签，必须指定 -m <msg> 或者 -f <file> 参数，否则会弹出默认编辑器编写注解信息

-s, --sign：使用 GPG 签名标签，默认使用 git 用户的 email 作为 key，如果没有 gpg 程序或者没有生成 gpg 密钥对会报错

-u <key-id>, --local-user=<key-id>：指定 gpg 签名的 key，需要有 gpg 秘钥对

-f, --force：如果已经存在标签，强制替换老的标签

-m <msg>, --message=<msg>：标注信息来自于命令行文本

-F <file>, --file=<file>：标注信息来自于文件

3.2 删除 tag

-d, --delete：删除已存在的标签

3.3 查看 tag

git tag：默认显示所有标签

-l <pattern>, --list <pattern>：显示符合指定模式的标签，支持 shell 模式下的通配符，如：任意数量字符 *、单个字符 ? 、字符集 [a-z] 、序列 {1..5}/{a..g}，不支持正则

-n<num>：每个标签显示多少行的注解信息

--column[=<options>], --no-column：–column 参数单行显示所有标签，而不是一行显示一个标签。至于 options，没有查到用法

--contains <commit>：列出包含指定 commit 的 tag，如：taga 指向 commit3，而 commit3 的父节点有 commit1、commit2，那么–contains commit1，是会列出标签 taga 的。

--points-at <object>：列出指向某个 commit 的所有 tag

--cleanup=<mode>：模式有：verbatim, whitespace,strip。verbatim：显示所有，whitespace：清除头和尾的空白行，strip：清除 whitespace 和注释行

3.4 校验 tag

-v, --verify：校验标签，只能校验使用 gpg 签名过的标签

3.5 2.X 版本参数

--create-reflog：新增 tag 时，为新增的 tag 指定一个引用，可以是分支、标签、hash 值

--sort=<key>/<-key>：为所有的 tag 排序显示: key 顺序、-key 逆序，默认排序是按照 ASCII 排序，可以指定的排序方式：refname(默认)、version:refname、taggerdate、tagger、committerdate、objecttype。version:refname：按照版本号排序，例如：V1.0、V1.1、V1.2，和默认的区别就是后面是数值，以数值大小排序。taggerdate：以创建 tag 的时间排序。tagger：以 tag 的创建人排序。committerdate：以 commit 的时间排序。objecttype：以对象类型排序。

--format=<format>：以指定格式显示，默认为：--format="%(refname:strip=2)" ，引用名称为：refs/tags/tagname,strip=2 后则是 tagname，其他的占位符：

%n: 换行符
%(refname): 标签的引用名称（例如 refs/tags/v1.0）
%(objectname)`: 标签的对象名称（例如 1a2b3c4d）
%(*objectname): 标签指向的对象的对象名称（例如 1a2b3c4d）
%(*objecttype): 标签指向的对象的类型（例如 commit、tree、blob 等）
%(*objectsize): 标签指向的对象的大小（以字节为单位）
%(*taggername): 标签的创建者的名称
%(*taggeremail): 标签的创建者的电子邮件地址
%(*taggerdate): 标签的创建时间
%(*subject): 标签的说明文字

--merged <commit>：列出指向 commit 的 tag，含义同 --points-at <object>

--no-merged <commit>：列出不指向 commit 的 tag

4 本地操作示例

切换 tag

git checkout tagname

新增 tag：

# 新增不带标注的tag,tag指向当前HEAD
git tag tagname

# 新增带标注的tag，tag指向当前HEAD
git tag -a tag name -m “tag message”

# 新增tag，指向分支/tag/哈希
git tag tagname 分支/tag/哈希

# 强制覆盖旧tag
git tag tagname -f -m "tag message"

删除 tag：

git tag -d tagname

查看 tag：

# 显示所有tag
git tag

# 显示前5个tag
git tag |head -n5

# 显示指定tag
git tag tagname

# 显示tag指向的hash
git rev-parse tagname

# 显示符合指定模式的tag
git tag --list "V1.*"
git tag --list "V1.?"
git tag --list "V1.[1-5].*"

# 显示包含指定commit的tag
git tag --contains commit-id

# 显示指向某个commit的tag
git tag --points-at commit-id

2.X 版本功能：

# tag按照版本号排序显示
git tag --sort "version:refname"
# tag按照版本号排序显示，逆序
git tag --sort "-version:refname"
# tag按照tag时间排序
git tag --sort "taggerdate"

# tag按照指定格式显示,例如
git tag --list --format="%(refname:strip=2)  Committer:%(taggername)"

5 远程操作示例

可以对远程仓库标签执行：新增和删除

# 推送标签
git push origin tagname

# 推送所有标签
git push origin --tags

# 删除指定标签
git push origin :remote-tagname

# 下载指定标签
git fetch tagname

# 下载所有标签
git fetch origin --tags