Resolve diverged local and remote Git branches

A diverged branch has commits on both sides that the other side does not contain. Fetch first so you are comparing with the current remote history, then decide which commits to preserve. The examples use main; substitute your actual branch name.

Inspect before changing history

Save or stash unfinished work, including any untracked files you need, then run:

git switch main
git fetch origin
git log --left-right --oneline main...origin/main
git branch backup/main-before-reconcile

Lines marked < belong only to the local side; > marks the remote side. The backup branch protects committed history, not uncommitted files. Divergence can follow work on multiple machines, web edits, or an earlier amend or rebase of shared commits.

Merge to preserve both histories

git merge origin/main
# Resolve any conflicts, stage the resolutions, then commit.
git push origin main

For an actual divergence, a successful merge creates a merge commit. git pull --no-rebase origin main combines fetching and merging; a bare pull may use another strategy or refuse divergence depending on configuration.

Rebase unpublished local work

git rebase origin/main
# If paused, resolve conflicts and stage each resolution.
# Continue with git rebase --continue, or cancel with --abort.
git push origin main

Rebase rewrites the replayed commits. When only unpublished local commits were rebased onto the current remote tip, an ordinary push can succeed; force is not automatically required. If others use the rewritten history, coordinate the change or choose a merge.

Discard one side only after reviewing it

To discard local branch commits and tracked-file changes in favor of the fetched remote:

git reset --hard origin/main

This is destructive to local changes and can remove untracked paths that obstruct tracked files. Preserve needed files first. Replacing the remote with the local branch is a separate, exceptional decision: review the remote-only commits and use a specifically scoped --force-with-lease push only with the team's agreement and branch permissions. A lease checks a remote ref; it does not judge whether deleting its commits is correct.

Set a repository policy

git config pull.rebase true makes pull prefer rebase in this repository. git config pull.ff only instead refuses non-fast-forward pulls and requires an explicit reconciliation. Choose the policy with your team.

If a force push removed needed history, preserve the missing commit from a backup branch, another clone, or an available reflog, then agree on a restoration. Another blind force push can discard still more work.

References: git pull, git reset, and git push.