ruff CLI

The Ruff binary. Source: crates/ruff/.

Purpose

ruff is the user-facing CLI for the Ruff linter and formatter. It dispatches to subcommands, resolves configuration, discovers files, and parallelizes work via rayon.

Directory layout

crates/ruff/src/
├── main.rs               # binary entry point
├── lib.rs                # re-exports
├── args.rs               # clap definitions for top-level + subcommands
├── commands/             # one module per subcommand
│   ├── check.rs
│   ├── format.rs
│   ├── analyze/
│   ├── clean.rs
│   ├── config.rs
│   ├── linter.rs
│   ├── rule.rs
│   ├── server.rs
│   └── version.rs
├── cache.rs              # incremental cache (.ruff_cache)
├── diagnostics.rs        # diagnostic aggregation
├── printer.rs            # text/JSON/GitHub/SARIF/Junit/etc. output formats
├── resolve.rs            # workspace + file discovery
└── stdin.rs              # `-` / `--stdin-filename` plumbing

Key abstractions

Type	File	Purpose
Args, Command	crates/ruff/src/args.rs	clap definitions; Command is the enum of subcommands.
cache::Cache	crates/ruff/src/cache.rs	Per-package cache stored under .ruff_cache/.
printer::Printer	crates/ruff/src/printer.rs	Output adapter; switches on --output-format.
commands::check::check	crates/ruff/src/commands/check.rs	Top-level ruff check driver.
commands::format::format	crates/ruff/src/commands/format.rs	Top-level ruff format driver.
resolve::resolve_settings	crates/ruff/src/resolve.rs	Walks up to find config, applies --config/--extend.

Subcommands

Subcommand	Description
check	Lint files. Default subcommand for backward compatibility.
format	Format files (or check formatting with --check).
server	Start the Ruff LSP server (delegates to crates/ruff_server).
analyze graph	Print the import graph for a project.
clean	Clean cache directories.
config	Inspect resolved configuration.
linter	List enabled lint rules / categories.
rule	Print documentation for a single rule (ruff rule F401).
version	Print the CLI version.
help / help check / help format	Subcommand help.

How ruff check works

1. Parse args. clap macro on Args deserializes the command line into a Command::Check(CheckCommand).
2. Resolve settings. resolve::resolve_settings walks from the working directory up looking for pyproject.toml, ruff.toml, or .ruff.toml. Per-file overrides are layered on at lint time.
3. Discover files. ignore::WalkBuilder walks the file system honoring .gitignore, .ignore, and Ruff's exclude settings.
4. Parallelize. rayon::par_iter over the file list. For each file:
   • Read source.
   • Parse with ruff_python_parser.
   • Lint with ruff_linter::check_path.
   • Optionally apply autofixes (--fix, --unsafe-fixes) and write the file back.
5. Aggregate. Diagnostics are collected, sorted by file and line, deduplicated.
6. Output. printer::Printer formats according to --output-format (text, concise, json, json-lines, junit, grouped, github, gitlab, sarif, azure, pylint).

Output formats

The text format uses ruff_annotate_snippets for source-code snippets with carets and colors. The --output-format flag is a one-stop shop for CI integration:

ruff check --output-format github         # for GitHub Actions
ruff check --output-format sarif > out.sarif
ruff check --output-format json

Caching

Cache files live under .ruff_cache/ (the directory is gitignored by default). The cache key combines the file content hash, the resolved Settings, and the Ruff version. Hits skip parsing entirely.

ruff clean removes the cache; --no-cache disables reads/writes for a single run.

Stdin mode

echo "import os" | ruff check --stdin-filename foo.py -

Stdin mode is used by editor integrations that pre-date the LSP and by some CI setups. The --stdin-filename argument tells Ruff what name to use for diagnostics.

Entry points for modification

• Add a subcommand: extend Command in args.rs, add a module to commands/, dispatch from main.rs.
• Add an output format: extend OutputFormat in args.rs, add a printer variant in printer.rs.
• Change file discovery: tweak resolve.rs and the ignore integration.
• Tweak caching: cache shape lives in cache.rs.

For LSP behavior, see ruff_server. For the linter algorithm itself, see ruff_linter.