Workspaces and Worktrees
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:
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 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:
[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:
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 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:
.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.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.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.rm.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:
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.