（三）分支与标签 - git tag 命令的使用

文章目录

[1. 命令概述](#1. 命令概述)
[2. 命令格式](#2. 命令格式)
[3. 基本用法](#3. 基本用法)
- [3.1 列出标签](#3.1 列出标签)
- [3.2 创建标签](#3.2 创建标签)
- [3.3 查看标签详情](#3.3 查看标签详情)
- [3.4 删除标签](#3.4 删除标签)
- [3.5 推送标签到远程](#3.5 推送标签到远程)
4.高级用法
- [4.1 签名标签 (GPG签名)](#4.1 签名标签 (GPG签名))
- [4.2 检出标签](#4.2 检出标签)
- [4.3 标签列表的排序与格式化](#4.3 标签列表的排序与格式化)
[5. 注意事项](#5. 注意事项)
- [5.1 命名规范](#5.1 命名规范)
- [5.2 附注标签 vs 轻量标签](#5.2 附注标签 vs 轻量标签)
- [5.3 不要重推已存在的标签](#5.3 不要重推已存在的标签)
- [5.4 --tags 与 --follow-tags](#5.4 --tags 与 --follow-tags)
[6. 补充信息](#6. 补充信息)

1. 命令概述

git tag 命令用于创建、列出、删除或验证标签。标签是一个静态的引用，指向 Git 历史中的某个特定提交。它通常用于标记发布点（例如，v1.0.0, v2.1-rc）。

核心概念：

与分支的区别：分支（branch）是一个会移动的指针，随着新的提交而不断前进。而标签（tag）是一个静态的指针，一旦指向某个提交，就固定不变（轻量标签）或极难改变（附注标签）。
用途：标记项目的重要节点，如版本发布、稳定版、测试版等，方便快速定位和回溯。

2. 命令格式

基本格式如下：

bash 复制代码

git tag [-a | -s | -u <keyid>] [-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] [--create-reflog] [--sort=<key>] [--format=<format>] [<pattern>...]
git tag -v <tagname>...

虽然看起来很复杂，但我们可以通过具体的用法来理解它。

3. 基本用法

3.1 列出标签

列出仓库中所有已有的标签。

bash 复制代码

git tag

这会以字母顺序列出所有标签。
常用选项：

-l 或 --list：显式地列出标签（在现代 Git 版本中，git tag 默认行为就是 -l）。
使用模式匹配过滤标签：

bash 复制代码

# 列出所有 v1. 开头的标签    
git tag -l "v1.*"    
# 列出所有 rc (发布候选) 标签    
git tag -l "*rc*"

3.2 创建标签

主要有两种类型的标签：轻量标签 和 附注标签 。
a) 轻量标签像一个不会移动的分支，它只是一个指向特定提交的指针。不存储任何额外信息（如作者、日期、注释）。

bash 复制代码

git tag <tagname>
# 例如，在当前提交上创建 v1.0-light 标签
git tag v1.0-light

b) 附注标签 存储在 Git 数据库中的一个完整对象。它们包含打标签者的名字、电子邮件、日期、标签信息，并且可以被 GPG 签名和验证。
推荐用于公共版本发布。

bash 复制代码

git tag -a <tagname> -m "<message>"
# 例如
git tag -a v1.0 -m "Version 1.0 stable release"

-a：指定要创建一个附注标签。
-m：指定标签信息，类似于提交信息。如果不加 -m，Git 会启动编辑器让你输入。

c) 对历史提交打标签 默认情况下，git tag 会在 HEAD 所指向的提交上打标签。你也可以对历史上的任何提交打标签，只需要指定提交的校验和（或部分校验和）。

bash 复制代码

git tag -a <tagname> <commit-hash> -m "<message>"
# 例如，为提交 `a1b2c3d` 打上标签
git tag -a v0.9 a1b2c3d -m "Version 0.9 beta"

3.3 查看标签详情

使用 git show <tagname> 可以查看标签指向的提交信息，以及标签本身的详细信息。

bash 复制代码

git show v1.0

对于附注标签，输出会显示：标签对象信息（标签人、日期、注释）、对应的提交信息。
对于轻量标签，输出只显示对应的提交信息。

3.4 删除标签

删除本地标签：

bash 复制代码

git tag -d <tagname>
# 例如
git tag -d v1.0-light

删除远程标签（需要两步）：

删除本地标签（如上所述）。
使用 git push 将删除操作推送到远程仓库。

bash 复制代码

# 语法： git push <remote> :refs/tags/<tagname>    
git push origin :refs/tags/v1.0-light    
# 更直观的现代语法 (Git v1.7.0+)    
git push origin --delete v1.0-light

3.5 推送标签到远程

默认情况下，git push 命令不会将标签传送到远程服务器。你需要显式地推送标签。
推送单个标签：

bash 复制代码

git push origin <tagname>
# 例如
git push origin v1.0

推送所有本地标签：

bash 复制代码

git push origin --tags

注意：--tags 会将所有本地尚未存在于远程的标签都推送上去，包括轻量标签和附注标签。

(更安全的选择) 推送所有附注标签：

bash 复制代码

git push origin --follow-tags

--follow-tags 只会推送那些当前提交能到达的附注标签。这是一种更安全、更精准的做法，避免了意外推送一些临时的或本地的轻量标签。

4.高级用法

4.1 签名标签 (GPG签名)

使用 GPG 私钥对标签进行加密签名，以验证其真实性和完整性。这需要使用 -s 代替 -a。

bash 复制代码

git tag -s <tagname> -m "<message>"
# 例如
git tag -s v1.1-signed -m "My signed v1.1 tag"

验证签名标签：

bash 复制代码

git tag -v <tagname>
# 例如
git tag -v v1.1-signed

此命令需要签名者的公钥在你的 GPG 密钥链中

4.2 检出标签

如果你想查看标签指向的代码状态，可以基于标签创建一个新分支。

bash 复制代码

git checkout -b <new-branch-name> <tagname>
# 例如，基于 v1.0 标签创建一个用于修复旧版本bug的分支
git checkout -b fix-v1.0-bug v1.0

重要：通常你不会直接在标签上工作（因为标签指向的是一个不可变的提交），所以先创建分支是标准做法。

4.3 标签列表的排序与格式化

按版本号排序：

默认的字典序排序会让 v1.10 排在 v1.2 前面。使用 --sort 可以按版本号正确排序。

bash 复制代码

git tag -l --sort=-version:refname "v*"

-version:refname 表示按版本号倒序（最新的在前面），去掉 - 则是正序。

自定义输出格式：

使用 --format 可以像 git log 一样自定义列表输出。

bash 复制代码

# 以更详细的格式列出标签
git tag -l --format='%(tag) %(taggerdate:short) %(subject)'

5. 注意事项

5.1 命名规范

推荐使用语义化版本命名，如 v1.0.0, v2.1.3。
避免使用空格和特殊字符，可以使用 ., -, _。
不要以 - 开头。

5.2 附注标签 vs 轻量标签

附注标签是功能完备的 Git 对象 ，包含完整信息且可签名，强烈推荐用于所有公开的、重要的版本发布。
轻量标签适合临时或私人的标记，比如在本地标记一个需要稍后回顾的提交。

5.3 不要重推已存在的标签

使用 git tag -a -f <tagname> 可以强制移动一个已存在的标签到新的提交。
但这会改变历史，如果这个标签已经被其他人拉取，会造成混乱。对于已经推送到远程的标签，应尽量避免修改。正确的做法是删除旧的，创建新的。

5.4 --tags 与 --follow-tags

在推送时，养成使用 git push --follow-tags 的习惯，而不是 git push --tags，这样可以避免污染远程仓库。

6. 补充信息

工作流示例一个典型的版本发布工作流：

bash 复制代码

# 1. 确保工作在正确的分支（如 main），并且代码处于要发布的状态
git checkout main

# 2. 运行测试，确保一切正常
npm test

# 3. 创建附注标签
git tag -a v1.2.0 -m "Release version 1.2.0: Added new dashboard feature"

# 4. （可选）签名标签
# git tag -s v1.2.0 -m "..."

# 5. 将标签和对应的提交推送到远程
git push origin main --follow-tags

# 如果只想推送标签，也可以
# git push origin v1.2.0