用途:根据实际暂存变更(git diff --cached)生成提交消息,让读者不打开 diff 也能知道“改了什么、为什么改”。仅负责写消息,不执行暂存、拆分、提交或推送。
主要能力与工作流:
- 先看变更:运行 git status --short 和 git diff --cached --stat 确认已有暂存内容。若暂存区为空则停止并询问用户,绝不凭空编造提交消息。
- 选择类型:按变更选定唯一前缀(一个提交混合类型时应让用户拆分):feat(新功能)、fix(修复)、docs(仅文档)、refactor(行为不变的重构)、test(增改测试)、chore(构建、依赖、杂项)。
- 写标题:格式为 type: 英文祈使短语,≤50 字符,以动词开头(Add…、Fix…、Remove…、Unify…)。禁止“update code”“some changes”“fix bug”等空泛标题。
- 写主体(可选但推荐):1–3 行解释 why,而非逐步复述 how。修复必须写明触发条件;新功能应描述用户可见变化。
- 输出可直接运行的命令,而不是让用户自己拼装的纯文本。
可运行示例: git status --short git diff --cached --stat git commit -m "feat: add CAPTCHA verification to login endpoint" -m "Blocks automated credential stuffing; CAPTCHA valid 5 minutes, account locks 10 minutes after 3 failures." git commit -m "fix: keep order-list filters across pagination" -m "Trigger: filter first, then turn the page. Cause: page turns dropped the query params."
规则:标题面向快速浏览者,主体面向三个月后的自己,职责分离;功能与重构混合应拆成两个提交;消息不含“AI 生成”等元评论。
限制:只读暂存 diff,无法描述 diff 未体现的意图;why 不可推断时询问而非编造。50 字符标题与祈使语气是常见默认,仓库自有约定(Gitmoji、Jira 前缀、项目覆盖)优先。锁文件、压缩产物等生成或第三方变更汇总描述,不逐行列。反模式包括:对空暂存区写消息、把一切都标为 chore、超长标题、主体当实现日志。