https://prek.j178.dev/configuration/?h=prek.toml#configuration-file
Gemini can make mistakes so double check it.
The decision to migrate from a traditional .pre-commit-config.yaml to a native prek.toml boils down to three core benefits: eliminating YAML structural fragility, unlocking monorepo workspace intelligence, and gaining granular execution control that the legacy framework cannot provide.
Here is exactly what changes for the better when you make the swap:
1. Resilience Over Structural Fragility
YAML is a whitespace-sensitive serialization format. A single accidental space or tab can silent-fail your local lint pipelines or corrupt your configurations.
- Whitespace Immunity: TOML relies entirely on explicit syntax closures ([sections], [[arrays]], and strings). Indentation is completely aesthetic, making it much easier to edit by hand or via automated tools without risking a syntax crash.
- Inline Definitions: Defining quick hooks can be done compactly on a single line rather than forcing massive multi-line structural nesting blocks.
# Clean, readable, and impossible to break with a tab character
hooks = [
{ id = "trailing-whitespace" },
{ id = "end-of-file-fixer" },
{ id = "check-yaml", files = '\.yaml$' }
]
2. Dynamic Monorepo Workspace Traversal
The legacy Python framework operates from a rigid "one repo, one config file" mindset. If you run a large codebase with multiple independent subfolders, mapping paths involves maintaining fragile, unreadable regex boundaries.
prek.toml introduces native Workspace Awareness:
- You can drop independent prek.toml files into your project subdirectories.
- When a developer commits a file inside a subfolder, prek dynamically walks up the tree, isolates the localized sub-configuration, and boots up only the relevant tooling.
- This isolates dependencies cleanly, preventing frontend engineers from needing a heavy Python toolchain built onto their machines just to commit a TypeScript component.
3. Advanced Filtering via Natural Globs
The original framework forces developers to use Python's raw regex syntax for file inclusions and exclusions.
prek.toml handles files using straightforward, standard shell globbing lists. It is significantly faster to write, easier to audit, and more intuitive for team members.
# Traditional YAML Regex (Confusing and prone to parsing bugs)
exclude: ^(dist/|vendor/|.*\.min\.js$)
# Native TOML Globs (Clear, explicit, and highly scannable)
[files]
exclude = { glob = ["dist/**", "vendor/**", "*.min.js"] }
4. Total Priority Execution Control
When running massive lint pipelines across a codebase, you want lightweight structural tests (like syntax checkers or code formatters) to run before heavy, slow static analysis tools (like deep security scanners or type checkers).
While the legacy system executes hooks in a strict, sequential top-to-bottom layout, prek.toml breaks this constraint by allowing you to attach explicit priority flags directly to individual hooks.
[[repos]]
repo = "https://github.com/astral-sh/ruff-pre-commit"
rev = "v0.4.4"
hooks = [
{ id = "ruff-format", priority = "10" }, # Executes immediately in parallel group 10
{ id = "ruff", priority = "50" } # Holds off until formatting steps pass completely
]
5. Built-in, Zero-Dependency Performance
When using prek.toml, you can instantly toggle the core execution logic over to repo = "builtin".
This instructs the engine to completely bypass cloning remote packages, downloading runtimes, or building isolated multi-megabyte virtual environments. It drops down into native, compiled Rust shims built directly into your local prek binary, dropping your pre-commit overhead down to a fraction of a millisecond.
Migration Tip: You can test this instantly without manually rewriting your existing setups. Run prek util yaml-to-toml in your terminal to automatically translate your current .pre-commit-config.yaml layout into a valid prek.toml file.
https://prek.j178.dev/configuration/?h=prek.toml#configuration-file
Gemini can make mistakes so double check it.
The decision to migrate from a traditional .pre-commit-config.yaml to a native prek.toml boils down to three core benefits: eliminating YAML structural fragility, unlocking monorepo workspace intelligence, and gaining granular execution control that the legacy framework cannot provide.
Here is exactly what changes for the better when you make the swap:
1. Resilience Over Structural Fragility
YAML is a whitespace-sensitive serialization format. A single accidental space or tab can silent-fail your local lint pipelines or corrupt your configurations.
2. Dynamic Monorepo Workspace Traversal
The legacy Python framework operates from a rigid "one repo, one config file" mindset. If you run a large codebase with multiple independent subfolders, mapping paths involves maintaining fragile, unreadable regex boundaries.
prek.toml introduces native Workspace Awareness:
3. Advanced Filtering via Natural Globs
The original framework forces developers to use Python's raw regex syntax for file inclusions and exclusions.
prek.toml handles files using straightforward, standard shell globbing lists. It is significantly faster to write, easier to audit, and more intuitive for team members.
4. Total Priority Execution Control
When running massive lint pipelines across a codebase, you want lightweight structural tests (like syntax checkers or code formatters) to run before heavy, slow static analysis tools (like deep security scanners or type checkers).
While the legacy system executes hooks in a strict, sequential top-to-bottom layout, prek.toml breaks this constraint by allowing you to attach explicit priority flags directly to individual hooks.
5. Built-in, Zero-Dependency Performance
When using prek.toml, you can instantly toggle the core execution logic over to repo = "builtin".
This instructs the engine to completely bypass cloning remote packages, downloading runtimes, or building isolated multi-megabyte virtual environments. It drops down into native, compiled Rust shims built directly into your local prek binary, dropping your pre-commit overhead down to a fraction of a millisecond.