Client-Side Hooks

## What a hook is A Git hook is not a plugin API or a config setting — it is just a program that Git executes at a fixed point in a command's lifecycle. Git looks in the repository's hook directory (by default `.git/hooks` inside a normal clone) for a file whose name is exactly the hook point, runs it, and inspects the process exit status. Any language works as long as the file is executable and, on Unix, starts with a shebang line such as `#!/bin/sh` or `#!/usr/bin/env python3`. ## Why the samples don't fire A fresh repository already contains files like `pre-commit.sample` and `commit-msg.sample`, copied from Git's template directory when the repository was created. They are deliberately inert: Git looks for `pre-commit`, not `pre-commit.sample`, so nothing happens until you rename the file and make sure it is executable (`chmod +x`). "I wrote the hook and nothing ran" is nearly always one of three things: wrong filename, missing executable bit, or a bad shebang. ## The exit-code contract The contract is deliberately primitive. - **Exit 0** — the hook approves; Git continues. - **Any non-zero exit** — for a hook that runs *before* the operation, Git aborts. `git commit` creates no commit object, `git push` transfers nothing. That is the whole protocol. There is no rich error object, no severity level, no "warn but continue". If a hook wants to warn without blocking, it prints a message and exits 0. ## Which hooks can actually abort The pre-operation hooks can veto: `pre-commit` (before the message is even collected), `prepare-commit-msg` (before the editor opens), `commit-msg` (after the message is written), and `pre-push` (before any objects go over the wire). The notification hooks cannot: `post-commit`, `post-merge` and `post-checkout` all run after the state change is complete, and Git documents that they cannot affect the outcome. `post-checkout` has one wrinkle — its exit status becomes the exit status of `git checkout`/`git switch`, so a failing hook makes the command *report* failure even though the checkout already happened. ## Talking to the developer Standard output and standard error from a client-side hook go to the terminal, so the human sees them. Practically that means: print the reason for rejection to stderr, keep it to a couple of lines, and name the file or rule that failed. A hook that exits 1 silently produces a mystifying `git commit` that appears to do nothing. ## Hooks run in the repository Git invokes the hook with the working tree as the current directory (for a normal, non-bare repository) and sets Git environment variables such as `GIT_DIR`. A subtlety that bites `pre-commit` hooks: the commit is built from the **index**, not from the working tree, so linting the files on disk can approve content that is not what will be committed. The careful pattern is to inspect staged content, for example `git diff --cached --name-only --diff-filter=ACM`. ## Bypassing `git commit --no-verify` skips `pre-commit` and `commit-msg`; `git push --no-verify` skips `pre-push`. Because the hook is a plain file inside `.git`, a developer can also just delete it or remove its executable bit. That is why client hooks are a fast feedback mechanism, not a guarantee. ## Performance Every pre-operation hook sits directly in the developer's inner loop. A `pre-commit` hook that runs the whole test suite turns a one-second commit into a coffee break and trains the team to type `--no-verify` reflexively. Keep client hooks to sub-second checks on the staged files and let slower verification happen elsewhere.