Diff mode scans only files that changed compared to a base branch, making React Doctor extremely fast even in large codebases.
Quick Start
Run with --diff to scan only changed files:
npx react-doctor . --diff
- Detects your current branch
- Finds the base branch (usually
main or master)
- Identifies changed source files
- Scans only those files
Diff mode uses Git to detect changes. Your project must be a Git repository.
How Diff Mode Works
React Doctor compares your current state to a base branch:
Detect Git repository
Verifies the directory is a Git repo
Identify base branch
Looks for main or master branch
Get changed files
Runs git diff --name-only to find modified files
Filter source files
Includes only .ts, .tsx, .js, .jsx files
Run checks
Scans only the filtered changed files
Diff mode is much faster than full scans. Use it in CI/CD, pre-commit hooks, and during development.
Specifying Base Branch
Override the auto-detected base branch:
npx react-doctor . --diff develop
develop branch instead of main.
Common Use Cases
# Compare to main
npx react-doctor . --diff main
# Compare to master
npx react-doctor . --diff master
# Compare to develop
npx react-doctor . --diff develop
# Compare to specific commit
npx react-doctor . --diff abc123
Uncommitted Changes
If you have uncommitted changes, React Doctor detects them:
npx react-doctor . --diff
# Found 5 uncommitted changed files. Only scan current changes? (Y/n)
Uncommitted changes mode compares your current state to the last commit (HEAD).
Feature Branch Detection
When you’re on a feature branch, React Doctor asks:
npx react-doctor . --diff
# On branch feat/login (12 changed files vs main). Only scan this branch? (Y/n)
Forcing Diff Mode
Pin diff mode in your config to always scan only changes:
Or specify a base branch:
CLI flags override config. Running npx react-doctor . (without --diff) will still do a full scan even if diff is in the config.
Disabling Auto-Detection
Preventing React Doctor from prompting about diff mode:
This disables automatic detection and prompts.
Diff Mode in CI/CD
Diff mode is ideal for pull request checks:
GitHub Actions
.github/workflows/react-doctor.yml
name: React Doctor
on:
pull_request:
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
with:
fetch-depth: 0 # Required for diff mode
- uses: millionco/react-doctor@main
with:
diff: main
github-token: ${{ secrets.GITHUB_TOKEN }}
Set fetch-depth: 0 to fetch full Git history. React Doctor needs this to compare branches.
GitLab CI
react-doctor:
stage: test
script:
- npx react-doctor . --diff $CI_MERGE_REQUEST_TARGET_BRANCH_NAME
only:
- merge_requests
Bitbucket Pipelines
pipelines:
pull-requests:
'**':
- step:
name: React Doctor
script:
- git fetch origin $BITBUCKET_PR_DESTINATION_BRANCH
- npx react-doctor . --diff origin/$BITBUCKET_PR_DESTINATION_BRANCH
Diff Mode Limitations
Dead Code Detection Skipped
Dead code analysis requires scanning the entire codebase to detect unused exports. React Doctor automatically skips dead code detection in diff mode:
npx react-doctor . --diff
# Only runs lint checks on changed files
Context-Dependent Rules
Some issues span multiple files. Diff mode may miss:
- Unused props passed from unchanged parent components
- Missing imports in unchanged files
- Type errors in unchanged files that depend on changed files
Run full scans periodically (e.g., on merge to main) to catch context-dependent issues.
Git Integration
React Doctor uses standard Git commands:
Current Branch Detection
git rev-parse --abbrev-ref HEAD
Base Branch Detection
git rev-parse --verify main
git rev-parse --verify master
master if main doesn’t exist.
Changed Files
git diff --name-only main...HEAD
Uncommitted Changes
git diff --name-only HEAD
React Doctor requires Git 2.0+ for proper diff detection.
Pre-Commit Hooks
Run React Doctor on staged files before committing:
Using Husky
Install Husky:
npm install --save-dev husky
npx husky init
#!/usr/bin/env sh
npx react-doctor . --diff --no-ami
--no-ami flag skips interactive prompts.
Using lint-staged
For more control, use lint-staged:
npm install --save-dev lint-staged husky
package.json:
{
"lint-staged": {
"*.{ts,tsx,js,jsx}": [
"npx react-doctor . --diff --no-ami"
]
}
}
#!/usr/bin/env sh
npx lint-staged
Pre-commit hooks can slow down commits if scans take too long. Consider using diff mode or --score for faster feedback.
Combining with Other Flags
Diff + Verbose
See which files have issues:
npx react-doctor . --diff --verbose
Diff + Project
Scan only changed files in a specific monorepo project:
npx react-doctor . --project web --diff
Diff + Score
Get only the score for changed files:
npx react-doctor . --diff --score
SCORE=$(npx react-doctor . --diff --score)
if [ "$SCORE" -lt 75 ]; then
echo "Score too low: $SCORE"
exit 1
fi
Troubleshooting Diff Mode
”No feature branch or uncommitted changes detected”
You’re on the base branch (main/master) with no changes. Diff mode falls back to full scan.
To use diff mode:
- Create a feature branch:
git checkout -b feat/my-feature
- Make changes and commit
- Run
npx react-doctor . --diff
”fetch-depth: 0 required” in CI
GitHub Actions checks out only the latest commit by default. Add:
- uses: actions/checkout@v5
with:
fetch-depth: 0
Diff Mode Finds No Files
If no source files changed:
npx react-doctor . --diff
# No changed source files, skipping.
Base Branch Not Found
If React Doctor can’t find main or master:
npx react-doctor . --diff develop
Best Practices
1. Use Diff Mode in CI
Scan only PR changes for fast feedback:
- uses: millionco/react-doctor@main
with:
diff: main
2. Run Full Scans on Main
Catch issues missed by diff mode:
on:
push:
branches:
- main
jobs:
scan:
steps:
- uses: millionco/react-doctor@main
# No diff flag = full scan
3. Use Diff Mode During Development
Get instant feedback while coding:
npx react-doctor . --diff --verbose
4. Combine with Monorepo Project Selection
Maximum speed in large monorepos:
npx react-doctor . --project web --diff
Diff mode + project selection is the fastest way to get feedback in large codebases.