Git Worktree FAQ

The git worktree command was introduced in Git 2.5, released in July 2015. The git worktree list subcommand was added in Git 2.7 (October 2015), and git worktree remove came later in Git 2.17 (April 2018). Before remove existed, you had to manually delete the directory and run git worktree prune.

You can check your Git version with git --version. Any version from the last several years will have full worktree support.

No. Worktrees are entirely a local concept. When you push from a worktree, GitHub (or any remote) sees a normal push from a normal Git client. The remote has no way to tell whether the push came from a primary worktree, a linked worktree, or a completely separate clone. Your commits, branches, and tags look identical regardless.

Yes, if the branches have different dependencies. Each worktree has its own working directory, which means its own node_modules folder. When you create a new worktree, it starts without node_modules — you need to run npm install (or yarn / pnpm install) in that directory.

The upside is that each worktree’s dependencies are isolated. Switching branches with git checkout in a single directory can leave stale or mismatched node_modules, while worktrees avoid this problem entirely.

If you use pnpm, its content-addressable store means shared packages are only stored on disk once, reducing the cost of running install in multiple worktrees.

No. Git enforces a rule that each branch can only be checked out in one worktree at a time. If you try, you will see:

$ git worktree add ../second-wt feature/x
fatal: 'feature/x' is already checked out at '/home/user/first-wt'

This restriction exists to prevent conflicting updates to the same branch ref. If two worktrees could modify the same branch independently, commits could be lost.

Workaround: If you need the same code in two places, create a new branch from the same commit:

git worktree add -b feature/x-review ../review feature/x

A linked worktree uses roughly the same space as the checked-out files in your project — it is not a full clone. All worktrees share a single object store (the .git/objects directory), so Git objects (commits, trees, blobs) are not duplicated.

For a typical project, the cost is the size of the source files plus any build artifacts or dependencies generated in that worktree (like node_modules or target/). Compare this to git clone, which duplicates the entire object database.

You can check with:

du -sh ../my-worktree

Yes. Worktrees are a core Git feature, not a third-party tool. Git has built-in safeguards:

• It prevents the same branch from being checked out in two worktrees.
• git worktree remove refuses to remove a worktree with uncommitted changes unless you pass --force.
• Worktrees share the same reflog, so you can recover from mistakes the same way you would in any Git repo.
• Locking (git worktree lock) prevents accidental pruning of worktrees on removable media.

The one thing to avoid is deleting a worktree directory with rm -rf instead of using git worktree remove. Doing so won’t corrupt your repo, but it leaves stale metadata that you need to clean up with git worktree prune.

If you delete a linked worktree with rm -rf instead of git worktree remove, the files are gone but Git still has metadata about that worktree in .git/worktrees/<name>/. This means:

• git worktree list will still show the worktree (marked as prunable).
• The branch it had checked out may still be “locked” to that worktree, preventing you from checking it out elsewhere.

Fix: Run git worktree prune to clean up stale entries. After that, everything is back to normal.

# Clean up after a manually deleted worktree
git worktree prune

# Verify it's gone
git worktree list

Copying the repo directory (e.g., cp -r) creates a fully independent clone with its own object store. This has significant downsides compared to worktrees:

• Disk space: A copy duplicates every Git object. Worktrees share the object store.
• Synchronization: Changes in one copy are invisible to the other. With worktrees, a commit in one is immediately available in all others.
• Branch tracking: Copies have independent branch refs that can diverge. Worktrees share refs, so you always see the same branches.
• Cleanup: Copies are easy to forget about. Worktrees are tracked by Git and visible via git worktree list.

The only case where copying might make sense is if you want a truly independent repo that will diverge permanently. For parallel development on the same project, worktrees are better in every way. See also Worktree vs Clone.