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:
#:schema https://kpozin.github.io/sprawl-guard/schemas/v2/sprawl-guard.schema.jsonschema_version = 2Run 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.
Editor support
Section titled “Editor support”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.
Upgrade the configuration
Section titled “Upgrade the configuration”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.
Sections and defaults
Section titled “Sections and defaults”[limits]
Section titled “[limits]”| 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.
Git LFS files
Section titled “Git LFS files”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.
[limits.max_lines_per_file]
Section titled “[limits.max_lines_per_file]”| 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.
[limits.max_direct_files_per_directory]
Section titled “[limits.max_direct_files_per_directory]”| 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. |
[ignore]
Section titled “[ignore]”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.
[traversal]
Section titled “[traversal]”| 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.
[files]
Section titled “[files]”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[tests]
Section titled “[tests]”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:
[tests]globs = [ "tests/**", "**/tests/**", "test/**", "**/test/**", "spec/**", "**/spec/**", "__tests__/**", "**/__tests__/**", "__mocks__/**", "**/__mocks__/**", "**/*.test.*", "**/*.spec.*", "**/*_test.*", "**/*_spec.*",][languages.<id>]
Section titled “[languages.<id>]”| 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.
[language_groups.<name>]
Section titled “[language_groups.<name>]”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.
[language_groups.frontend]languages = ["javascript", "typescript", "jsx", "tsx"]
[language_groups.frontend.limits.max_direct_files_per_directory]production = 12test = 20Omitted 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:
[language_groups.documentation.limits.max_direct_files_per_directory]production = 20[[overrides]]
Section titled “[[overrides]]”| 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.
[[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"[ratchet]
Section titled “[ratchet]”| 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.
[output]
Section titled “[output]”| 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.
Glob patterns
Section titled “Glob patterns”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/**.
Precedence
Section titled “Precedence”Sprawl Guard applies configuration in this order:
- Built-in defaults come first. Fields in the root configuration replace the corresponding defaults.
- Arrays in the root configuration replace their default arrays, except
extend_*fields, which add to them.[files].extend_excludeextends the built-in lockfile excludes. - Language-specific file limits and
count_linesreplace their global values. For literate languages, Sprawl Guard adds comments automatically unless a language-specificcount_linesis set. - Custom-group directory limits replace their global values. Documentation directory limits start from their unlimited defaults.
- Matching path overrides apply in declaration order. Later entries replace only the fields they set.
- CLI options override the output format, whether
checkfails on stale entries, unreadable-path handling, root, and configuration path for that run.