Configuration reference
poly reads a single poly.toml. This page is the key-by-key reference; the
Configuration guide explains how the pieces fit
together.
Editor setup (JSON Schema)
Section titled “Editor setup (JSON Schema)”poly publishes a JSON Schema for poly.toml at:
https://polylint.github.io/polylint/poly-v2.schema.jsonPoint your editor at it for validation and autocomplete. The simplest way is the
schema directive as the first line of poly.toml:
#:schema https://polylint.github.io/polylint/poly-v2.schema.json
[defaults]line_length = 120The directive is an ordinary TOML comment that taplo
and the editors built on it understand, and poly fmt leaves it in place. You
can also generate the schema locally — it is derived from the same types the
parser uses:
poly config schema --output poly.schema.jsonThe per-engine [engines.<id>] tables are autocomplete hints: each backend
lists the keys it declares, but the tables stay open because a language id may be
any tree-sitter grammar and some backends derive their key set from an upstream
type. poly lint remains the authority — it reports unknown-config-key for any
key no engine reads. The v2 schema is committed as schemas/poly-v2.schema.json;
poly config schema prints the one the running binary uses.
Top-level sections
Section titled “Top-level sections”| Section | Purpose |
|---|---|
required_version, root |
Name the poly versions CI installs; stop the config cascade. |
[components] |
Which downloadable engine components a run may use. |
[defaults] |
Line width, line endings, whitespace — the base every formatter layers on. |
[discovery] |
The file walk: excludes, the prune set, generated files. |
[engines.<id>] |
Per-engine rule and formatter configuration, including ast-grep’s rule directories. |
[workspace] |
When the whole-project phase of poly lint runs. |
[per_file_ignores] |
Suppress rules by path glob. |
[tools] |
Opt into catalog tools. |
[cache] |
Result-cache and sccache configuration. |
[commit] |
poly commit message linting and cleanup. |
[hooks] |
Git-hook stages, builtins and inline jobs. |
extends |
Share configuration from local or pinned-remote bases. |
required_version and root
Section titled “required_version and root”| Key | Type | Default | Meaning |
|---|---|---|---|
required_version |
string | — | The poly versions this repository expects (">=0.34, <0.35"). Components version in lock-step with poly, so it selects them too. Read by the GitHub Action’s version: from-config, which installs the newest release in the range, and written by poly migrate --to-v2. poly refuses to load a config the running version does not satisfy. |
root |
boolean | false |
Stop the upward config cascade here (a .git directory is an implicit boundary). Replaces v1’s [workspace] root. |
[components]
Section titled “[components]”Selection and policy for downloadable engine components. See Components and offline use.
| Key | Type | Default | Meaning |
|---|---|---|---|
enable |
"auto" or array |
"auto" |
"auto" derives components from the discovered files and configured engines; an array names components or presets. |
disable |
array | [] |
Components never to use. An unknown name, or an engine table of a disabled component, is a warning (set enabled = false in the table to silence it); an unknown enable name, or a name in both lists, is a config error. |
install |
"auto" | "never" |
"auto" |
Whether a run may download a missing component. |
on_missing |
"fail" | "skip" |
"fail" |
Exit 2, or skip the files and charge them to the skip budget, when a needed component is unavailable. --on-missing overrides it. |
[defaults]
Section titled “[defaults]”The opinionated base layer. Each key is applied wherever a tool exposes the setting.
| Key | Type | Default | Meaning |
|---|---|---|---|
line_length |
integer | 120 |
Target maximum line length. |
line_ending |
string | "lf" |
"lf" or "crlf". |
final_newline |
boolean | true |
Enforce a single trailing newline. |
trim_trailing_whitespace |
boolean | true |
Strip trailing whitespace. |
[discovery]
Section titled “[discovery]”| Key | Type | Default | Meaning |
|---|---|---|---|
exclude |
string or array | [] |
Gitignore-style globs pruned from the walk. A leading / anchors to the config directory; otherwise it matches at any depth. Accumulates across extends (use exclude_mode = "replace" to opt out). |
force_exclude |
boolean | true |
Apply exclude to explicitly named paths too. |
no_prune |
string or array | [] |
Directory names to keep despite the built-in prune set (build, dist, …). |
generated |
boolean | true |
Whether poly lints and formats machine-generated files. |
Engines
Section titled “Engines”[engines.<id>]: one table per engine, keyed by the engine id (ruff, oxc, taplo, rumdl, typos,
astgrep, quality, uncomment, …). See Languages and engines
page for which engine serves each language. Options that apply everywhere sit directly in the
table; narrow with sub-tables:
[engines.ruff] # every phase, every languageselect = ["E", "F"]
[engines.ruff.format] # the format phase only (also: .lint)line_length = 100
[engines.ruff.lang.python] # one language (also: .lang.python.lint / .format)target_version = "py312"
[engines.ruff.rules.ANN201] # a per-rule overridelevel = "error"Precedence, lowest to highest: tool defaults, the tool’s native config files, [engines.<id>], its
lint or format sub-table, its lang.<language> sub-table, then lang.<language>.lint or
.format. The names enabled, lint, format, lang and rules are reserved.
Every engine table accepts enabled (boolean; an absent key means the engine’s
own default — typos is off unless [engines.typos] enabled = true). Linter backends that
participate in rule selection accept the uniform triple:
| Key | Type | Meaning |
|---|---|---|
select |
array | Replace the default rule set with these codes / categories. |
extend_select |
array | Add to the default rule set. |
ignore |
array | Remove from the selected set. |
rules.<id> |
table | Per-rule override: [engines.<id>.rules.<code>] level = "error" | "warning" | "info" | "hint", plus rule parameters. When several level entries match a code, the longest wins: F401 beats the family F. |
Each engine also reads its own keys ([engines.ruff] line_length, [engines.mago] php_version, …).
poly lint reports a key that no engine reads as unknown-config-key with a source span, and
poly config validate checks the keys offline from the component index.
ast-grep rules
Section titled “ast-grep rules”[engines.astgrep] also carries the ast-grep rule settings that v1 kept in a top-level [rules] table:
| Key | Type | Default | Meaning |
|---|---|---|---|
rule_dirs |
array | [".poly/rules"] |
Directories of custom ast-grep *.yml rule files, relative to the config. Set to [] to disable. |
builtin_pack |
boolean | true |
Load poly’s built-in ast-grep rule pack. |
Go architecture rules
Section titled “Go architecture rules”Three more keys of [engines.astgrep] configure architecture checks for Go. They need no Go toolchain: a call or import
is resolved from the file’s own import block, and module-internal imports against the go.mod that governs the file
(the nearest one, so nested modules work). They report through the same select, extend_select, ignore and
[engines.astgrep.rules.<id>] level as the pack’s rules; a configured entry is on by default and reports at error
unless its level or a rules.<id> override says otherwise. _test.go files are skipped unless an entry sets
include_tests = true.
Every glob (paths, allow_in, a layer’s paths) is matched against the file’s path relative to its module root,
with / separators. * stays within one path element, ** crosses elements, and a trailing /** also matches the
directory itself.
| Key | Rule id | Entry fields |
|---|---|---|
go_forbidden_calls |
go-forbidden-call |
call (<import path>.<Name>, Name may use wildcards), paths, allow_in, message, level, include_tests |
go_forbidden_imports |
go-forbidden-import |
import (a glob over import paths), paths, allow_in, message, level, include_tests |
go_layers |
go-layer-violation |
name, paths (directory globs), may_import (layer names), message, level, include_tests |
[[engines.astgrep.go_forbidden_calls]]call = "os.Getenv" # the package is an import path: "os/exec.Command", "log/slog.Info"paths = ["internal/**"] # where it applies (default: everywhere)allow_in = ["internal/ambient/**"] # exemptions inside pathsmessage = "read the environment through ambient.Env"
[[engines.astgrep.go_forbidden_calls]]call = "log.Fatal*" # wildcard on the selector name
[[engines.astgrep.go_forbidden_imports]]import = "github.com/sigstore/**"paths = ["pkg/**"]
[[engines.astgrep.go_layers]]name = "domain"paths = ["internal/domain/**"]may_import = [] # may import no other layer
[[engines.astgrep.go_layers]]name = "infra"paths = ["internal/infra/**"]may_import = ["domain"]A forbidden call is any selector pkg.Name whose pkg is the local name of a matching import, aliases followed. A dot
import of a forbidden package is itself the finding, since it hides the selectors. The local name of an unaliased import
is the last path element minus a major-version suffix (yaml/v3, yaml.v3 and yaml all give yaml); the check is
syntactic, so a local variable that shadows the package name is a false positive. A layer is the first go_layers entry
whose paths match the file’s directory; an import of a module package in another layer is a violation unless the
importing layer lists it in may_import. Imports of packages outside the module, and of module packages in no layer, are
not layer-checked (go_forbidden_imports covers them). A bad entry (unknown field, missing call, invalid glob, a
may_import naming no layer) fails the run with a message naming the key and index.
To grandfather existing violations, list the rule id per path in [per_file_ignores].
Migrating from ai-rulez’s archlint test package. forbidden (import path to selectors) becomes one
go_forbidden_calls entry per selector, or a wildcard, with exempt prefixes as allow_in = ["internal/runner/**"] and
the internal/ scope as paths. The allowlist.txt ratchet becomes [per_file_ignores] entries. Differences: archlint
counts sites per file and fails when an allowlist entry is stale (poly has no stale-entry check); it skips a selector
whose identifier go/parser resolved to a local object (poly is syntactic and cannot); and its go list -deps import test
follows transitive dependencies, where go_forbidden_imports checks direct imports only.
Python type checking
Section titled “Python type checking”[engines.python-types] is opt-in Python type checking, a project-check engine. backend picks the checker: "ty" (in the
python component) or "pyrefly" (its own opt-in pyrefly component, fetched when a config selects it). The two share one
table, so switching is one value.
[engines.python-types]backend = "ty" # or "pyrefly"python_version = "3.12" # default: the interpreter's, else the checker's latestsrc = ["src"] # first-party roots; default: the project root and src/extra_paths = ["stubs"] # searched before first-party codeNeither backend starts a process: poly resolves the virtualenv and its site-packages itself and hands the paths over
(pyrefly’s interpreter query is forced off). ty’s ty.toml and [tool.ty], and pyrefly’s pyrefly.toml and
[tool.pyrefly], are not read. pyrefly’s findings carry its own rule codes (bad-assignment, missing-import, …); the
component is built without pyrefly’s bundled third-party stubs, so only typeshed’s stdlib stubs come with it.
A run never ends up checking nothing when type checking was asked for:
- A
backendthat is not a string (backend = 1,true, an array) is reported as an unknown value by ty, the default backend, and the run exits 2. An unsetbackendkeeps type checking off. backend = "pyrefly"while thepyreflycomponent is disabled ([components] disable) or missing from the build (the bundled binary links no pyrefly) is an error that names the component and says how to enable it, exit 2. Under--offline,install = "never"oron_missing = "skip"the unavailable component is instead a counted skip, as for every component (ADR 0039), and--deny-skipsapplies.--onlyand--skiptake the engine name (pyrefly) or the shared table name (python-types) for either backend:--skip python-typesstops whichever is configured, and--only python-typeskeeps it. Like any selection they only narrow:--only pyreflywithbackend = "ty"runs nothing. That is reported as a skip that names the backend, or says it is unset (`--only pyrefly` selects nothing here: `[python-types] backend` is "ty"), and counted by--deny-skips/--max-skips, unlike other--only/--skipexclusions: you asked for a check and got none, so the run must not read as a pass.- pyrefly uses the run’s thread budget (
-j/--jobs, else every core), as passed over the component protocol.
JavaScript and TypeScript workspaces
Section titled “JavaScript and TypeScript workspaces”[engines.skif] runs skif: opt-in dependency, manifest, version-policy and dead-code linting for npm, pnpm, yarn and bun
workspaces, a project-check engine in the web component (preset aliases skif and js-deps). A project’s own
skif.toml is honored; the keys below override it.
[engines.skif]enabled = truedir = "." # the workspace, relative to the project rootignore = ["empty-dependencies"] # skif rule ids to turn offselect = ["catalog-mismatch"] # run only these rulesignore_packages = ["@scope/legacy-*"]ignore_dependencies = ["left-pad"]production = false # judge production dependencies onlyjs = true # false turns the source (import) analysis offthreads = 4 # skif's own pool; default: poly's job count, 1 spawns nonepnpm_lock = "pnpm-lock.yaml" # also npm_lock, yarn_lock, bun_lockskif reads only the files poly hands it: sources (including Vue, Svelte and Astro components), manifests, tsconfig,
pnpm-workspace.yaml, skif.toml and every .gitignore and .ignore under dir, plus the lock files, never
node_modules. It always sees the whole tree: .gitignore and the pruned directories apply, but [discovery] exclude, --exclude and nested poly.toml scopes do not cut the import graph; they only decide which files get
findings. The result is cached on all of them, so editing any member package.json re-runs the check, and it does
not depend on what is installed on the machine. Every run reads and hashes the whole tree to compute that key, so on
a very large monorepo the cost of a warm run is the read, not skif.
Three rules judge a dependency by what an installed package provides and are off unless you ask for them:
unlisted-binaries, unused-dev-dependencies and unused-dependencies. Without node_modules, a dependency used
only through a binary named otherwise (@acme/toolkit running kit) or only as another dependency’s peer is
reported as unused (a lock file supplies peers, not pnpm binary names). Turn one on with select, with
[engines.skif.rules.<id>] level = "error", or in your skif.toml [rules].
poly lint --fix applies skif’s safe fixes to the manifest a finding is in; fixes that are unsafe, need a choice or
edit another file stay suggestions. After the fixes the check runs once more and that run is the report. Set
[engines.skif.rules.<id>] level to move a finding’s severity.
TypeScript type checking
Section titled “TypeScript type checking”[engines.tsrs] is an experimental, opt-in tsc --noEmit: a project-check engine in its own tsrs component,
built on tsrs, a Rust port of the TypeScript 7 compiler (ADR 0051). It builds one
program from the project’s tsconfig.json and reports the compiler’s errors and warnings as TS<code> findings
(TS2322, TS2307, …), with the message chain in the description (--verbose).
[engines.tsrs]enabled = trueproject = "tsconfig.json" # default: the nearest tsconfig.json from `dir` up to the project rootdir = "." # the project directory, relative to the project rootstrict = true # overrides the tsconfig's `strict`skip_lib_check = true # overrides the tsconfig's `skipLibCheck`report_unresolved_modules = false # report packages the project declares but the check cannot seethreads = 4 # checkers; default: poly's job countBecause it is an engine, poly lint runs it when enabled, and so does the builtin lint hook of pre-commit; no
[hooks.pre-commit.commands.*] entry is needed. A project check judges the whole program, so poly hands it every
JavaScript, TypeScript and JSON file under dir (.gitignore and the pruned directories apply; [discovery] exclude
and nested poly.toml scopes do not cut the program) and the result is cached on all of them.
The check is hermetic: tsrs reads those files through an in-memory file system, never the disk, and poly hands over no
node_modules. An import of an installed package therefore cannot resolve. TS2307, TS2792, TS7016 and
TS2688, and the Cannot find name ... install type definitions codes, are dropped when a package.json of the
project declares the package (or its @types package, or @types/node for Node built-ins) and reported when it does
not, since an undeclared import is a real error. “Declares” means the package.json files in the importing file’s
directory and above, so a sibling package’s dependencies do not count. With react or @types/react declared and the
jsx option set, TS2875 and TS7026 are dropped too. Set report_unresolved_modules = true to see them all. A
tsconfig.json that extends a package the project declares (@tsconfig/node20/tsconfig.json) is checked without the
inherited options and gets one warning saying so; an extends of an undeclared package stays an error (TS6053).
Findings under node_modules, and in JavaScript files (unless allowJs puts them in the program), are never reported,
though those files are inputs; the project’s own declaration files (.d.ts) are reported, as tsc does unless
skipLibCheck is set. Findings follow tsc’s order and stop at the first group that has
any: config, syntax, then semantic errors.
One program is checked: set project to the tsconfig of the package you want in a monorepo, one poly.toml scope per
package. tsrs reads its own TSRS_* environment variables; poly sets none and reads none.
R formatting and linting
Section titled “R formatting and linting”R is formatted by air and linted by jarl,
both in process in the r component (ADR 0070); no R installation is involved. Each reads its own project config the
way its CLI does, and the [engines.*] table is laid over it.
[engines.air] # the formatter; the nearest air.toml (or .air.toml) above the file is read firstline_width = 100 # default 120 without an air.toml (air's own default is 80)indent_width = 2indent_style = "space" # or "tab"line_ending = "lf" # "auto", "lf", "crlf" or "native"persistent_line_breaks = trueassignment_style = "arrow" # "equal" or "preserve"skip = ["graph_from_literal"] # calls that are left as writtentable = ["my_table"] # calls formatted as tablesdefault_table = true
[engines.jarl] # the linter; the nearest jarl.toml (or .jarl.toml) above the file is read firstselect = ["PERF", "any_is_na"] # rule names or categories (CORR, SUSP, PERF, READ, ...); replaces the default setextend_select = ["assignment"]ignore = ["seq"]check_roxygen = true # lint the @examples of roxygen commentsmin_r_version = "4.1" # switches off rules that need a newer R
[engines.jarl.rules.assignment]operator = "=" # the rule's own option, as in [lint.assignment] of jarl.toml[engines.jarl.rules.seq]level = "error" # severity for one ruleA project with an air.toml is formatted exactly as air format formats it: poly’s 120-column default is not laid
under the file, so a key it omits keeps air’s default (80 columns). Without one, poly’s [defaults] line width and
line ending and the language’s indent width apply. air’s exclude and default-exclude patterns (renv/,
RcppExports.R, import-standalone-*.R, …) are reported as skipped files. A file that does not parse is an error.
jarl reports a rule’s findings with its rule name as the code. Rules in the CORR category (code that is outright wrong
or useless) are errors and every other rule is a warning, unless level says otherwise. Only safe fixes are attached,
so poly lint --fix applies them; an unsafe fix is reported with fix = "unsafe" in the finding’s metadata. jarl’s
exclude and include file filters are not applied: use [discovery] and [per_file_ignores]. Rules that look
functions up in installed packages see only what the file and the project’s NAMESPACE declare, since poly never
starts R.
styler remains an opt-in host formatter ([engines.styler] enabled = true); it then runs after air. Set
[engines.air] enabled = false to format with styler alone. An enabled air recipe under [tools] still takes R formatting over from the component.
[workspace]
Section titled “[workspace]”| Key | Type | Default | Meaning |
|---|---|---|---|
run |
"auto" | "always" | "never" |
"auto" |
When poly lint runs the whole-project phase: for repository-wide runs only (auto), even for named paths (always), or never. --workspace overrides it. |
[per_file_ignores]
Section titled “[per_file_ignores]”A table of path glob → rule codes to suppress for files matching the glob. Globs are relative to the config that declares them.
[per_file_ignores]"tests/**" = ["F401"][tools]
Section titled “[tools]”Opt into tools from the vendored catalog, keyed by catalog name
([tools.<name>]). Every entry is inert until enabled = true.
| Key | Type | Default | Meaning |
|---|---|---|---|
enabled |
boolean | false |
Whether the tool runs. |
command |
string | — | Which catalog command to invoke. |
args |
array | — | Replace the catalog command’s argv entirely. |
stages |
array | [] |
Git stages the tool runs in. |
files |
string or array | — | Include glob(s). |
exclude |
string or array | — | Exclude glob(s). |
env |
table | {} |
Environment variables injected when running the tool. |
root |
string | — | Working directory, relative to the config root. |
extra_args |
array | [] |
Flags added to every role’s argv, just before the file list. Keeps the catalog’s own flags, so this is where configuration goes (["-c", "checkstyle.xml"]). |
format_extra_args |
array | [] |
extra_args for the formatting role only. |
lint_extra_args |
array | [] |
extra_args for the linting role only. |
bin |
string | — | Executable to run instead of the catalog binary on PATH: a program name or an absolute path. For a JVM tool, the java. |
version |
string | — | Pinned release to use. Looked up in the catalog’s checksummed releases. |
url, sha256 |
string | — | Download and digest for a version the catalog does not seed. The URL must be https on a host the catalog names for the tool. |
install |
string | "never" |
"auto" downloads the pinned version into poly’s cache when the tool is missing. A version that cannot be provisioned makes the tool unavailable; poly never runs a different version from PATH. |
values_files |
array | [] |
helm: values files (-f) passed to every chart, relative to the config root. |
chart_values |
table | {} |
helm: chart-directory glob to the values files passed for the charts it matches. |
skip_charts |
array | [] |
helm: chart-directory globs the tool does not run on (library charts). |
prepare |
bool | true |
helm: run helm dependency build once per chart before linting, unless charts/ already satisfies Chart.lock or POLY_OFFLINE is set. |
prepare_attempts |
integer | 5 |
helm: attempts at the prepare step before checking with the dependencies on disk. 1 disables the retry. |
prepare_backoff_secs |
integer | 4 |
helm: wait after the first failed attempt; doubles after each further failure. |
prepare_jitter_secs |
integer | 4 |
helm: up to this many random extra seconds added to every wait. |
verify_skip_charts |
bool | true |
helm: still run each skip_charts chart and fail when the tool now passes on it; false skips them without running. |
new_from_rev |
string | — | golangci-lint: report only findings introduced since this git revision (--new-from-rev). |
goos |
array | [] |
golangci-lint: run once per operating system with GOOS set and merge the findings. |
bin, url/sha256, env, args, extra_args, format_extra_args, lint_extra_args,
new_from_rev and root are honoured only in a trusted repository (a bare
bin name always is). Trusted or not, bin is a program name or an absolute path, root stays
inside the repository, url must be https on a host the catalog names for the tool, and env may
not set loader, git-config or runtime-injection variables (LD_*, DYLD_*, GIT_CONFIG*,
NODE_OPTIONS, …).
Tools with a recipe (checkstyle, palantir-java-format, buildifier, buf, actionlint, gau,
hadolint, golangci-lint, helm, helm-template, tflint, tofu, terraform,
pyproject-fmt, npm-groovy-lint, air, jarl, checkmake, editorconfig-checker, rbcop, swiftlint, scalafmt) run batched, parse the tool’s report into file/line/rule
diagnostics, and are described in Tool catalog.
[cache]
Section titled “[cache]”| Key | Type | Default | Meaning |
|---|---|---|---|
enabled |
boolean | true |
Master switch for both cache tiers. |
dir |
string | — | Override the cache root directory. |
[cache.results] hooks |
string | "safe" |
"off", "safe" or "aggressive". |
[cache.sccache] enabled |
boolean | false |
Enable tier-2 sccache for compiler hooks. |
[cache.sccache] bin |
string | — | sccache binary (bare name or absolute path). |
[cache.sccache] dir |
string | — | sccache storage directory. |
[cache.sccache] max_size |
string | — | Maximum cache size (e.g. "10G"). |
dir, [cache.sccache] dir and a path [cache.sccache] bin are honoured only in a
trusted repository.
Without dir, the result cache lives in the per-user cache directory (POLY_CACHE_HOME, else
~/.cache/poly on Linux, ~/Library/Caches/poly on macOS, %LOCALAPPDATA%\poly on Windows), in a
slot keyed by the repository’s git common dir. Every git worktree of one repository therefore shares
one result cache, and a new worktree’s first run reuses what the others already computed. The hook
staged snapshot is per-run working state, so it stays in a separate slot per worktree.
[commit]
Section titled “[commit]”| Key | Type | Meaning |
|---|---|---|
preset |
string | Named preset to seed the rules from (e.g. "conventional"). |
write |
boolean | Whether the cleaner rewrites the message in place. |
[commit.rules] message |
table | { pattern, description, enforce_length, enforce_case } — a required subject pattern. A pattern replaces the Conventional Commits structural check; enforce_length and enforce_case keep its length limits and its subject case / trailing full stop checks. |
[commit.rules] excludes |
array of tables | { pattern, message } — subjects that skip linting. |
[commit.rules] cleanup |
array of tables | { find, replace, description } — find/replace cleanups. |
[commit.rules] single_line |
boolean | Reject multi-line subjects. |
[commit.rules] require_body |
boolean | Require a non-empty body. |
[commit.rules] exit_nonzero_on_rewrite |
boolean | Exit non-zero when the cleaner rewrote the message. |
[commit.rules] no_emojis |
boolean | Reject emojis. |
[commit.rules] ascii_only |
boolean | Require ASCII-only content. |
[commit.rules] title_prefix |
string | Required subject prefix. |
[commit.rules] title_prefix_separator |
string | Separator after the prefix. |
[commit.rules] title_suffix |
string | Required subject suffix. |
[commit.rules] title_suffix_separator |
string | Separator before the suffix. |
[commit.rules] ai_cleanup |
boolean | Set to false to keep AI attribution trailers and banners instead of removing them (default true). |
[hooks]
Section titled “[hooks]”The [hooks] table holds reserved keys plus one key per git stage
([hooks.pre-commit], [hooks.commit-msg], …).
Reserved keys:
| Key | Type | Meaning |
|---|---|---|
stages |
array | Default stages for builtin hooks that do not set their own. commit-msg and prepare-commit-msg apply only to commit; a file-checking builtin runs there only when it lists the stage itself. |
env |
table | Environment merged into every job. |
sources |
array of tables | [[hooks.sources]] producer catalogs: { id, path | git, revision, hooks }. |
snapshot_include |
string or array | Untracked paths pulled into the staged snapshot (ADR 0019). |
isolate |
boolean | Force hooks onto the staged snapshot (unset uses the per-invocation default). |
snapshot |
"auto" | "full" |
auto (default) materializes only the staged files and their directory context unless a workspace or cargo job will run; full always materializes the whole index. |
partial_stage |
"fail" | "restage" |
What a stage_fixed job does when its fix lands on a file that also has unstaged edits. fail (default) withholds the fix and names the commands to resolve it; restage stages only the fixed content and leaves the edits in the worktree. |
builtin |
table | See below. |
[hooks.builtin] — poly’s in-process hooks. Each of lint, fmt, commit is a
bare boolean or a table; file_safety and cargo are a boolean or a tuned
group table.
| Key | Type | Meaning |
|---|---|---|
lint / fmt / commit |
boolean or table | { enabled, stages, files, exclude }; lint and fmt also take fix, priority and jobs (see the hooks guide). |
file_safety |
boolean or table | { enabled, stages, files, exclude, max_added_file_kb, merge_conflict, added_large_files, private_key, case_conflict, executables_have_shebangs, shebang_scripts_are_executable, aws_credentials, requirements_txt_fixer, priority, jobs }. |
cargo |
boolean or table | { enabled, stages, clippy, sort, machete, deny, clippy_args, cache, lint }. |
A stage table ([hooks.pre-commit]) accepts:
| Key | Type | Meaning |
|---|---|---|
parallel / piped / follow |
boolean | Concurrency and output-streaming behaviour. |
exclude_tags |
array | Tags whose jobs are excluded. |
files / exclude |
string or array | Stage-level include/exclude globs. |
skip / only |
boolean or array | Guard: a bare bool or [{ run = "<command>" }]. |
fail_on_changes |
boolean | Fail if jobs dirty the working tree. |
precondition |
string | Guard command; non-zero skips the stage with a warning. |
before / after |
string or array | Commands run before/after the jobs. |
jobs |
array of tables | Ordered jobs ([[hooks.pre-commit.jobs]]). |
commands / scripts |
tables | Named jobs ([hooks.pre-commit.commands.<name>]). |
A job accepts name, run xor script, runner, args, glob,
files, exclude, file_types, root, skip, only, precondition,
before, tags, env, fail_text, timeout, priority, serial,
stage_fixed, show_output, workspace, interactive, use_stdin and cache.
root runs the job from a subdirectory and passes file arguments relative to it (as lefthook
and pre-commit do): a job with root = "products/em/backend" receives src/x.py, not
products/em/backend/src/x.py, in "$@" and in {staged_files} / {all_files}. Files outside
root are not passed, and a job none of whose files are under root is skipped.
show_output = true prints the job’s output even when it passes; by default only a failing job’s
output is shown, so a warning from a job that exits 0 is otherwise dropped.
poly hooks run --verbose (-v) does the same for every job.
extends
Section titled “extends”A top-level list of base configs to inherit from (ADR 0020). Each entry is a
local path string or a { path | git, revision, file } table; a single entry may
be given without the array.
extends = [ { git = "https://github.com/acme/poly-baseline", revision = "<40-hex-oid>", file = "poly.toml" }, "./poly.overrides.toml", # later entry = higher precedence]A local path outside the repository is read only once the repository is trusted.
exclude_mode = "replace" in a table next to an exclude list makes that list
replace the inherited one rather than accumulate. A symbolic (branch/tag) git
ref must be locked first: poly lock records it (so does poly hooks install).
Remote git bases and [[hooks.sources]] are fetched over https or ssh (including scp-like
host:path) only; git://, http://, file:// and ext:: URLs are rejected. Plain local paths are
unaffected. POLY_GIT_ALLOW_PROTOCOLS (a :-separated list, passed to git as GIT_ALLOW_PROTOCOL,
for example https:ssh:git) replaces the default list; a leading + extends it instead
(+http:git allows https, ssh, http and git). A GIT_ALLOW_PROTOCOL already set in the
environment is overridden by poly’s own list for these fetches.