Git 提交规范：让你的代码历史更清晰

原创已于 2025-10-28 21:44:45 修改 · 1k 阅读

20 ·

CC 4.0 BY-SA版权

文章标签：

#git #前端

于 2025-09-08 08:00:00 首次发布

git 专栏收录该内容

2 篇文章

订阅专栏

前言

在团队协作开发中，一个清晰、规范的 Git 提交历史记录是非常重要的。它不仅能够帮助团队成员快速了解项目的演进过程，还能在出现问题时迅速定位和回溯。然而，很多开发者在日常工作中忽略了 Git 提交信息的重要性，导致提交历史混乱不堪，难以维护。

本文将为你详细介绍 Git 提交规范的重要性、常见的提交信息格式、如何编写高质量的提交信息，以及一些实用的工具和最佳实践。无论你是 Git 新手还是有经验的开发者，都能从本文中获得实用的知识和技巧。

一、为什么需要 Git 提交规范？

在开始学习具体的提交规范之前，让我们先了解一下为什么需要规范 Git 提交信息。

1.1 提高代码审查效率

在团队协作中，代码审查是保证代码质量的重要环节。清晰的提交信息能够让审查者快速了解每次提交的目的和内容，提高审查效率。

1.2 便于问题追溯

当项目出现问题时，我们经常需要通过 Git 历史记录来追溯问题的根源。规范的提交信息能够帮助我们更快地定位到可能导致问题的提交。

1.3 自动化工具集成

规范的提交信息可以与多种自动化工具集成，例如：

自动生成 CHANGELOG
根据提交信息触发特定的 CI/CD 流程
自动决定版本号的变更（如语义化版本控制）

1.4 提升团队协作体验

统一的提交规范能够让团队成员之间更好地沟通和协作，减少因为提交信息不清晰而导致的误解和沟通成本。

二、常见的 Git 提交信息格式

目前，业界有几种比较流行的 Git 提交信息格式规范。下面我们将分别介绍这些规范，并分析它们的优缺点。

2.1 Angular 提交规范

Angular 提交规范是目前应用最广泛的 Git 提交规范之一，它定义了一种结构化的提交信息格式：

<type>(<scope>): <subject>

<body>

<footer>

其中：

type：提交的类型，如 feat、fix、docs、style、refactor、test、chore 等
scope：可选，提交的影响范围
subject：提交的简短描述
body：可选，提交的详细描述
footer：可选，包含 Breaking Changes 或关闭的 issue 信息

优点：

结构清晰，易于理解
支持自动化工具集成
能够通过类型快速识别提交的目的

缺点：

格式相对严格，需要一定的学习成本

2.2 Conventional Commits

Conventional Commits 是基于 Angular 提交规范的一个轻量级扩展，它更加灵活，适用于各种项目类型：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

优点：

与 Angular 规范兼容
更加灵活，适用范围更广
有完整的规范文档和工具支持

缺点：

仍然需要一定的学习和适应成本

2.3 原子化提交（Atomic Commit）

原子化提交不是一种特定的格式，而是一种提交理念，它强调每次提交应该只包含一个完整的、独立的更改：

每个提交只解决一个问题或实现一个功能
提交应该是可测试的和可回滚的
提交信息应该清晰地描述这个单一的更改

优点：

使代码历史更加清晰和可维护
便于回滚和调试
提高团队协作效率

缺点：

需要开发者有较强的自律性
在某些情况下可能会导致提交数量过多

2.4 比较与选择

选择适合团队的提交规范时，需要考虑以下因素：

团队的规模和协作方式
项目的类型和复杂度
现有的工具链和工作流程
团队成员的 Git 熟练程度

对于大多数团队来说，Conventional Commits 是一个不错的选择，它既有足够的结构来支持工具集成，又有一定的灵活性来适应不同的项目需求。

三、如何编写高质量的 Git 提交信息

了解了常见的提交规范后，下面我们来学习如何编写高质量的 Git 提交信息。

3.1 提交信息的结构

一个完整的 Git 提交信息通常包括三个部分：标题（subject）、正文（body）和脚注（footer）。

3.1.1 标题

标题是提交信息的第一行，它应该简洁明了地描述这次提交的主要内容。一个好的标题应该：

长度控制在 50 个字符以内
以动词开头，使用现在时态（如 “Add” 而不是 “Added”）
首字母大写
结尾不使用句号

示例：

Add support for dark mode
Fix memory leak in user profile page
Update API documentation

3.1.2 正文

正文是提交信息的可选部分，它提供了关于这次提交的更多详细信息。正文应该：

与标题之间空一行
每行长度控制在 72 个字符以内
详细解释提交的背景、目的和实现方式
使用第一人称叙述（如 “I” 或 “We”）

示例：

This commit adds support for dark mode across the entire application.

The dark mode can be enabled via the user settings menu and will apply to all UI elements, including the navigation bar, sidebar, and content area.

The implementation uses CSS variables for theme colors, making it easy to maintain and extend in the future.

3.1.3 脚注

脚注也是提交信息的可选部分，它通常用于包含一些额外的信息，如关联的 issue、Breaking Changes 等。脚注应该：

与正文之间空一行
使用特定的格式标记不同类型的信息

关联 Issue 的示例：

Closes #123
Fixes #456
Refs #789

Breaking Changes 的示例：

BREAKING CHANGE: The `getUserInfo` API now returns a Promise instead of using a callback.

To migrate, replace:

getUserInfo(userId, function(userInfo) {
  // handle userInfo
});

with:

getUserInfo(userId).then(function(userInfo) {
  // handle userInfo
});

3.2 提交类型的选择

在 Conventional Commits 规范中，提交类型（type）是一个重要的组成部分，它帮助我们快速识别提交的目的。常见的提交类型包括：

类型	描述	示例
feat	新增功能	feat: Add user authentication
fix	修复 bug	fix: Fix login page validation
docs	文档更改	docs: Update API documentation
style	代码风格更改（不影响功能）	style: Format code with Prettier
refactor	代码重构（不新增功能或修复 bug）	refactor: Simplify data processing logic
test	添加或修改测试	test: Add unit tests for user service
chore	构建过程或辅助工具的变动	chore: Update dependencies
perf	性能优化	perf: Optimize database query
ci	CI 配置更改	ci: Update GitHub Actions workflow
build	构建系统或外部依赖项的更改	build: Update webpack configuration
revert	撤销之前的提交	revert: Revert “Add feature X”

选择合适的提交类型能够使提交历史更加清晰和有意义。

3.3 实用技巧

除了遵循基本的格式和规范外，还有一些实用的技巧可以帮助你编写更好的 Git 提交信息：

3.3.1 使用命令行模板

你可以为 Git 配置一个提交信息模板，这样每次执行 git commit 命令时，就会自动使用这个模板：

# 创建一个模板文件
touch ~/.gitmessage

# 编辑模板文件，添加你喜欢的格式
cat > ~/.gitmessage << EOF
# <type>(<scope>): <subject>
# 
# <body>
# 
# <footer>
EOF

# 配置 Git 使用这个模板
git config --global commit.template ~/.gitmessage

3.3.2 拆分大型更改

如果你的更改比较大，包含多个功能或修复，最好将其拆分为多个小的、原子化的提交。这样做的好处是：

每个提交都有一个明确的目的
便于代码审查和问题追溯
减少冲突的可能性
便于回滚特定的更改

3.3.3 使用 imperative mood

在编写提交信息时，建议使用命令式语气（imperative mood），即使用 “Add” 而不是 “Added” 或 “Adding”。这种语气更加简洁和直接，也符合 Git 本身的惯例（如 git merge --help 中的描述）。

3.3.4 检查拼写和语法

提交信息是代码历史的一部分，应该像代码一样保持专业和整洁。在提交前，检查一下提交信息的拼写和语法，确保它清晰易懂。

四、Git 提交规范工具

为了帮助开发者更好地遵循 Git 提交规范，社区开发了许多实用的工具。下面我们将介绍一些常用的工具。

4.1 Commitizen

Commitizen 是一个帮助你编写符合规范的提交信息的工具。它提供了一个交互式的命令行界面，引导你填写提交信息的各个部分：

安装：

# 全局安装
npm install -g commitizen

# 在项目中初始化
commitizen init cz-conventional-changelog --save-dev --save-exact

使用：

git cz

运行 git cz 后，会出现一个交互式界面，引导你选择提交类型、填写影响范围、描述等信息。

4.2 Commitlint

Commitlint 是一个用于检查提交信息是否符合规范的工具。它可以与 Git hooks 集成，在提交前自动检查提交信息：

安装：

# 安装依赖
npm install --save-dev @commitlint/{cli,config-conventional}

# 创建配置文件
echo "module.exports = { extends: ['@commitlint/config-conventional'] }" > commitlint.config.js

集成 Git hooks：

# 安装 husky
npm install husky --save-dev

# 启用 Git hooks
husky install

# 添加 commit-msg hook
husky add .husky/commit-msg "npx --no -- commitlint --edit '$1'"

这样，每次提交时，如果提交信息不符合规范，Commitlint 会自动阻止这次提交。

4.3 standard-version

standard-version 是一个自动生成 CHANGELOG、管理语义化版本和创建 Git 标签的工具。它可以根据符合规范的提交信息自动确定版本号的变更：

安装：

npm install --save-dev standard-version

配置：
在 package.json 中添加脚本：

{
  "scripts": {
    "release": "standard-version"
  }
}

使用：

# 生成新版本
npm run release

# 生成预发布版本
npm run release -- --prerelease

# 生成特定版本
npm run release -- --release-as 1.0.0

4.4 其他实用工具

除了上面介绍的工具外，还有一些其他的实用工具可以帮助你更好地管理 Git 提交：

gitmoji：允许你在提交信息中使用 emoji，使提交信息更加直观和有趣
git-commit-plugin：一些 IDE（如 VS Code）的插件，可以在 IDE 中直接生成符合规范的提交信息
semantic-release：比 standard-version 更强大的自动版本管理工具，完全自动化整个发布流程

五、Git 提交规范的最佳实践

在实际应用中，除了遵循基本的格式和使用工具外，还有一些最佳实践可以帮助你更好地管理 Git 提交。

5.1 为团队制定适合的规范

不同的团队和项目可能有不同的需求，因此最好根据团队的实际情况制定适合的提交规范。在制定规范时，应该考虑：

团队成员的 Git 熟练程度
项目的类型和复杂度
现有的工作流程和工具链
团队的沟通方式和偏好

制定规范后，应该组织培训和讨论，确保团队成员都理解和接受这个规范。

5.2 结合项目管理工具

Git 提交规范可以与项目管理工具（如 Jira、GitHub Issues、GitLab Issues 等）结合使用，提高团队的协作效率：

在提交信息中引用相关的 issue 编号
使用特定的关键词（如 “Closes”、“Fixes”）自动关闭相关的 issue
配置自动化工作流，根据提交信息触发特定的操作

示例：

fix: Resolve login page validation error

The login form was allowing invalid email addresses to be submitted.
This commit adds proper email validation using regex.

Fixes #123

5.3 定期审查和改进

Git 提交规范不是一成不变的，应该定期审查和改进：

收集团队成员的反馈和建议
分析实际应用中遇到的问题和挑战
参考行业最佳实践和新的工具
根据项目的发展和变化调整规范

5.4 教育和培训

为了确保团队成员能够正确地遵循 Git 提交规范，教育和培训是必不可少的：

新成员加入时，提供关于提交规范的培训
定期组织团队讨论，分享经验和技巧
编写详细的文档和示例，供团队成员参考
鼓励团队成员互相学习和帮助

5.5 处理特殊情况

在实际工作中，可能会遇到一些特殊情况，需要灵活处理：

紧急修复：在紧急情况下，可以适当简化提交信息，但事后应该补充详细信息
大型重构：对于大型重构，可以在提交信息中提供更多的背景和上下文信息
协作提交：当多个开发者协作完成一个功能时，可以使用 Co-authored-by 标签在提交信息中包含所有贡献者

协作提交示例：

feat: Add user dashboard

Co-authored-by: Alice <alice@example.com>
Co-authored-by: Bob <bob@example.com>

六、常见问题与解决方案

在实践 Git 提交规范的过程中，可能会遇到一些常见的问题。下面我们将介绍这些问题及其解决方案。

6.1 忘记遵循规范

问题：有时候可能会忘记遵循提交规范，直接使用 git commit -m "Fix something" 这样的命令提交。

解决方案：

使用 Git hooks 和 Commitlint 等工具自动检查提交信息
养成使用 git cz 而不是 git commit 的习惯
如果发现提交信息不符合规范，可以使用 git commit --amend 命令修改最近的提交信息

6.2 提交信息过于简短或模糊

问题：有些开发者可能会使用过于简短或模糊的提交信息，如 “Fix bug”、“Update code” 等。

解决方案：

为团队提供明确的指南和示例，说明什么样的提交信息是好的
鼓励开发者在提交信息中提供更多的背景和上下文信息
在代码审查时，将提交信息的质量作为审查的一部分

6.3 团队成员不接受新规范

问题：有些团队成员可能习惯了自由的提交方式，不愿意接受新的规范。

解决方案：

在制定规范时，广泛征求团队成员的意见和建议
解释规范的好处和重要性，帮助团队成员理解为什么需要遵循规范
提供工具和培训，减少遵循规范的工作量和难度
从小范围试点开始，逐步推广到整个团队

6.4 历史提交信息不规范

问题：对于已经有大量历史提交的项目，如何处理不规范的历史提交信息？

解决方案：

对于历史提交，一般不建议修改，因为这会改变 Git 历史，可能会影响其他开发者
从现在开始，严格遵循新的规范
可以使用 git rebase 命令修改最近的几个提交信息，但要谨慎使用，尤其是对于已经推送到远程仓库的提交

七、总结与展望

Git 提交规范是团队协作开发中的重要实践，它能够帮助我们维护清晰、可追溯的代码历史，提高团队的协作效率和代码质量。

在本文中，我们介绍了 Git 提交规范的重要性、常见的提交信息格式、如何编写高质量的提交信息、实用的工具和最佳实践，以及常见问题与解决方案。希望这些内容能够帮助你和你的团队更好地实践 Git 提交规范。

随着软件开发实践的不断发展，Git 提交规范也在不断演进。未来，我们可能会看到更多智能化的工具和更灵活的规范出现，帮助开发者更轻松地管理 Git 提交。无论如何，清晰、规范的提交信息将始终是团队协作开发中的重要基础。

让我们从现在开始，为每一次提交编写一个清晰、规范的信息吧！

个人重磅上线数规规排五助手：让彩票选号变得更智能的专业工具

在数字彩票的世界里，每一注号码都承载着彩民的希望与期待。然而，面对复杂的数字组合和变幻莫测的开奖规律，许多彩民常常感到无从下手。今天，我要向大家介绍一款能够帮助您提升选号效率和准确性的专业工具——数规规排五助手。

为什么需要排五助手？

排列五彩票作为一种数字型彩票，其玩法简单但选号却并不容易。许多彩民在选号时往往依赖直觉或者简单的随机选择，这种方式虽然充满乐趣，但在长期参与中很难获得理想的回报。

排五助手正是为了解决这一痛点而诞生的。它不仅仅是一个简单的随机数生成器，更是一个集数据分析、趋势预测和智能算法于一体的综合性选号工具。
程序员也要有点娱乐生活，搞不好就中个排列五了呢？

感兴趣的可以微信搜索小程序“数规规-排五助手”体验体验！或直接浏览器打开如下链接：

https://www.luoshu.online/jumptomp.html

可以直接跳转到对应小程序

如果觉得本文有用，欢迎点个赞👍+收藏🔖+关注支持我吧！