> Switchyard docs. Every page, as markdown, is listed at https://switchyard.so/llms.txt

# Make checks and clones start faster

Shorten the time before a check's command starts, and the time an agent waits for its clone.

**You will have:** checks that check out only what they read, passes that are reused, and clones that download only what the machine lacks.
**Works with:** `.yard/rules.toml`, `yard`, plain Git. Switchyard turns on starts from a saved disk for a project when you ask.

Each section is one change. Make the changes that fit your repository, in any order. [Write rules and checks](/docs/rules) explains every key of the rules file used here.

## Before you start

- A project with at least one check that runs on Switchyard's machines. A check that waits for GitHub's checks starts on GitHub, and nothing here changes it.
- A project admin, to save rules and change settings: an owner or admin signed in, or the project admin key.

## Measure a check's start

Read how long each part of a check's start took.

```sh
yard status --json
```

Each check that ran on a Switchyard machine carries `stages`, in milliseconds, under `mergeQueue.testBuilds[].checks[]`; `yard check log --json` prints it too: `stopMs` is the stop of the machine before it, `startMs` the machine's start, `networkMs` the network filter, `treeMs` the checkout, `cacheMs` the build cache, and `launchMs` the command's launch. A large `treeMs` means that the checkout is the part to shorten.

A check is billed for the time its command runs. The time before the command starts is not billed.

## Check out only what a check reads

Without `checkout`, a check's machine gets the whole tree. Name the files or folders that the check reads, and the machine gets only those.

```toml
[[check]]
name = "api tests"
command = "cd services/api && npm ci && npm test"
checkout = ["services/api", "packages/shared"]
skeleton = true
```

- `checkout` takes one to sixteen files or folders, without wildcards. A path that the commit does not have fails the check by name.
- `skeleton = true` adds the top-level files and every build manifest outside the list, such as `package.json` and lockfiles. A monorepo's build tools then see every package while the sources stay out.

A check with `checkout` tests only the files it reads. A change to any other file needs another check that reads it, or an `[[unchecked]]` table. [Say which paths need no check](/docs/rules#step-3-say-which-paths-need-no-check) explains the hold.

## Let a check reuse its pass

A check that reuses a pass starts no machine and costs nothing.

1. Give the check `paths`: the files and folders it reads. A test build that changes nothing under them reuses the check's pass.
2. Pin what the command downloads, with a lockfile. A pass on exactly the same tree is then reused for good. [Reuse a pass](/docs/rules#reuse-a-pass) says when to set `cache` instead.

```toml
[[check]]
name = "web build"
command = "npm ci && npm run build"
paths = ["apps/web", "package-lock.json"]
```

## Keep Git's file contents out of the checkout

By default, the `.git` folder of a check's checkout holds the commit and its trees, and no file contents. `git status`, `git rev-parse`, `git ls-files` and `git log` of the commit work.

Set `git = "full"` only on a check whose command reads file contents from Git, such as `git diff` after the command changed a file. The machine then also writes every checked-out file into `.git`, which takes longer.

```toml
[[check]]
name = "generated files are current"
command = "npm ci && npm run generate && git diff --exit-code"
git = "full"
```

## Keep the checks that run ahead

Two project settings run a task's checks before the merge queue needs them. Both are on by default. Keep them on unless you have a reason.

- `checks-before-submit`: a task's checks run on its latest pushed commit once 30 seconds pass with no push. A pass is then ready when the agent submits. Such a run is billed only when the submit reuses its pass. A project starts at most 30 of these check runs in an hour.
- `checks-while-reviewing`: a task that waits for a person's review runs its checks while it waits, so an approval can merge at once.

`yard settings` prints the project's settings. `yard settings set checks-before-submit on` turns the first on again.

## Keep the build cache on

Checks keep their package downloads between runs when the project's `build-cache` setting is on, which is the default. The cache is keyed by the lockfiles, so commit a lockfile at the repository root or at each checkout root. [Read a failed check](/docs/rules#read-a-failed-check) has the cache's sizes.

## Start checks from a saved disk

A check can start from a saved disk: a copy of a machine that already holds main's checkout. The check's machine then fetches only the files that changed since the disk was saved, where a fresh setup unpacks the whole tree.

Starts from a saved disk are off by default. Switchyard turns them on for one project at a time. To ask, write to [support@switchyard.so](/contact) with the project's id. You change nothing in the rules file.

Once they are on, a check starts from a saved disk when all of these are true:

- the check has no `checkout` list, so it takes the whole tree;
- the check does not set `git = "full"`;
- the check starts no `services`.

Every other check takes a fresh setup, as before. So does any check whose saved disk does not match its commit exactly. [Guarantees](/docs/guarantees#a-check-runs-on-exactly-its-commit) states what Switchyard promises about a saved disk, and [limits](/docs/limits#checks-and-the-merge-queue) says how long a saved disk can stay after its project is deleted.

## Make a clone faster

A task's clone is plain Git, so three things shorten it.

**Start the task from inside a clone of the repository.** Run `yard branch new` in any clone of the repository on that machine. The new clone borrows the objects that the first clone already has, and downloads only what the machine lacks.

```sh
yard branch new 'Add sales tax to cart totals' --dir sales-tax
```

**Use the clone you are in.** `--here` checks the task out in the current repository and clones nothing. It is refused in a clone that already holds a task.

```sh
yard branch new 'Add sales tax to cart totals' --here
```

**With plain Git, clone less.** A task's remote serves shallow, blob-less and sparse clones.

```sh
git -c http.extraHeader="Authorization: Bearer <git key>" clone --depth 1 --filter=blob:none --sparse --branch <git branch> <git remote> work
```

- `--depth 1` fetches the task's last commit without its history.
- `--filter=blob:none` fetches a file's contents only when Git needs them.
- `--sparse` checks out only the top-level files. `git sparse-checkout set <folder>` then adds the folders the agent works in.

A push from such a clone lands like any other push. Switchyard's own load runs clone tasks this way.

## Wake the Git engine ahead of work

A project's Git engine stops when it is idle. The first clone, push or check after that waits while the engine loads the repository from storage.

Wake the engine before a batch of agents starts. A project admin does this.

```sh
yard engine wake --wait
```

`--wait` stays until the engine is awake. MCP: `yard_wake_engine`.

Two project settings wake the engine without a command. Both are on by default for a repository above 1 GB.

- `yard settings set wake-on-open on`: the engine wakes when someone opens the project.
- `yard settings set warm-hour on`: the engine stays awake for an hour after the last push, task, check or open.

An engine that is awake is billed as engine time. [Pay and set a spending limit](/docs/billing#engine-time-and-machine-size) says how engine time is billed.

## Verify

Submit a task, then run `yard status --json` again. Compare `treeMs` of the same check with the first reading.

## Next

- [Write rules and checks](/docs/rules): every key of a `[[check]]` table.
- [Limits](/docs/limits): machine sizes, and how many check machines run at once.
- [Guarantees](/docs/guarantees): what is promised about the commit a check runs on.
