How to Merge Git Worktree Changes

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.

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 ../feature-auth, you've committed changes
cd ../feature-auth
git log --oneline -3
# a1b2c3d Add OAuth2 provider
# d4e5f6a Add login form validation
# 7890abc Create auth service skeleton

# These commits are already visible from your main worktree
cd ../project
git log --oneline feature/auth -3
# a1b2c3d Add OAuth2 provider
# d4e5f6a Add login form validation
# 7890abc Create auth service skeleton

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 ../project

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

# Merge the feature branch
git merge feature/auth

# 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 feature worktree, push the branch
cd ../feature-auth
git push -u origin feature/auth

# Create a PR using the GitHub CLI (or your platform's tool)
gh pr create --base main --head feature/auth \
  --title "Add OAuth2 authentication" \
  --body "Implements login, registration, and OAuth2 provider support."

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

Pull merged changes

cd ../project
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 ../feature-auth
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 ../project
git merge feature/auth
# 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 ../feature-auth

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

# Delete the remote branch if no longer needed
git push origin --delete feature/auth

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 ../project
git stash          # Save uncommitted work
git merge feature/auth
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 ../feature-auth

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

# Now the branch can be deleted
git branch -d feature/auth