Git 工作流

使用常规提交格式和语义化版本控制，标准化的 Git 提交、拉取请求和发布流程。

前置条件

请勿在技能加载时主动验证这些工具。如果因缺少工具导致命令失败，请逐步引导用户完成安装与配置。

使用场景

• 创建提交：遵循常规提交规范，使用简洁、祈使语气的提交信息
• 创建拉取请求：生成包含清晰描述和测试计划的 PR
• 创建发布：更新版本号、CHANGELOG、标签以及 GitHub 发布

上述工作流可独立使用，也可按需组合使用。

平台检测

通过 git remote get-url origin 检测远程仓库地址，选择对应工作流：

快速参考

提交格式

类型(作用域): 简洁摘要

- 可选的项目符号（最多 3-4 项）
- 保持简短且聚焦

类型：feat、fix、refactor、docs、test、chore、style、ci、perf、build、revert

分支命名

• feature/功能描述
• fix/问题描述
• docs/文档描述
• refactor/重构描述
• test/测试描述

发布检查清单

1. 更新项目文件中的版本号
2. 更新 CHANGELOG.md
3. 提交：chore(release): bump version to x.y.z
4. 打标签：git tag v{version} && git push upstream v{version}
5. 使用 gh release create 创建 GitHub 发布

默认行为

• 保持消息简洁：提交信息和 PR 标题必须简明扼要。避免冗余词汇。差异内容已展示“做了什么”——消息应解释“为什么这么做”。
• 禁止 AI 签名：提交或 PR 中不得包含 Co-Authored-By: Claude、Generated with Claude Code 或任何 AI 标记。
• 提交后立即推送：提交后始终立即推送，不询问用户。

- 若已有上游追踪 → git push

- 若无上游追踪 → git push -u origin <branch>

• 单一职责提交：每个提交只做一件事。若更改涉及多个类型或作用域，应在推送前拆分为多个独立提交。
• PR/MR 描述为自然段落，非模板：包含主题 + 2-3 句说明“原因”的陈述句 + 一行 验证： / Verify:。描述中不得使用 Markdown 标题、表情符号列表或直接复制提交列表。完整格式与禁止模式详见 [examples-and-templates.md](references/examples-and-templates.md#pr-description)。

详细指南

参见 [examples-and-templates.md](references/examples-and-templates.md) 获取提交示例（正反对比）、PR 正文模板及 CHANGELOG 格式。

验证

使用 scripts/validate_commit.py 验证提交信息：

python3 scripts/validate_commit.py "feat(auth): add OAuth2 support"
python3 scripts/validate_commit.py --file .git/COMMIT_EDITMSG

验证器检查以下内容：

• 是否符合常规提交格式
• 主题行长度（小于 72 字符）
• 是否使用祈使语气
• 是否不存在 AI 生成标记
• 正文格式及项目符号数量

常用工作流

提交（默认：提交并推送）

git add <files>
git commit -m "feat(component): add new feature" && git push

拉取请求

git checkout -b feature/new-feature
# ... 进行修改，提交（按默认行为自动推送）...
gh pr create --title "feat(component): add new feature" --body "..."

发布

# 更新版本文件 + CHANGELOG.md
git add .
git commit -m "chore(release): bump version to 1.2.0" && git push
git tag v1.2.0 && git push upstream v1.2.0
gh release create v1.2.0 -R owner/repo --title "v1.2.0" --notes "..."

常见问题