Git提交信息与分支命名：让代码评审少返工的实操规范

现象：评审意见一半不在代码本身

很多合并请求被打回，不是因为算法写错，而是评审人第一眼看不懂：这次改动到底改了什么、为什么要改、改完怎么验证。提交信息只有“修复问题”“更新代码”，分支名叫“test1”“new-branch”，评审人只能逐行猜意图，猜错就返工。把提交信息和分支命名当成正式的工程文档来写，是成本最低的提效办法。

原则：一个提交只做一件事

提交是最小的评审单位，也是最小的回滚单位。一个提交里同时改功能、修样式、顺手重构三个文件，出问题时无法单独回滚，评审时也无法单独通过。正确的做法是按意图拆分：先做准备性的重构，再做功能改动，最后补测试和文档。每个提交都能独立编译、独立通过相关测试，这样评审人可以按顺序读，历史也更容易用二分查找定位回归。

提交信息：标题说明意图，正文说明证据

我常用的格式是“类型（范围）：动词开头的简短描述”，例如 feat（登录）：支持短信验证码登录，fix（订单）：修复金额为零时仍可提交的问题，docs（接口）：补充分页参数说明，refactor（缓存）：抽取公共的缓存键生成逻辑。标题控制在一行内，正文写三段：背景是线上遇到了什么现象或需求来自哪里；改动是改了哪些关键路径和判断条件；验证是跑了哪些测试、手动验证了哪些场景、还有哪些已知风险。

标题要避免“优化”“调整”“修改”等空词，因为它们没有说明方向。把“优化查询”改成“为订单列表查询增加用户维度索引，避免全表扫描”，评审人立刻知道收益和风险点。同样，避免在标题里写人名、写“紧急”之类无法长期理解的信息，紧急程度应该放在工单或合并请求的描述里，而不是写进永久历史。

分支命名：从名字就能判断用途和归属

分支名建议用“类型/工单号-简短描述”的形式，例如 feature/1024-sms-login、fix/1031-order-zero-amount、hotfix/1032-payment-timeout、docs/1033-api-pagination。类型说明分支的生命周期，工单号让分支和需求、缺陷一一对应，简短描述用小写和短横线，避免中文、空格和过长的句子。临时实验分支可以加个人标识，例如 experiment/zhangsan-cache-benchmark，到期要及时删除，不要长期留在仓库里。

拆分与整理：提交前先读一遍自己的历史

提交之前，先用 git status 和 git diff 检查改动范围，把调试代码、临时日志和无关文件排除在外。如果一个提交里混入了两件事，可以用 git add -p 按文件块挑选，用 git rebase -i 把顺序理顺、把重复的提交合并。整理历史不是造假，而是把“探索过程”翻译成“可读的交付过程”，就像写文章前要先列提纲。已经推送到公共分支的历史不要随意改写，改写只适用于自己本地、尚未被他人基于的分支。

合并前自查清单

第一，标题是否让不了解背景的人也能看懂意图；第二，正文是否写清背景、改动和验证；第三，一个提交是否只做一件事；第四，是否删除了调试代码和临时文件；第五，分支名是否包含类型和工单号；第六，是否跑过相关测试并说明结果；第七，是否标注了兼容性变化和回滚方式；第八，文档和注释是否同步更新。八条都通过，再发起评审，返工率会明显下降。

团队落地：模板比口号更有效

团队可以把提交模板放进仓库，例如 .gitmessage 模板，写好类型、范围和正文段落的提示，成员用 git config commit.template 指定它。代码评审时先看提交历史再看代码 diff，历史混乱的合并请求先退回整理，而不是边猜边审。经过两三个迭代，团队会形成共同的阅读习惯：新成员通过历史就能理解模块演进，老成员在排查问题时也能快速定位某次改动的上下文。

结语

好的提交信息和分支命名，本质上是对未来读者的负责。今天多花两分钟写清意图和证据，明天排查问题、做代码评审、做版本回滚时都能省下成倍的时间。先从下一个提交开始：一个提交一件事，标题说清意图，正文写清背景、改动和验证，分支名带上类型和工单号。