# Seed Local Files

> Copy .env.local and other files git doesn't track into every new workspace, so a fresh branch runs without setting it up by hand.

By the end of this guide, every new workspace starts with your `.env.local` and any other local file your app needs. A fresh worktree has everything git tracks and nothing it doesn't, so without seeding it has no `.env.local`, no local certificates and no local config, and the app fails before you've looked at the branch.

## Before you start

You'll need a [configured project](https://testlane.dev/docs/configuration/overview), which we'll call `my-project`, and the files you want in every workspace, like `.env.local`.

## Seed your first files

::steps{level="3"}

### List the files to seed

Add `seed_files` to `[setup]`, with each path relative to the root of the workspace:

```toml [~/.testlane/my-project.toml]
[setup]
run = "pnpm install --frozen-lockfile"
seed_files = [".env.local", "config/local.json"]
```

### Put the files in the seeds directory

Testlane looks for each file in `seeds/<project>/` in your config directory, laid out the way the workspace is:

```
~/.testlane/
  my-project.toml
  seeds/
    my-project/
      .env.local
      config/
        local.json
```

### Open a workspace

```bash
testlane my-project feat/login run dev
```

```
→ fetching origin/feat/login
→ worktree ready: /home/you/dev/testlane/my-project/trees/feat-login
→ seeded .env.local
→ seeded config/local.json
→ running setup
```

Testlane copies the files before it installs anything, so your install step can read them too. Note that a seeded file git doesn't ignore shows up as an untracked change, which makes the workspace `dirty`, so `sync` refuses it and `clean` skips it. We recommend listing every seeded file in the repository's `.gitignore`, as most projects already do for `.env.local`. Keep in mind that seeding is part of setup, so `run`, `exec`, `shell` and `start` seed a workspace, while `checkout` and `code` do only when you add `--setup`.

::

## Seed from a checkout you already have

If you keep your real `.env.local` in a checkout of the project, point `seed_from` at it rather than copying the file into the seeds directory:

```toml [~/.testlane/my-project.toml]
[setup]
seed_files = [".env.local"]
seed_from = "~/dev/my-project"
```

Testlane looks in `seeds/<project>/` first and in `seed_from` second, and copies the first file it finds. So you can keep most files in your checkout and override one or two in the seeds directory.

When it finds a file in neither place, it warns and carries on, so a missing file never stops a command:

```
warning: no seed source for '.env.local' (looked in seeds/my-project and seed_from)
```

## Refresh a seeded file

Seeding never overwrites a file that's already in the workspace, so edits you make there survive the next `run`. To copy a file again, like after you rotate a key, add `--reseed`:

```bash
testlane my-project feat/login run dev --reseed
```

`--reseed` deletes each seeded file in the workspace first, then copies it from its source again. It works on `run`, `exec`, `shell` and `start`.

Note that every path in `seed_files` must be relative and can't contain `..`, so a seed never lands outside the workspace. `testlane config validate` rejects anything else:

```
my-project.toml: setup.seed_files.0: must be a relative path with no '..' segments (got '../x')
```

## Keep secrets safe

Seeds are ordinary files on your disk, and Testlane copies them as they are, without encrypting or hiding anything. So we recommend three things:

- Keep the seeds directory out of every repository you push.
- Where your app allows it, seed a reference to a secret, like a vault key name or the path of a credential helper, rather than the secret itself.
- Read the output of `run --dry-run` before you paste it anywhere, since it prints every value from `[env]`.

## Check your config

Before you rely on seeding, check the project file, since a bad `seed_files` entry stops every command that reads it:

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

```
→ my-project: ok
```

`config validate` lists every schema error in a file at once, like a key it doesn't know or a value out of range. Once those pass, it checks the paths, `seed_files` and `default_command`, so a second run can find more. Without a project name, it checks every project file and prints `→ all project configs valid`.

## Where to go next

Here's where to go from here:

- [Project file](https://testlane.dev/docs/configuration/project-file) has `seed_files`, `seed_from` and the rest of `[setup]`.
- [Refresh a workspace](https://testlane.dev/docs/guides/refresh-a-workspace) shows how to bring a workspace up to date without losing your edits.
- [Troubleshooting](https://testlane.dev/docs/guides/troubleshooting) starts with `doctor` when something doesn't work.
