Install hook command

commitbrief install-hook

Drop a small shell script at .git/hooks/<name> that runs CommitBrief against the relevant change set, blocking the git operation on a critical-severity finding.

Synopsis

commitbrief install-hook [--hook=<name>] [--uninstall]

Supported hooks

Hook name	Default?	What the body does
pre-commit	✓ (default)	Runs commitbrief --staged --fail-on=critical --quiet --no-cost-check. Blocks the commit on any critical-severity finding.
commit-msg	no	Same body as pre-commit. (Useful when you want the review to happen after the commit message is composed.)
pre-push	no	Reads git's per-ref stdin protocol (<local-ref> <local-sha> <remote-ref> <remote-sha> per line) and runs commitbrief diff <remote>..<local> --fail-on=critical --quiet --no-cost-check for each ref being pushed. Skips branch deletions; for new branches reviews the tip commit.

post-commit, post-receive, and other hooks are intentionally not supported.

Flags

Flag	Notes
--hook=<name>	Which hook to install. Default pre-commit. Must be one of pre-commit, commit-msg, pre-push.
--uninstall	Remove a hook previously written by install-hook. Refuses to touch a hook that does not carry our generated-marker comment.

The global --yes flag allows overwriting an existing hook file (the previous contents are backed up to <name>.bak.<timestamp>).

Embedded absolute path (UC-27)

The generated hook embeds the absolute path of the running commitbrief binary as a single-quoted shell token instead of relying on $PATH lookup. Resolved via os.Executable() plus filepath.EvalSymlinks so the path survives brew upgrade (which swaps the keg symlink target).

This makes the hook work under GUI git clients (Tower, GitHub Desktop, Fork, JetBrains IDEs) that strip the user's shell $PATH and would otherwise fail to find commitbrief if it sits under /opt/homebrew/bin/.

Generated marker

Every hook this command writes contains the verbatim comment:

Generated by `commitbrief install-hook`

--uninstall greps for this marker before removing — a hand-written hook of the same name is never clobbered.

Conflict handling

Situation	Behavior
Target hook does not exist	Write it. Print Installed <path>.
Target hook exists, has our marker, no --yes	Refuse with install-hook: <path> already exists; re-run with --yes to back it up and overwrite.
Target hook exists, has our marker, with --yes	Rename existing to <path>.bak.<UTC-ISO-timestamp>. Write fresh.
Target hook exists, NO marker, with --yes	Same backup + overwrite — the user explicitly opted in.
--uninstall, file missing	No-op success. Print install-hook: no commitbrief hook at <path> (already uninstalled).
--uninstall, marker present	Remove. Print Removed <path>.
--uninstall, marker missing	Refuse with install-hook: <path> was not written by commitbrief; refusing to remove. Delete it manually if intended.

Examples

# Default: install pre-commit hook.
commitbrief install-hook

# Pre-push hook instead.
commitbrief install-hook --hook=pre-push

# Overwrite an existing hook (backup auto-created).
commitbrief install-hook --yes

# Remove the hook we installed earlier.
commitbrief install-hook --uninstall

# Same — for the pre-push variant.
commitbrief install-hook --hook=pre-push --uninstall

See also

• Review command — what the hook body actually runs.
• Diff command — the pre-push body's invocation form.
• Exit codes — how --fail-on=critical decides block / pass.