l-pc-front 项目文档

主题

百想科技1970-01-01
1925
8m

Git Tag 使用文档 ​

1. 概述 ​

Git Tag 是 Git 版本控制系统中用于标记特定提交的功能，通常用于标记发布版本、里程碑或重要的代码点。在项目中，我们使用 Git Tag 来管理软件版本，便于追踪和回溯。

2. 项目中的 Git Tag 管理工具 ​

本项目提供了一个交互式的 Git Tag 管理工具，位于 scripts/git-tag-cli.js。该工具可以帮助开发者快速创建和推送 Git Tag，并自动生成版本文件。

2.1 工具功能 ​

  • 自动检测当前分支
  • 检查未提交的更改
  • 自动生成建议版本号
  • 验证语义化版本格式
  • 交互式输入版本号和描述
  • 自动创建并推送 Git Tag
  • 可选择生成版本文件
  • 可选择构建项目

2.2 工具依赖 ​

  • Node.js
  • Git

3. 如何使用 Git Tag 管理工具 ​

3.1 基本使用 ​

在项目根目录下运行以下命令：

bash
node scripts/git-tag-cli.js

或通过 npm 脚本运行（如果已配置）：

bash
npm run tag

3.2 操作流程 ​

  1. 工具启动后，会显示当前分支信息
  2. 检查是否有未提交的更改
  3. 自动生成建议版本号
  4. 提示用户输入版本号（可使用默认值）
  5. 提示用户输入标签描述（可选）
  6. 显示操作确认信息
  7. 用户确认后，创建并推送 Git Tag
  8. 询问是否生成版本文件
  9. 询问是否构建项目
  10. 显示操作结果

4. 版本号规范 ​

本项目使用语义化版本号规范（Semantic Versioning），格式为：

vX.Y.Z
  • X：主版本号，当你做了不兼容的 API 修改
  • Y：次版本号，当你做了向下兼容的功能性新增
  • Z：修订号，当你做了向下兼容的问题修正

4.1 示例 ​

  • v1.0.0：初始版本
  • v1.0.1：修复了一个 bug
  • v1.1.0：添加了新功能
  • v2.0.0：做了不兼容的 API 变更

4.2 注意事项 ​

  • 版本号必须以 v 开头
  • 工具会自动为没有 v 开头的版本号添加 v
  • 工具会验证版本号格式是否符合语义化版本规范

5. 版本文件生成 ​

当创建 Git Tag 后，可以选择生成版本文件。版本文件生成脚本位于 scripts/generate-version.js，会生成一个 version.json 文件到 public 目录。

5.1 版本文件内容 ​

json
{
  "version": "v1.0.0",
  "build": "abc123",
  "commitTime": "2025-12-17T10:00:00+08:00",
  "buildTime": "2025-12-17 10:00:00"
}
  • version：当前 Git Tag
  • build：Git Commit Hash（短版本）
  • commitTime：Git 提交时间
  • buildTime：版本文件生成时间

6. 版本检查机制 ​

项目中的 src/common/updateChecker.js 会定期检查版本更新，当发现新版本时会在控制台显示更新信息。

6.1 检查逻辑 ​

  1. 获取本地 version.json 文件中的版本信息
  2. 获取远程 version.json 文件中的版本信息
  3. 比较版本号和构建号
  4. 如果发现新版本，在控制台显示更新信息

6.2 控制台输出格式 ​

========================================
🔄 发现新版本！
========================================
┌─────────────────┬─────────────────────────┐
│    (index)     │          Values         │
├─────────────────┼─────────────────────────┤
│    本地版本     │        "v1.0.0"          │
│   本地构建号    │   "abc123"              │
│  本地提交时间   │  "2025-12-17T10:00:00..."│
│    远程版本     │        "v1.0.1"          │
│   远程构建号    │   "def456"              │
│  远程提交时间   │  "2025-12-17T11:00:00..."│
└─────────────────┴─────────────────────────┘
========================================

7. 完整的版本发布流程 ​

  1. 在开发分支完成功能开发和测试
  2. 合并到主分支（如 master 或 main）
  3. 运行 node scripts/git-tag-cli.js 创建 Git Tag
  4. 选择生成版本文件
  5. 选择构建项目
  6. 部署构建产物到服务器

8. 常用 Git Tag 命令 ​

8.1 查看所有标签 ​

bash
git tag

8.2 查看标签列表（带详细信息） ​

bash
git tag -l --format="%(refname:short)\t%(taggerdate:short)\t%(subject)"

8.3 按模式搜索标签 ​

bash
git tag -l "v1.*"  # 查看所有 v1.x.x 版本

8.4 按时间排序查看标签 ​

bash
git tag --sort=-creatordate  # 降序排列（最新的在前）
git tag --sort=creatordate   # 升序排列（最旧的在前）

8.5 查看标签详情 ​

bash
git show v1.0.0

8.6 创建轻量标签 ​

bash
git tag v1.0.0

8.7 创建带注释的标签 ​

bash
git tag -a v1.0.0 -m "版本 1.0.0 发布"

8.8 创建带签名的标签（GPG） ​

bash
git tag -s v1.0.0 -m "版本 1.0.0 发布"

8.9 验证签名标签 ​

bash
git tag -v v1.0.0

8.10 推送单个标签 ​

bash
git push origin v1.0.0

8.11 推送所有标签 ​

bash
git push origin --tags

8.12 删除本地标签 ​

bash
git tag -d v1.0.0

# 删除远程仓库的标签 (先删本地，再推送到远程)
git tag -d v1.0.0
git push origin :refs/tags/v1.0.0
# 或者使用更直观的删除远程标签命令 (Git v1.7.0 之后)
git push origin --delete v1.0.0

8.13 删除远程标签 ​

bash
git push origin :refs/tags/v1.0.0

8.14 批量删除本地标签 ​

bash
git tag -d $(git tag -l "v0.*")  # 删除所有 v0.x.x 版本的本地标签

8.15 批量删除远程标签 ​

bash
git push origin --delete $(git tag -l "v0.*")  # 删除所有 v0.x.x 版本的远程标签

8.16 切换到特定标签 ​

bash
git checkout v1.0.0

8.17 基于标签创建分支 ​

bash
git checkout -b branch-from-tag v1.0.0

8.18 查看标签的提交历史 ​

bash
git log v1.0.0 --oneline

8.19 查看特定版本范围的标签 ​

bash
git tag --merged master  # 查看已合并到 master 分支的标签

8.20 同步远程标签到本地 ​

bash
git fetch origin --tags

8.21 检查本地标签与远程标签的差异 ​

bash
git fetch origin
git tag -l > local-tags.txt
git ls-remote --tags origin | awk '{print $2}' | sed 's/refs\/tags\///' > remote-tags.txt
diff local-tags.txt remote-tags.txt

8.22 查看标签对应的提交哈希 ​

bash
git rev-parse v1.0.0

8.23 获取最近的标签 ​

bash
git describe --tags --abbrev=0

8.24 获取当前提交的标签及距离 ​

bash
git describe --tags  # 输出格式：v1.0.0-5-gabc123

8.25 列出包含特定提交的标签 ​

bash
git tag --contains abc123

9. 最佳实践 ​

  1. 只在稳定版本上创建 Git Tag
  2. 使用语义化版本号规范
  3. 为每个标签添加有意义的注释
  4. 定期清理不再使用的标签
  5. 确保在推送标签前所有更改都已提交
  6. 每次发布新版本时都生成版本文件

10. 常见问题 ​

10.1 如何处理未提交的更改 ​

如果有未提交的更改，工具会给出警告并询问是否继续。建议先提交或暂存更改，以确保标签指向正确的代码状态。

10.2 如何回滚标签 ​

如果创建了错误的标签，可以使用以下步骤回滚：

  1. 删除本地标签：git tag -d v1.0.0
  2. 删除远程标签：git push origin :refs/tags/v1.0.0
  3. 重新创建正确的标签

10.3 如何查看标签对应的提交 ​

bash
git show v1.0.0

10.4 如何在特定提交上创建标签 ​

bash
git tag -a v1.0.0 abc123 -m "版本 1.0.0 发布"

其中 abc123 是提交的哈希值。

11. 总结 ​

Git Tag 是管理软件版本的重要工具，本项目提供的交互式工具可以简化 Git Tag 的创建和推送流程。遵循语义化版本号规范和最佳实践，可以帮助团队更好地管理和追踪软件版本。

通过版本检查机制，用户可以及时了解到新版本的发布，提高软件的更新率和用户体验。

最近更新