# Differences from pre-commit

## General differences

- `prek` supports `.pre-commit-config.yaml`, `.pre-commit-config.yml`, and native `prek.toml` configuration files. Use [`prek util yaml-to-toml`](reference/cli.md#prek-util-yaml-to-toml) to convert an existing YAML config.
- `prek` implements some common hooks from `pre-commit-hooks` in Rust for better performance.
- `prek` supports `repo: builtin` for offline, zero-setup hooks.
- `prek` uses `~/.cache/prek` as the default cache directory for repos, environments and toolchains.
- `prek` decouples hook environments from their repositories, allowing shared toolchains and environments across hooks.
- `prek` supports `language_version` as a semver specifier and automatically installs the required toolchains.
- `prek` supports `files` and `exclude` as glob lists (in addition to regex) via `glob` mappings. See [Configuration Reference](reference/configuration.md#top-level-files).
- `prek` supports a [`shell`](reference/configuration.md#shell) hook option for explicit shell-source execution through predefined adapters such as `bash`, `sh`, and `pwsh`. Upstream `pre-commit` runs `entry` directly; shell behavior must be spelled into `entry` itself.
- `prek` reports more precise configuration parsing errors, including exact source locations.

## Behavioral divergences

These differences intentionally change upstream behavior instead of adding a compatible superset.

- File identification gives recognized extensions precedence over loose filename-prefix matches. For example, `makefile.png` is treated as a PNG image, while upstream `identify` also gives it `makefile` and `text` tags. Exact filename matches such as `Cargo.toml` still keep their name-specific tags.

## Workspace mode

`prek` supports workspace mode, allowing you to run hooks for multiple projects in a single command. Each subproject can keep its own `prek.toml` or `.pre-commit-config.yaml` file.

See [Workspace Mode](./workspace.md) for more information.

## Language support

See the dedicated [Language Support](languages.md) page for a complete list of supported languages, prek-specific behavior, and unsupported languages.

Recent releases added support for more managed hook runtimes, including Bun, Julia, Deno, and experimental .NET support.

## Managed runtime download verification

For supported managed runtime downloads, `prek` verifies the downloaded archive or installer against the checksum published by the runtime's own distribution channel before extracting or installing it.

This helps catch corrupted or unexpectedly changed downloads before they are unpacked. It does not add an independent trust root: if an upstream release, mirror, or checksum file is compromised together with the archive, SHA-256 verification alone cannot detect that.

`uv` downloads are not covered by this behavior yet.

## Command line interface

For a compatibility-focused command mapping, see [Compatibility with pre-commit](compatibility.md).

### `prek run`

- `prek run [HOOK|PROJECT]...` supports selecting or skipping multiple projects or hooks in workspace mode, instead of only accepting a single optional hook id. See [Running Specific Hooks or Projects](workspace.md#running-specific-hooks-or-projects) for details.
- `prek run` can execute hooks in parallel by priority (hooks with the same [`priority`](./reference/configuration.md#priority) may run concurrently), instead of strictly serial execution.
- In workspace mode, `prek run` can execute independent projects at the same directory depth concurrently, while still running child projects before their parents.
- `prek` provides dynamic completion for hook ids.
- `prek run --dry-run` shows which hooks would run without executing them.
- `prek run --last-commit` runs hooks on files changed by the last commit.
- `prek run --directory <DIR>` runs hooks on a specified directory.
- `prek run --no-fail-fast` lets you override the configured `fail_fast` setting for a single run and continue after failures.

### `prek install`

- `prek install` and `prek uninstall` honor repo-local and worktree-local `core.hooksPath` when choosing where to manage Git shims.

### `prek validate-config`

- `prek validate-config` accepts both `prek.toml` and `.pre-commit-config.yaml`.

### `prek list`

`prek list` lists all available hooks, their ids, and descriptions. This provides a better overview of the configured hooks.

### `prek update`

- `prek update` updates all projects in the workspace to their latest revisions.
- `prek update` checks updates for the same repository only once, speeding up the process in workspace mode.
- `prek update` supports `--dry-run` to preview the updates without applying them.
- `prek update` supports `--exit-code` to exit non-zero when updates are available, and `--check` as an alias for `--dry-run --exit-code`.
- `prek update` validates pinned SHA revisions against fetched upstream refs, including impostor-commit detection, and keeps stale `# frozen:` comments in sync when it can.
- `prek update` supports the `--cooldown-days` option to skip releases newer than the specified number of days (based on the tag creation timestamp for annotated tags, or the tagged commit timestamp for lightweight tags).
- `prek update` supports `--exclude-repo` to skip selected repositories while updating everything else.
- `prek update` supports tag filtering with `--include-tag`, `--exclude-tag`, `--repo-include-tag`, and `--repo-exclude-tag`, using glob patterns to keep or remove matching tags before selecting an update.

### `prek sample-config`

- `prek sample-config` can generate either YAML or TOML and can write directly to a file with `--file`.

### `prek util`

- `prek util identify` shows the file-identification tags prek uses for filtering and debugging hook selection.
- `prek util list-builtins` lists all built-in hooks bundled with prek.
- `prek util yaml-to-toml` converts `.pre-commit-config.yaml` to `prek.toml`.

### `prek cache`

- `prek` groups cache maintenance under `prek cache` instead of separate top-level `clean` and `gc` commands.
- `prek cache gc` removes unused cached repositories, environments and toolchains, and supports `--dry-run`.
- `prek cache clean` removes all cached data.
- `prek cache dir` and `prek cache size` help inspect the cache before or after cleanup.

## Not implemented

The `pre-commit hazmat` subcommand introduced in pre-commit
[v4.5.0](https://github.com/pre-commit/pre-commit/releases/tag/v4.5.0) is not
implemented. This command is niche and unlikely to be widely used.
