Git branch diverged: choose merge or rebase
These blocks describe different cases, not one script. Choose the case that matches your repository. Replace example branch names, file paths and VERIFIED_COMMIT before use. Abort commands apply only to their active operation; do not run both alternatives.
Short answer
A branch has diverged when its local tip and its upstream each contain commits absent from the other. Fetch first, inspect both sides, and choose how to combine them. Merge preserves both histories; rebase replays selected local commits on the fetched upstream and changes their IDs. The warning is information about the graph, not proof that your files are lost.
The example and its prerequisites
This example uses a local main tracking origin/main, with two local commits and one remote commit, as the example. Check that these are your actual branch and upstream before following it. Fetch updates the remote-tracking reference; it does not by itself merge that history into your current branch. A renamed remote or a branch without an upstream needs different names in the commands.
Inspect before changing anything
Read status and branch -vv, then fetch origin. The left/right count for HEAD...origin/main tells you how many commits are exclusive to each side. Inspect the graph and each patch: a count of two versus one says nothing about whether they edit the same function. Do not diagnose divergence using a stale remote-tracking reference or a count alone.
git status --short
git branch -vv
git fetch origin
git rev-list --left-right --count HEAD...origin/main
git log --oneline --graph --decorate HEAD origin/mainKeep a reference or a separate checkout
Before integrating, create rescue/before-sync at the local tip and handle uncommitted changes separately. A rescue branch preserves committed history. A verified stash can preserve selected local files, with different coverage for tracked, untracked and ignored content. Check what you saved. Running merge or rebase over unrelated dirty work makes both conflict handling and later recovery harder to reason about.
git branch rescue/before-sync HEADThe first workflow
Choose merge when preserving the existing history is appropriate, especially when local commits are already shared. git merge origin/main combines the fetched upstream with the current branch. If neither side is an ancestor of the other, a successful merge normally records both parents. Review the resulting diff and project checks before publishing; a completed merge does not certify that the combined code works.
git merge origin/mainChoose the other outcome deliberately
Choose rebase for local commits that your team permits you to rewrite. git rebase origin/main replays the local work on top of the fetched tip, usually creating new commit IDs. Colleagues may already depend on the old IDs if those commits were shared. Do not treat a cleaner-looking graph as permission to rewrite a shared branch or bypass its protected-branch rules.
git rebase origin/mainLimits and exceptions
For merge conflicts, read status, resolve the intended files, stage them and finish the merge; merge --abort abandons that active integration when its preconditions allow. During rebase, resolve and stage the current conflict, then rebase --continue. Rebase can stop at several commits. Use rebase --abort to return from the active rebase rather than mixing commands from the merge workflow.
git status
git merge --abortgit rebase --abortConflicts and cleanup
Do not use reset --hard origin/main as a generic answer to divergence. It discards the local branch's separate history from that branch and can overwrite tracked local files. That is a different decision: deliberately abandon local work. This guide combines wanted histories instead. If you no longer want local commits, inspect them and preserve the appropriate copies before following a separate discard procedure.
Verify the result
Inspect the final graph and status, compare the result against origin/main, and run the relevant project checks. An ordinary push can be rejected if the remote advanced after your fetch. Fetch again and review the new state; do not escalate automatically to force push. The rescue reference remains useful until the integration and its effects are reviewed.
git status --short
git log -8 --oneline --graph --decorate
git diff origin/main HEADCommon questions
Why does git pull ask for a strategy? Pull includes fetching and an integration choice, so an unspecified policy can be ambiguous. Does merge always avoid conflicts? No; both approaches can encounter conflicting changes. Is rebase always better? No: whether commits are shared and the team's history policy matter more than a universal preference.
Review the operation in FluxGit
Use FluxGit’s visual history and patch view to review the operation and the relevant commits. Keep the branch, sharing and local-file checks in this example. The download page lists the currently available builds and platforms.