Quickstart¶

This page helps you get productive with prek in minutes, whether you are migrating from pre-commit or starting from scratch.

First follow the installation guide to install prek on your system.

I already use pre-commit I'm new to pre-commit-style tools

Already using pre-commit?¶

Great news - prek is designed as a drop-in replacement, you only need two tweaks:

1. Replace every pre-commit command in your scripts or documentation with prek. Your existing .pre-commit-config.yaml continues to work unchanged.

   $ prek run
   trim trailing whitespace.................................................Passed
   fix end of files.........................................................Passed
   typos....................................................................Passed
   cargo fmt................................................................Passed
   cargo clippy.............................................................Passed
   

2. Reinstall the Git shims once via prek install -f (run this if you previously executed pre-commit install).

From here you can explore what prek adds on top of pre-commit:

• Key differences and new features
• Built-in Rust-native hooks
• Workspace mode for monorepos

New to pre-commit-style workflows?¶

Follow this short example to experience how prek automates linting and formatting tasks.

1. Initialize the repository¶

From the root of a Git repository without an existing hook configuration, run:

prek init

This creates a starter prek.toml and installs the pre-commit Git shim so Git runs prek when you commit.

The generated configuration uses prek's built-in hooks:

[[repos]]
repo = "builtin"
hooks = [
  { id = "trailing-whitespace" },
  { id = "end-of-file-fixer" },
  { id = "check-added-large-files" },
]

Add a small YAML file so the first run has something to check, then stage both files:

project: prek
enabled: true

git add prek.toml example.yaml

prek run checks the staged snapshot, so a new or changed config must be staged before this default run. You can still review or unstage it after trying the workflow.

2. Run hooks on demand¶

Use prek run to execute all configured hooks on the files in your current git staging area:

$ prek run
trim trailing whitespace.................................................Passed
fix end of files.........................................................Passed
check for added large files..............................................Passed

The built-in hooks in this example are ready to run immediately. Remote hooks can take longer on their first run while prek downloads their repository and prepares the environment.

Need to run a single hook? Pass its ID, for example prek run trailing-whitespace. You can also target specific files with --files, or run against the entire repository with --all-files. Use --all-files after adding or changing a hook to check existing files that are not staged.

3. Customize the hooks¶

Edit the generated configuration to add or remove hooks. For example, add Ruff to lint and format Python files:

[[repos]]
repo = "https://github.com/astral-sh/ruff-pre-commit"
rev = "v0.16.0"
hooks = [
  { id = "ruff-check" },
  { id = "ruff-format" },
]

Because prek init installed the Git shim, every git commit invokes the configured hooks for the files in that commit. Run prek install to reinstall the shim later, or prek uninstall to remove it.

4. Go further¶

For other setups, prek init --format yaml creates .pre-commit-config.yaml. Use prek init --no-install to create only the config, then run prek install when you are ready to enable checks on commit. To create a config in an existing subdirectory, see Monorepos.

• Explore richer configuration options in the official pre-commit documentation. Every example there works with prek.
• See Running Hooks for the commands you will use after setup and how to handle hook failures.
• Check the configuration reference for prek-specific settings.
• Browse the built-in hooks and the difference guide to see what else you can leverage.

That’s it! You now have automated checks running locally with minimal setup. When you’re ready to dive deeper, the rest of the docs cover advanced workflows, language-specific installers, and more.