15. 标签管理

提交哈希是一串看不懂的字符。标签就是给某个提交起个名字，比如 v1.0、release-20260729。一看到名字就知道这是哪个版本。

为什么需要标签

“请把上周一打包发布的那个版本 commit 6a5819e 再发一次。”

一串哈希很难记也很难沟通。换成：“把 v1.2 再发一次”，是不是清晰多了？

标签常用于：

• 标记发布版本（v1.0、v2.1.3）。
• 标记关键节点（上线日期、里程碑）。
• 标记需要回溯的审计点。

轻量标签 vs 附注标签

Git 支持两种标签：

类型	轻量标签	附注标签
本质	指向提交的指针	Git 数据库中的一个对象
保存信息	只有提交哈希	打标签人、时间、说明，可 GPG 签名
场景	临时标记、本地使用	正式发布、对外共享

日常开发推荐用附注标签。轻量标签更像”临时书签”。

创建附注标签

git tag -a v1.0 -m "发布版本 1.0"

-a 是 --annotated，-m 是指定说明。不加 -m 会打开编辑器让你写。

git tag

v1.0

创建完成。这个标签默认打在 HEAD 指向的提交上。

给历史提交打标签

发现上周的提交忘打标了？

git log --oneline

a1b2c3d 添加用户登录
d4e5f6g 修复注册 bug
h7i8j9k 初始提交

给 d4e5f6g 补一个 v0.9：

git tag -a v0.9 d4e5f6g -m "发布版本 0.9"

标签是按字母顺序列出的，不是按时间顺序。

创建轻量标签

不加 -a 就是轻量标签：

git tag v1.0-lw

没有说明、没有签名，适合本地临时标记某个提交。

查看标签详情

git show v1.0

附注标签会显示打标签人、时间、说明，然后才是提交内容：

tag v1.0
Tagger: Your Name <you@example.com>
Date:   Mon Jul 28 10:00:00 2026 +0800

发布版本 1.0

commit a1b2c3d...

轻量标签只显示提交信息。

列出所有标签

git tag

按模式过滤：

git tag -l "v1.*"

v1.0
v1.1
v1.2

推送标签

git push 不会自动把标签推到远程。需要显式推送。

推送单个：

git push origin v1.0

推送所有本地标签（一次性）：

git push origin --tags

删除标签

本地删除：

git tag -d v0.9

远程删除，两种写法：

git push origin --delete v0.9
git push origin :refs/tags/v0.9

先删本地再删远程，两步都要做。

检出标签

想看看某个标签时刻的代码：

git checkout v1.0

会进入”分离头指针”（detached HEAD）状态。这个状态能看代码、做实验，但提交不属于任何分支。

想基于标签修改代码、继续开发，先建分支：

git checkout -b version2 v1.0

这样新提交就挂在 version2 分支上了。

标签的重用策略

标签不应该移动。如果你发现打错了，正确做法是：

1. 删除错误标签：git tag -d v1.0。
2. 重新创建：git tag -a v1.0 <正确的commit> -m "修正"。

不要试图”移动”标签到另一个提交，这会让历史混乱。

标签命名建议

• 用 v 开头：v1.0、v2.3.1。
• 语义化版本号：MAJOR.MINOR.PATCH。
• 大版本不兼容改 MAJOR，新增功能改 MINOR，bug 修复改 PATCH。
• 保持全仓库统一风格。

本章小卡片

命令	作用
git tag	列出标签
git tag -a <name> -m "msg"	创建附注标签
git tag -a <name> <commit>	给历史提交打标签
git tag -l "v1.*"	按模式过滤标签
git show <tag>	查看标签详情
git push origin <tag>	推送单个标签
git push origin --tags	推送所有标签
git tag -d <tag>	删除本地标签
git push origin --delete <tag>	删除远程标签
git checkout -b <branch> <tag>	基于标签创建分支