docs/usage.md
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.
First, install prek, then run this command from the repository root:
prek install
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:
prek install -f
Hook environments are normally prepared the first time they are needed. To prepare them during setup instead, run:
prek install --prepare-hooks
Use Git as usual: stage the changes that belong in the commit, then commit them.
$ 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.
A hook can reject a change and print the problem it found. For example:
$ 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:
$ 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.
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:
$ 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:
$ 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.
You do not need to create a commit to run the configured hooks.
Run hooks for the files currently staged in Git:
prek run
Run hooks against the whole repository, commonly before opening a pull request:
prek run --all-files
Run a single hook by ID:
prek run ruff
Inspect what would run without executing hooks or changing files:
prek run --dry-run
When the repository's policy permits it, Git can bypass the pre-commit and
commit-msg hooks for one commit:
git commit --no-verify
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.
List the hooks and projects discovered in the current workspace:
prek list
Use verbose output when a hook fails without enough context:
prek run -vvv
prek also writes a log file to ~/.cache/prek/prek.log by default. See
Debugging when reporting a prek problem.
If you maintain the repository's prek setup, validate its configuration after editing it:
prek validate-config prek.toml
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:
prek util identify path/to/file
Update pinned hook repository revisions or prepare hook environments without touching Git shims:
prek update
prek prepare-hooks
Show or clean cached repositories, hook environments, and toolchains:
prek cache dir
prek cache gc
prek cache clean