Generated hooks fail during `git worktree add` — vendor/bin/captainhook not found

[delolmo]

Description

The hook scripts generated by CaptainHook unconditionally call vendor/bin/captainhook without checking that the binary exists. This causes git worktree add to fail, because the post-checkout hook fires in the new worktree before composer install has been run.

Steps to reproduce

1. Have a project with CaptainHook installed and hooks active (including post-checkout)
2. Run git worktree add /tmp/my-worktree HEAD

Expected behavior

The worktree is created successfully. The hook either skips execution or exits gracefully when vendor/bin/captainhook is not available.

Actual behavior

The hook fails with:

Preparing worktree (new branch 'worktree-xxx')
.git/hooks/post-checkout: 17: vendor/bin/captainhook: not found

The worktree creation is aborted.

Root cause

The generated hook template calls vendor/bin/captainhook unconditionally:

vendor/bin/captainhook $INTERACTIVE --configuration=captainhook.json --input="$input" hook:post-checkout "$@"

In a fresh worktree, vendor/ does not exist yet — composer install has not run.

Suggested fix

Guard the invocation with an existence check:

[ -x vendor/bin/captainhook ] && vendor/bin/captainhook $INTERACTIVE --configuration=captainhook.json --input="$input" hook:post-checkout "$@"

This affects all generated hooks, not just post-checkout, since any hook could theoretically fire in a context where vendor/ is absent (e.g., sparse checkouts, CI environments that install hooks before dependencies).

Environment

• CaptainHook 5.25.11
• Git 2.49.0
• PHP 8.5.0

[sebastianfeldmann]

Adding something like this is easy for local execution

if [ ! -x ' . $this->getExecutable() . ' ]; then
    echo "CaptainHook executable not found"
    exit 0
fi

In the Docker variant this is getting a bit harder to solve :/
The only path that needs to be configured is the path to CaptainHook from inside the container.
I can't use that to find the binary on the host system.

I will think about it a bit more but releasing the fix for the local version makes sense.

[sebastianfeldmann]

Let's say

• you write a git hook
• you execute a command in the hook script
• the command is not available

So your hook is broken.
Do you want the hook to fail or do you want your hook silently to succeed?

I'm actually not sure, but my first instinct is that I want it to fail.

[sebastianfeldmann]

A quick fix would be to run

CAPTAINHOOK_SKIP_HOOKS=1 git worktree add ...

For bigger rebases it also makes sense to call it like

CAPTAINHOOK_SKIP_HOOKS=1 git rebase main

But then skipping the hooks is an explicit decision, because you know that something bad will happen if you do not skip the hooks.

[delolmo]

Thanks for the quick response and the planned fix for local execution.

Regarding your question, I think the distinction is between not yet installed and genuinely broken:

• Not yet installed: git worktree add creates a new working tree that shares .git/hooks with the main worktree, but has no vendor/ yet. The binary will exist after composer install. Failing here blocks a legitimate Git operation for no reason.
• Genuinely broken: someone deleted vendor/bin/captainhook or misconfigured the path. Failing loudly makes sense here.

Both cases look the same from the hook's perspective (-x fails), so I understand the tension. But I'd argue that silently skipping is the safer default. A missing binary means the hook cannot do its job regardless, and failing doesn't fix anything; it just blocks the Git operation. The actual protection (pre-commit checks, etc.) will kick in once the environment is set up.

CAPTAINHOOK_SKIP_HOOKS=1 works as a workaround, but it requires knowing in advance that hooks will break, which is the kind of thing that trips up every new contributor on the project until someone documents it.