pre-commit: Git Hook Framework for Code Quality Automation¶

Overview¶

pre-commit is a framework for managing and running Git hooks to automatically check or modify code before commits are created. It provides a standardized way to install, configure, and execute code quality tools such as linters, formatters, and security scanners across projects and programming languages.

pre-commit is a general-purpose, language-agnostic tool that works with Git repositories. It is commonly used to enforce code style, detect errors early, and maintain consistent development standards across teams.

Typical use cases include:

(1) Running linters before committing code (2) Automatically formatting source files (3) Preventing commits with syntax or style errors (4) Running security or secret-detection checks (5) Enforcing repository-wide coding standards

Scope and Applicability¶

pre-commit operates at the Git repository level and integrates with local developer workflows.

Supported scenarios:

(1) Local development environments across major operating systems (2) Multiple programming languages in a single repository (3) Integration with CI pipelines (4) Use with both small and large codebases

pre-commit is language-agnostic and executes tools defined in repository configuration.

Core Concepts and Components¶

pre-commit is structured around a configuration file and reusable hook definitions.

Configuration Structure¶

The .pre-commit-config.yaml file defines which hooks are executed.

Minimal example:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer

Each repository entry typically includes:

(1) repo: URL of the hook repository (2) rev: Version or tag to use (3) hooks: List of hook identifiers to enable

Before enabling pre-commit: (1) Create a .pre-commit-config.yaml file in the repository root (2) Select hooks relevant to the project’s languages and standards (3) Pin each hook repository to a specific version (4) Install the hooks locally using the CLI

Installation and Setup¶

Typical setup process:

(1) Install pre-commit using a package manager or Python package installer. (2) Create or add a .pre-commit-config.yaml file to the repository. (3) Run the installation command to register the Git hooks. (4) Commit the configuration file to the repository.

Example installation commands:

pip install pre-commit
pre-commit install

To standardize pre-commit usage across a team: (1) Commit the configuration file to the repository (2) Document the installation command in the project setup guide (3) Optionally run hooks in CI to enforce consistency

Hook Execution Flow¶

This flow describes how pre-commit operates during a commit. It is triggered when a developer attempts to create a commit and results in either a successful commit or a blocked commit with reported issues.

(1) The developer stages changes using Git. (2) The developer runs the git commit command. (3) The pre-commit Git hook is triggered automatically. (4) pre-commit loads the configuration from .pre-commit-config.yaml. (5) Each configured hook runs against the staged files. (6) If a hook modifies files, the commit is paused and the developer must re-stage the changes. (7) If any hook fails, the commit is blocked and errors are reported. (8) If all hooks pass, the commit proceeds successfully.

Common Hook Categories¶

Limitations and Considerations¶

(1) Hooks run locally and may depend on the developer’s environment. (2) Initial hook installation can take time due to environment setup. (3) Some hooks may require language-specific runtimes. (4) Developers must install pre-commit locally for hooks to run automatically.

To ensure hooks are always applied: (1) Run pre-commit in CI pipelines (2) Fail builds when hooks do not pass (3) Keep hook versions pinned and updated regularly

Reference¶

(1) https://pre-commit.com/ (2) https://github.com/pre-commit/pre-commit