Concepts

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

AspectWorkspace
What it isA git worktree, a block of ports, a data directory and a state entry
Where it livesworktrees_path/<slug>, which defaults to {root}/{project}/trees/<slug>
Portsports 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}
Statusesclean, dirty or missing, plus a PR's state when gh is around
Inspectlist for every workspace, info for one, both with --json
Removerm 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:

~/.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 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:

~/.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:

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:

Copyright © 2026