Back to Details

git-commit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Git Commit with Conventional Commits

基于Conventional Commits的Git提交

Overview

概述

Create standardized, semantic git commits using the Conventional Commits specification. Analyze the actual diff to determine appropriate type, scope, and message.
使用Conventional Commits规范创建标准化的语义化git提交。分析实际差异以确定合适的类型、范围和消息。

Commit format

提交格式

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
<type>[可选范围]: <描述>

[可选正文]

[可选页脚]

Commit types

提交类型

TypePurpose
feat
New feature
fix
Bug fix
docs
Documentation only
style
Formatting/style (no logic)
refactor
Code refactor (no feature/fix)
perf
Performance improvement
test
Add/update tests
build
Build system/dependencies
ci
CI/config changes
chore
Maintenance/misc
revert
Revert commit
类型用途
feat
新功能
fix
Bug修复
docs
仅修改文档
style
格式/样式调整（无逻辑变更）
refactor
代码重构（无新功能/Bug修复）
perf
性能优化
test
添加/更新测试
build
构建系统/依赖项变更
ci
CI/配置变更
chore
维护/杂项任务
revert
回退提交

Breaking changes

破坏性变更

Exclamation mark after type/scope:
feat!: remove deprecated endpoint
And/or: 
BREAKING CHANGE
footer
feat: allow config to extend other configs

BREAKING CHANGE: `extends` key behavior changed
在类型/范围后添加感叹号：
feat!: 移除已弃用的端点
和/或添加 
BREAKING CHANGE
页脚：
feat: 允许配置继承其他配置

BREAKING CHANGE: `extends` 键的行为已更改

Workflow

工作流程

1. Inspect status

1. 检查状态

bash
git status --porcelain
Default behavior:
  • Prefer already staged changes when present.
  • If nothing is staged, stage only the coherent logical change.
  • Leave unrelated worktree changes untouched.
bash
git status --porcelain
默认行为：
  • 如果存在已暂存的更改，优先使用这些更改。
  • 如果没有任何内容被暂存，仅暂存逻辑连贯的更改。
  • 不改动无关的工作区更改。

2. Analyze diff

2. 分析差异

bash
undefined
bash
undefined

If files are staged, use staged diff.

如果文件已暂存，使用暂存区差异。

git diff --staged
git diff --staged

If nothing is staged, use working tree diff.

如果没有暂存内容，使用工作区差异。

git diff

When staged and unstaged changes coexist, commit only the staged changes by default. If the staged changes appear incomplete, inspect the unstaged diff and decide whether to stage closely related files or ask the user.
git diff

当暂存和未暂存变更同时存在时，默认仅提交已暂存的变更。如果已暂存的变更看起来不完整，检查未暂存的差异，决定是否暂存密切相关的文件或询问用户。

3. Stage files (if needed)

3. 暂存文件（如有需要）

If nothing is staged or you want to group changes differently:
bash
undefined
如果没有任何内容被暂存或需要重新分组变更：
bash
undefined

Stage specific files

暂存特定文件

git add path/to/file1 path/to/file2
git add path/to/file1 path/to/file2

Stage by pattern

按模式暂存

git add .test. git add src/components/*

**Never commit secrets** (.env, credentials.json, private keys).
git add .test. git add src/components/*

**切勿提交机密信息**（.env、credentials.json、私钥等）。

4. Generate commit message

4. 生成提交消息

Analyze the diff to determine:
  • Type: What kind of change is this?
  • Scope: What area/module is affected?
  • Description: One-line summary of what changed. (present tense, imperative mood, <72 chars)
Use the smallest accurate type and scope. Prefer short, single-line commits with no body. Add a body only when the commit is large or nuanced enough that it cannot be summarized clearly in one short sentence. Do not add an explanatory body just because extra context is available.
Use breaking-change syntax only when the diff truly changes a public contract.
分析差异以确定：
  • 类型：这是何种类型的变更？
  • 范围：哪个区域/模块受到影响？
  • 描述：变更内容的单行摘要（使用现在时、祈使语气，长度<72字符）。
使用最精确的最小类型和范围。优先使用简短的单行提交，无需正文。仅当提交内容较大或细节丰富，无法用一句话清晰概括时才添加正文。不要仅因为有额外上下文就添加解释性正文。
仅当差异真正更改了公共契约时，才使用破坏性变更语法。

5. Execute commit

5. 执行提交

bash
undefined
bash
undefined

Single line

单行提交

git commit -m "<type>[scope]: <description>"
git commit -m "<type>[scope]: <description>"

Multi-line with body/footer

带正文/页脚的多行提交

git commit -m "$(cat <<'EOF' <type>[scope]: <description>
<optional body> <optional footer> EOF )" ```
git commit -m "$(cat <<'EOF' <type>[scope]: <description>
<可选正文>
<可选页脚> EOF )"
undefined

Best practices

最佳实践

  • One logical change per commit.
  • Present tense: "add" not "added".
  • Imperative mood: "fix bug" not "fixes bug".
  • Keep description under 72 characters.
  • Reference issues with trailers such as 
    Closes #123
    or 
    Refs #456
    only when the diff or user request provides that context; If there is no body, append after the description instead: 
    feat: add login, closes #123
  • 每次提交对应一个逻辑变更。
  • 使用现在时：用“add”而非“added”。
  • 使用祈使语气：用“fix bug”而非“fixes bug”。
  • 描述长度保持在72字符以内。
  • 仅当差异或用户请求提供相关上下文时，才用 
    Closes #123
    或 
    Refs #456
    等尾部信息引用问题；如果没有正文，可将其附加在描述后：
    feat: 添加登录功能, closes #123

Git safety protocol

Git安全协议

  • Never update git config.
  • Never run destructive commands (--force, hard reset) without explicit request.
  • Never skip hooks (--no-verify) unless user asks.
  • Never force push to main/master.
  • If hooks fail before the commit is created, fix the issue and retry
  • If a commit was created and later validation fails, do not amend unless requested
  • 切勿修改git配置。
  • 除非有明确请求，否则切勿运行破坏性命令（--force、硬重置）。
  • 除非用户要求，否则切勿跳过钩子（--no-verify）。
  • 切勿强制推送到main/master分支。
  • 如果在提交创建前钩子执行失败，修复问题后重试
  • 如果提交已创建但后续验证失败，除非有请求否则不要修改提交

Final verification

最终验证

After committing:
bash
git status --short
git log -1 --oneline
Report the new commit hash and subject. Mention any remaining unstaged or untracked changes.
提交完成后：
bash
git status --short
git log -1 --oneline
报告新的提交哈希和主题。提及任何剩余的未暂存或未跟踪变更。

References

参考资料