ruff-formatting — laurigates/claude-plugins…

Document Skill original

Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.

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

bash

# 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

bash

# 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

bash

# 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

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)

toml

line-length = 88

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

Black Compatibility

toml

[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

Preview: ruff format --diff (see changes)
Check: ruff format --check (CI validation)
Apply: ruff format (modify files)
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

bash

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)

toml

[tool.ruff]
line-length = 88

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

Recommended

toml

[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.