teebe › Guides › Git worktree vs branch

Git worktree vs branch: when to use which

Plus worktree vs clone and worktree vs stash, with a decision table.

Short answer: a branch is a pointer to a commit inside your repository's history. A worktree is a second working directory on disk, checked out to a branch (or a detached commit) of that same repository. They aren't competing options for the same job, a git worktree always has a branch (or a detached HEAD) checked out inside it. The real question is whether you want a second branch in your current directory, or a second directory entirely. This guide walks through both, plus how a worktree compares to cloning the repo again and to git stash, so you know which one to reach for. If you want the visual version of all this running live, teebe is a native macOS worktree GUI built for exactly this.

What a branch gives you, and what switching costs

A branch costs almost nothing to create: git branch feature-a just writes a new ref pointing at your current commit. The catch is that your repository has only one working directory, so only one branch can be checked out at a time. Moving to another branch means git checkout or git switch, which rewrites every file in your working tree to match that branch's snapshot.

That's fine when your tree is clean. It's not fine mid-feature: uncommitted changes either block the switch outright, or force you to commit something half-finished, or send you to git stash first. Then there's the rebuild cost, switch a branch in a project with a compiled asset pipeline or a long npm install, and you're waiting again every time you cross branches. None of this is a bug in branches, it's just what "one working directory" implies.

What a worktree gives you

A worktree sidesteps the one-directory limit. git worktree add creates a second working directory, linked to the same .git object store, with its own branch checked out. Branches, stashes, remotes, and the full commit history are shared, only the working files and the index are duplicated. One rule to remember: a branch can be checked out in only one worktree at a time, so each worktree needs its own branch (or a detached HEAD).

git worktree add ../repo-hotfix -b hotfix
git worktree list
git worktree remove ../repo-hotfix

Your main checkout is untouched while the second one exists. No stash, no rebuild, no committing half-done work just to switch context. Removing a worktree does not delete its branch, that's a separate git branch -d.

Worktree vs clone

A second git clone also gets you a second working directory, so why not just clone again? Because a clone duplicates the entire object store, every commit, every blob, on disk, and re-fetching keeps two remotes in sync separately. A worktree shares one .git directory, so it's a fraction of the disk cost and there's nothing to re-fetch, new commits made in one worktree are immediately visible to every other worktree of the same repo.

A clone still earns its place when you genuinely want isolation: a different remote entirely, a fork you're testing independently, or a case where you don't want any shared state at all, including shared stashes. For everyday parallel work on the same repository, a worktree is the lighter tool.

Worktree vs stash

git stash is for a five-minute interruption on the branch you're already on: shelve your changes, do the quick thing, stash pop, keep going. It's fast because it doesn't touch the filesystem layout at all.

Once the interruption needs its own build, its own dependency install, or is going to run longer than you'd want to hold your real work in limbo, stash stops being the right tool. A worktree gives the interruption a completely separate directory, so your in-progress branch never moves and never risks a messy stash pop later.

Decision table

Why AI coding agents made worktrees mainstream

Worktrees existed for years as a niche git feature. They went mainstream because terminal coding agents needed a way to run without colliding. claude --worktree creates an isolated worktree and starts a session inside it, on a new branch, by default under .claude/worktrees/, our Claude Code worktrees guide covers the flags and cleanup behavior. Codex's app does the same thing when you choose "Worktree" in a new chat, starting in a detached HEAD until you name a branch, see the Codex worktrees guide. Cursor's parallel agents each get their own isolated checkout too, covered in the Cursor worktrees and parallel agents guide. All three tools converged on the same idea: one worktree per agent session, so agents can't step on each other's files.

The side effect is that a single project can end up with several worktrees on disk at once, several separate directories, each mid-change. That's what teebe is for: it lists every worktree of every repo you add, shows a live file tree for each, badges files the instant an agent touches them, and lets you peek any diff inline, all in one native window instead of several terminal tabs. See every git worktree GUI for Mac compared if you want the full landscape.

Gotchas

• Branch already checked out. fatal: 'x' is already checked out at <path> means that branch is in use by another worktree. Check out a different branch or create a new one for the second worktree.
• Gitignored files aren't there. A new worktree is a fresh checkout, files like .env that are gitignored won't be copied in automatically.
• Stale worktree references. If you delete a worktree directory by hand instead of running git worktree remove, git still thinks it exists. Run git worktree prune to clean up the reference.

For the full set of commands, see the git worktree cheat sheet.

Frequently asked questions

Is a git worktree the same as a branch?

No. A branch is a pointer to a commit inside one repository's history. A worktree is a second working directory on disk, checked out to a branch (or a detached commit) of a repository you already have. Every worktree has a branch or detached HEAD, but a branch does not require a worktree of its own.

Can two worktrees use the same branch?

No. Git blocks checking out the same branch in two worktrees at once and prints fatal: 'branch' is already checked out at <path>. Check out a different branch, or create a new one, in the second worktree.

Does a git worktree copy the whole repository?

No. Linked worktrees share the same .git object store, branches, stashes, and remotes as the main worktree. Only the working files and an index are duplicated, so a worktree is much cheaper than a second clone.

When should I use git stash instead of a worktree?

Use stash for a short interruption you'll resolve in minutes, like a quick fix on the same branch. Use a worktree when the interruption needs its own build, its own dependency install, or will run for longer than a few minutes, since a worktree does not touch your current working directory at all.

Do gitignored files like .env show up in a new worktree?

No. A worktree is a fresh checkout, so gitignored files are absent by default. Claude Code and Codex both support a .worktreeinclude file, in gitignore syntax, that lists gitignored files to copy into each new worktree.

Free · open source · macOS 14+. Back to teebe.io →