prek

prek is a high-performance, Rust-based reimagining of the pre-commit framework. It is designed as a faster, dependency-free, and drop-in alternative that manages language toolchains and dependencies for running hooks.

Key features include:

• A single binary with no external runtime dependencies (no Python required).
• Full compatibility with original pre-commit configurations and hooks.
• Built-in support for monorepos via workspace mode.
• Integration with uv for Python environment management.
• Improved toolchain installations for Python, Node.js, Bun, Go, Rust, and Ruby.
• Built-in Rust-native implementations of common hooks.

The prek CLI is a fast Git hook manager written in Rust. The general usage pattern is:

prek [OPTIONS] [HOOK|PROJECT]... [COMMAND]

Available commands include:

• prek install: Install Git hook shims.
• prek prepare-hooks: Prepare environments for configured hooks.
• prek run: Run configured hooks.
• prek list: List configured hooks.
• prek uninstall: Uninstall Git hook shims.
• prek validate-config: Validate prek configuration files.
• prek validate-manifest: Validate pre-commit hook manifests (.pre-commit-hooks.yaml).
• prek sample-config: Generate a sample prek configuration file.
• prek update: Update configured repositories.
• prek cache: Manage the prek cache.
• prek try-repo: Try hooks from a repository.
• prek util: Run utility commands.
• prek self: Manage the prek installation.

Use prek try-repo to run hooks from a local repository without needing to publish a release. This is useful for iterating on hook development.

Syntax: prek try-repo <path-to-hook-repo> <hook-id> [options]

Note: For prepare-commit-msg or commit-msg hooks, you must pass the --commit-msg-filename argument during testing.

# In another repository where you want to test the hook
prek try-repo ../path/to/hook-repo my-hook-id --verbose

Bun hooks are installed via bun install and run the configured entry. The repository must contain a package.json. The entry should be a Bun command or a provided bin name. additional_dependencies are supported. Bun hooks can run without a pre-installed Bun runtime if toolchain download is available.

Supported language_version formats:

• default or system
• bun, bun@latest
• bun@1, 1
• bun@1.1, 1.1
• bun@1.1.0, 1.1.0
• Semver ranges (e.g., >=1.0, <2.0)

Note: Bun support is a prek-only extension.

Builds an image from the repository root using docker build . and runs the hook inside the container. The first token of entry is used as the container --entrypoint.

Runtime Details:

• The repository is bind-mounted to /src with working directory /src.
• Supports Docker, Podman, or Container (auto-detected).
• Environment variables from env are passed via -e.
• Uses --init for signal forwarding.

Environment Variables:

• PREK_CONTAINER_RUNTIME: Override auto-detection.
• PREK_DOCKER_NO_INIT=1: Skip the --init flag (use if the environment cannot run the init helper).

For remote hooks, prek creates a Conda environment from the repository's environment.yml. For repo: local hooks, it creates a minimal environment using only additional_dependencies.

Conda Executables:

• Uses system conda by default.
• Set PRE_COMMIT_USE_MAMBA=1 to use mamba.
• Set PRE_COMMIT_USE_MICROMAMBA=1 to use micromamba.

Note on language_version: Explicit language_version requests are rejected for Conda. Python or package versions must be declared in the environment.yml file.

repos:
  - repo: local
    hooks:
      - id: conda-hook
        name: Conda hook
        language: conda
        entry: python -c "import colorama; print('ok')"
        additional_dependencies: [colorama]

You can execute hooks without creating a Git commit using the prek run command. Use these commands to verify changes or check the entire repository.

• Run hooks against currently staged files.
• Run hooks against all files in the repository.
• Run a specific hook using its ID.
• Perform a dry run to see what would run without executing them or modifying files.

Execution Order

Projects are executed from deepest to shallowest. For example, in a structure with src/backend/ and src/, src/backend/ runs first, followed by src/, and finally the workspace root.

File Visibility

Each project is isolated: a hook in a project can only see and process files within its own directory tree. It cannot reference files in sibling directories. If a hook needs access to files across multiple projects, move its configuration to a common ancestor directory (like the workspace root).

Concurrency

Projects at the same depth can run concurrently. Concurrency is bounded by the PREK_CONCURRENT_HOOKS environment variable. Note that hooks should be designed to avoid contending for shared resources (like sibling project files or shared caches) outside their own directory.

To start a new workflow, create a prek.toml file in the root of your repository. This file defines the repositories and hooks to be used. While prek.toml is the native format, prek can also read existing .pre-commit-config.yaml files.

[[repos]]
repo = "https://github.com/pre-commit/pre-commit-hooks"
rev = "v6.0.0"
hooks = [
  { id = "check-yaml" },
  { id = "end-of-file-fixer" },
]

Installs additional_dependencies via deno install --global into an isolated DENO_DIR. Deno hooks can run without a pre-installed runtime if toolchain download is available.

Dependency Rules:

• Use npm: or jsr: specifiers.
• Local files: ./path/to/tool.ts:name.
• To override executable name: npm:semver@7:semver-tool.

Supported language_version formats:

• default or system
• deno, deno@latest, deno@x, deno@x.y, deno@x.y.z
• Semver ranges (e.g., >=x.y, <x+1.0)

Examples:

• NPM package: entry: deno run -A npm:eslint
• JSR package: entry: deno run -A jsr:@biomejs/biome
• Built-in command: entry: deno fmt

repos:
  - repo: local
    hooks:
      - id: eslint
        name: ESLint
        language: deno
        entry: deno run -A npm:eslint
        types: [ts, tsx, js, jsx]