Concepts

How It Works

The resolve, materialize and act pipeline that every Testlane workspace command runs, and what each step does.

Knowing what Testlane does under the hood lets you predict any verb before you run it, and tells you where to look when something goes wrong. This page takes the pipeline from the Introduction and opens up each step. Every command that opens a workspace runs it:

  1. 1Resolve

    resolve(ref)

    Turns the ref you typed into a git target and a slug.

    • Pull request42gets the slugpr-42
    • Branchfeat/logingets the slugfeat-login
    • Commit9fceb02…gets the slugsha-9fceb02d0a
    • Path../my-appgets the slugadopted-my-app-…
  2. 2Materialize

    materialize(workspace)

    Makes a worktree with its dependencies, seed files and ports, or reuses it.

    1. Bare cloneFirst use of a project only
    2. WorktreeNew workspaces only
    3. PortsNew workspaces only
    4. Seed filescheckout and code skip them, unless --setup
    5. SetupSkipped on a cache hit. checkout and code skip it, unless --setup
  3. 3Act

    act(command)

    Opens an editor, runs a command or starts a shell.

    • checkout
    • code
    • run
    • exec
    • shell
    • start
The three steps in detail, with when each sub-step runs.

checkout is the pipeline with nothing to do in the last step, and code, run, exec, shell and start each swap in an act step of their own. sync, diff, info, rm, stop and logs act on a workspace you've already opened, so they never create one.

This page covers:

  • Resolve: how the ref you typed becomes a git target and a slug.
  • Materialize: the clone, the worktree, the ports, the seed files and the cached install.
  • Act: what each verb does once the workspace is ready.
  • Where Testlane keeps things: the directories and files it writes.

At a glance

AspectHow it works
Pipelineresolve(ref) → materialize(workspace) → act(command), for every verb that opens a workspace
CloneOne bare, partial clone per project, at repo_path
WorkspaceOne git worktree per ref, at worktrees_path/<slug>
SlugThe workspace's directory name, like pr-42 or feat-login
PortsA block of ports ports per workspace, the same one each time where it's free
Seed filesCopied in from <config-dir>/seeds/<project>/ or setup.seed_from, never over an existing file
Setupsetup.run, skipped while the files in setup.cache_key haven't changed
ReuseA workspace that exists is reused with no network call, unless you pass --fetch
StateOne JSON file per project, in ${XDG_STATE_HOME:-~/.local/state}/testlane

Resolve

Let's start with the first step. Testlane takes the ref you typed and turns it into a git target: a pull request, a branch, a commit or a working tree you already have, which it adopts. It tries each form in a fixed order and takes the first that matches, and Refs has the order and the flags that force a form.

Resolving a ref also gives the workspace its slug, the name of its directory and of its entry in the state:

Kind of refSlug
Pull requestpr-<n>
BranchThe branch name made safe for a path, like feat-login
Commitsha- and the first 10 characters of the SHA
Adopted pathadopted-, the directory's name and a short hash of its path

A branch's slug lowercases the name and turns every character outside letters, digits, ., _ and - into a -, so feat/login becomes feat-login. When two different branches come out with the same slug, the second gets a short hash on the end, so they never share a directory.

Materialize

Now let's look at the second step, which makes sure the workspace exists and is ready to run. You can run it as often as you like: for a workspace that's already there, it skips the network and prints → worktree ready (reused). Pass --fetch to fetch the ref again anyway.

Bare clone

The first time you use a project, Testlane makes a bare, partial clone of it at repo_path. Every workspace of that project is a git worktree off this one clone, so the second ref costs a fetch rather than a full clone:

→ cloning git@github.com:my-org/my-project.git (bare, partial)

Worktree

For a new workspace, Testlane fetches the ref and adds a worktree for it at worktrees_path/<slug>. A workspace that already exists keeps its worktree, so this step and the next only run the first time:

→ fetching origin/feat/login
→ worktree ready: /home/you/dev/testlane/my-project/trees/feat-login

Ports

Each new workspace gets a block of ports next to each other, as many as the project's ports key asks for, and keeps it for as long as it exists. 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 workspace you remove and open again usually gets the same port, which keeps your bookmarks and OAuth callback URLs working.

Seed files

Testlane copies each file in setup.seed_files into the workspace, from <config-dir>/seeds/<project>/ first and setup.seed_from second. It never overwrites a file that's already there, unless you pass --reseed. This is how .env.local gets into a new workspace without you copying it by hand.

Setup

When [setup] has a run command, Testlane hashes the files that setup.cache_key matches and compares the hash with the one it recorded for this workspace. When they match, it skips the install:

→ setup up to date (cache hit)

When they don't, or the install has never run, it runs the command and records the new hash once it succeeds. A failed install exits with 6 (E_SETUP) and keeps the old hash, so the next command tries again.

Keep in mind that checkout and code skip the seed files and the install, so they stay fast. Pass --setup when you want both. run, exec, shell and start always run it, unless you pass --no-setup.

Act

Next, let's look at the last step, which is the verb you asked for. sync and diff are in the table too, though they work on a workspace you've already opened rather than opening one:

VerbWhat it does
checkoutNothing more: it prints the workspace's path
codeOpens the workspace in your editor
run <name>Runs [commands.<name>] through bash -c
exec -- <argv…>Runs the command you give it, without a shell
shellStarts a shell in the workspace
syncFetches the ref again and resets the worktree to it
diffShows gh pr diff for a PR, or git diff <merge-base>...HEAD

Every process Testlane starts in a workspace gets its variables, like TESTLANE_PATH, TESTLANE_PORT and TESTLANE_BRANCH, along with everything you set in [env]. Environment and templates lists them all.

Where Testlane keeps things

Finally, let's look at where all of this lives on your disk:

LocationWhat's in itDefault
Config directoryThe project files, defaults.toml and the seed files~/.testlane
repo_pathThe bare, partial clone{root}/{project}/repo
worktrees_pathOne directory per workspace{root}/{project}/trees
Data directoryEach workspace's private files, in $TESTLANE_DATA_DIR{worktrees_path}/.data/<slug>
State directoryA JSON file per project: its workspaces, ports, PRs, last ref and the repository config you approved${XDG_STATE_HOME:-~/.local/state}/testlane

The state is Testlane's bookkeeping. It records which workspaces exist, which ports they hold and which ref you used last, which is what - resolves to. When it drifts from what's on disk, like after you delete a workspace's directory by hand, testlane doctor warns you and testlane <project> clean --prune-state removes the entries that are left.

Where to go next

The other Concepts pages go deeper into the first two steps:

  • Refs lists every kind of ref, in the order Testlane tries them.
  • Workspaces and worktrees covers what follows from the worktree model, and the caveats worth knowing.

To see the pipeline run, follow the quick start.

Copyright © 2026