The previous lesson closed off local undoing: reset, restore, clean, and a decision table that ended with a row pointing here. This lesson deals with everything that happens between your repository and the server, and it closes the promise left open in lesson 04-05, where we saw the non-fast-forward rejection and only gave the basic way out.

The problem has a name and a precise definition: divergence. And it has a reputation for being complicated that it does not deserve, because as soon as you draw the graph the solution is usually obvious. What confuses people is that the same state presents itself with four different messages depending on how you discover it: a status that says "have diverged", a pull that refuses to decide, a rejected push, or a colleague reporting that commits have vanished on them.

We are going to see that all four are the same situation, that there are exactly three ways out of it, and that the choice between the three depends on a single question: whose branch is this?

And at the end, the serious case: what to do when the person who rewrote the published history was somebody else, and you have two days' work resting on a base that no longer exists.

1. What "have diverged" means exactly
2. Measuring the divergence
3. The four messages for the same situation
4. The three pull policies and which to choose
5. How you end up with a divergence
6. The rejected push: diagnosis and ways out
7. --force-with-lease and why it sometimes does not protect you
8. When the remote was rewritten and you have work on top of it
9. Recovering the previous remote branch with origin/branch@{1}
10. Unrelated histories: --allow-unrelated-histories
11. Coordination: what needs saying and when

Two branches have diverged when each one has commits the other does not have. Formally: a common ancestor exists, and two different paths lead away from it.

Your main has two commits the server does not have. The server has three you do not have. The common ancestor is 4f8a2e6.

Compare it with the two cases that are not divergence:

The key word is decide. A divergence is not an error: it is a situation in which Git cannot know what you want and refuses to invent it. Everything that follows is a way of making that decision.

Recalling lesson 03-01: the common ancestor is the one Git calculates with git merge-base, and it is the basis of the three-way merge. You can see it directly:

Before resolving, measure. These commands modify nothing.

fetch updates origin/main without touching your main (lesson 04-04). Without this, you are reasoning about an old snapshot of the server.

The three dots are essential: A...B is the symmetric difference, the commits that are on one branch but not on the other. --left-right separates them by side.

With the tracking branch configured (lesson 04-06), this is enough:

This is what really lets you decide:

< is the left-hand side (your main), > the right-hand one (origin/main).

And the question that determines whether there are going to be conflicts:

If the sets of files do not overlap, the integration will be clean.

Depending on how you arrive at the divergence, Git tells you about it in a different way. Recognising all of them is half the lesson.

This is the pure diagnosis. The numbers match rev-list --left-right --count.

Since Git 2.27, pull refuses to choose for you:

This is a good thing. Previously, pull performed a silent merge and filled the history with "Merge branch 'main' of git.example.com..." commits that nobody had asked for. Now it forces you to have a policy, and that is section 4.

It is the same information in fewer words: there is divergence and your policy says "do not decide for me". It is not a fault (lesson 04-04, error 3).

Or, in its more alarming variant:

Both say the same thing: the server has commits you do not have, and accepting your push would leave them unreachable. It is a protection on the server's part, not a fault of yours. That is section 6.

git pull is fetch + integration (lesson 04-04). The policy decides which integration.

Visually, from the same starting point:

The recommended configuration for most people:

Or, if your team works with short branches and wants a linear history (which is what Ana does in task-manager):

rebase.autoStash avoids the "cannot pull with rebase: You have unstaged changes", which is the most frequent complaint against pull --rebase.

The golden rule still applies (lesson 05-01): pull --rebase rewrites your local commits, which you have not published yet. That is legitimate. What you must never do is rebase commits that are already on the server and that others may have.

And a setting that prevents a classic mistake:

If you had pending fixup! commits (lesson 05-02), they will not be squashed by surprise during a pull. Check it in your configuration: if you have it enabled without knowing, a pull --rebase can reorganise your commits.

Understanding the cause matters, because it determines which of the ways out is the right one.

Ana committed locally while Bruno was publishing his work. Nobody has done anything wrong. It is the normal behaviour of a distributed system with several people.

Way out: integrate (merge or rebase, according to the policy) and push. No drama.

Carla published GT-247, spotted a typo in the message and ran git commit --amend.

What has happened. --amend does not modify the commit: it creates a new one with a different hash and moves the branch (lesson 09-01, section 5.3). The original commit is still on the server. Local and remote now each have one commit the other does not have: a divergence of 1 and 1.

Way out: if the branch is hers alone, push --force-with-lease. If not, integration is needed, and the result is ugly (the commit would appear twice).

Bruno ran git reset --hard HEAD~2 on a published branch to "get rid of two commits", and then worked for two more hours.

A divergence of 2 and 2. And here there is an underlying decision: should commits C and D disappear from the project or not?

Way out: if they should disappear and the branch is his, --force-with-lease. If the branch is shared, the correct answer was git revert (lesson 05-06) and not reset; now it is a case of integrating and reverting.

Diego did a rebase -i on main to "tidy up the history" and forced the push. Everybody who had main fetched finds themselves with a divergence they did not cause.

This is the serious case, and it has a section of its own: 8.

Ana and Carla are working on GT-241 at the same time. Both run pull --rebase. Each rebase rewrites the other's commits. The result is a spiral of duplicated commits that ends badly.

Way out: on genuinely shared branches, pull.rebase false. The policy has to be per branch, not out of habit.

This is the closing of what was promised in lesson 04-05.

With those four answers you already know which way out applies.

With pull configured:

If conflicts appear during the rebase, the mechanics are those of lesson 05-01, including the inversion of ours/theirs. And if you get overwhelmed:

Only if all three conditions hold:

1. It is a feature branch and nobody else uses it.
2. What is on the server are old versions of your own commits.
3. You have checked point 3 of the diagnosis and there are no commits from anybody else.

The + at the front indicates that it was a forced push.

Never a bare --force. The difference is section 7.

Sometimes the right answer is not to force and not to integrate, but to publish somewhere else:

Especially useful if the branch has an open pull request with review comments (lesson 07-02): forcing can leave the comments orphaned. Publishing a new branch keeps everything and allows comparison with git range-diff (lesson 07-02).

Recalling lesson 04-05: --force-with-lease only forces if the server is where you think it is. It compares the real remote tip with your local copy of the tracking branch (refs/remotes/origin/GT-241).

That stale info means: "the server is not where your origin/GT-241 says it is; somebody has published something since your last fetch". That is exactly the protection working: it has stopped you destroying somebody else's work.

And here is the detail hardly anybody knows about, and which has to be understood properly:

If you run git fetch just before --force-with-lease, the protection disappears.

Because fetch updates origin/GT-241 with what is on the server right now, including your colleague's new commits. Your lease comes to match reality, the check passes, and you force on top of work you have never seen.

The worst of it is that the sequence is reasonable: "I'll update before forcing" sounds like good practice. And many IDEs run fetch automatically in the background, so it can happen to you without you typing the command at all.

Git 2.30 added the option that fixes the hole:

--force-if-includes additionally checks that the remote commits you are about to overwrite are incorporated into your local history, by looking at your reflog. That is to say: it requires you to have seen and integrated what you are about to replace, not merely to have fetched it.

Configure it as the default behaviour:

With that, every --force-with-lease you run carries the extra check automatically. It is one line of configuration that eliminates an entire class of accidents.

And the explicit variant, when you want to be absolutely precise:

Verbose, but there is no way to get it wrong.

This is the serious case, and the one that produces the most panic. It deserves the complete procedure.

The situation. Diego did a rebase -i on main to tidy up the history and forced the push. Ana had main fetched and, on top of it, three GT-241 commits she had not yet published.

First of all: you have lost nothing. Your commits are still in your repository, intact. And you also have the old main commits locally, even though the server no longer has them. In fact, your clone is now the only copy of the previous version, and that puts you in a strong position.

The messages are repeated on the two branches, with different hashes. That is the unmistakable pattern of a rewritten history. Confirm it:

git range-diff (lesson 07-02) compares two series of commits and says whether the content is the same:

The first two are identical (=); the third changed (!) and it shows you exactly how. This is the information you need before deciding anything.

Two seconds. From here on, nothing you do is irreversible.

The command that solves exactly this is the --onto from lesson 05-01. Its form is:

which reads: "take the commits on <branch> that come after <old-base> and reapply them on top of <new-base>".

In our case:

• New base: origin/main (the new history).
• Old base: 7d3a8f4 (the old main your branch hung off).
• Branch: GT-241.

Your three commits, with new hashes, on the new base. Not a single duplicated commit.

How to find the old base if you have not made a note of it:

Your local main still has the old version. Since you had nothing of your own on main (all your work was on GT-241), simply align it:

If you did have commits of your own on main, do not do that: take them out to a branch first (git branch my-main-commits) and transplant them with the same --onto.

Three =s: the content of your commits is identical to what it was before the transplant. Nothing has been lost or altered. Now you can delete the backup with peace of mind:

And run the tests before publishing: the rebase has reapplied your code on a different base, and even if there were no conflicts, there can be semantic incompatibilities.

If your GT-241 commits were already on the server, after the rebase your branch diverges from origin/GT-241. Since GT-241 is yours:

A detail that saves situations and that hardly anybody knows about: remote tracking branches have a reflog too.

Two extremely valuable things in that output:

1. forced-update is the proof that somebody rewrote the published history. If you were in doubt about what happened, there is the evidence with its date.
2. origin/main@{1} is where the server's main was before the rewrite.

This is what makes it possible to reconstruct what the server had before, and it is the reason why, when somebody forces and destroys work, any colleague who had the branch fetched can put it back:

And with dates too:

That is exactly the reflog mechanism, whose complete treatment — including the @{n} versus @{time} syntax and the expiry limits — is lesson 09-04.

What it means. The two branches have no common ancestor at all. It is not a divergence: they are two completely independent family trees, each with its own root commit.

First of all, check that it is the benign case:

If the remote only has the platform's initial commit:

It will probably conflict in README.md: resolve it as normal (lesson 03-05) and commit.

If the remote has the real project and your local history is the surplus one:

And if somebody has published another project on top of yours, this is an incident: do not merge anything, tell the team, and use the origin/main@{1} from section 9 (or any colleague's clone) to restore. Lesson 09-05 covers the use of other clones as a backup.

Never run --allow-unrelated-histories "because Git is complaining". That refusal is a very useful sanity check: Git is telling you that those two things have nothing to do with each other. Find out why before you override it.

The non-technical part, which is the one that saves the most time.

Before rewriting anything shared:

1. Give notice beforehand, not afterwards. A thirty-second message in the team channel: "I am going to force main at 16:00 to get the database dump out of the history. Do not pull until I say so."
2. Say what everybody else has to do. Even if it is obvious to you, it is not to somebody who is busy with something else:

   After the all-clear, everybody:
     git fetch origin
     git switch main
     git reset --hard origin/main
   If you have branches with commits of your own, tell me before touching
   anything and we will do the rebase --onto together.
   

3. Do it at a quiet time. Never on a Friday afternoon, never during a delivery.
4. Confirm when it is over. Silence produces blind pulls.

When it has already happened and you gave no notice:

1. Say so anyway, as soon as possible. The cost of saying "I have forced main, do not pull" after five minutes is zero. After five hours it is an afternoon's work for three people.
2. Offer the procedure from section 8, not a "sort it out".
3. If you have destroyed somebody else's work, section 9 recovers it from any clone in the team. It is not lost.

Structural prevention (lesson 07-06):

A protected branch makes this whole section unnecessary. If main does not accept --force, the problem cannot happen. It is the most profitable measure in the lesson.

And locally, a personal protection:

Mistake 1: answering a rejected push with --force. The rejection means the server has commits you do not have. Forcing destroys them. Diagnose first: git log --oneline HEAD..@{u} says whose they are.

Mistake 2: reasoning about origin/main without having run fetch. origin/main is a local snapshot that may be hours old. Every diagnosis starts with git fetch.

Mistake 3: git fetch just before --force-with-lease. It cancels the protection. Use --force-if-includes, or configure it with push.useForceIfIncludes true.

Mistake 4: using pull --rebase on a branch somebody else also has. It rewrites published commits and generates duplicates in a chain. The policy must be per branch, not out of habit.

Mistake 5: running --allow-unrelated-histories without looking at what is on the other side. You can end up merging an entire other project into yours. Look at git log origin/main first.

Mistake 6: git reset --hard origin/main without checking what you have ahead. git log --oneline @{u}..HEAD costs a second and tells you exactly what you are about to throw away.

Mistake 7: redoing the work by hand after somebody else's rewrite. git rebase --onto transplants it in one command and range-diff proves nothing has been altered.

Mistake 8: forcing a branch with an open pull request full of comments. It can leave the review orphaned. Consider publishing a new branch.

Mistake 9: not telling anyone. The technical cost of a shared rewrite is small; the social cost of not announcing it, enormous.

Tip 1: git status -sb as a reflex. One line that says [ahead N, behind M] and settles half your doubts.

Tip 2: pull.ff only as the global value. It forces you to look before integrating, and avoids merge commits nobody asked for.

Tip 3: push.useForceIfIncludes true. One line of configuration that eliminates the --force-with-lease hole.

Tip 4: git range-diff before and after any rewrite. It is the objective proof that the content has not changed.

Tip 5: remember origin/branch@{1}. The server's previous history is still in your remote reflog, and with it you can restore what somebody else destroyed.

Tip 6: protect main on the server. It is the only solution that makes the problem impossible, rather than treating it.

1. Set up a local remote with git init --bare and clone it twice (simulating Ana and Bruno).
2. From Bruno's clone, make two commits and publish them.
3. From Ana's, without running fetch, make two different commits.
4. Run git fetch and measure the divergence with git status -sb, git rev-list --left-right --count and git log --left-right --oneline.
5. Try git push and transcribe the exact message.
6. Resolve it with pull --rebase and check with git log --graph that the history has ended up linear.
7. Repeat the whole exercise with pull --no-rebase and compare the two resulting graphs.

1. With the same setup, have Ana publish a commit on GT-241.
2. Ana runs git commit --amend on that commit (without publishing yet).
3. In the meantime, Bruno publishes a new commit on GT-241.
4. Ana runs git push --force-with-lease. Note the result and explain it.
5. Ana runs git fetch and tries again. Note the result and explain why it has changed.
6. Check that Bruno's commit has disappeared from the server and recover it using origin/GT-241@{1} from Bruno's clone.
7. Repeat step 5 with --force-if-includes and check that it does protect this time.

1. Set up a remote with three commits on main and clone it twice.
2. From Ana's clone, create GT-241 on main with three commits of her own (without publishing it).
3. From Diego's clone, do a git rebase -i on main to modify the second commit's message, and force the push.
4. Ana runs fetch and diagnoses the situation with git log --graph --all and git range-diff.
5. Ana transplants GT-241 with git rebase --onto and aligns her main.
6. Verify with range-diff that her three commits are identical in content.
7. Check in git reflog show origin/main that the forced-update has been recorded.

Solution 1:

Linear, no forks. Her two commits have new hashes (b52c9d1 → 8f2d6a1): the rebase has recreated them on the new base.

Solution 2:

The protection has worked. Ana's origin/GT-241 points at her original commit; the server is on Bruno's commit. Since they do not match, Git refuses.

It went through. And it has destroyed Bruno's commit. The fetch updated origin/GT-241 to Bruno's commit; the lease came to match reality; the check was satisfied. Ana never saw Bruno's work and overwrote it all the same.

In fact Bruno does not even need the reflog: he has the commit on his local branch. His local GT-241 is still intact:

And to put it back on the server it would need integrating with Ana's amended version — a cherry-pick of Bruno's commit onto the new branch (lesson 05-03) — coordinated between the two of them.

Now it does protect, even after the fetch. The extra check requires the remote commits that are about to be overwritten to be incorporated into Ana's local history, not merely fetched. And they are not: she never integrated them.

Solution 3:

Note down that 7d3a8f4: it is the old base.

Two parallel lines with the same messages: rewritten history.

Only one message changed; the content is identical. A complete diagnosis in one command.

Three =s. Identical content, new base, zero duplicated commits.

forced-update with its date, and origin/main@{1} keeping the server's previous history. If it had been necessary to restore it, there it was.

Divergences stop being frightening as soon as you see them for what they are: a situation in which Git cannot decide for you.

• Diverging means each branch has commits the other does not have. It is measured with git status -sb and with git rev-list --left-right --count main...origin/main, and it is understood by looking at both sides with git log --left-right. Every diagnosis starts with git fetch.
• The four messages are the same situation: the "have diverged" from status, the "You have divergent branches" from pull, the "Not possible to fast-forward" from pull.ff only and the non-fast-forward from push.
• Three pull policies: merge for genuinely shared branches, rebase for your own, ff-only when you prefer to decide by hand. The choice is per branch, not out of habit.
• A rejected push is answered by diagnosing, not by forcing: git log --oneline HEAD..@{u} says whose the server's commits are. If they belong to somebody else, you integrate. If they are old versions of yours and the branch is yours alone, you force with --force-with-lease.
• --force-with-lease does not protect you if you have run fetch just beforehand, because the lease is updated with what you have not yet seen. --force-if-includes fixes it; push.useForceIfIncludes true leaves it set for good.
• When somebody else rewrites the published history and you have work on top of it, the procedure is: back up with git branch, transplant with git rebase --onto <new-base> <old-base> <branch>, align main with reset --hard origin/main, and verify with git range-diff that the content has not changed.
• Remote branches have a reflog too. origin/main@{1} keeps where the server was before the rewrite, and forced-update is the evidence that it happened. With that, any clone in the team can restore what was destroyed.
• refusing to merge unrelated histories is not divergence: they are two trees with no common ancestor. Look at what is on the other side before using --allow-unrelated-histories.
• And what saves the most: giving notice beforehand, and protecting main on the server so that the problem cannot happen at all.

One idea remains that has appeared in almost every section without being developed: the reflog. It has been the source of the ORIG_HEAD from the previous lesson, of the origin/main@{1} from this one, and of the promise we have had outstanding since lesson 03-06 ("-D is recoverable") and 05-01 ("a disastrous rebase can be undone").

It is time to develop it in full: what it is exactly, where it lives, how long it lasts, how to read it, and the complete recovery recipe book — the reset --hard that swept away three days, the branch deleted with -D, the rebase that went wrong, the deleted stash — plus what to do when even the reflog is not enough.

Continue in lesson 09-04: Recovering Lost Commits.