好的提交” vs “你的提交”：如何写出完美的 Git 提交信息

原创

用户10525067

修改于 2024-10-30 18:40:50

1780

“好的提交” vs “你的提交”：如何写出完美的 Git 提交信息

这么好的文章，点个赞价格关注吧❤❤~

为什么我们要在意编写清晰的提交信息？

提交是程序员工作的重要组成部分。它们就像代码上的糖霜，如果编写正确，它们会带来巨大的价值。一个写得好的提交信息变得不可或缺，因为它们提供了上下文——否则提交信息就没有存在的必要。

一个好的提交显示了一个开发者是否是一个好的合作者 — Peter Hutterer, Linux.

开发者中一个常见的错误是将 Git 仓库当作备份系统。随意提交以捕捉当前代码状态会阻碍你在未来检查代码库时理解过去的更改。像“WIP”，“午饭时间”，“今天的代码结束”，“我累死了”，“周末愉快团队”和“第一个提交”这样的提交信息只会使你的 Git 日志混乱，使你难以理解你做出的重要提交，因为这些信息没有任何附加价值。

试图推送到远程仓库时应避免的一些关键错误

**切勿单独对不同文件进行更改并提交**

单独对不同文件进行更改并提交可能会在查看提交历史或与其他团队成员协作时导致问题。理解更改的完整上下文及其相互关系变得具有挑战性。

例如，我正在构建一个在线商店。我不应该这样做：

# 单独对 header.js 进行更改并提交

git add header.js

git commit -m "改进头部布局"



# 单独对 footer.js 进行更改并提交

git add footer.js

git commit -m "优化页脚设计"

查看你的 Git 日志，这种提交结构会变得混乱，尤其是当你的提交历史增长时。

**提交应该清晰、简洁，并组织成逻辑单元**。例如，在完成代码布局部分并处理头部和页脚部分后，最好在完成这些更改后再一起提交：

# 将 header.js 和 footer.js 的更改暂存

git add header.js footer.js



# 将相关更改一起提交

git commit -m "增强 UI：头部和页脚改进"

我理解这在理论上听起来比实际操作容易。这就是为什么保持一个专门用于提交的私人分支是个好习惯，然后通过压缩将这些更改合并到你的主分支中。

创建专用分支进行私人提交

提交代码并不一定意味着它必须成为你 Git 日志中永久存在的一部分。将私人分支视为你的个人程序员草稿本——在这里你可以自由地进行实验而无需担心他人的审视。

想象一下这样的场景：你正在编码中间，需要暂时离开去休息一下，或者你要去吃晚饭。担心失去当前进度促使你提交更改——这是私人分支的完美使用案例。无论你是结束当天的编码还是只是想做一次即兴的提交，这些更改都会找到属于它们的私人分支。

commit [commit-hash]

Author: Your Name <your.email@example.com>

Date:   [Timestamp]

    WIP



commit [commit-hash]

Author: Your Name <your.email@example.com>

Date:   [Timestamp]

    提交前以防文件丢失



commit [commit-hash]

Author: Your Name <your.email@example.com>

Date:   [Timestamp]

    要去吃晚饭了



commit [commit-hash]

Author: Your Name <your.email@example.com>

Date:   [Timestamp]

    上厕所时间！

在协作环境中，重要的是使你的私人分支名称显而易见，因为你不能让这些类型的提交信息出现在公共分支中。

无论是通过显式命名分支还是直接与队友沟通，都要明确表示此分支内容不打算作为正在进行工作的基础。一个好的私人分支命名可以是：private/do-not-use-this

每个成为公共分支一部分的提交都必须体现一个精心制作、自包含、可逆且描述清晰的工作单元。

分支命名规范

为了便于管理和协作，从 develop 或 main 拉取的新分支应遵循以下命名规范：

**从 develop 拉取的新分支：**
格式：develop-姓名-功能-日期
示例：develop-john-new-feature-20241030
说明：这种命名方式清楚地表明了分支来源（develop），负责开发的人（姓名），功能或任务描述，以及创建日期。这有助于团队成员快速了解每个分支的来源和目的，从而提高协作效率。
**从 main 拉取的新分支：**
格式：main-fix
示例：main-login-bugfix
说明：这种命名方式表明了分支来源（main）以及修复内容。这种简洁明了的命名方式有助于快速定位修复相关的问题。

此外，还可以考虑以下几种常见情况：

**特性分支（Feature Branch）：**
格式：feature/功能描述
示例：feature/shopping-cart
说明：用于开发新功能或增强现有功能。
**修复分支（Bugfix Branch）：**
格式：bugfix/问题描述
示例：bugfix/navbar-crash
说明：用于修复代码中的 bug 或问题。
**发布分支（Release Branch）：**
格式：release/版本号
示例：release/1.0.0
说明：用于准备发布版本，通常包含最后的小修小补和测试。
**热修复分支（Hotfix Branch）：**
格式：hotfix/问题描述
示例：hotfix/security-patch
说明：用于紧急修复生产环境中的严重问题。

这种详细且一致的命名规范可以帮助团队成员迅速了解每个分支的用途，从而提高项目管理效率和协作体验。

案例分析：开发在线商店的购物车功能

让我们看看我们一直在开发的在线商店项目。在这个上下文中，你作为前端开发人员负责添加购物车功能。你的旅程如下：

你首先通过增强购物车部分的 CSS 展示效果并进行了相应的提交。在推进过程中，你为购物车引入了 JavaScript 功能，导致了另一次提交。在追求完美过程中，你注意到了文本对齐问题，并花时间优化 CSS，然后又进行了额外的一次提交。

继续工作，你发现并解决了与将产品添加到购物车时计数器行为相关的 bug。这次快速修复也被捕捉到了一个提交中。最后，你通过在点击结账按钮时引入加载动画来提升用户体验，以最终的一次决定性提交结束。

现在让我们看看 git 日志：

commit [commit-hash-1]

Author: Your Name <your.email@example.com>

Date:   [Timestamp]



    增强购物车部分 CSS 展示效果



commit [commit-hash-2]

Author: Your Name <your.email@example.com>

Date:   [Timestamp]



    为购物车引入 JavaScript 功能



commit [commit-hash-3]

Author: Your Name <your.email@example.com>

Date:   [Timestamp]



    优化 CSS 以解决文本对齐问题



commit [commit-hash-4]

Author: Your Name <your.email@example.com>

Date:   [Timestamp]



    修复与购物车行为相关的计数器 bug



commit [commit-hash-5]

Author: Your Name <your.email@example.com>

Date:   [Timestamp]



    为结账按钮引入加载动画

如果需要将这些更改与在线商店相关的其他功能分支中的其他提交合并，审核过程可能会变得具有挑战性。

如何修复这些日志中的问题？

首先切换到你的功能分支：

# 切换到名为 feature/cart-section 的功能分支

git checkout feature/cart-section

然后，将所有来自 private/do-not-use-this 分支中的 commits 合并压缩成 feature/cart-section 中的一条 commit 信息：

# 使用单个 commit 合并和压缩来自私人分支中的所有 commits 到功能分支中

git merge --squash private/do-not-use-this

合并和压缩后，你需要编写一条清晰且描述性的 commit 信息：

# 编写详细的 commit 信息

git commit -v -m "Feat：创建带有漂亮动画的购物车功能



增强了购物车部分 CSS 布局，解决了文本对齐问题，并优化布局以提高美观性和可读性。

"

编写完美提交信息的七条标准规则

这些规则提供了指南和最佳实践，以确保你的 commit 信息格式正确并传达清晰的信息。虽然具体规则可能因不同来源而有所不同，但总体目标是提高 commit 信息在 Git 版本控制系统中的可读性和可理解性。

规则1：限制主题行至50个字符（最多）。

编写 commit 信息主题行时，建议保持简洁和集中。主题行作为 commit 目的的快速摘要，最好限制在最多50个字符以内。

如果难以符合50字符限制，这可能表明对 commit 意图缺乏清晰认识。 commit 信息应清晰、简洁，并能够独立存在。通过遵守此字符限制，你被迫优先考虑最重要的信息，使团队和未来自己能够一目了然地了解更改性质。

规则2：仅大写主题行首字母。

编写 commit 信息时，使用标题大小写，仅大写主题行首字母，就像编写简短句子一样。将其余消息，包括任何附加细节，保持小写。

规则3：不要在主题行末尾加句号。

不在主题行末尾加句号部分是历史原因，部分是为了保持一致风格。惯例是将主题行视为标题或命令，因此它使用祈使语气（例如，“添加功能”或“修复 bug” 而不是“已添加功能”或“已修复 bug”）。省略末尾句号有助于强化这一惯例，并保持主题行简洁。

git commit -v -m "创建带有漂亮动画的购物车功能"

规则4：在主题行和正文之间留一空行。

虽然此指南看似奇怪，但它源于实用性。许多开发者使用没有自动换行功能的命令行界面，因此引入有意格式化规则以确保一致且易读的 commit 信息。

git commit -v -m "创建带有漂亮动画的购物车功能



正文...

"

规则5：正文行宽度限制为72个字符。

需要澄清的是，这一准则不是关于传统换行；相反，这种做法考虑到命令行用户可能会遇到超过72字符后截断的信息体的问题。

大多数情况下，你的信息会超过72个字符。在这种情况下，建议拆分文本并在下一行继续句子，如下所示：

git commit -v -m "创建带有漂亮动画的购物车功能



增强了购物车部分 CSS 布局，解决了文本对齐问题，并优化布局以提高美观性和可读性。

"

总之，用破折号或星号加空格表示项目符号是一种标准做法。此外，为提高组织清晰度，保持悬挂缩进也很重要。

规则6：使用祈使语气。

一种有价值的方法是编写 commit 信息时，以实现特定操作为基础来构建。如果应用此 commit，将完成某个动作。例如，不要这样：

git commit -m "修复布局页面上的 bug" ❌，

而要这样：

git commit -m "修复布局页面上的 bug" ✔。

换句话说，如果应用此 commit，它确实会修复布局页面上的 bug。

规则7：解释“什么”和“为什么”，但不解释“如何”。

限制 commit 信息到“什么”和“为什么”，创建简明但信息丰富的解释。寻求了解“如何”实现代码的人可以直接查看代码库。而应该突出改变了什么以及改变原因，包括哪个组件或区域受影响。

案例分析：Angular 的 Commit 信息实践

Angular 是有效 commit 消息实践的重要示例。 Angular 团队倡导在编写 commit 消息时使用特定前缀。这些前缀包括“chore: ,”“docs: ,”“style: ,”“feat: ,”“fix: ,”“refactor: ,”和“test: .”。通过使用这些前缀，commit 历史成为了解每个 commit 性质的重要资源。