prek 0.2.16

Better `pre-commit`, re-engineered in Rust
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

# Contributing to prek

Thanks for your interest in improving **prek**! This guide walks through the development environment, our snapshot-based testing workflow, and the helper tasks defined in `mise.toml` to keep everything smooth.

## 1. Set up the Rust development environment

1. **Install Rust with `rustup`** (recommended)

   Install `rustup` from <https://rustup.rs> if you do not already have it. Then install the toolchain pinned in `rust-toolchain.toml` (currently Rust 1.90):

   ```bash
   rustup show
   ```

   Finally, add the common developer components:

   ```bash
   rustup component add rustfmt clippy
   ```

1. **Install project helper tools**

   Install [`mise`](https://mise.jdx.dev/) to manage project-specific tools and tasks, then run `mise install` in the repository root to download the tool versions declared in `mise.toml` (for example `cargo-insta`, `cargo-nextest`, and the language toolchains used in integration tests).

1. (Optional) **Bootstrap git hooks**

   ```bash
   prek install
   ```

   This installs a `pre-push` git hook that keeps formatting and linting checks aligned with CI before you push changes.

## 2. Writing tests with `insta` snapshot assertions

prek uses [insta](https://insta.rs/) for snapshot testing. It's recommended (but not necessary) to use
`cargo-insta` for a better snapshot review experience.

If you are contributing new functionality, please include coverage via unit tests (in `src/…` using `#[cfg(test)]`) or integration tests (under `tests/`).

In integration tests, you can use `cmd_snapshot!` macro to simplify creating snapshots for prek commands. For example:

```rust
#[test]
fn test_run() {
    let context = TestContext::new();
    context.init_project();

    cmd_snapshot!(context.filters(), context.run(), @"");
}
```

## 3. Running tests and updating snapshots

You can invoke the test suite directly with Cargo or use the convenience tasks defined in `mise.toml`.

### Direct Cargo commands

- To run and review a specific snapshot test:

  ```bash
  cargo test --package <package> --test <test> -- <test_name> -- --exact
  cargo insta review
  ```

Where `<package>` is the crate name (for example, `prek`), `<test>` is the integration test file name (for example, `builtin_hooks`), and `<test_name>` is the specific test function name.

- Run snapshot-aware tests with the review UI:

  ```bash
  cargo insta test --review [test arguments]
  ```

  This command runs the selected tests, shows snapshot diffs, and lets you approve or reject updates interactively.

### Using mise tasks

`mise run <task>` picks up the arguments and environment declared in `mise.toml`. Helpful tasks include:

- `mise run test-unit -- <filter>` – run binary/unit tests matching `<filter>` with `cargo insta test --review --bin prek`.
- `mise run test-all-unit` – run all unit tests with snapshot review enabled.
- `mise run test-integration <test> [filter]` – run one integration test (for example `mise run test-integration builtin_hooks detect_private_key_hook`).
- `mise run test-all-integration` – execute the full integration test suite with review prompts.
- `mise run test` – run `cargo test` across the workspace without the snapshot review flow.
- `mise run lint` – run `cargo fmt` and `cargo clippy` (useful before opening a pull request).

## 4. Before you open a pull request

- Ensure `mise run lint` passes without errors.
- Include documentation updates if your change alters the user-facing behavior.
- Keep commits focused and write descriptive messages—this helps reviewers follow along.

Thanks again for contributing!