第五章. Git 提交规范指南：Conventional Commits 工程化实践

本章学习路径

1. 微操暂存：使用 add -p 和补丁编辑模式，将混杂的修改拆解为原子化的提交。
2. 状态回退：辨析 restore --staged 与 reset 的区别，安全地管理暂存区内容。
3. 历史修补：掌握 amend 修改提交元数据的方法，并理解其对 Commit ID 的影响。
4. 特殊技巧：利用 allow-empty 触发 CI 以及 --author 修正身份的冷门但重要技巧。
5. 工程规范：深度解析 Conventional Commits 标准，让提交信息成为可读文档。

5.1. 暂存区的高级操作：交互式筛选实战

在上一章，我们习惯了使用 git add . 一把梭。但在团队协作中，这种粗放的操作往往是事故的根源。为了解决“一次提交包含多个无关修改”的痛点，Git 提供了一把手术刀——交互式暂存（Interactive Staging）。

本节我们将通过一个精心设计的实战，跨越文件的物理边界，在 代码块（Hunk） 甚至 行（Line） 的颗粒度上进行精细化操作。

5.1.1. 核心概念：什么是 Hunk？

在 Git 的视角里，文件并不是最小单位。当 Git 扫描变更时，它会把 连续变化的行 以及它们周围的上下文（Context）聚合在一起，形成一个 Hunk（代码块）。

• 如果两个修改点相隔很远（例如超过 3 行），Git 会自动将它们识别为 两个 Hunk。
• 如果两个修改点挨得很近，Git 会默认将它们合并为 一个 Hunk（我们稍后会学习如何用 s 强行拆散它们）。

5.1.2. 环境初始化：构建“混合修改”现场

为了确保实验结果的一致性，我们需要构建一个代码行数足够多、能让 Git 自动识别出分隔的文件。

步骤 1：创建初始状态

请在项目根目录创建 MathUtils.java，并直接复制以下内容（注意中间的空行不能少，这是为了隔离 Hunk）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

public class MathUtils {
    
    // 1. 加法运算
    public int add(int a, int b) {
        return a + b;
    }

    // 占位符：为了拉开距离，保证 Git 自动拆分 Hunk
    // ...
    // ...
    // ...

    // 2. 除法运算
    public int divide(int a, int b) {
        return a / b;
    }
}

提交这个初始版本：

1
2

git add MathUtils.java
git commit -m "init: basic math utils"

步骤 2：制造“脏代码”与“修复”共存的现场

现在，我们模拟真实场景：你修复了 divide 的 Bug（正事），但顺手在 add 里加了调试打印（脏代码）。

请用以下代码 完全覆盖 MathUtils.java：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

public class MathUtils {
    
    // 1. 加法运算
    public int add(int a, int b) {
        System.out.println("DEBUG: calculating..."); // <--- 修改点 A：脏代码，不该提交
        return a + b;
    }

    // 占位符：为了拉开距离，保证 Git 自动拆分 Hunk
    // ...
    // ...
    // ...

    // 2. 除法运算
    public int divide(int a, int b) {
        if (b == 0) return 0; // <--- 修改点 B：关键修复，必须提交
        return a / b;
    }
}

此时的目标是：只提交修改点 B，丢弃修改点 A。

5.1.3. 实战一：使用 s (Split) 拆分与筛选

在终端执行交互式命令：

1

git add -p MathUtils.java

交互界面深度解析

Git 会扫描文件，并展示第一个差异块。此时底部的提示符 [y,n,q,a,d,s,e,?] 是我们操作的核心。你需要熟练掌握以下关键指令：

操作流程演示

场景 A：如果 Git 显示 (1/2)
这意味着我们预留的空行起作用了，Git 自动识别出了两个块。

1. 看到包含 System.out.println 的块时，输入 n（拒绝）。
2. 看到包含 if (b == 0) 的块时，输入 y（同意）。

场景 B：如果 Git 显示 (1/1)（我们正常可能不会遇到，但有可能！）
这意味着修改点离得太近，Git 把它们合并了。

1. 此时不要急着选 y 或 n，请输入 s 并回车。
2. Git 会强制根据未修改的行进行切割，然后重新问你。
3. 切开后，针对脏代码输入 n，针对修复代码输入 y。

验证结果

操作完成后，执行 git status，你会看到神奇的 “双重状态”：

1
2
3
4
5

Changes to be committed:
  modified:   MathUtils.java  <-- 这里面只有 Bug 修复

Changes not staged for commit:
  modified:   MathUtils.java  <-- 这里面残留着打印语句

5.1.4. 实战二：使用 e (Edit) 模式处理行内混合

s 命令虽然好用，但它有一个致命局限：如果修改在同一行，或者紧挨着，它就切不开了。

这时，我们需要用到 Git 的终极武器：补丁编辑（Patch Editing）。

场景模拟

创建一个配置文件 config.properties 并提交：

1

timeout=1000

1
2

git add config.properties
git commit -m "init: config"

现在，我们将它修改为：

1

requestTimeout=5000

这里发生了两个变化：

1. 重构：timeout -> requestTimeout
2. 改值：1000 -> 5000

目标：先提交重构（改名），但不提交改值。

操作指引

1. 执行 git add -p config.properties。
2. Git 会显示：

   1 2	-timeout=1000 +requestTimeout=5000

3. 因为变化在同一行，输入 s 无效。请输入 e (Edit)。

手动伪造补丁

Git 会打开编辑器，展示 Diff 内容。请注意，你现在编辑的不是文件，而是即将生效的“补丁”。

将编辑器中的内容修改为：

1
2

-timeout=1000
+requestTimeout=1000

• 我们保留 - 行（旧代码）。
• 我们手动把 + 行里的 5000 改回 1000。这相当于告诉 Git：“我这次只改了变量名，没改值”。

保存关闭后，执行 git diff --cached，你会发现暂存区里确实只存入了变量名的修改。

5.1.5. 撤销暂存：git restore --staged 的反向操作

不仅 git add 可以交互式，撤销也可以。

如果你不小心把一堆文件加到了暂存区，想把其中几个特定的 Hunk 拿出来（比如发现里面混了密码），但这比较少用，可以使用：

1

git restore --staged -p

此时的逻辑是 反向 的：

• 输入 y：表示 “是的，我要把这个块踢出暂存区”（Unstage）。
• 输入 n：表示 “不，把这个块留在暂存区里”（Keep staged）。

5.2. 提交修补与特殊元数据修正（非重要）

在完成暂存区的精细控制后，我们执行了 git commit。但人非圣贤，提交之后我们可能会发现：

• Commit Message 写了个错别字。
• 少提交了一个配置文件。
• 用了错误的个人邮箱提交了公司代码。

如果创建新的提交来修正这些错误，会导致历史记录变得脏乱差（Dirty History）。Git 提供了 amend 机制，让我们能够“时光倒流”，在不产生新记录的情况下修正最近一次的错误。

5.2.1. 提交修补：git commit --amend 的对象替换原理

场景一：修改提交信息

如果你只是想改一下刚才那条提交记录的备注：

1

git commit --amend -m "fix: 修复了登录模块的空指针异常 (修正版)"

场景二：追加漏提交的文件

如果你提交完才发现少加了 config.yaml：

1
2
3
4
5

# 1. 先把漏掉的文件加入暂存区
git add config.yaml

# 2. 执行修补，--no-edit 表示沿用上次的提交信息，不打开编辑器
git commit --amend --no-edit

底层原理：对象替换机制（危险！）

很多初学者认为 amend 是在“修改”旧的提交。这是一个巨大的误解。

在 Git 的对象存储模型中，Commit 对象是 不可变 的（Immutable）。一旦生成，它的内容、时间、父节点哈希就永久固定了。

当你执行 git commit --amend 时，Git 实际上做了以下三件事：

1. 读取上一次提交（HEAD）的内容。
2. 结合当前暂存区的内容（如果有），创建一个 全新的 Commit 对象（拥有全新的 SHA-1 哈希值）。
3. 将 HEAD 指针从旧 Commit 移动到这个新 Commit 上。

旧的 Commit 对象并不会立即消失，它变成了一个 悬空对象（Dangling Commit），因为没有任何分支指向它，它最终会被 Git 的垃圾回收机制（GC）清理掉。

绝对红线：严禁在公共分支上执行 Amend
正因为 amend 会改变 Commit ID（哈希值），它本质上是在重写历史。如果你的代码已经 push 到了远程共享分支（如 develop 或 main），绝对不要在本地执行 amend。否则，当你再次 push 时，会因为历史线分叉而被拒绝（需要 force push），这会覆盖队友的代码，引发严重的团队协作灾难。
原则：Amend 仅限于还未推送到远程的本地私有提交。

5.2.2. 作者修正：使用 --author 临时覆盖提交身份

场景：你在家办公，使用个人电脑开发公司的开源项目。你的全局 Git 配置（Global Config）是个人邮箱 me@gmail.com，但公司要求提交必须使用 me@company.com。

你不想每次都改全局配置，也不想改项目的 .git/config（因为偶尔也要用个人身份提 PR）。

解决方案：单次覆盖。

1

git commit -m "feat: corporate feature" --author="Alice <alice@company.com>"

如果已经提交了，发现作者错了，可以结合 amend 进行修正：

1

git commit --amend --author="Alice <alice@company.com>" --no-edit

配置优先级回顾：
--author 参数 > 项目级 .git/config > 用户级 ~/.gitconfig > 系统级 /etc/gitconfig。

5.2.3. 空提交应用：git commit --allow-empty 的工程价值

默认情况下，如果暂存区为空，Git 会阻止你执行 commit，提示 nothing to commit。但在 DevOps 工程化实践中，我们经常需要“无中生有”地创建一个提交。

命令：

1

git commit --allow-empty -m "chore: trigger ci build"

两大核心应用场景：

1. 触发 CI/CD 流水线：有时候代码没变，但你需要重新运行流水线（比如之前的构建因为网络原因失败了，或者为了刷新缓存）。与其随便改个文件加个空格（Dirty Hack），不如提交一个优雅的 Empty Commit。GitLab/GitHub Actions 依然会识别到新的 Commit SHA 并触发构建。
2. 初始化仓库的 Root Commit：在初始化一个新仓库时，很多架构师习惯先打一个空的 chore: initial commit。这样做的好处是，后续如果需要对第一次真正的代码提交进行 Rebase（变基）操作，会非常方便。因为 Git 的 Rebase 很难处理根节点（Root Commit），有一个空的根节点作为基座，能避免很多麻烦。

5.3. 提交信息的工程化规范

写好代码是程序员的本分，写好 Commit Message 是工程师的素养。一条模糊的 fix bug 或 update code 提交记录，是给未来维护者（包括两周后的你自己）挖的坑。

为了解决“提交信息随心所欲”的问题，Angular 团队提出了 Conventional Commits（约定式提交） 规范，这已成为目前全球最主流的工程化标准。

5.3.1. 提交信息的 “解剖学” 结构

一条标准的工程化 Commit Message 由 Header（标题）、Body（正文）、Footer（页脚） 三部分组成。

整体结构对比

注意：各部分之间需要用 空行 分隔。

Header 结构分解

1
2
3
4

fix(cart): prevent negative item quantity
 ^    ^            ^
 |    |            |
Type Scope      Subject

Subject 书写规范

Body 写作对比

Body 应该解释：

• Why：为什么要做这个改动（背景/问题）
• How：如何解决的（方案/思路）
• Impact：可能的影响（兼容性/性能）

Footer 常用标记

这些 Footer 标记会被 GitHub/GitLab 等平台的自动化工具识别，用于触发相应的流程动作。

5.3.2. 语义化类型（Type）速查表

Type 是规范的核心，它决定了这次提交的性质。请对照下表，并在右侧查看 真实场景示例：

5.3.3. 为什么要这么麻烦？（工程化价值）

这种细粒度的区分不仅仅是为了“整洁”，而是为了实现 自动化（Automation）。

如果你的团队严格遵守上述规范，配合自动化工具（如 standard-version），就能实现全自动流水线：

1. 自动生成更新日志：工具扫描所有 feat 和 fix，自动生成精美的 CHANGELOG.md。
2. 自动计算版本号：
   • 检测到 feat -> 自动将版本从 1.0.0 升至 1.1.0。
   • 检测到 fix -> 自动将版本从 1.0.0 升至 1.0.1。
   • 检测到 BREAKING CHANGE -> 自动将版本从 1.0.0 升至 2.0.0。

这就是我们在序章中提到的“工程化思维”——用一次性的规范约束，换取永久的自动化便利。

5.4. 本章总结

本章我们完成了从“会提交”到“专业提交”的蜕变。我们不再将 Git 仅仅视为一个存档工具，而是将其视为一个精密的版本管理系统。

本章核心知识体系回顾

1. 原子提交（Atomic Commit）：
   • 利用 git add -p 将文件拆解为 Hunk，利用 e 模式拆解行级差异。
   • 原则：一次提交只做一件事。这能极大降低回滚风险和 Code Review 的认知负担。
2. 历史修补（History Rewriting）：
   • 利用 commit --amend 修正最近一次的失误。
   • 铁律：只修补本地私有分支，绝不修补远程共享分支。
3. 工程规范（Engineering Standards）：
   • Commit Message 不是备忘录，而是给团队看的文档。
   • 遵循 type(scope): subject 格式，为未来的自动化运维（Auto Release）打下地基。

知识速查表

常见问题

• Q: 我执行了 amend，但是现在的 Hash 值变了，之前的提交去哪了？
  • A: 之前的提交变成了“悬空提交”（Dangling Commit），它依然存在于对象库中，但没有分支指向它。我们可以通过 git reflog 找回它（下一章重点）。
• Q: git add -p 太慢了，有图形化工具吗？
  • A: VS Code 的源代码管理面板、SourceTree 等工具都支持可视化选择 Hunk。但理解命令行 -p 的原理，能让你在服务器端或无 GUI 环境下依然游刃有余。

下一章预告

现在我们已经能够优雅地生成提交了，但如果在这个过程中我们犯了更严重的错误（比如误删了文件、提交了错误的版本并且已经 push 了），该怎么办？或者我们需要在不同的历史版本之间穿梭查看？

下一章 “第六章. Git 版本回退全攻略：详解 Reset、Revert 与 Reflog”，我们将掌握 Git 的“时光机”——Reset、Revert 和 Reflog，学会如何在任何绝境中找回代码。