跳转到内容
案例 生态 源码解读 文档

规范地撰写提交信息指南

干净的提交历史能大幅降低代码评审、bisect 和变更日志生成的难度。OpenCode 读取你的暂存 diff，按团队约定产出提交信息。

何时使用此案例

  • 完成一个功能，工作区堆着一堆无关改动。
  • 团队有提交信息规范，手写太繁琐。
  • 想有一份可随时 bisect 或回退的清晰历史。

前置配置

  • 在仓库里已安装 OpenCode
  • 一份 .gitmessage 模板或团队约定（Conventional Commits、自定义前缀等）
  • 工作区里已准备好的改动

步骤

  1. 检查暂存内容

    确认暂存区与你要提交的内容一致。

    git status
git diff --cached --stat

  2. 请求信息建议

    把 diff 给 OpenCode，让它给一条 Conventional Commit 建议。

    读取我的暂存 diff 并建议一条 Conventional Commit 信息。使用 type(scope): subject 格式。subject 用祈使语气，不超过 72 字符。body 应该解释 为什么，而不是 做了什么。

  3. 必要时取消暂存并重新分组

    如果 diff 混着多个不相关的修改，让 OpenCode 拆成逻辑提交。

    这个 diff 混了 bug 修复和重构。请建议怎么拆成两个提交，告诉我每个提交包含哪些文件，并给每个写一条提交信息。

  4. 逐组提交

    把每组分别 add 并提交，使用 OpenCode 建议的信息。

    git reset HEAD
git add <files-for-first-commit>
git commit -m "fix(parser): handle empty input without panic

Previously an empty input caused a nil deref in the lexer.
Added an early return and a unit test."

  5. 验证历史读起来顺畅

    看看最近几个 commit，确认它们讲了一个连贯的故事。

    git log --oneline -10

关键提示词

读取我的暂存 diff 并建议一条 Conventional Commit 信息。然后看看 diff 里是否混了多个不相关的修改，需要拆成独立 commit。如果需要，列出每个 commit 包含哪些文件，并给每个写一条信息。

验证重点

  • git log --oneline 读起来是一段连贯的叙事
  • 每个 commit 独立构建和测试通过
  • 信息符合团队约定（如 type(scope): subject）

常见坑点

  • 混关注点：“改错别字 + 加新功能 + 改格式”这种 commit 无法安全回退。先重新分组。
  • subject 太笼统：“fix stuff” 或 “update code” 对未来的你毫无帮助。始终要求具体 subject。
  • body 缺上下文：为什么 几乎不会从 diff 一眼看出。让 OpenCode 写 1-2 行 body。

相关文档

  • 策略 — 控制 OpenCode 如何在整个项目中应用变更
  • 配置 — 管理 OpenCode 行为的 opencode.json 文件

相关案例

相关文档

下一步