AI 编码代理把硬盘吃爆:一份只删“安全 worktree”的 Git 清理脚本

👉 工具网址:https://git–a.com/

最近开发者社区里讨论很多:Claude Code、Codex、Cursor 这类 AI 编码代理并行干活时,会在你电脑里留下大量 Git worktree,有些人的 Mac 硬盘一夜之间被吃掉几 TB。

听起来很夸张,但真正麻烦的不是“怎么释放空间”,而是:哪些目录能安全删,哪些删了可能丢代码。

worktree 为什么会把硬盘塞满?

你可以把 Git worktree 理解成“主仓库的分身目录”。

一个项目原本有一个主目录。为了让 AI 代理同时做不同任务,比如一个修登录 bug,一个改支付逻辑,一个补测试,就会用:

git worktree add ../wt-fix-login

这样每个任务都有独立目录,互不干扰。

问题也在这里:每个 worktree 都是一个完整工作区。代理会在里面安装依赖、跑构建、生成缓存,例如:

  • node_modules
  • target/
  • .build
  • DerivedData
  • iOS 模拟器镜像
  • 各种临时数据库或日志

10 个代理各开一个 worktree,就可能变成 10 份依赖和构建缓存。更糟的是,AI 代理创建目录很积极,删除目录很保守,因为它不确定这个任务是不是已经安全保存。

所以硬盘就这样被堆满。

怎样判断一个 worktree 可以安全删除?

一个 worktree 只有在“里面的东西已经在别处也存在”时,才适合删。

主要有三个条件:

  • 没有未提交或新产生的文件。 可以用 git status --porcelain --untracked-files=all 看,输出为空才安全。
  • 没有只在本地存在的提交。 可以用 git rev-list --count HEAD --not --remotes 看,结果是 0,说明当前分支提交都已经推到远端。
  • 被 .gitignore 忽略的文件里没有重要东西。 node_modules 通常可以重建,但 .env、本地数据库、测试数据也可能被忽略,这些可能只存在于本地。

另外,如果你曾经手动删除过目录,但没有用 git worktree remove,Git 里可能还留着记录,可以用:

git worktree prune

来清理这些失效记录。

一个默认只预览的清理脚本

下面这个脚本的核心思路很简单:

  • 默认不删除,只列出所有副 worktree,并告诉你能不能删。
  • 显示每个目录大小,方便你先处理最占空间的。
  • 标记 SAFE:没有未提交改动,也没有只在本地的提交。
  • 标记 KEEP:可能还有没保存的代码,不能删。
  • 只有加上 --delete,才会真正删除 SAFE 的 worktree。
  • 它不会使用 git worktree remove --force,不会强行删。

建议先完整跑一次,不删任何东西,看清楚哪些被标记为 SAFE。

#!/usr/bin/env bash
# safe-worktree-cleanup.sh: list agent worktrees, delete only the ones that hold nothing unique.
# 中文说明:这个脚本用于列出 AI 代理创建的 Git worktree,只删除“没有独占内容”的目录。
# Usage: bash safe-worktree-cleanup.sh [--delete]   (run anywhere inside the repo)
# 用法:在仓库目录里任意位置运行;不加 --delete 时只是预览。
# Dry run by default. Needs git 2.17+.
# 默认不会删除任何东西;建议先跑一次预览,确认 SAFE/KEEP 后再加 --delete。
set -uo pipefail
DELETE=0; [[ "${1:-}" == "--delete" ]] && DELETE=1
# 参数是 --delete 时,才真正执行删除。
git fetch -q --all --prune || echo "warning: fetch failed, 'pushed' is judged from old remote refs"
# 拉取远端信息,判断本地提交是否已经推到远端;网络失败时也会继续,但提示可能用旧数据。
first=1
git worktree list --porcelain | sed -n 's/^worktree //p' | while IFS= read -r wt; do
  if (( first )); then first=0; continue; fi          # the first entry is the main checkout
  # 第一行通常是你的主仓库目录,这里不动它。
  if [[ ! -d "$wt" ]]; then echo "GONE  $wt (folder already deleted; prune will drop it)"; continue; fi
  # 目录不存在时,只报告;最后用 prune 清理 Git 里的残留记录。
  size=$(du -sh "$wt" 2>/dev/null | cut -f1)
  # 统计这个 worktree 有多大,方便先看磁盘杀手。
  changed=$(git -C "$wt" status --porcelain --untracked-files=all | wc -l | tr -d ' ')
  # 统计未提交改动 + 未跟踪文件;不是 0 就可能有没保存的代码,标记为 KEEP。
  local_only=$(git -C "$wt" rev-list --count HEAD --not --remotes 2>/dev/null || echo "?")
  # 统计“当前分支有、但所有远端都没有”的提交;不是 0 就删了可能丢提交。
  ignored=$(git -C "$wt" status --porcelain --ignored=matching | grep -c '^!!')
  # 统计被 .gitignore 忽略但存在的文件数量;可能包含 node_modules、build、.env、本地数据。
  if [[ "$changed" == "0" && "$local_only" == "0" ]]; then
    echo "SAFE  $size  $wt  ($ignored ignored paths will be deleted too)"
    if (( DELETE )); then git worktree remove "$wt" && echo "      removed"; fi
  else
    echo "KEEP  $size  $wt  ($changed changed files, $local_only commits on no remote)"
  fi
done
git worktree prune
# 最后清理已经不存在目录的旧 worktree 记录。

运行后,输出可能长这样:

SAFE  2.1G  ../wt-fix-login   (3 ignored paths will be deleted too)
KEEP  1.8G  ../wt-refactor    (4 changed files, 0 commits on no remote)
KEEP  640M  ../wt-tests       (0 changed files, 2 commits on no remote)

意思是:

  • ../wt-fix-login 看起来可以安全删除。
  • ../wt-refactor 里有 4 个未保存改动,不能删。
  • ../wt-tests 没有未提交文件,但有 2 个提交只存在本地,没推到远端,也不能删。

如果你看到 KEEP,可以选两条路:

  • 如果这个分支还有用,就把代码推到远端,比如 git push。
  • 如果确认工作已经不要了,再手动处理。

如果看到某个目录有很多 ignored paths,先别急着删,可以进入那个目录检查:

git status --ignored

尤其要警惕 .env、本地 SQLite 文件、测试数据、构建出来的临时配置。

怎么避免以后再堆满?

几个习惯很有用:

  • 一个任务一个 worktree,并用任务命名。 比如 wt-fix-login、wt-pay-refund,一周后还能看懂。
  • 尽早把分支推远端。 只要提交已经在远端,本地目录就更容易变成“可抛弃缓存”。
  • 构建缓存尽量共享。 比如共享 pnpm store、设置 CARGO_TARGET_DIR、复用构建目录,不要每个 worktree 都复制一份。
  • 定期跑清理脚本。 不要等硬盘爆红才随便删目录。

如果多个 AI 代理同时写一个仓库,还有什么方案?

原始素材里也提到一个产品:Git A。它面向“很多 AI 代理在同一个仓库工作”的场景。作者披露自己参与 Git A 开发,但前面给出的脚本本身是普通 Git 能力,不依赖它的产品。

Git A 的思路是:代理未保存的改动、还没推远的提交会被自动保存,避免因为断电、会话中断、额度用完、误删本地目录而丢失。它还有一个方向是所有代理最终汇到同一主分支,减少传统 Git 并行推送时的冲突和失败率。

不过对大多数单人开发者来说,先把普通 Git worktree 管理好,就已经能解决硬盘爆炸和误删焦虑了。

直达网址:https://git–a.com/

more