hk install

• How to hail it: hk install [FLAGS]
• Also answers to: i
• Effect: modifies state (it touches, as well as looks)

Set up git hooks to run hk: rig the bosun's pipes that call all hands on deck.

The recommended setup is hk install --global. It installs the hooks once into the user's global git config (~/.gitconfig, or ~/.config/git/config when that be the one git uses), so the whole fleet, every ship on the machine, picks them up automatically. In a project without an hk.pkl, with no charts aboard, the installed hook exits silently and does nothing (a no-op), so 'tis safe to enable everywhere ye sail. Requires Git 2.54+.

Without --global, the hooks are installed into the current ship only. On Git 2.54+ this uses config-based hooks (hook.<name>.command), which leave .git/hooks/ untouched and work cleanly alongside other hook managers. On older Git it falls back to writing script shims.

If hk is already configured globally (any hook.hk-* entry in the global git config), the per-repo install is skipped — and any stale local hooks are cleaned up — so the global install remains the single source of truth and hk doesn't fire twice per event. Pass --force-local to install local hooks anyway. The skip does not apply with --legacy or on Git older than 2.54, which cannot read the global hooks: there the local script shims are installed.

Flags to fly

• --force-local — Rig local hooks on this ship even when hk is already configured globally (any hook.hk-* entry in the global git config). By default a per-repo install is skipped in that case, so hk doesn't fire twice per event. Not compatible with --global.

• --global — Recommended. Install in the global git config so every ship on this machine gets hk hooks. Requires Git 2.54 or newer. In repos without an hk.pkl, the installed hook is a silent no-op: the pipe sounds and nobody is called.

• --legacy — Force the old rigging: legacy .git/hooks/ script shims instead of Git 2.54+ config-based hooks. Installs the shims even when hk is already configured globally, because Git older than 2.54 does not read global hooks. On Git 2.54+, hk then runs twice for each event that has both a global hook and a shim. Not compatible with --global.

• --force — With the legacy .git/hooks/ script shims, replace an existing hook that hk did not write, and replace a symlinked hook with a regular file (the symlink's target is left alone). By default hk refuses to install if any target is a hook it did not write or a symlink, and installs nothing.

• --mise — Run hooks through mise x, so the tools the quartermaster (mise) manages are on hand without activating mise in the shell.

  Set HK_MISE=1 as a standing order to make this the default behavior.

• -h --help — Print help, for when ye've lost yer bearings

Tales from the deck

Choose a local installation, for one ship, or a global one on Git 2.54+, for the whole fleet. Add --mise when Git needs mise to provide the tools.

hk install

# Alternative: install once for all repositories
hk install --global

Further charts

Getting started: get under way · Troubleshooting: the ship's log · All the bosun's calls