# Workspaces and Worktrees

> What a Testlane workspace is, how its ports and data directory keep it apart from the others, and the git worktree caveats worth knowing before you hit them.

A workspace lets you keep a ref open and running next to your own work, and next to as many other refs as you like. Each one is a git worktree with its own ports, a private data directory and an entry in Testlane's state that ties them together.

Testlane keeps one **bare, partial clone** per project and makes one **git worktree** per ref. That's the whole model, and most of how Testlane behaves follows from it, the handy parts and the awkward ones.

This page covers:

- **Why worktrees:** what the model gives you.
- **Port isolation:** how two workspaces run side by side.
- **The data directory:** where a workspace keeps files that aren't in git.
- **Inspecting workspaces:** how to see what you have.
- **Known caveats:** what follows from worktrees, before you run into it.

## At a glance

| Aspect         | Workspace                                                                          |
| -------------- | ---------------------------------------------------------------------------------- |
| What it is     | A git worktree, a block of ports, a data directory and a state entry               |
| Where it lives | `worktrees_path/<slug>`, which defaults to `{root}/{project}/trees/<slug>`         |
| Ports          | `ports` per workspace, from 1 to 10 with 1 by default, in `$TESTLANE_PORT` and `{port}` |
| Data directory | `{worktrees_path}/.data/<slug>`, in `$TESTLANE_DATA_DIR` and `{data_dir}`          |
| Statuses       | `clean`, `dirty` or `missing`, plus a PR's state when `gh` is around               |
| Inspect        | `list` for every workspace, `info` for one, both with `--json`                     |
| Remove         | `rm` for one, `clean` for several                                                  |

## Why worktrees

Let's start with what worktrees give you. A worktree is a real directory of its own that shares its git objects with one clone, so you can:

- Keep five branches open at once without five full clones on disk.
- Leave your own checkout alone, with no stashing to review someone else's branch.
- Run several dev servers at the same time, each on its own port.

## Port isolation

Now let's look at how two workspaces run side by side. Each workspace gets a block of ports next to each other, as many as the project's `ports` key asks for, from 1 to 10 with 1 by default. The first is `$TESTLANE_PORT` in the environment and `{port}` in your config. The rest are `$TESTLANE_PORT_1`, `$TESTLANE_PORT_2` and so on, and `{port+1}`, `{port+2}` and so on:

```toml [~/.testlane/my-project.toml]
ports = 2

[env]
PORT = "{port}"
API_PORT = "{port+1}"
```

Testlane picks the first block from a hash of the slug, inside the project's window above `base_port`, and only tries the next block when that one is taken or in use. So a branch usually keeps the same port from one session to the next. [Run dev servers in parallel](https://testlane.dev/docs/guides/run-dev-servers-in-parallel) walks through a working setup.

## The data directory

Next, let's look at where a workspace keeps files that don't belong in git. Every workspace gets `$TESTLANE_DATA_DIR`, a private directory outside the worktree at `{worktrees_path}/.data/<slug>`. We recommend it for anything that would otherwise clutter `git status`, like SQLite files, upload directories and caches:

```toml [~/.testlane/my-project.toml]
[env]
DATABASE_URL = "file:{data_dir}/dev.db"
```

The data directory goes when the workspace does.

## Inspecting workspaces

Then let's look at how to see what you have. `list` shows every workspace of a project, and `info` shows one in detail:

```bash
testlane my-project list
testlane my-project feat/login info
testlane my-project feat/login info --du   # with the disk it uses
```

```
slug: feat-login
kind: branch
ref: feat/login
branch: feat/login
path: /home/you/dev/testlane/my-project/trees/feat-login
ports: 4153
status: clean
created: 2026-07-25T05:51:38.363Z
last used: 2026-07-25T05:51:38.827Z
```

Both take `--json` for scripts, and `list --json --du` adds each workspace's disk use as `diskBytes`. [Script with Testlane](https://testlane.dev/docs/guides/script-with-testlane) shows what you can build on them.

## Known caveats

Finally, let's look at the sharp edges. These follow from how git worktrees work, so they're not bugs Testlane can hide, but knowing them can save you an afternoon:

::accordion
  :::accordion-item{label="In a worktree, .git is a file, not a directory"}
  Inside a worktree, `.git` is a file that points back at the clone. Tools that expect a `.git` directory, like some Docker volume setups and older shell scripts, can trip over it.
  :::

  :::accordion-item{label="core.hooksPath and husky can point the wrong way"}
  A repository that sets a relative hooks path, as husky does, can have it resolve wrongly from a worktree, and `pnpm install` can try to install hooks into the bare clone. `testlane doctor` warns when `core.hooksPath` is set, and leaves your repository as it is.
  :::

  :::accordion-item{label="A partial clone fetches what it needs as it goes"}
  The first checkout of a worktree, and a `diff` across trees Testlane hasn't fetched yet, need a network connection. That's the trade for never downloading history you won't read, so working offline does less.
  :::

  :::accordion-item{label="A branch can only be checked out once"}
  Git won't check out the same branch in two worktrees. When that happens, Testlane stops with an error that says the branch is already checked out in another workspace, and suggests using that one or removing it with `rm`.
  :::

  :::accordion-item{label="Deleting a workspace by hand leaves its metadata behind"}
  Removing a workspace's directory with `rm -rf` leaves git's worktree metadata and Testlane's state entry behind. `list` then shows the workspace as `missing`, and `testlane doctor` warns about it:

  ```
  SLUG        KIND    BRANCH      STATUS   PORT  AGE  LAST USED
  feat-login  branch  feat/login  missing  4153  2m   1m
  ```

  To clear what's left, run `clean` with `--prune-state`:

  ```bash
  testlane my-project clean --prune-state --yes
  ```

  We recommend removing workspaces with `testlane <project> <ref> rm` or `clean` in the first place, since they tidy up both.
  :::
::
