Filter-pre-commit-hooks

Small Python program that extracts and filters pre-commit hooks so that only a subset of them can be executed. Why is such a program helpful? Pre-commit only provides a way to skip hooks. There is no way to explicitly state which hooks should be run.

The program is available in this repository as the script filter_pre_commit_hooks.py and as the package filter-pre-commit-hooks on PyPI.

By default, the program returns all hooks that have the given tags. In the following example, all pre-commit hooks that are tagged with fix and task are executed (tagging is described further below):

SKIP=$(uv run -s filter_pre_commit_hooks.py fix task) pre-commit run -a

The program itself is executed with uv run, a subcommand of uv, which is a package manager for Python. This is because the script contains inline script metadata specifying required dependencies. The script also contains a shebang, so it can be executed directly.

Using the package from PyPI, the equivalent command looks like this:

SKIP=$(filter-pre-commit-hooks fix task) pre-commit run -a

Tags are extracted from the "alias" field of every hook. Tags are declared by putting them into parenthesis at the end of the respective alias. Individual tags are separated by commas. Here are two exemplary aliases:

forbid-new-submodules (check, task)
mixed-line-ending (fix, task)

Options can be passed to the script to change the behavior of the script. For example, to filter hooks by their identifier instead of their tags. For more information on this, try out the --help option of the script or read the source code.

A valid config used with the script can be found in .pre-commit-config.yaml. Some tasks in Justfile run selected pre-commit hooks using the script.

Shell completion

This program uses Click for the CLI. Click provides automatically generated shell completion for Bash, Fish, and Zsh. Check out the official documentation here.

Project status

The project is maintained by me, Tim, and I am interested in keeping it alive as I am actively using it.

Versioning

The project follows Semantic Versioning.

Contributing

Contributions are welcome. Please refer to CONTRIBUTE.md.

Licensing

This work is licensed under the ISC license. See LICENSE for the license text.

The license is also included in the script filter_pre_commit_hooks.py itself.

Template

This project is based on the following Copier template: https://github.com/trallnag/copier-template-python-script.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

filter_pre_commit_hooks-3.0.0.tar.gz (40.2 kB view details)

Uploaded Jul 11, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

filter_pre_commit_hooks-3.0.0-py3-none-any.whl (7.3 kB view details)

Uploaded Jul 11, 2026 Python 3

File details

Details for the file filter_pre_commit_hooks-3.0.0.tar.gz.

File metadata

Download URL: filter_pre_commit_hooks-3.0.0.tar.gz
Upload date: Jul 11, 2026
Size: 40.2 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for filter_pre_commit_hooks-3.0.0.tar.gz
Algorithm	Hash digest
SHA256	`722db7dc3ba24a6050e4939b09e30e7c1150aa1c8508b3d71f36a81cb0e434a2`
MD5	`6a2a22c20d3872a2a45d0dac53d1867c`
BLAKE2b-256	`d2898f53386902b5c39865cd303d212912a629da59ec3e6453f7a145b3e78b6b`

See more details on using hashes here.

Provenance

The following attestation bundles were made for filter_pre_commit_hooks-3.0.0.tar.gz:

Publisher: release.yaml on trallnag/filter-pre-commit-hooks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: filter_pre_commit_hooks-3.0.0.tar.gz
- Subject digest: 722db7dc3ba24a6050e4939b09e30e7c1150aa1c8508b3d71f36a81cb0e434a2
- Sigstore transparency entry: 2145599256
- Sigstore integration time: Jul 11, 2026
Source repository:
- Permalink: trallnag/filter-pre-commit-hooks@2099001c97220892202bfd74eba6d844d2888617
- Branch / Tag: refs/tags/v3.0.0
- Owner: https://github.com/trallnag
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yaml@2099001c97220892202bfd74eba6d844d2888617
- Trigger Event: push