From e77e5a0b4b4c3f6fa6c8aec239a00c90e8934541 Mon Sep 17 00:00:00 2001 From: Anilcan Cakir Date: Thu, 3 Sep 2026 19:28:02 +0300 Subject: [PATCH 1/3] chore(worktree): put worktrees under .claude and carry the overrides into them Worktrees used to sit beside the checkout as -, which put them in the workspace directory next to the real repositories and left EnterWorktree unusable, since that tool writes to a fixed .claude/worktrees/. Pattern proven on fluttersdk/magic_starter#124. --- .gitignore | 5 +++++ .worktreeinclude | 21 +++++++++++++++++++++ 2 files changed, 26 insertions(+) create mode 100644 .worktreeinclude diff --git a/.gitignore b/.gitignore index 82d6c5b..67bb0bb 100644 --- a/.gitignore +++ b/.gitignore @@ -43,3 +43,8 @@ pubspec_overrides.yaml .ac/ CLAUDE.local.md .sync-agents-cache.json + +# Worktrees Claude Code creates for parallel sessions and isolated subagents. +# Only this subdirectory: the rest of `.claude/` is tracked, because the rules +# under it are part of the repository. +.claude/worktrees/ diff --git a/.worktreeinclude b/.worktreeinclude new file mode 100644 index 0000000..1c9f3cf --- /dev/null +++ b/.worktreeinclude @@ -0,0 +1,21 @@ +# Gitignored files copied into every worktree Claude Code creates, for `--worktree`, +# for `EnterWorktree`, and for a subagent with `isolation: worktree`. +# +# A worktree is a fresh checkout, so `pubspec_overrides.yaml` is absent from it, and +# its absence fails silently rather than loudly: the siblings resolve from pub.dev +# instead of the working trees beside this one, `flutter pub get` succeeds, and the +# suite then passes against the PUBLISHED packages while the diff under review is of +# the local ones. An unreleased sibling API is where that bites. +# +# `.gitignore` syntax, and only files that match AND are gitignored are copied, so a +# tracked file can never be duplicated by this list. +# +# The paths inside `pubspec_overrides.yaml` have to be ABSOLUTE for this to work. +# Worktrees live under `.claude/worktrees/`, so a relative `../magic` resolves +# to `.claude/worktrees/magic`, which does not exist, and version solving fails on +# the first path dependency. +# +# NOT processed when a WorktreeCreate hook replaces the default git logic; such a +# hook has to copy these itself. + +pubspec_overrides.yaml From c7f64014a6f35450f16282a6cb78b7d05ca91032 Mon Sep 17 00:00:00 2001 From: Anilcan Cakir Date: Thu, 3 Sep 2026 20:01:25 +0300 Subject: [PATCH 2/3] docs(worktree): correct the .claude claim and record the git clean reach --- .gitignore | 8 ++++++-- CLAUDE.md | 4 ++++ 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 67bb0bb..b7d7f71 100644 --- a/.gitignore +++ b/.gitignore @@ -45,6 +45,10 @@ CLAUDE.local.md .sync-agents-cache.json # Worktrees Claude Code creates for parallel sessions and isolated subagents. -# Only this subdirectory: the rest of `.claude/` is tracked, because the rules -# under it are part of the repository. +# Only this subdirectory, so anything else that lands under `.claude/` stays visible +# to git. Nothing is tracked there today.# +# They sit inside the working tree rather than beside it, so `git clean -xdf` here +# wipes a live worktree's contents while `.git/worktrees/` survives, leaving a +# registration that needs `git worktree prune`. A worktree's `.git` is a file rather +# than a directory, so git's nested-repo guard does not stop it. .claude/worktrees/ diff --git a/CLAUDE.md b/CLAUDE.md index 1bb6c89..7ae0e61 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -44,6 +44,10 @@ directly is flagged as an unnecessary import. Local sibling development goes through the gitignored `pubspec_overrides.yaml`. The committed `pubspec.yaml` stays on hosted caret constraints so a fork outside this workspace resolves on its own. +That overrides file must use ABSOLUTE paths. `.worktreeinclude` copies it into worktrees under +`.claude/worktrees/`, where the conventional relative `../magic` resolves to +`.claude/worktrees/magic` and fails version solving on the first path dependency. + ## Barrels Four, and the split is the API: From 5e14ac0af444566e79b3aaa82f9bcc052ea14c44 Mon Sep 17 00:00:00 2001 From: Anilcan Cakir Date: Thu, 3 Sep 2026 20:30:52 +0300 Subject: [PATCH 3/3] fix(worktree): git clean -xdf skips a worktree, only -xdff does not The comment claimed plain -xdf wipes a live worktree because its .git is a file rather than a directory. Measured on a scratch repo: the dry run prints "Skipping repository .claude/worktrees/slug", the worktree survives -xdf with its untracked files intact, and only -xdff removes it and leaves the registration prunable. The guard keys on the gitlink, not on the form of .git. Also splits the stray # that joined the two comment blocks. --- .gitignore | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/.gitignore b/.gitignore index b7d7f71..fd120b1 100644 --- a/.gitignore +++ b/.gitignore @@ -46,9 +46,11 @@ CLAUDE.local.md # Worktrees Claude Code creates for parallel sessions and isolated subagents. # Only this subdirectory, so anything else that lands under `.claude/` stays visible -# to git. Nothing is tracked there today.# -# They sit inside the working tree rather than beside it, so `git clean -xdf` here -# wipes a live worktree's contents while `.git/worktrees/` survives, leaving a -# registration that needs `git worktree prune`. A worktree's `.git` is a file rather -# than a directory, so git's nested-repo guard does not stop it. +# to git. Nothing is tracked there today. +# +# They sit inside the working tree rather than beside it. `git clean -xdf` leaves them +# alone: git's nested-repository guard resolves a gitfile too, so it reports "Skipping +# repository .claude/worktrees/" and the contents survive. `git clean -xdff` does +# not skip them, and wipes a live worktree while `.git/worktrees/` survives, +# leaving a registration that `git worktree prune` then has to clear. .claude/worktrees/