docs: how to set up a git worktree, and why inheritance hides the gaps - #860
Merged
Conversation
A worktree gets a fresh checkout but no npm install. Node walks up for node_modules, so a worktree inside this repo silently inherits the main checkout's ~1300 packages and mostly works — which is why the gaps surface as unrelated-looking failures deep into a task instead of up front. Documents `npm ci` as the one-time setup step, with the four failure signatures hit while working in a worktree this week. They look unrelated and have four distinct causes: - postinstall-generated + gitignored (licensing key) — in no fresh checkout - un-hoisted workspace dep (posthog-node, only in apps/website/node_modules) — the walk up from WORKTREE/apps/website never passes through MAIN's - literal path reference (katex css, resolved from workspace root) — no module resolution, so nothing to inherit through - turbopack resolving its own workspace root (cockpit build) Also records the two things not to do: hand-copying packages from the main checkout (a partial copy pulls a package without its transitive deps, and a mistargeted cp can overwrite node_modules itself), and `npm install` on macOS (rewrites the lockfile and drops the Linux @next/swc-* bindings). Verified rather than assumed — ran `npm ci` in this worktree: exit 0, package-lock.json byte-identical afterwards, all four gaps closed, and `nx build cockpit` went from failing on pristine main to exit 0. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Contributor
blove
enabled auto-merge (squash)
August 30, 2026 01:21
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
1 participant
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.
A
git worktreegets a fresh checkout but nonpm install. Node resolves modules by walking up, so a worktree created inside this repo silently inherits the main checkout's ~1,300 packages and mostly works. That inheritance is the whole problem: the gaps don't fail at setup, they fail an hour into a task, looking like something you just broke.I hit four of them this week. They look unrelated and have four distinct causes:
Failed to resolve import "./license-public-key.generated.js"Cannot find module 'posthog-node'(website build)apps/website/node_modules, never hoisted; the walk up fromWORKTREE/apps/website/never passes through the main checkout'sCould not resolve "node_modules/katex/dist/katex.min.css"Next.js inferred your workspace root, but it may not be correct(cockpit build)One command fixes all four:
npm ci, once per worktree.Also documents what not to do
Don't hand-copy packages from the main checkout. This is what I'd been doing, and it's what my own notes recommended — both were wrong. A partial copy pulls a package without its transitive dependencies (copying
nexttraded one error for a worseCannot find module 'picocolors'cascade), and a mistargetedcpinto a not-yet-existing directory copies the package asnode_modules, splatting its files at the root. The list of packages to copy also keeps growing.Don't run
npm installin a worktree on macOS — it rewritespackage-lock.jsonand drops the Linux@next/swc-*bindings, breaking CI.npm ciinstalls strictly from the lockfile and never writes it.Verified, not assumed
I'd never actually run the remedy I was about to document, so I ran it in this worktree first:
npm ci→ exit 0package-lock.jsonbyte-identical afterwards (diff -qclean) — confirming the "never rewrites the lockfile" claim directly rather than citing docsposthog-nodeinapps/website/node_modules, katex CSS at the worktree root,nextresolvable (1,322 packages)nx build cockpitwent from failing to exit 0 — the same build I'd confirmed fails on pristine main in this worktreenx build websitealso exit 0Docs-only change; no code touched.
🤖 Generated with Claude Code