Feature: scan staged (git index) content for pre-commit; document --diff vs working tree

[Akshay090]

Problem

For pre-commit hooks we need to lint exactly what will be committed (the git index), not necessarily the current working tree.

Current behavior:

• --diff (see packages/react-doctor/src/utils/get-diff-files.ts) uses either all uncommitted changes vs HEAD (git diff --name-only … HEAD) or branch vs merge-base, not git diff --cached.
• The programmatic API’s diagnose(directory, { includePaths }) passes paths to oxlint, which reads those files from disk. If a file is partially staged, the working tree can differ from the index, so diagnostics may not match the staged snapshot.

We ran into this when wiring react-doctor into a pre-commit flow: paths came from the index (git diff --cached --name-only) but oxlint still read the on-disk file, so a bad staged hunk could be missed when the working tree had been reverted locally.

Suggested directions (maintainer’s choice)

1. CLI flag such as --staged / --cached that:

   • Resolves the file set with git diff --cached --name-only (with appropriate diff-filter), and
   • Ensures lint runs against index content (e.g. materialize git show :path to temp files, or another approach that fits the oxlint pipeline).

2. Documentation that states explicitly:

   • --diff is not “staged-only,” and
   • For pre-commit, users may need git stash push --keep-index, or to skip when partially staged, or another documented pattern.

3. If docs mention running alongside lint-staged, clarify that child processes still read disk unless the tree is explicitly aligned to the index—lint-staged does not automatically fix that for arbitrary subprocesses.

Related

• Is it possible to run react doctor as a pre-commit hook? #74 — pre-commit and confusion with --diff vs branch diffs

Environment (fill if helpful)

• react-doctor version: (e.g. npm lockfile)
• OS: macOS / Linux / Windows