wiki.ivanpollak.com

prek is an alternative for pre-commit, a framework for running pre-commit hooks. The idea behind both systems is that common maintainer burdons can be avoided by running some sort of formating tool or linter over the whole code-base before any commit. Commits for the project should not be commitable if such a tool detects an error.

For example; There is a new developer in a project, who just got into the project and may come from a completely different programming language. The new developer previously has coded like this:

int main( void )
{
  return 0;
}

However for the new project, he is required to write code like this:

int main( void ) {
  return 0;
}

This is a quite trivial change, however it is possible that this developer forgets about it. This is where such tools come into place. They allow for the lead developer to easily configure pre-commits for every system.

An example configuration for a repository might look like this (using pre-commit):

repos:
-   repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v2.3.0
    hooks:
    -   id: check-yaml
    -   id: end-of-file-fixer
    -   id: trailing-whitespace
-   repo: https://github.com/psf/black
    rev: 22.10.0
    hooks:
    -   id: black

In this configuration, various configurations can be configured, which should be installed into the pre-commit hook. In the example the following ones are set:

check-yaml: Tries to load all yaml files and verify their syntax
end-of-file-fixer: Makes sure that all files end in a newline and only a newline
trailing-whitespace: Trims trailing whitespaces

Why prek

prek is just another attempt to rewrite existing tools into rust. It presents itself to be a reimagined version of pre-commit, built in Rust, dependency-free * and faster.

Using prek

This section describes the usage of the prek tool.

Setting up prek

prek should work with already pre-commit configurations out of the box, thus only the usage changes. CI pipelines, setup scripts or documentations need to have pre-commit replaced with prek. Alternatively, prek also can be configured in prek.toml.

Example configuration

An example configuration of prek using prek.toml could look like the following:

[[repos]]
repo = "https://github.com/pre-commit/pre-commit-hooks"
rev = "v6.0.0"
hooks = [
  { id = "check-yaml" },
  { id = "end-of-file-fixer" },
]

Installing pre-commits

To (re)install pre-commit hooks, run:

$ prek install -f

Running the pre-commits

If the pre-commits should be run without having the need to commit, use:

prek run

Managing failures

If a commit fails due to some error, the commit will fail. This means that the files will still be staged but not commited. When this happens, fix the issue and commit it again. Some commit hooks may be able to solve the issue automatically by themselfs. If this happend, just stage the changed file again and try to commit again.

Skip running hooks

On a test commit, or when knowingly producing an issue that prek would complain about, the pre-commit hook can be skipped. This can be done by using the --no-verify flag to git.

NOTE: If a CI is configured to use prek, it will fail. Use this flag with caution.

prek