Create and inventory before mutation
grok worktree create NAME prepares a worktree the way grok -w does without starting a session; without --ref it starts from HEAD plus uncommitted changes, so pass --ref when you need a clean base.
Inventory with grok worktree list --json and narrow by repository when several projects are tracked; in Grok Build 1.0.67 the list covers the registry’s worktrees, unfinished copies, and Grove clones. Use worktree show with an exact ID or path for one candidate, and grok du --json to see what ~/.grok and its worktrees use on disk.
Check Git status, untracked files, branch, HEAD, and any unpushed commits inside the worktree. Grok’s tracking record cannot prove the checkout is disposable.
grok worktree create fix-auth --ref origin/main
grok worktree list --json
grok worktree show ID_OR_PATH
grok du --jsonPreview removal and garbage collection
grok worktree rm accepts one or more IDs and supports --dry-run. grok worktree gc also supports --dry-run, but without --max-age it expires nothing, and it keeps any worktree whose work would not survive. Preview an idle sweep with --max-age 7d --dry-run, then re-resolve the candidates immediately before mutation.
Avoid --force until dirty and unpushed work has been reviewed and preserved. On rm it removes a worktree even when a process, an open session, or unsaved work is inside it; on gc it skips the live-process, open-session, and protected-path guards. Age alone is not evidence that a branch is obsolete.
- Use exact IDs, not broad path globs.
- Capture a diff or commit before removal when retention is required.
- Re-list after cleanup to verify the intended result.
grok worktree gc --max-age 7d --dry-run
grok worktree rm --dry-run IDTreat the database separately
worktree db stats and db path inspect tracking metadata. db rebuild scans the filesystem to reconstruct that database; it changes local indexing state, not Git history.
Use rebuild when tracking is wrong, not as a substitute for Git cleanup. Review scan roots so unrelated repositories are not accidentally enrolled.
Handle Grove clones and recovery explicitly
Grok Build 1.0.67 release help adds Grove surfaces: grok clone lazy-clones a repository through Grove (NFS on macOS, FUSE on Linux) with a fast depth-1 bootstrap unless you pass --full-history. grok worktree detach converts a Grove-projected worktree into a plain git worktree, and rm --keep-store unmounts and forgets a Grove clone while leaving its store on disk.
When the source repository is gone, grok worktree salvage with --out recovers hydrated and dirty files into a plain repository. clean-artifacts purges escape-directory artifact contents that git clean does not remove; list them with --dry-run first because --yes is irreversible. Inspect redirects with worktree redirect list before adding, deleting, fixing up, or unmounting any.
- Salvage before deleting a worktree whose source repository disappeared.
- Treat clean-artifacts --yes and grok du --clean as irreversible deletions.
- The official worktrees page does not document Grove; these commands come from 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