Back to Details

repository-cleanup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Repository Cleanup

仓库清理

Goal

目标

Inspect local and remote branches, pull requests, commits, stashes, worktrees, and the local databases left behind by old worktrees. Recover valuable work, then remove the proven stale state the user selects, until the repository is current and organized. Nothing is removed that the user did not select by name.
检查本地和远程分支、PR、提交、stash、worktree，以及旧 worktree 遗留的本地数据库。先恢复有价值的工作，再移除用户选定的、已证实过时的状态，直至仓库保持最新且井然有序。未经用户按名称选择，不会移除任何内容。

Loop Prompt

循环提示词

text
Inspect local and remote branches, pull requests, commits, stashes, and worktrees. Recover valuable work, list everything stale, and remove only the items the user selects, until the repository is current and organized.
Stop when valuable work is recovered and remaining repository state is intentional.
text
Inspect local and remote branches, pull requests, commits, stashes, and worktrees. Recover valuable work, list everything stale, and remove only the items the user selects, until the repository is current and organized.
当有价值的工作已恢复，且剩余的仓库状态均是有意保留时停止。

When To Use

使用场景

Use this when abandoned branches, old worktrees, unclear pull requests, unmerged commits, or forgotten stashes make it difficult to know which repository state still matters.
This loop cleans Git repository state. It is not a source-code housekeeping pass; use 
housekeeper
for dead code, stale files, duplicated logic, broken links, unused dependencies, and project-structure cleanup.
当废弃分支、旧 worktree、状态不明的 PR、未合并的提交或被遗忘的 stash 导致难以判断哪些仓库状态仍然重要时，使用此流程。
此流程用于清理 Git 仓库状态，并非对源代码进行维护整理；死代码、无效文件、重复逻辑、失效链接、未使用的依赖和项目结构清理应使用 
housekeeper
。

Workflow

工作流程

  1. Inspect the current working tree before changing anything: current branch, uncommitted changes, stashes, remotes, upstreams, and registered worktrees.
  2. Fetch current remote state without pruning. List the stale remote-tracking refs instead (
    git remote prune --dry-run <remote>
    ); they are removal candidates like any other.
  3. Inventory local branches, remote branches, open and recently closed pull requests, unmerged commits, stashes, worktrees, and orphaned databases (see Databases).
  4. Classify each item as current, valuable but unfinished, superseded, merged, abandoned, or uncertain.
  5. Record evidence for each classification: upstream status, merge base, PR state, commit reachability, stash contents, worktree dirtiness, owner, and recent activity.
  6. Recover valuable work before cleanup. Move useful commits or stashed changes to the appropriate current branch, preserve patches, or keep a clearly named branch.
  7. Ask before removing anything. Put every removal candidate of the batch (merged branches, stale remote-tracking refs, stashes, worktrees, databases, remote branches, PRs to close) in one list: each item's exact name, the step 5 evidence, its size where known, and 
    cannot recover
    when nothing else holds a copy. Ask the user to pick the items to remove (
    AskUserQuestion
    with 
    multiSelect: true
    where available, nothing pre-ticked; otherwise a numbered list they answer with numbers). An answer that names no item ("ok", "go ahead") picks nothing.
  8. Remove only the selected items, by their exact names. Everything unselected stays, and the report names it.
  9. Rerun the inventory after cleanup until every remaining branch, pull request, commit, stash, worktree, and database is intentional.
  1. 在更改任何内容前检查当前工作树：当前分支、未提交更改、stash、remote、upstream 和已注册的 worktree。
  2. 获取最新的远程状态，但不要执行 prune。改为列出过时的远程跟踪引用（
    git remote prune --dry-run <remote>
    ）；它们与其他项目一样，都是移除候选项。
  3. 清点本地分支、远程分支、开放及最近关闭的 PR、未合并的提交、stash、worktree 和孤立数据库（参见“数据库”）。
  4. 将每个项目分类为：当前、有价值但未完成、已被取代、已合并、已废弃或不确定。
  5. 为每项分类记录证据：upstream 状态、merge base、PR 状态、提交可达性、stash 内容、worktree 是否存在未提交更改、所有者以及近期活动。
  6. 清理前先恢复有价值的工作。将有用提交或 stash 中的更改移至合适的当前分支、保存补丁，或保留一个名称清晰的分支。
  7. 移除任何内容前先征求用户同意。将该批次的所有移除候选项（已合并分支、过时的远程跟踪引用、stash、worktree、数据库、远程分支和需要关闭的 PR）集中列在一份清单中：每个项目的准确名称、第 5 步中的证据、已知时的体积；如果没有其他副本，则标注 
    cannot recover
    。请用户选择要移除的项目（可用时使用 
    AskUserQuestion
    并设置 
    multiSelect: true
    ，且不预选任何项目；否则提供编号清单，由用户用编号回答）。回答中未指定任何项目（如“ok”“继续执行”）表示不选择任何项目。
  8. 仅按准确名称移除用户选定的项目。未选定的所有内容保持不变，并在报告中列出。
  9. 清理后重新执行清点，直至每个剩余的分支、PR、提交、stash、worktree 和数据库都有明确保留意图。

Inventory Commands

清点命令

Use the repository's existing tools and hosting provider first. Common Git and GitHub CLI checks:
bash
git status --short --branch
git stash list
git stash show --stat stash@{0}
git remote -v
git fetch --all
git remote prune --dry-run origin
git worktree list --porcelain
git branch --format='%(refname:short) %(upstream:short) %(committerdate:relative)'
git branch --merged
git branch --no-merged
git log --all --decorate --oneline --graph --date-order -n 80
gh pr list --state open --json number,title,headRefName,baseRefName,author,updatedAt,url
gh pr list --state closed --limit 30 --json number,title,headRefName,baseRefName,author,updatedAt,closedAt,mergedAt,url
Worktrees whose PR merged, and the databases left behind, come from one script. With no arguments it changes nothing and prints the candidates as JSON. It removes only the names you pass, after the user selected them, and it refuses the whole run, changing nothing, if one name is not a candidate:
bash
bash scripts/prune-merged-worktrees.sh    # list: merged clean worktrees, their databases, orphans
bash scripts/prune-merged-worktrees.sh --remove <worktree path> --drop pgsql:<database>   # selected items only
A worktree's database can be dropped only in the same run that removes that worktree. Never pass a name the user did not select, and never build the arguments from the whole list.
If 
gh
is unavailable or the repository is not on GitHub, use the equivalent provider CLI, web UI, or local Git evidence and report the PR visibility gap.
优先使用仓库现有工具和托管服务提供方。常见的 Git 和 GitHub CLI 检查如下：
bash
git status --short --branch
git stash list
git stash show --stat stash@{0}
git remote -v
git fetch --all
git remote prune --dry-run origin
git worktree list --porcelain
git branch --format='%(refname:short) %(upstream:short) %(committerdate:relative)'
git branch --merged
git branch --no-merged
git log --all --decorate --oneline --graph --date-order -n 80
gh pr list --state open --json number,title,headRefName,baseRefName,author,updatedAt,url
gh pr list --state closed --limit 30 --json number,title,headRefName,baseRefName,author,updatedAt,closedAt,mergedAt,url
已合并 PR 对应的 worktree，以及遗留数据库，都由同一个脚本处理。不带参数运行时，脚本不会更改任何内容，只会将候选项以 JSON 形式打印出来。只有在用户选定后，脚本才会移除传入的指定名称；如果任一名称不是候选项，脚本会拒绝整个运行并保持所有内容不变：
bash
bash scripts/prune-merged-worktrees.sh    # list: merged clean worktrees, their databases, orphans
bash scripts/prune-merged-worktrees.sh --remove <worktree path> --drop pgsql:<database>   # selected items only
worktree 的数据库只能在删除该 worktree 的同一次运行中删除。绝不能传入用户未选择的名称，也绝不能根据完整列表拼接参数。
如果 
gh
不可用，或仓库不在 GitHub 上，请使用相应的提供方 CLI、Web UI 或本地 Git 证据，并报告 PR 可见性方面的缺口。

Databases

数据库

Worktrees and one-off test runs leave local databases behind: a per-worktree 
DB_DATABASE
, throwaway test databases (
<app>_pr42
, 
<app>_triage_<date>
), and Laravel parallel testing's 
<db>_test_N
copies of each. The script's 
databases
list holds, with sizes, each candidate database by exact name, a parallel-testing copy as an item of its own. Its 
source
says why: 
worktree
(registered for, or named by, a candidate worktree), 
registry
(a registered database whose worktree is gone), or 
orphan
(named 
<app db>_*
and named by no 
.env
, 
.env.testing
, or 
phpunit.xml
of the main checkout or a remaining worktree). It never lists a database in use, or a parallel-testing copy of one.
Classify each listed database by its name: a PR number, branch, worktree, or date that maps to merged or removed work is abandoned; a name that reads as a deliberate copy (
_backup
, 
_snapshot
, 
_pre_migration
) or maps to nothing is uncertain. Show the list grouped that way, with sizes, in the step 7 selection, and drop only the selected names, through the script's 
--drop
. Each drop is irreversible: offer a 
pg_dump
/
mysqldump
first for anything uncertain.
worktree 和一次性测试运行会遗留本地数据库：每个 worktree 独享的 
DB_DATABASE
、临时测试数据库（
<app>_pr42
、
<app>_triage_<date>
），以及 Laravel parallel testing 创建的各个 
<db>_test_N
副本。脚本的 
databases
列表按准确名称记录每个候选数据库及其大小，并将 parallel-testing 副本单独列为一个项目。其 
source
字段说明原因：
worktree
（为候选 worktree 注册，或由其命名）、
registry
（已注册数据库对应的 worktree 已不存在），或 
orphan
（名称为 
<app db>_*
，且主 checkout 或剩余 worktree 的任何 
.env
、
.env.testing
或 
phpunit.xml
均未引用）。它绝不会列出正在使用的数据库，或正在使用的数据库的 parallel-testing 副本。
根据名称对每个列出的数据库进行分类：如果 PR 编号、分支、worktree 或日期对应已合并或已移除的工作，则归为已废弃；如果名称看起来是刻意创建的副本（
_backup
、
_snapshot
、
_pre_migration
），或无法对应任何内容，则归为不确定。在第 7 步的选择中按上述方式分组展示列表及大小，并且只通过脚本的 
--drop
删除选定的名称。每次删除都不可逆：对于任何不确定的数据库，应先提供 
pg_dump
/
mysqldump
备份选项。

Classification Guide

分类指南

  • Current: actively used branch, active pull request, current worktree, release branch, or protected branch.
  • Valuable but unfinished: contains unmerged commits, unpushed commits, or stashed changes that appear relevant, even if old.
  • Superseded: replaced by a newer branch, merged through a different branch, or made irrelevant by a later implementation.
  • Merged: fully integrated into the target branch or corresponding pull request is merged.
  • Abandoned: old, ownerless, no useful unique commits or stash contents, no active pull request, and no dirty worktree.
  • Uncertain: insufficient evidence, unclear ownership, dirty worktree, ambiguous unmerged commits, unclear stash contents, or possible external dependency.
Uncertain items are not cleanup candidates until more evidence or user approval resolves them.
  • 当前： 正在使用的分支、活动 PR、当前 worktree、发布分支或受保护分支。
  • 有价值但未完成： 包含看起来相关的未合并提交、未推送提交或 stash 更改，即使它们创建时间较早。
  • 已被取代： 已被更新的分支替代、通过其他分支合并，或因后续实现而不再适用。
  • 已合并： 已完全合并到目标分支，或对应 PR 已合并。
  • 已废弃： 历史较久、无明确所有者、不含有用独有提交或 stash 内容、没有活动 PR，且 worktree 不存在未提交更改。
  • 不确定： 证据不足、所有权不明确、worktree 存在未提交更改、未合并提交含义不清、stash 内容不明，或可能存在外部依赖。
在获得更多证据或用户批准并解决疑点之前，不确定的项目不能作为清理候选项。

Cleanup Rules

清理规则

  • Every removal is one the user selected by name in step 7. Proof that an item is stale makes it a candidate, never a removal; no repository policy or earlier approval replaces the selection.
  • Use 
    git branch -d
    for selected local branches proven merged. Use 
    git branch -D
    only after explicit approval and only after preserving any useful commits.
  • Do not drop stashes until their contents have been inspected and the user has approved the exact stash to drop.
  • Before removing a worktree, verify it has no uncommitted changes and its branch/commits have been classified.
  • Drop a database only when the user selected that exact name. Never drop one the main checkout or a remaining worktree uses.
  • Before deleting a branch with unique commits, preserve the work by merging, cherry-picking, tagging, renaming, or exporting patches.
  • Before dropping a valuable stash, recover it onto the appropriate branch or preserve it as a patch with enough context to reapply.
  • Prefer small batches. Re-inventory after each batch so the next decision uses current evidence.
  • 每项移除操作都必须是用户在第 7 步按名称选择的项目。证明项目已过时只能使其成为候选项，绝不能直接执行移除；仓库策略或以往批准均不能替代本次选择。
  • 对已证实合并的本地分支使用 
    git branch -d
    。只有在获得明确批准且已保存任何有用提交后，才能使用 
    git branch -D
    。
  • 在检查 stash 内容并获得用户对准确 stash 的批准前，不得丢弃 stash。
  • 移除 worktree 前，验证其不存在未提交更改，且其分支和提交已完成分类。
  • 只有用户选择了准确名称时才能删除数据库。绝不能删除主 checkout 或剩余 worktree 正在使用的数据库。
  • 删除包含独有提交的分支前，应通过合并、cherry-pick、打标签、重命名或导出补丁来保存工作。
  • 丢弃有价值的 stash 前，应将其恢复到合适的分支，或保存为包含足够上下文、可重新应用的补丁。
  • 优先采用小批次处理。每批完成后重新清点，使后续决策基于最新证据。

Report

报告

End with:
  • Repository state inventoried.
  • Branches, pull requests, commits, stashes, worktrees, and databases classified.
  • Valuable work recovered or preserved.
  • Cleanup actions taken, with evidence for each.
  • Verification commands run after cleanup.
  • Remaining intentional repository state, including any kept stashes.
  • Deferred or uncertain items and what approval or evidence is needed.
最终报告应包括：
  • 已清点仓库状态。
  • 已对分支、PR、提交、stash、worktree 和数据库进行分类。
  • 已恢复或保留有价值的工作。
  • 已执行清理操作，并附上每项操作的证据。
  • 清理后已运行验证命令。
  • 剩余仓库状态均为有意保留，包括保留的 stash。
  • 已说明暂缓或不确定的项目，以及需要何种批准或证据。

Guardrails

防护规则

  • Do not discard uncommitted changes, stashes, unpushed commits, or dirty worktrees.
  • Do not use 
    git reset --hard
    , 
    git checkout --
    , 
    git clean
    , or force-delete branches unless the user explicitly asked for that exact destructive action.
  • Do not close someone else's pull request or delete a remote branch without confirmation.
  • Do not treat old age alone as proof that work is stale.
  • Preserve evidence for every destructive cleanup action.
  • 不得丢弃未提交更改、stash、未推送提交或存在未提交更改的 worktree。
  • 除非用户明确要求执行对应的破坏性操作，否则不得使用 
    git reset --hard
    、
    git checkout --
    、
    git clean
    或强制删除分支。
  • 未经确认，不得关闭他人的 PR 或删除远程分支。
  • 不得仅凭项目存在时间较久就认定其已过时。
  • 为每项破坏性清理操作保留证据。