Git 完全指南 / 09 - 标签管理：annotated tags、lightweight tags、签名

第九章：标签管理

标签是标记项目历史中特定节点的方式，通常用于版本发布。

9.1 标签概述

标签（Tag）是对特定提交的永久标记，不会像分支那样随新提交移动。

C1 → C2 → C3 → C4 → C5
              ↑         ↑
           v1.0.0     v1.1.0

轻量标签 vs 附注标签

特性	轻量标签 (Lightweight)	附注标签 (Annotated)
对象类型	引用指针	独立的 tag 对象
包含信息	仅标签名	标签名、作者、日期、说明
签名支持	❌	✅
推荐场景	临时标记	正式发布版本

9.2 轻量标签

# 创建轻量标签
$ git tag v1.0.0

# 标记特定提交
$ git tag v1.0.0-beta abc1234

# 创建并切换到标签
$ git switch -c release-v1.0.0 v1.0.0

9.3 附注标签

# 创建附注标签
$ git tag -a v1.0.0 -m "Release version 1.0.0"

# 标记特定提交
$ git tag -a v1.0.0 abc1234 -m "Version 1.0.0"

# 使用编辑器编写详细说明
$ git tag -a v2.0.0
# 会打开编辑器

# 查看标签详细信息
$ git show v1.0.0
tag v1.0.0
Tagger: John Doe <[email protected]>
Date:   Mon Jan 15 10:00:00 2024 +0800

Release version 1.0.0

commit abc1234...
Author: John Doe <[email protected]>
Date:   Mon Jan 15 09:00:00 2024 +0800

    Final commit for v1.0.0

9.4 签名标签

# 使用 GPG 签名标签
$ git tag -s v1.0.0 -m "Signed release v1.0.0"

# 验证签名标签
$ git tag -v v1.0.0
object abc1234...
type commit
tag v1.0.0
tagger John Doe <[email protected]>

Signed release v1.0.0
gpg: Signature made Mon Jan 15 10:00:00 2024
gpg:                using RSA key ABCD1234...
gpg: Good signature from "John Doe <[email protected]>"

GPG 密钥配置

# 生成 GPG 密钥
$ gpg --full-generate-key

# 列出 GPG 公钥
$ gpg --list-secret-keys --keyid-format=long
sec   rsa4096/ABCD1234EFGH5678 2024-01-01 [SC]
      1234567890ABCDEF1234567890ABCDEF12345678
uid                 [ultimate] John Doe <[email protected]>
ssb   rsa4096/1234567890ABCDEF 2024-01-01 [E]

# 配置 Git 使用 GPG 密钥
$ git config --global user.signingkey ABCD1234EFGH5678
$ git config --global commit.gpgsign true

# 自动签名所有标签
$ git config --global tag.gpgsign true

9.5 标签管理操作

9.5.1 查看标签

# 列出所有标签
$ git tag
v1.0.0
v1.1.0
v2.0.0

# 按模式过滤
$ git tag -l "v1.*"
v1.0.0
v1.1.0

# 按通配符过滤
$ git tag -l "v*.*.*"

# 按提交过滤
$ git tag --contains abc1234
$ git tag --merged main

# 按排序
$ git tag --sort=-version:refname    # 版本号降序
$ git tag --sort=version:refname     # 版本号升序

9.5.2 删除标签

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

# 删除远程标签
$ git push origin --delete v1.0.0-beta
# 或
$ git push origin :refs/tags/v1.0.0-beta

9.5.3 推送标签

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

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

# 推送特定标签（精确控制）
$ git push origin tag v1.0.0

9.6 语义化版本号（SemVer）

MAJOR.MINOR.PATCH

v1.2.3
│ │ │
│ │ └── PATCH: 向后兼容的 bug 修复
│ └──── MINOR: 向后兼容的新功能
└────── MAJOR: 不兼容的 API 变更

版本变更	说明	示例
MAJOR	重大变更，不向后兼容	v2.0.0
MINOR	新功能，向后兼容	v1.1.0
PATCH	Bug 修复，向后兼容	v1.0.1
预发布版本	测试版本	v1.0.0-beta.1
元数据	构建信息	v1.0.0+build.123

9.7 标签与发布流程

# 完整发布流程示例

# 1. 确保代码测试通过
$ npm test

# 2. 更新版本号（如果需要）
$ npm version patch    # 自动创建 v1.0.1 标签

# 3. 创建附注标签
$ git tag -a v1.0.0 -m "Release v1.0.0: Initial stable release"

# 4. 推送标签
$ git push origin v1.0.0

# 5. 在 GitHub/GitLab 创建 Release
# 使用 gh CLI
$ gh release create v1.0.0 --title "v1.0.0" --notes "Release notes here"

业务场景

场景	推荐方案
正式版本发布	附注标签 + 语义化版本
标记重要里程碑	附注标签 + 详细说明
临时标记	轻量标签
安全发布	签名标签（GPG）
自动化发布	CI/CD 触发创建标签

扩展阅读

🔗 上一章：08 - 撤销操作 | 下一章：10 - 子模块