{"canonical_url":"https://engineer.company/glossary/git-hook/","content_markdown":"# git hook\n\n## What it is\n\nA git hook is a program that git itself starts at a fixed point in its own work:\nbefore a commit is recorded, once a commit message has been written, before a\npush leaves the machine, or when a server receives one. Each hook is a file\nnamed after its moment, such as `pre-commit`, `commit-msg` or `pre-push`, with\nno extension. By default git looks for them in `.git/hooks` inside the\nrepository, and the `core.hooksPath` setting points it elsewhere. The file has\nto be executable, since git ignores one without the executable bit, but it can\nbe written in any language the machine runs.\n\nClient-side hooks run in a developer's own clone and fire on operations such as\ncommitting and merging. Server-side hooks run on the machine that receives\npushes, such as a forge, and fire when pushed commits arrive.\n\nWhat turns a hook from a notification into a guard is its exit status. The\n`pre-commit` hook takes no arguments, and a non-zero exit aborts the commit. The\n`commit-msg` hook receives the path of a file holding the proposed message and\nmay reject the message or edit it. The `pre-push` hook gets the remote's name\nand location as arguments and one line per reference on standard input, and a\nnon-zero exit stops the push before anything is sent. On the server,\n`pre-receive` runs once per push, reads the old object name, new object name and\nreference name for each reference, and if it exits non-zero, none of the\nreferences are updated. Hooks that run after the event, such as `post-commit`,\nare meant for notification and cannot change its outcome.\n\nWhen `git init` creates a repository, it fills the hooks directory with example\nscripts whose names end in `.sample`. git runs one only after it has been\nrenamed without the suffix.\n\n## Why it matters\n\nA hook turns a check that someone has to remember into one that happens on its\nown, at the cheapest moment. A formatter or a secret scanner that runs as the\ncommit is made catches a problem while the change is still in its author's head,\nrather than in review days later or in a CI run after the work has been shared.\n\nHooks are also how a rule becomes a property of a repository rather than of\nwhoever happens to be committing. A convention in a contributing guide holds\nonly as long as people read the guide; the same convention in a `commit-msg`\nhook applies to every commit.\n\nThe two groups differ in how much they can promise. The Pro Git book points out\nthat cloning a repository does not copy its client-side hooks, and recommends\nenforcing policy on the server side. A server-side hook such as `pre-receive`\napplies to every push from everyone, whatever they have installed locally. The\ncost is time: a hook runs on every commit or every push, and a check that makes\ncommitting slow invites people to skip it.\n\n## What it looks like in practice\n\nThis site's own repository installs its hooks through the pre-commit framework,\nconfigured in `.pre-commit-config.yaml` and installed by `task setup`, which\nruns `pre-commit install --install-hooks`. The file installs three git hooks. At\nthe pre-commit stage it runs Prettier, markdownlint, stylelint, yamllint,\ncodespell, Ruff's lint and format checks, a gitleaks secret scan, an emoji check\nand a tone check. At the commit-msg stage it runs\none script that holds messages to a conventional, emoji-free form. At the\npre-push stage it runs the whole gate, `task check`, which takes minutes rather\nthan seconds, a price the comment on that hook accepts because a push is rare.\nThe file's header says never to bypass the hooks with `--no-verify`, and that\ncomment holds to it: a push that cannot wait is not ready.\n\nA commit-message hook also holds\n[four repositories to one history standard](/portfolio/held-4-repositories-to-one-history-standard/):\na conventional prefix and scope, a subject under a fixed length, no emojis and\nno attribution trailers. The hook rejects anything that does not conform in\nevery repository that carries work, so the standard belongs to the repository\nrather than to whoever commits.\n\n[A server-side hook for the company's own forge was rehearsed](/portfolio/rehearsed-the-forge-ci-hook-found-2-defects/)\nbefore any real push reached it. Such a hook executes in a bare repository with\nno working tree, under an environment the forge sets, reading pushed references\nfrom standard input, so running it by hand on a laptop proves little. The\nrehearsal creates a bare repository, installs the hook, clones, commits, pushes\nand asserts on both the accept and the reject path. It found two defects that\nwere invisible in the file, both described below.\n\nOn one project,\n[the commit hook and the quality gate turned out to run different checks](/portfolio/found-the-hooks-and-the-gate-disagreeing/),\nalthough a document said the hook ran the gate. A test now resolves both to the\nchecks they actually invoke and fails when the sets diverge. The five that had\nrun only in the gate were the ones reading the CV prose, so the code was guarded\non every commit and the writing only when someone remembered.\n\nA client-side hook does not need a framework at all. This one, saved as\n`.git/hooks/commit-msg` and made executable, rejects a commit whose subject does\nnot start with a conventional type:\n\n```sh\n#!/bin/sh\n# git passes the path of the proposed commit message as $1\npattern='^(feat|fix|docs|chore)(\\([a-z0-9-]+\\))?: .+'\nif head -n 1 \"$1\" | grep -Eq \"$pattern\"; then\n    exit 0\nfi\necho \"commit-msg: start the subject with a type, as in 'fix(nav): ...'\" \u003e\u00262\nexit 1\n```\n\n## Where it goes wrong\n\n- **A fresh clone arrives without the hooks.** Each clone has to install them,\n  which is the job `task setup` does here. A comment in this site's\n  `Taskfile.yml` spells out the quiet version of the failure: without\n  `pre-commit` on the machine, `task setup` installs nothing, every hook\n  silently does not run, and the result looks exactly like a repository that is\n  passing.\n- **`--no-verify` walks straight past them.** `git commit --no-verify` bypasses\n  the `pre-commit` and `commit-msg` hooks, `git push --no-verify` bypasses\n  `pre-push`, and setting `core.hooksPath` to `/dev/null` turns off every hook\n  at once. A rule that must hold belongs in a server-side hook as well.\n- **git's environment follows the hook into other repositories.** git exports\n  variables such as `GIT_DIR` so that git commands in a hook find the right\n  repository, and githooks(5) advises clearing them when a hook works in another\n  one. The forge rehearsal met exactly this: the gate checked out the pushed\n  revision and ran the tests inside it, the tests inherited git's pointer to the\n  bare repository, and nineteen of them went red on correct code.\n- **Standard input carries the edge cases.** The rehearsal's other defect was a\n  fallback that, with no reference to work with, substituted a placeholder git\n  cannot resolve; because the value arrives on standard input, the failure\n  surfaced as an unrelated error much further down. The page also notes that the\n  forge will see forced updates and branch deletions, which the rehearsal does\n  not construct. In githooks(5), a deleted reference reaches `pre-push` as\n  `(delete)` with an all-zeroes object name.\n- **A slow hook gets skipped.** Bringing the five prose checks into the commit\n  hook meant making two of them fast enough for a pre-commit budget, and that\n  page is plain that runtime grows with the content and that there is a point at\n  which a slow hook gets bypassed.\n- **The format passes and the meaning goes unchecked.** As the page on the four\n  repositories puts it, the format is checked and the content is not, so a\n  conforming subject line that describes nothing passes exactly as well as one\n  that explains the change.\n\n## Further reading\n\n- [githooks documentation](https://git-scm.com/docs/githooks) — every hook git\n  supports, when it runs, what it receives and what its exit status decides.\n- [Pro Git: Git Hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks)\n  — client-side and server-side hooks, how to install one, and why a clone\n  leaves them behind.\n- [Pro Git: An Example Git-Enforced Policy](https://git-scm.com/book/en/v2/Customizing-Git-An-Example-Git-Enforced-Policy)\n  — a server-side `update` hook that enforces a message format and access rules,\n  with client-side hooks that warn before a push.\n- [git config](https://git-scm.com/docs/git-config) — the `core.hooksPath`\n  setting, for moving hooks out of `.git/hooks` or switching them all off.\n- [git commit](https://git-scm.com/docs/git-commit) — the `--no-verify` option\n  and the two hooks it bypasses.\n- [git push](https://git-scm.com/docs/git-push) — the `pre-push` hook and the\n  `--no-verify` option that skips it.\n\n\u003chttps://engineer.company/glossary/git-hook/\u003e\n","date_modified":"2026-10-24T11:22:25Z","description":"How git hooks stop a bad commit or push at the moment it happens, why a fresh clone arrives without them, and the ways they get quietly skipped.","formats":{"gemtext":"https://engineer.company/glossary/git-hook/index.gmi","gopher":"https://engineer.company/glossary/git-hook/gophermap","html":"https://engineer.company/glossary/git-hook/","json":"https://engineer.company/glossary/git-hook/index.json","markdown":"https://engineer.company/glossary/git-hook/index.md","pdf":"https://engineer.company/glossary/git-hook/index.pdf"},"kind":"page","language":"en","title":"What is a git hook?","url":"https://engineer.company/glossary/git-hook/","version":1}