你是否曾在 `git log` 中看到过“fix bug”或“update”这样模糊的提交信息？当需要回溯代码变更时，这种信息几乎毫无帮助。清晰的 Git 提交信息是团队协作的基石，它让代码历史变得可读、可追溯。本文将从实际问题出发，提供一套实用的提交信息规范，帮助你写出高质量的提交消息。
为什么提交信息如此重要
提交信息不仅是对代码变更的简单描述，更是项目历史的“日志”。清晰的提交信息可以让你在几个月后快速理解某次变更的原因和内容，也能让协作者（包括未来的自己）通过 `git log` 高效地定位问题。相反，模糊的提交信息会导致调试成本增加，甚至引发误解。
提交信息的基本结构
一条结构良好的提交信息通常包含三个部分：主题行（subject）、正文（body）和脚注（footer）。主题行是必填的，正文和脚注根据情况选用。
<type>(<scope>): <subject>
<body>
<footer>
主题行：简洁而明确
主题行是对本次提交的简短总结，通常不超过 50 个字符。它应该使用祈使句，如“Add new feature”而不是“Added new feature”。主题行中要避免使用句号结尾，并尽量保持动词开头。
常见的类型前缀包括：
- feat：新功能
- fix：修复 bug
- docs：文档变更
- style：代码格式调整（不影响逻辑）
- refactor：重构（不新增功能或修复）
- test：测试相关
- chore：构建、工具或依赖变更
例如：feat(auth): add login endpoint 比 add login 更具信息量。
正文：解释“为什么”和“怎么做”
当提交内容复杂时，正文可以详细说明变更的背景、动机和实现方式。正文与主题行之间用空行分隔，每行不超过 72 个字符。正文应回答“为什么需要这个变更”以及“它如何解决问题”，而不是重复代码细节。
例如：
fix(parser): handle unicode escaping in strings
The previous parser failed on strings containing unicode escape sequences,
causing incorrect output for non-ASCII characters. This change adds proper
handling by decoding escapes before tokenization.
脚注：引用问题和相关提交
脚注通常用于引用 issue 编号、关联的提交或破坏性变更（BREAKING CHANGE）。例如：
BREAKING CHANGE: the `login` function now requires a `tenant` parameter.
Closes #123
常见误区与失败条件
编写提交信息时，有几个常见误区需要注意：
- 主题行过长：超过 50 字符的信息在 `git log` 中会被截断，导致信息不完整。
- 信息过于模糊：如“update”或“fix”，无法传达具体变更内容。
- 缺少上下文：如果提交是为了修复某个 issue，务必在脚注中注明。
- 使用过去时：主题行应使用祈使句，而非过去时。
实操建议：如何逐步编写提交信息
以下是一个可操作的流程，帮助你写出规范的提交信息：
- 先提交代码：确保代码变更完整且可编译。
- 思考变更内容：问自己“我完成了什么？”和“为什么这样做？”
- 写主题行：用祈使句，简洁描述，不超过 50 字符。
- 补充正文：如果变更复杂，用几个要点解释动机和实现。
- 添加脚注：如果涉及 issue 或破坏性变更，务必注明。
- 检查并提交：使用
git commit提交，必要时用git commit --amend修改。
不同场景下的提交信息示例
以下是一些实际场景的示例，供你参考：
- 修复 bug：
fix(cache): clear cache on logout to prevent stale sessions - 新增功能：
feat(api): add pagination support to list endpoints - 重构代码：
refactor(utils): extract date formatting into shared module - 更新文档：
docs(readme): update installation instructions
总结与进一步阅读
清晰的 Git 提交信息是良好工程实践的一部分。通过遵循上述规范，你可以显著提升代码库的可维护性。当然，这些规范并非强制，团队可以根据自身情况调整，但一致性是关键。
如果你希望深入了解相关技术，可以参考 Python 官方文档 和 MDN Web 文档，它们提供了丰富的技术资源。此外，你也可以浏览 Git 版本控制 技术文章 获取更多相关内容。
参考资料
延伸阅读