pr-cleanup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR Cleanup Skill

PR清理Skill

Operator Context

操作场景

This skill operates as an operator for post-merge branch cleanup, configuring Claude's behavior for safe, systematic removal of stale local branches. It implements a Sequential Safety pattern -- identify target, verify merge status, delete safely, confirm result.

该Skill用于合并后的分支清理，配置Claude的行为以安全、系统地移除过时的本地分支。它采用顺序安全模式——识别目标分支、验证合并状态、安全删除、确认结果。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

Protected Branches: NEVER delete main, master, or develop branches
Safe Delete First: Always use
```
git branch -d
```
before considering
```
-D
```
Identify Before Switch: Capture branch name BEFORE switching to main
Verify Merge Status: Confirm branch was merged or remote-deleted before removing
Report Results: Always show what was deleted and what remains
Worktree Cleanup First: Before deleting any branch, check if a git worktree references it. Worktree branches block
```
git branch -d/-D
```
and
```
gh pr merge --delete-branch
```
. Run
```
git worktree remove
```
before branch deletion.

受保护分支：绝不删除main、master或develop分支
优先安全删除：始终先使用
```
git branch -d
```
，再考虑使用
```
-D
```
先识别再切换：在切换到main分支前先记录目标分支名称
验证合并状态：在移除分支前确认该分支已合并或远程分支已删除
报告结果：始终展示已删除的分支和剩余的分支
先清理工作区：在删除任何分支前，检查是否有git worktree引用该分支。Worktree分支会阻止
```
git branch -d/-D
```
和
```
gh pr merge --delete-branch
```
命令的执行。在删除分支前先运行
```
git worktree remove
```
。

Default Behaviors (ON unless disabled)

默认行为（默认开启，可关闭）

Prune Remote References: Run
```
git remote prune origin
```
after cleanup
Pull Latest: Pull main/master with
```
--prune
```
after switching
Show Remaining Branches: List local branches after cleanup completes
Squash-Merge Detection: Check for
```
[gone]
```
upstream when
```
-d
```
fails

修剪远程引用：清理完成后运行
```
git remote prune origin
```
拉取最新代码：切换到main/master分支后，使用
```
--prune
```
参数拉取最新代码
展示剩余分支：清理完成后列出所有本地分支
检测 squash 合并：当
```
-d
```
命令执行失败时，检查上游分支是否标记为
```
[gone]
```

Optional Behaviors (OFF unless enabled)

可选行为（默认关闭，可开启）

Batch Cleanup: Delete all merged branches with
```
--all
```
flag
Dry Run: Show what would be deleted without acting, with
```
--dry-run
```
flag

批量清理：使用
```
--all
```
参数删除所有已合并的分支
试运行：使用
```
--dry-run
```
参数展示会删除的分支，但不执行实际删除操作

What This Skill CAN Do

该Skill可实现的功能

Delete local branches that have been merged into main/master
Detect squash-merged branches by checking upstream tracking status
Batch-delete all merged branches except protected ones
Prune stale remote-tracking references
Dry-run to preview cleanup actions

删除已合并到main/master的本地分支
通过检查上游跟踪状态检测squash合并的分支
批量删除除受保护分支外的所有已合并分支
修剪过时的远程跟踪引用
试运行以预览清理操作

What This Skill CANNOT Do

该Skill不可实现的功能

Delete remote branches (local cleanup only)
Review or merge PRs (use /pr-review instead)
Run CI checks (use ci skill instead)
Create or rename branches
Force-delete unmerged branches without explicit user confirmation

删除远程分支（仅支持本地清理）
评审或合并PR（请使用/pr-review）
运行CI检查（请使用CI Skill）
创建或重命名分支
在未获得用户明确确认的情况下强制删除未合并的分支

Instructions

操作步骤

Step 0: CHECK for Worktrees

步骤0：检查Worktree

Goal: Remove any git worktrees referencing the target branch before attempting deletion.

Worktree agents (dispatched with

isolation: "worktree"

) create local branches that block both

git branch -d

and

gh pr merge --delete-branch

. Check and clean up worktrees first:

bash

undefined

目标：在尝试删除分支前，移除所有引用目标分支的git worktree。

Worktree代理（通过

isolation: "worktree"

调度）创建的本地分支会阻止

git branch -d

和

gh pr merge --delete-branch

命令的执行。请先检查并清理Worktree：

bash

undefined

List worktrees referencing any branch

列出引用任何分支的Worktree

git worktree list

If the target branch appears in a worktree, remove it

如果目标分支出现在某个Worktree中，移除该Worktree

git worktree remove <worktree-path>


If worktree removal fails (e.g., uncommitted changes), report the issue to the user. Do not force-remove without confirmation.

**Gate**: No worktrees reference the target branch.

git worktree remove <worktree-path>


如果Worktree移除失败（例如存在未提交的更改），请向用户报告问题。未获得确认前请勿强制移除。

**检查点**：没有Worktree引用目标分支。

Step 1: IDENTIFY Target Branch

步骤1：识别目标分支

Goal: Determine which branch to clean up before any state changes.

If user provides a branch name argument, use that. Otherwise capture the current branch:

bash

BRANCH_TO_DELETE=$(git branch --show-current)

If already on main/master, ask the user which branch to clean up. Do not proceed without a target.

Detect the main branch name:

bash

MAIN_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "master")

Gate: Branch to delete is identified and is NOT a protected branch (main/master/develop).

目标：在更改任何状态前确定要清理的分支。

如果用户提供了分支名称参数，使用该名称。否则获取当前所在分支：

bash

BRANCH_TO_DELETE=$(git branch --show-current)

如果当前已在main/master分支上，请询问用户要清理的分支名称。未确定目标分支前请勿继续。

检测主分支名称：

bash

MAIN_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "master")

检查点：已识别目标分支，且该分支不是受保护分支（main/master/develop）。

Step 2: SWITCH and Pull

步骤2：切换分支并拉取最新代码

Goal: Move to main branch and sync with remote.

bash

git checkout "$MAIN_BRANCH" && git pull --prune origin "$MAIN_BRANCH"

Gate: Successfully on main/master with latest changes.

目标：切换到主分支并与远程仓库同步。

bash

git checkout "$MAIN_BRANCH" && git pull --prune origin "$MAIN_BRANCH"

检查点：成功切换到main/master分支并获取了最新代码。

Step 3: DELETE Local Branch

步骤3：删除本地分支

Goal: Remove the target branch safely.

Attempt safe delete first:

bash

git branch -d "$BRANCH_TO_DELETE"

-d

fails with "not fully merged":

Check if branch was squash-merged by looking for gone upstream:

bash

git branch --format '%(refname:short) %(upstream:track)' | grep "$BRANCH_TO_DELETE"

If upstream shows
```
[gone]
```
, the remote branch was deleted (PR was merged). Inform user and offer
```
-D
```
.
If upstream is NOT gone, warn user the branch may contain unmerged work. Only use
```
-D
```
with explicit user confirmation.

Prune stale remote-tracking references:

bash

git remote prune origin

Gate: Target branch deleted and remote references pruned.

目标：安全删除目标分支。

首先尝试安全删除：

bash

git branch -d "$BRANCH_TO_DELETE"

如果

-d

命令执行失败并提示“not fully merged”（未完全合并）：

通过检查上游分支是否标记为gone来判断是否为squash合并：

bash

git branch --format '%(refname:short) %(upstream:track)' | grep "$BRANCH_TO_DELETE"

如果上游分支显示
```
[gone]
```
，说明远程分支已删除（PR已合并）。告知用户并建议使用
```
-D
```
命令。
如果上游分支未标记为gone，警告用户该分支可能包含未合并的工作内容。仅在获得用户明确确认后使用
```
-D
```
命令。

修剪过时的远程跟踪引用：

bash

git remote prune origin

检查点：目标分支已删除，远程引用已修剪。

Step 4: REPORT Results

步骤4：报告结果

Goal: Confirm what happened and show current state.

Report format:

PR Cleanup Complete
  - Switched to: [main branch name]
  - Deleted local branch: [branch name]
  - Pruned remote references
  - Remaining local branches:
    [list from git branch]

Run

git branch

to show remaining local branches.

目标：确认操作结果并展示当前状态。

报告格式：

PR清理完成
  - 已切换到：[主分支名称]
  - 已删除本地分支：[分支名称]
  - 已修剪远程引用
  - 剩余本地分支：
    [git branch命令的输出列表]

运行

git branch

命令展示剩余的本地分支。

Extended Cleanup (--all)

扩展清理（--all参数）

When user passes

--all

, first remove all stale worktrees, then delete branches:

bash

undefined

当用户传入

--all

参数时，首先移除所有过时的Worktree，然后删除分支：

bash

undefined

Step 0: Clean up worktrees pointing at branches we're about to delete

步骤0：清理指向即将删除分支的所有过时Worktree

git worktree list --porcelain | grep -A2 'branch refs/heads/' | grep -v 'main|master|develop'

git worktree list --porcelain | grep -A2 'branch refs/heads/' | grep -v 'main\|master\|develop'

For each stale worktree: git worktree remove <path>

对于每个过时的Worktree：git worktree remove <path>


Then delete all branches merged into main except protected branches:

```bash
git branch --merged "$MAIN_BRANCH" | grep -v -E '^\*|main|master|develop' | xargs -r git branch -d

Also find squash-merged branches with gone upstreams:

bash

git branch --format '%(refname:short) %(upstream:track)' | awk '$2 == "[gone]" { print $1 }'

Show the full list before deleting and confirm with user if more than 3 branches.


然后删除所有已合并到主分支的分支（受保护分支除外）：

```bash
git branch --merged "$MAIN_BRANCH" | grep -v -E '^\\*|main|master|develop' | xargs -r git branch -d

同时找出上游分支已标记为gone的squash合并分支：

bash

git branch --format '%(refname:short) %(upstream:track)' | awk '$2 == "[gone]" { print $1 }'

如果待删除的分支超过3个，请先展示完整列表并获得用户确认后再执行删除操作。

Examples

示例

Example 1: Current Branch Cleanup

示例1：当前分支清理

User says:

/pr-cleanup

Actions:

Capture current branch name (IDENTIFY)
Switch to main, pull latest (SWITCH)
Delete the branch with
```
-d
```
, prune remote refs (DELETE)
Show remaining branches (REPORT)

用户输入：

/pr-cleanup

操作：

获取当前分支名称（识别）
切换到main分支并拉取最新代码（切换）
使用
```
-d
```
命令删除分支，修剪远程引用（删除）
展示剩余分支（报告）

Example 2: Named Branch Cleanup

示例2：指定分支清理

User says:

/pr-cleanup feature/auth-flow

Actions:

Use
```
feature/auth-flow
```
as target (IDENTIFY)
Switch to main, pull latest (SWITCH)
Delete
```
feature/auth-flow
```
, prune remote refs (DELETE)
Show remaining branches (REPORT)

用户输入：

/pr-cleanup feature/auth-flow

操作：

使用
```
feature/auth-flow
```
作为目标分支（识别）
切换到main分支并拉取最新代码（切换）
删除
```
feature/auth-flow
```
分支，修剪远程引用（删除）
展示剩余分支（报告）

Example 3: Squash-Merged Branch

示例3：Squash合并分支清理

User says:

/pr-cleanup

on a squash-merged branch Actions:

Capture current branch name (IDENTIFY)
Switch to main, pull latest (SWITCH)
```
-d
```
fails, detect
```
[gone]
```
upstream, use
```
-D
```
after informing user (DELETE)
Show remaining branches (REPORT)

用户在squash合并的分支上输入：

/pr-cleanup

操作：

获取当前分支名称（识别）
切换到main分支并拉取最新代码（切换）
```
-d
```
命令执行失败，检测到上游分支标记为
```
[gone]
```
，告知用户后使用
```
-D
```
命令删除（删除）
展示剩余分支（报告）

Error Handling

错误处理

Error: "Branch not fully merged"

错误：“Branch not fully merged”

Cause: Branch was squash-merged or rebase-merged, so git does not recognize it as merged Solution:

Check if upstream tracking shows
```
[gone]
```
(remote branch deleted after PR merge)
If gone, inform user and use
```
git branch -D
```
to force-delete
If not gone, warn user branch may have unmerged work and ask for confirmation

原因：分支采用squash合并或变基合并，导致Git无法识别其已合并解决方案：

检查上游跟踪状态是否显示
```
[gone]
```
（PR合并后远程分支已删除）
如果显示
```
[gone]
```
，告知用户并使用
```
git branch -D
```
强制删除
如果未显示
```
[gone]
```
，警告用户该分支可能包含未合并的工作内容，需获得用户确认后再使用
```
-D
```
命令

Error: "Cannot delete checked-out branch"

错误：“Cannot delete checked-out branch”

Cause: Attempting to delete the branch you are currently on Solution:

Switch to main/master first with
```
git checkout
```
Then retry the delete operation

原因：尝试删除当前所在的分支解决方案：

先使用
```
git checkout
```
切换到main/master分支
然后重试删除操作

Error: "Cannot determine main branch"

错误：“Cannot determine main branch”

Cause:

refs/remotes/origin/HEAD

is not set (common in freshly cloned repos) Solution:

Try
```
git remote set-head origin --auto
```
to set it
Fall back to checking if
```
main
```
or
```
master
```
exists locally
Ask user to specify if neither is found

原因：

refs/remotes/origin/HEAD

未设置（常见于刚克隆的仓库）解决方案：

尝试使用
```
git remote set-head origin --auto
```
设置
回退到检查本地是否存在
```
main
```
或
```
master
```
分支
如果两者都不存在，请询问用户指定主分支

Anti-Patterns

反模式

Anti-Pattern 1: Force-Deleting Without Checking Merge Status

反模式1：未检查合并状态就强制删除

What it looks like: Using

git branch -D

immediately without trying

-d

first Why wrong: May destroy unmerged work with no recovery path Do instead: Always try

-d

first, check merge/upstream status, then

-D

only with evidence

表现：直接使用

git branch -D

命令，而不先尝试

-d

危害：可能会销毁未合并的工作内容，且无法恢复 正确做法：始终先尝试

-d

命令，检查合并/上游状态，仅在有证据表明已合并时使用

-D

Anti-Pattern 2: Deleting Before Switching

反模式2：未切换分支就删除

What it looks like: Trying to delete the current branch while still on it Why wrong: Git will refuse, causing a confusing error Do instead: Always switch to main/master before deleting the target branch

表现：在当前所在分支上尝试删除该分支危害：Git会拒绝执行，导致令人困惑的错误 正确做法：始终先切换到main/master分支，再删除目标分支

Anti-Pattern 3: Skipping the Report

反模式3：跳过结果报告

What it looks like: Deleting branches silently without showing what was removed Why wrong: User has no confirmation of what happened, no visibility into remaining state Do instead: Always list deleted branches and remaining local branches

表现：静默删除分支，不展示已移除的分支危害：用户无法确认操作结果，也无法了解当前仓库状态 正确做法：始终列出已删除的分支和剩余的本地分支

Anti-Pattern 4: Batch Delete Without Preview

反模式4：批量删除前未预览

What it looks like: Running

--all

and deleting everything without showing the list first Why wrong: May delete branches user intended to keep Do instead: Show the list of branches to be deleted and confirm before proceeding

表现：使用

--all

参数直接删除所有分支，而不先展示待删除列表危害：可能会删除用户想要保留的分支 正确做法：先展示待删除的分支列表，获得用户确认后再执行删除操作

References

参考资料

This skill uses these shared patterns:

Verification Checklist - Pre-completion checks

该Skill使用以下共享模式：

验证清单 - 完成前检查 ",