Git Commit Message 的规范书写-CFANZ编程社区

Git Commit Message 的规范书写

规范书写非常重要，它是项目协作和后期维护的基石。一份清晰的提交信息可以帮助你和其他开发者快速理解代码变更的意图、背景和影响。

目前，最广为接受和推崇的规范是 Angular 规范，它衍生出了 Conventional Commits 约定式提交标准。下面我将详细介绍这套规范。

核心规范：Conventional Commits

一个规范的 Commit Message 包含三个部分：Header、Body 和 Footer。格式如下：

<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>

在实际操作中，(scope)、<body> 和 <footer> 在某些小型或简单的提交中可以省略，但 <type> 和 <subject> 是必须的。

1. Header（头部）

头部是唯一必需的部分，它由三部分组成：类型（type）、作用域（scope，可选） 和 **主题（subject）**。

类型 (type)

type 用于说明本次提交的性质，必须是以下标识之一：

feat: 新增功能 (feature) - 与之前的功能无关的新内容。
fix: 修复 bug - 修复了代码中的问题。
docs: 文档更新 (documentation) - 仅修改了文档（如 README, CHANGELOG, API 文档等）。
style: 代码格式调整 - 不影响代码逻辑的更改（如空格、分号、缩进、格式化等）。
refactor: 代码重构 - 既不是修复 bug 也不是新增功能的代码更改（即改善代码结构、可读性，但不影响外部行为）。
perf: 性能优化 (performance) - 提高性能的代码更改。
test: 测试相关 - 增加或修改测试用例（单元测试、集成测试等）。
build: 构建系统或外部依赖更改 - 影响构建系统或外部依赖的更改（如 Webpack, npm, Gulp, Bazel 等）。
ci: CI 配置更改 (Continuous Integration) - 更改持续集成系统的配置或脚本（如 Travis, Circle, GitHub Actions, GitLab CI）。
chore: 杂项事务 - 其他不修改源代码或测试文件的琐碎更改（如更新构建任务、包管理器配置等）。
revert: 回滚提交 - 撤销之前的某次提交。

作用域 (scope, 可选)

scope 用于说明本次提交影响的范围，通常是代码模块、组件或文件的名称。例如：fix(router):、feat(auth):、refactor(users):。它可以帮助快速定位变更位置。

主题 (subject)

subject 是本次提交目的的简短描述。

使用祈使句、现在时态：仿佛在命令代码库做什么。例如：“change” 而不是 “changed” 或 “changes”。
首字母不要大写。
**结尾不要加句号 (.)**。
长度限制：建议在 50 个字符以内。

Header 示例：

feat(payment): add support for Alipay (新增功能)
fix(login): resolve infinite redirect loop (修复 bug)
docs: update API documentation for User model (文档更新)
refactor(utils): simplify config loading logic (代码重构)

2. Body（正文，可选）

在 Header 之后空一行，可以编写更详细的描述，说明本次提交的动机、与之前行为的对比等。

使用祈使句、现在时态。
每行长度建议在 72 个字符以内，方便阅读。
说明 “为什么要这么做”，而不是“做了什么”（代码本身已经展示了做了什么）。

示例：

feat(auth): implement remember me functionality

- Add `remember_token` field to users table
- Set long-lived cookie if remember me is checked
- Add middleware to authenticate via remember token
Closes #123

3. Footer（页脚，可选）

在 Body 之后空一行，用于放置一些额外信息，通常包括：

不兼容的变动 (BREAKING CHANGE): 如果本次提交包含与之前版本不兼容的变更（例如修改了 API、删除了某个功能），必须在此处说明。以 BREAKING CHANGE: 开头，后面跟详细的描述。
```
BREAKING CHANGE: The `getUser(id)` method now returns a Promise instead of accepting a callback.
```
关闭 Issue (Closes): 如果本次提交解决了某个或多个 Issue（例如 GitHub Issue），可以在这里关联它们。关联后，提交代码后这些 Issue 会自动关闭。
```
Closes #234
Fixes #123, #456
```
参考链接 (Referencing): 可以放置相关的文档链接或其他参考信息。

完整示例

示例 1：包含不兼容变动的功能提交

feat(api): send email to users on completion of order

- Add `emailService` module with send function
- Trigger email after order status is set to 'completed'

BREAKING CHANGE: The `order.complete()` method now requires an email address as its first argument.

Closes #789

示例 2：简单的修复提交

fix: prevent page crash when search query is empty

- Add null check for query parameter in search handler
- Add corresponding test case

Fixes #101

示例 3：文档更新

docs: update installation guide for Node.js 18

为什么需要遵守这些规范？

生成可读性强的变更日志 (CHANGELOG)：工具可以根据 feat 和 fix 等类型自动生成清晰、分类的变更日志。
触发自动化流程：根据提交类型（如 fix, feat, BREAKING CHANGE），可以自动决定版本号的升级（遵循 Semantic Versioning）。
提高代码审查效率：审查者一眼就能看出提交的意图和影响范围。
更好的项目可维护性：历史记录清晰，便于回溯和排查问题。

工具推荐

为了更轻松地遵守规范，推荐使用以下工具：

Commitizen: 一个交互式工具，通过命令行问答的方式帮助你生成符合规范的提交信息。安装后使用 git cz 代替 git commit。
commitlint: 一个校验工具，可以配置 Git Hook（如 commit-msg），在提交时自动检查信息格式是否符合规范，不合格则拒绝提交。
IDE 插件: 许多现代 IDE（如 VS Code）都有插件可以辅助编写 Commit Message。

养成书写规范 Commit Message 的习惯，对你和你的团队都大有裨益。