Git Worktrees, Branches, and Parallel Sessions

This is a generic explanation of how Git worktrees relate to branches and how multiple sessions eventually combine their changes.

The Three Separate Concepts

There are three different things involved:

1. Repository

The repository is the Git project itself:

• commit history
• branches
• tags
• metadata in .git

This is the shared source of truth.

2. Branch

A branch is a named pointer to a commit.

Examples:

• main
• feature-ui
• feature-api

A branch is not a folder. It is a reference in Git history.

3. Worktree

A worktree is a directory on disk containing checked-out files from the repository.

This is the folder you actually open in your editor and modify.

Examples:

• /projects/repo
• /projects/repo-ui
• /projects/repo-api

A worktree is not a branch. It is a filesystem directory.

The Relationship Between Them

The source of confusion is that a worktree usually has one branch checked out inside it.

That means people often talk like this:

• “the UI worktree”
• “the feature-ui branch”

In practice, they are closely associated, but they are still different:

• the branch is the line of history
• the worktree is the folder using that line of history

Without Worktrees

Normally, a repository has one working directory:

/projects/repo

If that directory has main checked out, and you want to work on feature-ui, you switch branches in the same folder:

git checkout feature-ui

That creates a problem for parallel sessions:

• one folder can only have one checkout at a time
• uncommitted changes in one task interfere with another
• two terminals in the same folder are still sharing the same checkout

With Worktrees

Worktrees let the same repository have multiple working directories at once.

Example:

git worktree add ../repo-ui -b feature-ui
git worktree add ../repo-api -b feature-api

Now you might have:

/projects/repo       -> worktree folder
/projects/repo-ui    -> worktree folder
/projects/repo-api   -> worktree folder

And the current checkouts might be:

• /projects/repo has main checked out
• /projects/repo-ui has feature-ui checked out
• /projects/repo-api has feature-api checked out

All of these folders still belong to the same repository.

What git worktree add Actually Does

When you run:

git worktree add ../repo-ui -b feature-ui

Git does several things:

1. Creates a new directory at ../repo-ui
2. Creates a new branch named feature-ui
3. Checks that branch out in the new directory
4. Connects that directory to the same repository history

That is why worktrees and branches often appear fused in examples. One command commonly creates both at once.

But they are still separate:

• you can talk about the branch by itself
• you can talk about the worktree folder by itself

A Concrete Mental Model

Think of it like this:

• repository = the library
• branch = one storyline or draft version
• worktree = a desk where one draft is laid out for editing

You can have multiple desks open at once, each with a different draft, but the library behind them is the same.

What Multiple Sessions Actually Look Like

Imagine three terminals:

Terminal A

cd /projects/repo
git branch --show-current
# main

Terminal B

cd /projects/repo-ui
git branch --show-current
# feature-ui

Terminal C

cd /projects/repo-api
git branch --show-current
# feature-api

Each terminal is working in a different folder.

That is the important part.

The isolation comes from separate worktree directories, not from magic coordination between sessions.

What git worktree list Means

This command:

git worktree list

might show:

/projects/repo       abc1234 [main]
/projects/repo-ui    def5678 [feature-ui]
/projects/repo-api   9876fed [feature-api]

Read each line as:

• this folder is a worktree
• it currently points at this commit
• it currently has this branch checked out

Again:

• folder = worktree
• bracketed name = branch

How Work Gets Reconciled

Worktrees do not reconcile code.

They only prevent local checkout conflicts by giving each task its own folder.

Actual reconciliation happens later through normal Git operations:

• git merge
• git rebase
• git cherry-pick

The key point is this:

• worktrees isolate active editing
• commits preserve each session’s work
• Git history operations combine that work later

What “Reconcile” Actually Means

When people say work from two sessions must be “reconciled,” they usually mean one of these:

• both sets of commits need to end up on the same branch
• one branch must be updated to include another branch’s changes
• conflicts between overlapping edits must be resolved

This happens at the branch and commit level, not at the worktree level.

The worktree is only where the files live while you are editing them.

The Reconciliation Timeline

A realistic sequence looks like this:

1. Create separate worktrees
2. Each worktree checks out a different branch
3. Each session edits files in its own folder
4. Each session commits its changes to its own branch
5. Later, one branch is merged, rebased, or cherry-picked into another
6. If Git detects overlapping changes, a human resolves the conflict

That is the full lifecycle.

The worktree matters at steps 1 through 3. Git branch operations matter at steps 4 through 6.

Example: No Conflict Reconciliation

Suppose you start from main at commit A.

History:

A

You create two worktrees:

• /projects/repo-ui on branch feature-ui
• /projects/repo-api on branch feature-api

Session 1 makes a UI change and commits B. Session 2 makes an API change and commits C.

History now looks like:

      B  feature-ui
     /
A---+
     \
      C  feature-api

Later, from a worktree that has main checked out, you run:

git merge feature-ui
git merge feature-api

If the changes do not overlap in a conflicting way, Git can combine them cleanly:

      B  feature-ui
     / \
A---M---N  main
     \ /
      C  feature-api

You can think of this as:

• UI work happened in one worktree
• API work happened in another worktree
• reconciliation happened when both branches were merged into main

The worktrees were not merged. The branches were merged.

Example: Conflict Reconciliation

Now imagine both sessions changed the same logical area of the same file.

Session 1 in /projects/repo-ui changes:

src/app/page.tsx

Session 2 in /projects/repo-api also changes:

src/app/page.tsx

Because these are different worktree folders, both sessions can keep working without immediate interference.

That is useful, but it only delays the conflict until integration time.

History might look like:

      B  feature-ui
     /
A---+
     \
      C  feature-api

Now someone tries:

git checkout main
git merge feature-ui
git merge feature-api

Git may stop and report a merge conflict.

At that moment, Git is saying:

• both branches changed related lines
• Git cannot safely choose the final version alone
• a person must edit the file and decide the final combined content

That manual fix is the actual reconciliation.

Where the Conflict Is Resolved

The conflict is resolved in whichever worktree is performing the merge or rebase.

For example, if /projects/repo has main checked out and you run:

cd /projects/repo
git merge feature-api

then /projects/repo becomes the place where conflict markers appear in files.

The other worktrees do not automatically show that temporary merge state.

This matters because:

• worktree folders are separate checkouts
• the merge is happening in one specific checkout
• that checkout becomes the place where the human resolves conflicts

What Merge Conflict Resolution Looks Like

Suppose Git inserts conflict markers:

<<<<<<< HEAD
current version from main
=======
incoming version from feature-api
>>>>>>> feature-api

A human edits that file into the desired final form, then runs:

git add <file>
git commit

At that point, reconciliation is complete for that merge.

Rebase Reconciliation

Rebase reconciles work differently.

Instead of combining two branch tips with a merge commit, rebase replays one branch’s commits on top of another base.

Example:

cd /projects/repo-api
git rebase main

This means:

• take commits from feature-api
• pretend they were made starting from the current main
• replay them one by one

If a replayed commit conflicts, Git pauses and asks for resolution in that worktree.

Typical flow:

git rebase main
# resolve files
git add <file>
git rebase --continue

So with rebase:

• reconciliation still happens at integration time
• conflicts still require manual decisions
• the worktree running the rebase is where that process occurs

Cherry-Pick Reconciliation

Cherry-pick is the narrowest form of reconciliation.

Instead of combining whole branches, it applies selected commits onto another branch.

Example:

cd /projects/repo
git cherry-pick <commit-from-feature-ui>

This is useful when:

• only one commit from another session is needed
• you do not want the entire branch
• you want a very selective integration path

Cherry-pick can also produce conflicts, and they are resolved in the worktree performing the cherry-pick.

Why Separate Worktrees Still Help If Conflicts Happen Later

A common misunderstanding is:

• “If conflicts can still happen later, what did the worktree solve?”

It solved the active working-state problem.

Without worktrees:

• you constantly switch branches in one folder
• uncommitted work blocks switching
• one session can dirty the environment for another
• testing one branch can disturb another branch’s files

With worktrees:

• each branch has its own folder
• each session keeps its own uncommitted state
• each session can run independently
• integration is delayed until commits are ready

So worktrees reduce operational friction even though they do not eliminate merge conflicts.

What Happens to Other Worktrees After Reconciliation

Suppose /projects/repo merges feature-ui into main.

The /projects/repo-ui worktree does not magically disappear.

It still exists as a separate folder, still associated with its checked-out branch.

Depending on what you want, you might:

• keep that worktree for more work
• update it with git pull or git rebase main
• remove it if the task is finished

So reconciliation does not automatically clean up worktrees. It only changes branch history.

Important Rule: One Branch Cannot Be Checked Out in Two Worktrees at Once

Git prevents the same branch from being checked out simultaneously in multiple worktrees.

That rule exists because Git wants one checked-out branch to have one active working state.

This is part of how worktrees avoid confusion.

You can still:

• create multiple worktrees for the same repository
• use different branches in each worktree
• merge or rebase those branches later

But you do not normally have the same branch checked out in two active worktrees at once.

Shared Repository, Separate Working States

All worktrees share the same underlying repository data:

• object database
• refs
• commit history

But each worktree has its own:

• checked-out files
• HEAD
• index/staging state

That is why reconciliation is possible:

• all commits belong to the same repository
• Git can merge, rebase, or cherry-pick between them later

Operator Pack

Get the Git Worktrees Reconciliation Pack

Request the operator version of this guide: the setup checklist, merge-vs-rebase decision sheet, and a simple workflow you can hand to a team running parallel sessions.

• Worktree setup checklist for parallel feature work
• Merge vs rebase vs cherry-pick decision guide
• Conflict-resolution workflow for integration time
• Cleanup checklist for finished branches and worktrees

Work email

Website URL (optional)

Send me the pack Sending...

By requesting the pack, you agree to hear from us about this resource and related services. You can opt out anytime.