Git 提交规范指南

发表于 更新于 分类于 ， 阅读次数： Waline： 本文字数： 4.7k 阅读时长 ≈ 4 分钟

在团队协作中，清晰、规范的 Git 提交信息（Commit Message）是维护项目健康的关键。它不仅能帮助开发者快速回顾历史记录，还能配合自动化工具生成 Changelog。本文将介绍业界通用的 Angular 提交规范（Conventional Commits），并分享几款提升效率的辅助工具。

1. 提交信息结构

标准的提交信息由三个部分组成：标题（Header）、正文（Body） 和 页脚（Footer）。

1
2
3
4
5
<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>
  • Header（必填）：简述变更内容。
    • type: 提交类型（如 feat, fix）。
    • scope: （可选）影响范围（如 auth, api）。
    • subject: 简短描述，动词开头，使用祈使句。
  • Body（选填）：详细描述修改动机和前后对比。
  • Footer（选填）：用于关联 Issue（Close #123）或标记破坏性变更（BREAKING CHANGE）。

2. 提交类型（Type）

选择正确的 type 是规范的核心。以下是决策流程图，帮助你快速定位：

flowchart TD
    Start[开始提交] --> Q1{是否修改了<br>生产环境代码?}
    Q1 -- 是 --> Q2{是否改变了<br>功能逻辑?}
    Q1 -- 否 --> Q3{修改内容类别?}
    
    Q2 -- 新功能 --> Feat(feat<br>新功能)
    Q2 -- 修复Bug --> Fix(fix<br>修补Bug)
    Q2 -- 性能优化 --> Perf(perf<br>性能优化)
    Q2 -- 代码重构 --> Refactor(refactor<br>重构)
    
    Q3 -- 文档/注释 --> Docs(docs<br>文档)
    Q3 -- 格式/样式 --> Style(style<br>格式)
    Q3 -- 测试用例 --> Test(test<br>测试)
    Q3 -- 构建/依赖 --> Build(build<br>构建)
    Q3 -- CI配置 --> Ci(ci<br>集成)
    Q3 -- 其他杂务 --> Chore(chore<br>杂务)
    Q3 -- 回滚 --> Revert(revert<br>回滚)
    
    style Feat fill:#e1f5fe,stroke:#01579b
    style Fix fill:#ffebee,stroke:#b71c1c
    style Refactor fill:#f3e5f5,stroke:#4a148c

2.1 常用类型详解

类型说明示例
feat新功能 (Feature)。引入新功能。feat(user): add login endpoint
fix修补 (Fix)。修复 Bug。fix(nav): resolve layout issue on mobile
refactor重构。既不新增功能也不修复 Bug 的代码更改（如解耦、重命名）。refactor(auth): simplify token validation logic
docs文档。仅修改文档（如 README, API 文档）。docs: update installation guide
style格式。不影响代码运行的格式调整（空格、分号、缩进）。style: fix eslint warnings
test测试。增加或修改测试用例。test(api): add unit tests for user controller
perf性能。提高性能的代码更改。perf(image): implement lazy loading
build构建。修改构建系统或外部依赖（npm, maven）。build: upgrade react to v18
ci集成。修改 CI/CD 配置文件或脚本。ci: add github actions workflow
chore杂务。其他不修改源码或测试的琐碎更改。chore: update .gitignore
revert回滚。撤销之前的提交。revert: feat(user): add login endpoint

3. 效率工具推荐

3.1 CZ AI

1
2
3
4
5
npm install -g cz-git commitizen
echo '{ "path": "cz-git", "$schema": "https://cdn.jsdelivr.net/gh/Zhengqbbb/cz-git@1.9.4/docs/public/schema/cz-git.json" }' > ~/.czrc

# 推荐一步安装这个
npm i -g czg
  • 配置文件 ~/.config/.czrc
  • 黑盒的，不能自定义，默认输出英文
  • 目前：deepseek-ai/DeepSeek-V3.2

3.2 使用 Sgpt

  • 最终依赖 sgpt，pip install shell-gpt
  • 配置： ~/.config/shell_gpt/.sgptrc ，修改 API_BASE_URL 和 apikey
  • 目前：google/gemini-2.5-flash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
# 核心 git ai 使用, 注意使用的 git diff HEAD
function ac() {
        local message=$(gitmsg <<< "$(git diff HEAD)")

    if [ -z "$message" ]; then
        echo "Error: Failed to generate commit message." >&2
        return 1
    fi

    echo "Generated commit message:"
    echo "  $message"
    echo

    # 询问用户是否确认使用该提交信息
    echo -n "Use git diff HEAD, Do you want to use this commit message? [Y/n/e] "

    # 兼容 bash 和 zsh 的读取方式
    if [ -n "$ZSH_VERSION" ]; then
                read -k 1 choice < /dev/tty
    else
            read -n 1 choice < /dev/tty
    fi
    echo  # 换行

    case "$choice" in
        [nN])
            echo "Commit cancelled."
            return 1
            ;;
        [eE])
            # 允许用户编辑提交信息
            local temp_file=$(mktemp)
            echo "$message" > "$temp_file"
            ${EDITOR:-vi} "$temp_file"
            message=$(cat "$temp_file")
            rm -f "$temp_file"

            if [ -z "$message" ]; then
                echo "Error: Empty commit message after editing." >&2
                return 1
            fi
            ;;
        *)
            # 默认情况下（Y或直接回车）使用生成的信息
            ;;
    esac


    # 执行 git commit
    git commit -m "$message"
    local exit_code=$?
    if [ $exit_code -eq 0 ]; then
        echo "✓ Commit successful!"
    else
        echo "✗ Commit failed with exit code: $exit_code" >&2
        return $exit_code
    fi
}


# 辅助函数
function gitmsg() {
   sgpt '你是一位资深的软件工程师，擅长编写清晰、规范的 Git 提交信息。根据我提供的内容，生成一条符合「约定式提交规范」的中文 Git 提交信息。要求: 1.  格式: 严格遵循 `< 类型>(<范围>): <主题>` 的格式。常用类型: `feat`(新功能), `fix`(修复), `refactor`(重构), `style`(格式), `docs`(文档), `perf`(性能), `ci`(持续集成), `chore`(杂务)。2.内 容: 用言简意赅的中文进行描述。只描述核心的、用户可感知或对开发者重要的变更。省略不重要的细节，如修改变量名、调整缩进等（除非是`style`类型的提交）。3. 输出:不要添加任何前言、解释或思考过程,直接输出最终的提交信息，且仅输出一条。'
}

3.3 使用 Ai Commit

原理是 git diff 结果，交给 open ai。

1
2
3
4
5
6
7
8
9
10
11
npm install -g aicommits
# 设置轨迹流动私钥
aicommits config set OPENAI_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  
aicommits config set model=deepseek-ai/DeepSeek-V3


npm root -g  #查找一下
vi /opt/homebrew/lib/node_modules/aicommits/dist/cli.mjs
find api.openai.com and replace it with your URL. There is only one occurrence of this text.

await Zi("api.siliconflow.cn","/v1/chat/completions")

3.4 Obsidian Git

在插件的 commit message script 里填写：

1
git diff HEAD -- ':(exclude).obsidian/plugins' ':(exclude).smart-env' | /opt/anaconda3/bin/sgpt '你是一位资深的软件工程师，擅长编写清晰、规范的 Git 提交信息。根据我提供的内容，生成一条符合「约定式提交规范」的中文 Git 提交信息。要 求: 1.  格式: 严格遵循 `<类型>(<范围>): <主题>` 的格式。常用类型: `feat`(新功能), `fix`(修复), `refactor`(重构), `style`(格式), `docs`(文档), `perf`(性能), `ci`(持续集成), `chore`(杂务)。2.内容: 用言简意赅的中文进行描述。只描述核心的、用户可感知或对开发者重要的变更。省略不重要的细节 ，如修改变量名、调整缩进等（除非是`style`类型的提交）。3. 输出:不要添加任何前言、解释或思考过程,直接输出最终的提交信息，且仅输出一条。'