# Get started

Install Sprawl Guard, check a repository, and record the violations it already has.

Commands on this page run `sprawl-guard` as installed with Cargo or Homebrew. If you installed Sprawl Guard with pnpm, npm, or uv, replace `sprawl-guard` with `pnpm exec sprawl-guard`, `npm exec -- @kpozin/sprawl-guard`, or `uv run sprawl-guard`.

## 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**

```sh
pnpm add --save-dev @kpozin/sprawl-guard
```

Command 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**

```sh
npm install --save-dev @kpozin/sprawl-guard
```

Command 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**

```sh
uv add --dev sprawl-guard
```

Command 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**

```sh
cargo install sprawl-guard
```

**Homebrew**

```sh
brew install kpozin/tap/sprawl-guard
```

Homebrew 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](/sprawl-guard/run-in-ci.md#run-the-check-before-you-commit).
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](https://github.com/kpozin/sprawl-guard/blob/main/SECURITY.md#verify-a-release).

## Check a repository

Run these commands from the repository root.

1. Create the configuration file, `sprawl-guard.toml`.

   ```sh title="Initialize a repository"
   sprawl-guard init
   sprawl-guard init --write
   ```

   The 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](/sprawl-guard/configure-checks.md). If the project already uses an ESLint or
   Oxlint `max-lines` rule, you can
   [start from that rule](#start-from-a-max-lines-rule) instead.

2. Run the check.

   ```sh title="Run the first check"
   sprawl-guard check
   ```

   A passing check prints:

   ```text
   Configuration: sprawl-guard.toml

   No 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:

   ```text
   Configuration: sprawl-guard.toml

   Files 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](/sprawl-guard/run-in-ci.md).

## 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.

1. Preview the violations to record.

   ```sh
   sprawl-guard update
   ```

   ```text
   Ratchet changes:
   + add src/large.py (production lines): none -> 430
   + add src/flat (production direct files, group: source): none -> 12

   Preview only; use --write to apply.
   ```

   A directory entry also names the language group whose files it counts, as
   [How checks work](/sprawl-guard/reference/how-checks-work.md) explains.

   If the list includes generated or third-party code, exclude those paths in
   [the configuration](/sprawl-guard/configure-checks.md#choose-which-files-to-check) and preview
   again.

2. Write the ratchet file and run the check.

   ```sh
   sprawl-guard update --write
   sprawl-guard check
   ```

   ```text
   Configuration: sprawl-guard.toml

   No sprawl-guard violations found.
   Checked 14 source files in 2 directories across 1 language.
   Passed with 2 ratchet entries remaining.
   ```

3. Commit `sprawl-guard.toml` and `sprawl-guard.ratchet.toml` together.

Next, [add the check to CI](/sprawl-guard/run-in-ci.md), then read
[Work with the ratchet](/sprawl-guard/ratchet.md) to see how to record improvements.

## 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.

**ESLint**

1. 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:

   ```sh
   sprawl-guard config import eslint src/index.js
   sprawl-guard config import --write eslint src/index.js
   ```

2. Preview [ratchet entries](#record-existing-violations) for the oversized files that ESLint
   exempts, then save them:

   ```sh
   sprawl-guard update --import eslint
   sprawl-guard update --import eslint --write
   ```

**Oxlint**

1. Preview a configuration based on the rule, then save it:

   ```sh
   sprawl-guard config import oxlint
   sprawl-guard config import --write oxlint
   ```

2. Preview [ratchet entries](#record-existing-violations) for the oversized files that Oxlint
   exempts, then save them:

   ```sh
   sprawl-guard update --import oxlint
   sprawl-guard update --import oxlint --write
   ```

3) 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.

4) Preview the remaining violations with `sprawl-guard update`, and fix any that you don't want to
   accept. Then [record the rest](#record-existing-violations) with `sprawl-guard update --write`.

5) Remove the `max-lines` rule from the linter's configuration, then commit that change together
   with `sprawl-guard.toml` and `sprawl-guard.ratchet.toml`.

The CLI reference explains how Sprawl Guard
[reads the rule](/sprawl-guard/reference/cli-and-output.md#config-import-eslintoxlint) and
[which exemptions it imports](/sprawl-guard/reference/cli-and-output.md#update-paths).
