commit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create exactly one coherent commit while preserving changes outside its intended scope. Write the commit message in English and communicate with the user in their language. Follow explicit user instructions and applicable repository guidance before the defaults below.

创建恰好一个连贯的提交，同时保留其预期范围之外的变更。提交信息需使用英文撰写，与用户沟通时使用用户的语言。在遵循以下默认规则前，请优先执行用户的明确指令及适用的仓库指南。

Repository Context

仓库上下文

Status: !
```
git status --short
```
Staged changes: !
```
git diff --cached
```
Unstaged changes: !
```
git diff
```

Untracked files: !

git ls-files --others --exclude-standard

Unmerged files: !
```
git diff --name-only --diff-filter=U
```
Current branch: !
```
git branch --show-current
```
Recent commits: !
```
git log --oneline -10
```

状态: !
```
git status --short
```
已暂存变更: !
```
git diff --cached
```
未暂存变更: !
```
git diff
```

未追踪文件: !

git ls-files --others --exclude-standard

未合并文件: !
```
git diff --name-only --diff-filter=U
```
当前分支: !
```
git branch --show-current
```
近期提交: !
```
git log --oneline -10
```

1. Define the Commit Scope

1. 定义提交范围

If the worktree and index contain no changes, tell the user there is nothing to commit and stop.
Select the target changes in this order:
- If the user named files or a logical change, use that scope. If unrelated changes are already staged, explain the conflict and ask how to proceed before changing the index.
- Otherwise, if staged changes exist, treat the staged diff as the complete target. Leave unstaged and untracked changes untouched.
- Otherwise, group unstaged and untracked changes by purpose. If they form one clear logical change, use that group. If there are multiple plausible groups or a file's inclusion is ambiguous, present the groups and ask which one to commit.
Judge cohesion by behavior and purpose, not by file count alone. Keep tests, documentation, and configuration with the implementation they directly support.

如果工作区和索引中没有任何变更，告知用户没有可提交的内容并停止操作。
按以下顺序选择目标变更:
- 如果用户指定了文件或某个逻辑变更，使用该范围。如果已有无关变更被暂存，说明冲突情况并询问用户如何处理，再修改索引。
- 否则，如果存在已暂存变更，将已暂存的差异视为完整目标。保留未暂存和未追踪的变更不动。
- 否则，按用途对未暂存和未追踪的变更进行分组。如果它们构成一个清晰的逻辑变更，使用该分组。如果存在多个合理分组或某个文件的归属不明确，展示分组并询问用户要提交哪一组。
根据行为和用途判断连贯性，而非仅依据文件数量。将测试、文档和配置与它们直接支持的实现代码放在同一提交中。

2. Prepare the Index

2. 准备索引

When the exact target is not already staged, stage only its files with explicit pathspecs:

bash

git add -- "path/with[brackets]/file.ts" "another path/file.md"

Use

--

before paths and quote paths containing spaces, brackets, parentheses, wildcards, or other shell-special characters. Include untracked files only when they are part of the target change. Exclude local configuration, credentials, temporary files, logs, and build artifacts unless repository guidance explicitly tracks them and they are required by the change. If a target file mixes relevant and unrelated hunks, stage only the relevant hunks; ask the user before staging the whole file when safe partial staging is not practical.

After staging, re-run

git status --short

and

git diff --cached

. The staged diff is now the sole source of truth for the commit.

当确切的目标变更尚未被暂存时，仅使用明确的路径规范暂存目标文件:

bash

git add -- "path/with[brackets]/file.ts" "another path/file.md"

在路径前使用

--

，并为包含空格、方括号、圆括号、通配符或其他shell特殊字符的路径添加引号。仅当未追踪文件属于目标变更的一部分时才将其包含在内。排除本地配置、凭据、临时文件、日志和构建产物，除非仓库指南明确要求追踪它们且它们是变更必需的。如果目标文件混合了相关和无关的代码块，仅暂存相关的代码块；当无法安全地部分暂存时，在暂存整个文件前询问用户。

暂存完成后，重新运行

git status --short

和

git diff --cached

。此时已暂存的差异将作为提交的唯一依据。

3. Review the Staged Diff

3. 审核已暂存差异

Stop before committing when any blocking condition is present:

Condition	Required action
Empty staged diff	Tell the user there is nothing staged for this commit.
Unmerged entries or real conflict markers	List the affected files and ask the user to resolve them.
Suspected secret, credential, private key, or unintended `.env` file	Identify the location without repeating the value; ask the user to remove it or confirm it is non-secret test data.
Unclear or unrelated staged content	Explain the mismatch and ask how to scope the commit.

Also inspect added lines for accidental debug statements, generated output, logs, and unexplained

TODO

FIXME

markers. Ask only when an item appears unintended; do not treat every occurrence as an error.

当存在任何阻塞条件时，在提交前停止操作:

条件	所需操作
已暂存差异为空	告知用户本次提交没有暂存任何内容。
存在未合并条目或实际冲突标记	列出受影响的文件并要求用户解决冲突。
疑似包含密钥、凭据、私钥或意外的 `.env` 文件	指出位置但不重复内容；询问用户移除该内容或确认其为非保密测试数据。
已暂存内容不清晰或无关	说明不匹配情况并询问用户如何确定提交范围。

同时检查新增行中是否存在意外的调试语句、生成的输出、日志以及未说明的

TODO

或

FIXME

标记。仅当条目看起来是意外添加时才询问用户；不要将所有此类标记都视为错误。

4. Compose the Message

4. 撰写提交信息

Treat the message as a compact, standalone explanation for a human or coding agent that may not inspect the diff. Prioritize the changed behavior or system rule over author activity, file lists, and implementation inventory. Ground every claim in the staged changes and relevant repository context.

First follow an explicit repository commit convention. Use recent commit history as supporting evidence, not as a replacement for written guidance. Then distill:

The primary before-and-after change in behavior, capability, data flow, or system rule.
The single core intuition that explains most of the staged diff.
Only the context needed to prevent a reader from forming the wrong mental model.

When no convention is defined, use these defaults:

Title (subject): Start with an imperative English verb. Name the affected concept and its changed behavior or governing rule, not merely the editing action or a broad benefit. Prefer
```
Deduplicate retries by request ID
```
to
```
Update retry handling
```
. Omit a trailing period and keep the title concise; do not exceed 72 characters.
Description (body): Default to one short paragraph whose first sentence states the smallest true transition:
```
Previously, <old rule>. Now, <new rule>.
```
Include the deciding unit, direction, or unchanged boundary only when it is part of that transition. Omit the body only when the title itself makes both sides and the governing rule recoverable. Do not summarize files or tests.
Use one minimal toy example when concrete input, state, or output makes a non-obvious rule faster to understand. For example:
```
Attempts r1, r1, r2 now create two jobs instead of three because request ID defines identity.
```
Keep the example faithful to the diff; do not invent unsupported behavior.
After the intuition, include motivation, an important constraint or tradeoff, breaking behavior, or migration guidance only when it materially helps the reader understand or act on the change.
Separate the description from the title with a blank line and wrap body lines at 72 characters.

Do not turn the description into a file-by-file or hunk-by-hunk summary. Omit secondary edits, routine tests, and mechanical details unless they change the core mental model. Do not force a body or toy example based only on change size.

提交信息应是一份简洁、独立的说明，供人类或代码Agent阅读，无需查看差异内容。优先描述变更后的行为或系统规则，而非作者的操作、文件列表或实现细节。所有表述都应基于已暂存的变更和相关仓库上下文。

首先遵循明确的仓库提交规范。将近期提交历史作为辅助参考，而非书面指南的替代。然后提炼以下内容:

行为、能力、数据流或系统规则的主要前后变化。
能够解释大部分已暂存差异的核心逻辑。
仅保留防止读者形成错误认知所需的上下文信息。

当没有定义规范时，使用以下默认规则:

标题（主题）: 以英文祈使动词开头。指明受影响的概念及其变更后的行为或规则，而非仅编辑操作或宽泛的收益。优先使用
```
Deduplicate retries by request ID
```
而非
```
Update retry handling
```
。末尾不要加句号，保持标题简洁；长度不超过72个字符。
描述（正文）: 默认使用一个简短段落，第一句说明最精准的转变:
```
Previously, <old rule>. Now, <new rule>.
```
仅当决策单元、方向或未变更边界属于该转变的一部分时才包含它们。仅当标题本身能清晰体现前后变化和规则时才省略正文。不要总结文件或测试内容。
当具体的输入、状态或输出能让非显而易见的规则更容易理解时，使用一个简单的示例。例如:
```
Attempts r1, r1, r2 now create two jobs instead of three because request ID defines identity.
```
示例需忠实于差异内容；不要编造未被支持的行为。
在核心逻辑之后，仅当动机、重要约束或权衡、破坏性行为或迁移指南能切实帮助读者理解或实施变更时才包含这些内容。
用空行分隔标题和描述，正文每行不超过72个字符。

不要将描述变成逐文件或逐代码块的总结。除非次要编辑、常规测试和机械细节会改变核心认知，否则省略这些内容。不要仅根据变更大小强行添加正文或示例。

5. Verify and Commit

5. 验证并提交

Before executing the commit, review

git diff --cached

one final time and verify:

Every staged change belongs to the selected scope.
The message gives an accurate core mental model of the staged change without requiring file-by-file inspection or claiming unstaged work.
The staged diff still passes the safety review above.

For a subject-only message, run:

bash

git commit -m "Subject line"

For a message with a body, use separate

-m

arguments so Git inserts a real blank line. Put real line breaks in a long body; never encode them as literal

\n

text.

bash

git commit \
  -m "Deduplicate retries by request ID" \
  -m "Retries now treat request ID as the unit of identity. Attempts r1, r1,
r2 create two jobs instead of three."

If the commit fails, inspect the error and current status before taking further action. If a hook modified files or the index, review the new staged diff and revalidate the message before retrying. Do not retry a failure blindly.

After success, inspect the complete stored message with

git log -1 --format='%B'

. Verify that the title/body separator and body line breaks are real line breaks, not literal

\n

text. If the just-created message is malformed, amend it using actual line breaks and inspect it again. Then run

git log -1 --format='%h %s'

and

git status --short

. Report the commit hash and subject, then mention any remaining unstaged or untracked changes. Do not push unless the user separately requested it.

执行提交前，最后一次检查

git diff --cached

并验证:

所有已暂存变更都属于选定的范围。
提交信息能准确呈现已暂存变更的核心认知，无需逐文件检查或提及未暂存的工作。
已暂存差异仍通过上述安全审核。

仅包含主题的提交信息，运行:

bash

git commit -m "Subject line"

包含正文的提交信息，使用单独的

-m

参数，以便Git插入真实的空行。长正文使用真实换行；不要将其编码为字面意义的

\n

文本。

bash

git commit \
  -m "Deduplicate retries by request ID" \
  -m "Retries now treat request ID as the unit of identity. Attempts r1, r1,
r2 create two jobs instead of three."

如果提交失败，在采取进一步操作前检查错误信息和当前状态。如果钩子修改了文件或索引，在重试前重新检查新的已暂存差异并验证提交信息。不要盲目重试失败的操作。

提交成功后，使用

git log -1 --format='%B'

检查完整的存储信息。验证标题/正文分隔符和正文换行是否为真实换行，而非字面意义的

\n

文本。如果刚创建的信息格式有误，使用真实换行修正并再次检查。然后运行

git log -1 --format='%h %s'

和

git status --short

。报告提交哈希和主题，然后提及任何剩余的未暂存或未追踪变更。除非用户单独要求，否则不要推送提交。