Worktrees and node_modules: the real cost, and how to avoid it

What a new worktree does not have

A worktree is a checkout, and git can only check out what git is tracking. Everything in your .gitignore is, by definition, not tracked, so it is not there. Nothing is broken; the directory is exactly as complete as a fresh clone would be.

# every ignored path in the current checkout
git status --ignored --short | grep '^!!'

# what that costs, biggest first
git status --ignored --porcelain | sed -n 's/^!! //p' | xargs -I{} du -sh {} 2>/dev/null | sort -rh | head

The source checkout is not the cost

Git objects are shared across every worktree of a repository. Adding a worktree adds one checkout of the tracked files and a few kilobytes of administrative state, not a second copy of your history. On a repository with a long history that difference is enormous, and it is why git worktree add returns in under a second where git clone takes a minute.

# shared: history, objects, packs. Paid once, whatever the worktree count.
du -sh .git

# per worktree: tracked files only
du -sh --exclude=.git --exclude=node_modules .

# per worktree: the number that actually matters
du -sh node_modules

The honest arithmetic is that N worktrees cost one repository, N source checkouts, and N dependency trees. The first is free, the second is usually trivial, and the third is the entire objection. Everything below is about collapsing the third.

pnpm: one store, hard-linked everywhere

pnpm keeps every version of every package once, in a content-addressable store. In pnpm's own words, "all the files are saved in a single place on the disk. When packages are installed, their files are hard-linked from that single place, consuming no additional disk space." A second, third, and tenth worktree install therefore add close to nothing.

npm install -g pnpm

# in each worktree
pnpm install

# where the shared store is
pnpm store path

# reclaim space from versions nothing references any more
pnpm store prune

# check the store has not been corrupted by an editor or a build tool
pnpm store status

How each package manager behaves

bun documents the same idea from the other direction: it "uses the fastest installation method available on the target platform: clonefile on macOS and hardlink on Linux", falling back to copyfile where neither is available. Copy-on-write and hard links solve the same problem, so the practical answer is: if the project is already on npm and you have started running worktrees, moving to pnpm or bun is the change that pays for itself.

Copy the gitignored config automatically

Forgetting .env is the single most common way a new worktree looks broken. The application starts, fails to reach a database, and the failure has nothing to do with worktrees. Three tools now do this copy for you, and they all take the same shape: a list of gitignored paths to bring across.

Claude Code: .worktreeinclude

Put a .worktreeinclude file in the project root. It uses .gitignore syntax, and only files that match a pattern and are gitignored are copied, so tracked files are never duplicated. It applies to every worktree Claude Code creates with git, including subagent worktrees and desktop parallel sessions.

.env
.env.local
config/secrets.json

VS Code: git.worktreeIncludeFiles

The same idea as a setting, applied to worktrees created from the Source Control Repositories view. It takes glob patterns.

{
  "git.worktreeIncludeFiles": [
    ".env",
    "node_modules/**"
  ]
}

Everyone else: three lines of shell

for f in .env .env.local .env.development; do
  [ -f "$f" ] && cp "$f" "$dir/"
done

Symlinking, and exactly when it breaks

ln -s ../app/node_modules ../app-auth/node_modules

The same question in other ecosystems

Node is the loud case because node_modules is enormous and per project. Most other toolchains already put the expensive part in a machine-wide cache, so a worktree costs you the build output and nothing else.

uv has the same same-filesystem condition pnpm does, and states it directly: "It is important for performance for the cache directory to be located on the same file system as the Python environment uv is operating on. Otherwise, uv will not be able to link files from the cache into the environment and will instead need to fallback to slow copy operations."

Automate it once and stop thinking about it

Worktrees are only worth it if creating one is free. If it takes four commands and a two-minute install, you will stop doing it inside a week and go back to one directory and one agent.

#!/usr/bin/env bash
# wt <branch> - create a worktree, carry the config, install.
set -euo pipefail

name="$1"
repo="$(basename "$PWD")"
dir="../${repo}-${name//\//-}"

git worktree add -b "$name" "$dir"

for f in .env .env.local .env.development; do
  [ -f "$f" ] && cp "$f" "$dir/"
done

cd "$dir"
if   [ -f pnpm-lock.yaml ];    then pnpm install --prefer-offline
elif [ -f bun.lock ] || [ -f bun.lockb ]; then bun install
elif [ -f yarn.lock ];         then yarn install
elif [ -f package-lock.json ]; then npm ci
fi

echo "ready: $dir"

Questions people ask

Keep reading