unfork

name	unfork
description	Reconcile a long-diverged fork with its upstream. Use when a fork has drifted for months or years and the user wants to catch up to upstream while keeping only the local changes that still matter — rebuilt as a clean, minimal patch set.

Unfork

A long-diverged fork is two codebases wearing one name. The naive git merge upstream/main produces a conflict wall and a history nobody can audit. Your job is the opposite: figure out what the fork's divergence actually consists of, then rebuild only the still-valuable part on top of current upstream as clean, explainable commits.

Safety first: all work happens on a new branch. Never force-push, never rewrite the fork's existing branches, never discard the old branch — it remains the archive until the user retires it.

Phase 1 — Map the divergence

• Fetch upstream; find the merge-base; count ahead/behind.
• List every fork-side commit since the base. If the fork has merge commits from previous partial syncs, flatten your view to effective changes (diff-based, not commit-count-based).
• Summarize what upstream did meanwhile at feature level (releases, big refactors, renames) — this is the terrain the surviving patches must land on.

Phase 2 — Sentence every fork commit

Classify each fork-side change:

• ABSORBED — upstream has the identical/equivalent change. Detect with git cherry / patch-id first, but that only catches textual equivalence — also check semantic absorption: the bug it fixed has an upstream fix in different words. Drop these.
• SUPERSEDED — upstream solved the same problem differently. Drop the fork's version; verify the upstream solution actually covers the fork's use case, and note the gap if it doesn't.
• ALIVE — still unique, still wanted. These survive to the rebuild.
• OBSOLETE — patches to code upstream deleted, workarounds for problems that no longer exist, experiments nobody remembers wanting. Confirm with the user before dropping anything with unclear intent.

Where the user's intent is unknowable from the code, ask — the sentencing table is exactly the decision they need to see anyway.

Phase 3 — Rebuild

• New branch from current upstream HEAD.
• Re-apply only the ALIVE set, in dependency order, resolving each against modern upstream code (this may mean re-implementing, not just cherry-picking, when the surrounding code moved).
• Group the result into coherent commits — one logical change each, messages explaining why the fork carries this — so the next reconciliation (or an upstream PR) is easy.
• After each patch lands: build. After the last: full test suite, plus whatever fork-specific functionality exists gets exercised.

Phase 4 — The ledger

Write UNFORK.md: the sentencing table (every old fork commit → its fate and evidence), the new branch's patch list, verification results, and the standing advice — which ALIVE patches are candidates to upstream as PRs so the next unfork is smaller. A fork that upstreams its patches eventually gets to stop being a fork.