[fcbwilliams]

What

Two exclusive options on check narrow what is reported to what a change touches:

• --staged reports only violations about files staged in the index, for a pre-commit hook.
• --base <rev> reports only violations about files changed by the commits since the merge base of <rev> and HEAD, for a pre-push hook or a pull request.

runChecks takes the same narrowing as files and echoes it in the result.

Every check still reads the whole workspace, so cross-file checks keep their full view; only what is reported is narrowed:

• A violation is reported when the file it names changed, or, if it names a directory (single-storybook's .storybook), when a file under that directory changed.
• A violation about the repository's settings is always reported.
• A violation naming a path that does not exist (a missing config, a pattern) cannot be tied to a change, so it is always reported rather than hidden.

The changed files come from git diff --name-only --no-renames --relative -z. A rename counts as both paths, a deletion counts, and paths are relative to --cwd. An empty --base, or one starting with -, is refused. When git fails, the error says what git said and why the run needed it.

The README section Checking only what changed covers the hook setup and the limits. It recommends running --staged directly from .husky/pre-commit, because lint-staged skips commits that only delete files. It also notes that a scoped run cannot see a change that breaks a check at a file it did not touch, so CI should still run the full check.

Why

A repository adopting a check today has to fix every existing violation before it can commit anything, because the tool judges the whole tree. Scoped runs let a hook block only the violations a change introduces, and the full run stays in CI. This came up in an assessment of using this tool for deterministic pre-commit enforcement, where the lack of a staged or changed-files mode was the main gap.

Tests

• CLI (cli-command.integration.test.ts, git fixtures): staged files only, a staged deletion, --base reporting only the branch's own changes (merge-base semantics, including a base branch that moved on), a --cwd subdirectory with JSON files, refusal of both flags together, an empty base, an option-like base and an unknown revision.
• runChecks: narrowing, directory violations, violations at missing paths and settings violations.

pnpm lint:check, pnpm typecheck and pnpm test pass locally.

🤖 Generated with Claude Code