ruff format --diff: Preview Formatting Changes
ruff format --diff shows exactly how the formatter would rewrite each file, as a unified diff, without touching disk.
When --check tells you a file is wrong but not how, --diff shows the precise edits. It is the read-only way to see the formatter at work.
What it does
ruff format --diff computes the formatted output and prints a unified diff against the current contents for every file that would change. It writes nothing and, like --check, exits non-zero if any file would be reformatted.
Common usage
ruff format --diff .
ruff format --diff src/app.py
# capture the diff for a PR comment
ruff format --diff . > format.diffFlags
| Flag | What it does |
|---|---|
| --diff | Print formatting changes as a unified diff; do not write |
| <paths> | Files or directories to diff |
| --line-length <n> | Override line length for the diff |
| --target-version <ver> | Target Python version for the diff |
In CI
Use --diff in a workflow that posts the formatting changes back as a PR annotation so contributors can see and apply them. Because it shares --check exit semantics, it doubles as a gate that also explains itself.
Common errors in CI
An empty diff with exit 0 means everything is already formatted. A large unexpected diff usually means the runner Ruff version differs from the developer version; the formatter style can shift between releases, so pin the version. A parse error prints to stderr and produces no diff for that file.