标签（Tag）

标签用于给项目历史中的某个重要节点打上永久标记，最常见的用途是标记版本发布点（如 v1.0.0）。

轻量标签 vs 附注标签

轻量标签（Lightweight Tag）

轻量标签只是一个指向某个 Commit 的引用，没有额外信息：

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

# 创建到指定提交
git tag v1.0.0 abc123

# 存储在 .git/refs/tags/v1.0.0（内容是 commit SHA-1）
cat .git/refs/tags/v1.0.0
# abc123456789...

特点： 简单快速，但没有附加信息，不适合正式发布。

附注标签（Annotated Tag）

附注标签会创建一个独立的 Tag 对象，包含标签者信息、时间、说明等：

# 创建附注标签（-a 表示 annotated，-m 指定说明）
git tag -a v1.0.0 -m "Release version 1.0.0"

# 创建到指定提交
git tag -a v1.0.0 abc123 -m "Release version 1.0.0"

# 打开编辑器填写详细说明（不带 -m）
git tag -a v1.0.0

附注标签的额外信息：

git show v1.0.0

# 输出：
# tag v1.0.0
# Tagger: Zhang San <zhang@example.com>
# Date:   Mon Mar 9 10:30:00 2026 +0800
#
# Release version 1.0.0
# 
# 新增功能：
# - 用户认证模块
# - 商品管理功能
#
# commit abc123456789...
# Author: ...

推荐使用附注标签用于正式发布。

git tag 创建标签

# 轻量标签（当前 HEAD）
git tag v1.0.0

# 附注标签（推荐正式发布使用）
git tag -a v1.0.0 -m "版本说明"

# 签名标签（使用 GPG 签名，最高安全性）
git tag -s v1.0.0 -m "Signed release"

# 给历史提交打标签
git tag -a v0.9.0 abc123 -m "Retrospective: beta version"

给历史提交打标签

# 查看历史提交
git log --oneline
# abc123 feat: 发布 1.0.0 功能
# def456 feat: 完成认证模块

# 给某个历史提交打标签
git tag -a v1.0.0 abc123 -m "正式发布 v1.0.0"
git tag -a v0.9.0 def456 -m "完成认证模块"

git tag -l 过滤标签

# 查看所有标签（按字母顺序）
git tag

# 查看所有标签（按版本号排序）
git tag -l | sort -V

# 使用通配符过滤
git tag -l "v1.*"      # 所有 v1.x 版本
git tag -l "v2.*"
git tag -l "*-beta*"   # 所有 beta 版本

# 查看标签详情
git show v1.0.0

推送标签到远程

默认情况下，git push 不推送标签：

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

# 推送所有本地标签
git push origin --tags
git push --tags    # 推送到默认远程

# 推送所有附注标签（不推送轻量标签）
git push origin --follow-tags

推荐配置（总是推送附注标签）：

git config --global push.followTags true

删除本地和远程标签

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

# 删除远程标签（两种方式）
git push origin --delete v1.0.0
git push origin :refs/tags/v1.0.0    # 旧语法

# 批量删除本地标签（谨慎！）
git tag -l "v0.*" | xargs git tag -d

检出标签

# 检出标签（进入分离 HEAD 状态）
git checkout v1.0.0

# 从标签创建分支（用于在旧版本上做修复）
git checkout -b hotfix/v1.0.1 v1.0.0
git switch -c hotfix/v1.0.1 v1.0.0

验证签名标签

# 验证标签的 GPG 签名
git tag -v v1.0.0

语义化版本（SemVer）

标签通常遵循语义化版本规范：

v主版本号.次版本号.修订号

v1.0.0   → 初始正式版
v1.1.0   → 新增向后兼容的功能
v1.1.1   → 向后兼容的 bug 修复
v2.0.0   → 不兼容的 API 修改

预发布版本：
v1.0.0-alpha.1
v1.0.0-beta.2
v1.0.0-rc.1      → Release Candidate

# 完整的版本发布流程
# 1. 确保代码已合并到 main
git switch main
git pull

# 2. 创建附注标签
git tag -a v1.2.0 -m "Release v1.2.0

新功能：
- 添加用户头像上传
- 支持暗色主题

Bug 修复：
- 修复登录页面内存泄露
- 修复移动端布局问题"

# 3. 推送标签
git push origin v1.2.0

# 4. 在 GitHub 上基于标签创建 Release（附上 CHANGELOG）

自动化标签

使用工具自动管理标签和版本：

# 使用 npm 版本管理（Node.js 项目）
npm version patch   # 1.0.0 → 1.0.1（自动创建 tag）
npm version minor   # 1.0.0 → 1.1.0
npm version major   # 1.0.0 → 2.0.0
npm version prepatch   # 1.0.0 → 1.0.1-0
npm version prerelease # 1.0.1-0 → 1.0.1-1

# 推送版本标签
npm version minor && git push && git push --tags

总结

操作	命令
创建轻量标签	git tag v1.0.0
创建附注标签	git tag -a v1.0.0 -m "说明"
给历史提交打标签	git tag -a v0.9.0 <sha>
查看所有标签	git tag -l
过滤标签	git tag -l "v1.*"
推送单个标签	git push origin v1.0.0
推送所有标签	git push --tags
删除本地标签	git tag -d v1.0.0
删除远程标签	git push origin --delete v1.0.0

标签是版本管理的重要工具，结合 CI/CD 流水线，可以实现自动化的版本发布流程。