Git 提交规范

Git 提交规范的核心目标是 统一提交信息格式、提升代码可追溯性、降低团队协作成本，尤其适合多人协作项目或长期维护的代码库。以下是业界通用的标准化规范（基于 Angular 提交规范衍生，最主流方案），包含格式定义、类型说明、实操技巧和工具辅助，兼顾易用性和规范性：

一、核心提交信息格式（强制规范）

一个合格的 Git 提交信息（Commit Message）分为 3 部分：类型(范围): 描述（必填） + 空行 + 详细说明（可选） + 空行 + 关联标识（可选），格式如下：
bash
 
运行
<type>(<scope>): <subject>

<body>

<footer>
 

各部分说明：

部分 要求与示例
type（类型） 必须，标识提交的核心目的（如下表细分），全小写英文
scope（范围） 可选，指定提交影响的模块 / 功能（如 user、order、api、frontend），无则省略括号
subject（描述） 必须，简洁概括提交内容（100 字符内），首字母小写，结尾不加标点，用祈使句（如 “修复” 而非 “修复了”）
body（详细说明） 可选，补充 subject 未说明的细节（如修改原因、实现逻辑、影响范围），换行分隔
footer（关联标识） 可选，关联 Issue / 需求 ID（如 Closes #123）、标注不兼容变更（BREAKING CHANGE: ...）

二、type 类型定义（核心重点）

类型 适用场景 示例
feat 新增功能（如新增接口、新增页面、新增组件） feat(user): 新增用户注册接口
fix 修复 Bug（如逻辑错误、语法错误、兼容性问题） fix(order): 修复订单支付状态同步异常
docs 仅修改文档（如 README、注释、接口文档，不涉及代码逻辑） docs: 更新 API 接口参数说明
style 代码格式调整（如缩进、空格、命名规范、格式化，不改变代码逻辑） style: 统一变量命名为小驼峰
refactor 重构代码（既不新增功能，也不修复 Bug，如重构函数、优化逻辑、拆分模块） refactor(api): 拆分用户模块接口逻辑
perf 性能优化（如减少接口响应时间、降低内存占用、优化查询效率） perf(db): 优化订单表查询索引
test 新增 / 修改测试用例（如单元测试、集成测试） test(user): 补充用户登录单元测试
build 构建相关修改（如依赖包更新、构建脚本调整、Docker 配置修改） build: 升级 requests 依赖到 2.31.0
ci CI/CD 配置修改（如 GitHub Actions、Jenkins 脚本调整） ci: 新增代码提交前 lint 检查
chore 其他不影响代码逻辑的修改（如删除无用文件、配置文件调整、日志格式修改） chore: 删除废弃的测试数据文件
revert 回滚之前的提交 revert: feat(user): 回滚新增注册接口

三、提交规范实操示例

1. 基础示例（仅必填部分）

bash
 
运行
git commit -m "fix(frontend): 修复登录页验证码刷新失败问题"
 

2. 完整示例（含 body 和 footer）

bash
 
运行
git commit -m "feat(order): 新增订单批量导出功能

1. 支持按时间范围筛选订单导出
2. 导出格式支持 Excel/CSV 两种类型
3. 优化导出文件命名规则（订单_20251205_1000.xlsx）

Closes #456  # 关联需求 ID 456，提交后自动关闭该需求
"
 

3. 不兼容变更示例（footer 标注）

bash
 
运行
git commit -m "refactor(api): 重构用户信息接口

将 /api/v1/user 接口改为 /api/v2/user，参数结构调整为 JSON 格式

BREAKING CHANGE: 接口路径和参数格式不兼容旧版本，需前端同步更新
Closes #789
"
 

四、禁止与注意事项

  1. 禁止使用模糊描述（如 “修改了一些问题”“优化代码”“更新”），必须明确具体内容；
  2. 禁止提交信息包含无关内容（如吐槽、表情、中文标点混排）；
  3. 禁止单次提交包含多个不相关修改（如同时新增功能 + 修复其他模块 Bug，应拆分多次提交）；
  4. subject 首字母小写，结尾不加句号 / 感叹号，用祈使句（“新增”“修复”“优化” 而非 “新增了”“修复了”）；
  5. 涉及敏感信息（如密码、密钥）的修改，需在提交前确认已移除敏感内容，避免泄露。

五、工具辅助（自动校验 + 生成格式）

手动维护规范易出错，推荐用工具强制校验和自动生成提交格式：

1. Commitizen（自动生成规范格式）

  • 安装：激活虚拟环境后执行
    bash
     
    运行
    pip install commitizen  # Python 项目推荐
# 或 Node 项目：npm install -g commitizen
  • 使用：替代 git commit，按交互提示填写信息
    bash
     
    运行
    cz commit  # 或简写 cz c
     
    工具会自动引导选择 type、scope、输入 subject 等，无需记忆格式

2. pre-commit（提交前校验）

  • 作用：提交前自动检查提交信息是否符合规范，不符合则拒绝提交；
  • 配置步骤：
    1. 安装 pre-commit：pip install pre-commit
    2. 在项目根目录创建 .pre-commit-config.yaml 文件，添加以下内容：
      yaml
       
      repos:
- repo: https://github.com/commitizen-tools/commitizen
  rev: v3.28.0
  hooks:
  - id: commitizen
    stages: [commit-msg]
       
    3. 执行 pre-commit install 启用钩子；
       
      之后提交时，工具会自动校验提交信息，不符合规范会提示错误并终止提交。

3. 其他工具

  • commitlint：Node 项目常用，配合 husky 实现提交信息校验；
  • standard-version/semantic-release：根据提交记录自动生成版本号和 CHANGELOG.md（无需手动编写更新日志）。

六、团队协作补充建议

  1. 统一 scope 定义：团队提前约定 scope 可选值（如 frontend/backend/api/db），避免混乱；
  2. 小步提交：尽量保持单次提交的修改范围小（如 “修复一个 Bug”“新增一个小功能”），便于回溯和回滚；
  3. 关联需求 / Issue：提交时通过 Closes #ID/Fixes #ID 关联项目管理工具（如 Jira、GitHub Issues）的任务 ID，实现代码与需求的联动追溯；
  4. 定期 Review 提交记录：团队内定期检查提交规范执行情况，及时纠正不规范提交。

总结

Git 提交规范的核心是 “让提交信息有意义、可追溯”，通过 type(scope): subject 的固定格式 + 工具辅助，既能降低团队沟通成本，也能为后续代码维护、版本迭代提供清晰的历史依据。新手建议先牢记 type 类型和基础格式，再通过 Commitizen 等工具简化操作，逐步养成规范提交的习惯。
 
 
posted @ 2025-12-05 16:40  C++大哥来也  阅读(30)  评论(0)    收藏  举报