Skip to content

Configuration reference

Sprawl Guard looks only for sprawl-guard.toml in the repository root. To use another file, such as .sprawlrc.toml, pass --config PATH. Unknown sections and fields are errors.

Every root configuration starts with an editor schema directive and declares its schema version:

sprawl-guard.toml
#:schema https://kpozin.github.io/sprawl-guard/schemas/v2/sprawl-guard.schema.json
schema_version = 2

Run sprawl-guard init --write to create this minimal file, then add the sections below.

Use sprawl-guard config resolved to see the full resolved configuration. Use sprawl-guard config export to print a complete configuration suitable for committing.

Sprawl Guard publishes JSON Schemas for the configuration and the ratchet file. init, config export, update --write, and tighten --write include the Taplo directive that selects the appropriate schema in editors such as the Even Better TOML extension for VS Code.

Run sprawl-guard schema config or sprawl-guard schema ratchet to print either schema for local or offline use.

When a new version of Sprawl Guard changes the configuration format, run sprawl-guard config upgrade --write. It upgrades the file and keeps your comments and formatting. The CI workflow runs sprawl-guard config upgrade --check, which fails until you do.

Field Type and default Meaning
max_bytes_per_file size or "unlimited", unlimited Largest size of any one file (other than Git LFS files).
max_bytes_per_lfs_object size or "unlimited", unlimited Largest size of any one Git LFS file.

The byte limits apply to every file that check visits, including images, archives, and generated data. Use [[overrides]] to change them for particular paths.

Write a size as a number of bytes, such as 500000, or with a unit, such as "500 kB" or "1.5 GiB". kB, MB, GB, and TB are powers of 1000; KiB, MiB, GiB, and TiB are powers of 1024.

If your repository uses Git LFS, files that .gitattributes assigns to Git LFS count against max_bytes_per_lfs_object instead of max_bytes_per_file, at their full size even when Git LFS hasn’t downloaded them. This lets you keep max_bytes_per_file small without flagging the large files you keep in Git LFS on purpose.

Field Type and default Meaning
count_lines array, [] Extra line types to count: comments, blank_lines.
production positive integer, 400 Lines in a production file.
test positive integer, 800 Lines in a test file.

Code lines always count. count_lines adds comment or blank lines and must not contain duplicates. For literate languages, such as Markdown, Sprawl Guard adds comments automatically unless the language sets its own count_lines.

Field Type and default Meaning
production positive integer or "unlimited", 10 Direct production source files in one directory.
test positive integer or "unlimited", 10 Direct test source files in one directory.

All fields are booleans and default to true.

Only ignore files inside the repository root are read. Global Git excludes, .git/info/exclude, and ignore files above the root have no effect.

Enabled ignore files must not be symlinks, including broken links. Sprawl Guard reports an error instead of reading rules from the link’s target.

Field Meaning
respect_gitignore Respect .gitignore files.
respect_ignore Respect .ignore files.
respect_rgignore Respect .rgignore files.
respect_fdignore Respect .fdignore files.
skip_hidden Skip dot-prefixed file and directory names; Windows hidden attributes do not affect selection.

The scan always leaves out .git, whatever skip_hidden says.

Field Type and default Meaning
follow_symlinks enum, "none" none, files, directories, or files-and-directories.
same_file_system boolean, true Stay on the root’s filesystem.
max_entries positive integer, 1000000 Maximum visited filesystem entries.
max_parsed_code_file_bytes size, 10485760 (10 MiB) Largest source file whose code lines Sprawl Guard counts.
unreadable_paths enum, "fail" fail or warn for gaps in what check could analyze.

Sprawl Guard doesn’t count the lines of a source file larger than max_parsed_code_file_bytes. check lists the file and keeps checking everything else. Exclude large generated files instead of raising the limit. This setting protects the line counter and is not a policy. To fail check on large files, set [limits].max_bytes_per_file.

Paths below the root that can’t be read and source files too large to count are gaps in the analysis. check reports every gap along with every violation. With unreadable_paths = "fail", any gap makes check exit 2. With "warn", gaps are warnings, and violations alone decide the exit code. update and tighten refuse to write the ratchet file after an unreadable path under either setting.

max_file_bytes is a deprecated name for max_parsed_code_file_bytes and still loads. Run sprawl-guard config upgrade --write to rename it; setting both names is an error. The configuration schema accepts the old name and marks it as deprecated, so editors that use the schema show a warning.

extend_exclude is an array of repository-relative globs. Matching paths are removed before any language claims them. Like every extend_* field, it adds to the built-in list instead of replacing it.

The built-in exclusions are the lockfile-related patterns from GitHub’s code-review exclusions, matched at any depth:

**/*.lock **/bun.lockb **/go.sum
**/npm-shrinkwrap.json **/package-lock.json **/Package.resolved
**/pnpm-lock.yaml

check is a boolean that defaults to true. When false, test files are not checked. globs lists the patterns that mark test files. Setting it replaces these defaults:

sprawl-guard.toml
[tests]
globs = [
"tests/**",
"**/tests/**",
"test/**",
"**/test/**",
"spec/**",
"**/spec/**",
"__tests__/**",
"**/__tests__/**",
"__mocks__/**",
"**/__mocks__/**",
"**/*.test.*",
"**/*.spec.*",
"**/*_test.*",
"**/*_spec.*",
]
Field Type and default Meaning
enabled boolean, true Enable or disable this language.
include optional array of globs Replace the language’s bundled paths.
extend_include array of globs, [] Add paths to the language’s bundled paths.
exclude array of globs, [] Remove matching paths for this language.
test_globs array of globs, [] More globs that mark test files. Rust defaults to ["benches/**"].
exclude_cfg_test boolean, true for Rust Stop counting top-level Rust cfg(test) items in production files. Rust only.

Every Tokei language is enabled by default. Under [languages.<id>.limits.max_lines_per_file], production, test, and count_lines are optional. Each replaces the corresponding global value, and count_lines also replaces the automatic comments for literate languages. Run sprawl-guard languages to list all supported IDs and their bundled paths. IDs are case-insensitive.

Custom language groups give related languages one shared direct-file count and limit per directory. languages is a non-empty array of distinct supported language IDs. A language may belong to at most one custom group, and disabled languages may remain listed.

sprawl-guard.toml
[language_groups.frontend]
languages = ["javascript", "typescript", "jsx", "tsx"]
[language_groups.frontend.limits.max_direct_files_per_directory]
production = 12
test = 20

Omitted custom-group limit fields inherit their global values. Languages outside custom groups are assigned automatically: Tokei literate languages use documentation, and all others use source. The source group uses the global directory limits and cannot be configured directly.

The documentation group has unlimited direct files by default. Its table cannot declare languages, but a custom group may list a literate language, which replaces that language’s automatic assignment. Documentation-group limits can be made finite:

sprawl-guard.toml
[language_groups.documentation.limits.max_direct_files_per_directory]
production = 20
Field Type Meaning
paths non-empty array of globs Repository-relative paths matched by the override.
reason non-empty string Why the override exists.
max_lines_per_file.production optional positive integer Production file limit.
max_lines_per_file.test optional positive integer Test file limit.
max_direct_files_per_directory.production optional positive integer or "unlimited" Production direct-file limit.
max_direct_files_per_directory.test optional positive integer or "unlimited" Test direct-file limit.
max_bytes_per_file optional size or "unlimited" Byte limit for matching files (other than Git LFS files).
max_bytes_per_lfs_object optional size or "unlimited" Byte limit for matching Git LFS files.

Each override must set at least one limit. Matching entries apply in order, and later entries replace only the fields they set.

sprawl-guard.toml
[[overrides]]
paths = ["vendor/**"]
max_lines_per_file = { production = 1200, test = 1600 }
max_direct_files_per_directory = { production = 20, test = "unlimited" }
reason = "Upstream layout"
[[overrides]]
paths = ["assets/**"]
max_bytes_per_file = "500 kB"
reason = "Image budget"
Field Type and default Meaning
file path, "sprawl-guard.ratchet.toml" Repository-relative ratchet file.
require_current boolean, true Fail checks when ratchet entries are stale.

This section names the ratchet file and whether check fails on stale entries. The ceilings themselves live in the ratchet file. See Record existing violations to create it.

Field Type and default Meaning
format enum, "human" human, json, sarif, or github.
max_findings positive integer or "unlimited", 50 Most findings that human and GitHub output list from check.

Only check reads [output]. check --format and check --max-findings take precedence. Other commands default to human output.

max_findings counts violations first, then warnings, then skipped unreadable paths, so a failing check always lists why it failed. It also bounds how many files a directory finding names, and how many paths the report lists when unreadable paths stop the check. Findings past the cap still count toward their group’s total, a footer gives how many findings were shown out of the total, and the exit status still reflects every violation. Recorded violations within their ratchet ceilings are not findings, so they never count. JSON and SARIF output always list every finding.

Every glob in the configuration is matched against a file’s whole path, relative to the repository root and written with /.

Pattern Matches
* Any text within one path component. src/*.rs skips src/a/b.rs.
? One byte within one path component, so one ASCII character.
** Any number of path components, when it is a whole component: src/**.
[ab] One of the listed characters.
{a,b} Either alternative.
foo.rs Only foo.rs in the root. Write **/foo.rs to match it anywhere.

Unlike a .gitignore line, a pattern is never matched against a file’s name alone, and a trailing / does not select a directory’s contents. Write generated/**.

Sprawl Guard applies configuration in this order:

  1. Built-in defaults come first. Fields in the root configuration replace the corresponding defaults.
  2. Arrays in the root configuration replace their default arrays, except extend_* fields, which add to them. [files].extend_exclude extends the built-in lockfile excludes.
  3. Language-specific file limits and count_lines replace their global values. For literate languages, Sprawl Guard adds comments automatically unless a language-specific count_lines is set.
  4. Custom-group directory limits replace their global values. Documentation directory limits start from their unlimited defaults.
  5. Matching path overrides apply in declaration order. Later entries replace only the fields they set.
  6. CLI options override the output format, whether check fails on stale entries, unreadable-path handling, root, and configuration path for that run.
© 2026 Konstantin Pozin