but

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitButler CLI Skill

Use GitButler CLI (

but

) as the default version-control interface.

将GitButler CLI（

but

）作为默认的版本控制界面。

Non-Negotiable Rules

不可违反的规则

Use

but

for all write operations. Never run

git add

git commit

git push

git checkout

git merge

git rebase

git stash

, or

git cherry-pick

Start every write/history-edit task with
```
but status --json
```
.
For mutation commands, always add
```
--json --status-after
```
.
Use CLI IDs from
```
but status --json
```
/
```
but diff --json
```
/
```
but show --json
```
; do not hardcode IDs and do not switch branches with
```
git checkout
```
.
After a successful mutation with
```
--status-after
```
, do not run a redundant
```
but status
```
unless needed for new IDs.
If the user says a
```
git
```
write command (for example "git push"), translate it to the
```
but
```
equivalent and execute the
```
but
```
command directly.
For branch-update tasks, run
```
but pull --check --json
```
before
```
but pull --json --status-after
```
. Do not substitute
```
but fetch
```
+ status summaries for this check.
Avoid routine
```
--help
```
probes before mutations. Use the command patterns in this skill (and
```
references/reference.md
```
) first; only use
```
--help
```
when syntax is genuinely unclear or after a failed attempt.

所有写入操作均使用

but

命令。禁止运行

git add

、

git commit

、

git push

、

git checkout

、

git merge

、

git rebase

、

git stash

或

git cherry-pick

命令。

所有写入/编辑历史的任务均以
```
but status --json
```
开头。
执行变更类命令时，务必添加
```
--json --status-after
```
参数。
使用
```
but status --json
```
/
```
but diff --json
```
/
```
but show --json
```
返回的CLI ID；请勿硬编码ID，也不要使用
```
git checkout
```
切换分支。
使用
```
--status-after
```
参数成功执行变更操作后，除非需要获取新ID，否则请勿重复运行
```
but status
```
。
如果用户提及某个Git写入命令（例如"git push"），将其转换为对应的
```
but
```
命令并直接执行。
执行分支更新任务时，先运行
```
but pull --check --json
```
，再运行
```
but pull --json --status-after
```
。请勿用
```
but fetch
```
+ 状态摘要替代此检查步骤。
执行变更操作前，避免常规性地使用
```
--help
```
查询。优先使用本技能中的命令模式（及
```
references/reference.md
```
）；仅当语法确实不明确或尝试失败后，才使用
```
--help
```
。

Core Flow

核心流程

bash

but status --json

bash

but status --json

If new branch needed:

如果需要创建新分支：

but branch new <name>

Perform task with IDs from status/diff/show

使用status/diff/show返回的ID执行任务

but <mutation> ... --json --status-after

undefined

but <mutation> ... --json --status-after

undefined

Canonical Command Patterns

标准命令范式

Commit specific files/hunks:

but commit <branch> -m "<message>" --changes <id>,<id> --json --status-after

Create branch while committing:

but commit <branch> -c -m "<message>" --changes <id> --json --status-after

Amend into a known commit:

but amend <file-id> <commit-id> --json --status-after

Reorder commits:

but move <source-commit-id> <target-commit-id> --json --status-after

Push:
```
but push
```
or
```
but push <branch-id>
```

Pull update safety flow:

but pull --check --json

then

but pull --json --status-after

提交特定文件/代码块：

but commit <branch> -m "<message>" --changes <id>,<id> --json --status-after

提交时创建分支：

but commit <branch> -c -m "<message>" --changes <id> --json --status-after

修改已有提交：

but amend <file-id> <commit-id> --json --status-after

调整提交顺序：

but move <source-commit-id> <target-commit-id> --json --status-after

推送：
```
but push
```
或
```
but push <branch-id>
```

拉取更新的安全流程：

but pull --check --json

然后

but pull --json --status-after

Task Recipes

任务操作指南

Commit one file

提交单个文件

```
but status --json
```
Find that file's
```
cliId
```

but commit <branch> -c -m "<clear message>" --changes <file-id> --json --status-after

```
but status --json
```
找到该文件的
```
cliId
```

but commit <branch> -c -m "<清晰的提交信息>" --changes <file-id> --json --status-after

Commit only A, not B

仅提交A，不提交B

```
but status --json
```
Find
```
src/a.rs
```
ID and
```
src/b.rs
```
ID
Commit with
```
--changes <a-id>
```
only

```
but status --json
```
找到
```
src/a.rs
```
的ID和
```
src/b.rs
```
的ID
仅使用
```
--changes <a-id>
```
参数执行提交

User says "git push"

用户说“git push”

Interpret as GitButler push. Run

but push

(or

but push <branch-id>

) immediately. Do not run

git push

, even if

but push

reports nothing to push.

将其理解为GitButler的推送命令。直接运行

but push

（或

but push <branch-id>

）。即使

but push

提示没有内容可推送，也不要运行

git push

。

Check mergeability, then update branches

检查合并可行性，然后更新分支

Run exactly:
```
but pull --check --json
```
If user asked to proceed, run:
```
but pull --json --status-after
```
Do not replace step 1 with
```
but fetch
```
,
```
but status
```
, or a narrative-only summary.

严格运行：
```
but pull --check --json
```
如果用户确认继续，运行：
```
but pull --json --status-after
```
请勿用
```
but fetch
```
、
```
but status
```
或仅文字摘要替代步骤1。

Amend into existing commit

修改已有提交

```
but status --json
```
Locate file ID and commit ID from
```
status
```
(or
```
but show <branch-id> --json
```
)

Run exactly:

but amend <file-id> <commit-id> --json --status-after

Never use
```
git checkout
```
or
```
git commit --amend
```

```
but status --json
```
从
```
status
```
（或
```
but show <branch-id> --json
```
）中找到文件ID和提交ID

严格运行：

but amend <file-id> <commit-id> --json --status-after

绝对不要使用
```
git checkout
```
或
```
git commit --amend
```

Reorder commits

调整提交顺序

```
but status --json
```
Identify source/target commit IDs in the branch by commit message

Run:

but move <commit-a> <commit-b> --json --status-after

From the returned
```
status
```
, refresh IDs and then run the inverse move:
```
but move <commit-b> <commit-a> --json --status-after
```
This two-step sequence is the safe default for reorder requests.
Never use
```
git rebase
```
for this.

```
but status --json
```
根据提交信息在分支中识别源提交ID和目标提交ID

运行：

but move <commit-a> <commit-b> --json --status-after

从返回的
```
status
```
中刷新ID，然后运行反向调整命令：
```
but move <commit-b> <commit-a> --json --status-after
```
这种两步操作是调整提交顺序的安全默认方式。
绝对不要使用
```
git rebase
```
完成此操作。

Git-to-But Map

Git与But命令映射表

```
git status
```
->
```
but status --json
```

git add

git commit

but commit ... --changes ... --json --status-after

```
git checkout -b
```
->
```
but branch new <name>
```
```
git push
```
->
```
but push
```

git rebase -i

but move

but squash

but reword

```
git cherry-pick
```
->
```
but pick
```

```
git status
```
->
```
but status --json
```

git add

git commit

but commit ... --changes ... --json --status-after

```
git checkout -b
```
->
```
but branch new <name>
```
```
git push
```
->
```
but push
```

git rebase -i

but move

but squash

but reword

```
git cherry-pick
```
->
```
but pick
```

Notes

注意事项

Prefer explicit IDs over file paths for mutations.
```
--changes
```
is the safe default for precise commits.
```
--changes
```
accepts one argument per flag. For multiple IDs, use comma-separated values (
```
--changes a1,b2
```
) or repeat the flag (
```
--changes a1 --changes b2
```
), not
```
--changes a1 b2
```
.
Read-only git inspection is allowed (
```
git log
```
,
```
git blame
```
) when needed.
Keep skill version checks low-noise:
- Do not run
```
but skill check
```
  as a routine preflight on every task.
- Run
```
but skill check
```
  when command behavior appears to diverge from this skill (for example: unexpected unknown-flag errors, missing subcommands, or output shape mismatches), or when the user asks.
- If update is available, recommend
```
but skill check --update
```
  (or run it if the user asked to update).
For deeper command syntax and flags, use
```
references/reference.md
```
.
For workspace model and dependency behavior, use
```
references/concepts.md
```
.
For end-to-end workflow patterns, use
```
references/examples.md
```
.

执行变更操作时，优先使用明确的ID而非文件路径。
```
--changes
```
是精准提交的安全默认参数。
```
--changes
```
每个参数仅接受一个值。若要传入多个ID，可使用逗号分隔（
```
--changes a1,b2
```
）或重复该参数（
```
--changes a1 --changes b2
```
），请勿使用
```
--changes a1 b2
```
格式。
必要时可使用只读的Git检查命令（
```
git log
```
、
```
git blame
```
）。
降低技能版本检查的干扰：
- 不要在每个任务开始时例行运行
```
but skill check
```
  。
- 当命令行为与本技能描述不符时（例如：出现意外的未知参数错误、缺少子命令或输出格式不匹配），或用户要求时，才运行
```
but skill check
```
  。
- 如果有可用更新，建议运行
```
but skill check --update
```
  （或在用户要求时直接运行）。
如需了解更详细的命令语法和参数，请参阅
```
references/reference.md
```
。
如需了解工作区模型和依赖行为，请参阅
```
references/concepts.md
```
。
如需了解端到端工作流模式，请参阅
```
references/examples.md
```
。