Why worktrees enable parallel work in Git - Why It Works This Way

Overview - Why worktrees enable parallel work

What is it?

Git worktrees allow you to have multiple working directories linked to the same repository. Each worktree can be on a different branch or commit, letting you work on several tasks at once without switching branches in a single folder. This means you can edit, build, and test different versions of your project side by side.

Why it matters

Without worktrees, developers must constantly switch branches in one folder, which can be slow and risky if changes are not committed. Worktrees solve this by enabling parallel work on multiple branches, improving productivity and reducing errors. This is especially helpful in teams or when juggling multiple features or fixes simultaneously.

Where it fits

Before learning about worktrees, you should understand basic Git concepts like repositories, branches, and commits. After mastering worktrees, you can explore advanced Git workflows, continuous integration setups, and multi-branch development strategies.

Mental Model

Core Idea

Git worktrees let you have multiple independent folders for different branches from the same repository, enabling parallel work without switching contexts.

Think of it like...

Imagine a kitchen with one stove and one cooking pot. Normally, you can cook only one dish at a time. Worktrees are like having multiple stoves and pots, so you can cook several dishes simultaneously without waiting or cleaning between recipes.

MainRepo
├── Worktree1 (branch A)
├── Worktree2 (branch B)
└── Worktree3 (branch C)

Each worktree is a separate folder linked to the same .git data, allowing independent edits.

Build-Up - 7 Steps

1

Foundation

Understanding Git branches and working directory

Concept: Learn what a Git branch is and how the working directory reflects the current branch's files.

A Git branch is a pointer to a commit. Your working directory shows the files from the branch you have checked out. When you switch branches, Git replaces the files in your folder to match the new branch's snapshot.

Result

You can only work on one branch at a time in a single folder.

Knowing that your working directory is tied to one branch explains why switching branches can interrupt your work.

2

Foundation

Limitations of single working directory

Concept: Explore why working on multiple branches in one folder is difficult and risky.

If you want to work on two features, you must switch branches back and forth. This can cause lost changes or conflicts if you forget to commit. Also, switching branches takes time and interrupts your flow.

Result

Working on multiple tasks simultaneously in one folder is inefficient and error-prone.

Understanding these limits motivates the need for a better way to handle parallel work.

3

Intermediate

Introducing Git worktrees

Concept: Learn that Git worktrees allow multiple working directories linked to one repository.

Git worktrees create new folders connected to the same .git data but checked out to different branches or commits. You can edit files in each folder independently without switching branches in one place.

Result

You can have multiple branches checked out at once in separate folders.

Realizing that worktrees share repository data but have separate working directories unlocks parallel development.

4

Intermediate

Creating and managing worktrees

🤔Before reading on: do you think creating a worktree copies the entire repository or just links to existing data? Commit to your answer.

Concept: Understand how to create and remove worktrees efficiently.

Use 'git worktree add ' to create a new worktree folder for a branch. This does not duplicate the whole repository but links to the existing Git data. Use 'git worktree remove ' to delete a worktree safely.

Result

You have multiple folders with different branches ready for independent work.

Knowing that worktrees avoid data duplication saves disk space and speeds up setup.

5

Intermediate

Parallel workflows with worktrees

🤔Before reading on: do you think changes in one worktree affect other worktrees immediately? Commit to your answer.

Concept: Explore how worktrees enable simultaneous development on different branches without interference.

Each worktree has its own working directory and index, so changes in one do not affect others until you commit and push. This allows testing, building, or debugging multiple features side by side.

Result

You can develop and test multiple features or fixes in parallel safely.

Understanding isolation between worktrees prevents accidental overwrites and merges.

6

Advanced

Internal Git data sharing in worktrees

🤔Before reading on: do you think each worktree has a full copy of the .git folder? Commit to your answer.

Concept: Learn how worktrees share Git data internally to save space and maintain consistency.

Worktrees share the main repository's .git folder but have a small .git file pointing back to it. This means all branches and history are shared, but working directories are separate. Git manages this with a worktrees folder inside .git to track them.

Result

Worktrees are lightweight and efficient, sharing data but allowing separate work.

Knowing this internal sharing explains why worktrees are fast and space-saving.

7

Expert

Handling conflicts and edge cases with worktrees

🤔Before reading on: can two worktrees check out the same branch simultaneously? Commit to your answer.

Concept: Understand limitations and best practices to avoid conflicts when using worktrees.

Git prevents checking out the same branch in multiple worktrees to avoid conflicts. You must create separate branches or use detached HEAD states. Also, deleting worktrees improperly can leave stale references, so use Git commands to clean up.

Result

You avoid branch conflicts and keep repository state clean when using worktrees.

Knowing these rules prevents common errors and keeps parallel work stable.

Under the Hood

Git worktrees work by creating additional working directories linked to the same Git repository data. Instead of duplicating the entire .git folder, each worktree has a small pointer file that references the main repository's .git directory. Git tracks these worktrees internally in a special folder, managing their branches and states separately. This allows multiple branches to be checked out simultaneously in different folders, sharing the same object database and history but with isolated working files and indexes.

Why designed this way?

Worktrees were designed to solve the problem of slow and risky branch switching in a single working directory. By sharing the repository data, Git avoids wasting disk space and keeps history consistent. The design balances efficiency with isolation, allowing parallel work without duplicating data. Alternatives like cloning the repository multiple times waste space and complicate synchronization, so worktrees provide a lightweight, integrated solution.

┌─────────────┐
│ Main .git   │
│ Repository  │
└─────┬───────┘
      │
      │
┌─────▼───────┐      ┌───────────────┐      ┌───────────────┐
│ Worktree 1  │      │ Worktree 2    │      │ Worktree 3    │
│ (branch A) │      │ (branch B)    │      │ (branch C)    │
│ .git file ├──────▶│ .git file     │      │ .git file     │
└────────────┘      └───────────────┘      └───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think worktrees duplicate the entire repository data? Commit to yes or no before reading on.

Common Belief: Worktrees create full copies of the repository, so they use a lot of disk space.

Reality: Worktrees share the main repository's data and only create separate working directories, saving disk space.

Why it matters: Believing worktrees duplicate data may discourage their use, leading to inefficient workflows and wasted storage.

Quick: Can you check out the same branch in two different worktrees at the same time? Commit yes or no.

Common Belief: You can have the same branch checked out in multiple worktrees simultaneously.

Reality: Git prevents checking out the same branch in multiple worktrees to avoid conflicts.

Why it matters: Trying to do this causes errors and confusion, disrupting parallel work.

Quick: Do changes in one worktree automatically appear in others? Commit your answer.

Common Belief: Changes made in one worktree instantly affect all other worktrees.

Reality: Each worktree has its own working directory and index; changes are isolated until committed and pushed.

Why it matters: Misunderstanding this can cause fear of using worktrees or accidental overwrites.

Quick: Is deleting a worktree folder like deleting any folder? Commit yes or no.

Common Belief: You can delete a worktree folder by just removing it from the file system.

Reality: You must use Git commands to remove worktrees properly; otherwise, stale references remain.

Why it matters: Improper deletion leads to repository confusion and errors in Git operations.

Expert Zone

1

Worktrees share the object database but maintain separate index and HEAD files, allowing independent staging and commits.

2

Detached HEAD states in worktrees enable quick experiments without creating branches, but require careful cleanup.

3

Git tracks worktrees internally in .git/worktrees, and manual edits here can corrupt repository state.

When NOT to use

Avoid worktrees when you need completely isolated repositories with different remotes or configurations; in such cases, cloning is better. Also, for very large repositories with heavy disk I/O, multiple clones may perform better than many worktrees.

Production Patterns

Teams use worktrees to test multiple features or bug fixes simultaneously on CI servers. Developers keep long-lived worktrees for major features to avoid branch switching. Worktrees also help in code reviews by checking out pull request branches side by side.

Connections

Containerization (Docker)

Both enable isolated environments sharing common resources.

Understanding how worktrees share Git data but isolate working files is similar to how containers share the host OS kernel but isolate applications.

Multitasking in Operating Systems

Worktrees enable parallel work like multitasking allows multiple processes to run independently.

Seeing worktrees as parallel tasks helps grasp how independent workspaces improve productivity without interference.

Version Control Branching

Worktrees build on branching by providing physical folders for each branch.

Knowing branching basics clarifies why worktrees are a natural extension for parallel development.

Common Pitfalls

#1 Deleting a worktree folder manually without Git commands.

Wrong approach:

rm -rf path/to/worktree

Correct approach:

git worktree remove path/to/worktree

Root cause:

Misunderstanding that Git tracks worktrees internally and manual deletion leaves stale references.

#2 Trying to check out the same branch in two worktrees.

Wrong approach:

git worktree add ../wt2 master
# Then again
git worktree add ../wt3 master

Correct approach:

git worktree add ../wt2 master
# For second worktree, create a new branch
git worktree add ../wt3 feature-branch

Root cause:

Not knowing Git restricts multiple worktrees on the same branch to prevent conflicts.

#3 Assuming changes in one worktree auto-update others.

Wrong approach:

Editing files in one worktree and expecting them to appear in another without commit or checkout.

Correct approach:

Commit changes in one worktree, then pull or checkout in another to see updates.

Root cause:

Confusing shared repository data with isolated working directories.

Key Takeaways

Git worktrees let you work on multiple branches at the same time in separate folders without switching branches.

They share the same repository data, saving disk space and keeping history consistent.

Worktrees isolate changes in each folder, preventing accidental overwrites and enabling parallel development.

Git restricts checking out the same branch in multiple worktrees to avoid conflicts.

Proper management of worktrees with Git commands prevents stale references and repository errors.

Practice

1. What is the main benefit of using git worktree for parallel work?

easy

A. It deletes old branches to save space.

B. It automatically merges branches without conflicts.

C. It allows working on multiple branches simultaneously in separate folders.

D. It creates a backup of the entire repository.

Solution

1. Step 1: Understand what git worktree does

   git worktree lets you check out multiple branches at once in different folders without cloning the repo multiple times.

2. Step 2: Compare options with this feature

   Only It allows working on multiple branches simultaneously in separate folders. correctly describes this benefit. Other options describe unrelated or incorrect features.

3. Final Answer:

   It allows working on multiple branches simultaneously in separate folders. -> Option C

4. Quick Check:

   Parallel branch work = It allows working on multiple branches simultaneously in separate folders. [OK]

Hint: Worktrees = multiple branches in separate folders [OK]

Common Mistakes:

• Thinking worktrees merge branches automatically
• Confusing worktrees with backups
• Assuming worktrees delete branches

2. Which command correctly creates a new worktree for branch feature in folder ../feature?

easy

A. git worktree create feature ../feature

B. git worktree add ../feature feature

C. git add worktree ../feature feature

D. git checkout worktree feature ../feature

Solution

1. Step 1: Recall correct syntax for adding a worktree

   The correct syntax is git worktree add <path> <branch>.

2. Step 2: Match options to syntax

   Only git worktree add ../feature feature matches this syntax exactly. Others use wrong commands or order.

3. Final Answer:

   git worktree add ../feature feature -> Option B

4. Quick Check:

   Correct add syntax = git worktree add ../feature feature [OK]

Hint: Use 'git worktree add <path> <branch>' to create worktree [OK]

Common Mistakes:

• Using 'create' instead of 'add'
• Mixing order of arguments
• Using 'git add' or 'git checkout' incorrectly

3. Given these commands executed in a repo:

git worktree add ../feature feature
cd ../feature
git status

What will git status show in the ../feature folder?

medium

A. On branch master, with changes from master branch.

B. Error: not a git repository.

C. Detached HEAD state with no branch.

D. On branch feature, with changes from that branch.

Solution

1. Step 1: Understand what git worktree add ../feature feature does

   This creates a new folder ../feature checked out to the feature branch.

2. Step 2: Check git status in that folder

   Since the folder is a valid worktree on feature branch, git status shows branch feature and its changes.

3. Final Answer:

   On branch feature, with changes from that branch. -> Option D

4. Quick Check:

   Worktree folder branch = feature [OK]

Hint: Worktree folder tracks specified branch, not master [OK]

Common Mistakes:

• Assuming worktree defaults to master branch
• Thinking worktree folder is detached HEAD
• Confusing worktree folder with unrelated repo

4. You ran git worktree add ../dev feature but got an error: fatal: 'feature' is not a commit and a branch 'feature' cannot be created from it. What is the likely cause?

medium

A. The branch 'feature' does not exist in the repo.

B. The folder '../dev' already contains a git repo.

C. You forgot to commit changes before adding worktree.

D. You used 'git worktree create' instead of 'add'.

Solution

1. Step 1: Analyze the error message

   The error says 'feature' is not a commit and branch cannot be created, meaning the branch does not exist.

2. Step 2: Match cause to options

   The branch 'feature' does not exist in the repo. matches this cause. Other options describe unrelated issues or wrong commands.

3. Final Answer:

   The branch 'feature' does not exist in the repo. -> Option A

4. Quick Check:

   Branch must exist before adding worktree [OK]

Hint: Check branch exists before adding worktree [OK]

Common Mistakes:

• Assuming folder conflict causes this error
• Thinking uncommitted changes block worktree add
• Confusing 'add' with 'create' command

5. You want to work on two features in parallel without cloning the repo twice. You create two worktrees:

git worktree add ../feature1 feature1
git worktree add ../feature2 feature2

What is a key advantage of this approach compared to cloning twice?

hard

A. It saves disk space by sharing the same .git data.

B. It automatically syncs changes between branches.

C. It prevents any merge conflicts between branches.

D. It allows pushing both branches with one command.

Solution

1. Step 1: Understand difference between worktrees and cloning

   Worktrees share the same repository data (.git) but have separate working folders, saving disk space.

2. Step 2: Evaluate options

   It saves disk space by sharing the same .git data. correctly states the disk space saving. Other options describe features not provided by worktrees.

3. Final Answer:

   It saves disk space by sharing the same .git data. -> Option A

4. Quick Check:

   Worktrees share repo data, saving space [OK]

Hint: Worktrees share .git data, saving space vs cloning [OK]

Common Mistakes:

• Thinking worktrees auto-sync branches
• Assuming worktrees prevent merge conflicts
• Believing one push updates multiple branches