semantic-commit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Semantic Commit

语义化Git提交

Create git commits following the Conventional Commits specification.

创建符合Conventional Commits规范的Git提交。

Commit Format

提交格式

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

<type>[可选 scope]: <描述>

[可选 正文]

[可选 页脚]

Guidelines

规范指南

Start with a short prefix followed by colon and space (feat:, fix:, docs:, refactor:, test:, chore:, etc.)
Isolate your changes and commit only what you did (no unrelated files)
feat: for user-visible features, fix: for bug fixes
A scope MAY be added in parentheses, e.g.
```
fix(parser):
```
- only when it meaningfully improves clarity
Short description in imperative mood explaining what changed, not how
Body MAY be included after one blank line for context, rationale, or non-obvious behavior
Footers MAY be included (Token: value format, use
```
-
```
instead of spaces in tokens)
Breaking changes should be explained clearly in description or body, no special marking required
Clarity and usefulness matter more than strict conformance

以简短前缀开头，后跟冒号和空格（feat:, fix:, docs:, refactor:, test:, chore:等）
隔离变更内容，仅提交你本次修改的内容（不要包含无关文件）
feat: 用于用户可见的新功能，fix: 用于修复bug
可在括号中添加scope，例如
```
fix(parser):
```
- 仅当它能显著提升清晰度时才添加
简短描述使用祈使语气，说明变更内容而非实现方式
若需要补充上下文、理由或非直观行为说明，可在空一行后添加正文
可添加页脚（采用Token: 值的格式，Token中用
```
-
```
代替空格）
破坏性变更需在描述或正文中清晰说明，无需特殊标记
清晰度和实用性比严格遵循规范更重要

Commit Types

提交类型

Type	Description
`feat`	A new feature (user-visible)
`fix`	A bug fix (user-visible)
`docs`	Documentation only changes
`style`	Changes that do not affect the meaning of the code (formatting, semicolons, etc.)
`refactor`	A code change that neither fixes a bug nor adds a feature
`perf`	A code change that improves performance
`test`	Adding missing tests or correcting existing tests
`build`	Changes that affect the build system or external dependencies
`ci`	Changes to CI configuration files and scripts
`chore`	Other changes that don't modify src or test files
`revert`	Reverts a previous commit

类型	描述
`feat`	用户可见的新功能
`fix`	用户可见的bug修复
`docs`	仅修改文档
`style`	不影响代码含义的变更（如格式化、分号调整等）
`refactor`	既不修复bug也不添加功能的代码变更
`perf`	提升性能的代码变更
`test`	添加缺失测试或修正现有测试
`build`	影响构建系统或外部依赖的变更
`ci`	修改CI配置文件和脚本
`chore`	其他不修改源码或测试文件的变更
`revert`	回滚之前的提交

Workflow

工作流程

dot

digraph commit_workflow {
    rankdir=TB;
    node [shape=box];
    
    check [label="Check git status"];
    stage [label="Stage changes\n(if needed)"];
    review [label="Review staged diff"];
    analyze [label="Analyze changes\nDetermine type & scope"];
    write [label="Write commit message"];
    commit [label="Execute git commit"];
    
    check -> stage;
    stage -> review;
    review -> analyze;
    analyze -> write;
    write -> commit;
}

dot

digraph commit_workflow {
    rankdir=TB;
    node [shape=box];
    
    check [label="Check git status"];
    stage [label="Stage changes\n(if needed)"];
    review [label="Review staged diff"];
    analyze [label="Analyze changes\nDetermine type & scope"];
    write [label="Write commit message"];
    commit [label="Execute git commit"];
    
    check -> stage;
    stage -> review;
    review -> analyze;
    analyze -> write;
    write -> commit;
}

1. Check Repository State

1. 检查仓库状态

bash

git status --short
git diff --cached --stat   # staged changes
git diff --stat            # unstaged changes

bash

git status --short
git diff --cached --stat   # 已暂存的变更
git diff --stat            # 未暂存的变更

2. Stage Changes

2. 暂存变更

If no changes are staged:

Ask which files to stage
Stage only files you changed for this task (avoid unrelated changes)

如果没有已暂存的变更：

询问需要暂存哪些文件
仅暂存本次任务修改的文件（避免无关变更）

3. Review Staged Changes

3. 审核已暂存的变更

bash

git diff --cached

Understand what was modified to write an accurate message.

bash

git diff --cached

了解修改内容，以便撰写准确的提交消息。

4. Determine Type and Scope

4. 确定类型和Scope

Based on the changes:

Type: What category of change? (feat, fix, refactor, etc.)
Scope: What area of the codebase? Only add when it meaningfully improves clarity
Breaking: Does this break backward compatibility? Explain clearly in description or body

根据变更内容：

类型：变更属于哪一类别？（feat、fix、refactor等）
Scope：代码库的哪个区域？仅当能显著提升清晰度时才添加
破坏性：是否破坏向后兼容性？需在描述或正文中清晰说明

Writing Good Commit Messages

撰写优质提交消息

Subject Line

主题行

Use imperative mood: "add feature" not "added feature"
Keep under 50 characters when possible
Don't end with a period
Explain what changed, not how

<Good> ``` feat(auth): add OAuth2 login support fix: prevent crash on empty input refactor(api): extract validation logic ``` </Good> <Bad> ``` updated some stuff fix bug WIP changes ``` </Bad>

使用祈使语气："add feature" 而非 "added feature"
尽可能控制在50字符以内
结尾不要加句号
说明变更内容而非实现方式

<正确示例>

feat(auth): add OAuth2 login support
fix: prevent crash on empty input
refactor(api): extract validation logic

</正确示例>

<错误示例>

updated some stuff
fix bug
WIP
changes

</错误示例>

Body (Optional)

正文（可选）

Include after one blank line when context, rationale, or non-obvious behavior needs explanation:

Explain motivation for the change
Contrast with previous behavior
Note any side effects

fix(parser): handle unicode characters in filenames

Previously, filenames with non-ASCII characters would cause
a decode error. Now using UTF-8 decoding with fallback to
latin-1 for legacy files.

Closes #123

当需要说明上下文、理由或非直观行为时，可在空一行后添加正文：

说明变更的动机
对比之前的行为
注明任何副作用

fix(parser): handle unicode characters in filenames

Previously, filenames with non-ASCII characters would cause
a decode error. Now using UTF-8 decoding with fallback to
latin-1 for legacy files.

Closes #123

Footer (Optional)

页脚（可选）

Use Token: value format (use

instead of spaces in token names):

```
Closes #123
```
or
```
Fixes #456
```
for issue references
```
Co-authored-by: Name <email>
```
for pair programming
```
Reviewed-by: Name <email>
```
for review attribution

采用Token: 值的格式（Token名称中用

代替空格）：

```
Closes #123
```
或
```
Fixes #456
```
用于关联议题
```
Co-authored-by: Name <email>
```
用于结对编程署名
```
Reviewed-by: Name <email>
```
用于审核署名

Examples

示例

Changes	Commit
New endpoint added	`feat(api): add user profile endpoint`
Bug causing crash	`fix: prevent null pointer on empty config`
Updated README	`docs: add installation instructions`
Reformatted code	`style: apply prettier formatting`
Renamed internal function	`refactor: rename processData to parseInput`
Optimized query	`perf(db): add index for user lookups`
Added unit tests	`test: add coverage for auth module`
Updated dependencies	`build: upgrade react to v18`
Changed CI config	`ci: add node 20 to test matrix`
Cleaned up files	`chore: remove unused imports`
Breaking API change	`feat(api): change response format to JSON arrays`

变更内容	提交消息
添加新接口	`feat(api): add user profile endpoint`
修复导致崩溃的bug	`fix: prevent null pointer on empty config`
更新README	`docs: add installation instructions`
格式化代码	`style: apply prettier formatting`
重命名内部函数	`refactor: rename processData to parseInput`
优化查询	`perf(db): add index for user lookups`
添加单元测试	`test: add coverage for auth module`
更新依赖	`build: upgrade react to v18`
修改CI配置	`ci: add node 20 to test matrix`
清理文件	`chore: remove unused imports`
破坏性API变更	`feat(api): change response format to JSON arrays`

Common Mistakes

常见错误

Mistake	Fix
Past tense ("added")	Use imperative ("add")
Too vague ("fix bug")	Be specific ("fix null check in parser")
Too long subject	Keep concise, move details to body
Wrong type	`fix` = bug, `feat` = new capability, `refactor` = no behavior change
Combining unrelated changes	Split into multiple commits
Overusing scope	Only add scope when it meaningfully improves clarity

错误	修正方式
使用过去式（"added"）	使用祈使语气（"add"）
描述过于模糊（"fix bug"）	具体化描述（"fix null check in parser"）
主题行过长	保持简洁，将细节移至正文
类型选择错误	`fix` =修复bug， `feat` =新增功能， `refactor` =无行为变更的代码调整
合并无关变更	拆分为多个提交
过度使用scope	仅当能显著提升清晰度时才添加scope

Quick Reference

快速参考

feat:     New feature for users
fix:      Bug fix for users  
docs:     Documentation only
style:    Formatting, no logic change
refactor: Code change, no behavior change
perf:     Performance improvement
test:     Adding/fixing tests
build:    Build system, dependencies
ci:       CI configuration
chore:    Maintenance, tooling
revert:   Reverting commits

feat:     用户可见新功能
fix:      用户可见bug修复  
docs:     仅修改文档
style:    格式化调整，无逻辑变更
refactor: 代码调整，无行为变更
perf:     性能优化
test:     添加/修复测试
build:    构建系统、依赖变更
ci:       CI配置变更
chore:    维护工作、工具调整
revert:   回滚提交