Skip to content

Git Worktree Workflows

When an agent works on multiple features, switching branches leaves files dirty. Worktrees give each task its own directory while sharing Git history.

Why Branches Don't Isolate

When an agent works on a task, it needs a bounded workspace. Traditional branch switching fails this requirement:

  • Context bleed: Files modified for one task remain dirty when switching
  • Concurrent work blocked because only one branch can be active
  • Stashing and switching disrupts running processes and dependency state

Worktrees solve this by giving each task its own directory with an independent working tree, while sharing the underlying Git history.

Worktrees vs Alternatives

Aspect Branch Switching Multiple Clones Worktrees
Isolation None Full Full
Disk space Minimal Duplicated Shared .git
Git history Shared Duplicated Shared
Setup time Instant Slow (full clone) Fast
Agent parallelism No Yes Yes

Branch switching doesn't isolate files, and cloning duplicates everything. Worktrees share Git data while keeping working directories separate.

How .git Sharing Works

A worktree is a linked working tree pointing to the same .git directory:

project/
├── .git/                    # Shared repository data
├── .worktrees/              # Worktree container
│   ├── feature-auth/        # Independent working tree
│   └── bugfix-login/        # Another independent tree
└── src/                     # Main working tree

Each worktree has its own HEAD, staged changes, and can run separate processes. But all share Git objects, remotes, and branches. Changes pushed from one worktree are immediately visible to others.

Directory Strategies

Project-local (.worktrees/): Visible, discoverable, requires .gitignore entry.

Global location (~/.worktrees/project/): No .gitignore needed, works across repos, less discoverable.

Most agent workflows prefer project-local for simplicity.

Why Agents Benefit

Worktrees align naturally with how agents work:

  • Bounded context: Each task gets its own isolated environment
  • Multiple agents work simultaneously without coordination overhead
  • Switch between tasks without losing state
  • Start each task from a known-good commit

The overhead of creating a worktree pays off whenever isolation prevents confusion or protects the main working tree from experimental changes.

Topics

  • Workflows - Parallel agents, single-task isolation, and when worktrees help
  • Lifecycle - From basic create/cleanup to managed development workflows

External Resources