Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
## Where to Start

- New to `prek`: start with [Installation](installation.md), then follow the [Quickstart](quickstart.md).
- Already set up: use [Common Workflows](usage.md) for the commands you run day to day.
- Already set up: use [Common Workflows](usage.md) for day-to-day commands and handling hook failures.
- Writing config: read [Configuration](configuration.md), then use the [Configuration Reference](reference/configuration.md) for exact keys.
- Looking for setup patterns: browse the [Cookbook](cookbook.md).
- Working in a monorepo: see [Workspace Mode](workspace.md).
Expand Down
2 changes: 1 addition & 1 deletion docs/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ Now every `git commit` will invoke `prek run` for the files included in the comm
### 4. Go further

- Explore richer configuration options in the official [pre-commit documentation](https://pre-commit.com/). Every example there works with prek.
- See [Common Workflows](./usage.md) for the commands you will use after setup.
- See [Common Workflows](./usage.md) for the commands you will use after setup and how to handle hook failures.
- Check the [configuration reference](./reference/configuration.md) for prek-specific settings.
- Browse the [built-in hooks](./builtin.md) and the [difference guide](./diff.md) to see what else you can leverage.

Expand Down
155 changes: 130 additions & 25 deletions docs/usage.md
Original file line number Diff line number Diff line change
@@ -1,36 +1,126 @@
# Common Workflows

This page summarizes the commands you normally use after a project already has a `prek.toml` or `.pre-commit-config.yaml`.
This page explains how to use prek in a repository that already contains a
`prek.toml` or `.pre-commit-config.yaml`, including setup, running hooks, and
handling a hook that prevents a commit.

## Set Up Once
## Set up the repository

Install Git shims so `prek` runs automatically during Git operations:
First, [install prek](installation.md), then run this command from the repository
root:

```bash
prek install
```

If the repository used `pre-commit` before, overwrite the existing shims once:
This installs the Git shims selected by the repository's configuration so that
prek runs automatically during Git operations. If the repository does not
select any hook types, prek installs a `pre-commit` shim by default. If the
repository previously used `pre-commit` and already has its shims installed,
replace them once:

```bash
prek install -f
```

Prepare hook environments ahead of time, which is useful for CI images or when you want the first commit to be fast:
Hook environments are normally prepared the first time they are needed. To
prepare them during setup instead, run:

```bash
prek install --prepare-hooks
```

## Run Hooks
## What happens when you commit

Use Git as usual: stage the changes that belong in the commit, then commit them.

```console
$ git add settings.json
$ git commit -m "Update settings"
check json...............................................................Passed
mixed line ending........................................................Passed
[main 0123456] Update settings
1 file changed, 1 insertion(+)
```

Before Git creates the commit, the `pre-commit` shim runs hooks configured for
that stage against the staged files. Unstaged changes are temporarily stashed
while the hooks run, so the hooks check the contents that will be committed. The
first run may take longer while prek downloads and prepares hook environments.

If every hook passes, Git creates the commit. If a hook fails or modifies files,
prek exits unsuccessfully and Git stops without creating the commit.

## When a hook reports a failure

A hook can reject a change and print the problem it found. For example:

```console
$ git commit -m "Update settings"
check json...............................................................Failed
- hook id: check-json
- exit code: 1

settings.json: Failed to json decode (trailing comma at line 3 column 1)
```

Read the hook output, fix the reported problem, stage the corrected file, and
retry the commit:

```console
$ git add settings.json
$ git commit -m "Update settings"
check json...............................................................Passed
[main 0123456] Update settings
1 file changed, 1 insertion(+)
```

The failed attempt did not create a partial commit. Other hooks may have reported
additional problems, so check the complete output before retrying.

## When a hook modifies files

Formatters and other fixing hooks can update files automatically. prek marks the
run as failed so that you can review and stage those changes before committing
them:

```console
$ git commit -m "Normalize line endings"
mixed line ending........................................................Failed
- hook id: mixed-line-ending
- exit code: 1
- files were modified by this hook

Fixing mixed.txt
```

Inspect the changes, make any further edits you want, stage the final result, and
retry:

```console
$ git diff -- mixed.txt
$ git add mixed.txt
$ git commit -m "Normalize line endings"
mixed line ending........................................................Passed
[main 0123456] Normalize line endings
1 file changed, 3 insertions(+), 3 deletions(-)
```

A hook can both modify files and report another error. In that case, keep the
automatic fixes you want and resolve the remaining error before staging and
retrying.

## Run hooks yourself

You do not need to create a commit to run the configured hooks.

Run hooks for the files currently staged in Git:

```bash
prek run
```

Run hooks against the whole repository, commonly after changing hook configuration or before opening a PR:
Run hooks against the whole repository, commonly before opening a pull request:

```bash
prek run --all-files
Expand All @@ -42,51 +132,65 @@ Run a single hook by ID:
prek run ruff
```

Run without changing files or executing hooks, to inspect what would run:
Inspect what would run without executing hooks or changing files:

```bash
prek run --dry-run
```

## Inspect and Debug
## Skip hooks for one commit

List the hooks and projects discovered in the current workspace:
When the repository's policy permits it, Git can bypass the `pre-commit` and
`commit-msg` hooks for one commit:

```bash
prek list
git commit --no-verify
```

Validate configuration files:
This does not fix the reported problem, and the same checks may still fail in
continuous integration. Prefer fixing or explicitly resolving the hook failure
when possible.

## Inspect and debug

List the hooks and projects discovered in the current workspace:

```bash
prek validate-config prek.toml
prek list
```

Use `.pre-commit-config.yaml` instead if that is the repository's config file.

Inspect file type tags when `types`, `types_or`, or `exclude_types` filters do not match as expected:
Use verbose output when a hook fails without enough context:

```bash
prek util identify path/to/file
prek run -vvv
```

Use verbose output when a hook fails in a way that needs more context:
prek also writes a log file to `~/.cache/prek/prek.log` by default. See
[Debugging](debugging.md) when reporting a prek problem.

## Maintain the repository's hook configuration

If you maintain the repository's prek setup, validate its configuration after
editing it:

```bash
prek run -vvv
prek validate-config prek.toml
```

## Maintain Hooks
Use `.pre-commit-config.yaml` instead if that is the repository's config file.

Update pinned hook repository revisions:
Inspect file type tags when `types`, `types_or`, or `exclude_types` filters do not
match as expected:

```bash
prek update
prek util identify path/to/file
```

Prepare hook environments without touching Git shims:
Update pinned hook repository revisions or prepare hook environments without
touching Git shims:

```bash
prek update
prek prepare-hooks
```

Expand All @@ -98,8 +202,9 @@ prek cache gc
prek cache clean
```

## Where to Go Next
## Where to go next

- [Configuration](configuration.md) covers config file formats, discovery, and validation.
- [Configuration](configuration.md) covers config file formats, discovery, and
validation.
- [Workspace Mode](workspace.md) covers monorepos and nested project configs.
- [CLI Reference](reference/cli.md) lists every command and option.