pre-commit hooks

pre-commit hooks #

pre-commit is a framework for building and running git hooks. See the official documentation for more information: pre-commit.com

This document provides a list of available pre-commit hooks provided by Poetry.

Note
If you specify the args: for a hook in your .pre-commit-config.yaml, the defaults are overwritten. You must fully specify all arguments for your hook if you make use of args:.
Note
If the pyproject.toml file is not in the root directory, you can specify args: ["-C", "./subdirectory"].

poetry-check #

The poetry-check hook calls the poetry check command to make sure the poetry configuration does not get committed in a broken state.

Arguments #

The hook takes the same arguments as the poetry command. For more information see the check command.

poetry-lock #

The poetry-lock hook calls the poetry lock command to make sure the lock file is up-to-date when committing changes.

Arguments #

The hook takes the same arguments as the poetry command. For more information see the lock command.

poetry-export #

The poetry-export hook calls the poetry export command to sync your requirements.txt file with your current dependencies.

Warning
This hook is provided by the Export Poetry Plugin.
Note
It is recommended to run the poetry-lock hook prior to this one.

Arguments #

The hook takes the same arguments as the poetry command. For more information see the export command.

The default arguments are args: ["-f", "requirements.txt", "-o", "requirements.txt"], which will create/update the requirements.txt file in the current working directory.

You may add verbose: true in your .pre-commit-config.yaml in order to output to the console:

hooks:
-   id: poetry-export
    args: ["-f", "requirements.txt"]
    verbose: true

Also, --dev can be added to args to write dev-dependencies to requirements.txt:

hooks:
-   id: poetry-export
    args: ["--dev", "-f", "requirements.txt", "-o", "requirements.txt"]

poetry-install #

The poetry-install hook calls the poetry install command to make sure all locked packages are installed. In order to install this hook, you either need to specify default_install_hook_types, or you have to install it via pre-commit install --install-hooks -t post-checkout -t post-merge.

Arguments #

The hook takes the same arguments as the poetry command. For more information see the install command.

Usage #

For more information on how to use pre-commit please see the official documentation.

A minimalistic .pre-commit-config.yaml example:

repos:
-   repo: https://github.com/python-poetry/poetry
    rev: ''  # add version here
    hooks:
    -   id: poetry-check
    -   id: poetry-lock
    -   id: poetry-export
    -   id: poetry-install

A .pre-commit-config.yaml example for a monorepo setup or if the pyproject.toml file is not in the root directory:

repos:
-   repo: https://github.com/python-poetry/poetry
    rev: ''  # add version here
    hooks:
    -   id: poetry-check
        args: ["-C", "./subdirectory"]
    -   id: poetry-lock
        args: ["-C", "./subdirectory"]
    -   id: poetry-export
        args: ["-C", "./subdirectory", "-f", "requirements.txt", "-o", "./subdirectory/requirements.txt"]
    -   id: poetry-install
        args: ["-C", "./subdirectory"]

FAQ #

Why does pre-commit autoupdate not update to the latest version? #

pre-commit autoupdate updates the rev for each repository defined in your .pre-commit-config.yaml to the latest available tag in the default branch.

Poetry follows a branching strategy where the default branch is the active development branch, and fixes get backported to stable branches. New tags are assigned in these stable branches.

pre-commit does not support such a branching strategy and has decided to not implement an option, either on the user’s side or the hook author’s side, to define a branch for looking up the latest available tag.

Thus, pre-commit autoupdate is not usable for the hooks described here.

You can avoid changing the rev to an unexpected value by using the --repo parameter (may be specified multiple times), to explicitly list repositories that should be updated. An option to explicitly exclude repositories will not be implemented into pre-commit.