`but setup` displaces hooks owned by hook managers (prek, pre-commit, husky) without detecting them, and provides no escape hatch

[ichoosetoaccept]

Version

0.19.5

Operating System

macOS

Distribution Method

dmg (Mac OS - Apple Silicon)

Describe the issue

Summary

but setup unconditionally overwrites pre-commit and post-checkout hooks without checking whether a hook manager (prek, pre-commit, husky, lefthook, etc.) already owns them. It renames existing hooks with a -user suffix and installs GITBUTLER_MANAGED_HOOK_V1 wrappers in their place. While but setup does print a note that it is "Installing Git hooks", it does not name the affected files, does not warn that existing hooks will be displaced, and does not detect pre-existing hook managers.

The resulting state is fragile in several distinct ways.

Failure modes

1. Insufficient warning on but setup

but setup does print a note:

Installing Git hooks to help manage commits on the workspace branch

However it does not:

• Name which hook files will be affected (pre-commit, post-checkout)
• Mention that existing hooks will be renamed to a -user suffix
• Detect whether a hook manager (prek, pre-commit, husky) is already installed and owns those files
• Offer a way to skip hook installation (--no-hooks) for projects that manage hooks independently

A developer running but setup in a project where prek already owns pre-commit gets no indication that their hook runner has just been demoted to pre-commit-user and wrapped by a GitButler shim.

2. Inconsistent coverage — pre-push is left untouched

GitButler wraps pre-commit and post-checkout, but ignores pre-push entirely. This means pre-push hooks continue running through the hook manager's full pipeline (including stash-before-hooks). When combined with a stale gitbutler/workspace HEAD commit, this causes linters to run against stale file content — see the stale-workspace-HEAD issue filed separately (#12750).

3. prek install after but setup silently breaks workspace guard

Running prek install a second time (e.g., after git clone on a new machine following the project's README) produces:

Hook already exists at `.git/hooks/pre-commit`, moved it to `.git/hooks/pre-commit.legacy`
Migration mode: prek will also run legacy hook `.git/hooks/pre-commit.legacy`
prek installed at `.git/hooks/pre-commit`

Result:

pre-commit         → fresh prek runner
pre-commit.legacy  → GitButler wrapper  ← prek calls this in migration mode, which calls...
pre-commit-user    → old prek runner    ← ...this orphaned duplicate: prek runs TWICE
post-checkout      → fresh prek runner  ← GitButler cleanup logic GONE
post-checkout-user → prek runner (orphaned)

In prek's default migration mode, the GitButler workspace guard still runs (via .legacy), but prek is invoked twice — once directly, once via the wrapper calling pre-commit-user. Running prek install --overwrite removes .legacy entirely, at which point the workspace guard is silently gone with no error or warning.

4. No escape hatch

There is no but setup --no-hooks flag, no config option to disable hook management, and no way to tell GitButler "I already manage hooks through prek — provide your logic as a hook I can call."

Environment

• GitButler CLI: but (latest)
• OS: macOS 15 / macOS 26 beta
• Hook manager tested: prek v0.3+ (pre-commit compatible)
• Also affects: pre-commit (uses .git/hooks/), Husky (both .git/hooks/ for v4 and .husky/ for v5+ — same displacement pattern regardless of core.hooksPath)

How to reproduce (Optional)

Reproduction

With prek (hooks in .git/hooks/)

# Fresh repo with prek already managing hooks
git init /tmp/hook-test
git commit --allow-empty -m "init"
cat > /tmp/hook-test/prek.toml << 'EOF'
minimum_prek_version = "0.3.3"
default_install_hook_types = ["pre-commit", "pre-push", "post-checkout"]
[[repos]]
repo = "builtin"
hooks = [{ id = "trailing-whitespace" }]
EOF
prek install -C /tmp/hook-test

Hooks before but setup:

.git/hooks/pre-commit    → prek runner
.git/hooks/pre-push      → prek runner
.git/hooks/post-checkout → prek runner

but setup   # run in /tmp/hook-test

Hooks after but setup:

.git/hooks/pre-commit         → GITBUTLER_MANAGED_HOOK_V1 wrapper  ← replaced, no file-level warning
.git/hooks/pre-commit-user    → prek runner (demoted, non-standard filename)
.git/hooks/pre-push           → prek runner                         ← untouched (inconsistent!)
.git/hooks/post-checkout      → GITBUTLER_MANAGED_HOOK_V1 wrapper  ← replaced, no file-level warning
.git/hooks/post-checkout-user → prek runner (demoted, non-standard filename)

With Husky (hooks in .husky/, core.hooksPath = .husky)

but setup is aware of core.hooksPath — when set to .husky, it correctly installs its wrappers into .husky/ rather than .git/hooks/. However, the same displacement pattern applies:

# Fresh repo with Husky-style hooks
git init /tmp/husky-test && git commit --allow-empty -m "init"
mkdir /tmp/husky-test/.husky
echo '#!/bin/sh\necho "husky: running pre-commit"' > /tmp/husky-test/.husky/pre-commit
chmod +x /tmp/husky-test/.husky/pre-commit
git -C /tmp/husky-test config core.hooksPath .husky
but setup   # run in /tmp/husky-test

Result — .husky/ after but setup:

.husky/pre-commit      → GITBUTLER_MANAGED_HOOK_V1 wrapper  ← original displaced
.husky/pre-commit-user → original Husky hook (50 bytes)
.husky/post-checkout   → GitButler post-checkout handler    ← injected
.git/hooks/            → empty (correctly unaffected)

The GitButler GUI setting "Enable Husky hooks" is orthogonal to this — it controls whether GitButler's internal hook execution calls .husky/ scripts, not how but setup behaves.

Expected behavior (Optional)

Expected behaviour

but setup should:

1. Detect existing hook managers before overwriting. If pre-commit, post-checkout, or pre-push are already owned by a recognised hook manager (prek, pre-commit, husky, etc.), print a warning and instructions rather than silently renaming.

2. Provide composable hook scripts — ship the workspace guard and post-checkout cleanup as standalone scripts (e.g., installed to .git/gitbutler/hooks/) that can be called from any hook manager config.

3. Support --no-hooks (or a config flag) to skip all hook installation for teams that manage hooks independently.

4. Handle pre-push consistently — either wrap it the same way as pre-commit/post-checkout, or don't wrap any hooks at all and rely on the composable scripts approach.

Suggested integration pattern

The correct integration for a prek-managed project looks like this (currently requires manual setup with no official guidance):

# prek.toml
[[repos]]
repo = "local"
hooks = [
    { id = "gitbutler-workspace-guard",
      name = "GitButler Workspace Guard",
      language = "system",
      entry = "nu .git/gitbutler/hooks/workspace-guard.nu",   # hypothetical
      pass_filenames = false,
      always_run = true,
      stages = ["pre-commit"] },
]

GitButler should ship these scripts and document this pattern as the recommended integration for projects using hook managers.

Relevant log output (Optional)

[spider-yamet]

May I work on this issue? Hope this project is open for contribution.
cc: @Byron @slarse

[ichoosetoaccept]

May I work on this issue? Hope this project is open for contribution. cc: @Byron @slarse

I believe you're free to, thanks for offering! Be sure to check contribution guidelines 🙂.

[ichoosetoaccept]

I should add that this issue is a blocker for me in regards to Gitbutler right now. I'm running but teardown in all projects where I adopted Gitbutler until this is resolved because I use prek extensively in all my projects and don't want to deal with Gitbutler messing up my carefully crafted git hook setup.

BTW, prek is my personal favorite of many git hook managers out there. I strongly assume that all of these are affected by this:

• Husky
• pre-commit
• Overcommit
• Lefthook
• hk

Even more info:

• awesome-git-hooks
• awesome-precommit

[Byron]

Thanks a lot for reporting!

I think the interactions with hook managers aren't quite sane yet, particularly with prek. Also I must add that many pre-commit hooks require the new commit tree to be present in the .git/index, which is something that GitButler might not always do.

There are many unknowns for me, but I tried to clear them up real quick with Codex (see below the line). In any case, help is certainly welcome.

---

but commit is not delegating to git commit. In the current CLI path it manually runs pre-commit, then commit-msg, creates the commit, then runs post-commit, all gated by --no-hooks / --no-verify (crates/but/src/command/legacy/commit.rs#L361-L522). It does not run prepare-commit-msg or the rest of Git’s usual client-side hook chain.

The interaction with but setup is:

• but setup switches to gitbutler/workspace and installs GitButler-managed pre-commit and post-checkout hook files, respecting core.hooksPath if it exists (setup.rs#L379-L394, managed_hooks.rs#L179-L300).
• The managed pre-commit wrapper first runs the displaced user hook as pre-commit-user, then blocks direct git commit on gitbutler/workspace with GITBUTLER_ERROR (managed_hooks.rs#L18-L61).
• but commit intentionally calls that same hook chain, but special-cases GITBUTLER_ERROR as success, so the user’s original pre-commit still runs and GitButler’s workspace guard does not block but commit (hooks.rs#L79-L115).
• but teardown removes/restores those managed hooks before checking out a normal branch, while the managed post-checkout hook also self-cleans if the user leaves the workspace branch manually (teardown.rs#L115-L148, managed_hooks.rs#L63-L136).

Hook lookup matters too. GitButler uses git2-hooks for pre-commit / commit-msg / post-commit, and that library gives core.hooksPath absolute precedence; if it is set, fallback search paths are not consulted (hooks.rs#L47-L60, git2-hooks/src/hookspath.rs#L23-L59). So the GitButler “Enable Husky hooks” setting is orthogonal to but setup: it only affects GitButler’s internal fallback search for .husky when core.hooksPath is not set.

My estimate for prek and Husky:

• If prek or Husky is already installed before but setup, but commit will usually still run the displaced pre-commit through GitButler’s wrapper. So this is not mainly a “hooks never run” problem.
• The real problem is ownership. but setup renames pre-commit and post-checkout to *-user and takes over the canonical filenames. That collides with how hook managers such as prek and husky expect to own those entrypoints.
• That makes reinstall flows fragile. The prek double-run / lost-guard scenario described in issue #12748 and the linked comment is a credible consequence of GitButler’s rename scheme plus prek’s install model.
• Husky is affected differently but for the same structural reason: GitButler respects core.hooksPath, so if Husky owns that path, GitButler installs its wrappers there and displaces Husky’s files in-place rather than bypassing them.
• There is also a behavioral mismatch: but commit runs pre-commit against a synthetic index built from the selected DiffSpecs, then resets that index and creates the commit from GitButler’s own selection model (repo.rs#L89-L106, hooks.rs#L79-L93, commit.rs#L431-L458). So validate-only hooks should mostly work, but auto-fix-and-restage flows may not behave like native git commit.

Net: but commit is designed to compose with GitButler’s own managed pre-commit wrapper, but but setup still takes over hook entrypoints that third-party managers consider theirs. So the main risk for prek / Husky is not total hook loss; it is fragile ownership, possible duplicate execution after reinstall, possible loss of the GitButler workspace guard, and non-native behavior for auto-fixing hooks.