mergemain

Merge the latest main into the current branch and resolve the conflicts correctly. The whole point is the conflict resolution: never resolve by picking a side because it is easier.

Step 1 — Pre-flight

git rev-parse --abbrev-ref HEAD          # current branch
git status --porcelain                   # must be clean
git remote -v
git rev-parse --abbrev-ref origin/HEAD   # real default branch (main/master/develop)

• If HEAD is already the default branch, stop and tell the user — there is nothing to merge.
• If the working tree is dirty, stop and ask: commit, stash, or abort. Do not stash silently; someone's uncommitted work is not yours to move.
• Note the current HEAD sha so you can offer an exact rollback later.

Step 2 — Get main fresh

git fetch origin --prune

Merge from origin/<default> directly — do not check out main, and do not rely on a stale local copy. Report how far behind the branch was (git rev-list --count HEAD..origin/main) and how many files main touched.

Step 3 — Merge

git merge origin/main --no-edit

If it merges cleanly, jump to Step 6.

Step 4 — Understand before resolving

List the conflicts (git diff --name-only --diff-filter=U) and, for each file, build real context before touching it:

• git log --oneline HEAD..origin/main -- <file> — why main changed it.
• git log --oneline origin/main..HEAD -- <file> — why this branch changed it.
• Read the whole file, not just the <<<<<<< hunks, plus the callers of anything whose signature moved.

Classify each conflicted hunk:

• Disjoint — the two sides changed different concerns that happen to sit on adjacent lines. Keep both, ordered so the file still reads correctly.
• Same concern, main is newer — main refactored/renamed/moved what the branch also edited. Take main's structure and re-apply the branch's intent on top of it (rename the branch's call sites, move its logic into main's new file, adapt to the new signature). Never discard the branch's behavior just because main rewrote the surroundings.
• Same concern, genuinely competing — both sides implement the same thing differently. This is the only case that needs a decision, and it is the case you escalate if it is not obvious.

Default heuristics (they are heuristics, not rules — the context above wins):

• The branch's feature logic is the reason the branch exists: preserve it.
• Main's UI/styling/copy/formatting-only changes on files where the branch only changed logic: take main's presentation, keep the branch's logic.
• Main's infra changes — dependency bumps, config, migrations, CI, codegen, shared utilities, cross-cutting renames: take main's version and adapt the branch to it. Main is the trunk everyone else builds on.
• Lockfiles (package-lock.json, pnpm-lock.yaml, yarn.lock, poetry.lock): never hand-merge. Take main's, then re-run the install command so the branch's own dependency additions are reinstated.
• Migrations: never renumber or drop main's migration. Keep both and, if ordering matters, re-date the branch's migration to come after main's.
• Generated files (build output, codegen, snapshots): regenerate rather than merge by hand.
• Deleted on one side, modified on the other: do not guess. Find out why it was deleted — usually the content moved somewhere else, so port the change to the new home.

Resolve by editing the file to the correct final state, removing every conflict marker. git checkout --ours/--theirs is only acceptable for lockfiles and generated files.

Step 5 — Ask when it is genuinely ambiguous

Stop and ask the user when:

• Both sides implement the same behavior differently and neither is clearly a superset.
• Resolving requires product intent you cannot read off the code (which validation rule wins, which copy is correct, which default is intended).
• Main deleted or fundamentally reshaped something the branch depends on.
• A schema/migration conflict could cause data loss.

Ask with the actual code in front of them: file, both versions, what each does, what you recommend and why. Ask all such questions in one batch rather than interrupting repeatedly. Do the unambiguous files first so only the real questions remain.

Step 6 — Verify the merge, not just the syntax

After every file is resolved, before finishing:

1. git diff --check and grep for leftover <<<<<<<, =======, >>>>>>>.
2. Run the project's install (if lockfiles moved), typecheck, lint, and test commands. Paste the real output.
3. Re-read the diff of the merge result against both parents for any file you resolved by hand — confirm main's change survived and the branch's change survived.
4. Semantic check: renamed symbol updated everywhere, new required config documented, no duplicate imports or duplicated function bodies from a both-sides keep.

Only commit the merge when this passes. If tests were already failing on main before the merge, say so explicitly rather than attributing it to the merge.

Step 7 — Report

• Files that conflicted and how each was resolved, in one line apiece.
• Anything you took from main that changes how the branch must be run (new env var, migration to run, dependency added).
• Verification results, verbatim.
• The rollback command: git reset --hard <pre-merge-sha> (or git merge --abort if you stopped mid-merge).

Do not push. Pushing is the user's call unless they explicitly asked for it.