# Project File

> Every key a Testlane project file takes, from the repository to setup, with its type, its default and what it's for.

A project file tells Testlane where a project's repository is and how to get a workspace of it running, so you can open any of its refs with one command. Reach for this page when you add a project or want to know what a key does. Each project has one file at `<config-dir>/<project>.toml`, and a repository can ship a `.testlane.toml` that sets some of the same keys for everyone. Only `repo` is required:

```toml [~/.testlane/my-project.toml]
repo = "git@github.com:my-org/my-project.git"
default_branch = "main"
editor = "zed"
ports = 2
base_port = 5700

[setup]
run = "pnpm install --frozen-lockfile"
cache_key = ["pnpm-lock.yaml", "**/package.json"]
seed_files = [".env.local"]

[env]
PORT = "{port}"
API_PORT = "{port+1}"

[commands.dev]
run = "pnpm dev"
```

## At a glance

| Key                 | Type                  | Default                                        | What it's for                                                              |
| ------------------- | --------------------- | ---------------------------------------------- | -------------------------------------------------------------------------- |
| `repo`              | string                | Required                                       | The repository's clone URL, over SSH or HTTPS                              |
| `repo_path`         | path                  | `{root}/{project}/repo`                        | Where Testlane keeps the project's clone                                   |
| `worktrees_path`    | path                  | `{root}/{project}/trees`                       | Where the workspaces go                                                    |
| `default_branch`    | string                | Detected from `origin` on the first clone      | The branch `diff` compares against and `clean --merged` checks             |
| `editor`            | string                | `defaults.editor`, then `code`                 | What `code` opens a workspace in                                           |
| `default_command`   | string                | `defaults.default_command`, then `code`        | What `testlane <project> <ref>` does with no verb                          |
| `ports`             | integer, 1 to 10      | `1`                                            | How many ports each workspace gets                                         |
| `base_port`         | integer, 1024 to 65000 | Derived from the project's name               | Where the project's ports start                                            |
| `setup.run`         | string                | None                                           | The install command for a workspace                                        |
| `setup.cache_key`   | list of globs         | `[]`                                           | The files whose changes make setup run again                               |
| `setup.seed_files`  | list of paths         | `[]`                                           | Files to copy into a new workspace                                         |
| `setup.seed_from`   | path                  | None                                           | A second place to copy seed files from                                     |
| `env`               | table of strings      | `{}`                                           | Environment variables for commands, setup and hooks                        |
| `commands.<name>`   | table                 | None                                           | Named commands for `run` and `start`                                       |
| `hooks.<name>`      | string                | None                                           | Scripts that run at four points in a workspace's life                      |

`{root}` is `root` from `defaults.toml`, and `{project}` is the project's name. A path may start with `~` for your home directory, and Testlane expands nothing else in it, like `$HOME`. We recommend absolute paths or paths that start with `~`, since a relative one is read from the directory you run Testlane in.

A repository's `.testlane.toml` may set `default_command`, `ports`, `setup.run`, `setup.cache_key`, `setup.seed_files`, `[env]`, `[commands]` and `[hooks]`. The other keys describe your machine, so they're user-only: they go in your project file, and Testlane rejects them in the repository's file. Where both files set a key, yours wins, as [Ship a config with your repo](https://testlane.dev/docs/guides/ship-a-config-with-your-repo#override-a-key) explains. The tables below say which keys a repository may set.

## Repository keys

These say where the project's code comes from and where its copies go on disk.

| Key              | Type   | Default                                   | In `.testlane.toml` |
| ---------------- | ------ | ----------------------------------------- | ------------------- |
| `repo`           | string | Required                                  | User-only           |
| `repo_path`      | path   | `{root}/{project}/repo`                   | User-only           |
| `worktrees_path` | path   | `{root}/{project}/trees`                  | User-only           |
| `default_branch` | string | Detected from `origin` on the first clone | User-only           |

`repo` is the URL Testlane clones, and it's also how it knows which project a pull request URL belongs to. Without `root` in `defaults.toml`, set `repo_path` and `worktrees_path` yourself, since there's nothing to put them under. `worktrees_path` can't be inside `repo_path`.

We recommend setting `default_branch`. Testlane only looks it up from `origin` in the run that first clones the repository, and it doesn't keep what it found, so later runs don't know it. Without it, `diff` falls back to a plain `git diff` of the working tree rather than showing everything since the ref left the default branch, and `clean --merged` checks for merged branches against `main`.

## Behaviour keys

These shape what Testlane does with a workspace once it has one.

| Key               | Type                   | Default                                  | In `.testlane.toml` |
| ----------------- | ---------------------- | ---------------------------------------- | ------------------- |
| `editor`          | string                 | `defaults.editor`, then `code`           | User-only           |
| `default_command` | string                 | `defaults.default_command`, then `code`  | Allowed             |
| `ports`           | integer, 1 to 10       | `1`                                      | Allowed             |
| `base_port`       | integer, 1024 to 65000 | `3000 + (hash of the name % 40) × 100`   | User-only           |

`editor` is a preset name, like `zed` or `nvim`, or a template of your own, and [Editors](https://testlane.dev/docs/configuration/editors) lists them. `default_command` is one of the verbs `checkout`, `code`, `shell`, `diff` and `info`, or the name of one of the project's `[commands]`, and `config validate` rejects anything else. [Commands and Hooks](https://testlane.dev/docs/configuration/commands-and-hooks#default-command) shows it at work.

`ports` is how many ports in a row each workspace gets, from `{port}` to `{port+N}`. Each project picks its workspaces' ports from a window that starts at `base_port` and is `100 × ports` wide. The derived `base_port` puts projects 100 apart, which fits the default of one port each, so if you raise `ports`, we recommend setting `base_port` too, to keep the project's window clear of the others. [Run dev servers in parallel](https://testlane.dev/docs/guides/run-dev-servers-in-parallel) walks through a setup with two ports.

## `[setup]`

`[setup]` gets a fresh workspace ready to run: it copies in your seed files, then runs your install command. It runs before `run`, `exec`, `shell` and `start`, unless you pass `--no-setup`, and `checkout` and `code` run it when you pass `--setup`. Leave the table out and nothing is copied or installed.

```toml [~/.testlane/my-project.toml]
[setup]
run = "pnpm install --frozen-lockfile"
cache_key = ["pnpm-lock.yaml", "**/package.json"]
seed_files = [".env.local"]
seed_from = "~/dev/my-project"
```

| Key          | Type          | What it does                                                                                     | In `.testlane.toml` |
| ------------ | ------------- | ------------------------------------------------------------------------------------------------ | ------------------- |
| `run`        | string        | The install command, run with `bash -c` in the workspace, with [template variables](https://testlane.dev/docs/configuration/environment-and-templates) | Allowed |
| `cache_key`  | list of globs | The files Testlane hashes, relative to the workspace, to decide whether `run` needs to run again | Allowed |
| `seed_files` | list of paths | Paths relative to the workspace, with no `..`, to copy in when they aren't there yet             | Allowed |
| `seed_from`  | path          | A directory to copy seed files from when `seeds/<project>/` doesn't have them                    | User-only |

`cache_key` is what makes the second `run` in a workspace fast. Testlane hashes every file its globs match, leaving out `node_modules/` and `.git/`, and skips `run` while the hash is the same as at the last install that worked. Without a `cache_key`, the hash never changes, so `run` installs once per workspace. A failed install keeps the old hash, so the next command tries again.

Seed files never overwrite a file that's already in the workspace, unless you pass `--reseed`. [Seed local files](https://testlane.dev/docs/guides/seed-local-files) walks through them.

## `[env]`, `[commands]` and `[hooks]`

These three tables have pages of their own, since each does a lot. A repository's `.testlane.toml` may set all three:

- **`[env]`** sets environment variables for every command, setup and hook in a workspace, with template values like `"{port}"`. See [Environment and Templates](https://testlane.dev/docs/configuration/environment-and-templates).
- **`[commands.<name>]`** gives `run` and `start` something to run, with a `cwd` and an `env` of its own. See [Commands and Hooks](https://testlane.dev/docs/configuration/commands-and-hooks).
- **`[hooks]`** runs your scripts after checkout, before a command, after `sync` and before a removal. See [Commands and Hooks](https://testlane.dev/docs/configuration/commands-and-hooks#hooks).

## How Testlane checks the file

Testlane reads a project file strictly: a key it doesn't know is an error, not something it skips. That way a typo, like `worktree_path` for `worktrees_path`, stops you straight away instead of quietly doing nothing. Check a file after you change it:

```bash
testlane config validate my-project
```

```
my-project.toml: ports: Number must be less than or equal to 10
my-project.toml: (root): Unrecognized key(s) in object: 'worktree_path'
```

Testlane lists every problem in the file in one run, then exits `3` (`E_CONFIG`). Any other command that loads a broken file stops with `E_CONFIG` too.

A repository's `.testlane.toml` is checked as strictly. Testlane checks it when it reads it from the default branch, in `config trust`, `config add` or a command that checks out a workspace, and it names a user-only key and the file to move it to:

```
error(E_CONFIG): my-project:.testlane.toml: editor: user-only key; set it in my-project.toml
```

Keep in mind that `config validate` doesn't read the default branch, so it checks only the copy of the repository's file you've approved.
