ruff Formatting

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

When to Use This Skill

| Use this skill when... | Use another tool instead when... | |------------------------|----------------------------------| | Formatting Python files | Linting for code issues (use ruff check) | | Checking format compliance in CI | Type checking (use basedpyright) | | Migrating from Black | Detecting dead code (use vulture/deadcode) | | Setting up format-on-save | Running tests (use pytest) |

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

| Context | Command | |---------|---------| | Format directory | ruff format src/ | | Check formatting | ruff format --check | | Show diff | ruff format --diff | | CI check + diff | ruff format --check --diff | | Format + lint | ruff format && ruff check | | Format changed files | git diff --name-only --diff-filter=d \| grep '\.py$' \| xargs ruff format |

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

| Command | Purpose | Exit Code | Modifies Files | |---------|---------|-----------|----------------| | ruff format | Format files | 0 | Yes | | ruff format --check | Validate formatting | 1 if unformatted | No | | ruff format --diff | Show changes | 0 | No | | ruff format --check --diff | Validate + show | 1 if unformatted | No |

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.