HOOOK
← Back to Blog

Git Worktrees: The Feature That Waited a Decade for Its Moment

By Avi Peltz

Git worktrees, introduced in 2015 as part of Git 2.5, remained largely unknown for nearly a decade. The feature enables developers to maintain multiple working directories connected to a single repository, solving workflow challenges that have become increasingly relevant with modern development practices and AI-assisted coding.

Part I: The Problem Before Worktrees

The Pain of Context Switching

Traditional workflow friction involves constant switching between branches using git stash, git checkout, and git stash pop. This creates mental overhead as editors reload files, language servers re-index, and developers lose context.

Historical Workarounds

Multiple clones: Developers duplicated entire repositories to work on parallel features, creating maintenance complexity and synchronization issues.

git stash gymnastics: While functional, managing multiple stashes proved error-prone and cumbersome.

Linear work: Teams simply avoided parallel development, finishing one task before starting another.

The git-new-workdir Script

Before official support, Git shipped a contributed script in contrib/workdir/git-new-workdir that created new working directories with symlinked .git internals. This was "hacky" and unsupported, with a fragile symlink-based architecture.

Part II: Worktrees Land in Git 2.5

July 2015: Official Introduction

Git 2.5 (July 29, 2015) introduced git worktree as a first-class feature, authored primarily by Nguyễn Thái Ngọc Duy. The concept formalized a key insight: repositories consist of two separable components—the object store containing commits and the working state of checked-out files.

Architecture

Creating a worktree establishes:

  • A new directory with .git as a file (not directory) referencing the main repository
  • Metadata entries in .git/worktrees/<name>/
  • A branch checkout in the isolated directory

The .git file contains: gitdir: /path/to/main/repo/.git/worktrees/feature-branch

Shared vs. Separate Resources

Shared across worktrees: Object store, branch references, tags, remote configuration, hooks, repository configuration.

Separate per worktree: Working directory files, HEAD, index, staging area, untracked files, merge/rebase state.

The One Branch Rule

Git enforces that a branch can only be checked out in one worktree at a time, preventing confusion and preventing dirty diffs from appearing unexpectedly.

Part III: The Anatomy of a Worktree

File Structure

The main repository maintains .git/worktrees/ containing subdirectories for each linked worktree with their own HEAD, index, and commondir references.

Garbage Collection and Pruning

git worktree prune removes stale worktree metadata for deleted directories, automatically preventing orphaned entries from accumulating.

Part IV: Why Worktrees Stayed Niche

Single-Branch Dominance

Most teams followed linear workflows: create branch, work, open PR, merge, delete. Parallel work wasn't considered necessary.

GUI Support Gaps

Popular Git interfaces (GitKraken, SourceTree, GitHub Desktop, VS Code) lacked or provided poor worktree support, limiting visibility and adoption.

Command Obscurity

git worktree add ../feature -b feature proved less intuitive than the familiar git checkout -b feature for developers accustomed to traditional workflows.

Storage Constraints

Each worktree requires a full working directory checkout. On smaller SSDs or slower disks, this overhead discouraged adoption.

Part V: Why Worktrees Are Having a Moment

Code Review Culture

Interrupt-driven development demands quick context switching. Worktrees preserve feature-branch context when reviewing other work or addressing urgent issues without destructive stashing.

CI/CD and Testing

Testing interactions between multiple branches or PR combinations becomes feasible when both are checked out simultaneously without rebasing.

Monorepo Efficiency

Large repositories benefit significantly—cloning a 10GB repo twice wastes storage, while worktrees share the object store and only duplicate working files.

AI Coding Agents

This represents the primary driver. AI agents need isolated environments to:

  • Make changes without affecting the user's workspace
  • Commit to independent branches
  • Run builds and tests
  • Iterate transparently

The pattern enables parallel human and AI work on shared codebases, treating agents similarly to reviewing a colleague's pull requests.

Part VI: Worktrees Under the Hood

Repository Discovery

Git searches for .git:

  • Checks current directory
  • If .git is a file, reads its gitdir: path
  • Follows that path
  • Checks for commondir file indicating shared resources elsewhere

The commondir Mechanism

Linked worktrees' git directories contain commondir files pointing to the main .git. Git consults commondir for shared resources (objects, refs) and uses worktree-specific directories for local state.

Concurrent Access Protection

Lock files prevent corruption:

  • .git/index.lock — prevents concurrent index modifications
  • .git/refs/heads/<branch>.lock — prevents concurrent ref updates
  • .git/worktrees/<name>/locked — marks worktrees as locked during unavailability

Part VII: Leveraging Worktrees Effectively

Organization

Establish predictable locations: ~/.worktrees/project-name/branch-name/ or adjacent: ~/projects/repo/ and ~/projects/repo--feature/.

Naming Conventions

Match worktree directories to branch names for clarity.

Helper Functions

Shell utilities simplify creation: 

wt() {
  local branch="$1"
  local repo_name=$(basename $(git rev-parse --show-toplevel))
  local worktree_path="$HOME/.worktrees/$repo_name/$branch"
  git worktree add "$worktree_path" -b "$branch"
  cd "$worktree_path"
}

Cleanup

Regularly remove completed worktrees to prevent accumulation.

Limitations

  • Cannot checkout identical branches simultaneously
  • Cannot nest worktrees
  • Submodules require separate initialization
  • Some IDE features lack worktree awareness

Conclusion

Worktrees represent old technology meeting contemporary demands. The implementation elegantly separates shared components (objects) from isolated ones (working files)—analogous to containerization principles. For developers managing parallel work, conducting reviews, or coordinating with AI agents, worktrees provide isolation without duplication.