git-commit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Commit

Git 提交

Overview

概述

Write commit messages from actual repository changes. Prefer concise, intention-focused messages over file-by-file diff summaries. Treat

references/commit-convention.md

as the baseline style guide, then adapt scope and wording to the current repository.

根据实际仓库变更编写提交信息。优先使用简洁、聚焦意图的信息，而不是逐文件复述 diff。以

references/commit-convention.md

作为基础风格指南，再根据当前仓库调整 scope 和措辞。

Workflow

工作流

Inspect the change set first.
- Prefer
```
git diff --staged
```
  when changes are staged.
- Use
```
git diff
```
  when no staged diff exists or when the user asks about unstaged changes.
- Use
```
git status --short
```
  to understand file scope.
- If the repository contains a commit convention file, read it before writing the message. Check likely names such as
```
COMMIT_CONVENTION.md
```
  ,
```
CONTRIBUTING.md
```
  ,
```
.github/COMMIT_CONVENTION.md
```
  , or
```
.github/CONTRIBUTING.md
```
  .
- Inspect recent commit subjects with
```
git log --format=%s -n 20
```
  to infer the repository's preferred output language. Follow the dominant language used in history. If recent commit subjects are mixed with no clear dominant language, or if there is no commit history or another error prevents inspection, default to English.
Choose one commit intent.
- If changes contain unrelated intents, recommend splitting commits.
- If the user still wants one message, choose the dominant intent and explain the tradeoff briefly.
Choose the header:

text

<type>(<scope>): <subject>

Add a body only when it clarifies intent, impact, compatibility, migration, or mixed change types.

首先检查变更集。
- 有已暂存变更时，优先使用
```
git diff --staged
```
  。
- 没有已暂存的 diff，或用户询问未暂存变更时，使用
```
git diff
```
  。
- 使用
```
git status --short
```
  了解变更涉及的文件范围。
- 如果仓库包含提交规范文件，应在编写信息前读取该文件。检查可能存在的名称，例如
```
COMMIT_CONVENTION.md
```
  、
```
CONTRIBUTING.md
```
  、
```
.github/COMMIT_CONVENTION.md
```
  或
```
.github/CONTRIBUTING.md
```
  。
- 使用
```
git log --format=%s -n 20
```
  检查近期提交主题，以推断仓库偏好的输出语言。遵循历史记录中的主导语言。如果近期提交主题语言混杂、没有明确的主导语言，或者没有提交历史或其他错误导致无法检查，则默认使用英文。
选择一个提交意图。
- 如果变更包含互不相关的意图，建议拆分为多个提交。
- 如果用户仍希望只使用一条信息，则选择主导意图，并简要说明这种取舍。
选择标题：

text

<type>(<scope>): <subject>

仅在有助于说明意图、影响、兼容性、迁移或混合变更类型时添加 body。

Type Selection

Type 选择

```
feat
```
: new feature
```
fix
```
: bug or defect fix
```
perf
```
: performance improvement
```
refactor
```
: implementation restructuring without external behavior changes
```
style
```
: formatting or code style only
```
test
```
: test additions or adjustments
```
docs
```
: documentation or comments
```
chore
```
: dependencies, build, scaffolding, and miscellaneous maintenance
```
ci
```
: CI changes
```
types
```
: type definition changes
```
revert
```
: revert an existing commit
```
wip
```
: temporary work-in-progress commit

For mixed changes, either split commits or use the dominant type in the header and type-prefixed bullets in the body.

```
feat
```
：新功能
```
fix
```
：错误或缺陷修复
```
perf
```
：性能改进
```
refactor
```
：不改变外部行为的实现重构
```
style
```
：仅涉及格式或代码风格
```
test
```
：新增或调整测试
```
docs
```
：文档或注释
```
chore
```
：依赖、构建、脚手架及其他杂项维护
```
ci
```
：CI 变更
```
types
```
：类型定义变更
```
revert
```
：回退已有提交
```
wip
```
：临时的进行中提交

对于混合变更，可以选择拆分提交，或者在标题中使用主导 type，并在 body 中使用带 type 前缀的条目。

Scope Selection

Scope 选择

Derive

scope

from the current repository. Do not reuse scopes from the reference file unless they match actual changed paths or local conventions.

Use this priority:

Use scopes explicitly defined by the repository's own commit convention.
Use a stable workspace/package/app/module name from changed paths, such as
```
api
```
,
```
web
```
,
```
cli
```
,
```
core
```
,
```
ui
```
,
```
docs
```
, or the package name.
Use a more precise long-lived submodule name only when the change is clearly concentrated there and the name is reusable.
Use
```
repo
```
for repository-level changes, cross-cutting changes, or changes that cannot be reduced to one module.

If no meaningful scope is required by the repository's convention, omit it only when the local style allows scope-less headers.

从当前仓库中推导

scope

。除非参考文件中的 scope 与实际变更路径或本地约定一致，否则不要直接复用。

按以下优先级选择：

使用仓库自身提交规范中明确定义的 scope。
使用从变更路径中提取的稳定 workspace、package、app 或 module 名称，例如
```
api
```
、
```
web
```
、
```
cli
```
、
```
core
```
、
```
ui
```
、
```
docs
```
或 package 名称。
仅当变更明显集中于某个模块，且该名称可重复使用时，才使用更精确、长期存在的 submodule 名称。
对于仓库级变更、跨模块变更，或无法归入单一模块的变更，使用
```
repo
```
。

如果仓库约定不要求有意义的 scope，则仅在本地风格允许无 scope 标题时省略。

Subject And Body

Subject 与 Body

Write the subject as the core intent of the change. Keep it short, concrete, and action-oriented. Avoid vague subjects such as

update

fix bug

, or

optimize code

Match the output language to the repository's recent commit history. Use the dominant language when it is clear. If the recent history is inconsistent or mixed, or if there is no commit history or another inspection failure, write the commit message in English by default.

Write the body when useful:

Describe intent, impact, and necessary background.
Avoid restating each changed file.
If all bullets are the same change type, do not repeat the type in every bullet.
If the commit mixes change types, prefix body bullets with
```
type:
```
.

Examples:

text

feat(auth): add session refresh flow

- 增加会话刷新入口，减少登录态过期后的重复认证
- 补齐旧 token 兼容逻辑，避免升级后状态丢失

text

refactor: align release workflow

- refactor: 收敛构建与发布脚本的职责边界
- fix: 修正缺少版本号时的默认值异常
- docs: 补充新的发布流程说明

将 subject 写为变更的核心意图。内容应简短、具体且以行动为导向。避免使用

update

、

fix bug

或

optimize code

等含糊表述。

输出语言应与仓库近期提交历史保持一致。当主导语言清晰明确时，使用该语言。如果近期历史不一致或语言混杂，或者没有提交历史或其他检查失败，则默认使用英文编写提交信息。

在有帮助时编写 body：

说明意图、影响和必要的背景信息。
避免逐个复述变更文件。
如果所有条目的变更类型相同，不要在每个条目中重复 type。
如果提交混合了多种变更类型，请在 body 条目前加上
```
type:
```
。

示例：

text

feat(auth): 添加会话刷新流程

- 增加会话刷新入口，减少登录态过期后的重复认证
- 补齐旧 token 兼容逻辑，避免升级后状态丢失

text

refactor: 对齐发布工作流

- refactor: 收敛构建与发布脚本的职责边界
- fix: 修正缺少版本号时的默认值异常
- docs: 补充新的发布流程说明

Reference

参考

Read

references/commit-convention.md

for the baseline Conventional Commits rules and examples. Override its scope examples with the current repository's structure.

阅读

references/commit-convention.md

，了解基础的 Conventional Commits 规则和示例。应以当前仓库结构覆盖其中的 scope 示例。