mirror of
https://github.com/j178/prek.git
synced 2026-04-25 02:11:36 +02:00
Improve compatibility and migration docs (#1940)
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
Jo
GitHub
@@ -340,26 +340,28 @@ prek self update
|
||||
|
||||
### prek is faster
|
||||
|
||||
- It is [multiple times faster](https://prek.j178.dev/benchmark/) than `pre-commit` and takes up half the disk space.
|
||||
- It redesigned how hook environments and toolchains are managed, they are all shared between hooks, which reduces the disk space usage and speeds up the installation process.
|
||||
- Repositories are cloned in parallel, and hooks are installed in parallel if their dependencies are disjoint.
|
||||
- Hooks can run in parallel by priority (hooks with the same [`priority`](https://prek.j178.dev/configuration/#priority) may run concurrently), reducing end-to-end runtime.
|
||||
- It is [multiple times faster](https://prek.j178.dev/benchmark/) than `pre-commit` while also using less disk space.
|
||||
- Hook environments and toolchains are shared across hooks instead of being duplicated per repository, which reduces both install time and cache size.
|
||||
- Repositories are fetched in parallel, hook environments are prepared in parallel when their dependencies do not overlap, and hooks can run concurrently by [`priority`](https://prek.j178.dev/configuration/#priority).
|
||||
- It uses [`uv`](https://github.com/astral-sh/uv) for creating Python virtualenvs and installing dependencies, which is known for its speed and efficiency.
|
||||
- It implements some common hooks in Rust, [built in prek](https://prek.j178.dev/builtin/), which are faster than their Python counterparts.
|
||||
- It implements some common hooks in Rust as [builtins](https://prek.j178.dev/builtin/), which are faster than their Python counterparts.
|
||||
- It supports `repo: builtin` for offline, zero-setup hooks, which is not available in `pre-commit`.
|
||||
|
||||
### prek provides a better user experience
|
||||
### prek is easier to work with
|
||||
|
||||
- No need to install Python or any other runtime, just download a single binary.
|
||||
- No hassle with your Python version or virtual environments, prek automatically installs the required Python version and creates a virtual environment for you.
|
||||
- Built-in support for [workspaces](https://prek.j178.dev/workspace/) (or monorepos), each subproject can have its own `.pre-commit-config.yaml` file.
|
||||
- [`prek run`](https://prek.j178.dev/cli/#prek-run) has some nifty improvements over `pre-commit run`, such as:
|
||||
- `prek run --directory <dir>` runs hooks for files in the specified directory, no need to use `git ls-files -- <dir> | xargs pre-commit run --files` anymore.
|
||||
- `prek run --last-commit` runs hooks for files changed in the last commit.
|
||||
- `prek run [HOOK] [HOOK]` selects and runs multiple hooks.
|
||||
- [`prek list`](https://prek.j178.dev/cli/#prek-list) command lists all available hooks, their ids, and descriptions, providing a better overview of the configured hooks.
|
||||
- [`prek auto-update`](https://prek.j178.dev/cli/#prek-auto-update) supports `--cooldown-days` to mitigate open source supply chain attacks.
|
||||
- prek provides shell completions for `prek run <hook_id>` command, making it easier to run specific hooks without remembering their ids.
|
||||
- No need to install Python or any other runtime just to use `prek`; it is a single binary.
|
||||
- `prek` automatically installs the toolchains it needs for supported languages, so you spend less time managing Python versions, Node runtimes, Ruby installs, and similar setup.
|
||||
- It supports native [`prek.toml`](https://prek.j178.dev/configuration/) in addition to pre-commit YAML, and [`prek util yaml-to-toml`](https://prek.j178.dev/cli/#prek-util-yaml-to-toml) helps migrate existing configs.
|
||||
- Built-in support for [workspaces](https://prek.j178.dev/workspace/) means monorepos can keep separate configs per project and still run everything from one command.
|
||||
- [`prek install`](https://prek.j178.dev/cli/#prek-install) and [`prek uninstall`](https://prek.j178.dev/cli/#prek-uninstall) honor repo-local and worktree-local `core.hooksPath`.
|
||||
- [`prek run`](https://prek.j178.dev/cli/#prek-run) supports selecting or skipping multiple projects or hooks in workspace mode, instead of only accepting a single optional hook id, and adds quality-of-life improvements such as `--dry-run`, `--directory`, `--last-commit`, and `--no-fail-fast`.
|
||||
- [`prek list`](https://prek.j178.dev/cli/#prek-list), [`prek util identify`](https://prek.j178.dev/cli/#prek-util-identify), and [`prek util list-builtins`](https://prek.j178.dev/cli/#prek-util-list-builtins) make it easier to inspect configured hooks, debug file matching, and discover builtins.
|
||||
|
||||
### prek includes security-focused safeguards
|
||||
|
||||
- [`prek auto-update`](https://prek.j178.dev/cli/#prek-auto-update) supports `--cooldown-days`, so you can keep newly published releases on hold for a cooling-off period before adopting them.
|
||||
- [`prek auto-update`](https://prek.j178.dev/cli/#prek-auto-update) validates pinned SHA revisions against the fetched upstream refs, including impostor-commit detection, and keeps `# frozen:` comments in sync with the configured commit.
|
||||
- [`prek auto-update --check`](https://prek.j178.dev/cli/#prek-auto-update--check) is useful in CI when you want updates or frozen-reference mismatches to fail the job without rewriting the config.
|
||||
|
||||
For more detailed improvements prek offers, take a look at [Difference from pre-commit](https://prek.j178.dev/diff/).
|
||||
|
||||
|
||||
+41
-13
@@ -1,21 +1,49 @@
|
||||
# Compatibility with pre-commit
|
||||
|
||||
`prek` is designed to be a practical drop-in replacement for `pre-commit`.
|
||||
`prek` aims to be a practical drop-in replacement for `pre-commit` for existing repositories, hook configs, and day-to-day workflows.
|
||||
|
||||
- Existing `.pre-commit-config.yaml` and `.pre-commit-config.yml` files work unchanged. See [Configuration](configuration.md).
|
||||
- Most day-to-day `pre-commit` commands work unchanged in `prek`.
|
||||
## What works unchanged
|
||||
|
||||
## Command and flag differences
|
||||
- Existing `.pre-commit-config.yaml` and `.pre-commit-config.yml` files work in `prek`. See [Configuration](configuration.md).
|
||||
- Most common `pre-commit` workflows keep working, including the usual hook repositories and manifests.
|
||||
- Several upstream command spellings are still accepted as compatibility aliases, so existing scripts do not need to be rewritten immediately.
|
||||
|
||||
Only the commands and flags below differ from the preferred `prek` spelling. The compatibility forms are still accepted so existing scripts do not break.
|
||||
## Preferred command and flag spellings
|
||||
|
||||
`prek` keeps compatibility aliases for the commands below, but the preferred spellings use a more descriptive CLI layout.
|
||||
|
||||
| Compatibility spelling | Preferred `prek` spelling |
|
||||
| -- | -- |
|
||||
| `prek install-hooks` | `prek prepare-hooks` |
|
||||
| `prek install --install-hooks` | `prek install --prepare-hooks` |
|
||||
| `prek autoupdate` | `prek auto-update` |
|
||||
| `prek gc` | `prek cache gc` |
|
||||
| `prek clean` | `prek cache clean` |
|
||||
| `prek init-templatedir` | `prek util init-template-dir` |
|
||||
| `prek init-template-dir` | `prek util init-template-dir` |
|
||||
| `pre-commit migrate-config` | Not provided directly; use `prek util yaml-to-toml` to migrate YAML to `prek.toml` |
|
||||
|
||||
## Why the CLI is reorganized
|
||||
|
||||
`pre-commit` keeps many maintenance commands as separate top-level entries. `prek` reorganizes some of them so the command tree is easier to navigate:
|
||||
|
||||
- related cache operations live under `prek cache`
|
||||
- helper and migration commands live under `prek util`
|
||||
- `prepare-hooks` describes what the command actually does more clearly than `install-hooks`
|
||||
|
||||
That improves discoverability without dropping compatibility, because the older spellings remain available.
|
||||
|
||||
## Not implemented
|
||||
|
||||
- `prek install-hooks` still works, but `prek prepare-hooks` is the preferred spelling.
|
||||
- `prek install --install-hooks` still works, but `prek install --prepare-hooks` is the preferred flag spelling.
|
||||
- `prek autoupdate` still works, but `prek auto-update` is the preferred spelling.
|
||||
- `prek gc` still works as a hidden compatibility command, but `prek cache gc` is preferred.
|
||||
- `prek clean` still works as a hidden compatibility command, but `prek cache clean` is preferred.
|
||||
- `prek init-templatedir` and `prek init-template-dir` still work as hidden compatibility commands, but `prek util init-template-dir` is preferred.
|
||||
- `pre-commit hazmat` is not implemented in `prek`.
|
||||
- `pre-commit migrate-config` is not provided as a direct command. Use `prek util yaml-to-toml` if you want to migrate from YAML to `prek.toml`.
|
||||
|
||||
If you need strict upstream portability, stay with the YAML config format and avoid `prek`-only features such as `prek.toml`, `repo: builtin`, glob mappings for `files` and `exclude`, and workspace mode. See [Configuration](configuration.md) and [Differences](diff.md).
|
||||
## If you need strict upstream portability
|
||||
|
||||
If the same config must continue working in upstream `pre-commit`, stay with the YAML config format and avoid `prek`-only features such as:
|
||||
|
||||
- `prek.toml`
|
||||
- `repo: builtin`
|
||||
- glob mappings for `files` and `exclude`
|
||||
- workspace mode
|
||||
|
||||
See [Configuration](configuration.md) for config-level compatibility details and [Differences](diff.md) for broader behavior and CLI differences.
|
||||
|
||||
+35
-14
@@ -2,17 +2,18 @@
|
||||
|
||||
## General differences
|
||||
|
||||
- `prek` supports both `.pre-commit-config.yaml` and `.pre-commit-config.yml` configuration files.
|
||||
- `prek` supports `.pre-commit-config.yaml`, `.pre-commit-config.yml`, and native `prek.toml` configuration files. Use [`prek util yaml-to-toml`](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` decoupled hook environment from their repositories, allowing shared toolchains and environments across hooks.
|
||||
- `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](configuration.md#top-level-files).
|
||||
- `prek` reports more precise configuration parsing errors, including exact source locations.
|
||||
|
||||
## Workspace mode
|
||||
|
||||
`prek` supports workspace mode, allowing you to run hooks for multiple projects in a single command. Each subproject can have its own `.pre-commit-config.yaml` file.
|
||||
`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.
|
||||
|
||||
@@ -20,39 +21,59 @@ See [Workspace Mode](./workspace.md) for more information.
|
||||
|
||||
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.
|
||||
|
||||
## 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. See [Running Specific Hooks or Projects](workspace.md#running-specific-hooks-or-projects) for details.
|
||||
- `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`](./configuration.md#priority) may run concurrently), instead of strictly serial execution.
|
||||
- `prek` provides dynamic completions of hook id.
|
||||
- `prek run --last-commit` to run hooks on files changed by the last commit.
|
||||
- `prek run --directory <DIR>` to run hooks on a specified directory.
|
||||
- `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` command lists all available hooks, their ids, and descriptions. This provides a better overview of the configured hooks.
|
||||
`prek list` lists all available hooks, their ids, and descriptions. This provides a better overview of the configured hooks.
|
||||
|
||||
### `prek auto-update`
|
||||
|
||||
- `prek auto-update` updates all projects in the workspace to their latest revisions.
|
||||
- `prek auto-update` checks updates for the same repository only once, speeding up the process in workspace mode.
|
||||
- `prek auto-update` supports `--dry-run` option to preview the updates without applying them.
|
||||
- `prek auto-update` supports `--dry-run` to preview the updates without applying them.
|
||||
- `prek auto-update` supports `--check` to exit non-zero when updates are available or frozen-reference mismatches are found, without rewriting the config.
|
||||
- `prek auto-update` validates pinned SHA revisions against fetched upstream refs, including impostor-commit detection, and keeps stale `# frozen:` comments in sync when it can.
|
||||
- `prek auto-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 sample-config`
|
||||
|
||||
- `prek sample-config` command has a `--file` option to write the sample configuration to a specific file.
|
||||
- `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 cache clean` to remove all cached data.
|
||||
- `prek cache gc` to remove unused cached repositories, environments and toolchains.
|
||||
- `prek cache dir` to show the cache directory.
|
||||
- `prek cache size` to show the total size of the 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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user