Files
ruff/python/ruff-ecosystem/README.md
Zanie Blueandzaniebot 589433f2ed Add HTML reports for Ruff ecosystem checks (#29629)
Ruff ecosystem comments can omit details from large linter diffs.
Generate HTML reports alongside the Markdown results for linter and
formatter runs, with project filters, search, and paginated browsing.
Linter reports also support filtering by rule; formatter reports include
hunk context.

Link the available reports from the PR comment through the shared
publisher, retaining the downloadable artifact.

Co-authored-by: zaniebot <242828183+zaniebot@users.noreply.github.com>
2026-10-28 19:10:52 -04:00

64 lines
1.8 KiB
Markdown

# ruff-ecosystem
Compare lint and format results for two different ruff versions (e.g. main and a PR) on real world projects.
## Installation
From the Ruff project root, install with [uv](https://docs.astral.sh/uv/):
```shell
uv tool install -e ./python/ruff-ecosystem
```
## Usage
```shell
ruff-ecosystem <check | format> <baseline executable> <comparison executable>
```
Note executable paths may be absolute, relative to the current working directory, or will be looked up in the
current Python environment and PATH.
Run `ruff check` ecosystem checks comparing your debug build to your system Ruff:
```shell
ruff-ecosystem check ruff "./target/debug/ruff"
```
Run `ruff format` ecosystem checks comparing your debug build to your system Ruff:
```shell
ruff-ecosystem format ruff "./target/debug/ruff"
```
Run `ruff format` ecosystem checks comparing with changes to code that is already formatted:
```shell
ruff-ecosystem format ruff "./target/debug/ruff" --format-comparison ruff-then-ruff
```
Run `ruff format` ecosystem checks comparing with the Black formatter:
```shell
ruff-ecosystem format black ruff -v --cache python/checkouts --format-comparison black-and-ruff
```
The default output format is markdown, which includes nice summaries of the changes. You can use `--output-format json` to display the raw data — this is
particularly useful when making changes to the ecosystem checks.
Add `--html-output report.html` to also write a searchable HTML report containing all changes.
## Development
When developing, it can be useful to set the `--pdb` flag to drop into a debugger on failure:
```shell
ruff-ecosystem check ruff "./target/debug/ruff" --pdb
```
You can also provide a path to cache checkouts to speed up repeated runs:
```shell
ruff-ecosystem check ruff "./target/debug/ruff" --cache ./repos
```