docs(git-hooks): document CaptainHook + git-worktree workaround#31
Merged
Conversation
`captainhook/hook-installer` fails in secondary git worktrees because `.git` is a pointer file, not a directory. This adds a Troubleshooting section to `references/git-hooks-setup.md` covering the symptom, cause, and two known fixes (`composer install --no-plugins` preferred; pre-creating the hooks dir as fallback). Also: - Extend the skill description with "git hooks" and "worktrees" triggers so the skill activates on hook-install failures in worktree-based repos. - Add checkpoint GW-14a: info-level reminder for projects that depend on `captainhook/hook-installer` to document the worktree workaround in their README. Context: encountered repeatedly during t3x-nr-vault release work, where every `composer install` in a feature-branch worktree tripped the same error. Canonical workaround lives in `netresearch/typo3-ci-workflows` README, but the skill's own hook docs never mentioned it. Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
|
Warning You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again! |
Contributor
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
There was a problem hiding this comment.
Pull request overview
Adds documentation and skill metadata to better support git hook frameworks—specifically documenting and detecting the CaptainHook failure mode in secondary git worktrees—so agents/users can diagnose and apply the known workaround.
Changes:
- Added a Troubleshooting section to the git hooks setup reference covering CaptainHook + git worktrees.
- Expanded skill trigger/description keywords to include common hook frameworks and worktree hook-install failures.
- Added a new checkpoint to detect
captainhook/hook-installerincomposer.jsonand prompt documenting the workaround.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| skills/git-workflow/references/git-hooks-setup.md | Documents CaptainHook worktree install failure and workarounds in a new Troubleshooting section. |
| skills/git-workflow/checkpoints.yaml | Adds checkpoint GW-14a to detect captainhook installer usage and remind to document the worktree workaround. |
| skills/git-workflow/SKILL.md | Updates skill description to better match hook-framework and worktree troubleshooting queries. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
yamllint fails on lines > 160 chars. The GW-14a checkpoint description exceeded that after a single-line JSON-style 'desc:'. Switch to block scalar (>-) so the long guidance line can wrap without yamllint noise and without changing the rendered string. Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
- Lead with hooks-dir workaround using git rev-parse --git-path hooks which honors core.hooksPath if configured (no branching needed). - Demote composer install --no-plugins to last-resort fallback and spell out the side effects (phpstan/extension-installer, TYPO3 composer installers, captainhook itself won't register). - Drop reference to user's private global CLAUDE.md; link to git-worktree(1) upstream docs instead. Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
captainhook/hook-installerfails in secondary git worktrees because.gitis a pointer file (gitdir: /path/to/bare/worktrees/NAME), not a directory. The resolver in captainhook ≤ 1.x chokes on the pointer and abortscomposer install:The
netresearch/typo3-ci-workflowsmeta-package README already documents this, but thegit-workflowskill's ownreferences/git-hooks-setup.md— which explicitly lists captainhook as a supported framework — never mentioned the failure mode. This PR closes that gap.Changes
references/git-hooks-setup.md: NewTroubleshootingsection with aCaptainHook + git worktrees (FAQ)entry covering symptom, cause, recommended fix (composer install --no-plugins), alternative fix (pre-create hooks dir viagit rev-parse --git-dir), and cross-reference to the canonical workaround innetresearch/typo3-ci-workflows.SKILL.md: Extended the skill description withgit hooksframework keywords (lefthook, captainhook, husky, pre-commit) and a "hook-install failures in git worktrees" trigger phrase so the skill actually activates on this class of problem.checkpoints.yaml: NewGW-14a(info-level) — detectscaptainhook/hook-installerincomposer.jsonand reminds projects to document the worktree workaround in their README.Real-world context
Encountered repeatedly during t3x-nr-vault release work. The Netresearch bare-repo + worktrees convention (documented in the user's global
CLAUDE.mdunder "Git Worktree Convention") means everycomposer installin a feature-branch worktree hit this error. The fix was already known; it just wasn't where an agent reading the git-workflow skill would find it.Test plan
references/git-hooks-setup.mdrenders with new Troubleshooting section; bullets and backticks balancedSKILL.mdfrontmatter still valid YAML after description extensioncheckpoints.yamlparses —GW-14afollows samecontainspattern as GW-02/GW-03\n(no trailing blank lines → yamllintempty-linesclean)