为什么我们需要 Git 提交规范？——从一段“无注释”提交记录说起

问题背景： 接手了一个 "沉默"的老项目

前段时间我接手了一个后端老项目，该项目没有任何系统说明文档。当我尝试通过git提交记录来理解代码的演进过程时，看到了很多类似于这样的提交记录：

在最近文件更新中大部分提交没有注释，要么只有极其简略的描述。这种现象在不少老项目中普遍存在，但却给后续的维护者带来了巨大困扰。

不规范提交的典型问题

历史追溯困难

• ”新建文件”是什么文件？为什么要创建？
• “接口修改”具体修改了什么？解决了什么问题？
• 更是让人完全无法理解这次提交的意图

协作效率低下

• 团队成员无法快速理解他人的工作
• Code Review 时难以判断变更的合理性
• 排查问题时无法精准定位相关提交

项目维护成本增加

• 新成员需要花费大量时间理解代码演变过程
• 修复 Bug 时难以确定引入问题的具体提交
• 版本发布时无法准确生成变更日志

Git 提交规范的解决方案

基本要求：提交信息的结构化

一个好的提交信息应该包含三个部分：标题、正文、页脚。而标题又具有特殊格式，包括修改类型、形象范围，修改类型和标题必输

<类型>(<范围>): <主题>

<正文>

<页脚>

提交类型示例

config 为自定义类型，并非来自原始规范。

标题： 简单明了，不要超过 100 字。字太多在列表页显示不下会被省略号替代。

影响范围: 在需要特别注意的时候才出现，主要用于强调。（考虑到实用性，和原规范略有不同）。采用类似 URLPath 匹配的格式简要说明。

• *：影响整个工程
• sys-server*：影响 sys-server 整个模块
• \\VO：影响所有 VO 对象
• api\\account*：影响 account 相关接口

页脚说明： 用于标记关联信息

• 缺陷编号：http://bug-system.com/id/123
• 关联 Issue：Closes #45
• 相关人员：@张三 提示关注
• 破坏性变更：BREAKING CHANGE: 接口参数结构调整 ### 优秀提交信息示例

# 反面例子（应避免）
git commit –m "修改"
git commit –m "fix bug"
git commit –m "更新"

# 正面例子（推荐）
git commit –m "feat(user): 添加用户注册功能

– 实现手机号验证注册
– 添加短信验证码校验
– 完善用户信息初始保存逻辑

Closes #123"

重要 在提交前，请确保代码可执行，可打包， 否则其他同事可能会 🙂

总结

良好的 Git提交规范不仅是一种技术约定，更是一种团队协作文化。它像代码的“时间胶囊”，让每个提交都能清晰地向未来（包括未来的自己）讲述当时的故事。从今天开始，让我们告别> <no comment>，用有意义的提交信息，为项目的可持续发展打下坚实基础。 记住：好的提交信息，就是最好的文档。 点击链接查看 git相关知识笔记总结