Metadata-Version: 2.4
Name: prehook
Version: 0.5.0
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
License-File: LICENSE
Summary: Run git hooks as shell commands from pyproject.toml
Keywords: git,hooks,pre-commit,linter,formatter
Author-email: Christian Tanul <git@christiantanul.com>
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Repository, https://github.com/scriptogre/prehook

# `prehook`

[![CI](https://github.com/scriptogre/prehook/actions/workflows/ci.yml/badge.svg)](https://github.com/scriptogre/prehook/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/prehook)](https://pypi.org/project/prehook/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

Run git hooks configured in `pyproject.toml` using `uv`.

## Usage

1. Install (one-time):

    ```sh
    uvx prehook install
    ```

   _Use `--force` to overwrite existing git hooks._

2. Update hooks in `pyproject.toml`:

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

3. Commit:
    ```sh
    git commit -m "unfinished commit"
    ```

To run hooks manually:

```sh
uvx prehook run
```

To uninstall:

```sh
uvx prehook uninstall
```

## Configuration

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

```toml
[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](https://git-scm.com/docs/githooks#_hooks) 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

```sh
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

```toml
[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. |

Both can be overridden from the CLI:

```sh
uvx prehook run --parallel --fail-fast
```

## Why?

I used [`pre-commit`](https://pre-commit.com) 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:
```sh
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](https://pre-commit.com)                 | `.pre-commit-config.yaml` | Huge ecosystem of ready-made hooks, multi-language virtualenv management. |
| [lefthook](https://github.com/evilmartians/lefthook) | `lefthook.yml`            | Fast, language-agnostic, great parallel execution.                        |
| [prek](https://github.com/j178/prek)                 | `prek.toml`               | Compatible with pre-commit configs, written in Rust, parallel execution.  |
