# 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

::steps{level="3"}

### See what you have

```bash
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

```bash
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

```bash
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:

```bash
testlane my-project clean pr-42 feat-login
```

To remove one workspace by its ref instead, use `rm`:

```bash
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](#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:

```bash
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.

::warning
`--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:

```bash
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:

```bash
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:

```bash
testlane my-project clean --older-than 14d --dry-run
```

Then remove what's shipped and what you haven't touched for a fortnight:

```bash
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](https://testlane.dev/docs/cli/project-verbs#clean) lists every flag of `clean`.
- [Workspaces](https://testlane.dev/docs/concepts/workspaces) explains what a workspace holds and where Testlane keeps it.
- [Script with Testlane](https://testlane.dev/docs/guides/script-with-testlane) shows how to drive `clean` and the other verbs from scripts.
