Guides

Clean Up Workspaces

Remove the workspaces you've finished with, by name or by filter, and tidy up after one was deleted outside Testlane.

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:

FilterPicks
--allEvery workspace of the project
--mergedWorkspaces whose branch is merged into the default branch, checked with git alone
--closedWorkspaces 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-stateWorkspaces 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. clean warns with skipping 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-adopted to 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:

Copyright © 2026