Concepts

Refs

Every kind of ref Testlane accepts, the order it tries them in, and how to force the one you mean.

A ref tells Testlane what you want to run: a pull request, a branch, a commit or a working tree you already have. It's the second argument of every workspace command, so you can paste a PR number from a notification or a branch name from a chat and get a workspace for it:

testlane <project> <ref> [verb]

This page covers:

  • Resolution order: the forms Testlane tries, and which one wins.
  • Forcing a form: the flags for a ref that could be read two ways.
  • URL form: a link in place of the project and the ref.
  • Adopting a checkout: running Testlane in a working tree you already have.
  • The last-used ref: coming back to what you had open a moment ago.
  • When resolution fails: what the error tells you.

At a glance

AspectRefs
PositionThe second argument, after the project
Forms-, a path, a PR number, pr/<n>, a full commit SHA or a branch name
OrderFixed, and the first form that matches wins
Short SHAsRead as a branch name, never as a commit
Force one--pr <n>, --branch <name> or --path <p>, in place of the ref
URLsA clone or web URL in place of the project, with the ref taken from /pull/<n> or /tree/<branch>
ErrorsE_RESOLVE, exit code 4

Resolution order

Let's start with how Testlane reads a ref. It tries these forms in order and takes the first one that matches:

InputMeaningExample
-The last ref you used for this projecttestlane my-project - shell
Starts with /, ./, ../ or ~A working tree you already have, adoptedtestlane my-project ~/code/hotfix shell
<n> or #<n>A pull requesttestlane my-project 42
pr/<n>, in any caseA pull requesttestlane my-project pr/42
40 lowercase hex charactersA commit, checked out on its owntestlane my-project 1a2b3c… checkout
Anything else that's a valid branch nameA branchtestlane my-project feat/login code

Quote #<n> in your shell, as in testlane my-project '#42', since an unquoted # starts a comment there.

Note that Testlane never reads a short SHA as a commit. Seven hex characters could also be a branch name, so it takes them as one, and fetching that branch fails. Pass all 40 characters for a commit.

Forcing a form

Now let's look at a ref that could be read two ways, like a branch called 42, or one whose name is 40 hex characters. Three flags skip the table above and take the value as the form they name:

testlane my-project --pr 42 code       # 42 is a PR
testlane my-project --branch 42 code   # 42 is a branch called "42"
testlane my-project --path ./here shell # ./here is a working tree to adopt

The flag takes the place of the ref, so you don't pass one as well.

URL form

Next, let's look at links. You can pass a clone URL or a web URL in place of the project's name, and Testlane finds the project whose repo has the same host, owner and repository. SSH and HTTPS URLs match each other, and the .git on the end is optional.

In an HTTPS URL, a /pull/<n> or /tree/<branch> part becomes the ref:

testlane https://github.com/my-org/my-project/pull/42 code
testlane https://github.com/my-org/my-project/tree/feat/login diff
testlane git@github.com:my-org/my-project.git 42 code      # the ref comes after an SSH URL

So you can paste the link someone sent you, without remembering what you named the project. When no project's repo matches, Testlane exits with E_RESOLVE and lists the projects you've set up.

Adopting a checkout

Next, let's look at paths. A path doesn't create a worktree: Testlane adopts the working tree that's already there and runs your commands in it, with the same variables, ports and commands as any other workspace:

testlane my-project ~/code/my-project-hotfix shell

The path must exist and be a git working tree. clean leaves adopted workspaces out unless you pass --include-adopted, and even then it only removes their state entry and data directory. It never deletes the working tree or any of its branches, since Testlane didn't create them.

The last-used ref

Then there's -, which stands for the last ref you used with that project. It's the shortcut for "the thing I had open a moment ago":

testlane my-project - shell
testlane my-project - run dev

Testlane records the last ref in its state directory. When a project has none yet, it exits with E_RESOLVE:

error(E_RESOLVE): no last-used ref for 'my-project'

When resolution fails

Finally, let's look at what happens when a ref doesn't resolve. Testlane exits with code 4 (E_RESOLVE), and the error names the problem:

testlane my-project no/such/branch checkout
→ fetching origin/no/such/branch
error(E_RESOLVE): branch 'no/such/branch' does not exist on origin
hint: check the name, or push the ref first

Exit codes lists every code and what it means.

Copyright © 2026