prehook 0.6.0

Run git hooks as shell commands from pyproject.toml

prehook

Run git hooks configured in pyproject.toml using uv.

Usage

1. Install (one-time):

   uvx prehook install
   

   Use --force to overwrite existing git hooks.

   Installed hooks are self-contained sh (they read pyproject.toml directly), so committing never needs prehook itself, and editing the hook list needs no reinstall.

2. Update hooks in pyproject.toml:

   [tool.prehook]
   hooks = [
       "uvx ruff check",
       "uvx ruff format",
   ]
   

3. Commit:

   git commit -m "unfinished commit"
   

To uninstall:

uvx prehook uninstall

Run the hooks on demand (e.g. in CI) without committing:

uvx prehook run                 # pre-commit hooks
uvx prehook run --on pre-push   # a specific stage

Configuration

Each hook can have a name, target git hook type, and other options:

[tool.prehook]
hooks = [
    { name = "lint", run = "uvx ruff check --fix" },
    { name = "format", run = "uvx ruff format" },
    { name = "typecheck", run = "uvx pyright" },
    { name = "test", run = "pytest", on = ["pre-push"] },
]

Key	Default	Description
run	required	Command to execute.
name	derived from command	Label for output and SKIP.
on	["pre-commit"]	Which git hook types to run on.
verbose	false	Show output even on success.

uvx prehook install installs hooks for all supported git hook types, so adding new on values works without reinstalling.

Skipping hooks

SKIP=typecheck git commit -m "wip"         # skip by name
SKIP=lint,typecheck git commit -m "wip"    # skip multiple
git commit --no-verify -m "wip"            # skip all

Parallel and fail fast

[tool.prehook]
parallel = true
fail_fast = true
hooks = [
    { name = "lint+format", run = "uvx ruff check --fix && uvx ruff format" },
    { name = "typecheck", run = "uvx pyright" },
]

Key	Default	Description
fail_fast	false	Stop after first failure.
parallel	false	Run all hooks concurrently.

Why?

I used pre-commit for a long time, and it's a great tool.

But I prefer less configuration files, and for most projects I just want a quick:

uvx ruff check
uvx ruff format

Which are fast enough to always run on all files (rather than just staged ones).

Alternatives

If this tool doesn't do what you need, these are worth a look:

Tool	Config	What it does well
pre-commit	.pre-commit-config.yaml	Huge ecosystem of ready-made hooks, multi-language virtualenv management.
lefthook	lefthook.yml	Fast, language-agnostic, great parallel execution.
prek	prek.toml	Compatible with pre-commit configs, written in Rust, parallel execution.