让 Git Commit Message 更有料的技巧

在软件开发中，Git 是一个广泛使用的分布式版本控制系统，它帮助开发者管理项目的历史记录、协调团队协作、以及追踪代码的演变。在使用 Git 进行版本控制时，git commit 是最常用的命令之一，它允许开发者将代码的更改保存到仓库中。每次提交都需要提供一个简短的信息，即“commit message”，以描述本次提交的目的和内容。

良好的 commit message 不仅能提高项目的可维护性，还能促进团队间的沟通和协作。本文将探讨编写高质量 commit message 的重要性，并提供一些最佳实践和模板，帮助你在实际项目中应用这些技巧。

为什么 commit message 如此重要？

1. 代码历史的可读性：清晰的commit message 能帮助开发者快速理解项目的演变历史，尤其是在回顾代码变更或追踪问题时，良好的commit message 能极大提高效率。
2. 团队协作：在团队开发中，其他成员可能会查看你的commit message 以理解你所做的更改。如果commit message 模糊不清或没有足够的信息，可能会导致沟通问题甚至代码冲突。
3. 代码维护：随着时间的推移，开发者可能会忘记代码更改的具体原因。详细且清晰的commit message 能为未来的维护工作提供宝贵的背景信息，减少技术债务。

编写良好 commit message 的实践推荐

1. 简洁明了的标题行

commit message 的第一行应当是标题行，简明扼要地描述本次提交的主要内容。标题行应该限制在50个字符以内，并使用命令式语气，例如“Add”、“Fix”、“Update”等。这种语气使 commit message 更符合提交的语义，仿佛你在指示代码库要进行的更改。

示例：

feat(auth): add OAuth2.0 support

这条 commit message 明确说明了在认证模块中添加了OAuth2.0支持。feat 是一个常用的标识符，表示本次提交是一个新的功能（feature），后面的描述精简而有力。

2. 使用命令式语气

正如前面提到的，commit message 的标题行应使用命令式语气（如“Add”而不是“Added”）。这种语气不仅能明确表达意图，还能与 Git 的内部机制相吻合，形成一种自然的阅读流。

示例：

fix(ui): resolve button alignment issue in mobile view

在这个例子中，fix 表示这是一个修复提交，命令式的语气表明这个修复操作应在代码库中执行。

3. 保持标题和详细描述的分离

如果提交涉及复杂的更改或需要更多的背景信息来解释，应在标题行之后留一行空行，然后提供详细描述。这种做法可以使 commit message 的结构更清晰，标题行用于简要概述，而详细描述则提供更深入的解释。

示例：

refactor(auth): split authentication module into separate services

The authentication logic was split into separate classes to improve
testability and adhere to the single responsibility principle. This
refactor prepares the codebase for upcoming changes in the user
session management.

在这个例子中，标题行简明扼要，而详细描述解释了重构的原因和目的，这对于未来的维护至关重要。

4. 解释为什么，而不仅仅是做了什么

良好的 commit message 不仅要说明“做了什么”，还应解释“为什么要做”。这有助于团队成员和未来的维护者理解更改的背景和动机，避免重复劳动或误解。

示例：

remove deprecated API calls

The old API calls have been deprecated and will be removed in the next
major version. This commit updates our codebase to use the new API
calls to ensure compatibility with future versions.

这条 commit message 不仅描述了移除过时的 API 调用，还解释了这么做的原因，即为了保持与未来版本的兼容性。

5. 针对每次逻辑更改进行单独提交

每个提交应该只包含一个逻辑更改（如修复一个 bug 或添加一个 feature ）。这种做法有助于保持提交历史的清晰性，使得回溯和处理回滚时更加简单。如果你同时进行多个不相关的更改，应将其拆分成多个提交。

示例：

• 先提交一个用于修复 bug 的消息。
• 然后提交一个用于改进性能的消息。

通过这种方式，你可以确保每个提交都有明确的目的和边界。

6. 保持提交历史的整洁

在合并分支之前，可以使用 git rebase 或 git squash 来压缩历史，去掉不必要的中间提交或修正。保持提交历史简洁明了，有助于后期的代码审查和维护。

示例：

git rebase -i HEAD~3

这条命令允许你在最近的三次提交中进行交互式变基，你可以通过它合并或编辑 commit message ，使历史记录更加简洁。

7. 遵循团队的约定或风格指南

每个团队可能有自己的 commit message 格式或风格指南，遵循这些约定有助于保持整个项目的一致性。常见的格式有 Angular commit message 规范，使用 feat、fix、docs 等标识符来分类提交类型。

示例：

feat(auth): add JWT support for user sessions

这种格式不仅清晰，还能通过工具自动生成变更日志（changelog），帮助代码仓库管理。

8. 实现 commit message 与需求的关联

在许多项目中，开发工作与需求管理工具（如 JIRA、Trello）紧密关联。为了将 commit message 与需求对应起来，你可以在 commit message 中包含需求的唯一标识符（如 JIRA 任务编号、用户故事 ID 等）。

示例：

feat(auth): add OAuth2.0 support [PROJ-1234]

Implemented OAuth2.0 authentication mechanism to enhance security and
provide users with more login options. 

Closes PROJ-1234.

在这个例子中，[PROJ-1234] 是需求的唯一标识符，使用 Closes 关键字可以在提交后自动关闭相关任务。这不仅保持了提交与需求的一致性，还能方便追踪开发进度。

9. 自动化和工具支持

为了确保 commit message 的一致性，你可以使用 Git Hooks（如 prepare-commit-msg-hook ）来自动填充需求 ID 或检查commit message 格式。还可以结合 CI/CD 工具，通过脚本或插件自动验证 commit message 是否包含需求 ID。

示例 Git Hook 脚本：

#!/bin/sh
ISSUE_ID=$(git branch --show-current | grep -oE '[A-Z]+-[0-9]+')
if [ -n "$ISSUE_ID" ]; then
  echo "$ISSUE_ID: " | cat - "$1" > temp && mv temp "$1"
fi

这个 Hook 会在每次提交时自动在 commit message 前面加上分支名称中对应的需求 ID，确保 commit message 与需求实现关联。

结论

编写良好的 git commit message 是开发过程中至关重要的一部分。它不仅有助于项目的可维护性，还能提高团队协作效率，减少沟通成本。通过遵循本文中的推荐实践和模板，你可以编写出更加专业、易读且有价值的commit message ，为项目的长远成功打下坚实基础。

无论是在个人项目还是团队合作中，良好的 commit message 都是一种重要的编码素养。希望通过本文的分享，你能够在今后的开发工作中更好地应用这些技巧，为你的项目增色添彩。