用途
worktree-tidy 是一个用于管理 git worktree 的技能,目标是减少 git worktree 的数量,同时不丢失工作成果。它通过一个脚本引擎(Python 3.9+,仅用标准库)判断哪些 worktree 属于“陈旧”,展示报告由用户决定,脚本在每次移除前重新检查。
主要能力
扫描:不带参数时扫描当前文件夹所在仓库,或配置文件中列出的根目录;支持 --json 输出,支持 --root 指定文件夹下的一级仓库,支持 --repo 指定仓库,支持 --no-remote 跳过拉取/合并请求查询以加快速度。每次扫描会先修剪文件夹已不存在的 worktree 记录,--no-prune 则只报告不修剪。
报告:按仓库分组呈现,先给出可移除数量,再列出保留的 worktree 及每个阻塞原因(Blocker),以及可删除的分支。
移除:只移除脚本报告为可移除且用户确认的路径。移除前先 dry run,确认后加 --yes 实际执行。默认保留分支;仅当用户要求时才加 --delete-branch,且脚本仍会在删除前复查分支的请求已合并或关闭、分支尖端可从其他分支、标签或远程跟踪引用到达(branchSaved)。
事实判定:活动时间不使用索引文件,而是运行 git --no-optional-locks status,避免扫描本身被算作活动。Orca(可选)的固定状态和最后活动时间会被读取,但不会写入 Orca。合并请求通过分支的上游名或本地名,经源 URL 对应的主机 CLI(gh、cnb、glab)查询;CLI 缺失或失败时结果为 unknown,不允许删除分支。分离 HEAD 的 worktree 只有在其 HEAD 提交位于某个分支、标签或远程引用上时才可移除。
保护规则:不可再生的被忽略文件会阻塞移除(因为普通 git worktree remove 可能静默删除被忽略文件),绝不为了移除而丢弃它们。绝不为使 worktree 可移除而提交、暂存或丢弃改动;脏 worktree 只报告给用户处理。密钥类文件(.env、.env.、id_rsa、id_ed25519*、.pem、.key、.p12、.pfx、.keystore、.jks)永不可再生,即使在可再生文件夹内也阻塞移除。
使用方式
设置 TIDY 为脚本路径,然后:
python3 "$TIDY" scan python3 "$TIDY" --json scan --root ~/code python3 "$TIDY" scan --repo . --no-remote python3 "$TIDY" remove <path>... python3 "$TIDY" remove <path>... --yes python3 "$TIDY" remove <path>... --delete-branch --yes
用户明确选择仅因“recent”阻塞的 worktree 手工移除时,在 dry run 和实际移除中都加 --allow-recent;该标志只绕过空闲阈值,不绕过其他阻塞。退出码 1 表示至少一个路径失败,需如实报告每个错误。
配置:可选配置文件位于 $XDG_CONFIG_HOME/worktree-tidy/config.json(默认 ~/.config/worktree-tidy/config.json),字段包括 roots(扫描每个含 .git 目录的一级文件夹)、repos(额外仓库)、days(空闲天数阈值,--days 覆盖)、orca(false 或 --no-orca 停止读取 Orca)、regenerable(自定义可再生名称或路径前缀列表)。
适用场景
适合定期清理一个或多个仓库中积压的 worktree,尤其是在审查拉取请求后回收临时工作树;也适合在多个代码仓库之间统一查看哪些 worktree 可以安全移除、哪些分支可以删除。
限制
脚本只使用普通 git worktree remove,禁止使用 --force、rm -rf 或工具自带的删除命令(如 Orca 的 worktree rm 还会删除分支)。分支删除有严格条件,未知状态不允许删除。不可再生的被忽略文件和密钥文件会阻塞移除。需配置主机 CLI 才能查询合并请求,否则相关状态为 unknown。当日志或计数无法读取时,部分字段为 null。