Concurrent Branches

Merging Concurrent Branches

When several branches are open against the same repo at once, the conflicts do not land in the code you were thinking about. They land in a small, predictable set of hotspot files that nearly every change has to touch — a registry manifest, a version field, shared tool config, one aggregated test module, a tracked build output.

Each hotspot has exactly one correct resolution, and they are not the same rule. "Take ours" / "take theirs" is right for almost none of them. Worse, getting one wrong is silent: the dropped entry, the collided version, the stale bundle all merge green and are found later by someone who cannot reproduce them.

Find the hotspots before you need to resolve them

Files touched by nearly every commit are the files your branch will conflict on.

# the 15 files most commits touch — your hotspot list
git log --format= --name-only -n 200 | sort | uniq -c | sort -rn | head -15

Write the resolution rule for each one into the contributing docs. Under conflict pressure, with a stale branch and a red CI run, nobody re-derives "the version field is recomputed, not merged" correctly.

Additive registries: union both sides, never choose one

A manifest that lists every component — plugin entries, module paths, exported names, a feature list. Two branches each append an entry, and the conflict spans both additions:

<<<<<<< HEAD
    "./components/exporter",
    "./components/importer"        // theirs, already merged to main
=======
    "./components/exporter",
    "./components/validator"       // yours
>>>>>>> feature/validator

Both sides are correct and neither is a substitute for the other. Resolve by keeping every entry from both sides. Taking a side deletes a component that is still fully present in the tree — the code compiles, the tests pass, and the component is simply never registered or installed.

Nothing catches that unless you check the registry against the filesystem:

# every registered path exists
jq -r '.plugins[].components[]' manifest.json | while read -r p; do
  [ -e "${p#./}" ] || echo "registered but missing: $p"
done
# every component on disk is registered
for d in components/*/; do
  grep -q "\"./${d%/}\"" manifest.json || echo "present but unregistered: $d"
done

Run it as a repo test, not as a merge-day ritual. It is the only thing standing between a mis-resolved conflict and a component that quietly does not ship.

Single-value counters: recompute from the integration branch

A version field, a sequence number, a "latest migration" pointer. Both branches bumped 2.17.0 to 2.18.0; both are wrong now, because a third branch already merged and main is at 2.18.0 too.

Union is meaningless here and picking a side reintroduces a collision. The rule is recompute from the current integration branch, not from either side of the conflict — every change that merged since you branched consumed one increment:

git fetch origin main
git show origin/main:manifest.json | jq -r '.metadata.version'   # -> 2.18.0
# your branch takes 2.19.0, regardless of what your branch said before

Do this as the last step before pushing, not during the merge. If another branch lands while you resolve, you redo only one line.

Generated artifacts: rebuild, never merge

A committed minified bundle, a built PDF, a compiled schema, a checked-in snapshot. Git will happily produce a merge for the text ones and force a binary choice for the rest — and every such result is wrong, because a derived file's only correct content is whatever the merged sources generate.

Resolve the sources, then regenerate:

git checkout --merge -- src/ ui/app.jsx   # resolve the real inputs first
make build                                 # regenerate the artifact
git add dist/bundle.js docs/handbook.pdf

Two things make this reviewable rather than a leap of faith:

• Pin the generator version. If the bundler or typesetter is pinned, its output is byte-identical anywhere, and a reviewer can regenerate and diff to confirm the artifact matches the source. Unpinned, the artifact diff is a mix of your change and a tool upgrade, and nobody can tell them apart.
• Verify only the expected regions moved. A rebuilt document reflows: a one-paragraph edit typically spreads across two or three consecutive pages. Raster-diff or diff the rebuilt artifact against one built from the base commit in the same environment, and say in the PR which regions changed and why. Anything else that moved is your merge, not your edit.

Non-deterministic serialization turns every branch into a conflict

If a tracked file is written by iterating a map, set, or dict whose order is not stable, the whole file is rewritten on every run. Then every branch conflicts on every line, diffs are unreviewable, and real conflicts hide inside the churn.

Sort before writing:

# BAD — map iteration order; the file is rewritten differently every time
records = [to_record(k, v) for k, v in index.items()]

# GOOD — a stable key. ISO-8601 dates sort chronologically as plain strings,
# so no date parsing is needed to get a deterministic, reviewable file.
records = sorted((to_record(k, v) for k, v in index.items()), key=lambda r: r["date"])

This applies to any code path that rebuilds a committed file from an unordered collection, including the ones added later. Once one path forgets, the file is churny again.

Shared tool config: take the base file, re-apply your delta

pyproject.toml, package.json, lint config, a CI workflow — files where your branch added three lines and four other branches added their own. Reconciling hunks by hand is where dev-dependency pins and tool sections get silently dropped.

Take the integration branch's copy wholesale — it already carries everything that landed while you were away — then re-add only the lines your branch introduced:

git checkout origin/main -- pyproject.toml
# re-add just your delta, then confirm nothing else moved
git diff origin/main -- pyproject.toml

That last git diff should show your addition and nothing else. If it shows a pin reverting or a tool section disappearing, you took a side by accident.