CODE

告别杂乱提交信息：一份值得收藏的Git提交规范指南

2025/09/14 git 共 3121 字，约 9 分钟

告别杂乱提交信息：一份值得收藏的Git提交规范指南

在团队协作开发中，我们是否经常见到这样的Git提交信息？

  • fix bug
  • update
  • test
  • 又改了一下

这些模糊、随意的提交信息就像没有标签的罐头，时间一长，没人知道里面装的是什么，更不用说快速定位历史变更、生成清晰的变更日志（CHANGELOG）了。一份好的Git提交规范，是项目可维护性的基石。本文将带你深入理解并实践一套被广泛认可的Git提交规范。

为什么需要Git提交规范？

在回答“如何做”之前，我们首先要明白“为什么”。

  1. 提供更多的历史信息，方便快速浏览 规范的提交信息主题行（Subject）就像文章的标题，能让团队成员一目了然地了解这次提交的目的，无需深入查看代码变更。

  2. 方便过滤某些提交 例如，你可以快速筛选出所有新增功能（feat）的提交，或者所有破坏性变更（BREAKING CHANGE）的提交，这对于代码审查和发布极为有用。

  3. 直接从提交生成变更日志（CHANGELOG） 许多自动化工具（如standard-version、semantic-release）可以解析规范的提交信息，自动生成美观且结构清晰的变更日志，彻底告别手动维护的烦恼。

  4. 促进代码审查（Code Review） 清晰的提交信息能让审查者快速理解你的改动意图，将注意力集中在代码逻辑本身，而不是花时间猜测“这段代码到底在改什么”。

Angular提交规范解析

目前，社区内最流行、最完整的规范是Angular Git Commit Guidelines。它规定了一条提交信息应该包含三个部分：Header，Body和Footer。格式如下：

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

其中，Header是必需的，Body和Footer可视情况选填。

1. Header（头部）

头部只有一行，包括三个字段：type（必需）、scope（可选）和subject（必需）。

  • type（类型）: 说明本次提交的类别。允许使用以下标识符：
    • feat: 新增功能（feature）
    • fix: 修复bug
    • docs: 仅修改文档（documentation）
    • style: 调整代码格式（空格、分号等），不改变代码逻辑
    • refactor: 代码重构，既不是新增功能，也不是修改bug
    • perf: 性能优化（performance）
    • test: 增加或修改测试用例
    • build: 影响构建系统或外部依赖的更改（如gulp, broccoli, npm）
    • ci: 更改CI配置文件和脚本（如Travis, Circle, Jenkins）
    • chore: 杂项变动（不修改源文件/测试文件）
    • revert: 回滚之前的提交

  • scope（范围）: 说明本次提交影响的范围。这通常是代码中的一个模块或文件名。例如 fix(router):、feat(auth):。如果变动影响广泛，可以使用*。

  • subject（主题）: 对本次提交的简短描述，不超过50个字符。
    • 以动词开头，使用第一人称现在时，例如”change”而不是”changed”或”changes”
    • 首字母小写
    • 结尾不加句号（.）

2. Body（正文）

正文部分是对本次提交的详细描述，可以说明代码变动的动机、与之前行为的对比。写作时注意：

  • 在72个字符处换行
  • 使用祈使句，现在时态（如”Change”而不是”Changed”或”Changes”）

3. Footer（脚注）

脚注部分只用于两种情况：

  1. 不兼容的变动（Breaking Changes）: 以BREAKING CHANGE:开头，后面跟空格或两个换行符，描述变动详情及迁移方法。
  2. 关闭Issue: 如果本次提交针对某个Issue，可以在这里关闭它。例如 Closes #123, Fixes #456。

实战示例

让我们看几个例子，感受一下规范提交信息的强大。

示例1：一个简单的功能提交

feat: 添加用户密码重置功能

在用户设置页面新增了‘重置密码’按钮，点击后会向注册邮箱发送包含重置链接的邮件。

Closes #128

示例2：一个带范围和破坏性变更的修复

fix(api): 移除过期用户令牌的自动续期功能

移除 `userService.refreshToken()` 方法中针对过期令牌的自动处理逻辑，现在过期令牌必须重新登录获取。

BREAKING CHANGE:
`/api/v1/refresh` 接口不再接受过期超过7天的令牌。客户端需要捕获401错误并引导用户至登录页。

示例3：一个普通的文档更新

docs: 更新项目README中的快速入门指南

更新了依赖安装命令，从 `npm i` 改为 `yarn install`。
添加了环境变量配置的详细说明。

如何落地执行？工具推荐

仅靠文档和口头约定很难让规范持续执行。幸运的是，有一些强大的工具可以帮助我们。

1. Commitizen：交互式提交工具

Commitizen是一个交互式的命令行工具，它通过问答的方式引导你生成符合规范的提交信息。

安装与使用：

  1. 全局安装：npm install -g commitizen
  2. 在项目根目录下，初始化适配器（这里用Angular规范）：
    commitizen init cz-conventional-changelog --save-dev --save-exact
  3. 以后提交时，不再使用git commit，而是使用git cz或cz，然后根据提示一步步操作即可。

Commitizen交互界面示意图

2. Commitlint：提交信息校验工具

Commitlint可以检查你的提交信息是否符合规范，通常与Git的commit-msg钩子结合，在提交时自动校验，不符合规范则阻止提交。

安装与配置：

  1. 安装核心库和Angular配置：
    npm install --save-dev @commitlint/config-conventional @commitlint/cli
  2. 创建配置文件commitlint.config.js：
    module.exports = {
  extends: ['@commitlint/config-conventional']
};
  3. 使用Husky来添加Git钩子：
    npx husky install
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'

配置完成后，如果你尝试提交一个不规范的信息（如git commit -m "update"），commitlint会报错并终止提交。

3. standard-version：自动生成变更日志和版本发布

这个工具可以根据符合规范的提交历史，自动生成CHANGELOG.md，并基于feat和fix提交自动升级语义化版本号（SemVer）。

基本使用：

npx standard-version --first-release # 首次发布
# 后续发布
npx standard-version

它会自动：

  1. 根据feat提交升级次版本号（Minor）
  2. 根据fix提交升级修订号（Patch）
  3. 根据BREAKING CHANGE升级主版本号（Major）
  4. 生成或更新CHANGELOG.md文件
  5. 创建一个新的提交和Tag

总结

制定并执行Git提交规范，初看可能会觉得有些繁琐，增加了开发流程的步骤。但从长远来看，它为项目带来的可读性、可维护性和自动化能力的价值是巨大的。它不仅仅是一个格式要求，更体现了一种严谨、协作的工程师文化。

从今天起，尝试在你的个人项目或团队中引入这套规范吧。可以先从使用Commitizen开始，慢慢习惯这种提交方式，再逐步引入commitlint进行强约束。坚持下来，你一定会惊叹于它带来的改变。

文档信息

Search

    Table of Contents