feat(install): use Git 2.54 config-based hooks with --global support

[jdx]

Summary

• On Git 2.54+, hk install now writes config-based hooks (hook.hk-<event>.command / .event) instead of shell shims in .git/hooks/, keeping the hooks directory untouched and composing cleanly with other hook managers. Legacy shim mode is auto-used on older Git (and available via --legacy).
• New hk install --global writes those entries to the user's ~/.gitconfig so hk applies to every repository on the machine. In repos without hk.pkl the invocation is a silent no-op — driven by a new hidden --from-hook flag on hk run that the installed command passes.
• hk uninstall now cleans both modes (script shims + config entries) regardless of current git version, so upgrading git and then uninstalling works. hk uninstall --global is the global counterpart.
• Documented in docs/getting_started.md with a dedicated "Install Hooks Globally (Git 2.54+)" section including both the CLI flow and a hand-rolled ~/.gitconfig example.

How it works

With --global active, git fires every configured event against hk. hk run <event> --from-hook checks that the current repo has an hk.pkl and defines the event; if either is missing it exits 0 silently. So the user installs once and forgets, and repos without hk are unaffected.

Since Git 2.54 doesn't pass the event name to the configured command, there's one config entry per event (hook.hk-pre-commit.*, hook.hk-pre-push.*, etc.) rather than a shared entry — the name discriminates which hk invocation to run.

Test plan

• cargo test — 145 passed (including test_subcommands_are_sorted)
• bats: install_creates_git_hooks, install_warn_hookspath, install_worktree_hooks, uninstall, hook_{args,env,fix_default,stdin}
• Manual smoke test on locally-built git 2.54.0:
  • hk install in a repo writes hook.hk-* config entries and no script files
  • git commit in that repo fires the pre-commit hook via config
  • hk install --global writes 9 client-hook entries to ~/.gitconfig
  • git commit in a repo without hk.pkl (global install active) is a silent no-op and succeeds in ~90ms
  • git commit in a repo with minimal hk.pkl only triggers defined events; others (commit-msg, post-commit, etc.) are silent no-ops
  • Mixed-mode cleanup: a pre-existing shim in .git/hooks/pre-commit is removed when re-running hk install on git 2.54
  • hk uninstall removes both script shims and config entries; hk uninstall --global clears ~/.gitconfig
  • On git < 2.54, hk install --global errors cleanly with an upgrade hint; regular hk install falls back to script shims unchanged

This PR was generated by Claude Code.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes how git hooks are installed/executed (switching from .git/hooks shims to git config hook.* entries on Git 2.54+), plus adds global hook installation, which could affect developer workflows if misconfigured or if both global+local installs overlap.

Overview
On Git 2.54+, hk install now installs hooks via config-based git hooks (hook.hk-<event>.command/.event) instead of writing scripts into .git/hooks/, with --legacy to force the prior shim behavior.

Adds global hook installation/uninstallation via hk install --global / hk uninstall --global, and introduces a hidden hk run --from-hook mode so hook invocations silently no-op when no project hk config (or no matching event) is present.

hk uninstall now removes both legacy shims and config-based entries to support mixed/upgrade scenarios; docs/CLI usage specs and tests are updated accordingly, alongside minor refactors/cleanups (git version detection helper, small test/style tweaks).

^{Reviewed by Cursor Bugbot for commit a5138db. Bugbot is set up for automated code reviews on this repo. Configure here.}

[gemini-code-assist]

Code Review

This pull request introduces support for Git 2.54+ config-based hooks and global hook installation. It adds --global and --legacy flags to hk install and hk uninstall, along with a hidden --from-hook flag for graceful exits in repositories without hk configuration. Feedback was provided to improve the robustness of the installation process by validating configuration before performing cleanup and using a more specific signature when identifying existing shims for removal.

[gemini-code-assist]

Performing cleanup of existing hooks before validating the configuration can leave the repository in an inconsistent state (without any hooks) if Config::get() fails due to a syntax error in hk.pkl. It is safer to verify the configuration and determine the events to be installed before removing the current installation.

Suggested change

	// Clean up any prior installation so modes don't accumulate.
	remove_local_shims()?;
	remove_local_config_entries()?;
	let config = Config::get()?;
	let events: Vec<String> = config
	.hooks
	.keys()
	.filter(|h| h.as_str() != "check" && h.as_str() != "fix")
	.cloned()
	.collect();
	if use_config_hooks {
	install_local_config(&events, command)
	} else {
	"hk".to_string()
	install_local_shims(&events, command)
	}
	let config = Config::get()?;
	let events: Vec<String> = config
	.hooks
	.keys()
	.filter(|h| h.as_str() != "check" && h.as_str() != "fix")
	.cloned()
	.collect();
	// Clean up any prior installation so modes don't accumulate.
	remove_local_shims()?;
	remove_local_config_entries()?;
	if use_config_hooks {
	install_local_config(&events, command)
	} else {
	install_local_shims(&events, command)
	}

[gemini-code-assist]

The check content.contains("hk run") is quite broad and could lead to the accidental deletion of user-defined hooks that happen to contain this string (e.g., in a comment or as part of a different command). Using a more specific signature that matches the hk shim template would be safer.

Suggested change

	if content.contains("hk run") {
	if content.contains("test \"${HK:-1}\" = \"0\" || exec") {

[greptile-apps]

Greptile Summary

This PR adds Git 2.54+ config-based hook installation (hook.<name>.command / .event in .git/config or ~/.gitconfig) as the new default, with --legacy to fall back to script shims, and --global to write to ~/.gitconfig so every repo picks up hooks without a per-repo install. Uninstall is updated to clean both modes, --from-hook adds silent no-op semantics for repos without hk.pkl, and docs are updated with accurate double-execution semantics for the global+local combo.

All previously raised P1 concerns are resolved: the HK=0 escape hatch is present in write_config_hook (line 187) and the manual ~/.gitconfig example; the docs now correctly document that global and local config-based entries accumulate rather than replacing each other.

Confidence Score: 5/5

Safe to merge — all previously raised P1 concerns are resolved, implementation is correct, and the new behavior is well-guarded.

No P0 or P1 issues remain. The HK=0 escape hatch is present in both write_config_hook and the manual docs example. The double-execution semantics are accurately documented. The --from-hook two-level guard correctly short-circuits before config load and before hook dispatch. Exit code handling in remove_config_entries correctly distinguishes 'no matches' (code 1) from real errors (code ≥2). The only gap is no automated test for the Git 2.54+ config-based default path, but the PR includes thorough manual smoke tests.

test/install_creates_git_hooks.bats and the other bats test files — all pinned to --legacy, so the new config-based default path has no automated coverage.

Important Files Changed

Filename	Overview
src/cli/install.rs	Core of the PR: adds config-based hook install/uninstall helpers, --global and --legacy flags, HK=0 guard in write_config_hook, and warn_if_global_overlap. Logic is correct and well-structured.
src/hook_options.rs	Adds --from-hook flag; short-circuits before config load when no hk.pkl exists, and skips silently when a hook event isn't defined. Two-level guard correctly handles both cases.
src/git_util.rs	Adds git_version() (process-lifetime cached via OnceLock) and git_at_least(). Parsing handles platform suffixes like .windows.N correctly by stripping non-digit chars before parsing.
src/config.rs	Refactors project config search into project_config_search_paths + find_project_config helpers, and adds project_config_exists() for the --from-hook short-circuit. Clean decomposition with no behavioral change to the happy path.
src/cli/uninstall.rs	Now removes both legacy shims and config-based entries in one pass; adds --global flag delegating to remove_config_entries('--global').
docs/getting_started.md	New 'Install Hooks Globally (Git 2.54+)' section accurately documents double-execution semantics for global+local combos, HK=0 escape hatch, and the hook.hk-.enabled = false per-repo override.
test/install_creates_git_hooks.bats	Updated to use --legacy. No automated test covers the new default config-based path; all tests pin to shim mode.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[hk install] --> B{--global?}
    B -- yes --> C{git >= 2.54?}
    C -- no --> D[bail! upgrade hint]
    C -- yes --> E[remove_config_entries --global]
    E --> F[write_config_hook --global\nfor each DEFAULT_GLOBAL_EVENT]
    F --> G[print success]
    B -- no --> H[use_config_hooks =\n!legacy && git>=2.54]
    H --> I[Config::get - load hk.pkl]
    I --> J[remove_local_shims\n+ remove_local_config_entries]
    J --> K{events empty?}
    K -- yes --> L[warn & return]
    K -- no --> M{use_config_hooks?}
    M -- yes --> N[write_config_hook --local\nfor each event]
    N --> O[warn_if_global_overlap]
    M -- no --> P[write script shim\nto .git/hooks/]
    subgraph runtime [Runtime: hk run EVENT --from-hook]
        R[Config::project_config_exists?] -- no --> S[exit 0 silently]
        R -- yes --> T[Config::get]
        T --> U{hook defined?}
        U -- no --> V[exit 0 silently]
        U -- yes --> W[run hook steps]
    end

Loading

_{Reviews (6): Last reviewed commit: "fix(install): warn on global/local hook ..." | Re-trigger Greptile}

[tmeijn]

@jdx just to make you aware: ~/.config/git/config is also a valid global location and actually the one I'm using:

❯ git config list --show-origin --show-scope 
global  file:/home/tmeijn/.config/git/config    alias.b=branch
global  file:/home/tmeijn/.config/git/config    alias.bt=branch -v --sort=-committerdate

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a5138db. Configure here.}

[cursor]

Hardcoded ~/.gitconfig path ignores XDG config location

Low Severity

The install_global output message and uninstall --global info message hardcode ~/.gitconfig, but git config --global may write to ~/.config/git/config (XDG location) depending on user setup. The actual config write is correct (delegated to git), but the user-facing messages point to the wrong file, which is confusing when trying to verify or hand-edit the result.

Additional Locations (1)

• src/cli/uninstall.rs#L14-L15

 

^{Reviewed by Cursor Bugbot for commit a5138db. Configure here.}

[cursor]

Global overlap warning fires even after failed install

Low Severity

warn_if_global_overlap is called unconditionally after install_local_config, even when the install returned an error. This means a failed install still emits a warning about global/local overlap (spawning multiple git config subprocesses), then propagates the original error — producing confusing output.

 

^{Reviewed by Cursor Bugbot for commit a5138db. Configure here.}