Removing worktrees in Git - Deep Dive

Overview - Removing worktrees

What is it?

Removing worktrees in Git means deleting extra working directories linked to a single repository. These worktrees allow you to have multiple branches checked out at once in separate folders. When you no longer need a worktree, you remove it to keep your workspace clean and avoid confusion. This process safely detaches the worktree without affecting the main repository.

Why it matters

Without the ability to remove worktrees, your system would fill up with unused folders, wasting disk space and causing clutter. It would be harder to manage multiple branches simultaneously, leading to mistakes like editing the wrong branch. Removing worktrees helps maintain a tidy, efficient workflow, especially when working on many features or fixes at once.

Where it fits

Before learning to remove worktrees, you should understand basic Git commands, how to create and use worktrees, and branch management. After mastering removal, you can explore advanced Git workflows, automation scripts for managing multiple worktrees, and integrating worktrees into CI/CD pipelines.

Mental Model

Core Idea

Removing a Git worktree safely deletes its separate folder and unregisters it from the repository without harming other branches or the main project.

Think of it like...

Imagine your Git repository is a house with several guest rooms (worktrees). Each guest room lets a friend stay and work independently. When a friend leaves, you clean and close that room so it’s ready for the next visitor without disturbing the rest of the house.

┌─────────────────────────────┐
│ Main Git Repository          │
│ ┌───────────────┐           │
│ │ Worktree 1    │           │
│ └───────────────┘           │
│ ┌───────────────┐           │
│ │ Worktree 2    │           │
│ └───────────────┘           │
└─────────────┬───────────────┘
              │
       Remove worktree 2
              ↓
┌─────────────────────────────┐
│ Main Git Repository          │
│ ┌───────────────┐           │
│ │ Worktree 1    │           │
│ └───────────────┘           │
└─────────────────────────────┘

Build-Up - 6 Steps

1

Foundation

What is a Git worktree

Concept: Introduce the idea of multiple working directories linked to one Git repository.

A Git worktree is an additional folder connected to your main Git repository. It lets you check out different branches at the same time without switching branches in one folder. This helps when you want to work on multiple features or fixes simultaneously.

Result

You understand that worktrees are extra folders for different branches, not separate repositories.

Knowing that worktrees share the same repository data but have separate folders helps you manage multiple tasks without confusion.

2

Foundation

How to create a Git worktree

Concept: Learn the command to add a new worktree for a branch.

Use the command: git worktree add Example: $ git worktree add ../feature-branch feature This creates a new folder '../feature-branch' with the 'feature' branch checked out.

Result

A new folder appears with the specified branch ready for work.

Creating worktrees is simple and lets you work on branches side-by-side without switching.

3

Intermediate

Listing existing worktrees

🤔Before reading on: do you think 'git worktree list' shows only active worktrees or all worktrees ever created? Commit to your answer.

Concept: Discover how to see all current worktrees linked to your repository.

Run: $ git worktree list This command lists all active worktrees with their paths and checked-out branches.

Result

You get a list showing each worktree folder and its branch.

Knowing how to list worktrees helps you track your workspace and decide which worktrees to remove.

4

Intermediate

Why remove a worktree

🤔Before reading on: do you think removing a worktree deletes the branch or just the folder? Commit to your answer.

Concept: Understand the reasons and effects of removing a worktree.

Removing a worktree deletes the folder and unregisters it from Git but does NOT delete the branch itself. You remove worktrees to free disk space and avoid clutter when you no longer need that separate working folder.

Result

You know that branch data remains safe after removal, only the worktree folder is gone.

Separating branch deletion from worktree removal prevents accidental loss of work.

5

Advanced

Removing a worktree safely

🤔Before reading on: do you think deleting the worktree folder manually is enough to remove it from Git? Commit to your answer.

Concept: Learn the correct steps to remove a worktree without causing Git errors.

First, run: $ git worktree remove This unregisters the worktree and deletes its folder if possible. If the folder is locked or has uncommitted changes, Git will warn you. Avoid deleting the folder manually without unregistering, as Git will still think the worktree exists.

Result

The worktree is removed cleanly, and Git no longer lists it.

Using Git's remove command prevents repository corruption and dangling references.

6

Expert

Handling locked or dirty worktrees

🤔Before reading on: do you think Git allows removing a worktree with uncommitted changes by default? Commit to your answer.

Concept: Explore what happens if a worktree has uncommitted changes or is locked, and how to handle it.

Git refuses to remove worktrees with uncommitted changes to prevent data loss. You can: - Commit or stash changes in the worktree before removal. - Use force removal carefully with: $ git worktree remove --force Be cautious: forcing removal discards uncommitted work. Also, locked worktrees (e.g., open in editors) may block removal until closed.

Result

You can remove problematic worktrees safely or forcefully with awareness of risks.

Understanding Git's safety checks helps avoid accidental data loss during worktree removal.

Under the Hood

Git worktrees share the same .git repository data but have separate working directories. When you add a worktree, Git creates a new folder with a special link to the main repository's metadata. Removing a worktree unregisters this link from Git's internal worktree registry and deletes the folder if possible. This keeps the repository consistent and avoids orphaned references.

Why designed this way?

Git worktrees were designed to allow multiple branches to be checked out simultaneously without duplicating repository data. The removal process ensures safety by unregistering worktrees before deleting folders, preventing Git from referencing non-existent directories. This design balances flexibility with data integrity.

┌─────────────────────────────┐
│ Main Git Repository (.git)  │
│ ┌─────────────────────────┐ │
│ │ Worktree Registry       │ │
│ │ ┌───────────────┐       │ │
│ │ │ Worktree 1    │◄──────┼─┘
│ │ └───────────────┘       │ │
│ │ ┌───────────────┐       │ │
│ │ │ Worktree 2    │◄──────┼─┐
│ │ └───────────────┘       │ │
│ └─────────────────────────┘ │
└─────────────────────────────┘
         ▲              ▲
         │              │
   Folder 1        Folder 2

Removing a worktree deletes its folder and removes its entry from the registry.

Myth Busters - 4 Common Misconceptions

Quick: Does removing a worktree delete the Git branch it points to? Commit yes or no.

Common Belief: Removing a worktree deletes the branch and its history.

Reality: Removing a worktree only deletes the working directory and unregisters it; the branch and its commits remain intact in the repository.

Why it matters: Believing the branch is deleted can cause unnecessary fear or confusion, preventing users from cleaning up worktrees safely.

Quick: Is manually deleting a worktree folder enough to remove it from Git? Commit yes or no.

Common Belief: Deleting the worktree folder manually removes it completely from Git.

Reality: Manually deleting the folder leaves Git's worktree registry unaware, causing errors and confusion when listing or adding worktrees.

Why it matters: This can lead to broken references and errors in Git commands, complicating repository management.

Quick: Can you remove a worktree with uncommitted changes without losing data? Commit yes or no.

Common Belief: Git allows removing worktrees with uncommitted changes safely by default.

Reality: Git blocks removal of worktrees with uncommitted changes unless forced, to prevent accidental data loss.

Why it matters: Ignoring this can cause loss of work if forced removal is used without caution.

Quick: Does 'git worktree remove' delete the main repository? Commit yes or no.

Common Belief: Removing a worktree can delete or affect the main repository.

Reality: The main repository remains untouched; only the specified worktree is removed.

Why it matters: Understanding this prevents fear of damaging the main project when cleaning up worktrees.

Expert Zone

1

Git tracks worktrees in a special registry file inside the .git directory, which means removing a worktree updates this registry to keep repository state consistent.

2

Force removal of worktrees bypasses safety checks but can leave dangling references if not handled carefully, potentially confusing Git's internal state.

3

Worktrees can share the same index and object database, so changes in one worktree affect the repository but not other worktrees' working directories.

When NOT to use

Avoid using worktrees for very large repositories with limited disk space, as multiple working directories can consume significant space. Instead, use lightweight branching or shallow clones. Also, do not remove worktrees if you have uncommitted changes you want to keep; commit or stash first.

Production Patterns

In professional environments, worktrees are used to test multiple features or bug fixes simultaneously. Teams automate worktree creation and removal in CI pipelines to isolate builds. Removing worktrees is scripted to clean up after tests, ensuring no leftover folders clutter build agents.

Connections

Containerization (Docker)

Both manage isolated environments for work but at different layers (code vs system).

Understanding worktrees helps grasp how isolated environments work in software, similar to how containers isolate applications.

Filesystem Links (Symbolic Links)

Worktrees use filesystem links to share repository data across folders.

Knowing how symbolic links work clarifies how Git efficiently manages multiple worktrees without duplicating data.

Project Management (Kanban Boards)

Worktrees enable parallel task work similar to how Kanban boards visualize multiple tasks progressing independently.

Seeing worktrees as physical task spaces helps understand managing multiple development streams simultaneously.

Common Pitfalls

#1 Deleting the worktree folder manually without unregistering it from Git.

Wrong approach:

rm -rf ../feature-branch

Correct approach:

git worktree remove ../feature-branch

Root cause:

Misunderstanding that Git tracks worktrees internally and requires unregistering to avoid errors.

#2 Trying to remove a worktree with uncommitted changes without handling them first.

Wrong approach:

git worktree remove ../feature-branch

Correct approach:

git -C ../feature-branch add . && git commit -m 'Save work' or git stash
then git worktree remove ../feature-branch

Root cause:

Not realizing Git blocks removal to protect uncommitted work.

#3 Forcing removal of a worktree without understanding consequences.

Wrong approach:

git worktree remove --force ../feature-branch

Correct approach:

Commit or stash changes before removal to avoid data loss; use --force only when sure.

Root cause:

Ignoring Git's safety mechanisms due to impatience or lack of knowledge.

Key Takeaways

Git worktrees let you work on multiple branches in separate folders without switching branches in one place.

Removing a worktree deletes its folder and unregisters it from Git but does not delete the branch or repository data.

Always use 'git worktree remove' to cleanly remove worktrees; manual folder deletion causes Git errors.

Git prevents removing worktrees with uncommitted changes unless forced, protecting your work from accidental loss.

Understanding worktree removal helps maintain a clean, efficient workspace and prevents repository confusion.