ruff Formatting

Expert knowledge for using ruff format as an extremely fast Python code formatter with Black compatibility.

When to Use This Skill

Core Expertise

ruff format Advantages

• 10-30x faster than Black
• Drop-in Black replacement (99.9% compatible)
• Written in Rust for performance
• Supports Black's configuration options
• Format checking and diff preview
• Respects .gitignore automatically

Basic Usage

Simple Formatting

# Format current directory
ruff format

# Format specific files or directories
ruff format path/to/file.py
ruff format src/ tests/

# IMPORTANT: Pass directory as parameter to stay in repo root
ruff format services/orchestrator

Format Checking

# Check if files are formatted (exit code 1 if not)
ruff format --check

# Show diff without modifying files
ruff format --diff

# Check specific files
ruff format --check src/ tests/

# Preview changes before applying
ruff format --diff services/orchestrator
ruff format services/orchestrator  # Apply after review

Selective Formatting

# Format only Python files
ruff format src/**/*.py

# Format excluding tests
ruff format --exclude tests/

# Format only changed files (git)
git diff --name-only --diff-filter=d | grep '\.py$' | xargs ruff format

# Format files in specific directory
ruff format src/core/ src/utils/

Configuration

pyproject.toml

[tool.ruff]
line-length = 88
target-version = "py39"

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false
line-ending = "auto"
docstring-code-format = true
docstring-code-line-length = "dynamic"
exclude = [
    "*.pyi",
    "**/__pycache__",
    "**/node_modules",
    ".venv",
]

ruff.toml (standalone)

line-length = 88

[format]
quote-style = "single"
indent-style = "space"
skip-magic-trailing-comma = false
docstring-code-format = true

Black Compatibility

[tool.ruff]
line-length = 88
indent-width = 4
target-version = "py39"

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false
line-ending = "auto"

Format Workflow

1. Preview: ruff format --diff (see changes)
2. Check: ruff format --check (CI validation)
3. Apply: ruff format (modify files)
4. Verify: ruff format --check (confirm)

Best Practices

• Pass directory parameter directly: ruff format src/
• Preview changes first with --diff
• Use one formatter per project (ruff format replaces Black)
• Exclude generated files in pyproject.toml
• Keep pre-commit config in sync with formatter choice
• Enable docstring-code-format for better docs

Agentic Optimizations

Quick Reference

Essential Commands

ruff format                         # Format current directory
ruff format path/to/dir             # Format specific directory
ruff format --check                 # Check if formatted
ruff format --diff                  # Show formatting changes
ruff format file1.py file2.py       # Format specific files
ruff format --exclude tests/        # Exclude directory
ruff format --line-length 100       # Override line length

Format vs Check

Configuration Quick Start

Minimal (Black-compatible)

[tool.ruff]
line-length = 88

[tool.ruff.format]
quote-style = "double"
indent-style = "space"

Recommended

[tool.ruff]
line-length = 88
target-version = "py311"

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false
docstring-code-format = true
line-ending = "auto"
exclude = [
    "*.pyi",
    "migrations/**/*.py",
]

For detailed examples, advanced patterns, integration guides, and migration checklists, see [REFERENCE.md](REFERENCE.md).