Pre-commit hook
This page explains how to set up the deadcode pre-commit hook, how to use it, and why its behaviour can differ from a direct deadcode . run.
What the hook checks
The hook runs deadcode on the Python files that pre-commit passes to it. The commit is blocked when deadcode finds unused code, because the hook exits with a non-zero status.
Install
Install pre-commit in the environment where you create commits:
pip install pre-commit
Then install the Git hook in the repository:
pre-commit install
Configuration
Create a .pre-commit-config.yaml file in the root of your project directory, if it does not exist, and add the following:
repos:
- repo: https://github.com/albertas/deadcode
rev: v2.6.3
hooks:
- id: deadcode
The rev is a release tag
rev must be a released X.Y.Z tag, not a branch name or a raw commit SHA. The tag matches the version published on PyPI, so the hook installs the same released package.
To move to a newer release, run pre-commit autoupdate. It updates rev to the latest release tag.
Automatic fixing
Add args: [--fix] to let the hook remove the findings instead of only reporting them:
repos:
- repo: https://github.com/albertas/deadcode
rev: v2.6.3
hooks:
- id: deadcode
args: [--fix]
The findings are removed from the changed files, and the hook exits 1 on the run that changed files. Review the changes with git diff, then run the commit again.
Passing options and file selection
pre-commit appends the matched filenames to the hook command, so the effective command is deadcode <matched files> rather than the deadcode . you type in a terminal. Use the hook definition to control the file set:
types: [python]selects Python files only.exclude: ^tests/skips files whose paths match the exclusion expression.require_serial: trueruns the hook one file batch at a time instead of in parallel.
Extra deadcode options go under args, for example args: [--no-color] or args: [--exclude, venv].
Ignoring rules globally
Pass --ignore with one or more rule codes to suppress those findings for the whole hook run:
repos:
- repo: https://github.com/albertas/deadcode
rev: v2.6.3
hooks:
- id: deadcode
args: [--ignore, DC12]
The same rule codes can be configured once in pyproject.toml with [tool.deadcode] ignore = ["DC12"].
Exit status
0when nothing is found.1when unused code is found.2for invalid command-line usage.
pre-commit reports any non-zero hook exit status as a failed hook.
Running on all files
To check the whole repository instead of only the staged files, run:
pre-commit run deadcode --all-files
Troubleshooting: why the hook differs from deadcode .
A hook run and a direct deadcode . run can give different results. There are three concrete causes:
The hook runs the console script installed from the pinned
revinside pre-commit’s isolated environment, not the deadcode installed in your shell. An olderrevtherefore runs an older deadcode version.The hook analyses only the files matched by
typesandexclude, whiledeadcode .walks the whole tree you point it at.The hook’s output is a captured pipe, and its encoding follows the platform code page (the report showed
cp1252on Windows). Older deadcode versions used a directprintfor some messages and could not encode characters such as✨on that code page. Current versions protect all CLI output, including the parse-failure warning and verbose messages, not only the success message.
Solving it
Update rev to v2.6.0 or newer. Those releases contain the Unicode-safe output chain for CLI messages in general: the success banner, findings, the parse-failure warning and verbose output use a plain print first, then sys.stdout.reconfigure(encoding='utf-8'), then ASCII with ? replacements. The crash no longer occurs.
Setting PYTHONUTF8=1 in the environment is an additional user-side workaround for older pinned versions.