Skip to content

pre-commit

Runs checks such as linters and formatters automatically before every Git commit, as configured in the project.

pre-commit output

Syntax

pre-commit install | run [--all-files] | autoupdate | uninstall

Options

Option Description
install Set up the Git hook in .git/hooks/pre-commit
run Run the checks on the staged files
run --all-files Run them on all files, for example after setting it up
run HOOK_ID Only one check, such as shellcheck
autoupdate Update the versions of the hooks in the configuration
uninstall Remove the Git hook

The checks are listed in .pre-commit-config.yaml in the repository, each with a fixed version.

Examples

Set up the hook in a repository:

pre-commit install
pre-commit installed at .git/hooks/pre-commit

The configuration:

cat .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
  - repo: https://github.com/shellcheck-py/shellcheck-py
    rev: v0.10.0.1
    hooks:
      - id: shellcheck

Check all files once:

pre-commit run --all-files
trim trailing whitespace.................................................Failed
- hook id: trailing-whitespace
- exit code: 1
- files were modified by this hook

Fixing scripts/deploy.sh

fix end of files.........................................................Passed
check yaml...............................................................Failed
- hook id: check-yaml
- exit code: 1

while constructing a mapping
  in "compose.yaml", line 3, column 5
found duplicate key "restart" with value "unless-stopped" (original value: "yes")
  in "compose.yaml", line 7, column 5

shellcheck...............................................................Failed
- hook id: shellcheck
- exit code: 1

In scripts/deploy.sh line 2:
rm -rf $TARGET/old
       ^-----^ SC2086 (info): Double quote to prevent globbing and word splitting.

The first run downloads the hooks into ~/.cache/pre-commit, which takes a moment. The trailing spaces were fixed right away; the other two problems you fix yourself.

A commit is stopped:

git commit -m "Add deploy script"
trim trailing whitespace.................................................Passed
fix end of files.........................................................Passed
check yaml...............................................................Passed
shellcheck...............................................................Failed
- hook id: shellcheck
- exit code: 1

In scripts/deploy.sh line 2:
rm -rf $TARGET/old
       ^-----^ SC2086 (info): Double quote to prevent globbing and word splitting.

Did you mean:
rm -rf "$TARGET"/old

The commit wasn't created. Fix the script, git add it again and commit.

When do I need it?

  • So that mistakes are caught on your machine instead of in the pipeline
  • To give everyone in a team the same checks with one command
  • To fix trailing spaces and missing line ends automatically

The same checks in the pipeline

Run pre-commit run --all-files as a step in CI too. Then nothing gets through that skipped the hook on someone's machine.

Hooks can be skipped

git commit --no-verify skips all hooks. pre-commit is a help, not a guarantee, which is why the pipeline should check as well.

Distribution differences

Debian Ubuntu RHEL Arch
Install sudo apt install pre-commit sudo apt install pre-commit pipx install pre-commit sudo pacman -S pre-commit

yamllint · actionlint · git commit · shellcheck