git的提交规范

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

1. Git 规范

1.1 基本的 Commit 信息格式

一个常见的提交信息格式通常包括以下几个部分：

  • 类型（type）: 描述提交的类别，比如是新功能、修复、文档等。
  • 范围（scope）: 可选，描述提交影响的范围，比如是某个模块、功能等。
  • 主题（subject）: 简短的描述提交的目的。
  • 正文（body）: 可选，详细描述提交的内容、动机等。
  • 页脚（footer）: 可选，通常用于关闭某个 issue 或者添加破坏性变更的说明。

1.2 常见的类型（type）

直接判断：这个提交是否值得出现在最终的发行版上线日志（CHANGELOG）里？

  • 如果是，那它很可能是 feat 或 fix。
  • 如果否，那它更可能是 refactor, style, chore 等其他类型。

常见：

  • feat: 新功能 (feature)
    • 判断标准： 这次提交是否增加了代码库的新能力？
    • feat: 实现网站的暗黑模式切换
  • fix: 修复 bug
    • 判断标准： 这次提交是否修正了一个不正确的行为？
    • fix：解决 Safari 浏览器下日期显示不正确的问题
  • refactor: 代码重构（既不是新增功能，也不是修复 bug）
    • 判断标准： 用户或测试人员感觉不到任何变化，但代码变得更 “ 好 “ 了（更清晰、更高效、更易于扩展）。
    • refactor：移除重复的代码块，抽象成一个通用函数
  • docs: 文档修改
    • 判断标准： 只改动了 .md 文件或代码里的注释。
    • docs: 更新 README，补充项目本地启动步骤
  • style: 代码格式修改（不影响代码逻辑，如空格、分号等）
    • 判断标准： 由 Prettier、ESLint 等格式化工具自动生成的改动，或者手动调整了代码外观。
    • style: 移除多余的空行和未使用的 import 语句
  • test: 增加或修改测试
    • 判断标准： 只修改了测试文件（如 *.test.js, *.spec.js）或测试配置文件。
    • test(login): 为登录成功和失败的场景添加单元测试
  • perf: 性能优化
  • revert: 回滚某个先前的提交
  • build: 修改构建系统或外部依赖（如 a.js、npm）
    • 判断标准： 是否修改了 package.json、webpack.config.js、vite.config.js、pom.xml 这类文件？
    • build(deps): 添加 axios 库用于网络请求
  • ci: 修改 CI/CD 配置文件和脚本
    • 判断标准： 是否修改了 .github/workflows/、.travis.yml、Dockerfile 这类文件？
    • ci: 优化 Docker 镜像构建，减少镜像大小
  • chore: 其他不修改源码或测试的提交（杂项，其他不属于以上任何类型的琐碎修改，通常是辅助性的工具或配置改动。）
    • 判断标准： “ 家务活 “，不修改源代码、不修改测试、不修改构建和 CI，但又是必要的改动。
    • chore: 更新 .gitignore 文件，忽略 .env 本地配置文件

1.3 示例

1
2
3
4
git commit -m "feat(auth): add login functionality"
git commit -m "fix(cart): handle case when cart is empty"
git commit -m "docs(readme): update installation instructions"
git commit -m "refactor(user): simplify user model"

2. 规范工具

2.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

2.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. 输出:不要添加任何前言、解释或思考过程,直接输出最终的提交信息，且仅输出一条。'
}

2.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")

2.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. 输出:不要添加任何前言、解释或思考过程,直接输出最终的提交信息，且仅输出一条。'