Git 提交消息的写法 - 字数标准与最佳实践
8 分钟阅读
Git 提交消息是团队协作中最重要的沟通工具之一。良好的提交消息能让代码审查更高效，让项目历史更清晰。Git 版本控制书籍中也将提交消息的写法作为核心话题来讨论。
提交消息的标准格式
被广泛接受的 Git 提交消息格式由三部分组成：
标题行 (最多 50 字符)
正文 (每行 72 字符换行)
脚注 (可选)标题行和正文之间必须有一个空行。这是 Git 工具链正确解析提交消息的前提。
为什么是 50 字符和 72 字符
| 限制 | 字符数 | 技术原因 |
|---|---|---|
| 标题行 | 50 字符 (硬限制 72) | git log --oneline 的显示宽度；GitHub 在 72 字符处截断 |
| 正文换行 | 72 字符 | git log 默认缩进 4 字符，终端标准宽度 80 字符，80 - 4 - 4 = 72 |
50 字符的标题行限制源于 git log --oneline 的显示宽度。GitHub 的提交列表在 72 字符处截断标题，超出部分显示为省略号。将标题控制在 50 字符以内，可以确保在所有工具中完整显示。
72 字符的正文换行规则源于终端的标准宽度 (80 列)。git log 默认在左侧添加 4 个字符的缩进，右侧也预留 4 个字符的边距，因此正文的有效宽度为 72 字符。
Conventional Commits 规范
Conventional Commits 是一种结构化的提交消息格式，被越来越多的项目采用：
<type>(<scope>): <description>
[optional body]
[optional footer(s)]| 类型 (type) | 含义 | 示例 |
|---|---|---|
| feat | 新功能 | feat(auth): add OAuth2 login |
| fix | 修复 bug | fix(api): handle null response |
| docs | 文档变更 | docs: update API reference |
| style | 代码格式 (不影响逻辑) | style: fix indentation |
| refactor | 重构 (不改变功能) | refactor: extract helper function |
| test | 测试相关 | test: add unit tests for parser |
| chore | 构建/工具变更 | chore: update dependencies |
| perf | 性能优化 | perf: optimize database queries |
Conventional Commits 的优势在于可以自动生成 CHANGELOG、自动确定语义化版本号，以及让提交历史更加结构化和可搜索。
好的提交消息 vs 坏的提交消息
| ❌ 坏的示例 | ✅ 好的示例 | 改善点 |
|---|---|---|
| fix bug | fix(auth): prevent session timeout on idle | 明确了修复的内容和范围 |
| update | feat(dashboard): add real-time chart updates | 说明了具体的变更内容 |
| WIP | refactor(api): extract validation middleware | 描述了重构的具体操作 |
| asdfgh | docs: add deployment guide for production | 提供了有意义的描述 |
标题行的写作规则
- 使用祈使语气：写"Add feature"而不是"Added feature"或"Adding feature"。这与 Git 自动生成的消息 (如 "Merge branch") 保持一致。
- 首字母大写：标题行的第一个字母大写 (使用 Conventional Commits 时，type 小写，description 首字母大写)。
- 不加句号：标题行末尾不加句号。这是节省字符的惯例。
- 说明"做了什么"而非"怎么做的"："Fix login error"比"Change auth.js line 42"更有价值。
正文的写作指南
正文用于解释"为什么"做这个变更，而不是"做了什么" (标题已经说明了)。软件开发最佳实践中推荐在正文中包含以下信息：
- 变更的动机和背景
- 与之前实现方式的对比
- 可能的副作用或注意事项
- 相关的 Issue 或 PR 编号
中文提交消息的特殊考虑
虽然英文是 Git 提交消息的主流语言，但在中文团队中使用中文提交消息也是合理的选择。需要注意：
- 中文字符在等宽字体中通常占 2 个字符宽度，因此 50 字符的标题行实际上只能容纳约 25 个中文字符
- 72 字符的换行规则对应约 36 个中文字符
- 混合中英文时，注意字符宽度的计算
- Conventional Commits 的 type 和 scope 建议保持英文，description 可以使用中文
Git 工具中的字符限制
| 工具/平台 | 标题显示 | 截断行为 |
|---|---|---|
| git log --oneline | 完整显示 | 终端宽度截断 |
| GitHub 提交列表 | 72 字符 | 省略号截断 |
| GitHub PR 合并消息 | 完整显示 | 不截断 |
| GitLab 提交列表 | 72 字符 | 省略号截断 |
| VS Code 源代码管理 | 完整显示 | 50 字符处显示警告 |
总结
Git 提交消息的字数控制不是形式主义，而是确保团队协作效率和项目可维护性的实践。标题行 50 字符、正文 72 字符换行是经过时间验证的最佳实践。采用 Conventional Commits 规范可以进一步提升提交历史的结构化程度。写提交消息前使用字符计数器确认字数，养成良好的提交习惯。