Get started
Install
Section titled “Install”Add Sprawl Guard to a Node.js project (Node.js 22 or newer) or a Python project, or install the command-line tool with Cargo or Homebrew:
pnpm add --save-dev @kpozin/sprawl-guardCommand examples on this site have a pnpm tab. For a command written in the text, such as
sprawl-guard check, type pnpm exec sprawl-guard in place of sprawl-guard.
npm install --save-dev @kpozin/sprawl-guardCommand examples on this site have an npm tab. For a command written in the text, such as
sprawl-guard check, type npm exec -- @kpozin/sprawl-guard in place of sprawl-guard.
uv add --dev sprawl-guardCommand examples on this site have a uv tab. For a command written in the text, such as
sprawl-guard check, type uv run sprawl-guard in place of sprawl-guard.
To install Sprawl Guard outside a project, run uv tool install sprawl-guard,
pipx install sprawl-guard, or pip install sprawl-guard. Then type commands as the Cargo and
Homebrew tabs show them.
PyPI has Sprawl Guard for macOS, Windows on x64, Alpine Linux on x64, and other Linux distributions on x64 and Arm from Ubuntu 22.04, Debian 12, and Fedora 36 onward. It has none for Red Hat Enterprise Linux 9, Rocky Linux 9, AlmaLinux 9, or Amazon Linux 2023. If uv or pip can’t find a version that runs on your system, install with Cargo.
cargo install sprawl-guardbrew install kpozin/tap/sprawl-guardHomebrew installs one copy for the whole machine and upgrades it whenever you upgrade your other packages. Use it to try Sprawl Guard or to check repositories that you don’t maintain.
On Linux, the Homebrew copy runs on Ubuntu 22.04, Debian 12, Fedora 36, and later releases. It
doesn’t run on older releases or on Red Hat Enterprise Linux 9, Rocky Linux 9, AlmaLinux 9, or
Amazon Linux 2023. There, sprawl-guard fails with an error that mentions GLIBC; install with
Cargo instead.
If a project’s CI runs Sprawl Guard, your local copy should match the version that CI uses. To
install that version, follow Run in CI.
A Git hook runs the first sprawl-guard on your PATH, which might still be the Homebrew copy. Run
sprawl-guard --version to see which version that is.
To confirm that what you installed came from the Sprawl Guard release workflow, follow Verify a release.
Check a repository
Section titled “Check a repository”Run these commands from the repository root.
-
Create the configuration file,
sprawl-guard.toml.Initialize a repository pnpm exec sprawl-guard initpnpm exec sprawl-guard init --writeInitialize a repository npm exec -- @kpozin/sprawl-guard initnpm exec -- @kpozin/sprawl-guard init --writeInitialize a repository uv run sprawl-guard inituv run sprawl-guard init --writeInitialize a repository sprawl-guard initsprawl-guard init --writeInitialize a repository sprawl-guard initsprawl-guard init --writeThe first command shows the file, and the second writes it. Until you add settings to it, Sprawl Guard uses its built-in limits: 400 lines per file (800 for test files) and 10 source files directly inside each directory. To change them, see Configure checks. If the project already uses an ESLint or Oxlint
max-linesrule, you can start from that rule instead. -
Run the check.
Run the first check pnpm exec sprawl-guard checkRun the first check npm exec -- @kpozin/sprawl-guard checkRun the first check uv run sprawl-guard checkRun the first check sprawl-guard checkRun the first check sprawl-guard checkA passing check prints:
Configuration: sprawl-guard.tomlNo sprawl-guard violations found.Checked 2 source files in 2 directories across 2 languages.A failing check names each file or directory over its limit:
Configuration: sprawl-guard.tomlFiles over the line limit (1):src/large.py: 430 lines (limit 400)language: Python, counting code
If the check passes, commit sprawl-guard.toml and add the check to CI.
Record existing violations
Section titled “Record existing violations”An existing repository usually has files and directories over the limits. Instead of fixing them
all before you can start, record them in a ratchet file, sprawl-guard.ratchet.toml. The check
then allows each recorded violation at its current size. It fails if a recorded violation grows,
and also if it shrinks, until you record the smaller size.
-
Preview the violations to record.
Terminal window pnpm exec sprawl-guard updateTerminal window npm exec -- @kpozin/sprawl-guard updateTerminal window uv run sprawl-guard updateTerminal window sprawl-guard updateTerminal window sprawl-guard updateRatchet changes:+ add src/large.py (production lines): none -> 430+ add src/flat (production direct files, group: source): none -> 12Preview only; use --write to apply.A directory entry also names the language group whose files it counts, as How checks work explains.
If the list includes generated or third-party code, exclude those paths in the configuration and preview again.
-
Write the ratchet file and run the check.
Terminal window pnpm exec sprawl-guard update --writepnpm exec sprawl-guard checkTerminal window npm exec -- @kpozin/sprawl-guard update --writenpm exec -- @kpozin/sprawl-guard checkTerminal window uv run sprawl-guard update --writeuv run sprawl-guard checkTerminal window sprawl-guard update --writesprawl-guard checkTerminal window sprawl-guard update --writesprawl-guard checkConfiguration: sprawl-guard.tomlNo sprawl-guard violations found.Checked 14 source files in 2 directories across 1 language.Passed with 2 ratchet entries remaining. -
Commit
sprawl-guard.tomlandsprawl-guard.ratchet.tomltogether.
Next, add the check to CI, then read Work with the ratchet to see how to record improvements.
Start from a max-lines rule
Section titled “Start from a max-lines rule”If the project already limits file length with the ESLint or Oxlint max-lines rule, you can import
the rule’s limit and the files it exempts. Sprawl Guard runs the project’s own linter with Node.js,
so install the linter in node_modules first. Sprawl Guard is tested with ESLint 8.57 and 10, and
with Oxlint 1.93.
If sprawl-guard.toml already exists, config import --write fails in step 1. Copy the printed
[languages] tables into the file instead.
-
Preview a configuration based on the rule, then save it. ESLint can configure each file differently, so name a source file whose limit you want:
Terminal window pnpm exec sprawl-guard config import eslint src/index.jspnpm exec sprawl-guard config import --write eslint src/index.jsTerminal window npm exec -- @kpozin/sprawl-guard config import eslint src/index.jsnpm exec -- @kpozin/sprawl-guard config import --write eslint src/index.jsTerminal window uv run sprawl-guard config import eslint src/index.jsuv run sprawl-guard config import --write eslint src/index.jsTerminal window sprawl-guard config import eslint src/index.jssprawl-guard config import --write eslint src/index.jsTerminal window sprawl-guard config import eslint src/index.jssprawl-guard config import --write eslint src/index.js -
Preview ratchet entries for the oversized files that ESLint exempts, then save them:
Terminal window pnpm exec sprawl-guard update --import eslintpnpm exec sprawl-guard update --import eslint --writeTerminal window npm exec -- @kpozin/sprawl-guard update --import eslintnpm exec -- @kpozin/sprawl-guard update --import eslint --writeTerminal window uv run sprawl-guard update --import eslintuv run sprawl-guard update --import eslint --writeTerminal window sprawl-guard update --import eslintsprawl-guard update --import eslint --writeTerminal window sprawl-guard update --import eslintsprawl-guard update --import eslint --write
-
Preview a configuration based on the rule, then save it:
Terminal window pnpm exec sprawl-guard config import oxlintpnpm exec sprawl-guard config import --write oxlintTerminal window npm exec -- @kpozin/sprawl-guard config import oxlintnpm exec -- @kpozin/sprawl-guard config import --write oxlintTerminal window uv run sprawl-guard config import oxlintuv run sprawl-guard config import --write oxlintTerminal window sprawl-guard config import oxlintsprawl-guard config import --write oxlintTerminal window sprawl-guard config import oxlintsprawl-guard config import --write oxlint -
Preview ratchet entries for the oversized files that Oxlint exempts, then save them:
Terminal window pnpm exec sprawl-guard update --import oxlintpnpm exec sprawl-guard update --import oxlint --writeTerminal window npm exec -- @kpozin/sprawl-guard update --import oxlintnpm exec -- @kpozin/sprawl-guard update --import oxlint --writeTerminal window uv run sprawl-guard update --import oxlintuv run sprawl-guard update --import oxlint --writeTerminal window sprawl-guard update --import oxlintsprawl-guard update --import oxlint --writeTerminal window sprawl-guard update --import oxlintsprawl-guard update --import oxlint --write
-
Run
sprawl-guard check, and compare its results with the linter’s. The two tools count lines slightly differently. The check also applies limits that the linter doesn’t: the number of files directly inside each directory, and the length of files in other languages. -
Preview the remaining violations with
sprawl-guard update, and fix any that you don’t want to accept. Then record the rest withsprawl-guard update --write. -
Remove the
max-linesrule from the linter’s configuration, then commit that change together withsprawl-guard.tomlandsprawl-guard.ratchet.toml.
The CLI reference explains how Sprawl Guard reads the rule and which exemptions it imports.