# 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

| 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:

```bash
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:

```bash
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:

```bash
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":

```bash
testlane my-project - shell
testlane my-project - run dev
```

Testlane records the last ref in its [state directory](https://testlane.dev/docs/concepts/how-it-works#where-testlane-keeps-things). 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:

```bash
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](https://testlane.dev/docs/cli/exit-codes) lists every code and what it means.
