From f302b319497ccb8e7c9a3e251aa958a5b99172ea Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 18 Jul 2026 08:42:35 +0000 Subject: [PATCH 1/5] docs: add Troubleshooting section and broaden Coexisting warning to core.hooksPath Add a diagnostic checklist for when personal files fail to auto-link (init.templateDir set, no repo-local core.hooksPath shadowing .git/hooks, pre-ghostq clones need one ghostq apply, and reading ghostq status). Extend the Coexisting WARNING to cover hook managers that set a repo-local core.hooksPath (husky), a distinct mechanism from the post-checkout slot case that also blocks the seeded hook for clones and worktrees. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01EP3kitkunRnKiTed35oKgT --- README.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/README.md b/README.md index a9b980e..6f388ab 100644 --- a/README.md +++ b/README.md @@ -111,6 +111,50 @@ coexist with no caveat. > `lefthook.yml`), it takes that slot and ghostq won't auto-link **new > worktrees** of that repo — run `ghostq apply` in the new worktree by hand. > Clones, and every other hook, are unaffected. +> +> A second, separate failure mode: some hook managers set a repo-local +> `core.hooksPath` (husky does this). Since git honours only one hooks +> directory, that changes which hooks git runs and can keep ghostq's seeded +> `.git/hooks` hook from firing for that repo — for **clones and worktrees +> both**, not just new worktrees. Check with `git config --local --get +> core.hooksPath`; unset it (or reconfigure/migrate off that hook manager) to +> restore ghostq. lefthook writes into `.git/hooks` directly and sets no +> `core.hooksPath`, so it isn't affected; other (or newer) managers may differ, +> so check the config. + +## 🩺 Troubleshooting + +Personal files not auto-linking on a fresh `git clone` or `git worktree add`? +Work through these in order — each is a common reason the hook never seeds or +never fires. + +1. **Is ghostq installed?** `git config --get init.templateDir` should print + ghostq's template dir (path ending in `ghostq/template`). Empty, or pointing + somewhere else, means `ghostq install` never ran (or something overwrote the + setting) — run `ghostq install` and clone/`worktree add` again. + +2. **Is a repo-local `core.hooksPath` shadowing the seeded hook?** + `git config --local --get core.hooksPath` should print **nothing**. If it + prints a path, git reads hooks from there instead of `.git/hooks` — where + ghostq seeds its `post-checkout` — so ghostq's hook never fires. Some hook + managers set this (husky does). Unset it + (`git config --local --unset core.hooksPath`) or reconfigure that hook + manager, then run `ghostq apply` once. See the + [Coexisting](#-coexisting-with-lefthook-and-other-hook-managers) WARNING for + the full picture. + +3. **Did you clone the repo before installing ghostq?** git templates apply + only at clone/init time and are never retroactive, so a checkout that + predates `ghostq install` has no seeded hook. Run `ghostq apply` in it once + to link the overlay by hand; future clones and worktrees are covered. + +4. **Ask ghostq what it sees.** `ghostq status` prints the resolved repo + identity, the overlay entry path, and each managed file's link state, + changing nothing. Use it to confirm the repo maps to the overlay entry you + expect and to spot files that were skipped (e.g. not gitignored) or left + alone (a real file where a link would go). A repo with no matching remote + identity — no `origin`, or no overlay entry for its `host/user/repo` — is + skipped quietly, so that shows up here too. ## 🛡️ Safety From 30aa521f45bc4707be112779bdcfb61c9883309d Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 18 Jul 2026 08:53:06 +0000 Subject: [PATCH 2/5] docs: generalize core.hooksPath note instead of naming lefthook Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01EP3kitkunRnKiTed35oKgT --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 6f388ab..96de40b 100644 --- a/README.md +++ b/README.md @@ -118,9 +118,9 @@ coexist with no caveat. > `.git/hooks` hook from firing for that repo — for **clones and worktrees > both**, not just new worktrees. Check with `git config --local --get > core.hooksPath`; unset it (or reconfigure/migrate off that hook manager) to -> restore ghostq. lefthook writes into `.git/hooks` directly and sets no -> `core.hooksPath`, so it isn't affected; other (or newer) managers may differ, -> so check the config. +> restore ghostq. Not every manager does this — some write into `.git/hooks` +> directly and set no `core.hooksPath` — so check the config for whichever one +> you use. ## 🩺 Troubleshooting From 05760b27f1fff72a709fa60c1605bff335bcee19 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 18 Jul 2026 08:55:01 +0000 Subject: [PATCH 3/5] docs: generalize Coexisting heading, drop lefthook name Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01EP3kitkunRnKiTed35oKgT --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 96de40b..0734d2b 100644 --- a/README.md +++ b/README.md @@ -98,7 +98,7 @@ How the hook itself is wired (`init.templateDir`, the null-ref gate, migration from older versions) is an implementation detail — see [DEVELOPMENT.md](./DEVELOPMENT.md). -## 🤝 Coexisting with lefthook (and other hook managers) +## 🤝 Coexisting with hook managers ghostq doesn't take over your hooks. Install lefthook, husky, pre-commit, or your own `.git/hooks` scripts exactly as you normally would — there's nothing @@ -140,7 +140,7 @@ never fires. managers set this (husky does). Unset it (`git config --local --unset core.hooksPath`) or reconfigure that hook manager, then run `ghostq apply` once. See the - [Coexisting](#-coexisting-with-lefthook-and-other-hook-managers) WARNING for + [Coexisting](#-coexisting-with-hook-managers) WARNING for the full picture. 3. **Did you clone the repo before installing ghostq?** git templates apply From 211e67914438fe442585df42589e6f7ab547ad0a Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 18 Jul 2026 09:15:02 +0000 Subject: [PATCH 4/5] docs: tighten Troubleshooting and Coexisting wording Remove the duplicated core.hooksPath mechanism explanation between the Coexisting WARNING and Troubleshooting, keeping the commands and a one-line rationale in each. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01EP3kitkunRnKiTed35oKgT --- README.md | 40 +++++++++++++++------------------------- 1 file changed, 15 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 0734d2b..63b0fac 100644 --- a/README.md +++ b/README.md @@ -112,15 +112,11 @@ coexist with no caveat. > worktrees** of that repo — run `ghostq apply` in the new worktree by hand. > Clones, and every other hook, are unaffected. > -> A second, separate failure mode: some hook managers set a repo-local -> `core.hooksPath` (husky does this). Since git honours only one hooks -> directory, that changes which hooks git runs and can keep ghostq's seeded -> `.git/hooks` hook from firing for that repo — for **clones and worktrees -> both**, not just new worktrees. Check with `git config --local --get -> core.hooksPath`; unset it (or reconfigure/migrate off that hook manager) to -> restore ghostq. Not every manager does this — some write into `.git/hooks` -> directly and set no `core.hooksPath` — so check the config for whichever one -> you use. +> A second, separate case: some managers set a repo-local `core.hooksPath` +> (husky does). git then reads hooks only from there, not `.git/hooks`, so +> ghostq's seeded hook never fires — for **clones and worktrees both**. Check +> with `git config --local --get core.hooksPath` and unset it to restore +> ghostq. ## 🩺 Troubleshooting @@ -133,28 +129,22 @@ never fires. somewhere else, means `ghostq install` never ran (or something overwrote the setting) — run `ghostq install` and clone/`worktree add` again. -2. **Is a repo-local `core.hooksPath` shadowing the seeded hook?** - `git config --local --get core.hooksPath` should print **nothing**. If it - prints a path, git reads hooks from there instead of `.git/hooks` — where - ghostq seeds its `post-checkout` — so ghostq's hook never fires. Some hook - managers set this (husky does). Unset it - (`git config --local --unset core.hooksPath`) or reconfigure that hook - manager, then run `ghostq apply` once. See the - [Coexisting](#-coexisting-with-hook-managers) WARNING for - the full picture. +2. **Is a repo-local `core.hooksPath` set?** `git config --local --get + core.hooksPath` should print nothing; a path there shadows `.git/hooks` + (where ghostq seeds its hook), so nothing fires. Some managers set it (husky + does) — unset it (`git config --local --unset core.hooksPath`) or reconfigure + that manager, then run `ghostq apply` once. 3. **Did you clone the repo before installing ghostq?** git templates apply only at clone/init time and are never retroactive, so a checkout that predates `ghostq install` has no seeded hook. Run `ghostq apply` in it once to link the overlay by hand; future clones and worktrees are covered. -4. **Ask ghostq what it sees.** `ghostq status` prints the resolved repo - identity, the overlay entry path, and each managed file's link state, - changing nothing. Use it to confirm the repo maps to the overlay entry you - expect and to spot files that were skipped (e.g. not gitignored) or left - alone (a real file where a link would go). A repo with no matching remote - identity — no `origin`, or no overlay entry for its `host/user/repo` — is - skipped quietly, so that shows up here too. +4. **Ask ghostq what it sees.** `ghostq status` prints the resolved identity, + the overlay entry path, and each file's link state, changing nothing — use + it to confirm the repo maps to the entry you expect and to spot skipped + files. A repo with no `origin` or no matching overlay entry is skipped + quietly, which shows up here too. ## 🛡️ Safety From 97b3207cdd013366306aed21f245a8845e381b9e Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 18 Jul 2026 09:17:20 +0000 Subject: [PATCH 5/5] docs: add hard line breaks to separate check from fix In the Coexisting WARNING and each Troubleshooting step, break the line between the diagnosis and the remedy so the action reads on its own line. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01EP3kitkunRnKiTed35oKgT --- README.md | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 63b0fac..e247560 100644 --- a/README.md +++ b/README.md @@ -109,13 +109,13 @@ coexist with no caveat. > `git worktree add` runs a single shared `.git/hooks/post-checkout`. If your > own hook config *also* uses `post-checkout` (e.g. a `post-checkout:` block in > `lefthook.yml`), it takes that slot and ghostq won't auto-link **new -> worktrees** of that repo — run `ghostq apply` in the new worktree by hand. +> worktrees** of that repo — run `ghostq apply` in the new worktree by hand. > Clones, and every other hook, are unaffected. > > A second, separate case: some managers set a repo-local `core.hooksPath` > (husky does). git then reads hooks only from there, not `.git/hooks`, so -> ghostq's seeded hook never fires — for **clones and worktrees both**. Check -> with `git config --local --get core.hooksPath` and unset it to restore +> ghostq's seeded hook never fires — for **clones and worktrees both**. +> Check with `git config --local --get core.hooksPath` and unset it to restore > ghostq. ## 🩺 Troubleshooting @@ -125,26 +125,29 @@ Work through these in order — each is a common reason the hook never seeds or never fires. 1. **Is ghostq installed?** `git config --get init.templateDir` should print - ghostq's template dir (path ending in `ghostq/template`). Empty, or pointing - somewhere else, means `ghostq install` never ran (or something overwrote the - setting) — run `ghostq install` and clone/`worktree add` again. + ghostq's template dir (path ending in `ghostq/template`). + Empty, or pointing somewhere else, means `ghostq install` never ran (or + something overwrote the setting) — run `ghostq install` and clone/`worktree + add` again. 2. **Is a repo-local `core.hooksPath` set?** `git config --local --get core.hooksPath` should print nothing; a path there shadows `.git/hooks` - (where ghostq seeds its hook), so nothing fires. Some managers set it (husky - does) — unset it (`git config --local --unset core.hooksPath`) or reconfigure - that manager, then run `ghostq apply` once. + (where ghostq seeds its hook), so nothing fires. + Some managers set it (husky does) — unset it (`git config --local --unset + core.hooksPath`) or reconfigure that manager, then run `ghostq apply` once. 3. **Did you clone the repo before installing ghostq?** git templates apply only at clone/init time and are never retroactive, so a checkout that - predates `ghostq install` has no seeded hook. Run `ghostq apply` in it once - to link the overlay by hand; future clones and worktrees are covered. + predates `ghostq install` has no seeded hook. + Run `ghostq apply` in it once to link the overlay by hand; future clones and + worktrees are covered. 4. **Ask ghostq what it sees.** `ghostq status` prints the resolved identity, the overlay entry path, and each file's link state, changing nothing — use it to confirm the repo maps to the entry you expect and to spot skipped - files. A repo with no `origin` or no matching overlay entry is skipped - quietly, which shows up here too. + files. + A repo with no `origin` or no matching overlay entry is skipped quietly, + which shows up here too. ## 🛡️ Safety