如何编写一个优雅的commit message

在Git中，git commit 命令扮演着至关重要的角色。它的主要作用是将暂存区（staging area）里的改动内容提交到本地仓库（repository）中，形成一个新的版本或提交（commit）。这个过程是 Git 工作流程中的一个关键步骤，它允许开发者将他们的更改以逻辑上独立的单元进行保存，这些单元随后可以被追踪、共享、回滚或合并。

具体来说，git commit 命令的作用包括：

1）保存更改：当你对文件进行修改后，这些修改首先被 Git 跟踪为工作目录中的更改。通过 git add 命令，你可以将这些更改添加到暂存区（或称为索引区）。然后，git commit 命令将这些暂存的更改保存为一个新的提交（commit），这个提交包含了更改的元数据（如作者、提交者、日期、提交信息等）和更改的内容。

2）创建历史记录：每次提交都会创建一个新的版本，Git 会跟踪这些版本之间的变化，形成一个项目历史记录。这个历史记录允许你查看项目的演变过程，理解每个更改的上下文，以及回滚到以前的版本。

3）便于协作：在多人协作的项目中，git commit 使得每个开发者的更改都可以被清晰地记录和追踪。这有助于解决合并冲突、审查代码更改以及确保项目的稳定性和一致性。

4）促进版本控制：通过提交，Git 允许你管理项目的不同版本。你可以轻松地切换到项目的任何历史版本，比较不同版本之间的差异，以及基于旧版本创建新的分支。

使用 git commit 命令时，通常会附带一条提交信息（commit message），这条信息应该简洁明了地描述所做的更改。良好的提交信息实践有助于维护清晰的项目历史记录，并促进团队成员之间的有效沟通。

例如，提交一个更改的基本命令可能如下所示：

git add .  # 将所有更改添加到暂存区
git commit -m "添加新功能：用户注册页面"  # 提交更改并附上提交信息

在这个例子中，git add . 命令将所有更改添加到暂存区，而 git commit -m "添加新功能：用户注册页面" 命令则将这些更改提交到本地仓库，并附上了描述性的提交信息。

这篇文章我们先抛开Git这项技术不谈，单纯的了解下如何编写一个优雅的Commit Message

如何编写优雅的Commit Message

编写优雅的commit message是良好版本控制实践的一部分，它可以帮助团队成员更好地理解每次提交的目的和上下文。以下是一些编写优雅commit message的准则：

1）保持简短： 尽量让commit message的第一行简短且能够描述这次提交的核心内容。这通常被用作日志和版本历史中的标题。

2）使用清晰、具体的描述： 在简短标题之后，可以添加一个空行，然后添加更详细的描述。这个描述应该清晰地解释为什么需要这次提交，以及它是如何解决问题的。

3）使用动词开始： 尽量使用过去时态的动词来开始你的commit message，如“Add”, “Fix”, “Refactor”等，这有助于清晰地表达这次提交的动作。

4）引用相关的问题或任务： 如果你的提交与某个问题或任务相关，可以在commit message中引用该问题的编号或链接。这有助于跟踪和关联工作。

5）避免冗长和无关紧要的细节： 保持commit message的焦点在核心改动上，避免包含冗长的讨论或无关紧要的细节。

我们可以举个例子：

示例1：

Add user authentication feature

This commit adds a basic user authentication system to the application.
It includes a login form, a registration form, and a simple authentication
mechanism that checks user credentials against a database.

Fixes #123

这个commit message首先用简短的一行描述了主要改动（添加用户认证功能），然后通过详细描述进一步解释了改动的内容和目的，并最后通过Fixes #123关联到了一个具体的问题或任务。

优雅的commit message应该包含足够的信息，以便其他开发者（包括未来的你）能够迅速理解改动的内容、目的以及可能的影响。具体来说，一个优雅的commit message通常包含以下几个部分：

标题（Header） ：

• 简短描述：通常是一行，最多不超过50个字符（但这不是硬性规定，主要目的是保持简短）。
• 使用动词：以过去时态的动词开始，如“Add”, “Fix”, “Improve”, “Refactor”, “Remove”, “Update”等，清晰地表明这次提交的动作。
• 内容概述：简要概述这次提交的主要内容或目的。

正文（Body） （可选）：

• 详细解释：如果改动较为复杂或需要更详细的背景说明，可以在标题下方添加一个空行，然后编写正文部分。
• 原因：解释为什么进行这次改动，包括解决的具体问题、实现的功能或优化的点。
• 影响：描述改动可能带来的影响，包括对其他部分代码的依赖关系、需要特别注意的地方等。

尾注（Footer） （可选）：

• 关联问题：如果这次提交与某个问题或任务相关联，可以在尾注中引用该问题的编号或链接，例如“Closes #123”或“Fixes #456”。
• 破坏性变更：如果这次提交包含破坏性变更（Breaking Changes），应在此部分明确说明，以便其他开发者了解并做出相应调整。
• 其他元数据：根据需要，可以在尾注中添加其他元数据，如审核者、测试情况等。

参考开源项目的commit message

开源项目的commit message非常值得参考。开源项目通常由一群贡献者共同维护，他们遵循一定的编码标准和最佳实践，以确保项目的质量和可维护性。这些标准通常也包括编写清晰、有描述性的commit message。

1）Go：https://github.com/golang/go/commits/master/

首先我们看出go在GitHub开源仓库的commit message是非常有规律的，提交信息的标题都是以[修改包]:[变更内容]为主，我们选择一个commit进行查看：

https://github.com/golang/go/commit/d288776d9143370567fa56b44fa875d0e8fb02b6

cmd/compile: remove trivial closure reference

Trivial closures will be converted to global functions, thus they are
not closures anymore. Using fn.IsClosure function is enough, allow
removing the trivial/non-trivial closures in the code.

Change-Id: Iceb186dd92c1732b101e221ebc13406db35c69ea
Reviewed-on: https://go-review.googlesource.com/c/go/+/611995
......

也可以看出这个commit是非常详细的。

2）Grafana：https://github.com/grafana/grafana/commits/main/

Grafana的commit message虽然和go的内容组成不太一样，但是也保持着一定的规律。

我们随机查看一个具体的commit message：

https://github.com/grafana/grafana/commit/1c52d7b994b54e137d83343305a3cdf691d169b0

Docs: Update forward direction search for Loki entry (#92875)

只有标题部分，也是符合commit message原则的。

小总结

一个优雅的commit message在软件开发中具有多方面的作用，团队成员可以通过提交信息了解彼此的工作进度和更改内容，减少误解和冲突，也有助于代码审查者更快地理解提交的内容，从而提供更有效的反馈。同时，提交信息也可以作为讨论和改进代码的起点。除此之外，随着时间的推移，项目的开发历史会变得复杂和庞大。优雅的提交信息可以作为一个详细的、可搜索的历史记录，帮助开发者回顾过去的决策、修复回归问题以及理解系统的演进过程。那么就从现在开始，尝试着将自己的commit message编写的更加优雅。