Git Worktree Merge: How to Merge Worktree Changes into Main

Branches in a git worktree are regular Git branches. Merging works exactly the same way it does with any other branch — the only difference is that you may already have both the source and target branches checked out in separate directories.

Quick Steps: Merge a Worktree Branch into Main

If you just need the commands, here is the fastest path:

Merge worktree into main — 5 steps

# 1. Go to the worktree that has main checked out
cd ../your-project

# 2. Make sure main is up to date
git pull origin main

# 3. Merge the worktree branch
git merge feat/your-feature

# 4. Push
git push origin main

# 5. Clean up the worktree and branch
git worktree remove ../your-project-feat
git branch -d feat/your-feature

Read on for detailed explanations, alternative methods (PR, rebase), and troubleshooting.

Try It: Merging a Worktree Branch Back to Main

Merge, push, remove worktree, delete branch — the full post-hotfix workflow

The SetupReady to Merge

You've fixed the checkout crash in the acme-hotfix worktree and pushed the branch. Now it's time to merge hotfix/checkout-crash back into main. With worktrees, both branches are checked out in separate directories — you can reference the hotfix code while merging.

~/code/

2 directories, 1 shared .git

├── acme/ [feature/payments]
│   ├── .git/  full git database
│   ├── src/
│   ├── package.json
│   └── README.md
└── acme-hotfix/ [hotfix/checkout-crash]← you are here
    ├── .git  → ../acme/.git (linked)
    ├── src/
    ├── package.json
    └── README.md

acme/ has the real .git/ directory. acme-hotfix/ has a tiny .git file that points back — no duplicate history, no wasted disk.

Understanding the Workflow

When you create a worktree with a feature branch, any commits you make in that worktree are visible from every other worktree because they all share the same Git object database. This means you do not need to push or transfer changes before merging — the commits are already present in the repository.

Commits are shared across worktrees

# In worktree ../acme-hotfix, you've committed changes
cd ../acme-hotfix
git log --oneline -2
# 7a8b9c0 fix: null check on cart total
# e4f5a6b Deploy v2.3.1

# These commits are already visible from your main worktree
cd ../acme
git log --oneline hotfix/checkout-crash -2
# 7a8b9c0 fix: null check on cart total
# e4f5a6b Deploy v2.3.1

Method 1: Merge from the Main Worktree

The most straightforward approach is to switch to the worktree that has your target branch (usually main) checked out and merge the feature branch:

Merge from the main worktree

# Navigate to the main worktree
cd ../acme

# Make sure main is up to date
git pull origin main

# Merge the feature branch
git merge hotfix/checkout-crash

# Push the result
git push origin main

If there are conflicts, resolve them in the main worktree as you normally would. You can even open the feature worktree side by side in another editor window to reference the original code while resolving conflicts.

Method 2: Create a Pull Request

For team workflows, creating a pull request is usually preferred over a direct merge. Push the feature branch from any worktree and open a PR on your hosting platform:

Push and create a pull request

# From the hotfix worktree, push the branch
cd ../acme-hotfix
git push -u origin hotfix/checkout-crash

# Create a PR using the GitHub CLI (or your platform's tool)
gh pr create --base main --head hotfix/checkout-crash \
  --title "fix: null check on cart total" \
  --body "Fixes checkout crash when cart total is null."

After the PR is reviewed and merged on the remote, pull the changes into your local main worktree:

Pull merged changes

cd ../acme
git pull origin main

Method 3: Rebase Then Merge

If you prefer a linear history, rebase the feature branch onto main before merging. This is done in the feature worktree:

Rebase then fast-forward merge

# In the feature worktree, rebase onto main
cd ../acme-hotfix
git fetch origin
git rebase origin/main

# Resolve any conflicts during rebase, then continue
# git rebase --continue

# Switch to the main worktree and fast-forward merge
cd ../acme
git merge hotfix/checkout-crash
# This will be a fast-forward merge since we rebased

Tip: One advantage of worktrees is that you can rebase in the feature worktree while your main worktree remains untouched. If the rebase goes wrong, your main working directory is unaffected.

Cleaning Up After Merge

After merging, you should remove the worktree and optionally delete the branch:

Full cleanup after merge

# Remove the worktree directory and administrative data
git worktree remove ../acme-hotfix

# Delete the local branch (it's been merged, so -d is safe)
git branch -d hotfix/checkout-crash

# Delete the remote branch if no longer needed
git push origin --delete hotfix/checkout-crash

If you skip git worktree remove and delete the directory manually, remember to run git worktree prune to clean up the stale metadata.

Common Issues

"Cannot merge: you have unmerged files"

Make sure you have committed or stashed all changes in the target worktree before merging. Each worktree has its own working directory and index, so uncommitted changes in the main worktree will block the merge:

Stash before merging

cd ../acme
git stash          # Save uncommitted work
git merge hotfix/checkout-crash
git stash pop      # Restore your work

"Cannot delete branch checked out in another worktree"

You must remove the worktree before deleting the branch. If you already deleted the worktree directory manually, prune first:

Fix branch deletion errors

# If the worktree still exists, remove it properly
git worktree remove ../acme-hotfix

# If you deleted the directory manually, prune the stale entry
git worktree prune

# Now the branch can be deleted
git branch -d hotfix/checkout-crash