MoonBoi9001/merge-base-into-branch

Merge the base into a branch (instead of rebasing)

When a branch's base has moved on, you have two ways to catch up: rebase (replay the branch's commits on top of the new base) or merge (pull the new base in under a merge commit). This skill is for the merge route, and for doing it intelligently — the easy part is typing git merge; the hard part is resolving conflicts correctly and proving you didn't silently corrupt the branch's work.

Why merge here, not rebase

Rebase rewrites every commit on the branch (new hashes), which forces a git push --force. On a PR that can drop review approvals, detach review threads from their commits, and clobber a teammate who pulled the branch. A merge leaves the branch's existing commits untouched and adds one merge commit on top, so the push is an ordinary fast-forward — no force, approvals survive.

The cost is a busier branch graph (a merge commit, and sometimes duplicated copies of commits the base already absorbed). That looks messy, but if the branch eventually lands via squash-merge, the squash takes only the net diff — the merge commit and any duplicates collapse to nothing and never reach the base. So you get safety now and a clean base history later. (If instead the branch will land as a real merge and you care about its internal linear history, rebase may genuinely be the better tool despite the force-push — say so and let the user choose.)

The two scenarios — diagnose before you resolve

Everything downstream depends on which situation you're in. Don't guess; check.

• Scenario A — re-packaged duplicate. The base recently absorbed work the branch already contains. The classic case: a stacked parent PR squash-merged, so the base now holds a single squashed commit that is the same change as the pre-squash commits still sitting on the branch. The "conflict" is just two representations of the same change colliding. The base has nothing genuinely new for the branch.

• Scenario B — genuine new work. The base has real new commits the branch doesn't have, and the branch needs to fold them in. This is an ordinary sync.

How to tell them apart. Identify the commit your branch was built on relative to the base — call it the fork point. For a stacked PR that is the parent PR's old tip (the commit your branch sat on before the parent merged); git log --oneline <fork> ..HEAD should show only your own commits. Then:

git fetch origin <base>
git diff <fork> origin/<base> --stat

• Empty → the base's tree equals your fork point: it carries nothing you don't already have. Scenario A.
• Non-empty → the base has changes beyond your fork point. Scenario B (or a mix).

This single check is what makes the rest safe. Run it every time; don't assume.

Workflow

1. Establish a clean starting point

git status --short            # working tree must be clean before merging
git branch --show-current     # confirm you're on the branch you mean to update
git fetch origin <base>

2. Capture the branch's own change (before you merge)

You will verify against this afterwards, so capture it while it's still unambiguous:

bash <skill-dir>/scripts/verify-merge.sh capture <fork>
# equivalently: git diff <fork> HEAD > /tmp/own-change.diff

git diff <fork> HEAD is exactly what your PR is supposed to contribute once the base has absorbed everything up to the fork point.

3. Merge the base in

Merge a local base branch (not the remote-tracking ref) so the commit message reads the familiar Merge branch '<base>' into <yours>. Update that local ref first:

git branch -f <base> origin/<base>   # fast-forward your local <base> to the fetched tip
git merge <base>                     # let git create the merge commit + default message

What happens next depends on conflicts:

• No conflicts → git auto-commits with its standard merge message. Go to verify.

• Scenario A with conflicts → the conflicts are the duplicated work colliding. Because you proved (step 0/the diff check) the base's content is already in the branch, the correct result is your tree, wholesale. Use the ours merge strategy:

  git merge -s ours <base>           # result tree == your branch's tree, exactly
  

  -s ours records the base as a parent but keeps your tree verbatim, discarding the base's side — which loses nothing here precisely because you proved containment. It also auto-commits with the clean default message.

• Scenario B with conflicts → resolve each conflict by hand. You want both the base's new work and your branch's changes, combined correctly. Never blanket-pick a side. After resolving, git add the files and git commit to finish the merge.

4. The -s ours vs -X ours trap — read this before reaching for either

These look interchangeable and are not. This is the single easiest way to silently corrupt a branch, so internalise the difference:

• -X ours is a strategy option: during a normal three-way merge it resolves only the conflicting hunks in your favour, but it still applies the base's non-conflicting changes. If your branch deleted a line that the base still has, that deletion is not a conflict — so -X ours quietly re-adds the line, undoing your change. Nothing warns you.
• -s ours is a strategy: the merge result is your tree, period. The base contributes nothing to the tree. Safe only when you've proven the base's content is already in your branch (Scenario A). Wrong for Scenario B — it would throw away the base's new work.

For the duplicate scenario, prefer -s ours (whole-tree, provably correct after the containment check). Avoid -X ours there. Worked example below shows exactly how -X ours bites.

5. Verify — the non-negotiable step

A merge can look fine and have quietly changed the branch's diff. Always confirm before pushing.

• Scenario A: the post-merge diff against the base must be byte-identical to the change you captured in step 2:

  bash <skill-dir>/scripts/verify-merge.sh check origin/<base>
  # equivalently:
  #   git diff origin/<base> HEAD > /tmp/post.diff
  #   diff /tmp/own-change.diff /tmp/post.diff && echo IDENTICAL
  

  Anything other than identical means the merge altered your work (the -X ours trap is the usual culprit) — stop, do not push, redo the resolution.

• Scenario B: there is no single equality (the diff now legitimately includes the base's new work). Instead confirm, with judgment: every one of your own changes still survives, the base's new changes are present, and nothing contradictory slipped in.

• Both scenarios: build / compile / run the affected tests. A merge that resolves cleanly can still break the code where two changes meet.

6. Push — plainly, never forced

git push origin <branch>      # ordinary fast-forward

If git ever demands --force (or --force-with-lease) here, you did not do a merge — you rewrote history somewhere (an accidental rebase or amend). Stop and work out what happened; the whole point of this skill is that the push stays a fast-forward.

A note on commit-message hooks

Letting git merge create the commit gives you git's standard Merge branch ... message, and it does not route through git commit — so commit-message validators that hook git commit (e.g. ones demanding Conventional Commits) never see it. If a conflicted merge forces you to finish with git commit and such a validator rejects the default merge wording, the cleanest escape is to complete the merge via an auto-committing path instead (for Scenario A, git merge -s ours <base> resolves and commits in one step), which keeps the standard message and sidesteps the hook. Don't invent a Conventional-Commits title for a mechanical merge just to satisfy a linter if you can avoid it.

Worked example — how -X ours silently corrupts (real case)

A stacked PR (call it the child) made a base configurable: it deleted a hardcoded line const INTERVAL = 5000 and added a config field instead. Its parent then squash-merged into the base, so the base now held the parent's change as one squashed commit (Scenario A — the containment check came back empty).

Merging with git merge -X ours base reported 1 file changed, 1 insertion(+). That insertion was const INTERVAL = 5000 coming back: the base still had that line, the child had deleted it, the deletion wasn't a conflict, so -X ours re-applied the base's version and quietly undid the child's whole point. The byte-for-byte verification in step 5 caught it (the post-merge diff no longer matched the child's captured change). Redoing it with git merge -s ours base produced a tree identical to the child's, the verification came back IDENTICAL, and the push was a normal fast-forward.

The lesson: the verification is not ceremony. It is the thing that turns "looks merged" into "provably correct."

Quick checklist

1. Clean tree, on the right branch, git fetch origin <base>.
2. Find the fork point; git diff <fork> origin/<base> → empty = Scenario A, non-empty = B.
3. Capture the branch's own change (verify-merge.sh capture <fork>).
4. git branch -f <base> origin/<base> then git merge <base> — -s ours if A and it conflicts; hand-resolve if B. Never -X ours for the duplicate case.
5. Verify: A → diff identical to the captured change; B → judgment + build/tests. Always build.
6. git push — fast-forward, never forced.