feat: hook ownership model with external manager detection

[ichoosetoaccept]

Closes gitbutlerapp#12748

Summary

Adds a hook ownership model so GitButler can coexist with external hook managers (now: prek, later: pre-commit, lefthook, husky, etc.) instead of unconditionally overwriting their hooks.

This PR ships the plumbing + but CLI milestone described in gitbutlerapp#12748 (comment). It does not include but doctor, Desktop UI integration, or onboarding changes — those are separate follow-ups.

After a recent rebase onto upstream master, the PR was restructured so hook lifecycle commands are universal rather than legacy-only — modern (non-legacy) builds can now install and uninstall managed hooks too. Output styling was migrated to upstream's new theme::get() paint tokens. See "Restructure" below.

What changed

New but-hooks crate

All hook detection and management logic moved into a dedicated but-hooks crate, following the gitbutler- → but- migration. Existing consumers in gitbutler-repo continue working via re-exports.

• Hook manager detection — content-based signature matching (inspects hook file contents) with a config+binary fallback for managers that are configured but haven't installed hooks yet. Currently supports prek; adding new managers requires a single enum variant + match arms for owns_hook, has_config, is_available, and integration_instructions.
• Managed hook installation — installs GitButler's guard hooks with ownership checks. Non-GitButler hooks are preserved (not overwritten) unless --force-hooks is used, in which case the original is backed up to <hook>-user.
• Project-local binary detection — checks .venv/bin/ and node_modules/.bin/ in addition to system PATH, so project-local hook manager installations are detected.

Universal but hook subcommands

Composable CLI entry points that work in both legacy and modern builds — external hook managers, scripts, and modern-mode users can all invoke them:

• but hook install [--force] — install GitButler-managed hooks. Detects external managers and refuses to clobber them; --force overrides detection and re-enables gitbutler.installHooks=true. Universal: works without legacy crates.
• but hook uninstall — best-effort cleanup, signature-checks each hook so user/external hooks are never touched. Restores any pre-existing hook from <hook>-user. Universal.
• but hook pre-commit — blocks git commit on gitbutler/workspace with a helpful error directing the user to but commit.
• but hook post-checkout — prints an informational message when leaving the workspace branch.
• but hook pre-push — blocks git push on gitbutler/workspace with a helpful error directing the user to but push.
• but hook status — diagnostic showing hook mode (managed/external/disabled/unconfigured), per-hook ownership, orphaned hook detection, and context-aware recommendations. Supports human, shell, and JSON output.

All emit structured JSON via --format json (or --json).

Updated lifecycle commands (legacy-only)

but setup and but teardown remain legacy-gated (the commands themselves are #[cfg(feature = "legacy")]), but their hook handling shrinks to thin adapters that delegate to but hook install / but hook uninstall:

• but setup — translates --no-hooks (persist installHooks=false and call uninstall) and --force-hooks (translate to --force). Embeds the install report into its existing SetupResult JSON without duplicating output.
• but teardown — calls uninstall and surfaces the "externally managed" hint when prek (or similar) is detected in the hooks directory.

Restructure (post-rebase)

After this branch was rebased onto a fresh upstream master, two upstream landings prompted a restructure to keep the PR aligned with current direction:

• Theming: upstream introduced a theme::get() API with semantic tokens (success, attention, info, hint, command_suggestion, error). All ~40 colored::Colorize call sites in our changes (command/hook.rs, legacy/setup.rs, legacy/teardown.rs) now use the new API. colored::Colorize is dropped from those files.
• Modern builds: install/uninstall logic was lifted out of legacy/setup.rs (244 lines) and legacy/teardown.rs (~75 lines) into universal command::hook::install/uninstall functions. The legacy adapters are now ~25 / ~5 lines that delegate. As a side effect, modern (non-legacy) builds gain but hook install/uninstall for free.

Desktop backend (gitbutler-branch-actions)

Updated the existing update_workspace_commit call site to use ensure_managed_hooks() instead of the old install_managed_hooks_gix(). This is a backend-only change — no UI, no Tauri, no onboarding — ensuring the Desktop app's workspace migration path also respects external hook managers rather than overwriting them. Added a test confirming hooks are not installed when the config opt-out is active.

Automated tests

125 non-ignored tests across but-hooks, but, and gitbutler-branch-actions, organized in five layers:

• Unit tests (~20) — hook manager detection algorithms (content signatures, config+binary fallback, project-local binary paths in .venv/bin/ and node_modules/.bin/), configuration persistence, backup status formatting.
• Integration tests (~35) — filesystem operations with temp dirs: hook installation, uninstallation, backup/restore roundtrips, staleness detection, force-install overwrites, partial success with warnings, idempotency.
• Shell script execution tests (8) — actually run the installed hook scripts in real git repos: workspace branch guards block git commit, post-checkout cleanup fires when leaving workspace, user hook delegation works on non-workspace branches.
• CLI snapshot tests (~53) — snapbox-based output validation for but setup, but teardown, but hook status, plus the new but hook install / but hook uninstall direct-subcommand tests (tests/but/command/hook_install.rs, hook_uninstall.rs). Covers all flag combinations (--no-hooks, --force-hooks, --force, --json) and ownership modes (managed, external, disabled, unconfigured). The new direct-subcommand tests pass in both default (legacy) and --no-default-features (modern) builds.
• End-to-end prek integration tests (9, #[ignore]-gated) — real prek binary scenarios; require prek on PATH, run with cargo test -p but -- --ignored hook_prek.

Testing patterns: temp dir isolation for every test, environment variable mocking for binary availability (test-overrides feature flag), #[cfg(unix)] guards for permission-specific tests.

Manual testing

In addition to the automated suite above, I manually tested each user-facing scenario end-to-end. I built a release binary (cargo build --release -p but) and ran each scenario against a clean disposable git repo with a local bare remote. I captured screenshots by piping command output through cleen — a tool that renders ANSI terminal output to a PNG — using a pseudo-TTY wrapper (script -q /dev/null) so the binary emits colors through the pipe. The capture script is a local test artifact and is not included in the PR. All on macOS. Twelve scenarios covered:

Happy path

1. but setup on a clean repo — hooks installed

I ran but setup on a fresh repo. It switches to gitbutler/workspace and confirms each hook is in place — one line per hook. Verified that the installed hooks block git commit on the workspace branch with a GITBUTLER_ERROR as expected (pre-existing behavior, not screenshotted).

2. but hook status — verify hooks are in place

After setup, I ran but hook status. It shows all three hooks listed as GitButler-managed with green checkmarks. Running with --json emits structured per-hook status including ownership and any warnings (not shown here).

3. but teardown — clean exit

I ran but teardown. It reports each removed hook individually before checking out the target branch. Only GitButler-managed hooks are removed — any hooks not owned by GitButler are left untouched. The managed post-checkout script also auto-removes hooks on a plain git checkout <branch> away from the workspace.

External manager coexistence

4. prek detected — setup defers to external manager

With prek.toml present and prek install already run, I ran but setup. It detects prek, leaves the hooks untouched, persists gitbutler.installHooks=false, and prints ready-to-paste integration instructions.

5. but hook status — external ownership shown

I then ran but hook status. It shows external manager mode with per-hook ownership — prek owns the slots it has installed, and slots prek hasn't wired up yet appear as ✗ not configured (prek) with actionable warnings + recommendations.

6. but teardown — prek hooks left untouched

I ran but teardown in the prek-managed repo. It left prek's hooks untouched and printed guidance about removing but hook entries from the prek config if you want to fully disable the workspace guards.

7. prek detected — config+binary fallback (before prek install)

With only prek.toml present and the binary on PATH (no hook files yet), I ran but setup. It still detects prek via the config+binary fallback and shows the same integration instructions.

Override behaviors and re-run

8. --no-hooks flag — persistent opt-out

I ran but setup --no-hooks. It skips hook installation, persists gitbutler.installHooks=false, and (post-rebase) itemizes which previously-installed managed hooks were cleaned up.

9. Re-run detection — config opt-out preserved

After opting out (scenario 8), I ran but setup again. It shows the config-preserved opt-out without re-scanning and hints at --force-hooks to re-enable.

10. --force-hooks — override external manager detection

In a repo where prek was previously detected (installHooks=false), I ran but setup --force-hooks. It skips detection entirely, backs prek's hooks up to <hook>-user, installs GitButler's managed hooks in their place, and reports each one with ✓ Installed pre-commit etc.

11. but teardown with user backup — hooks restored

Continuing from scenario 10, I ran but teardown. It reports each hook removal and shows Restored pre-commit (your original hook is back) for the hook that was backed up to pre-commit-user.

Edge case

12. Pre-existing plain user hook — partial install with actionable warning

I placed a plain pre-commit hook (not owned by any known manager) and ran but setup. It installs post-checkout and pre-push (each with ✓ Installed …) and skips pre-commit with a yellow warning including the --force-hooks override hint.

Architecture

but setup (legacy) / Desktop app                but hook install / uninstall (universal)
    │                                                │
    └─────────────────┬──────────────────────────────┘
                      ▼
           ensure_managed_hooks()           ← single entry point for all callers
              ├── skip if: installHooks=false  OR  external manager detected
              │                                     ├── signature match in hook files
              │                                     └── config+binary fallback (no files yet)
              └── install_managed_hooks() ← only when both guards pass
                      └── install_hook()  ← per-hook, with ownership check

External hook manager (prek, etc.)
    │
    ▼
but hook pre-commit / post-checkout / pre-push
    └── workspace branch check → block or allow

Notes

gix::discover_with_environment_overrides() in hook subcommands

Byron flagged in his initial review that bare gix::discover() is not the right call for hook subcommands — Git sets GIT_DIR / GIT_WORK_TREE before invoking hooks and gitoxide has gix::open_with_environment_overrides() for exactly this. We use gix::discover_with_environment_overrides() which satisfies both requirements: it honours the git-provided environment variables when present (so git commit invocations work correctly), and falls back to a directory walk when invoked directly by an external manager like prek without GIT_DIR set. agents.md says not to re-discover repositories inside commands; these subcommands are a documented exception since they run as standalone hook subprocesses with no Context.

Skill files updated

crates/but/skill/references/reference.md was updated with the new but hook subcommands and the --no-hooks/--force-hooks flags for but setup, per the agents.md convention.

Scope note

This PR is scoped to plumbing + CLI only, per the agreed plan in gitbutlerapp#12748:

In scope	Out of scope (follow-up)
but-hooks crate	but doctor / but-diagnose
Universal but hook install/uninstall/pre-commit/post-checkout/pre-push/status	Desktop UI / settings
but setup / but teardown (delegate to universal)	Onboarding flow
Backend call site update	Additional hook manager support

Note

Add external hook manager detection and ownership model to GitButler-managed hooks

• Introduces but-hooks crate with managed hook installation, backup, and uninstall logic; setup and teardown now report hook status including detection of external managers (e.g., prek) and support --no-hooks/--force-hooks flags
• Replaces DEFAULT_FORGE_FACTORY across the desktop app with new project-scoped services (FORGE_INFO_SERVICE, PR_SERVICE, LISTING_SERVICE, REPO_SERVICE, CHECKS_MONITOR), injected at bootstrap and consumed throughout forge UI components
• Migrates stack/branch queries from legacy stacks/stackDetails endpoints to workspaceDetails backed by head_info, propagating Segment-based data through BranchView, BranchList, StackView, and related components
• Adds but-server local-only hardening: removes tunnel/auth/remote features, restricts CORS to localhost, and exposes new forge and branch-integration IPC routes
• Introduces but-transaction crate providing a rebase-backed transactional context with oplog snapshot management for workspace mutations
• Risk: DEFAULT_FORGE_FACTORY and ForgePrService are removed from all call sites; downstream code that previously relied on DetailedPullRequest, stackDetails, push_stack_legacy, or unapply_stack must migrate to new APIs

^{Macroscope summarized ddc1156.}

[ichoosetoaccept]

This change is part of the following stack:

• feat: hook ownership model with external manager detection #1 ◀

_{Change managed by git-spice.}