Merge Worktree Branch into Main
Follow these steps to merge a parallel-development worktree branch back into main.
Step 1: Preflight checks
- Ensure we are not already on main
- Ensure all changes are already committed. If not, you can automatically commit them
Step 2: Merge the branch to main
If the merge succeeds with no conflicts
Proceed to Step 3.
If there are merge conflicts
- Run
git diff --name-only --diff-filter=Uto list conflicted files. - Tell the user which files have conflicts.
- For each conflicted file:
- Read the file to understand the conflict markers (
<<<<<<<,=======,>>>>>>>) - Analyze both sides of each conflict and resolve it intelligently, preserving the intent of both changes where possible
- Edit the file to remove all conflict markers with the correct resolution
- Read the file to understand the conflict markers (
- After resolving all files, stage them:
git add <resolved files> - Complete the merge:
git commit --no-edit - Tell the user what resolutions were made.
Step 3: Rebuild native utilities if changed
After merging, check if the merged branch touched any native utility source code. Use the merge commit's two parents to see what the branch changed:
git diff HEAD^1 HEAD --name-only -- app/runtime/native/If any files under app/runtime/native/ were changed, recompile the Rust binaries
by running ./prepare from the repo root. This is critical because worktree
builds don't carry over to main — the release binaries in target/release/
are local to each worktree checkout.
./prepareIf no native utility files were changed, skip this step.
Step 4: Run the checks
Run the check suite from the repo root:
./quickcheckThen run the end-to-end test suite using the "e2e" skill.
If checks pass
Proceed to Step 5.
If checks fail
- Read the check output carefully to identify what failed.
- Investigate the failing code — read the relevant files and understand the issue.
- Fix the problem.
- Stage the fix and commit it with the prefix
merge fix:in the commit message. For example:merge fix: update import paths after merge - Run
./quickcheck --fullagain. - If it still fails, repeat this fix cycle up to 3 times. If checks still fail after 3 attempts, stop and tell the user:
"Checks are still failing after 3 fix attempts. Manual intervention needed." Show the remaining failure output so the user can debug.
Step 5: Summary
Print a summary:
- Branch that was merged
- Whether there were conflicts (and how they were resolved)
- Whether any post-merge fixes were needed (list the fix commits)
- Final check status
- Remind the user they can delete the worktree branch if it's no longer needed:
git branch -d <branch> git worktree remove <path> # if the worktree directory still exists