git-commit

Git Commit

概述

根据仓库中的实际变更编写提交消息。优先使用简洁、聚焦意图的消息，而不是逐个文件总结差异。将 references/commit-convention.md 作为基准风格指南，再根据当前仓库调整范围和措辞。

工作流

1. 先检查变更集。

   • 有暂存变更时，优先使用 git diff --staged。
   • 没有暂存差异，或用户询问未暂存的变更时，使用 git diff。
   • 使用 git status --short 了解文件范围。
   • 如果仓库包含提交规范文件，请先阅读再编写消息。检查可能的文件名，例如 COMMIT_CONVENTION.md、CONTRIBUTING.md、.github/COMMIT_CONVENTION.md 或 .github/CONTRIBUTING.md。
   • 使用 git log --format=%s -n 20 检查近期提交主题，以判断仓库偏好的输出语言。遵循历史记录中占主导地位的语言。如果近期提交主题语言混杂，无法判断主导语言，或者没有提交历史或其他错误导致无法检查，则默认使用英语。

2. 选择一种提交意图。

   • 如果变更包含无关的意图，建议拆分提交。
   • 如果用户仍希望使用一条消息，则选择占主导地位的意图，并简要说明取舍。

3. 选择标题：

<type>(<scope>): <subject>

4. 仅在有助于说明意图、影响、兼容性、迁移或混合变更类型时添加正文。

类型选择

• feat：新功能
• fix：错误或缺陷修复
• perf：性能改进
• refactor：重构实现，但不改变外部行为
• style：仅调整格式或代码风格
• test：新增或调整测试
• docs：文档或注释
• chore：依赖、构建、脚手架和其他杂项维护
• ci：CI 变更
• types：类型定义变更
• revert：撤销已有提交
• wip：临时的进行中提交

对于混合变更，可以拆分提交，也可以在标题中使用占主导地位的类型，并在正文的项目符号前添加类型前缀。

范围选择

根据当前仓库确定 scope。除非参考文件中的范围与实际变更路径或本地惯例相符，否则不要沿用。

按以下优先级选择：

1. 使用仓库自身提交规范中明确规定的范围。
2. 使用变更路径中的稳定工作区、软件包、应用或模块名称，例如 api、web、cli、core、ui、docs 或软件包名称。
3. 仅当变更明显集中在某个子模块，且其名称可复用时，才使用更精确的长期子模块名称。
4. 对仓库级、跨领域或无法归入单一模块的变更，使用 repo。

如果仓库规范不要求有意义的范围，且本地风格允许不带范围的标题，则可以省略范围。

主题和正文

将主题写成变更的核心意图。保持简短、具体且以行动为导向。避免使用 update、fix bug 或 optimize code 等含糊主题。

根据仓库近期提交历史匹配输出语言。能明确判断时，使用占主导地位的语言。如果近期历史语言不一致或混杂，或者没有提交历史或发生其他检查错误，则默认使用英语编写提交消息。

在有帮助时编写正文：

• 说明意图、影响和必要背景。
• 避免逐项重复每个变更文件。
• 如果所有项目符号都属于同一变更类型，则不必在每条前重复类型。
• 如果提交混合了多种变更类型，则在正文项目符号前添加 type:。

示例：

feat(auth): add session refresh flow

- 增加会话刷新入口，减少登录态过期后的重复认证
- 补齐旧 token 兼容逻辑，避免升级后状态丢失

refactor: align release workflow

- refactor: 收敛构建与发布脚本的职责边界
- fix: 修正缺少版本号时的默认值异常
- docs: 补充新的发布流程说明

参考

阅读 references/commit-convention.md，了解 Conventional Commits 的基准规则和示例。根据当前仓库的结构覆盖其中的范围示例。