Refs
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
| Aspect | Refs |
|---|---|
| Position | The second argument, after the project |
| Forms | -, a path, a PR number, pr/<n>, a full commit SHA or a branch name |
| Order | Fixed, and the first form that matches wins |
| Short SHAs | Read as a branch name, never as a commit |
| Force one | --pr <n>, --branch <name> or --path <p>, in place of the ref |
| URLs | A clone or web URL in place of the project, with the ref taken from /pull/<n> or /tree/<branch> |
| Errors | E_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:
| Input | Meaning | Example |
|---|---|---|
- | The last ref you used for this project | testlane my-project - shell |
Starts with /, ./, ../ or ~ | A working tree you already have, adopted | testlane my-project ~/code/hotfix shell |
<n> or #<n> | A pull request | testlane my-project 42 |
pr/<n>, in any case | A pull request | testlane my-project pr/42 |
| 40 lowercase hex characters | A commit, checked out on its own | testlane my-project 1a2b3c… checkout |
| Anything else that's a valid branch name | A branch | testlane 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.
How It Works
The resolve, materialize and act pipeline that every Testlane workspace command runs, and what each step does.
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.