Skip to content

Latest commit

 

History

History
118 lines (79 loc) · 3.57 KB

using-hooks.rst

File metadata and controls

118 lines (79 loc) · 3.57 KB
Raw

Using Version Control Hooks

Usage with the pre-commit git hooks framework

|Flake8| can be included as a hook for pre-commit. The easiest way to get started is to add this configuration to your .pre-commit-config.yaml:

-   repo: https://gitlab.com/pycqa/flake8
    rev: ''  # pick a git hash / tag to point to
    hooks:
    -   id: flake8

See the pre-commit docs for how to customize this configuration.

Checked-in python files will be passed as positional arguments. flake8 will always lint explicitly passed arguments (:option:`flake8 --exclude` has no effect). Instead use pre-commit's exclude: ... regex to exclude files. pre-commit won't ever pass untracked files to flake8 so excluding .git / .tox / etc. is unnecesary.

-   id: flake8
    exclude: ^testing/(data|examples)/

pre-commit creates an isolated environment for hooks. To use flake8 plugins, use the additional_dependencies setting.

-   id: flake8
    additional_dependencies: [flake8-docstrings]

Built-in Hook Integration

Note

It is strongly suggested to use |Flake8| via pre-commit over the built-in hook mechanisms. pre-commit smooths out many of the rough edges of git and is much more battle-tested than the |Flake8| hook impementation.

|Flake8| can be integrated into your development workflow in many ways. A default installation of |Flake8| can install pre-commit hooks for both Git and Mercurial. To install a built-in hook, you can use the :option:`flake8 --install-hook` command-line option. For example, you can install a git pre-commit hook by running:

.. prompt:: bash

    flake8 --install-hook git

This will install the pre-commit hook into .git/hooks/. Alternatively, you can install the mercurial commit hook by running

.. prompt:: bash

    flake8 --install-hook mercurial

Preventing Commits

By default, |Flake8| does not prevent you from creating a commit with these hooks. Both hooks can be configured to be strict easily.

Both our Git and Mercurial hooks check for the presence of flake8.strict in each VCS' config. For example, you might configure this like so:

.. prompt:: bash

    git config --bool flake8.strict true
    hg config flake8.strict true

Checking All Modified Files Currently Tracked

Note

Mercurial does not have the concept of an index or "stage" as best as I understand.

|Flake8| aims to make smart choices that keep things fast for users where possible. As a result, the |Flake8| Git pre-commit will default to only checking files that have been staged (i.e., added to the index). If, however, you are keen to be lazy and not independenty add files to your git index, you can set flake8.lazy to true (similar to how you would set flake8.strict above) and this will check all tracked files.

This is to support users who often find themselves doing things like:

.. prompt:: bash

    git commit -a

Note

If you have files you have not yet added to the index, |Flake8| will not see these and will not check them for you. You must git-add them first.