Grok WorldGrok Build CLI field station

GROK BUILD CLI / 17

管理 worktree lifecycle 而不遺失工作

Worktree 是真正 checkout,具有 branch/filesystem state;cleanup command 絕不只是 UI housekeeping。

CHANNELREPOSITORY 隔離 / 進階 / 15 MIN
來源核對日期2026-10-21
ORIGINOFFICIAL DOCS / PRIMARY

Mutation 前先建立與 inventory

grok worktree create NAME 會用與 grok -w 相同的方式建立 worktree,但不啟動 session;未加 --ref 時從 HEAD 加上 uncommitted changes 開始,需要乾淨 base 時請傳入 --ref。

用 grok worktree list --json 做 inventory,多專案時依 repo 縮小;Grok Build 1.0.67 的清單涵蓋 registry 的 worktrees、未完成的 copies 與 Grove clones。用 worktree show + exact ID/path 檢查單一 candidate,並用 grok du --json 查看 ~/.grok 與其 worktrees 的磁碟用量。

在 worktree 內查 Git status、untracked files、branch、HEAD、unpushed commits;tracking record 不能證明可丟棄。

grok worktree create fix-auth --ref origin/main
grok worktree list --json
grok worktree show ID_OR_PATH
grok du --json

預覽 remove 與 GC

grok worktree rm 可接多個 IDs 並支援 --dry-run;gc 也有 --dry-run,但未加 --max-age 時不會讓任何 worktree 過期,並會保留工作無法在別處存續的 worktree。用 --max-age 7d --dry-run 預覽 idle sweep,mutation 前再 resolve candidates。

Dirty/unpushed work 未 review/preserve 前不要 --force:rm 加上它時,即使 process、開啟中的 session 或未保存工作仍在 worktree 內也會移除;gc 加上它則略過 live-process、open-session 與 protected-path guards。Age 不是 obsolete evidence。

  • 使用 exact IDs,不用 broad globs。
  • 需要 retention 時先 diff/commit。
  • Cleanup 後 re-list 驗證。
grok worktree gc --max-age 7d --dry-run
grok worktree rm --dry-run ID

Database 分開處理

worktree db stats/path 檢查 tracking metadata;db rebuild 從 filesystem 重建 database,改的是 local index,不是 Git history。

Tracking 錯誤才 rebuild,不把它當 Git cleanup;review scan roots。

明確處理 Grove clones 與 recovery

Grok Build 1.0.67 release help 新增 Grove 相關指令:grok clone 透過 Grove(macOS 用 NFS、Linux 用 FUSE)lazy clone repository,未加 --full-history 時採快速 depth-1 bootstrap。grok worktree detach 把 Grove-projected worktree 轉成一般 git worktree;rm --keep-store 會 unmount 並移除 Grove clone 的登錄,但把它的 store 留在磁碟上。

Source repository 已不存在時,grok worktree salvage 搭配 --out 會把 hydrated 與 dirty files 救回成一般 repository。clean-artifacts 會清除 git clean 不處理的 escape-directory artifact 內容;--yes 不可逆,先用 --dry-run 列出。新增、刪除、fixup 或 unmount redirect 前,先用 worktree redirect list 檢查。

  • Source repository 消失時,先 salvage 再刪除 worktree。
  • clean-artifacts --yes 與 grok du --clean 都視為不可逆刪除。
  • 官方 worktrees 頁面沒有記載 Grove;這些指令來自 release help。
grok worktree redirect list MOUNT --json
grok worktree clean-artifacts ID_OR_PATH --dry-run
grok worktree salvage ID_OR_PATH --out ../recovered