gritHEAD → docs/hooks
Commands / PlumbingMarkdown

grit hooks

List hook scripts and run them by name.

grit hooks
grit hooks list
grit hooks run <NAME> [-- ARGS...]

Description

Discovers traditional hook scripts in the resolved hooks directory (core.hooksPath when set, otherwise .git/hooks). A relative core.hooksPath is relative to the directory hooks run in (the top of the work tree, or the git directory in a bare repository), so the same hooks are found from any subdirectory. Configured hook.<name>.* aliases are resolved when a hook runs, not in the list.

grit hooks run executes every hook registered for the event (config hooks first, then the script in the hooks directory) through the repository CommandRunner. The process exits with the hook's status when a hook ran and returned non-zero.

What a hook prints depends on the output mode. In human mode the hook writes straight to the terminal as it runs, with its stdout sent to stderr (every hook except pre-push, as in Git), so stdout stays free for grit's own output. With --json or --markdown, grit captures both streams and puts them in the result instead (stdout and stderr below), and nothing reaches the terminal.

Hooks run with the invoking environment (including PATH), from the top of the work tree. A script the OS will not execute directly runs through sh: /bin/sh on Unix, while on Windows a script's #! line names its interpreter (#!/bin/sh → sh, #!/usr/bin/env bash → bash), looked up first in the Git for Windows install that owns the git on PATH (usr\bin, bin), then on PATH, skipping the WSL launchers in System32 and WindowsApps. When the interpreter comes from a Git for Windows install, that install's mingw64\bin (or clangarm64\bin, ucrt64\bin, mingw32\bin) and usr\bin go in front of the hook's PATH, as Git does, so grep, sed, env and the other MSYS tools are found. Hook paths, in list output and on the hook's command line, and the repository paths hooks receive (GIT_DIR, GIT_COMMON_DIR, GIT_WORK_TREE, GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY) never carry the Windows \\?\ prefix, so git run inside a hook reads the same index grit wrote. Commit hooks (pre-commit, pre-merge-commit, prepare-commit-msg, commit-msg, post-commit) get GIT_INDEX_FILE for the index being committed, and GIT_EDITOR=: because grit never opens an editor.

When a hook cannot be started at all (for example, its interpreter is missing), the command fails with an error naming the hook, the program it tried to start and the OS error, instead of reporting an exit status:

$ grit hooks run pre-commit
error: failed to run hook pre-commit (.git/hooks/pre-commit): No such file or directory (os error 2)
$ echo $?
1

In --json mode the same message is the error field. grit commit, grit merge and grit rebase report it the same way for the hooks that run before they change anything (the table below); for post-commit and the other hooks that run after an operation completes, it is a warning and the operation still succeeds.

These hooks run before an operation records anything, with Git's arguments and in Git's order. A non-zero exit (or a hook that cannot be started) stops the operation:

Hook Run by Arguments Skipped by --no-verify
pre-commit grit commit, grit merge --continue none yes
pre-merge-commit grit merge and grit pull before a clean merge records its commit none yes
prepare-commit-msg grit commit, then grit merge the message file (.git/COMMIT_EDITMSG, or .git/MERGE_MSG for a merge) and its source: message (-m, -F), commit <oid> (--amend or -C reusing a message), merge (a merge message, always for grit merge) or squash (SQUASH_MSG) no, as in Git
commit-msg grit commit, then grit merge the message file yes
pre-rebase grit rebase and grit pull --rebase when there are commits to replay the upstream as you named it (the configured upstream's full ref, such as refs/remotes/origin/main, when omitted; the commit id for a pull) yes
pre-push grit push before sending anything remote name and URL; stdin lists the refs yes

prepare-commit-msg and commit-msg may rewrite the message file, and the commit records what they leave (an empty message aborts). A merge's message hooks see MERGE_HEAD, as in Git. A refused merge leaves the merged files with MERGE_HEAD recorded and the branch unchanged; finish it with grit merge --continue (or grit commit) or cancel it with grit merge --abort. Changes a pre-merge-commit hook stages (lint-staged style) go into the merge commit. A refused commit or rebase changes nothing. JSON commit output lists hook basenames that actually ran in hooks_run. Replayed commits (grit rebase, grit pick, grit revert) do not run the commit hooks.

Other commands run the hooks Git runs after them, with Git's arguments:

Hook Run by Arguments and stdin
post-checkout grit switch, grit worktree add (after checkout), grit rebase and grit history rewrites that change HEAD's tree <old HEAD> <new HEAD> 1 (all-zero old id from an unborn branch or a new linked worktree); for a rebase, <old tip> <onto> 1 like Git
post-merge grit merge and grit pull after a fast-forward or merge commit (0) or a squash (1) 0 or 1
post-rewrite grit commit --amend (amend), grit rebase and grit history rewrites (rebase) amend or rebase; stdin has one <old> <new> line per rewritten commit

These hooks run after the operation is complete, so their exit status never changes the result, and a hook that cannot be started is a hook_not_run warning. --dry-run and --check run no hooks. grit switch and grit commit list the hooks that ran in their JSON hooks_run field.

reference-transaction

Grit runs the reference-transaction hook for every ref-store transaction that changes direct object ids (create, update, delete, or reflog-only oid lines on HEAD). Pure symbolic updates (for example switching between two existing branches without moving a tip) do not run the hook, matching Git 2.43.

Phase When Exit status
prepared After locks are taken, before any ref or reflog is written Non-zero aborts the whole batch; grit then runs aborted (exit ignored)
committed After the transaction commits successfully Ignored
aborted After prepared refused or the batch was aborted without writing Ignored

Stdin is one line per ref update, sorted by ref name: <old-hex> <new-hex> <ref>\n. Old and new ids use the repository hash width; absent refs or deletions use the null object id. Attached commits on the files backend emit the same HEAD and branch lines Git does (same old and new commit ids, HEAD first lexicographically).

This hook is not skipped by --no-verify on commands that honor --no-verify for other hooks. Configured hook.reference-transaction.* entries and core.hooksPath apply the same way as for other hooks.

Options

grit hooks list

| -n, --limit <N> | List at most N hook scripts (truncated in JSON when more exist). |

Other global options apply.

grit hooks run

Argument Description
NAME Hook basename (e.g. pre-commit).
ARGS Optional arguments after --, forwarded to the hook.

JSON output

Schema: v1. Subcommands: hooks.list, hooks.run.

Field Type Meaning
action string list or run.
hooks array For list: each entry has name, path, executable, and source (hooks_dir or core_hooks_path).
truncated boolean For list: true when more hook scripts existed than returned (-n / --limit).
name string For run: hook basename.
exit_code number For run: subprocess exit code (0 when the hook was missing).
executed boolean For run: whether any hook script ran.
stdout string For run: what the hooks wrote to stdout (lossy UTF-8; empty when no hook ran).
stderr string For run: what the hooks wrote to stderr (lossy UTF-8; empty when no hook ran).

Markdown output

Schema: v1

--markdown renders a table of hooks for list, or a short summary for run followed by the hook's captured output under Hook stdout: and Hook stderr: headings, each in a text code block (a stream the hook left empty is omitted).

Exit status

Code Meaning
0 hooks list or hooks run when the hook exits 0 (or the hook is missing).
varies hooks run returns the hook subprocess exit code (custom).
1 hooks run when a hook could not be started (failure).
2 Invalid flags (usage).

See Exit codes.