commit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

commit

Turn whatever is uncommitted in the working tree into logical, atomic Conventional Commits — but only the files that belong to this branch. The non-obvious value is the out-of-scope guard: multi-worktree and multi-agent setups can leave stray files in the working tree that belong to another branch, and this skill never sweeps them into a commit.

This skill is the single source of truth for the commit-grouping contract. It is invoked two ways:

Standalone (
```
/commit
```
) — "commit my WIP nicely." It creates the commits on the current branch and stops. It never pushes, opens a PR, writes a changelog, or touches Linear.
Inside a ship flow (e.g.
```
/send-it
```
) — the commit step that runs before the lint gate, so the branch is clean before the changelog/PR work begins. The ship flow owns everything after the commits (lint, changelog, push, PR, Linear); this skill owns only the staging decision and the commits.

将工作区中所有未提交内容转换为符合逻辑的原子化Conventional Commits——但仅包含属于当前分支的文件。其独特价值在于范围外防护：多工作区和多Agent环境可能会在工作区中留下属于其他分支的零散文件，而本技能绝不会将这些文件纳入提交。

本技能是提交分组规则的唯一权威来源。有两种调用方式：

独立调用（
```
/commit
```
）——“帮我规范提交WIP内容”。它会在当前分支创建提交后停止，绝不执行推送、创建PR、生成变更日志或操作Linear。
在发布流程中调用（例如
```
/send-it
```
）——作为代码检查环节之前的提交步骤，确保在开始生成变更日志/创建PR前分支处于干净状态。发布流程负责提交后的所有操作（代码检查、变更日志、推送、PR、Linear）；本技能仅负责暂存决策和提交操作。

Configuration

配置

One knob lives in

config.json

beside this skill (a neutral

config.example.json

ships as a template):

Key	Meaning	Default
`baseBranch`	The trunk the branch diff is taken against ( `origin/<baseBranch>` ), used to compute the merge base for scope classification.	`"main"`

Throughout this document

<base>

is the

baseBranch

value.

When a ship flow delegates to this skill (e.g.

/send-it

), it may direct the classification against a different base for that run — for instance send-it's

--base

for a stacked PR. Honour the base the caller resolves; fall back to

config.json

baseBranch

only for a standalone

/commit

run.

本技能旁的

config.json

中有一个配置项（附带一个中立的

config.example.json

作为模板）：

键名	含义	默认值
`baseBranch`	分支差异对比的主干分支（ `origin/<baseBranch>` ），用于计算范围分类的合并基准。	`"main"`

本文档中所有

<base>

均指代

baseBranch

的值。

当发布流程委托本技能执行时（例如

/send-it

），可能会指定本次运行使用不同的基准——例如send-it的

--base

参数用于堆叠PR场景。优先遵循调用方指定的基准；仅在独立调用

/commit

时回退使用

config.json

中的

baseBranch

。

Process

流程

```
git status --porcelain
```
. If clean, there is nothing to commit — say so and stop.
Inspect the uncommitted files:
```
git status --porcelain
```
for the list,
```
git diff
```
and
```
git diff --cached
```
for the hunks.
Filter for branch relevance. Decide which uncommitted files are in scope:
- Compute the merge base:
```
git merge-base HEAD origin/<base>
```
  .
- Files the branch has already touched directly:
```
git diff --name-only <merge-base>...HEAD
```
  .
- In scope by default: an uncommitted file whose path is in that branch-touched list.
- Out of scope (uncertain): everything else once the branch has its own commits. This deliberately includes a file that merely sits in a directory the branch has touched but is not itself a path the branch changed — a shared directory is not enough to claim a file. A stray file from another branch or worktree can easily land in a directory this branch happens to have edited, and silently sweeping it in is exactly the out-of-scope leak this guard exists to prevent. Treat directory-only matches as out of scope unless the user explicitly confirms them.
- Fresh branch (no commits of its own yet): there is no branch-touched list to diff against, so nothing distinguishes your own work from a stray file left by another branch or worktree. Do not auto-promote every uncommitted file to in scope — that is exactly the leak this guard exists to catch. Treat all uncommitted files as uncertain and have the user confirm which belong before staging any of them.
Show the user the staging plan: in-scope files grouped by proposed commit, plus an explicit list of out-of-scope / uncertain files flagged as "uncertain — possibly from another branch/worktree." Ask: "Stage in-scope files and create the commits below? (yes / no / customise)". Uncertain files are never staged automatically. On a fresh branch the uncertain list is every uncommitted file (step 3): ask the user to confirm which belong, and treat only the confirmed files as in scope.
Group in-scope files into logical atomic commits:
- One commit per coherent unit (a feature, a bug fix, a refactor, a docs change, a tooling tweak). Don't bundle unrelated edits.
- Use Conventional Commits subjects (
```
feat:
```
  ,
```
fix:
```
  ,
```
chore:
```
  ,
```
docs:
```
  ,
```
refactor:
```
  ,
```
perf:
```
  ,
```
test:
```
  ), with a scope when one is obvious (
```
feat(commit): …
```
  ).
- For a breaking change, mark it honestly: a
```
!
```
  after the type/scope (
```
feat(api)!: …
```
  ) and/or a
```
BREAKING CHANGE:
```
  footer in the body. A ship flow reads the bump signal back out of these commit messages, so the markers must be accurate.
On confirmation, create the commits with
```
git add <specific files>
```
(never
```
git add -A
```
) and
```
git commit
```
. Stage only the files named in the plan; out-of-scope files stay in the working tree, untouched. Pass one
```
-m
```
per block to add a body or footer beyond the subject —
```
git commit -m "<subject>" -m "<body>"
```
, and for a breaking change
```
git commit -m "feat(api)!: <subject>" -m "BREAKING CHANGE: <what changed and the migration>"
```
(or
```
git commit -F <message-file>
```
for a longer body). A bare
```
git commit -m "<subject>"
```
is fine when no body is needed.

If a pre-commit hook reformats files, the commit still succeeds with the formatted content.

执行
```
git status --porcelain
```
。如果工作区干净，则无内容可提交——告知用户并停止操作。
检查未提交文件：通过
```
git status --porcelain
```
获取文件列表，通过
```
git diff
```
和
```
git diff --cached
```
查看代码块。
筛选分支相关文件。判断哪些未提交文件属于范围内：
- 计算合并基准：
```
git merge-base HEAD origin/<base>
```
  。
- 分支已直接修改的文件：
```
git diff --name-only <merge-base>...HEAD
```
  。
- 默认范围内：路径在上述分支修改列表中的未提交文件。
- 范围外（不确定）：分支已有自身提交后的所有其他文件。这故意包含那些仅位于分支修改过的目录中但自身未被分支修改的文件——共享目录不足以将文件归为当前分支。其他分支或工作区的零散文件很容易出现在当前分支恰好编辑过的目录中，而静默暂存这些文件正是本防护机制要阻止的范围外泄漏。除非用户明确确认，否则仅匹配目录的文件视为范围外。
- 新分支（尚未有自身提交）：没有分支修改列表可对比，因此无法区分你的工作内容与其他分支/工作区留下的零散文件。不要自动将所有未提交文件归为范围内——这正是本防护机制要避免的泄漏。将所有未提交文件视为不确定，让用户确认哪些属于当前分支后再暂存。
向用户展示暂存计划：按提议的提交分组展示范围内文件，同时明确列出范围外/不确定文件并标记为“不确定——可能来自其他分支/工作区”。询问：“是否暂存范围内文件并创建以下提交？（是/否/自定义）”。不确定文件绝不会被自动暂存。在新分支场景下，不确定列表包含所有未提交文件（步骤3）：请用户确认哪些属于当前分支，仅将确认后的文件视为范围内。
将范围内文件分组为符合逻辑的原子提交：
- 每个连贯单元对应一个提交（功能新增、Bug修复、重构、文档变更、工具调整）。不要捆绑无关编辑内容。
- 使用Conventional Commits主题（
```
feat:
```
  、
```
fix:
```
  、
```
chore:
```
  、
```
docs:
```
  、
```
refactor:
```
  、
```
perf:
```
  、
```
test:
```
  ），如有明确范围则添加范围（
```
feat(commit): …
```
  ）。
- 对于破坏性变更，如实标记：在类型/范围后添加
```
!
```
  （
```
feat(api)!: …
```
  ）和/或在正文中添加
```
BREAKING CHANGE:
```
  页脚。发布流程会从这些提交信息中读取版本升级信号，因此标记必须准确。
确认后，使用
```
git add <specific files>
```
（绝不使用
```
git add -A
```
）和
```
git commit
```
创建提交。仅暂存计划中指定的文件；范围外文件保留在工作区，不做修改。如果需要主题之外的正文或页脚，传递多个
```
-m
```
参数——
```
git commit -m "<subject>" -m "<body>"
```
，对于破坏性变更使用
```
git commit -m "feat(api)!: <subject>" -m "BREAKING CHANGE: <变更内容与迁移说明>"
```
（或对于较长正文使用
```
git commit -F <message-file>
```
）。如果无需正文，仅使用
```
git commit -m "<subject>"
```
即可。

如果预提交钩子重新格式化文件，提交仍会以格式化后的内容成功完成。

Commit-message prose

提交信息文案

Author commit subjects and bodies in the consuming repo's documented prose language. Across this estate that is British English (

colour

behaviour

-ise

-yse

). This governs prose only — never identifiers, dependency names, or upstream API field names.

提交主题和正文使用目标仓库文档指定的语言。本环境统一使用英式英文（

colour

、

behaviour

、

-ise

-yse

）。此规则仅适用于文案——绝不影响标识符、依赖名称或上游API字段名。

Grouping granularity — per-component splitting is parked

分组粒度——按组件拆分暂不处理

/commit

groups by intent (one commit per coherent change), not by component or package boundaries. Per-component atomic-commit splitting (attributing files to a package and cutting a commit per package) stays parked (A-374) — no estate repo does per-component path attribution today. Revisit only if a published multi-package monorepo doing per-component versioning off squash enters the estate.

/commit

按意图分组（每个连贯变更对应一个提交），而非按组件或包边界拆分。按组件拆分原子提交（将文件归到对应包并按包创建提交）暂不处理（A-374）——目前本环境没有仓库按组件路径归属处理。仅当发布的多包单仓库采用按组件版本化的 squash 合并方式进入本环境时，才重新考虑此功能。

Arguments

参数

$ARGUMENTS