Clean Up Workspaces
By the end of this guide, your machine holds only the workspaces you still need. Every workspace is a full checkout with its own dependencies, so they add up quickly, and clean removes them by name or by filter, always showing you its plan first.
Before you start
You'll need a project with a few workspaces in it, which we'll call my-project. testlane my-project list shows them.
Remove what's merged
See what you have
testlane my-project list
SLUG KIND BRANCH STATUS PORT AGE LAST USED
feat-search branch feat/search clean 4160 3d 2d
pr-42 pr pr/42 clean 4164 1d 1d
feat-login branch feat/login clean 4153 1d 0m
Preview the plan
testlane my-project clean --merged --dry-run
→ fetching origin/main
→ plan:
feat-search (merged, clean, 16 KB)
git -C /home/you/dev/testlane/my-project/repo worktree remove /home/you/dev/testlane/my-project/trees/feat-search
rm -rf /home/you/dev/testlane/my-project/trees/.data/feat-search
feat-search
→ freed 16 KB
--merged picks the workspaces whose branch is merged into origin/<default_branch>. --dry-run prints the plan, the commands clean would run and what it would free, without removing anything. Each line of the plan gives the reason, whether the workspace has changes and how much disk it uses.
Remove them
testlane my-project clean --merged
→ fetching origin/main
→ plan:
feat-search (merged, clean, 16 KB)
Remove 1 workspace(s)? [y/N] y
feat-search
→ freed 16 KB
clean asks before it removes anything, then prints each slug it removed and the space it freed.
Remove workspaces by name
Name the slugs, as list shows them, to remove exactly those workspaces:
testlane my-project clean pr-42 feat-login
To remove one workspace by its ref instead, use rm:
testlane my-project 42 rm
Both stop a process that start left running in the workspace before they remove it.
Remove workspaces by filter
Each filter picks workspaces by what's true of them:
| Filter | Picks |
|---|---|
--all | Every workspace of the project |
--merged | Workspaces whose branch is merged into the default branch, checked with git alone |
--closed | Workspaces whose pull request is closed or merged, checked with gh when it's signed in |
--older-than <age> | Workspaces you haven't used for at least <age>, a number and a unit, s, m, h, d or w, like 90m or 7d |
--prune-state | Workspaces whose directory is gone, as in Tidy up a missing workspace |
Without gh, --closed uses the pull request state Testlane saved when it created each workspace. Without that either, it falls back to --merged, which can pick a branch workspace too, so preview it with --dry-run first.
Filters combine, and a workspace has to match all of them. This removes only the workspaces that are merged and that you haven't used for a week:
testlane my-project clean --merged --older-than 7d
Note that you can name slugs or use filters, but not both in one command, since that's a usage error, E_USAGE (exit 2).
What clean leaves alone
clean skips two kinds of workspace, so it never throws away work you didn't mean to:
- A workspace with uncommitted changes.
cleanwarns withskipping feat-login: worktree is dirty (use --force)and removes the rest. - A working tree you adopted with a path ref. Testlane didn't create it, so filters leave it out. Add
--include-adoptedto include it. Even then, Testlane removes only its own data for it and leaves the directory where it is.
--force removes a workspace with uncommitted changes and throws those changes away. For a branch workspace, it also deletes the local branch.Tidy up a missing workspace
When a workspace's directory is deleted outside Testlane, like with rm -rf or a disk clean-up, Testlane still has an entry for it. list shows it as missing:
SLUG KIND BRANCH STATUS PORT AGE LAST USED
feat-search branch feat/search missing 4160 2m 1m
testlane doctor reports it too, and names the command that fixes it:
WARN project my-project: worktrees: 1 state entry with no live worktree (deleted on disk or unknown to git) — reconcile with `testlane my-project clean --prune-state`
Run that command to drop the entries whose directory is gone:
testlane my-project clean --prune-state --yes
→ plan:
feat-search (missing, state-only, clean, ?)
feat-search
→ freed 1 KB
Once it has removed a workspace Testlane created, clean also runs git worktree prune, so git forgets the missing directory too.
Clean up from a script
clean asks before it removes anything, and when nobody can answer, like in a script or CI, it stops with E_USAGE (exit 2) rather than guess:
error(E_USAGE): refusing to remove 1 workspace(s) without confirmation
hint: pass --yes for non-interactive use
Add --yes to answer for it:
testlane my-project clean --merged --yes
Make it a habit
We recommend a short clean-up once a week, like on a Friday. To see how much disk each workspace uses, testlane my-project list --json --du adds its size in bytes as diskBytes. Then preview the clean-up:
testlane my-project clean --older-than 14d --dry-run
Then remove what's shipped and what you haven't touched for a fortnight:
testlane my-project clean --closed --yes
testlane my-project clean --older-than 14d --yes
Where to go next
Here's where to go from here:
- Project verbs lists every flag of
clean. - Workspaces explains what a workspace holds and where Testlane keeps it.
- Script with Testlane shows how to drive
cleanand the other verbs from scripts.