Git Worktrees Explained: Why They're Suddenly Trending (Thanks to AI Coding Agents)

If you have followed developer discussions or coding-agent changelogs recently, you have probably seen git worktree mentioned as if it were a new invention. In reality, Git introduced worktrees back in 2015 (version 2.5). The sudden surge in interest has less to do with Git itself and more to do with how modern developer tooling runs.

Here is what a worktree actually does, what it costs you, and why it matters today.

What a Worktree Actually Is

Normally, a Git repository gives you one working directory tied to one branch at a time. Need to look at another branch? You git stash, checkout, do your work, checkout back, and stash pop. It works, but it causes friction, especially if you have a dev server running or uncommitted changes you do not want to touch yet.

A worktree lets you check out multiple branches at once, in separate folders, all sharing the same underlying repository:

# from inside your existing repo, currently on `main`
git worktree add ../myproject-feature-x feature-x

That creates a sibling folder checked out to feature-x. Your original folder stays on main, untouched. Both are functional checkouts of the same repository rather than separate clones.

git worktree list              # see everything active
git worktree remove <path>     # done with it, clean up

Disk Space Costs: What Actually Gets Duplicated

The .git directory (commit history, refs, objects, and trees) is shared across all worktrees. Git stores that data once, regardless of how many worktrees you create.

What does get duplicated is the set of checked-out files for each branch. On a sample repository measured during testing:

Adding a worktree cost roughly +76 MB instead of +143 MB. You are not re-cloning the repository, only checking out an additional set of source files.

What a Worktree Does Not Give You: Your Environment

A worktree only gives you Git-tracked files. Anything ignored by .gitignore or living outside the repository must be configured separately:

• node_modules: Always gitignored and never copied across. Each worktree requires its own npm install, yarn install, or pnpm install before running.
• Virtual environments, .env files, and local services: Python virtualenvs, database connections, and local secrets live outside version control, so each worktree needs its own configuration.
• Build caches: Local compiler and bundler caches are not shared by default.

A couple of practical notes for frontend projects:

• pnpm softens the disk cost. It uses a global content-addressable store and hardlinks packages into each node_modules. Multiple worktrees add minimal disk overhead even though each still requires an install pass. Standard npm and classic yarn do not do this; each worktree gets a standalone copy of every dependency.
• Do not symlink node_modules between worktrees unless you are certain both branches have identical dependencies. If package.json or the lockfile diverged between branches, a shared node_modules will cause runtime errors on one of them.

The Other Gotcha: Port Conflicts

If you launch dev servers in two worktrees simultaneously (for instance, running vite in both), both processes will attempt to bind the same default port. The second process either fails outright or grabs another port unpredictably, leading to confusing debugging sessions where you inspect the wrong server.

Common solutions:

• Override the port manually per worktree: vite --port 3001, next dev -p 3001, or PORT=3001 npm run dev.
• Use a local environment file: Place a .env.local inside each worktree (gitignored) specifying a distinct PORT.
• Let the tooling auto-increment: Vite and Next.js can assign the next available port automatically. This works for quick checks, though tracking which branch runs on which port requires attention.
• Containerize with Docker Compose, assigning isolated dynamic port mappings per instance.

There is no built-in port negotiation in Git or npm. You coordinate ports manually, exactly as you would with two distinct repository clones.

Why Worktrees Are Trending Now

Three developments converged:

1. Parallel AI coding agents. Tools that run multiple agents concurrently (such as one investigating an issue while another writes tests) require isolated working directories. Worktrees provide isolated checkouts from the same local repository without race conditions or overwriting uncommitted work.
2. Higher context-switching overhead. Long-running dev processes, TypeScript language servers, and file-watching containers make the traditional stash checkout stash pop cycle slow down local iteration.
3. A mature feature meeting a new use case. Git worktrees existed quietly for years. Parallel, agent-assisted workflows simply made multi-directory checkouts a practical daily necessity.

Summary

Worktrees solve a clear problem: they share Git history, avoid full repository duplicates, and keep multiple branches active in parallel without stashing. At the same time, they require manual environment management: dependencies must be installed per folder, and dev server ports need coordination. For sequential solo work, standard checkouts are often enough. When running automated coding agents alongside your own workflow, worktrees become indispensable.

Building tooling, dashboards, or full-stack products that need a solid engineering workflow behind them? Partner with the developers at Klickspell.