Automate Git Hooks for Code Quality

This guide builds a local feedback loop around Git events. It explains native hooks and shared configurations using Husky, lint-staged, commitlint, and the Python pre-commit framework. Checks can format staged files, run linters, validate Conventional Commit messages, or execute tests before a push. The emphasis is on predictable, quick checks that developers can understand and maintain.

Native hooks live in a repository's .git/hooks directory and are not shared automatically. The guide covers pre-commit, prepare-commit-msg, commit-msg, post-commit, pre-push, pre-rebase, post-merge, and post-checkout, with different responsibilities for each event. Frameworks provide a way to distribute configuration through the repository rather than relying on manual installation of individual local scripts.

Use this material when a project needs earlier feedback on formatting, linting, commit messages, or a small set of relevant tests. Husky v9+ and lint-staged suit JavaScript projects; pre-commit can coordinate checks across languages, including Black, Ruff, and ShellCheck. Commitlint rules can encode the team's chosen commit convention. Example limits and type lists are configuration choices, not universal requirements.

Keep local hooks fast and focused on affected files. Adopt checks gradually to keep feedback short: begin with formatting, then add linting, message checks, and appropriate tests. Expensive checks belong in the shared validation process. A locally successful hook cannot establish that every required check passed, and bypassable hooks must not become the sole enforcement point for a merge policy. CI must enforce the required rules independently.

Inputs include repository scripts, package versions, staged paths, language-specific configuration, and the team's commit policy. A Husky pre-commit hook can invoke the staged-file runner:

npx --no -- lint-staged

The result is immediate feedback or a rejected local operation with an actionable failure. Formatting automation must preserve partially staged changes. Avoid a blanket git add that stages unrelated edits. Custom shell hooks also need careful filename handling: simplistic line-oriented loops can break on spaces or unusual names, and inspecting working files may check different content from the staged snapshot. Secret detection should report a finding without printing the secret itself.

Installation and troubleshooting cover executable permissions, missing dependencies, incorrect paths, and hook configuration. Inspect an existing core.hooksPath before replacing it. When migrating older Husky setups, preserve current configuration and make targeted changes instead of deleting hook directories blindly. Verify commands against the installed major version, and review pinned third-party checks before introducing them.

The examples provide starting points for portable hooks and shared policy. Adapt them to the repository's actual scripts, staged-file behavior, and CI requirements; debugging a skipped or stale hook is part of setup, not proof that the policy is already enforced.