pre-commit

Install pre-commit into your Git hooks

$ pre-commit install

$ pre-commit run

$ pre-commit run --all-files

$ pre-commit clean

$ pre-commit autoupdate

pre-commit <subcommand> [options]

install
    Installs the Git hooks scripts into the .git/hooks/pre-commit directory, allowing pre-commit to run automatically before each commit.

run [<hook-id> ...]
    Manually runs the configured hooks against the current staged files or specified files. Useful for testing hooks or running them outside of a commit.

autoupdate
    Automatically updates the versions of the hooks defined in .pre-commit-config.yaml to their latest stable versions.

uninstall
    Removes the pre-commit Git hook scripts from the repository, restoring the default Git hook behavior.

clean
    Clears the pre-commit cache, which can resolve issues with stale hook installations or corrupted environments.

try-repo <repository>
    Tests a single hook from a specified repository without needing to add it to your configuration file.

--config <path>
    Specifies an alternative path to the pre-commit configuration file (default is .pre-commit-config.yaml).

--version
    Displays the installed version of the pre-commit framework.

--help
    Shows help message for the pre-commit command or a specific subcommand.

The pre-commit command, more accurately described as the pre-commit framework, is a powerful and extensible Python-based tool designed to standardize and manage Git pre-commit hooks in repositories. It helps developers enforce code quality, consistency, and style guidelines before code is committed, preventing common errors and ensuring a cleaner codebase.

Instead of manually setting up individual Git hooks, pre-commit allows you to define a list of hooks (often linters, formatters, or security checks) in a central configuration file (typically .pre-commit-config.yaml). When pre-commit is installed in a repository, it automatically runs these defined hooks against the staged files every time a developer attempts to commit changes. If any hook fails, the commit is aborted, prompting the developer to fix the issues.

This framework significantly reduces the overhead of maintaining consistent development practices across teams, automates tedious checks, and helps maintain a high standard of code quality throughout the project lifecycle. It supports hooks written in various languages and can be easily integrated into any Git repository.

The pre-commit framework requires Python to be installed on the system to function. It relies heavily on the .pre-commit-config.yaml file for its configuration; without this file, or if it's malformed, pre-commit will not know which hooks to run. Overly complex or slow hooks can significantly delay the commit process, impacting developer experience. Initial setup is per-repository and requires running `pre-commit install` once.

The core of pre-commit's functionality is defined in the .pre-commit-config.yaml file, located at the root of your Git repository. This YAML file specifies which hook repositories to use, the version of those repositories, and the specific hooks to run. It allows for detailed configuration of individual hooks, including arguments, file types to include or exclude, and more. This centralized configuration ensures that all developers working on the repository use the same set of quality checks.

While named 'pre-commit', the framework can manage hooks for various Git stages. Although its primary use case is the pre-commit hook, it can also support other hook types like pre-push (run before `git push`), pre-merge-commit, and commit-msg, allowing for a broader range of automated checks and validations throughout the Git workflow. This flexibility makes it a versatile tool for maintaining repository hygiene beyond just staged files.

The pre-commit framework was created by Anthony Sottile and first released in 2014. It emerged as a solution to the common problem of manually managing Git hooks and ensuring consistent code quality across development teams. Before pre-commit, developers would often share scripts or rely on ad-hoc solutions, leading to inconsistencies and maintenance challenges. Since its inception, pre-commit has gained significant popularity within the Python community and beyond, becoming a de facto standard for automating code quality checks in Git repositories due to its ease of use, extensibility, and robust ecosystem of pre-built hooks.

git(1), git-hooks(5)