git-worktree-tidy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

git-worktree-tidy

Routine hygiene for bare-repo + worktree layouts. Fetches origin, prunes gone branches and orphaned worktrees, and fast-forwards important local branches.

针对裸仓库（bare-repo）+工作区（worktree）结构的常规清理操作。从origin拉取代码，清理已失效的分支和孤立工作区，并快进重要的本地分支。

When to use

适用场景

User asks to "fetch prune", "clean up stale branches/worktrees", or "update main/dev to latest" in a worktree-based repo.

当用户在基于worktree的仓库中要求「拉取并清理（fetch prune）」、「清理过时分支/工作区」或「将main/dev分支更新到最新版本」时使用。

Hard Rules

硬性规则

All destructive actions (worktree remove, branch delete) require user confirmation. Present the full list and wait.
Never force-delete a worktree with uncommitted changes without explicit approval. Flag dirty worktrees separately.
Use
```
--ff-only
```
when updating branches. If ff-only fails, stop and ask.
Operate from the
```
.bare
```
directory (or repo root) for branch/worktree management commands.

所有破坏性操作（删除工作区、删除分支）都需要用户确认。展示完整操作列表并等待用户确认。
未经明确许可，绝不能强制删除包含未提交更改的工作区。需单独标记有未提交更改的工作区。
更新分支时使用
```
--ff-only
```
参数。如果快进失败，立即停止并询问用户。
分支和工作区管理命令需在
```
.bare
```
目录（或仓库根目录）下执行。

Workflow

工作流程

1) Locate the bare root

1) 定位裸仓库根目录

Determine the bare repo directory:

If cwd contains
```
.bare/
```
, use it
Otherwise:
```
git rev-parse --git-common-dir
```

All branch and worktree management commands run from this directory.

确定裸仓库目录：

如果当前工作目录包含
```
.bare/
```
，则使用该目录
否则执行命令：
```
git rev-parse --git-common-dir
```

所有分支和工作区管理命令都从该目录执行。

2) Fetch + prune

2) 拉取并清理

bash

git fetch --prune origin

Report what was pruned (deleted remote-tracking branches, updated refs).

bash

git fetch --prune origin

报告清理的内容（已删除的远程追踪分支、更新的引用）。

3) Discover stale branches

3) 发现过时分支

bash

git branch -vv | grep ': gone]'

Collect branch names whose upstream is gone.

bash

git branch -vv | grep ': gone]'

收集上游分支已失效的本地分支名称。

4) Discover stale worktrees

4) 发现过时工作区

bash

git worktree list
git worktree prune --dry-run

Cross-reference worktrees against the gone-branch list. Check each stale worktree for dirty state:

bash

cd <worktree-path> && git status --short

Categorize:

Clean + gone: safe to remove
Dirty + gone: flag for user review
Prunable metadata: orphaned worktree entries (directory already gone)

bash

git worktree list
git worktree prune --dry-run

将工作区列表与已失效分支列表交叉比对。检查每个过时工作区的状态：

bash

cd <worktree-path> && git status --short

分类标记：

已清理+已失效：可安全删除
有未提交更改+已失效：标记出来供用户审核
可清理元数据：孤立的工作区条目（对应目录已不存在）

5) Confirm deletions

5) 确认删除操作

Present a summary table:

Stale worktrees to remove:
  <path> (<branch>) [clean]
  <path> (<branch>) [dirty — N uncommitted changes]

Stale branches to delete:
  <branch>

Prunable worktree metadata:
  <entry>

Wait for user confirmation before proceeding.

展示汇总表格：

待删除的过时工作区：
  <路径> (<分支>) [已清理]
  <路径> (<分支>) [有未提交更改 — N项未提交内容]

待删除的过时分支：
  <分支>

可清理的工作区元数据：
  <条目>

在执行前等待用户确认。

6) Remove stale worktrees

6) 删除过时工作区

For each confirmed worktree:

bash

git worktree remove <name>

If removal fails (dirty), report and skip unless user approved force.

对每个已确认的工作区执行：

bash

git worktree remove <name>

如果删除失败（因工作区有未提交更改），则报告并跳过，除非用户批准强制删除。

7) Delete stale branches

7) 删除过时分支

bash

git branch -D <branch1> <branch2> ...

bash

git branch -D <branch1> <branch2> ...

8) Prune worktree metadata

8) 清理工作区元数据

bash

git worktree prune -v

bash

git worktree prune -v

9) Update important branches

9) 更新重要分支

Identify which branches have dedicated worktrees for

main

dev

, or other important branches (user may specify). For each:

bash

cd <worktree-path> && git pull --ff-only origin <branch>

If ff-only fails, report the divergence and ask for guidance.

识别哪些分支有专用工作区（如

main

、

dev

或用户指定的其他重要分支）。对每个分支执行：

bash

cd <worktree-path> && git pull --ff-only origin <branch>

如果快进失败，报告分支分歧情况并询问用户指导。

10) Final status

10) 最终状态

Show a summary: what was removed, what was updated, any items skipped.

展示汇总信息：已删除的内容、已更新的内容、以及任何被跳过的项。