Mastering Git Worktree: Clean Multi‑Branch Development Without Clutter

Problem

Git normally allows only a single branch to be checked out in a working directory. When a developer needs to work on hot‑fixes, feature branches, and maintenance branches at the same time, they must repeatedly stash changes, switch branches, and repeat the process, which wastes time and introduces context‑switch overhead.

Built‑in solution: git worktree

The git worktree command lets you create additional working directories that share a single .git repository. Each worktree can have a different branch checked out, while all of them use the same object database, saving disk space.

Improved workflow

The following steps create a clean layout where the project root contains only the .git directory and each branch lives in its own sub‑directory.

Step 1 – Clone the repository as a bare repository directly into .git

git clone --bare --single-branch <repo-url> my-project/.git

Cloning into .git makes the project root itself a Git repository; only the hidden .git/ folder holds the Git metadata.

Step 2 – Configure remote tracking for all branches

git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
git fetch origin

The fetch specification tells Git to retrieve every branch from origin as remote‑tracking references (e.g., origin/feature‑x) without creating local branches.

Step 3 – Add worktrees for the branches you need

# main branch
git worktree add main main

# feature branch example
git worktree add feature-auth origin/feature-auth

# bug‑fix branch example
git worktree add bugfix-cache origin/bugfix-cache

Resulting directory layout

my-project/
├── .git/                # Git internal data only
├── main/                # checkout of the main branch
├── feature-auth/        # checkout of origin/feature‑auth
└── bugfix-cache/        # checkout of origin/bugfix‑cache

Why this layout is advantageous

Clean local branch list – git branch shows only main; all other branches appear as remote references, reducing visual noise.

No fetch friction – Remote branches are already available as references. To start work on a new branch, simply run git worktree add <dir> origin/<new‑branch>.

IDE‑friendly – Each worktree can be opened in a separate editor window (VS Code, Claude Code, etc.) without path confusion.

Single Git database – All worktrees share the same .git/, saving disk space and avoiding duplicate clones.

Full setup script

# Clone as a bare repository into .git
git clone --bare --single-branch <repo-url> my-project/.git

# Configure remote tracking for every branch
git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
git fetch origin

# Create directories for worktrees (optional organization)
mkdir -p work/{current,features,maintenance}

# Add the main worktree
git worktree add work/current main

# Verify the configuration
git branch            # shows only 'main'
git branch -a         # shows all remote branches
git worktree list     # lists active worktrees

Typical daily workflow

Create a new worktree for a feature or bug‑fix, work, then remove it when finished.

# Add a worktree for an existing remote branch
git worktree add my-feature origin/my-feature

# Or create a new branch from main and add a worktree for it
git worktree add -b my-feature my-feature main

# Work inside the worktree
cd my-feature
code .
git commit -am "description of changes"
git push

# When the work is done, clean up the worktree
git worktree remove my-feature

Warning

Each worktree has its own working copy. In monorepos or projects with shared dependencies you must run the appropriate install command (e.g., npm install, yarn, pip install -r requirements.txt) inside each worktree to ensure dependencies are available.