How It Works
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:
1Resolve
resolve(ref)Turns the ref you typed into a git target and a slug.
- Pull request
42gets the slugpr-42 - Branch
feat/logingets the slugfeat-login - Commit
9fceb02…gets the slugsha-9fceb02d0a - Path
../my-appgets the slugadopted-my-app-…
- Pull request
2Materialize
materialize(workspace)Makes a worktree with its dependencies, seed files and ports, or reuses it.
- Bare cloneFirst use of a project only
- WorktreeNew workspaces only
- PortsNew workspaces only
- Seed files
checkoutandcodeskip them, unless--setup - SetupSkipped on a cache hit.
checkoutandcodeskip it, unless--setup
3Act
act(command)Opens an editor, runs a command or starts a shell.
checkoutcoderunexecshellstart
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
| Aspect | How it works |
|---|---|
| Pipeline | resolve(ref) → materialize(workspace) → act(command), for every verb that opens a workspace |
| Clone | One bare, partial clone per project, at repo_path |
| Workspace | One git worktree per ref, at worktrees_path/<slug> |
| Slug | The workspace's directory name, like pr-42 or feat-login |
| Ports | A block of ports ports per workspace, the same one each time where it's free |
| Seed files | Copied in from <config-dir>/seeds/<project>/ or setup.seed_from, never over an existing file |
| Setup | setup.run, skipped while the files in setup.cache_key haven't changed |
| Reuse | A workspace that exists is reused with no network call, unless you pass --fetch |
| State | One 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 ref | Slug |
|---|---|
| Pull request | pr-<n> |
| Branch | The branch name made safe for a path, like feat-login |
| Commit | sha- and the first 10 characters of the SHA |
| Adopted path | adopted-, 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:
| Verb | What it does |
|---|---|
checkout | Nothing more: it prints the workspace's path |
code | Opens the workspace in your editor |
run <name> | Runs [commands.<name>] through bash -c |
exec -- <argv…> | Runs the command you give it, without a shell |
shell | Starts a shell in the workspace |
sync | Fetches the ref again and resets the worktree to it |
diff | Shows 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:
| Location | What's in it | Default |
|---|---|---|
| Config directory | The project files, defaults.toml and the seed files | ~/.testlane |
repo_path | The bare, partial clone | {root}/{project}/repo |
worktrees_path | One directory per workspace | {root}/{project}/trees |
| Data directory | Each workspace's private files, in $TESTLANE_DATA_DIR | {worktrees_path}/.data/<slug> |
| State directory | A 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.