Listing worktrees in Git - Deep Dive

Overview - Listing worktrees

What is it?

Listing worktrees means showing all the separate working directories linked to a single Git repository. Each worktree is like a separate workspace where you can work on different branches or commits without switching in the main folder. This helps you manage multiple tasks or features in parallel easily. The command to list worktrees shows their paths and the branches they are connected to.

Why it matters

Without the ability to list worktrees, it would be hard to keep track of multiple working directories tied to the same project. Developers might get confused about which worktree is for which branch or task, leading to mistakes like editing the wrong code. Listing worktrees helps organize work clearly and avoid costly errors in code management.

Where it fits

Before learning to list worktrees, you should understand basic Git concepts like repositories, branches, and commits. Knowing how to create and use worktrees is helpful too. After mastering listing worktrees, you can explore advanced Git workflows, multi-branch development, and automation scripts that manage multiple worktrees.

Mental Model

Core Idea

Listing worktrees shows all active separate workspaces connected to one Git repository, helping you see where and what you are working on simultaneously.

Think of it like...

Imagine a toolbox with several drawers, each drawer holding tools for a specific job. Listing worktrees is like opening the toolbox and seeing all the drawers and what tools they contain, so you know exactly where to find what you need.

┌───────────────────────────────┐
│          Git Repository        │
├───────────────┬───────────────┤
│ Worktree Path │ Branch Name   │
├───────────────┼───────────────┤
│ /path/to/wt1  │ feature/login │
│ /path/to/wt2  │ bugfix/issue  │
│ /path/to/wt3  │ main          │
└───────────────┴───────────────┘

Build-Up - 6 Steps

1

Foundation

Understanding Git Worktrees Basics

Concept: Learn what a Git worktree is and why it exists.

A Git worktree is an additional working directory linked to the same Git repository. It allows you to check out different branches or commits in separate folders without switching branches in your main folder. This helps you work on multiple features or fixes at the same time.

Result

You understand that worktrees are separate folders connected to one Git repo, each with its own branch checked out.

Knowing that worktrees let you have multiple active workspaces avoids the confusion of switching branches repeatedly.

2

Foundation

Creating and Using Worktrees

Concept: Learn how to create a new worktree and switch branches in it.

Use the command 'git worktree add ' to create a new worktree folder at with the specified branch checked out. This folder acts like a separate workspace for that branch.

Result

A new folder appears with the branch checked out, ready for independent work.

Creating worktrees helps you isolate work on different branches without interfering with your main folder.

3

Intermediate

Listing All Worktrees

🤔Before reading on: do you think 'git worktree list' shows only paths, or both paths and branches? Commit to your answer.

Concept: Learn the command to list all active worktrees and what information it shows.

Run 'git worktree list' in your repository. It outputs each worktree's path, the branch or commit checked out there, and if the worktree is locked or not.

Result

You see a list of all worktrees with their folder paths and branch names.

Listing worktrees gives you a clear overview of all active workspaces, preventing confusion about where you are working.

4

Intermediate

Interpreting Worktree List Output

🤔Before reading on: do you think a locked worktree means you can still delete it safely? Commit to your answer.

Concept: Understand the meaning of each part of the 'git worktree list' output, including locked status.

The output shows lines like '/path/to/wt1 123abc [branch-name]'. If a worktree is locked, it means Git prevents its removal because it might be in use or important. Locked worktrees usually appear with a 'locked' label.

Result

You can tell which worktrees are active, which branch they track, and which are locked.

Knowing the locked status helps avoid accidentally deleting important worktrees.

5

Advanced

Managing Worktrees in Scripts

🤔Before reading on: do you think 'git worktree list' output is easy to parse in scripts? Commit to your answer.

Concept: Learn how to use the worktree list command output in automation or scripts.

The 'git worktree list' output is plain text with paths and branch info. You can parse it with shell commands or scripts to automate tasks like cleaning unused worktrees or reporting active branches.

Result

Scripts can programmatically read and act on worktree information.

Understanding the output format enables automation, saving time and reducing manual errors.

6

Expert

Hidden Worktrees and Edge Cases

🤔Before reading on: do you think all worktrees are always listed by 'git worktree list'? Commit to your answer.

Concept: Discover that some worktrees might not appear in the list if they are corrupted or manually removed, and how Git tracks worktrees internally.

Git stores worktree info in the .git/worktrees folder. If a worktree folder is deleted manually without using Git commands, it may still appear in the list but cause errors. Also, detached HEAD worktrees show commit hashes instead of branch names.

Result

You learn to recognize and fix inconsistencies in worktree listings.

Knowing Git's internal tracking prevents confusion and helps maintain repository health.

Under the Hood

Git keeps a special folder inside the main repository called .git/worktrees. Each worktree has a subfolder there storing metadata like the branch or commit it tracks and its path. When you run 'git worktree list', Git reads these metadata files and outputs the current state of all worktrees. Locked worktrees have a lock file to prevent accidental removal. Detached HEAD worktrees show commit hashes because they are not on a branch.

Why designed this way?

Git worktrees were designed to allow multiple working directories without duplicating the entire repository data. Storing metadata in .git/worktrees keeps the main repo clean and lets Git manage worktrees efficiently. Locking prevents accidental deletion of active worktrees, protecting work in progress. This design balances flexibility with safety.

┌───────────────────────────────┐
│        .git Folder            │
│ ┌───────────────┐             │
│ │ worktrees/    │             │
│ │ ┌───────────┐ │             │
│ │ │ wt1/      │ │             │
│ │ │ metadata  │ │             │
│ │ └───────────┘ │             │
│ │ ┌───────────┐ │             │
│ │ │ wt2/      │ │             │
│ │ │ metadata  │ │             │
│ │ └───────────┘ │             │
│ └───────────────┘             │
└───────────────────────────────┘

Command 'git worktree list' reads these metadata files to show worktree info.

Myth Busters - 4 Common Misconceptions

Quick: Does 'git worktree list' show worktrees that were deleted manually? Commit yes or no.

Common Belief: People often think 'git worktree list' only shows existing, valid worktrees.

Reality: It can show worktrees that no longer exist on disk if they were deleted manually without Git commands.

Why it matters: This can cause confusion and errors when Git tries to access missing worktrees, leading to broken workflows.

Quick: Is a locked worktree safe to delete? Commit yes or no.

Common Belief: Some believe locked worktrees are safe to remove anytime.

Reality: Locked worktrees are protected by Git to prevent accidental deletion because they may be in use or important.

Why it matters: Deleting locked worktrees can cause data loss or corrupt your repository state.

Quick: Does 'git worktree list' show only branches or also commits? Commit your answer.

Common Belief: Many think it only lists branches checked out in worktrees.

Reality: It also shows detached HEAD worktrees by displaying commit hashes instead of branch names.

Why it matters: Not knowing this can confuse users about what exactly is checked out in a worktree.

Quick: Does creating a worktree duplicate the entire repository data? Commit yes or no.

Common Belief: Some assume each worktree is a full copy of the repository.

Reality: Worktrees share the same Git data; only working directories are separate, saving disk space.

Why it matters: Misunderstanding this leads to unnecessary disk usage concerns and inefficient workflows.

Expert Zone

1

Worktrees can track commits directly (detached HEAD), which is useful for testing but can cause confusion if not tracked carefully.

2

Git does not automatically prune stale worktree metadata; manual cleanup is sometimes needed to keep the repo tidy.

3

Lock files prevent removal but do not stop editing files in a worktree, so data safety depends on user discipline.

When NOT to use

Avoid using worktrees when you need completely isolated repositories with separate histories or remotes. In such cases, cloning the repository is better. Also, for very large monorepos with complex dependencies, worktrees might complicate build systems.

Production Patterns

In professional teams, worktrees are used to test multiple features simultaneously, run parallel CI jobs on different branches, and isolate hotfixes without disturbing main development. Automation scripts often parse 'git worktree list' to clean up old worktrees or generate reports.

Connections

Branching in Git

Worktrees build on branching by allowing multiple branches to be checked out simultaneously in separate folders.

Understanding worktrees deepens your grasp of branching by showing how branches can coexist physically, not just logically.

Virtual Machines

Worktrees are like lightweight virtual machines sharing the same base system but running different tasks independently.

This connection helps appreciate how worktrees save resources by sharing data while isolating workspaces.

Project Management Kanban Boards

Listing worktrees is similar to viewing all active tasks on a Kanban board to track progress and status.

Seeing all worktrees at once helps manage parallel work streams just like a board helps manage tasks.

Common Pitfalls

#1 Deleting a worktree folder manually without using Git commands.

Wrong approach:

rm -rf /path/to/worktree

Correct approach:

git worktree remove /path/to/worktree

Root cause:

Not knowing Git tracks worktrees internally, so manual deletion leaves stale metadata causing errors.

#2 Ignoring locked status and forcing removal of a worktree.

Wrong approach:

git worktree remove /path/to/locked_worktree --force

Correct approach:

First unlock or finish work in the worktree before removing it safely.

Root cause:

Misunderstanding that locked worktrees protect important or in-use workspaces.

#3 Assuming 'git worktree list' output is always up-to-date without verifying disk state.

Wrong approach:

Relying solely on 'git worktree list' without checking if folders exist.

Correct approach:

Verify worktree folders exist on disk and clean stale entries manually if needed.

Root cause:

Believing Git automatically syncs metadata with filesystem changes.

Key Takeaways

Git worktrees let you have multiple working directories linked to one repository, each with its own branch or commit checked out.

The 'git worktree list' command shows all active worktrees with their paths, branches, and locked status, helping you manage parallel work.

Worktrees share Git data internally, so they save disk space compared to full clones but require careful management to avoid stale metadata.

Locked worktrees protect important workspaces from accidental removal, so always check their status before deleting.

Understanding how Git tracks worktrees internally helps prevent errors and enables automation for efficient multi-branch development.