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.

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.

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.

Are there any alternatives to pre-commit autoupdate? #

You may use pre-commit-update as an alternative to pre-commit autoupdate.

Since pre-commit-update can be used as a pre-commit hook itself, the easiest way to make use of it would be to include it inside .pre-commit-config.yaml:

repos:
-   repo: https://gitlab.com/vojko.pribudic.foss/pre-commit-update
    rev: v0.5.1post1
    hooks:
    -   id: pre-commit-update
-   repo: https://github.com/python-poetry/poetry
    rev: 1.8.3
    hooks:
    -   id: poetry-check
    -   id: poetry-lock
    -   id: poetry-export
    -   id: poetry-install

Your .pre-commit-config.yaml repos will be checked and updated every time pre-commit hooks run.

For more advanced configuration, please check the pre-commit-update documentation.