如何进行良好的 Git 提交

2025-06-10

如何进行良好的 Git 提交

本文原发表于我的个人博客。

Git 是开发高质量软件的重要工具，其使用已成为业界的普遍模式。它具有多种功能，使我们编写代码更加轻松，其中之一就是创建提交的功能。

Git 是一个重要的文档工具。项目的提交历史记录是查看代码和软件随时间演变的绝佳途径。在很多情况下，掌握这些信息非常有用。

在本文中，您将更好地了解此 Git 功能并学习如何使用它的良好实践。

什么是提交

Git 是一个版本控制工具。这意味着它用于控制软件项目随时间的变化和发展，而提交是实现这一目标的主要工具。

提交就像项目的快照，它显示了项目代码在某个时间点的状态。Git 提供了一些工具，允许您检查每次提交时的项目状态。这带来了一些好处，例如，您可以更有信心地对项目进行新的更改（因为如果出现问题，更改可以轻松还原）；或者，您可以更轻松地调试代码，因为您可以在不同的时间点运行项目，从而准确地了解不良行为的发生时间。

这表明 Git 是软件项目文档管理的重要工具。如果您需要了解某个功能何时添加到项目中，或者某个外部库何时被内部解决方案替换，项目的提交历史记录可以为您提供帮助。

但为了获得这些好处，项目需要拥有良好的提交历史。以下是一些关于如何进行良好提交的技巧，它们可以帮助未来需要维护此代码的人（如果这个人就是您自己）。

如何提交

创建提交有两个主要步骤：选择要包含在提交中的更改，以及创建提交本身。

您可以使用以下git status命令检查自上次提交以来项目中更新了哪些文件：

On branch my-branch-name
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified:   index.html
    modified:   index.css

Untracked files:
  (use "git add <file>..." to include in what will be committed)
    images/my-image.png
Enter fullscreen mode Exit fullscreen mode

知道了哪些文件被修改了，你就可以运行以下git add命令来暂存某个文件，以便将其包含在下一次提交中。在本例中，如果你想创建一个包含index.html和index.css文件的提交，则可以运行git add以下命令，将两个文件都暂存：

git add index.html
git add index.css
Enter fullscreen mode Exit fullscreen mode

如果您想要暂存项目中修改过的所有文件以供下次提交，您可以通过运行来实现git add .。

您git status还可以看到哪些文件暂存于该changes to be committed部分：

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
  modified:   index.html
  modified:   index.css
  new file:   my-image.png
Enter fullscreen mode Exit fullscreen mode

文件暂存后，我们现在可以运行git commit并创建提交本身。此命令将打开一个文本编辑器，其中包含一个文件，其中显示了以下格式的提交更改：


# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# On branch translate-nerves-page
# Changes to be committed:
#       modified:   index.html
#       modified:   index.css
#       new file:   my-image.png
Enter fullscreen mode Exit fullscreen mode

这里我们必须使用编辑器来写一个提交信息，用一个空行来分隔标题和信息正文：

Commit message title

Commit message body. This is an optional text where you can
explain with details that change being made in commit. Use
this space to explain what is changing and why the changes
are happenning.

Use a blank line before a new paragraph e wrap the lines to
about 72 characters.

 - Bullet points are okay

 - Typically hypens (-) or asterisks (*) are used for the
   bullets, preceeded by a single space with blank lines
   in between, but conventions may vary

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# On branch translate-nerves-page
# Changes to be committed:
#       modified:   index.html
#       modified:   index.css
#       new file:   my-image.png
Enter fullscreen mode Exit fullscreen mode

如果您不想添加消息正文，则可以运行带有-m标志的提交命令，将消息标题传递到引号之间：

git commit -m "Commit message title"
Enter fullscreen mode Exit fullscreen mode

一次提交应该包含多少代码

一次好的提交只做一件事。它让我们更容易理解项目随着时间的推移是如何发展的，并且在出现问题时可以恢复更改。

例如，假设您需要在项目中实现一个新功能，并开始为此编写代码。一段时间后，您意识到这个新功能的代码需要调用系统其他部分的一个模块，但这个模块非常混乱且难以理解。由于您已经在处理这个模块，因此您决定在返回新功能代码之前，先快速重构一下这个模块。

代码写好后，你开始编写自动化测试。整个过程进展顺利，但你发现测试库中有一个配置被禁用了，如果启用它，测试套件的执行效果会更好。于是你继续在项目中启用这个配置。

工作已完成，是时候做出承诺了。

在这种情况下，创建三个不同的提交是合理的：一个用于更改测试库配置，一个用于代码重构，第三个用于新功能（包括测试）。这听起来可能有些多余，但它可以改善项目的提交历史记录。针对不同的更改创建不同的提交，可以方便地在将来需要时恢复更改。

例如，如果团队决定使用这个新的测试配置不会增加太多价值，或者重构导致了错误，则可以恢复仅执行此操作的提交，而不必恢复功能代码。

一次提交只做一次更改非常重要。无论是修改一行代码，还是修改多个不同的文件。需要记住的是，提交的内容将来可以被访问和撤销。在创建提交时牢记这一点，有助于您衡量一次提交包含多少代码。

提交消息

提交消息用于记录提交内容。良好的提交消息对于良好的提交至关重要，因为它可以更轻松地理解项目在每个时间点发生的事情。提交消息分为两部分：标题和正文。

标题

提交消息标题是一个简洁的短语，用于说明提交的内容。它必须简洁、描述性强且具体。

例如，检查以下三个提交：

623509 style buttons
f12144 bugfix
23c30c refactoring
Enter fullscreen mode Exit fullscreen mode

虽然这些信息描述了提交的操作，但它们太过笼统。请与以下示例进行比较：

623509 Style login page buttons
f12144 Fix duplicate email delivery bug
23c30c Refactor UserAccount module
Enter fullscreen mode Exit fullscreen mode

使用特定的标题有助于通过消息标题区分提交。如果在偿还技术债务的一周内，团队创建了 10 个不同的提交，其中包含代码不同部分的重构，那么这 10 个不同的提交如果只包含一条消息，Refactoring提交历史记录就会变得混乱且难以阅读。但是，如果每个重构提交都在其消息中说明重构了哪些代码，这将使提交更具描述性，历史记录也更易于阅读。

Git 对提交消息标题没有字符限制，但建议将其控制在 50 个字符以内。这样可以更轻松地阅读历史记录，并迫使提交者停下来思考如何简洁地描述提交内容。GitHub 的 UI 了解这些约定，并在我们尝试创建超过 50 个字符的标题时显示警告。

文本输入框的图片，标题为“提交消息”，消息为“提交主题消息过长，GitHub 会在超过 72 个字符时将其折叠”，警告文本为“专业提示！优秀的提交摘要字符数少于 50 个。请在扩展描述中添加额外信息”。

除此之外，当显示标题超过 72 个字符的提交时，GitHub 的 UI 将会折叠标题。

GitHub 上的提交图像，带有消息“长提交主题消息表明 GitHub 将在以下情况下将其折叠...”

您可以将 50 个字符视为提交标题消息的软限制，将 72 个字符视为硬限制。如果难以用这么多字符概括提交的所有内容，则可能表明该提交进行了太多不同的更改。如果是这样，则有必要将其拆分为其他较小的提交。

身体

提交内容可能包含扩展描述或消息正文。此处用于进一步详细说明提交内容。消息正文可能很长，因此最好将其写成通用文本，也可以使用多个段落，添加指向其他服务的链接以帮助理解提交内容（例如，问题跟踪器上的任务），甚至可以使用项目符号。这里最重要的是进行良好的沟通。

非常重要的一点是，消息正文应该着重于详细解释提交中做了什么以及为什么会发生这些更改。传达更改的背景信息对于任何想要浏览提交历史记录的人来说都将非常有帮助。

使用消息正文来解释更改是如何进行的似乎是一个好主意，但在大多数情况下，这些信息已经存在于提交的代码中（可以使用 访问git diff）。在消息正文中添加这些信息除了冗余之外，还会使文本不必要地冗长，并且更难找到在其他地方找不到的信息。

即使我们有消息正文，也要记住，好的消息正文并不意味着就不需要好的消息标题。有些显示项目历史记录的命令（例如git log --oneline，git shortlog仅显示提交标题）会更具体，而正文则更适用于我们想要更完整地查看历史记录或单独查看提交的情况。好的消息正文很重要，但它不能取代好的消息标题。

值得一提的是，并非每个提交都需要很长的描述，有时仅标题就足以解释提交的作用。例如，一个修复了项目贡献指南中拼写错误的提交，只需标题就能有效地传达更改，而无需额外的描述。

a73197 Fix typo on contribution guide
Enter fullscreen mode Exit fullscreen mode

这里的主要目标是提供背景信息，以便当有人将来查看提交时，他们知道发生了什么变化以及为什么会发生这种变化。

风格

这里有一些关于如何做出良好提交的小技巧，但这可以帮助在项目中保持良好的历史记录。

标题大写

写作时将标题大写是一种很好的做法，在这里也适用。

不要以句号结尾

这也是一种很好的写作习惯。标题不需要以句号结尾，提交信息标题也一样。

使用空行分隔邮件标题和正文

在邮件正文前添加此换行符可使邮件更易于阅读。此外，如果没有此换行符，某些工具（例如git log、git shortlog和 ）可能会出现混淆。git rebase

将消息行数限制为 72 个字符

将消息正文限制为 72 个字符是一个好习惯。这可以使消息更易于阅读，并降低在命令行或某些图形界面上显示时文本格式被破坏的可能性。

在标题上使用祈使语气

这一点对于使提交历史更具可读性非常重要，但在编写提交消息时很容易忽略。

在编写提交消息时，使用陈述语气很容易说出已完成的事情或正在做的事情：

  • Fixed bug with Y
  • Changing behavior of X
  • Removed deprecated methods
  • Releasing version 1.0.0

以这种方式书写可能看起来更自然，但它会使历史更难阅读。

撰写邮件标题时务必使用祈使语气：

  • Refactor subsystem X for readability
  • Update getting started documentation
  • Remove deprecated methods
  • Release version 1.0.0

这遵循 Git 本身在自动创建提交消息时使用的标准，就像在某些情况下所做的那样git merge：

Merge branch 'myfeature'
Enter fullscreen mode Exit fullscreen mode

或者在git revert：

Revert "Add the thing with the stuff"

This reverts commit cc87791524aedd593cff5a74532befe7ab69ce9d.
Enter fullscreen mode Exit fullscreen mode

记住这个做法的秘诀是，好的提交消息必须始终能够完成以下句子：if applied, this commit will。例如：

  • 如果应用，此提交将refactor subsystem X for readability
  • 如果应用，此提交将update getting started documentation
  • 如果应用，此提交将remove deprecated methods
  • 如果应用，此提交将release version 1.0.0

测试

是否需要通过所有测试套件才能进行提交？

我认为在创建提交之前确保测试通过非常重要。考虑到提交是项目的快照，将来可以访问，因此通过测试将使在过去的任何提交中运行项目变得更加容易。此外，测试失败可能表明提交想要进行的更改尚未完成。

实用技巧

配置 Git 使用的编辑器

默认情况下，Git 使用系统默认的文本编辑器（大多数情况下是vi）来编辑提交信息。您可以通过修改配置来使用其他文本编辑器core.editor。例如，运行以下命令：

git config --global core.editor atom
Enter fullscreen mode Exit fullscreen mode

Git 现在将使用 Atom 作为标准文本编辑器，用于提交消息和其他一些情况，如交互式变基。

编辑最后提交信息

如果要编辑上次提交的消息，可以运行git commit --amend。这将打开文本编辑器，显示上次提交的内容，然后您可以在其中编辑消息。如果只想编辑提交消息标题，可以运行以下命令：

git commit --amend -m "New commit message"
Enter fullscreen mode Exit fullscreen mode

在最后一次提交中添加更多文件

您也可以通过运行来做到这一点git commit --amend。

在项目中执行要添加到上次提交的更改，使用 暂存更改git add，然后运行git commit --amend​​。正如我在上一节中提到的，这将打开您的文本编辑器，您也可以使用它来编辑提交消息。

如果您只想向提交添加更多文件更改而不编辑其消息，您可以通过运行来实现git commit --amend --no-edit。

最后提示

尽管提交是软件编写过程中的一项重复任务，但创建良好的提交并非易事。Git 是一个非常有用的沟通工具，有效的沟通也并非易事。使用 Git 时牢记这一点至关重要。

做出正确的提交需要付出努力，但这是有益的。未来维护这个项目的人会为此感到欣慰，而这个人可能就是你自己。

以下是我撰写本文时使用的一些资源，如果您想了解有关 Git 的更多信息，我推荐这些资源：

如果您对本文有任何建议、疑问或反馈，请在此处评论或在Twitter上联系我。谢谢！

鏂囩珷鏉ユ簮锛�https://dev.to/ruanbrandao/how-to-make-good-git-commits-256k
Devto 翻译
PREV
我创建了一个暴力破解工具，学习并发编程。
NEXT
您愿意为类型检查支付多少钱？