--diff <ref> — PR-scoped findings

On a codebase with non-trivial existing debt, a full doctor run surfaces dozens of warnings that the current PR didn't introduce. Most of them are legitimate but they drown the signal. --diff <ref> narrows the report to files touched since a git reference.

Usage

./manage.py doctor --diff origin/main

What it does, in order:

1. Asks git for every file that differs from <ref>: committed changes (git diff --name-only <ref>...HEAD), unstaged modifications (git diff --name-only), and new files (git ls-files --others --exclude-standard).
2. Filters findings: keep a finding if its location references one of those files.
3. Findings with no resolvable file path (e.g. views.unguarded on users:login) are kept — we'd rather over-report than silently drop them.

CI recipe — PR-only gate

# .github/workflows/doctor.yml — fails the PR on new findings only
- name: django-doctor (PR-scoped)
  run: |
    ./manage.py doctor \
      --diff origin/${{ github.base_ref }} \
      --ci \
      --html doctor-report.html

Combined with --ci, the exit code reflects the filtered findings, so existing debt doesn't block merges — only regressions do.

Combining with --section

--diff filters after checks run, so it composes with --section:

./manage.py doctor --section templates,views --diff origin/main

is the quickest way to audit a PR that touches templates and views.

Programmatic use

from django_doctor.diff import changed_files, filter_by_diff

files = changed_files("origin/main")
filtered = filter_by_diff(results, "origin/main")