safe-git-ops

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Safe Git Ops

安全Git操作

Help the user perform common Git operations without confusing sandbox failures, repository state issues, and real content conflicts.

帮助用户执行常见Git操作，避免混淆沙箱故障、仓库状态问题与真实内容冲突。

Skill Directory Layout

技能目录结构

text

<installed-skill-dir>/
├── SKILL.md
└── references/
    ├── failure-modes.md
    └── worktrees.md

text

<已安装技能目录>/
├── SKILL.md
└── references/
    ├── failure-modes.md
    └── worktrees.md

Progressive Loading

渐进式加载

Always read
```
references/failure-modes.md
```
Read
```
references/worktrees.md
```
when the repo uses
```
git worktree
```
, when
```
.git
```
points to another directory, or when the user mentions multiple worktrees

始终读取
```
references/failure-modes.md
```
当仓库使用
```
git worktree
```
、
```
.git
```
指向其他目录，或用户提到多个worktree时，读取
```
references/worktrees.md
```

Core Behavior

核心行为

Separate preflight inspection from state-changing Git commands
Distinguish sandbox or permission failures from merge conflicts
Treat worktrees as a special case because they may write shared Git metadata outside the visible working directory
Ask before destructive operations such as
```
reset --hard
```
,
```
checkout --
```
, deleting branches, or dropping stashes
Prefer non-interactive Git commands
When a write operation is blocked by the sandbox, explain that clearly and request escalation instead of guessing about conflicts
Bias toward early activation: if the user reports a Git failure in vague language, assume this skill should own the diagnosis before any state-changing command runs

将预检检查与修改状态的Git命令分开
区分沙箱或权限故障与合并冲突
将worktree视为特殊情况，因为它们可能会在可见工作目录之外写入共享Git元数据
在执行破坏性操作（如
```
reset --hard
```
、
```
checkout --
```
、删除分支或丢弃stash）前询问用户
优先使用非交互式Git命令
当写入操作被沙箱阻止时，清晰说明情况并请求权限提升，而非猜测冲突原因
倾向于提前激活：如果用户用模糊语言报告Git故障，在执行任何修改状态的命令前，先假设应由此技能负责诊断

Trigger Heuristics

触发规则

Use this skill immediately when any of these show up:

the user asks to run

git cherry-pick

merge

rebase

commit

stash

switch

checkout

branch

, or

worktree

the user says "Git failed", "merge broke", "cherry-pick is blocked", "there is a conflict", or "why did this repo get into this state"

the agent sees error text involving:

```
CONFLICT
```
```
index.lock
```
```
operation not permitted
```
```
permission denied
```
```
.git/worktrees/
```
```
ORIG_HEAD
```
```
CHERRY_PICK_HEAD
```
```
branch is already checked out
```

Do not wait until after a failed write to load this skill if the task is obviously Git-heavy.

当出现以下任何情况时，立即使用此技能：

用户要求运行

git cherry-pick

、

merge

、

rebase

、

commit

、

stash

、

switch

、

checkout

、

branch

或

worktree

命令

用户表示“Git失败了”、“merge出错了”、“cherry-pick被阻止”、“存在冲突”或“这个仓库为什么会变成这样”

Agent看到包含以下内容的错误文本：

```
CONFLICT
```
```
index.lock
```
```
operation not permitted
```
```
permission denied
```
```
.git/worktrees/
```
```
ORIG_HEAD
```
```
CHERRY_PICK_HEAD
```
```
branch is already checked out
```

如果任务明显涉及大量Git操作，不要等到写入失败后才加载此技能。

Misdiagnoses To Avoid

需避免的误诊

Never say any of the following unless Git actually proved it:

"this is a merge conflict" when the error is really permission-related
"this is just local to the current worktree" when the common git dir may be involved
"Git is broken" when the real issue is dirty state, detached HEAD, or an in-progress operation
"just rerun it" without saying whether the block is conflict, repo state, or sandbox

除非Git实际证实，否则绝不要说以下任何内容：

当错误实际与权限相关时，说“这是合并冲突”
当可能涉及公共Git目录时，说“这仅局限于当前worktree”
当实际问题是脏状态、分离HEAD或正在进行的操作时，说“Git坏了”
不说明阻止原因是冲突、仓库状态还是沙箱，就说“重新运行即可”

Step 1 — Orient the Repository

步骤1 — 定位仓库

Before any meaningful Git action, inspect the repository shape:

bash

git rev-parse --show-toplevel
git rev-parse --git-dir
git branch --show-current
git status --short

If the user mentions worktrees or

.git

is a file rather than a directory, also inspect:

bash

git worktree list
git rev-parse --git-common-dir

Summarize:

repo root
current branch
whether the tree is dirty
whether this is a worktree
whether shared Git metadata lives outside the current directory

在执行任何有意义的Git操作前，检查仓库结构：

bash

git rev-parse --show-toplevel
git rev-parse --git-dir
git branch --show-current
git status --short

如果用户提到worktree，或

.git

是文件而非目录，还需检查：

bash

git worktree list
git rev-parse --git-common-dir

总结信息：

仓库根目录
当前分支
工作树是否处于脏状态
是否为worktree
共享Git元数据是否存储在当前目录之外

Step 2 — Classify the Requested Operation

步骤2 — 分类请求的操作

Handle the request as one of these categories:

```
inspect
```
: status, log, diff, branch list, remotes, worktree layout
```
safe_write
```
: add, commit, cherry-pick, merge, rebase, stash, branch creation, worktree creation
```
destructive_write
```
: reset, checkout over local changes, clean, branch deletion, stash drop, force push

For

inspect

, run the command directly if sandbox rules allow it.

For

safe_write

, do a preflight check first.

For

destructive_write

, require explicit user confirmation before executing.

将请求分为以下类别之一处理：

```
inspect
```
（检查）：状态、日志、差异、分支列表、远程仓库、worktree布局
```
safe_write
```
（安全写入）：add、commit、cherry-pick、merge、rebase、stash、分支创建、worktree创建
```
destructive_write
```
（破坏性写入）：reset、覆盖本地更改的checkout、clean、分支删除、stash丢弃、强制推送

对于

inspect

操作，如果沙箱规则允许，直接运行命令。

对于

safe_write

操作，先执行预检检查。

对于

destructive_write

操作，执行前需要用户明确确认。

Step 3 — Preflight Before Any State-Changing Git Command

步骤3 — 执行修改状态的Git命令前的预检

Before

safe_write

destructive_write

, gather enough context to avoid sloppy failure handling:

bash

git status --short
git branch --show-current
git rev-parse --short HEAD

For

cherry-pick

merge

, or

rebase

, also inspect the target commit or branch first:

bash

git log --oneline --decorate -n 5
git show --stat --summary <target>

For worktrees, inspect the shared metadata location:

bash

git rev-parse --git-common-dir

If the command will likely write to shared Git metadata outside the sandboxed writable root, tell the user this before running it and be ready to request escalation.

If the user specifically asked for a worktree-scoped write operation such as

cherry-pick

merge

, or

commit

, explicitly mention before running it that worktrees may require writes under the common git dir rather than only the visible worktree path.

在执行

safe_write

或

destructive_write

操作前，收集足够上下文以避免草率的故障处理：

bash

git status --short
git branch --show-current
git rev-parse --short HEAD

对于

cherry-pick

、

merge

或

rebase

操作，还需先检查目标提交或分支：

bash

git log --oneline --decorate -n 5
git show --stat --summary <target>

对于worktree，检查共享元数据位置：

bash

git rev-parse --git-common-dir

如果命令可能会写入沙箱可写根目录之外的共享Git元数据，在运行前告知用户，并准备好请求权限提升。

如果用户明确要求执行worktree范围的写入操作（如

cherry-pick

、

merge

或

commit

），在运行前明确说明worktree可能需要在公共Git目录下写入，而非仅在可见的worktree路径中。

Step 4 — Execute and Interpret Failures Correctly

步骤4 — 正确执行并解释故障

When a Git write fails, classify the failure before telling the user what happened.

Use the guidance in

references/failure-modes.md

. The high-level rule is:

If Git reports
```
CONFLICT
```
, conflict markers, or asks to resolve files, this is a code conflict
If Git reports
```
operation not permitted
```
,
```
permission denied
```
, failure to create lock files, or inability to update refs or worktree metadata, this is a sandbox or permission problem
If Git reports dirty state, untracked-file overwrite, detached HEAD mismatch, or missing commit, this is a repository state problem

Do not tell the user "there is a conflict" unless Git actually reported one.

当Git写入失败时，先对故障进行分类，再告知用户情况。

遵循

references/failure-modes.md

中的指导原则。高层规则如下：

如果Git报告
```
CONFLICT
```
、冲突标记或要求解决文件，这是代码冲突
如果Git报告
```
operation not permitted
```
、
```
permission denied
```
、无法创建锁定文件或无法更新引用或worktree元数据，这是沙箱或权限问题
如果Git报告脏状态、未跟踪文件覆盖、分离HEAD不匹配或提交缺失，这是仓库状态问题

除非Git实际报告，否则不要告诉用户“存在冲突”。

Step 5 — Escalate Cleanly When Sandbox Restrictions Are the Real Problem

步骤5 — 当沙箱限制是真正问题时，清晰请求权限提升

If a write command is important and fails because of sandbox restrictions:

State that the failure is environmental, not a code conflict
Name the blocked operation
Mention the likely write target if known, such as:
- ```
.git/index.lock
```
- ```
.git/worktrees/...
```
- shared refs under the common git dir
Request permission escalation and rerun the same command

Use wording like:

This
git cherry-pick
failure looks like a sandbox write restriction, not a merge conflict. Git needs to update shared worktree metadata, so I should rerun it with elevated permissions.

如果重要的写入命令因沙箱限制而失败：

说明故障是环境问题，而非代码冲突
指出被阻止的操作
如果已知，提及可能的写入目标，例如：
- ```
.git/index.lock
```
- ```
.git/worktrees/...
```
- 公共Git目录下的共享引用
请求权限提升并重新运行同一命令

使用类似如下表述：

此次
git cherry-pick
失败看起来是沙箱写入限制导致的，而非合并冲突。Git需要更新共享worktree元数据，因此我需要以提升后的权限重新运行该命令。

Step 6 — Worktree-Specific Rules

步骤6 — Worktree特定规则

When the repo uses worktrees:

Assume
```
commit
```
,
```
cherry-pick
```
,
```
merge
```
,
```
rebase
```
, and similar commands may write outside the current worktree directory

Check

git worktree list

and

git rev-parse --git-common-dir

early

Avoid claiming that a failure is "local to this worktree" until you confirm where Git is trying to write
Be extra careful with branch deletion or reset because another worktree may be using the same branch

Read

references/worktrees.md

for the detailed handling rules.

当仓库使用worktree时：

假设
```
commit
```
、
```
cherry-pick
```
、
```
merge
```
、
```
rebase
```
及类似命令可能会在当前worktree目录之外写入

尽早检查

git worktree list

和

git rev-parse --git-common-dir

在确认Git尝试写入的位置前，不要声称故障“仅局限于此worktree”
删除分支或执行reset时要格外小心，因为其他worktree可能正在使用同一分支

阅读

references/worktrees.md

获取详细处理规则。

Step 7 — Report Outcomes Precisely

步骤7 — 精确报告结果

When you finish, report one of these outcomes clearly:

success
conflict requiring manual resolution
sandbox or permission restriction
repository state problem that needs a user choice

For each case, give the user the next action, not a vague Git dump.

Good example:

git cherry-pick <commit>
did not reach merge resolution. Git was blocked from writing shared worktree metadata under the common git dir, so this is a sandbox issue. The next step is to rerun the same command with elevated permissions.

Bad example:

cherry-pick failed, probably a conflict

完成操作后，清晰报告以下结果之一：

成功
需要手动解决的冲突
沙箱或权限限制
需要用户选择的仓库状态问题

对于每种情况，告知用户下一步操作，而非模糊的Git输出。

好示例：

git cherry-pick <commit>
未完成合并解析。Git被阻止写入公共Git目录下的共享worktree元数据，因此这是沙箱问题。下一步是以提升后的权限重新运行同一命令。

坏示例：

cherry-pick失败了，可能是冲突

Preferred Output Shape

Commands This Skill Should Handle Well

此技能应能妥善处理的命令

```
git status
```
,
```
log
```
,
```
diff
```
,
```
show
```
,
```
branch
```
,
```
remote
```
```
git add
```
,
```
commit
```
,
```
stash
```
```
git cherry-pick
```
```
git merge
```
```
git rebase
```
```
git switch
```
,
```
checkout
```
,
```
checkout -b
```
```
git worktree list
```
,
```
git worktree add
```

```
git status
```
、
```
log
```
、
```
diff
```
、
```
show
```
、
```
branch
```
、
```
remote
```
```
git add
```
、
```
commit
```
、
```
stash
```
```
git cherry-pick
```
```
git merge
```
```
git rebase
```
```
git switch
```
、
```
checkout
```
、
```
checkout -b
```
```
git worktree list
```
、
```
git worktree add
```

Commands Requiring Extra Caution

需要格外谨慎的命令

```
git reset --hard
```
```
git checkout -- <path>
```
```
git clean -fd
```
```
git branch -D
```
```
git stash drop
```
or
```
clear
```
```
git push --force
```

Do not run these without explicit user approval.

```
git reset --hard
```
```
git checkout -- <path>
```
```
git clean -fd
```
```
git branch -D
```
```
git stash drop
```
或
```
clear
```
```
git push --force
```

未经用户明确批准，不要运行这些命令。

safe-git-ops

Original

Translation

Safe Git Ops

安全Git操作

Skill Directory Layout

技能目录结构

Progressive Loading

渐进式加载

Core Behavior

核心行为

Trigger Heuristics

触发规则

Misdiagnoses To Avoid

需避免的误诊

Step 1 — Orient the Repository

步骤1 — 定位仓库

Step 2 — Classify the Requested Operation

步骤2 — 分类请求的操作

Step 3 — Preflight Before Any State-Changing Git Command

步骤3 — 执行修改状态的Git命令前的预检

Step 4 — Execute and Interpret Failures Correctly

步骤4 — 正确执行并解释故障

Step 5 — Escalate Cleanly When Sandbox Restrictions Are the Real Problem

步骤5 — 当沙箱限制是真正问题时，清晰请求权限提升

Step 6 — Worktree-Specific Rules

步骤6 — Worktree特定规则

Step 7 — Report Outcomes Precisely

步骤7 — 精确报告结果

Preferred Output Shape

推荐输出格式

Commands This Skill Should Handle Well

此技能应能妥善处理的命令

Commands Requiring Extra Caution

需要格外谨慎的命令