git-conventional-commit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Conventional Commit

Conventional Commit规范提交

Create git commits that follow the Conventional Commits v1.0.0 specification.

创建遵循Conventional Commits v1.0.0规范的Git提交。

Workflow

工作流程

1. Gather context

1. 收集上下文

Run these in parallel:

git status
git diff --cached
git diff
git log --oneline -10

并行运行以下命令：

git status
git diff --cached
git diff
git log --oneline -10

2. Analyze changes

2. 分析更改

Identify what changed (files, functions, features, fixes)
Identify why it changed (bug fix, new feature, refactor, etc.)
Group related changes — if changes are unrelated, suggest splitting into multiple commits
Check for sensitive files (.env, credentials, secrets) and warn before staging

确定内容变更（文件、函数、功能、修复）
确定原因变更（Bug修复、新功能、重构等）
将相关变更分组——如果变更不相关，建议拆分为多个提交
检查敏感文件（.env、凭据、密钥）并在暂存前发出警告

3. Stage changes

3. 暂存变更

Stage only related changes with
```
git add <specific-files>
```
Never use
```
git add -A
```
or
```
git add .
```
without confirming with the user
If unstaged changes exist that belong to a different logical change, leave them unstaged

使用
```
git add <specific-files>
```
仅暂存相关变更
未经过用户确认，切勿使用
```
git add -A
```
或
```
git add .
```
如果存在属于不同逻辑变更的未暂存内容，保持其未暂存状态

4. Write the commit message

4. 编写提交信息

Format per Conventional Commits v1.0.0:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

遵循Conventional Commits v1.0.0格式：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Type (required)

类型（必填）

Pick the most specific type:

Type	When to use
`feat`	New feature or capability (correlates with SemVer MINOR)
`fix`	Bug fix (correlates with SemVer PATCH)
`docs`	Documentation only
`style`	Formatting, whitespace, semicolons — no logic change
`refactor`	Code change that neither fixes a bug nor adds a feature
`perf`	Performance improvement
`test`	Adding or correcting tests
`build`	Build system or external dependencies (e.g., go.mod, package.json)
`ci`	CI configuration and scripts
`chore`	Maintenance tasks that don't modify src or test files
`revert`	Reverts a previous commit

选择最匹配的类型：

类型	适用场景
`feat`	新功能或能力（对应SemVer的MINOR版本）
`fix`	Bug修复（对应SemVer的PATCH版本）
`docs`	仅涉及文档修改
`style`	格式调整、空白字符、分号修改——无逻辑变更
`refactor`	既不是Bug修复也不是新增功能的代码变更
`perf`	性能优化
`test`	添加或修正测试用例
`build`	构建系统或外部依赖变更（如go.mod、package.json）
`ci`	CI配置和脚本变更
`chore`	不修改源码或测试文件的维护任务
`revert`	回滚之前的提交

Scope (optional)

范围（可选）

A noun in parentheses describing the section of the codebase:

feat(auth): add OAuth2 login flow
fix(parser): handle empty input gracefully
docs(readme): update installation steps

Derive scope from: package name, module, directory, or feature area.

用括号包裹的名词，描述代码库的相关部分：

feat(auth): 添加OAuth2登录流程
fix(parser): 优雅处理空输入
docs(readme): 更新安装步骤

范围可来自：包名、模块、目录或功能区域。

Description (required)

描述（必填）

Imperative mood: "add" not "added" or "adds"
Lowercase first letter
No period at end
Max ~50 characters for the entire first line (type + scope + description)

使用祈使语气：用"add"而非"added"或"adds"
首字母小写
结尾无句号
整行（类型+范围+描述）最多约50个字符

Body (optional)

正文（可选）

Separate from description with a blank line
Explain what and why, not how
Wrap at 72 characters
Use when the description alone is insufficient

与描述之间用空行分隔
说明内容和原因，而非实现方式
每行最多72个字符
当描述不足以说明时使用

Footer (optional)

页脚（可选）

Separate from body with a blank line
Format:
```
token: value
```
or
```
token #value
```
Use
```
-
```
instead of spaces in tokens (except
```
BREAKING CHANGE
```
)

Common footers:

```
BREAKING CHANGE: <description>
```
— breaking API change (SemVer MAJOR)
```
Refs: #123
```
— reference issues
```
Reviewed-by: Name <email>
```
```
Co-authored-by: Name <email>
```

与正文之间用空行分隔
格式：
```
token: value
```
或
```
token #value
```
令牌中用
```
-
```
代替空格（
```
BREAKING CHANGE
```
除外）

常见页脚：

```
BREAKING CHANGE: <description>
```
—— 破坏性API变更（对应SemVer的MAJOR版本）
```
Refs: #123
```
—— 关联议题
```
Reviewed-by: Name <email>
```
```
Co-authored-by: Name <email>
```

Breaking changes

重大变更

Indicate with either:

An exclamation mark after type/scope, e.g.
```
feat(api)!: change response format
```
A
```
BREAKING CHANGE:
```
footer with explanation
Both for maximum clarity

可通过以下任意方式标记：

在类型/范围后添加感叹号，例如
```
feat(api)!: 更改响应格式
```
使用
```
BREAKING CHANGE:
```
页脚并附加说明
同时使用以上两种方式以获得最高清晰度

5. Create the commit

5. 创建提交

Use a HEREDOC for multi-line messages:

bash

git commit -m "$(cat <<'EOF'
feat(auth): add OAuth2 login flow

Implement OAuth2 authorization code flow with PKCE for
secure browser-based authentication. Replaces the legacy
session-based auth which had CSRF vulnerabilities.

BREAKING CHANGE: /api/login now returns a JWT instead of
setting a session cookie
Refs: #342
EOF
)"

For single-line commits:

bash

git commit -m "fix(parser): handle empty input without panic"

使用HEREDOC编写多行提交信息：

bash

git commit -m "$(cat <<'EOF'
feat(auth): add OAuth2 login flow

Implement OAuth2 authorization code flow with PKCE for
secure browser-based authentication. Replaces the legacy
session-based auth which had CSRF vulnerabilities.

BREAKING CHANGE: /api/login now returns a JWT instead of
setting a session cookie
Refs: #342
EOF
)"

单行提交信息示例：

bash

git commit -m "fix(parser): handle empty input without panic"

6. Do NOT push

6. 请勿推送

Never push to remote unless the user explicitly asks.

除非用户明确要求，否则切勿推送到远程仓库。

Examples

示例

Simple fix:

fix: resolve null pointer in user lookup

Scoped feature:

feat(api): add pagination to list endpoints

Multi-line with breaking change:

feat(config)!: switch to YAML configuration format

Migrate from JSON to YAML for all configuration files.
Existing JSON configs are no longer supported.

BREAKING CHANGE: configuration files must be in YAML format
Refs: #891

Documentation:

docs: correct typos in contributing guide

Multiple footers:

fix(db): prevent connection pool exhaustion

Add connection timeout and max idle settings to prevent
pool exhaustion under high load.

Refs: #456
Reviewed-by: Alice <alice@example.com>

简单修复：

fix: 解决用户查找中的空指针问题

带范围的新功能：

feat(api): 为列表端点添加分页功能

含重大变更的多行提交：

feat(config)!: 切换为YAML配置格式

将所有配置文件从JSON迁移到YAML格式。
不再支持原有的JSON配置文件。

BREAKING CHANGE: 配置文件必须为YAML格式
Refs: #891

文档修改：

docs: 修正贡献指南中的拼写错误

多页脚示例：

fix(db): 防止连接池耗尽

添加连接超时和最大空闲连接设置，以避免
高负载下的连接池耗尽问题。

Refs: #456
Reviewed-by: Alice <alice@example.com>