How would you migrate a repository from Git Flow to a single long-lived main branch?

## The state you are starting from A Git Flow repository has two permanent branches that are genuinely different histories. `main` holds released commits; `develop` holds everything merged since the last release. Feature branches descend from `develop`, tooling and hooks may name `develop` explicitly, and everyone's clone checked out `develop` by default. A migration touches all of that, and the failure mode is not dramatic — it is a commit quietly left on a branch nobody looks at any more. ## Step 1 — measure the divergence Before changing anything, quantify it. `git rev-list --left-right --count main...develop` (three dots) prints two numbers: commits reachable only from `main`, and only from `develop`. `git log --oneline main..develop` lists the second set concretely, and `git log --oneline develop..main` the first — that second list is the interesting one, because anything on `main` that never made it back to `develop` is usually a hotfix that was merged in one direction only, exactly the Git Flow bug the migration is meant to end. ## Step 2 — converge the two lines There are two honest ways to close the gap. Run one final Git Flow release: cut a release branch from `develop`, merge it into `main`, tag it, and merge back. This is the least surprising option for a team mid-cycle, because the last act under the old model is the model working normally. Or, if there is no release ceremony worth preserving, merge `develop` into `main` directly with `git merge --no-ff develop` and tag the result. Either way the finishing condition is the same and is checkable: `git rev-list --count main..develop` returns 0, meaning `main` now contains everything `develop` had. Do not delete `develop` before this holds. Deleting a branch removes only the pointer, but once the remote branch is gone the commits it uniquely held may be unreachable on the server, and recovering them depends on someone's local clone still having them. ## Step 3 — move in-flight work Every open feature branch descends from `develop`, so merging one into `main` afterwards would drag along whatever `develop` had that `main` did not — which after step 2 is nothing, but the branch's merge base is still an old point. For a branch that only its author has, `git rebase --onto main develop feature/checkout` replays exactly the commits in `develop..feature/checkout` on top of `main`, giving a clean, recent merge base. For a branch several people already have, prefer merging `main` into it: rebasing rewrites commits that others may hold, and the recovery from that is its own subject. Deciding per branch — rather than mandating one — is the judgment part of this migration. ## Step 4 — retire develop Once `main` contains everything and open branches are re-pointed, delete the branch: `git branch -d develop` locally (the `-d` form refuses if it is not merged, which is a useful last check) and `git push origin --delete develop` on the remote. Expect a long tail: every clone still has a stale `origin/develop`, cleared with `git fetch --prune`. Local `develop` branches with an upstream that no longer exists show up in `git branch -vv` as `[origin/develop: gone]`. ## Step 5 — fix everything that named develop This is where migrations actually go wrong. Search for the name: hook scripts that check the pushed ref, any configured refspec that mentions `develop`, and aliases in config. Update the remote's HEAD so new clones check out the right branch — `git remote set-head origin -a` updates `refs/remotes/origin/HEAD` in your clone from what the remote reports, and `git clone` follows the remote's HEAD when deciding what to check out. Conventions change too. Tagging now happens on `main` rather than at a release-branch merge, and `main` receives every change rather than only releases, so its `--first-parent` log becomes a change-level log instead of a release-level one. Anything that read version history from that log needs revisiting. ## Step 6 — sequence it with the team Pick a low-traffic window, ask everyone to push or merge outstanding work first, and announce the exact moment `develop` disappears. The technical steps take minutes; the coordination is the whole risk. A single person who was on holiday and returns to a rebased world is the normal source of post-migration mess. ## What goes wrong Deleting `develop` before folding it into `main` strands commits. Leaving it in place "just for now" is worse than not migrating: people keep merging into it, and you now maintain two models. Forgetting the hooks and refspecs produces failures that look random. And the subtlest one: if the team keeps branches long-lived after the migration, they have paid the cost of moving without gaining the benefit, because the benefit was never the branch count — it was the short merge base that the new model makes possible.