From 4fcbabc13734feab0724b49e53082753a3f6ea4a Mon Sep 17 00:00:00 2001 From: Jo <10510431+j178@users.noreply.github.com> Date: Tue, 14 Apr 2026 11:48:55 +0800 Subject: [PATCH] Improve compatibility and migration docs (#1940) Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- README.md | 34 ++++++++++++++------------- docs/compatibility.md | 54 ++++++++++++++++++++++++++++++++----------- docs/diff.md | 49 ++++++++++++++++++++++++++++----------- 3 files changed, 94 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index 7ea9d9f4..cf5d9c16 100644 --- a/README.md +++ b/README.md @@ -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 ` runs hooks for files in the specified directory, no need to use `git ls-files -- | 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 ` 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/). diff --git a/docs/compatibility.md b/docs/compatibility.md index 297291d9..ca6a8ea6 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -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. diff --git a/docs/diff.md b/docs/diff.md index e085cd8c..a3feea27 100644 --- a/docs/diff.md +++ b/docs/diff.md @@ -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 ` 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 ` 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