笔记——Git Commit 提交规范

原创已于 2025-01-16 14:34:06 修改 · 6.3k 阅读

27 ·

CC 4.0 BY-SA版权

文章标签：

#git #代码规范 #笔记

于 2025-01-16 14:20:44 首次发布

笔记专栏收录该内容

5 篇文章

订阅专栏

Git Commit 提交规范

在团队协作中，合理的提交规范能够帮助开发者提高代码质量、简化代码审查流程，并促进更高效的团队协作。本文介绍 Git commit 提交规范的重要性，并分享一些最佳实践，帮助开发者更好地管理和记录代码提交。

文章目录

Git Commit 提交规范
一、常见的提交规范约定
- ★提交类型快查★
二、更多提交示例
三、更多约定式提交规范细则
四、一些提交规范的最佳实践
五、为什么使用约定式提交

一、常见的提交规范约定

一种较为常见且高效的提交信息规范是 Conventional Commits。这种规范定义了提交信息的结构和格式，能使得 Git 提交记录更加统一且有条理。

规范的格式为：

<类型>(<范围>): <简要描述>

[可选的详细描述]

★提交类型快查★

类型 (Type)：标识提交的目的或类别，常见的类型有：
- feat: 新功能 (Feature)
- fix: 修复问题 (Bug fix)
- docs: 文档更新 (Documentation)
- style: 代码格式化，无逻辑变更 (Styling)
- refactor: 代码重构 (Refactor)
- test: 增加或修改测试 (Test)
- chore: 其他修改，如构建过程、依赖管理等 (Chore)
- perf: 性能优化 (Performance)
范围 (Scope)：可选项，用来说明提交影响的模块或组件，如 core, api, ui, backend 等。
简要描述 (Subject)：提交的简短说明，概括了本次提交所做的工作。
详细描述 (Body)：可选项，用来进一步解释提交的内容，阐明实现的细节、背景或原因。
脚注 (Footer)：可选项，用于处理事务号、Breaking Changes（破坏性更改）等信息。

例子：

feat(user-profile): add user profile page

Added a new user profile page for displaying user information. Includes functionality to update and save user details.

BREAKING CHANGE: The API has been updated to include the `profile_picture` field.

二、更多提交示例

包含了描述以及正文内有破坏性变更的提交说明

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

包含了可选的 ! 字符以提醒注意破坏性变更的提交说明

chore!: drop Node 6 from testing matrix

BREAKING CHANGE: dropping Node 6 which hits end of life in April

不包含正文的提交说明

docs: correct spelling of CHANGELOG

包含作用域的提交说明

feat(lang): add polish language

为 fix 编写的提交说明，包含（可选的） issue 编号

fix: correct minor typos in code

see the issue for details on the typos fixed

closes issue #12

三、更多约定式提交规范细则

摘自 Conventional Commits 约定式提交规范

本文中的关键词 “必须（MUST）”、“禁止（MUST NOT）”、“必要（REQUIRED）”、“应当（SHALL）”、“不应当（SHALL NOT）”、“应该（SHOULD）”、“不应该（SHOULD NOT）”、“推荐（RECOMMENDED）”、“可以（MAY）” 和 “可选（OPTIONAL）” ，解释参考 RFC 2119 中所述。

每个提交都必须使用类型字段前缀，它由一个名词组成，诸如 feat 或 fix ，其后接一个可选的作用域字段，以及一个必要的冒号（英文半角）和空格。
当一个提交为应用或类库实现了新特性时，必须使用 feat 类型。
当一个提交为应用修复了 bug 时，必须使用 fix 类型。
作用域字段可以跟随在类型字段后面。作用域必须是一个描述某部分代码的名词，并用圆括号包围，例如： fix(parser):
描述字段必须紧接在类型/作用域前缀的空格之后。描述指的是对代码变更的简短总结，例如： fix: array parsing issue when multiple spaces were contained in string.
在简短描述之后，可以编写更长的提交正文，为代码变更提供额外的上下文信息。正文必须起始于描述字段结束的一个空行后。
在正文结束的一个空行之后，可以编写一行或多行脚注。脚注必须包含关于提交的元信息，例如：关联的合并请求、Reviewer、破坏性变更，每条元信息一行。
破坏性变更必须标示在正文区域最开始处，或脚注区域中某一行的开始。一个破坏性变更必须包含大写的文本 BREAKING CHANGE，后面紧跟冒号和空格。
在 BREAKING CHANGE: 之后必须提供描述，以描述对 API 的变更。例如： BREAKING CHANGE: environment variables now take precedence over config files.
在提交说明中，可以使用 feat 和 fix 之外的类型。
工具的实现必须不区分大小写地解析构成约定式提交的信息单元，只有 BREAKING CHANGE 必须是大写的。
可以在类型/作用域前缀之后，: 之前，附加 ! 字符，以进一步提醒注意破坏性变更。当有 ! 前缀时，正文或脚注内必须包含 BREAKING CHANGE: description

四、一些提交规范的最佳实践

简洁而清晰的提交信息：
提交信息的第一行应保持简洁，通常不超过 50 个字符。简洁明了的描述有助于快速理解提交的目的，避免信息冗余。
使用命令式语气：
提交信息应使用命令式动词（如 “Add”, “Fix”, “Refactor” 等）。例如，Fix bug in user login 而不是 Fixed bug in user login。
确保提交信息的一致性：
团队中的每个成员都应遵守统一的提交规范。可以通过 Git 钩子（如 commit-msg 钩子）或自动化工具（如 Commitizen）来强制实施提交信息的格式。
避免过于频繁的提交：
每个提交都应有明确的目的，避免一次提交中包含多个无关的功能变更，导致代码审查时增加难度。相反，将一个大的功能拆分为多个小的提交。
充分使用提交的详细描述：
在必要时，添加详细的描述来解释提交的背景、解决了哪些问题、为什么做出这些改动。这样，在后期查看时，开发者可以更好地理解每次提交的具体情况。
避免提交个人/临时工作：
提交信息应该反映出代码的实际变更和任务，而不是中途调试、未完成的工作或临时的代码。确保在提交之前清理掉不必要的调试信息和临时代码。