zit.toml
Checks, generated files, dependency installs and ignore patterns. Check results are reused wherever their inputs are unchanged.
Declare
zit.toml at the repository root, committed like any other file:
[[check]]
name = "api"
run = "cargo test -p api"
inputs = ["crates/api", "Cargo.lock"]
[[check]]
name = "ui"
run = "npm test --prefix ui"
inputs = ["ui"]
[[check]]
name = "lint"
run = "./scripts/lint.sh" # no inputs: depends on the whole state
| Field | Meaning |
|---|---|
name |
identifies the check in output and in the key |
run |
shell command, executed with sh -c at the root of a view of the state |
inputs |
paths the result depends on; omitted means everything |
timeout |
seconds before the check, and everything it started, is stopped and counted as failed; default 1800 |
serial |
true runs this check alone, whatever [accept] jobs allows; default false |
inputs are paths, not patterns. src/*.rs would match nothing in the tree and its evidence would be reused forever, so it is refused: zit.toml: input src/*.rs is a pattern; inputs are paths. Name the directory instead: src.
Exit code 0 is a pass. The command’s environment:
| Variable | Value |
|---|---|
ZIT_CHANGE, ZIT_STATE |
what is being checked |
TMPDIR |
a temp directory of its own, emptied before each verification (not between the checks of one verification) |
ZIT_CACHE_DIR |
a directory that outlives workspaces, shared with agents |
ZIT_PORT |
a free TCP port chosen for this view, as for workspaces (Agents); not reserved |
Where checks run
In a verification view: a directory at a stable path that is moved from state to state in place. Files that did not change keep their timestamps and files matched by .gitignore are kept, so incremental build tools stay warm; anything untracked is removed. On the Rust project in Lessons this is the difference between recompiling everything for every accept and not.
A check that needs a clean build directory must clean it itself.
Every check of one verification sees the state, not what an earlier check wrote: before each check after the first, the view is restored (git reset --hard, git clean -fd; ignored files kept). Two git calls per extra check. With [accept] jobs above 1 the checks that run at the same time share the view, so a check that writes tracked files needs serial = true.
Run
zit check <change> # run what has no evidence yet
zit check <change> --rerun # ignore existing evidence
zit check <change> --only ui # just this check (repeatable); an unknown name is an error
zit accept runs the same thing against the state that is about to become current, so you rarely call check yourself. zit accept --dry-run <change> names the checks an accept would run and those it would reuse, without running anything (CLI).
Reuse
The id of ui/ is a git tree id: a hash of every file under it. A change that touches only crates/api leaves that id, and therefore the ui key, unchanged.
Failures are stored too: a known-failing state is rejected without re-running. For a flaky check, zit check --rerun or zit accept --rerun runs everything again.
Limits
-
A change cannot weaken its own gate.
acceptruns the checks declared by current and those declared by the change. A change that rewritesrun = "cargo test"asrun = "true"still has to passcargo test. It can add checks, not remove them. -
zit.tomlis still code. Everyrun,deriveandpreparecommand executes with your privileges. A change’s own new checks and[[derive]]commands run when you check or accept it, and its[prepare]runs when anyone materialises it (--from) and when it is checked or accepted (in a verification view). A change that editszit.tomlshows it in its write set; read it before accepting or building on it. -
A check that times out or is killed is not remembered. Its result is reported but not stored as evidence, so the next accept runs it again instead of trusting a failure the code did not cause.
-
inputsis trusted. If a check reads files it did not declare, it can be reused when it should not be. -
Ignored files persist in a view from one check to the next (ADR 10).
-
The checks of one verification run one after another unless
[accept] jobssays otherwise (below). Up to eight verifications run at once.
The parse check
After git merge-tree composes a change onto current, every file both sides changed since their merge base, in a language Zit has a grammar for, is parsed in three versions: current’s, the change’s, and the merged text. Merged text with syntax errors that neither side had is refused:
rejected: does not parse after composing: src/lib.rs
JSON: {"outcome": "rejected", "reason": "error", "detail": "does not parse after composing: src/lib.rs"}. Files are parsed whole. It applies to accept, --batch, --dry-run and --allow-stale, not to status. It is on by default; current’s zit.toml turns it off:
[accept]
parse_check = false
Running checks at once
[accept]
jobs = 2 # default 1
[[check]]
name = "fmt"
run = "cargo fmt --check"
serial = true # runs alone
Up to jobs checks of one verification run at the same time, in the same view, started in declared order. Verdict order and evidence keys are unchanged; jobs is not part of a key. Concurrent checks share the view directory and $TMPDIR, so a check that writes into the tree needs serial = true. Measured with two sleep 1 checks on this Mac: 2.45 s sequential, 1.19 s with jobs = 2.
Free space
Before building any workspace (materialise, retry, run, the cached checkouts) and every verification view, Zit checks the free space on the volume holding its home:
zit: refusing to materialise: <N> MB free on the volume holding <home>, less than zit.minFreeMB = 512 (`git config zit.minFreeMB 0` disables this guard)
The threshold is git config zit.minFreeMB, default 512; 0 or a negative value disables it. The default has no test that exercises it. A full disk is what lost three agents’ work in Lesson 02 (Lessons).
Generated files
A file that a script builds from other files (a registry, an index, a bundle manifest) is not something two contributors can meaningfully conflict on. Declare it:
[[derive]]
path = "registry.json"
run = "python3 scripts/generate_registry.py"
Writes to path never make a change stale, conflicts inside it do not count, and claims on it never block anyone. When a change is composed onto current, run is executed on the composed state and its output for path is what lands. A failing run rejects the change: rejected: failed checks: derive registry.json. (ADR 12)
Dependencies
[prepare]
run = "npm ci"
inputs = ["package.json", "package-lock.json"]
Run once in the cached checkout every workspace is cloned from, and again only when inputs change. Every workspace starts with the result, as a copy-on-write clone. It may only create ignored files; anything else is an error that names the files. Use an install that does not rewrite the lockfile. (ADR 14)
How changes land
[accept]
linear = true # compose as one commit on top of current, never a merge commit
parse_check = true # refuse a composed state whose files no longer parse (default)
jobs = 1 # checks of one verification that may run at once (default)
Read from current, so it applies to everyone who accepts. linear is the same as zit accept --linear (Teams and review).
Stable workspace paths
[workspace]
stable_paths = true
or, for one machine, git config zit.stablePaths true. Workspaces are then made in numbered slots, <home>/ws/slot-N, with slot-N as the workspace id; the lowest free slot is taken. Disposing a slot keeps its tree/ and git/ (its meta.json becomes retired.json); the next workspace made there is a git reset --hard plus git clean -fd: tracked files reset, untracked removed, ignored files kept. Build tools that key their caches on the absolute path (Cargo, for example) then find their output from the last agent at that path.
The trade-off: agents inherit the previous agent’s ignored files, stale caches included; a slot whose [prepare] key differs from the new state’s is rebuilt; slots grow to the peak number of concurrent workspaces and stay until zit clean, which removes them all. [workspace] is read from the state being materialised.
Ignore patterns
ignore = ["agent-notes/", "*.log"]
Files agents and tools leave behind that should never be part of a change, in gitignore syntax. Added to your own global excludes and to built-in patterns for files that are never source: .DS_Store, __pycache__/, *.py[cod], .pytest_cache/, .mypy_cache/, .ruff_cache/, *.swp, and coding agents’ session state (.autohand/memory/, .autohand/*.local.json, .autohand/session-permissions.json, .claude/settings.local.json). Tracked files are never hidden. (ADR 13)
A complete example
ignore = [".coverage"]
[prepare]
run = "npm ci"
inputs = ["package.json", "package-lock.json"]
[[derive]]
path = "registry.json"
run = "node scripts/build-registry.js"
[[check]]
name = "unit"
run = "npm test"
inputs = ["src", "test", "package.json", "package-lock.json"]
[[check]]
name = "types"
run = "npx tsc --noEmit"
inputs = ["src", "tsconfig.json"]