commit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Commit

Git 提交

Overview

概述

Create atomic commits by staging the right files, analyzing the staged diff, composing a conventional commit message, and optionally pushing.

通过暂存正确的文件、分析暂存的差异、编写约定式提交信息，以及可选的推送操作，创建原子化提交。

Workflow

工作流程

0) Pre-flight checks

0) 预检检查

Verify inside a git worktree:
```
git rev-parse --is-inside-work-tree
```
Verify not detached:
```
git symbolic-ref HEAD
```
Verify not in rebase/merge/cherry-pick state: check for
```
.git/rebase-merge
```
,
```
.git/MERGE_HEAD
```
,
```
.git/CHERRY_PICK_HEAD
```
If any check fails, stop with a clear error and suggested fix.

验证是否处于Git工作树中：
```
git rev-parse --is-inside-work-tree
```
验证未处于分离HEAD状态：
```
git symbolic-ref HEAD
```
验证未处于变基/合并/拣选提交状态：检查是否存在
```
.git/rebase-merge
```
、
```
.git/MERGE_HEAD
```
、
```
.git/CHERRY_PICK_HEAD
```
文件
若任意检查失败，终止操作并返回清晰的错误信息及修复建议。

1) Collect context

1) 收集上下文信息

Current branch:
```
git branch --show-current
```
Git status:
```
git status --short --branch
```
Initial staged diff:
```
git diff --cached
```
Arguments:
```
$ARGUMENTS
```

Note: The staged diff may become stale after staging changes; re-read

git diff --cached

after STEP 2.

当前分支：
```
git branch --show-current
```
Git状态：
```
git status --short --branch
```
初始暂存差异：
```
git diff --cached
```
命令参数：
```
$ARGUMENTS
```

注意：在暂存变更后，已暂存的差异可能会失效；因此在步骤2完成后，需重新读取

git diff --cached

的内容。

2) Handle staging

2) 处理暂存操作

If
```
--all
```
:
- If no changes at all: error "No changes to commit"
- If unstaged changes exist:
```
git add -A
```
- If already staged: proceed
- Log staged files with status (A/M/D)
Otherwise (atomic commits):
- Session-modified files = files edited in this session
- Currently staged files:
```
git diff --cached --name-only
```
- For staged files NOT in session-modified set:
```
git restore --staged <file>
```
- For session-modified files with changes:
```
git add <file>
```
- Log staged files with status (A/M/D)
- If none: error "No files modified in this session"
Unrelated changes: session-modified files may contain pre-existing uncommitted changes (hunks not from this session). Include the entire file—partial staging is impractical. Never revert, discard, or
```
git checkout
```
unrelated changes.
Re-read staged diff:
```
git diff --cached
```

若使用
```
--all
```
参数：
- 若无任何变更：返回错误「无可提交的变更」
- 若存在未暂存的变更：执行
```
git add -A
```
- 若已完成暂存：继续后续流程
- 记录带有状态（A/M/D）的已暂存文件
其他情况（原子化提交）：
- 会话修改文件 = 本次会话中编辑的文件
- 当前已暂存文件：
```
git diff --cached --name-only
```
- 对于不在会话修改集合中的已暂存文件：执行
```
git restore --staged <file>
```
- 对于有变更的会话修改文件：执行
```
git add <file>
```
- 记录带有状态（A/M/D）的已暂存文件
- 若无符合条件的文件：返回错误「本次会话中无文件被修改」
无关变更：会话修改文件中可能包含预先存在的未提交变更（非本次会话产生的代码块）。需将整个文件纳入暂存——部分暂存操作不切实际。切勿回滚、丢弃或使用
```
git checkout
```
处理无关变更。
重新读取已暂存差异：
```
git diff --cached
```

3) Parse arguments

3) 解析参数

Flags:
- ```
--all
```
  commit all changes
- ```
--deep
```
  deep analysis, breaking changes, concise body
- ```
--push
```
  push after commit
Value arguments:
- Type keyword (any conventional type) overrides inferred type
- Quoted text overrides inferred description
Precedence:
1. Explicit type keyword in arguments
2. Heuristic inference from diff
3. Quoted text in arguments
4. Heuristic inference from diff

标志：
- ```
--all
```
  ：提交所有变更
- ```
--deep
```
  ：深度分析、检测破坏性变更、生成简洁的提交正文
- ```
--push
```
  ：提交后执行推送
值参数：
- 约定式提交类型关键字（任意合法类型）将覆盖自动推断的类型
- 带引号的文本将覆盖自动推断的描述信息
优先级：
1. 参数中显式指定的类型关键字
2. 基于差异的启发式推断结果
3. 参数中带引号的文本
4. 基于差异的启发式推断结果

4) Analyze changes

4) 分析变更

Default:
- Read the staged diff
- Ignore unrelated hunks (pre-existing changes not from this session) when determining type, scope, and description. If unrelated changes are in the same file as session changes, they are included in the commit scope but should not influence the commit message.
- Determine change type from behavior:
  - New functionality ->
```
feat
```
  - Bug fix or error handling ->
```
fix
```
  - Code reorganization without behavior change ->
```
refactor
```
  - Documentation changes ->
```
docs
```
  - Test additions/changes ->
```
test
```
  - Build system (webpack, vite, esbuild configs) ->
```
build
```
  - CI/CD pipelines (.github/workflows, .gitlab-ci) ->
```
ci
```
  - Dependencies ->
```
chore(deps)
```
  - Formatting/whitespace only ->
```
style
```
  - Performance improvements ->
```
perf
```
  - Reverting previous commit ->
```
revert
```
  - Other maintenance ->
```
chore
```
  - AI config (CLAUDE.md, AGENTS.md, .claude/, .gemini/, .codex/) ->
```
ai
```
- Infer scope only when path makes it obvious (lowercase)
- Extract a specific description of what changed (not just which files)
If
```
--deep
```
:
- Deep semantic analysis; detect breaking changes
- Infer scope from code structure even when path isn't clear
- Check for GitHub issues in the chat transcript
- Keep output concise

Conventional types: feat, fix, docs, style, refactor, test, chore, build, ci, perf, revert, ai

默认模式：
- 读取已暂存的差异内容
- 在确定提交类型、范围和描述时，忽略无关代码块（非本次会话产生的预先存在的变更）。若无关变更与会话变更位于同一文件中，需将其纳入提交范围，但不应影响提交信息的生成。
- 根据变更行为确定提交类型：
  - 新增功能 ->
```
feat
```
  - 修复Bug或错误处理 ->
```
fix
```
  - 代码重构（无行为变更） ->
```
refactor
```
  - 文档变更 ->
```
docs
```
  - 测试用例新增/修改 ->
```
test
```
  - 构建系统配置（webpack、vite、esbuild等） ->
```
build
```
  - CI/CD流水线配置（.github/workflows、.gitlab-ci等） ->
```
ci
```
  - 依赖项更新 ->
```
chore(deps)
```
  - 仅格式/空白字符变更 ->
```
style
```
  - 性能优化 ->
```
perf
```
  - 回滚之前的提交 ->
```
revert
```
  - 其他维护操作 ->
```
chore
```
  - AI配置文件（CLAUDE.md、AGENTS.md、.claude/、.gemini/、.codex/等） ->
```
ai
```
- 仅当文件路径明确时，推断提交范围（小写）
- 提取变更的具体描述（而非仅说明哪些文件被修改）
若启用
```
--deep
```
模式：
- 深度语义分析；检测破坏性变更
- 即使路径不明确，也从代码结构推断提交范围
- 检查聊天记录中的GitHub议题
- 保持输出简洁

约定式提交类型：feat, fix, docs, style, refactor, test, chore, build, ci, perf, revert, ai

5) Compose message

5) 编写提交信息

Subject line (<= 50 chars):

type(scope): description

type: description

Imperative mood ("add" not "added"), lowercase, no period
Describe what the change does, not which files changed
Default mode:
- Subject line required
- Body: hyphenated lines for distinct changes
- Skip body for trivial changes
If
```
--deep
```
:
- Body: 2-3 hyphenated lines max, focus on WHY
- Breaking change:
```
BREAKING CHANGE:
```
  + one-line migration note
- GitHub issues:
```
Closes #123
```

主题行（≤50字符）：

type(scope): description

或

type: description

使用祈使语气（如「add」而非「added」），小写，结尾无句号
描述变更的作用，而非仅说明哪些文件被修改
默认模式：
- 必须包含主题行
- 正文：使用连字符开头的行列出不同的变更点
- 微小变更可省略正文
若启用
```
--deep
```
模式：
- 正文：最多2-3个连字符开头的行，聚焦于「为什么做此变更」
- 破坏性变更：需包含
```
BREAKING CHANGE:
```
  + 单行迁移说明
- GitHub议题：需包含
```
Closes #123
```

6) Commit

6) 执行提交

Use
```
git commit -m "subject"
```
(add
```
-m "body"
```
only if body is non-empty)
Output: commit hash + subject + file count summary
If failed: show error + suggest fix

使用
```
git commit -m "subject"
```
（仅当正文非空时添加
```
-m "body"
```
）
输出内容：提交哈希值 + 主题行 + 文件数量汇总
若提交失败：显示错误信息 + 修复建议

7) Push (if

--push

)

7) 推送（若使用

--push

参数）

If upstream exists:
```
git push
```
If no upstream:
```
git push -u origin HEAD
```
If failed: show error + suggest fix (pull/rebase first, set upstream, check auth)

若已设置上游分支：执行
```
git push
```
若未设置上游分支：执行
```
git push -u origin HEAD
```
若推送失败：显示错误信息 + 修复建议（先拉取/变基、设置上游分支、检查权限等）

Examples

示例

Trivial changes (subject only):

fix: correct typo in error message
style: format config file
chore(deps): bump lodash to 4.17.21

Default (subject + brief body):

feat(auth): add oauth2 login support

- Add Google and GitHub OAuth providers
- Integrate alongside existing password auth

Deep mode (concise, focused on WHY):

feat(webhooks): add retry mechanism for failed deliveries

- Prevent data loss when downstream services are temporarily unavailable

微小变更（仅主题行）：

fix: correct typo in error message
style: format config file
chore(deps): bump lodash to 4.17.21

默认模式（主题行 + 简短正文）：

feat(auth): add oauth2 login support

- Add Google and GitHub OAuth providers
- Integrate alongside existing password auth

深度模式（简洁，聚焦于变更原因）：

feat(webhooks): add retry mechanism for failed deliveries

- Prevent data loss when downstream services are temporarily unavailable

commit

Original

Translation

Git Commit

Git 提交

Overview

概述

Workflow

工作流程

0) Pre-flight checks

0) 预检检查

1) Collect context

1) 收集上下文信息

2) Handle staging

2) 处理暂存操作

3) Parse arguments

3) 解析参数

4) Analyze changes

4) 分析变更

5) Compose message

5) 编写提交信息

6) Commit

6) 执行提交

7) Push (if
`--push`
)

7) 推送（若使用
`--push`
参数）

Examples

示例

commit

Original

Translation

Git Commit

Git 提交

Overview

概述

Workflow

工作流程

0) Pre-flight checks

0) 预检检查

1) Collect context

1) 收集上下文信息

2) Handle staging

2) 处理暂存操作

3) Parse arguments

3) 解析参数

4) Analyze changes

4) 分析变更

5) Compose message

5) 编写提交信息

6) Commit

6) 执行提交

7) Push (if --push)

7) 推送（若使用--push参数）

Examples

示例

7) Push (if
`--push`
)

7) 推送（若使用
`--push`
参数）