如何编写一个优雅的commit message

2024-09-11 23:08:24 浏览数 (3)

在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),这条信息应该简洁明了地描述所做的更改。良好的提交信息实践有助于维护清晰的项目历史记录,并促进团队成员之间的有效沟通。

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

代码语言:bash复制
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

代码语言:shell复制
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

代码语言:shell复制
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

代码语言:shell复制
Docs: Update forward direction search for Loki entry (#92875)

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

小总结

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

1 人点赞