Install hook command

Home / Commands / install-hook

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.

Caution

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

pre-commit framework (.pre-commit-hooks.yaml)

install-hook writes a native git hook script into .git/hooks/. If you already use the pre-commit framework, CommitBrief also ships a .pre-commit-hooks.yaml manifest so you can wire it in with a one-line entry instead — the two are distinct; pick whichever fits your setup.

Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/CommitBrief/commitbrief
    rev: v1.8.0
    hooks:
      - id: commitbrief          # language: golang — pre-commit builds the binary itself
      # - id: commitbrief-system   # language: system — use a binary already on PATH

Two hook ids are published:

id	language	Use when
commitbrief	golang	The documented default. pre-commit builds and caches the binary in an isolated environment, so a true one-line add works with no prior install.
commitbrief-system	system	You installed commitbrief via Homebrew / Scoop / go install and don't want pre-commit to manage a Go toolchain.

Both run commitbrief --staged --fail-on=high (override args: to change the gate, e.g. args: [--staged, --fail-on=critical]) with pass_filenames: false (CommitBrief fetches the staged diff itself) and stages: [pre-commit].

The hook runs non-interactively (no TTY). The pre-send secret scanner therefore aborts on a detected credential rather than prompting, so a leaked secret blocks the commit; --yes does not bypass the secret scan. If you intentionally need to allow a flagged value, add --allow-secrets to args:.

install-hook vs. the pre-commit framework

	install-hook	.pre-commit-hooks.yaml
What it is	A native git hook script in .git/hooks/	A manifest the pre-commit tool reads
Needs the framework	No	Yes (pre-commit)
Default gate	--fail-on=critical (--quiet --no-cost-check)	--fail-on=high
Installs the binary	No (uses the embedded absolute path)	commitbrief id builds it; commitbrief-system uses PATH

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.