Back to Details

commit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Commit

提交

Analyze uncommitted changes and create well-organized commits using conventional commit format.
分析未提交的变更，并使用规范式提交（conventional commit）格式创建结构清晰的提交。

Workflow

工作流程

1. Discover Changes

1. 发现变更

Current repo state (injected at invocation — no tool calls needed):
  • Status: !
    git status --porcelain
  • Diff stats: !
    git diff --stat
Abort before staging if any apply:
  • Not a git repository.
  • No changes ("Nothing to commit").
  • Mid-merge / rebase / cherry-pick / revert — 
    git add -A
    would stage conflict markers as content. Check 
    $(git rev-parse --git-dir)
    for 
    MERGE_HEAD
    , 
    CHERRY_PICK_HEAD
    , 
    REVERT_HEAD
    , 
    rebase-merge/
    , or 
    rebase-apply/
    . If any present, report the in-progress operation and stop.
  • Detached HEAD — 
    git symbolic-ref -q HEAD
    is empty. Commit would land on an unreferenced commit and be lost on branch switch. Report and stop.
当前仓库状态（调用时注入——无需工具调用）：
  • 状态：!
    git status --porcelain
  • 差异统计：!
    git diff --stat
如果出现以下任一情况，在暂存前终止操作：
  • 不是Git仓库。
  • 无变更（"Nothing to commit"）。
  • 处于合并/变基/拣选/回退过程中——
    git add -A
    会将冲突标记作为内容暂存。检查
    $(git rev-parse --git-dir)
    是否存在
    MERGE_HEAD
    、
    CHERRY_PICK_HEAD
    、
    REVERT_HEAD
    、
    rebase-merge/
    或
    rebase-apply/
    。如果存在任何一项，报告正在进行的操作并停止。
  • 处于分离HEAD状态——
    git symbolic-ref -q HEAD
    为空。提交会落在未被引用的提交上，切换分支时会丢失。报告此情况并停止。

2. Stage Files

2. 暂存文件

Run 
git add -A
to stage all changes.
Exclude generated or ephemeral files that should never be version-controlled: 
scratch.*
, 
temp.*
, 
debug.*
, 
playground.*
, 
*.log
, 
dist/
, 
build/
, 
target/
, 
node_modules/
, 
__pycache__/
.
If such files detected:
  1. Unstage with 
    git reset HEAD <file>
  2. Ask user if they want to add to .gitignore
Proceed when all intended files are staged and ephemeral files are excluded.
执行
git add -A
暂存所有变更。
排除不应被版本控制的生成文件或临时文件：
scratch.*
、
temp.*
、
debug.*
、
playground.*
、
*.log
、
dist/
、
build/
、
target/
、
node_modules/
、
__pycache__/
。
如果检测到此类文件：
  1. 使用
    git reset HEAD <file>
    取消暂存
  2. 询问用户是否要将其添加到.gitignore中
当所有目标文件已暂存且临时文件已排除后，继续操作。

3. Analyze Commit Boundaries

3. 分析提交边界

For each changed file, write a one-line PURPOSE description (not file location).
Group by PURPOSE, not directory:
  • Same goal = one commit
  • Different goals = separate commits
Each commit should represent one logical change because atomic commits enable 
git bisect
and 
git revert
without side-effects.
Signs of separate concerns:
  • "Added X" AND "Fixed Y" (feature + bugfix)
  • Changes that could be reverted independently
  • Different conventional-commit types on related work — a fix and its tests go in separate 
    fix:
    and 
    test:
    commits so the fix can be reverted without losing the tests
If multiple concerns: use 
git reset HEAD
then 
git add <specific-files>
for each group. Commit foundational changes first.
Handle renames (R status): When splitting, add BOTH old and new paths. Git detects renames by similarity scoring across the old/new pair — staging only the new path causes git to log a delete + add, losing rename history.
Proceed when every changed file is assigned to exactly one commit group.
对每个变更文件，编写一行用途描述（而非文件位置）。
按用途分组，而非按目录分组：
  • 同一目标 = 一次提交
  • 不同目标 = 分开提交
每次提交应代表一个逻辑变更，因为原子提交支持
git bisect
和
git revert
且无副作用。
需分开处理的迹象：
  • "添加了X"且"修复了Y"（功能+ bug修复）
  • 可独立回退的变更
  • 相关工作使用不同的规范式提交类型——修复代码与其测试应分别放在
    fix:
    和
    test:
    提交中，以便回退修复时不会丢失测试
如果存在多个关注点：使用
git reset HEAD
，然后对每组文件执行
git add <specific-files>
。优先提交基础变更。
处理重命名（R状态）：拆分提交时，同时添加旧路径和新路径。Git通过新旧文件对的相似度评分检测重命名——仅暂存新路径会导致Git记录为删除+添加，丢失重命名历史。
当每个变更文件都被分配到恰好一个提交组后，继续操作。

4. Validate

4. 验证

Run the validation script after staging:
bash
python3 ${CLAUDE_PLUGIN_ROOT}/skills/commit/scripts/validate.py . --output json
Interpret the result:
  • Exit 0 → validation passed; proceed to Step 5
  • Exit 1 → validation failed; parse the 
    output
    field, report the error to the user, and stop
  • Exit 2 → validator skipped (no marker file, no staged files match the validator's extensions, or the tool isn't installed); proceed to Step 5. The 
    output
    field names the reason.
暂存后执行验证脚本：
bash
python3 ${CLAUDE_PLUGIN_ROOT}/skills/commit/scripts/validate.py . --output json
解读结果：
  • 退出码0 → 验证通过；进入步骤5
  • 退出码1 → 验证失败；解析
    output
    字段，向用户报告错误并停止
  • 退出码2 → 验证器跳过（无标记文件、无暂存文件匹配验证器的扩展名，或工具未安装）；进入步骤5。
    output
    字段会说明原因。

5. Create Commit

5. 创建提交

Check recent commit style:
bash
git log --no-merges --oneline -10
Use conventional commit format:
<type>(<scope>): <description>
Types: feat, fix, docs, refactor, test, chore, perf
  • Lowercase subject, no period, imperative mood
  • Max 72 chars for subject
  • Omit Co-authored-by trailers and AI attribution — these pollute 
    git log
    and break downstream tooling that greps commit metadata
  • No emojis
If 
git commit
fails due to a pre-commit hook: the commit did NOT land. Check 
git status
— the hook may have auto-fixed files (e.g. 
auto-version.py
syncing 
plugin.json
) and left them modified. Re-stage (
git add -A
) and retry the same 
git commit
command with the same message. Do NOT use 
--amend
(amends the PREVIOUS commit, not the failed one). Do NOT use 
--no-verify
(skips the hook entirely, defeating its guard).
Proceed when the commit message is drafted and matches the repo's existing style.
查看近期提交风格：
bash
git log --no-merges --oneline -10
使用规范式提交格式：
<type>(<scope>): <description>
类型：feat、fix、docs、refactor、test、chore、perf
  • 主题使用小写，无句号，采用祈使语气
  • 主题最大72字符
  • 省略Co-authored-by尾部信息和AI归因——这些会污染
    git log
    并破坏依赖提交元数据的下游工具
  • 不使用表情符号
如果
git commit
因预提交钩子失败：提交未成功完成。检查
git status
——钩子可能自动修复了文件（例如
auto-version.py
同步
plugin.json
）并留下未暂存的修改。重新暂存（
git add -A
）并使用相同的提交信息重试
git commit
命令。不要使用
--amend
（会修改上一次提交，而非失败的提交）。不要使用
--no-verify
（会完全跳过钩子，失去其防护作用）。
当提交信息已草拟并匹配仓库现有风格后，继续操作。

6. Push (only if requested)

6. 推送（仅在请求时执行）

If user mentions "push" or arguments contain "push", run 
git push
. If push fails, report the error and stop — do not retry or force-push.
如果用户提及“push”或参数包含“push”，执行
git push
。如果推送失败，报告错误并停止——不要重试或强制推送。

Output

输出

One line per commit (hash + message). If temporary files were excluded, list them as bullets below.
每个提交一行（哈希值 + 提交信息）。如果排除了临时文件，在下方以项目符号列表列出这些文件。