标签管理

为什么需要 Tag？

Git 引入标签（Tag）的核心原因只有一个：Commit Hash 对人类不友好，而分支指针又会移动。在软件工程中，我们需要一种永久固定、语义清晰、不会漂移的方式来标记「某个特定时刻的快照」。这就是 Tag 存在的意义。

痛点	Commit Hash 的问题	Branch 的问题	Tag 的解决方案
可读性	`a3f8b2c` 毫无语义，没人记得住	`main` 有语义但不精确	`v1.0.0` 一眼就知道是什么版本
稳定性	不可变，但太难记	每次提交都会向前移动	不可变 + 人类可读
发布管理	无法表达「正式版/预发布」等元信息	不适合标记历史节点	专为版本发布设计，支持注解和签名

Tag 的两种类型

类型	本质	包含信息	推荐场景
轻量标签	仅仅是一个指向 commit 的指针（类似 branch）	只有名字 + commit hash	临时标记、个人笔记
附注标签	一个完整的 Git 对象，存储在数据库中	标签名、commit hash、作者、日期、备注消息、GPG 签名	所有正式发布版本

⚠️ 注意

永远使用附注标签做版本发布

轻量标签只用于临时用途。很多工具（如 git describe、GitHub Releases）只对附注标签生效。

创建标签

# ==================== 附注标签（推荐） ====================
# -a 表示创建附注标签（包含标签者信息、日期、说明文字等元数据）
# -m 指定标签的说明信息
git tag -a v1.0.0 -m "Release version 1.0.0: 首次正式发布"

# ==================== 轻量标签（仅临时使用） ====================
# 不带 -a 参数，只创建一个指向 commit 的指针
git tag v1.0.0-beta

# ==================== 给历史提交打标签（补打） ====================
# 在标签名后指定 commit hash
git tag -a v0.9.0 -m "Beta release" abc1234

💡 提示

版本号规范

v1.0.0 只是惯例不是规则。只要避开特殊字符和分支冲突，你可以用任何有意义的名称，但正式发布建议遵循 SemVer（语义化版本）以获得工具链兼容：

主版本号.次版本号.修订号（MAJOR.MINOR.PATCH）
MAJOR：不兼容的 API 修改
MINOR：向下兼容的功能性新增
PATCH：向下兼容的问题修正

查看标签

# ==================== 列出标签 ====================
# 列出所有标签
git tag

# 按模式过滤标签
# 只显示以 v1. 开头的标签
git tag -l "v1.*"

# ==================== 查看标签详情 ====================
# 查看某个标签的详细信息
# 输出包含：标签创建者、日期、备注消息、对应 commit 的完整 diff
git show v1.0.0

推送标签到远程

# ==================== 推送单个标签 ====================
git push origin v1.0.0

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

# ⚠️ 注意：git push 默认不会推送标签！必须显式指定

⚠️ 注意

Push Tag ≠ 自动 Commit

推送标签只是传输已有标签到远程，不产生任何新内容。先有标签才能推，如果对应的 commit 还没推送，需要先推代码。

删除标签

# ==================== 删除本地标签 ====================
git tag -d v1.0.0

# ==================== 删除远程标签 ====================
git push origin --delete v1.0.0

# 或者使用这种写法（效果相同）
git push origin :refs/tags/v1.0.0

基于标签操作

以分离 HEAD 状态查看某个版本

# checkout 标签名会进入 Detached HEAD 状态
git checkout v1.0.0

检出标签：HEAD 与 main 分离
图表加载后显示；也可展开查看下方源码。
查看 Mermaid 源码
flowchart LR
  accTitle: 检出标签：HEAD 与 main 分离
  A["A"] --- B["B"] --- C["C"]
  T["tag: v1.0.0"] --> B
  H["HEAD · detached"] --> B
  M["main"] --> C

HEAD 直接指向 commit B，不属于任何分支
如果你在此状态下做了新 commit，这些 commit 没有分支归属，一旦切走就可能丢失
Git 会给出明确警告：You are in 'detached HEAD' state...

从标签创建热修复分支（非常常用！）

# 以 v1.0.0 为起点，创建一个全新的分支 hotfix/v1.0.1
git checkout -b hotfix/v1.0.1 v1.0.0

从标签创建热修复分支
图表加载后显示；也可展开查看下方源码。
查看 Mermaid 源码
flowchart LR
  accTitle: 从标签创建热修复分支
  A["A"] --- B["B"] --- C["C"]
  T["tag: v1.0.0"] --> B
  H["HEAD"] --> F["hotfix/v1.0.1"] --> B
  M["main"] --> C

以 v1.0.0 为起点，创建一个全新的分支 hotfix/v1.0.1
HEAD 正常附着在新分支上
你可以安全地 commit、push，所有改动都有分支承载
原标签 v1.0.0 不受任何影响

✨ 技巧

标签管理最佳实践

正式发布必须用附注标签：包含版本信息、发布说明等元数据
遵循 SemVer 规范：便于工具链集成和依赖管理
及时推送标签：git push --tags 确保远程仓库有所有标签
不要删除已发布的标签：其他项目可能已经引用了这个标签
热修复从标签创建分支：git checkout -b hotfix/v1.0.1 v1.0.0

标签与发布流程

标签、Release 与部署流程
图表加载后显示；也可展开查看下方源码。
查看 Mermaid 源码
flowchart TB
  accTitle: 标签、Release 与部署流程
  A["完成开发并合并到 main"] --> B["创建附注标签：git tag -a v1.0.0"]
  B --> C["推送标签：git push origin v1.0.0"]
  C --> D["手动创建 Release，或由已配置的工作流创建"]
  D --> E["执行部署工作流并验证生产环境"]

推送标签本身不会自动创建 Release；需要手动发布，或事先配置相应的自动化工作流。

相关笔记：

分支管理 — 分支操作
撤销与回退 — Detached HEAD 的处理

目录