Supported git hooks

The hooks managed by the pre-commit framework are not limited to being executed before commits; they can also be used for other Git hooks:

commit-msg

commit-msg can be used with:

$ uv run pre-commit install --hook-type commit-msg
pre-commit installed at .git/hooks/commit-msg

The commit-msg hook can be configured with stages: [commit-msg], passing the name of a file containing the current contents of the commit message that can be checked.

post-checkout

The post-checkout hook is called when git checkout or git switch is executed.

The post-checkout hook can be used for example for

  • checking repositories

  • viewing differences from the previous HEAD

  • changing the metadata of the working directory.

In pre-commit it can be used with:

$ uv run pre-commit install --hook-type post-checkout
pre-commit installed at .git/hooks/post-checkout

Since post-checkout does not act on files, always_run must be set for all post-checkout scripts, for example:

- repo: local
  hooks:
  - id: post-checkout-local
    name: Post checkout
    always_run: true
    stages: [post-checkout]
    # …

There are three environment variables that correspond to the three arguments of post-checkout:

$PRE_COMMIT_FROM_REF

returns the reference of the previous HEAD

$PRE_COMMIT_TO_REF

returns the reference of the new HEAD, which may or may not have changed.

$PRE_COMMIT_CHECKOUT_TYPE

returns Flag=1 if it was a branch checkout and Flag=0 if it was a file checkout.

post-merge

As of version 2.11.0, the framework can also execute scripts for the post-merge hook:

$ uv run pre-commit install --hook-type post-merge
pre-commit installed at .git/hooks/post-merge

With $PRE_COMMIT_IS_SQUASH_MERGE you can find out if it was a squash merge.

post-rewrite

post-rewrite is called when commits are rewritten, for example from git commit --amend or from git rebase.

$ uv run pre-commit install --hook-type post-rewrite
pre-commit installed at .git/hooks/post-rewrite

Since post-rewrite does not affect files, always_run: true must be set.

Git tells the post-rewrite hook which command triggered the rewrite. pre-commit outputs this as $PRE_COMMIT_REWRITE_COMMAND.

pre-merge-commit

As of Git 2.24, there is a pre-merge-commit hook that is triggered after a merge is successful but before the merge commit is created. You can use it with the pre-commit framework with:

$ uv run pre-commit install --hook-type pre-merge-commit
pre-commit installed at .git/hooks/pre-merge-commit
pre-push

To use the pre-push hook with the pre-commit framework, enter the following:

$ uv run pre-commit install --hook-type pre-push
pre-commit installed at .git/hooks/pre-push

The following environment variables are provided for this purpose:

$PRE_COMMIT_FROM_REF

The remote revision that was pushed to.

$PRE_COMMIT_TO_REF

The local revision that was pushed to the remote revision.

$PRE_COMMIT_REMOTE_NAME

The local revision that was pushed to the remote revision, for example origin.

$PRE_COMMIT_REMOTE_URL

The URL of the remote repository that was pushed to, for example git@github.com:veit/python4datascience

$PRE_COMMIT_REMOTE_BRANCH

The name of the remote branch that was pushed to, for example refs/heads/TARGET_BRANCH.

$PRE_COMMIT_LOCAL_BRANCH

The name of the local branch that was pushed to the remote branch, for example HEAD.

pre-rebase

Since version 3.2.0, the framework also supports pre-rebase hooks:

$ uv run pre-commit install --hook-type pre-rebase
pre-rebase installed at .git/hooks/pre-rebase

pre-rebase hooks cannot be applied to files, and therefore they must be set as always_run: true, otherwise they will always be skipped.

post-commit

As of version 2.4.0, the framework can also execute post-commit hooks with:

$ uv run pre-commit install --hook-type post-commit
pre-commit installed at .git/hooks/post-commit

However, since post-commit does not work on files, all these hooks must set always_run:

- repo: local
  hooks:
  - id: post-commit-local
    name: post commit
    always_run: true
    stages: [post-commit]
    # …
prepare-commit-msg

prepare-commit-msg can be used with pre-commit with:

$ uv run pre-commit install --hook-type prepare-commit-msg
pre-commit installed at .git/hooks/prepare-commit-msg

The prepare-commit-msg hook is configured with stages: [prepare-commit-msg], passing the name of a file that contains the initial commit message, for example from git commit -m "COMMIT-MESSAGE" to create a dynamic template from it that is displayed in the editor. Finally, the hook should check that no editor is started with GIT_EDITOR=:.