git-commit-convention

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Commit 规范

Git Commit Guidelines

工作模式

Workflow

用户只要求生成或修改 commit message：检查相关 diff 后返回 message，不暂存、不提交。
用户明确要求执行提交：按下述流程检查、暂存并提交。

不要把“生成 commit message”视为执行提交的授权。

If the user only asks to generate or revise a commit message: inspect the relevant diff and return the message without staging or committing anything.
If the user explicitly requests a commit: inspect, stage, and commit the changes according to the workflow below.

Do not treat a request to “generate a commit message” as authorization to execute the commit.

执行流程

Execution Workflow

运行
```
git status --short
```
，检查相关的工作区 diff 和
```
git diff --cached
```
。
明确本次提交应包含哪些文件，并确保 message 只描述这些改动。
如果已有与本次任务无关的暂存内容，保留原状并停止提交，请用户决定是一起提交还是先拆分。
仅在用户要求执行提交时，逐项
```
git add <目标文件>
```
；不得使用
```
git add -A
```
或
```
git add .
```
。
再次检查
```
git diff --cached
```
，确认实际暂存内容与 message 一致后执行
```
git commit
```
。
返回 commit hash 和标题；提交失败时返回原始错误及可行的处理建议。

除非用户明确要求，否则不得执行

git commit --amend

、

git push

或使用

--no-verify

跳过 hooks。

Run
```
git status --short
```
and inspect the relevant worktree diff and
```
git diff --cached
```
.
Clearly determine which files should be included in the commit and ensure that the message describes only those changes.
If there is already staged content unrelated to the current task, leave it unchanged and stop before committing. Ask the user to decide whether to include it in the same commit or split it first.
Only when the user explicitly requests a commit, stage files individually using
```
git add <target file>
```
. Do not use
```
git add -A
```
or
```
git add .
```
.
Check
```
git diff --cached
```
again. After confirming that the staged content matches the message, execute
```
git commit
```
.
Return the commit hash and title. If the commit fails, return the original error and actionable suggestions for resolving it.

Unless explicitly requested by the user, do not execute

git commit --amend

git push

, or use

--no-verify

to bypass hooks.

Message 格式

Message Format

标题格式为

<type>: <subject>

，默认不带 scope；仅当同一次改动需要明确区分模块（如同时涉及前端/后端/CI）时添加

<type>(scope): <subject>

。

type	场景
feat	新功能、新特性
fix	Bug 修复
docs	文档变更
refactor	重构（不改功能、不修 bug）
chore	构建/依赖/配置等杂项
test	添加或修改测试
style	格式调整（不影响逻辑）
perf	性能优化

subject 默认使用中文，

type

保持英文；仅当用户明确要求其他语言时切换。默认单行提交：写完标题直接结束，不追加正文（因此也没有空行）。仅当用户明确要求说明、或确有多个关键改动需要记录时，才用简短中文 bullet 正文。不得编造 diff 中不存在的内容。

The title must follow

<type>: <subject>

and should not include a scope by default. Add

<type>(scope): <subject>

only when the same change needs to clearly distinguish between modules, such as when it involves frontend, backend, and CI changes simultaneously.

type	Use case
feat	New features or functionality
fix	Bug fixes
docs	Documentation changes
refactor	Refactoring that neither changes functionality nor fixes a bug
chore	Build, dependency, configuration, and other miscellaneous changes
test	Adding or modifying tests
style	Formatting changes that do not affect logic
perf	Performance optimizations

The subject should use Chinese by default, while

type

must remain in English. Use another language only when explicitly requested by the user. Use a single-line commit by default: end the message immediately after the title without adding a body, and therefore without a blank line. Add a concise Chinese bulleted body only when the user explicitly requests an explanation or when multiple key changes genuinely need to be documented. Never invent content that is not present in the diff.

提交粒度

Commit Granularity

同一逻辑变更（如同一问题修复、同一功能的多文件调整）默认合并为一个提交，不做过程性小提交。
未推送的同主题提交，可建议
```
git commit --amend
```
合并（执行前仍须用户确认）。
用户明确要求拆分提交时按用户要求执行。

By default, combine the same logical change—such as a single bug fix or a multi-file adjustment for one feature—into one commit rather than creating incremental commits for each step.
For unpushed commits with the same topic, you may recommend combining them with
```
git commit --amend
```
. The user must still confirm before execution.
When the user explicitly requests separate commits, follow the user's instructions.

AI 使用信息（可选）

AI Usage Information (Optional)

默认不写入任何 AI 相关脚注，保持提交信息简洁。仅当用户明确要求记录 AI 信息时，在 message 末尾追加一行：

text

AI-Generated-By: <Agent 名称及版本> / <模型>

获取方式以当前会话/生效配置为准，无法可靠获取时写

unknown

。Git 的 Author 已使用仓库配置的用户名和邮箱，因此不添加

Co-Authored-By

，也不重复写入 Git 用户身份。

By default, do not add any AI-related footer, keeping the commit message concise. Only when the user explicitly requests AI attribution, append the following line to the message:

text

AI-Generated-By: <Agent 名称及版本> / <模型>

Determine the information from the current session or active configuration. If it cannot be obtained reliably, use

unknown

. Because Git's Author identity already uses the username and email configured for the repository, do not add

Co-Authored-By

or repeat the Git user identity.