Merge Conflicts

Resolving merge conflicts

Determine the base branch first — don't assume main

Re-read git branch --show-current rather than trusting the branch from earlier in the session. Conductor runs sessions concurrently, so another one can check this worktree out onto a different branch and commit to it while your conversation is open — and the base you resolved for the branch you were on is then the wrong base, merged into work you haven't read.

"Update from base", "sync with main", "this branch is behind", "merge the base in" all need a base branch to merge from. Don't default to main. A branch is often stacked on another feature branch, and merging main instead silently pulls the wrong history — the diff looks "already up to date" against main while the real base has commits you're missing. Resolve the base in this order:

1. A branch the user names — "update from X" / "base is X" wins outright.
2. An open PR's base — gh pr view <branch> --json baseRefName. Also check the base of any feature branch you recently merged into this one (gh pr view <that-branch> --json baseRefName); a stack's branches usually share the same base.
3. The upstream tracking ref, if it names a branch other than this one's own remote mirror (git rev-parse --abbrev-ref @{u}).
4. The Conductor workspace target branch (from the workspace/system instructions) — a default hint, not the last word.

Re-resolve the base every time — it moves. When a base branch's PR merges, GitHub retargets the child PR (usually to main), so what you merged from last time may no longer be the base. Check gh pr view <branch> --json baseRefName, and gh pr list for whether the old base still has an open PR. A base whose PR has merged often keeps accumulating commits behind no PR at all; those aren't yours to integrate.

If 1–3 turn up nothing and the branch clearly builds on another feature branch — it was created by merging one in, was cut from main but layers work that lives on an unmerged branch, or the user talks about it as part of a stack — ask which branch to update from (offer the likely candidate) rather than merging main. Confirm before running the merge; a wrong base is expensive to unwind.

Bring a branch up to date

• git fetch origin, then git merge --no-edit origin/<base> (the base resolved above, not reflexively main).
• Read what the merge brought in from the merge itself, not from an earlier ahead/behind count — git log --oneline <pre-merge-HEAD>..<merge-commit>^2. Conductor worktrees share one .git, so refs/remotes/origin/* is shared too: another session's git fetch advances your base mid-conversation, and a count taken before the merge under-reports it. Telling the user "1 commit behind" and then merging 2 is how that surfaces.
• Merge, never rebase. Republishing a rebased branch needs a force-push, and we never force-push.
• If uncommitted work blocks the merge, commit that work first (it belongs to the branch anyway), then merge.
• Already up to date → nothing to do.

Base already merged? Merge its final commit before main

This repo squash-merges, so a merged base lands on main as one commit sharing no ancestry with the base's real commits. Merge main straight into the stacked branch and every file the base added comes back as an add/add conflict — git has no common ancestor to three-way merge against, so it hands you files you never touched.

Merge the base's tip first, then main:

gh pr view <base-pr> --json headRefOid --jq .headRefOid  # tip survives branch deletion
git fetch origin <sha>                                   # or refs/pull/<base-pr>/head
git merge --no-edit <sha>
git merge --no-edit origin/main

That makes your side byte-identical to what the squash put on main, so the add/add conflicts collapse and you're left only with files this branch actually changed.

The branch is usually deleted locally and on the remote by then, so don't look for origin/<base>; headRefOid and refs/pull/<n>/head are how you reach the commit.

Part of this branch already shipped as its own PR

Same cause the other way round: work split off this branch into its own PR lands on main as one squash commit, so every file both touched conflicts. main's side is the reviewed version of your own change — take it, then check that git diff origin/main lists only the work that PR left out.

Keep the merge commit to just the merge

A merge commit should contain only the reconciliation of the two histories — nothing else. Don't fold in lint fixes, refactors, renames, or "while I'm here" cleanups; buried inside a merge they're invisible in most diff views. Land them as separate commits after the merge.

Resolving conflicts

When git leaves <<<<<<< / ======= / >>>>>>> markers:

• Understand each side before choosing. The version on main and the version on the branch each exist for a reason. Read enough of both to know what each is trying to do — don't mechanically keep "ours" or "theirs." The correct resolution is often a combination, not one side wholesale.
• Consider the branch's purpose. What is this branch trying to accomplish? A conflict resolution that quietly drops the branch's intent (or reverts something main deliberately changed) is a bug, even if it compiles.
• Ask when it isn't clear-cut. If you can't confidently tell which side should win, or the two changes are semantically entangled, stop and ask the user rather than guessing. A wrong silent resolution is worse than a question.
• Both sides added at the same spot? Order matters. Keeping both isn't enough when either block has side effects. If the incoming block ends by reloading the page, anything of yours that depends on unsaved state has to come after it — concatenated the other way it still passes while testing nothing.
• Taking one side resolves the marked blocks, not the file. git checkout --ours/--theirs replaces the whole file, discarding the other side's hunks that merged cleanly around the conflict. Delete the unwanted half of each <<<<<<< block instead; git checkout -m -- <file> restores the markers if you already reached for it.
• Don't blanket-replace a renamed string. Two call sites that shared a string can have legitimately diverged; sed-ing the whole file changes the one that shouldn't move.
• A conflicted schema_migrations list takes both versions. Each side appended its own migration, so keep both lines in descending order — in db/structure.sql and db/primary_replica_structure.sql alike — then bin/rails db:migrate to re-dump. Never hand-edit the structure files.
• After resolving, verify the result actually makes sense — the merged code should reflect both intents, not just parse. Run the relevant tests if the conflict touched logic.