pre-commit: Automated Git Hooks for Python

Every tool covered so far in this section — Ruff for linting and formatting, mypy for type verification — genuinely provides real value, but only in the moment someone actually runs it. A tool that's configured, documented in a README, and generally agreed to be valuable, but that depends on every individual developer remembering to manually run it before every commit, has a structural weakness: under deadline pressure, when someone's new to the team and hasn't internalized the workflow yet, or simply out of an ordinary human lapse, it *will* eventually be skipped — not because anyone disagrees it's valuable, but because manual, memory-dependent processes have a predictable, non-zero failure rate at scale, across enough commits and enough people.

The pre-commit framework closes exactly this gap by converting 'please remember to run these checks' into an automated git hook — a script that git itself invokes automatically at a specific point in the commit process (specifically, right before the commit is finalized), with no dependency on any individual remembering to trigger it manually. pre-commit install, run once per local clone of a repository, registers this hook with git; from that point forward, every git commit in that clone automatically triggers the configured checks first, with zero further action required from the developer beyond the ordinary act of committing.

This is the specific mechanism that makes 'we use Ruff and mypy' an actually *enforced* team practice rather than an aspirational one — the tools' value was always real, but pre-commit is what guarantees that value is consistently realized, for every commit, by every contributor, without relying on discipline or memory alone.

The critical detail that makes pre-commit an actual enforcement mechanism, not merely a convenience: a failing hook doesn't just print a warning alongside a commit that proceeds anyway — it blocks the commit from happening at all. git commit -m "..." with a failing ruff hook exits with a non-zero status, the commit is not created, and the developer sees exactly what failed (F401 'os' imported but unused, in the example) and must resolve it — fix the code, or explicitly override the hook if the situation genuinely warrants it — before that commit can actually complete.

This genuine blocking behavior is precisely what distinguishes pre-commit from a purely advisory tool. A check that merely prints a warning is easy to see, acknowledge, and proceed past anyway, especially under time pressure — exactly the human behavior pattern this section's earlier lessons noted about linting speed and friction. A check that structurally prevents the commit from completing removes that path of least resistance entirely; the only way forward is actually resolving the issue (or making a conscious, deliberate decision to bypass the hook, which most teams configure to require explicit intent, like git commit --no-verify, rather than being the accidental default).

Many hooks configured with --fix (like the ruff hook in the example) will *automatically resolve* many findings as part of running, meaning the blocked-commit experience for common, automatically-fixable issues is often just: the hook runs, fixes the issue, stages the fix, and the developer simply re-runs git commit — a low-friction correction, not a demand for extensive manual intervention, for the routine cases the auto-fix capability actually covers.

A newly-installed pre-commit hook only checks files actually involved in each *new* commit going forward — it has no natural mechanism for retroactively checking an entire, potentially large, pre-existing codebase that predates pre-commit's introduction. pre-commit run --all-files fills exactly this gap: it applies every configured hook to *every* file in the repository in one pass, regardless of whether those files are part of any pending commit — precisely what's needed the first time pre-commit is introduced into an existing project with its own accumulated, unaddressed formatting and linting debt.

This is also the standard way pre-commit is typically verified in CI, as a complementary safety net alongside the local git hook: even with pre-commit install documented and expected of every contributor, a CI step running pre-commit run --all-files (or the equivalent, checking the specific changed files in a pull request) provides a genuine backstop — catching the rare case where a contributor's local hook wasn't installed correctly, was deliberately bypassed with --no-verify, or simply wasn't set up yet for a brand-new contributor's very first commit.

This local-hook-plus-CI-backstop combination is the complete, professional pattern: the local hook provides fast, immediate feedback exactly at the moment of committing (the cheapest possible point to catch and fix an issue), while the CI check provides a genuine, unbypassable guarantee that nothing slips through regardless of any individual contributor's local setup — defense in depth applied specifically to code quality enforcement, mirroring the same layered-defense philosophy this curriculum's security section applied to a different category of risk.

A linting rule that everyone agrees is a good idea, but that depends on each person remembering to run it manually, will eventually be skipped by someone, under deadline pressure. pre-commit removes that dependency on memory entirely.

pre-commit runs configured checks (Ruff, mypy, and others) AUTOMATICALLY before every git commit -- not something a developer has to remember to trigger manually.

Once installed, EVERY 'git commit' automatically triggers the configured hooks first -- a failing check BLOCKS the commit from happening at all.

Checkpoint: What actually happens if a pre-commit hook (like ruff) fails during "git commit"?

• →The commit itself is blocked and does not happen at all until the issue is resolved
• →A warning is printed, but the commit proceeds normally regardless

pre-commit run --all-files applies the SAME checks to the entire existing codebase -- useful for onboarding pre-commit into an existing project, and for CI verification.

Checkpoint: Why does pre-commit run --all-files exist, given that a normal commit only checks staged/changed files?

• →It lets you apply the same checks to the ENTIRE codebase at once, useful for onboarding pre-commit into an existing project or for a full CI verification pass
• →It runs faster than checking only staged files

That completes the core Developer Tools toolkit — Ruff, Black, mypy, and now pre-commit enforcement. VS Code Debugger closes this section with the interactive debugging tooling every professional Python developer relies on.

Gate a Real Commit on Hook Results. Finish should_allow_commit(): even one failing hook blocks the commit entirely.