Echoes: Notes & Signals by James StoneEchos

Git Worktree

2 min read

this allows you to have a fully independant copy of the repo in a new directory.

gpt-co-created

Git Worktrees — One-Page Practical Guide

TL;DR Git worktrees let you check out multiple branches of the same repo at the same time, in separate directories, without cloning or constantly switching branches.

What is a Git Worktree?

A Git worktree is an additional working directory attached to the same Git repository.

  • One repo
  • One .git object store
  • Multiple working directories
  • Each directory checks out a different branch

Think of it as parallel checkouts, not copies.

Why Would I Use It?

Git worktrees solve problems caused by:

  • Frequent branch switching
  • Stashing / unstashing
  • Needing two versions of the app running at once
  • Large monorepos where cloning is expensive

They are especially useful when:

  • You want parallel work
  • You want one branch frozen while another is active
  • Tooling expects a full repo checkout

Your Concrete Example (as-is)

Goal

  • Keep working on your current feature branch
  • Spin up a reference branch only to run the dev server
  • Compare behavior/UI without touching that reference branch

Solution

  • Main repo directory → active development
  • Worktree directory → reference branch, dev server running

You:

  • Never switch branches
  • Never stash
  • Never risk mixing states

This is a textbook Git worktree use case.

Same Example (Anonymized)

Scenario

  • Large monorepo
  • App depends on shared libraries and root workspace config
  • You need:
    • Branch A → active coding
    • Branch B → baseline preview

Using worktrees

  • Repo root stays on Branch A
  • A sibling directory checks out Branch B
  • Both run simultaneously
  • Both are fully functional

How You Navigate Worktrees

Worktrees are just directories.

Example layout: