遵循 Git 提交规范：写出清晰提交日志 – wiki基地

作者： /

Git 提交规范：如何写出清晰、有意义的提交日志

在现代软件开发流程中，Git 已经成为版本控制的事实标准。它强大、灵活，能够帮助团队高效协作，追踪代码变更。然而，Git 的效能并非仅在于其命令行工具或 GUI 界面，很大程度上取决于我们如何使用它——特别是如何书写提交日志（Commit Messages）。

一个清晰、规范、富有意义的提交日志，就像项目代码库的历史书，详细记录了每一次变更的脉络、原因和影响。忽视提交日志的质量，无异于拥有强大的工具却不知如何使用，最终导致代码历史混乱、协作效率低下、问题追踪困难。

本文将深入探讨遵循 Git 提交规范的重要性，以及如何写出真正清晰、有价值的提交日志。

为什么我们需要遵循 Git 提交规范？

或许有人认为，提交日志不过是给 git log 命令看的一堆文字，简单记录一下改动内容就够了。这种想法大错特错。高质量的提交日志带来的好处是多方面的：

  1. 提升协作效率： 团队成员可以快速理解你的提交意图和具体改动。在进行代码评审（Code Review）时，清晰的提交信息能大大减少沟通成本。新加入的成员也能更容易地理解项目的演进历史。
  2. 便于历史追溯与问题定位： 当线上出现 Bug 时，你需要回溯代码历史，找到引入问题的提交。一个描述准确的提交日志能让你快速锁定可能的范围，配合 git bisect 等工具，可以高效地定位问题根源。
  3. 简化维护与重构： 在维护旧代码或进行大型重构时，理解每一部分代码的历史变迁至关重要。良好的提交日志提供了宝贵的上下文信息。
  4. 自动化生成发布说明（Changelog）： 如果团队遵循一套严格的提交规范（如 Conventional Commits），甚至可以自动化地根据提交历史生成项目的发布说明，极大地减少了手动编写文档的工作量。
  5. 促进更好的提交习惯： 遵循规范的过程，实际上也是一个促使开发者思考“我这次提交到底做了什么？为什么做？它的影响是什么？”的过程。这有助于形成“原子化”的提交习惯，避免一次提交包含大量无关的改动。
  6. 增强项目专业性： 清晰、一致的提交历史是一个项目成熟度和专业度的体现。

什么样的提交日志是“好”的？

一个好的 Git 提交日志通常具备以下特征：

  • 简洁明了： 尤其是第一行（主题行），应该高度概括本次提交的核心内容。
  • 详细具体： 如果需要，提交正文应提供足够的细节，解释 为什么 进行此更改，以及 如何 进行此更改（如果方法不明显）。
  • 聚焦单一职责： 理想情况下，一次提交只做一件事情——实现一个功能、修复一个 Bug、进行一次重构等。提交日志也只描述这一件事。
  • 上下文丰富： 如果改动与某个 Bug 报告、需求或任务关联，日志中应包含对应的引用（如 Issue ID）。
  • 可读性强： 使用清晰的语言，注意语法和拼写。遵循一定的格式规范，使信息结构化。

Git 提交日志的基本结构

尽管存在多种规范，但大多数 Git 提交日志都遵循一个基本的三段式结构：

“`
主题行 (Subject Line)

正文 (Body)

页脚 (Footer)
“`

各部分的说明：

  1. 主题行 (Subject Line / Summary Line):

    • 这是提交日志的第一行，也是最重要的部分。
    • 它应该简洁地概括本次提交的 目的 或 内容。
    • 长度建议控制在 50 个字符以内（这不是硬性限制，但很多工具会截断或提示）。
    • 通常使用祈使句（Imperative Mood），现在时。例如：“Add feature X”，“Fix bug Y”，“Refactor Z”。想象你正在告诉 Git 应用这个提交做什么。
    • 首字母通常大写。
    • 末尾不要加句号。
    • 主题行之后必须跟一个空行，将主题行与正文分开。这是 Git 工具识别主题和正文的关键。

  2. 正文 (Body):

    • 提供本次提交的详细说明。
    • 解释 为什么 要做这个改动，而不是仅仅重复主题行说的 做了什么。
    • 描述改动的 背景、动机 和 带来的影响。
    • 如果改动比较复杂，可以在此详细阐述实现思路。
    • 每行长度建议控制在 72 个字符以内，方便在终端中阅读。
    • 可以使用空行分隔段落，使用 * 或 - 创建列表。

  3. 页脚 (Footer – 可选):

    • 用于记录与本次提交相关的元数据。
    • 常见的用途包括：
      • 引用关联的 Issue 或 Bug 报告：例如 Fixes #123, Closes JIRA-456, Resolves gitlab#789。这有助于将代码提交与项目管理工具中的任务关联起来。
      • 声明破坏性变更：如果本次提交引入了不兼容的 API 改动或行为变化，可以在这里明确指出，通常以 BREAKING CHANGE: 或 BREAKING-CHANGE: 开头。这对于遵循语义化版本控制（Semantic Versioning）的项目非常重要。
      • 署名：如果提交是与他人合作完成，可以使用 Co-authored-by: 标记合作者。

实践指南：写出高质量提交日志的技巧

了解了基本结构，接下来是一些更具体的实践技巧：

  1. 先审查，再提交，后书写： 在使用 git commit 之前，先用 git status 和 git diff --cached (或 git diff HEAD) 仔细审查你将要提交的所有改动。确保这些改动是逻辑相关的，并且是你打算提交的内容。理解了改动内容，才能写出准确的提交信息。
  2. 使用祈使句和现在时： 遵循“Add feature”、“Fix bug”的格式，而不是“Added feature”、“Fixing bug”。这使得提交历史读起来像是一系列命令或执行的动作，更具一致性。
    • 不好: Changed button color
    • 好: Change button color to blue
  3. 主题行高度概括： 想象你的团队成员只看主题行，他们能否大致理解这个提交是关于什么的？
    • 不好: update files
    • 不好: bug fix
    • 好: Fix: Prevent infinite loop in user authentication
    • 好: Feat: Implement user profile page
  4. 正文解释“为什么”和“如何”： 如果改动不直观，正文是解释其动机和实现细节的地方。
    • 主题: Refactor: Improve performance of data fetching

    • 正文:
      “`
      Previously, data fetching used a synchronous loop which blocked the UI.
      This commit refactors the process to use asynchronous calls with Promise.all
      to fetch data concurrently, significantly reducing load times for large datasets.

      Also includes minor optimizations for data parsing.
      ``
      5. **关联 Issue 或任务：** 如果有对应的 Issue 或任务跟踪，在页脚或正文中引用它们。这能建立代码提交与项目管理之间的联系。
      *      Fixes #123(GitHub/GitLab 等，通常会自动关闭 Issue)
      *      Related to #456*See JIRA-789 for details6. **保持原子性提交：** 尽量让每个提交只包含一个独立的逻辑改动。避免将多个不相关的修改打包在一起提交。如果一个 Bug 修复涉及修改多个文件，但这些修改共同完成了这个 Bug 修复，那仍然是一个原子性的提交。如果同时修复了一个 Bug 又新增了一个不相关的按钮，这最好是两个提交。
      7. **利用模板和工具：** 配置 Git 提交模板 (      .gitmessage) 可以帮助你记住提交结构的各个部分。使用 commit message lint 工具（如commitlint` 结合 Conventional Commits）可以在提交前检查格式是否符合规范。
      8. 团队内部达成一致并遵守： 最重要的是，整个团队需要就提交规范达成一致，并共同遵守。可以将规范文档化，并在代码评审中相互提醒。

常见的提交规范：Conventional Commits

在众多提交规范中，Conventional Commits 是一个非常流行且有影响力的规范。它提供了一套轻量级的约定，用于在提交消息中包含有关功能、修复和破坏性变更的语义信息。这使得自动化工具能够解析提交消息，例如自动生成 Changelog、确定版本号等。

Conventional Commits 的提交消息格式如下：

“`
type(scope?): description

[optional body]

[optional footer(s)]
“`

  • type: 必须。表示提交的类型。常见的类型包括：
    • feat: 新功能 (A new feature)
    • fix: Bug 修复 (A bug fix)
    • docs: 文档改动 (Documentation only changes)
    • style: 代码格式改动，不影响代码逻辑（空格、分号等） (Changes that do not affect the meaning of the code)
    • refactor: 代码重构，不引入新功能或修复 Bug (A code change that neither fixes a bug nor adds a feature)
    • test: 测试用例改动 (Adding missing tests or correcting existing tests)
    • chore: 构建过程或辅助工具的变动，不影响源文件或测试文件（例如生成文档、更改构建流程等） (Changes to the build process or auxiliary tools and libraries)
    • build: 影响构建系统或外部依赖的改动 (Changes that affect the build system or external dependencies)
    • ci: CI 配置文件或脚本的改动 (Changes to our CI configuration files and scripts)
  • scope: 可选。表示改动影响的范围，例如模块、组件或文件路径。用括号包围。
    • feat(api): add user endpoint
    • fix(ui): correct button alignment
  • description: 必须。主题行的简短描述，同基本结构的描述要求。
  • Body: 可选。同基本结构的正文。

  • Footer: 可选。同基本结构的页脚。特别注意 BREAKING CHANGE。

    • 声明破坏性变更：可以在页脚以 BREAKING CHANGE: description 的形式声明。或者在 type 后紧跟 !，如 feat!: add new authentication method，然后在正文或页脚详细描述破坏性变更。

示例：

“`
feat(user): add user profile page

Implements the user profile page allowing users to view and edit their information.

Includes forms for updating email, password, and preferences.

Resolves #101, #102
“`

“`
fix(auth): handle empty password during login

Previously, submitting an empty password would cause a server error.
This commit adds validation to prevent empty passwords and provides user feedback.

Fixes #45
“`

“`
refactor: simplify database connection logic

Reduces complexity by consolidating connection pooling setup into a single module.
Removes deprecated configuration options.
“`

“`
feat!: introduce new webhook API

BREAKING CHANGE: The payload structure for webhook events has been updated.
Existing integrations using the old payload structure will need to be updated.
See documentation for new structure details.

Related to #200
“`

遵循 Conventional Commits 规范的最大好处在于其机器可读性，可以与 Semantic Release 等工具无缝集成，实现版本发布的自动化。

避免常见的提交日志陷阱

  • 提交信息过于简略或含糊： “update files”、“fix bug”这类信息毫无价值。
  • 将不相关的改动打包在一起： 使得提交历史混乱，难以回溯。
  • 提交信息与实际改动不符： 这是最糟糕的情况，具有误导性。
  • 忽略正文和页脚： 对于复杂或重要的改动，只写主题行是远远不够的。
  • 过度依赖 GUI 工具的自动生成信息： GUI 工具生成的提交信息通常过于简单，不符合规范要求。

如何在团队中推行提交规范？

  1. 明确规范： 选择或制定一套适合团队的提交规范（例如采用或修改 Conventional Commits）。将其文档化，让所有成员都能查阅。
  2. 培训与沟通： 向团队成员解释为什么需要这个规范，以及如何遵循它。可以通过分享会、Code Review 中的反馈等方式进行。
  3. 工具辅助：
    • 配置 Git 提交模板 (git config --global commit.template ~/.gitmessage)。
    • 使用 Git Hook（如 pre-commit 钩子）结合 commitlint 等工具强制检查提交信息的格式。
  4. 代码评审： 将提交信息的质量作为代码评审的一部分。如果提交信息不规范，Code Review 可以不通过。
  5. 领导层或资深成员带头： 项目负责人或经验丰富的开发者首先遵循规范，树立榜样。

总结

写出清晰、有意义的 Git 提交日志是一项值得投入时间和精力去培养的习惯。它不仅仅是技术细节，更是团队协作效率、项目可维护性和历史可追溯性的重要基石。通过遵循规范（如 Conventional Commits），利用 Git 提交日志的基本结构，并采纳一些实用的书写技巧，我们可以将杂乱无章的提交历史转变为一份条理清晰、价值非凡的项目演进记录。

记住，每一次 git commit 都是在为项目的未来书写历史。花几分钟写好提交信息，将为未来节省数小时乃至数天的时间。让我们从现在开始，认真对待每一次提交，写出能够讲述故事、传递价值的提交日志吧！

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部