Git Worktrees Are the Most Underused Feature in Git

There is a feature in Git that has been available since version 2.5, released in July 2015, and most developers have never heard of it. It does not require a plugin. It is not experimental. It is documented, stable, and solves a problem that nearly every developer encounters weekly: working on multiple branches at the same time.

That feature is git worktree.

What Are Git Worktrees?

A git worktree lets you check out multiple branches of the same repository simultaneously, each in its own directory on your filesystem. No cloning. No copying. No juggling stashes. Each worktree gets its own working directory and its own index, but they all share the same .git data --- the same commits, the same refs, the same history.

If you have ever been deep in a feature branch and needed to quickly review a pull request, fix a production bug, or compare behavior across two branches, you know the pain. You either stash your work, clone the repo again, or resign yourself to context-switching one branch at a time.

Worktrees eliminate that entirely. You just open another directory.

How Worktrees Work: A Practical Tutorial

Let's walk through the core commands. Suppose you are working in a repository at ~/projects/my-app on the main branch.

Creating a Worktree

To check out a feature branch in a separate directory:

git worktree add ../my-app-feature feature-branch

This creates a new directory at ~/projects/my-app-feature with the feature-branch checked out. The directory is a fully functional working copy --- you can edit files, run tests, start dev servers, everything. But it shares the same underlying Git data as your main worktree.

If the branch does not exist yet, you can create it and add the worktree in one step:

git worktree add -b new-feature ../my-app-new-feature

This creates a new branch called new-feature based on your current HEAD and checks it out in the new directory.

Listing Worktrees

To see all your active worktrees:

git worktree list

Output looks something like this:

/Users/you/projects/my-app              abc1234 [main]
/Users/you/projects/my-app-feature      def5678 [feature-branch]
/Users/you/projects/my-app-new-feature  ghi9012 [new-feature]

Each line shows the directory path, the current commit hash, and the checked-out branch.

Removing a Worktree

When you are done with a worktree, clean it up:

git worktree remove ../my-app-feature

This removes the directory and unregisters the worktree. The branch and its commits remain untouched in the repository.

If you manually delete the directory instead, run git worktree prune to clean up stale references.

Key Rules to Know

There are a few important things to understand about how worktrees behave:

• Shared .git directory. All worktrees share the same .git data. A commit made in one worktree is immediately visible in every other worktree. The same goes for stashes, tags, and remote refs.
• Independent working directory and index. Each worktree has its own set of files on disk and its own staging area. Changes in one worktree do not appear in another until they are committed.
• One branch per worktree. Git prevents you from checking out the same branch in two worktrees simultaneously. This is a safety feature --- it prevents you from accidentally making conflicting changes to the same branch from two different directories.
• Lightweight. Worktrees do not duplicate your repository's object database. Git uses hardlinks where possible, so the disk overhead is minimal.

Common Use Cases (No AI Required)

Even if you never use an AI coding tool, git worktrees can transform your daily workflow. Here are the scenarios where they shine.

Reviewing a PR While Continuing Your Work

You are mid-feature on add-search when a teammate asks you to review their pull request on fix-auth-redirect. Without worktrees, you stash your changes, switch branches, review, switch back, pop the stash, and hope nothing broke. With worktrees:

git worktree add ../my-app-review fix-auth-redirect

Open ../my-app-review in another editor window. Review the code. Run the tests. Leave your feature branch completely untouched.

Running Long Tests on One Branch While Developing on Another

Your test suite takes twelve minutes. You want to run the full suite on your feature branch, but you also want to keep writing code. With worktrees, you can run tests in one directory and continue developing in another. Both are the same repository. Neither interferes with the other.

# In terminal 1: run tests in the worktree
cd ~/projects/my-app-feature
npm test
 
# In terminal 2: keep coding in the main worktree
cd ~/projects/my-app
vim src/components/Dashboard.tsx

Comparing Behavior Across Branches Side by Side

Need to compare how a page renders on main versus your feature branch? Start two dev servers on different ports:

# Main branch (default worktree)
cd ~/projects/my-app && PORT=3000 npm run dev
 
# Feature branch (worktree)
cd ~/projects/my-app-feature && PORT=3001 npm run dev

Open both in your browser and compare directly.

Hotfixes Without Stashing Work in Progress

Production is down. You need to create a hotfix branch from main immediately. Your current branch has a dozen uncommitted files across three features. Stashing all of that and hoping it replays cleanly is stressful. Instead:

git worktree add -b hotfix/fix-login ../my-app-hotfix main
cd ../my-app-hotfix
# Fix the bug, commit, push, deploy
git worktree remove ../my-app-hotfix

Your in-progress work was never touched.

Why Worktrees Are Perfect for AI Agents

Here is where things get interesting. The rise of AI coding agents --- tools that can read your codebase, write code, and run commands --- has created a new problem that worktrees solve elegantly.

AI coding agents need filesystem isolation. They read files to understand context, write files to implement changes, and run commands to verify their work. If you have two agents working simultaneously, or an agent working while you are also editing files, they are all modifying the same working directory. That is a recipe for conflicts, race conditions, and broken state.

This is the core problem with most AI coding tools today: they assume a single-threaded workflow where the developer and the AI take turns. But that is not how productive development works.

Git worktrees provide exactly what parallel AI development needs:

• Complete filesystem isolation. Each worktree is its own directory. An agent in one worktree cannot accidentally overwrite files another agent is editing.
• Independent branch tracking. Each worktree is on its own branch, so changes are isolated at the Git level too.
• Shared Git history. All worktrees see the same commits, so agents can reference the full history of the project.
• Zero-copy efficiency. Worktrees do not duplicate your .git objects. Git uses hardlinks, so spinning up ten worktrees does not mean ten copies of your repository.
• Clean branch-per-task workflow. Each task gets its own branch in its own worktree. When the task is done, the branch gets merged and the worktree gets removed. No residual state.

This maps perfectly to how real AI development workflows should operate --- multiple tasks running in parallel, each isolated, each reviewable independently.

How ChatML Orchestrates Worktrees

ChatML is built around this insight. When you create a new session in ChatML, here is what happens behind the scenes:

1. A new branch is created from your current HEAD. The branch name encodes the session, so you can always trace a set of changes back to the conversation that produced them.
2. A worktree is created using git worktree add, placing the new working directory in an isolated location. The agent never touches your main working directory.
3. A Claude agent is spawned and scoped to that worktree directory. It can read files, write files, and run commands --- but only within the boundaries of its worktree.
4. File changes are watched in real time. As the agent modifies files, diffs stream into the ChatML UI so you can see exactly what is happening.
5. When the session completes, you review the diff, merge the branch if you are satisfied, and the worktree is cleaned up automatically.

The key insight is that multiple sessions can run simultaneously. Each session gets its own worktree, its own branch, and its own agent instance. They all share the same repository history, but they cannot interfere with each other. You can have one agent refactoring your authentication system, another writing tests for your API endpoints, and a third updating your documentation --- all at the same time, all in the same repo.

This architecture --- which required some deliberate technology choices to build well --- turns AI coding from a sequential back-and-forth into genuine parallel development.

Branch Watching and Real-Time Diffs

One of the benefits of the worktree model is observability. Because each worktree is an independent directory, ChatML can run a file system watcher on each one without interference. When an agent modifies a file, the change is detected immediately and the diff is computed against the branch point.

This means you can watch multiple agents work at the same time in the ChatML UI. Each session shows a live stream of file changes, additions, and deletions. You see the same information you would see in a git diff, but updating in real time as the agent writes code.

Because the worktrees are isolated directories, the file watchers are independent too. A change in one worktree does not trigger a watcher in another. There is no cross-talk, no false positives, no performance degradation as you add more sessions.

When an agent finishes its task, you get a clean diff of everything that changed on that branch. You can review it the same way you would review any pull request --- file by file, line by line. If something looks wrong, you can ask the agent to revise it, or you can edit the files yourself. The worktree is just a directory with a branch checked out. There is nothing magical about it.

Try It Yourself

Even if you are not interested in AI coding tools, git worktrees are worth adding to your toolkit today. Here is a quick cheat sheet to get started:

# Create a worktree for a new branch
git worktree add ../project-experiment -b experiment
 
# Create a worktree for an existing branch
git worktree add ../project-review origin/pr-42 --checkout
 
# List all worktrees
git worktree list
 
# Remove a worktree when done
git worktree remove ../project-experiment
 
# Clean up stale worktree references
git worktree prune

Git Worktrees vs. Git Stash vs. Git Clone

Developers often reach for git stash or a full git clone when they need to work on multiple things. Here is how worktrees compare:

When to use stash: You need to briefly switch branches and come right back. The change is small and you do not need two checkouts simultaneously.

When to use worktrees: You need to work on two branches at the same time -- reviewing a PR while coding, running tests on one branch while developing on another, or running multiple AI agents in parallel.

When to use clone: You need a completely independent copy with its own remote configuration, or you are working across multiple forks.

A few tips from experience:

• Keep worktree directories next to your main repo, not inside it. Using ../repo-name-suffix is a common convention.
• Remember that node_modules is not shared. Each worktree has its own working directory, so you will need to run npm install (or your package manager equivalent) in each one. This is also true for any build artifacts or generated files.
• Use descriptive directory names that match what you are doing. ../my-app-hotfix is more useful than ../my-app-2.
• Do not forget to remove worktrees when you are done. They take up disk space and can accumulate over time. git worktree list is your friend.

We built ChatML on this foundation -- the full story of 750+ AI-written pull requests shows what parallel worktree development looks like at scale. ChatML launched as v0.1.0 with automatic worktree management built in. If you want this entire workflow automated --- worktree creation, branch management, AI agent scoping, real-time diff streaming, and clean teardown --- that is exactly what ChatML does. Each AI session runs in its own worktree, so you can run multiple agents in parallel without ever worrying about filesystem conflicts.

Download ChatML and try it with your own repositories.