提交信息别只写update：约定式提交让Git历史变成文档
打开很多项目的git log，你会看到这样的历史：“update”“修改”“fix bug”“1”“aa”。三个月后回看，没人说得清每次提交改了什么、为什么改；想用git blame追一个bug的引入点，翻十页都是无效信息。提交信息是写给别人（包括未来的自己）看的，而“update”三个字等于什么都没说。约定式提交（Conventional Commits）就是解决这个问题的轻量级规范——它不要求你写长篇大论，只要求提交信息遵循一套统一结构，让历史从“流水账”变成“可读的文档”。
为什么提交信息值得规范
Git历史是项目最忠实的时间线，而提交信息是这条时间线上唯一的注释。规范提交信息有三个直接收益。第一，可追溯：线上出问题时，git bisect配合清晰的提交信息，能快速定位“哪个提交引入了回归”；如果每条提交都写“fix”，定位只能靠猜。第二，可协作：code review时，审查者通过提交信息就能判断改动意图是否合理，不用逐行猜你在想什么；新成员接手模块，读提交历史就像读一份按时间排序的设计笔记。第三，可自动化：规范的结构化信息能让工具自动生成变更日志（CHANGELOG）、按语义化版本自动判断版本号，这些在“update”式提交下完全无法实现。
约定式提交的格式与常用类型
约定式提交的格式很简单：<类型>[可选范围]: <描述>，必要时加正文和脚注。例如“feat(user): 增加手机号登录”或“fix(cart): 修复并发下单库存超卖”。常见的类型与含义对应关系如下：
- feat：新增功能，对应语义化版本的小版本（minor）升级，比如“feat: 支持批量导出”。
- fix：修复bug，对应补丁版本（patch），比如“fix: 修复金额精度丢失问题”。
- refactor：重构，不新增功能也不修bug，只是改进内部实现，比如“refactor: 抽取公共校验逻辑”。
- perf：性能优化，“perf: 列表渲染改为虚拟滚动，首屏时间降低40%”。
- docs / test / style / build / ci / chore：分别对应文档、测试、格式调整、构建系统、CI配置和其他杂项改动。
- BREAKING CHANGE：破坏性变更必须标注，放在脚注或类型后加感叹号（如“feat(api)!: 重构订单接口参数”），它对应主版本（major）升级，是下游团队最需要警惕的信号。
描述部分用祈使句、小写开头、不超过50个字符为宜，说“做了什么”而不是“做了什么和怎么做的”——怎么做的属于代码，提交信息只需说明意图。复杂的提交把“为什么这么做”写进正文，用空行与标题隔开，比如补充“回退此改动的原因：该方案在低端机型上内存超限”。
一个真实场景：一次线上事故的定位速度
某团队上线新版本后接到大量投诉：用户优惠券无法使用。运维立刻回滚，随后开始定位引入问题的提交。这个团队的提交信息规范，git log里清楚地列着“feat(coupon): 接入新的核销接口”“refactor(coupon): 调整优惠券状态机”，排查者直接锁定了几天前那笔feat提交，打开diff发现是接口字段映射写错，前后不到半小时。团队负责人说，过去在“update”式历史里找这种问题，至少要人肉翻遍一周的改动，有时还要逐个问“这段是你写的吗”。规范提交信息省下的不只是半小时，而是每次事故里最宝贵的定位时间。
常见误区与避坑
- 误区一：为了规范而规范，一条提交塞一堆改动。约定式提交的前提是“小步提交”：一个逻辑单元一个提交。把十个不相关的改动塞进一条“feat: 各种更新”，再规范也没用。
- 误区二：类型滥用。把所有改动都写成fix或feat，规范就失去了信息量。拿不准时按“是否影响对外行为”判断：影响用户功能的是feat或fix，不影响的是refactor或chore。
- 误区三：只写类型不写范围。“fix: 修复问题”和“fix(user): 修复注册页手机号校验”的信息量天差地别。涉及模块时尽量带上范围，哪怕只是文件名级别的提示。
- 误区四：强制规范却不给工具。靠口头提醒坚持不了两周。用commitlint在提交时做格式校验，用husky挂钩子，让不合规的提交直接进不了历史，规范才能落地。
行动建议
如果你是个人项目，从今天起把提交信息从“update”改成约定式格式，坚持两周你会习惯；如果你是团队一员，建议做三件事：在仓库加commitlint配置强制格式校验；把常用类型表贴进团队Wiki或README；在code review时把“提交信息是否清晰”列为检查项。一个月后，当有人能靠git log在五分钟内回答“这个功能为什么这么写”时，你会明白：规范的提交信息不是形式主义，它是团队把代码历史当作资产来经营的第一步。