Skip to content

Latest commit

 

History

History
295 lines (209 loc) · 8.67 KB

File metadata and controls

295 lines (209 loc) · 8.67 KB

GitHub Workflow Status (branch) GoDoc Coverage Status Supported Go Versions GitHub Release Go Report Card

tago

用 Golang 构建的 Git 标签智能版本管理。


英文文档

ENGLISH README

主要特性

🏷️ 智能标签管理: 自动创建和升级 Git 仓库的语义版本标签
版本基数系统: 支持可配置的版本进位机制(1/10/100)
🎯 交互式确认: 使用低版本基数时操作前询问,高版本基数启用自动模式
🌍 子模块支持: 支持主项目和子模块的独立标签管理
📋 语义版本控制: 遵循 v{major}.{minor}.{patch} 格式规范

安装

go install github.com/yylego/tago/cmd/tago@latest

使用方法

查看标签列表

tago

输出示例:

refs/tags/v0.0.0 Wed Feb 12 16:18:18 2025 +0700
refs/tags/v0.0.1 Thu Feb 13 16:43:08 2025 +0700
refs/tags/v0.0.2 Thu Feb 13 18:43:40 2025 +0700
refs/tags/v0.0.3 Wed Apr 30 15:18:56 2025 +0700
refs/tags/v0.0.4 Wed May 7 18:38:38 2025 +0700

初始化仓库第一个标签

当仓库中不存在标签时创建第一个标签:

# 创建 v0.0.0 标签(默认)
tago init

# 创建自定义版本标签
tago init --major=1 --minor=0 --patch=0
tago init -a=0 -b=1 -c=0

init 命令智能处理这些场景:

  • 不存在标签:通过交互式确认创建新标签
  • 存在不同标签:报告已存在的标签并阻止执行
  • 相同标签存在于当前提交:跳过创建,询问是否推送
  • 相同标签存在于不同提交:报告提交不匹配并阻止执行

示例工作流:

# 首次运行 - 创建标签
$ tago init
Create tag v0.0.0? (Y/n): Y
Push tag v0.0.0 to remote? (Y/n): Y
SUCCESS

# 如果标签已存在于当前提交 - 询问推送操作
$ tago init
Tag v0.0.0 exists at current commit
Push tag v0.0.0 to remote? (Y/n): Y
SUCCESS

升级标签版本(交互模式)

从 va.b.c 升级到 va.b.c+1 并推送新标签,会要求用户确认:

tago bump

输出:

cd xxx && git push origin v0.0.5

升级标签版本(自动模式)

从 va.b.c 升级到 va.b.c+1 并推送新标签,无需用户确认:

tago bump -b=100

输出:

cd xxx && git push origin v0.0.5

主项目标签管理

在主项目根目录工作时:

tago bump main
tago bump main -b=10

子模块标签管理

在子模块目录工作时(带路径前缀):

cd submodule-dir
tago bump sub-module
tago bump sub-module -b=100

使用要求

  • Git 仓库: 必须在有效的 Git 仓库中运行
  • Git 分支: 假设主分支名称是 "main"(不是 "master")
  • 标签格式: 标签必须遵循语义化版本 v{major}.{minor}.{patch} 格式

版本基数系统说明

版本基数(-b 选项)控制版本号的进位机制:

  • 0 和 1: 交互模式,每次操作前询问确认
  • ≥ 2: 自动模式,支持版本号自动进位

版本进位示例

假设版本基数设置成 10:

  • v1.2.9v1.3.0(patch 达到基数时进位到 minor)
  • v1.9.8v1.9.9(标准递增)
  • v1.9.9v2.0.0(minor 达到基数时进位到 major)

高级用法

命令组合示例

# 查看当前标签
tago

# 升级标签(需确认)
tago bump

# 快速升级不需确认
tago bump -b=100

# 主项目标签升级
tago bump main -b=10

# 子模块标签升级(在子模块目录中运行)
cd my-submodule
tago bump sub-module -b=10

版本管理工作流

  1. 当开发完成时:运行 tago 查看当前标签
  2. 创建新版本:运行 tago bump 升级版本
  3. 自动化场景:使用 tago bump -b=100 跳过确认
  4. 多模块项目:根据上下文使用对应的子命令

核心能力

智能版本管理

  • 自动解析现有标签格式
  • 支持语义版本控制规范
  • 处理版本号进位逻辑
  • 验证 Git 仓库状态

灵活的确认机制

  • 低版本基数:交互式确认每个操作
  • 高版本基数:自动执行,适合脚本化场景
  • 简单有效的提示信息
  • 操作可取消性

多项目架构支持

  • 主项目标签:v{major}.{minor}.{patch}
  • 子模块标签:{path}/v{major}.{minor}.{patch}
  • 路径感知的标签管理
  • Git 子模块兼容设计

故障排查

常见问题

问题: "no tag found in repo"

  • 原因: 仓库中没有现有标签
  • 解决: 使用 init 命令:tago init 通过交互式确认创建第一个标签

问题: "not in submodule path"

  • 原因: 在项目根目录运行 tago bump sub-module 而不是在子模块目录
  • 解决: 进入子模块目录后再运行命令

问题: "tag format mismatch"

  • 原因: 现有标签不符合要求的 v{major}.{minor}.{patch} 格式
  • 解决: 确保标签遵循语义化版本格式(例如 v1.2.3,而不是 v1.2 / 1.2.3)

问题: "no matching tag found"

  • 原因: 没有找到匹配预期模式的标签(例如,查找主项目标签但仅存在子模块标签)
  • 解决: 根据命令上下文创建适当格式的标签(main vs sub-module)

问题: 推送失败 "origin does not seem to be a git repository"

  • 原因: 没有配置远程仓库
  • 解决: 添加远程仓库:git remote add origin <url> 或使用 -b=0 跳过自动推送

标签格式要求

  • 有效格式: v0.0.1, v1.2.3, v10.20.30
  • 无效格式: v1.2, 1.2.3, version-1.2.3, v1.2.x
  • 子模块标签: mymodule/v1.2.3, path/to/module/v0.1.0

📄 许可证类型

MIT 许可证 - 详见 LICENSE


💬 联系与反馈

非常欢迎贡献代码!报告 BUG、建议功能、贡献代码:

  • 🐛 问题报告? 在 GitHub 上提交问题并附上重现步骤
  • 💡 新颖思路? 创建 issue 讨论
  • 📖 文档疑惑? 报告问题,帮助我们完善文档
  • 🚀 需要功能? 分享使用场景,帮助理解需求
  • 性能瓶颈? 报告慢操作,协助解决性能问题
  • 🔧 配置困扰? 询问复杂设置的相关问题
  • 📢 关注进展? 关注仓库以获取新版本和功能
  • 🌟 成功案例? 分享这个包如何改善工作流程
  • 💬 反馈意见? 欢迎提出建议和意见

🔧 代码贡献

新代码贡献,请遵循此流程:

  1. Fork:在 GitHub 上 Fork 仓库(使用网页界面)
  2. 克隆:克隆 Fork 的项目(git clone https://github.com/yourname/repo-name.git
  3. 导航:进入克隆的项目(cd repo-name
  4. 分支:创建功能分支(git checkout -b feature/xxx
  5. 编码:实现您的更改并编写全面的测试
  6. 测试:(Golang 项目)确保测试通过(go test ./...)并遵循 Go 代码风格约定
  7. 文档:面向用户的更改需要更新文档
  8. 暂存:暂存更改(git add .
  9. 提交:提交更改(git commit -m "Add feature xxx")确保向后兼容的代码
  10. 推送:推送到分支(git push origin feature/xxx
  11. PR:在 GitHub 上打开 Merge Request(在 GitHub 网页上)并提供详细描述

请确保测试通过并包含相关的文档更新。


🌟 项目支持

非常欢迎通过提交 Merge Request 和报告问题来贡献此项目。

项目支持:

  • 给予星标如果项目对您有帮助
  • 🤝 分享项目给团队成员和(golang)编程朋友
  • 📝 撰写博客关于开发工具和工作流程 - 我们提供写作支持
  • 🌟 加入生态 - 致力于支持开源和(golang)开发场景

祝你用这个包编程愉快! 🎉🎉🎉


GitHub 标星点赞

Stargazers