Rewriting shared branches

So far you've rewritten commits that were only in your repository. This Lesson covers two situations where other people are involved: catching up with a branch your teammates push to, and replacing a branch you've already pushed.

Pulling with a rebase

You've committed on main but haven't pushed yet, and a teammate has pushed to main on origin. A plain git pull merges their commit into yours with a merge commit, as you learned in Remotes & Collaboration. git pull --rebase fetches their commit too, but then rebases instead of merging: your unpushed commits are replayed on top of theirs.

$ git pull --rebase
From https://git.example/team/project
   4607830..76fd3eb  main       -> origin/main
Successfully rebased and updated refs/heads/main.

History stays one straight line, with your commits last, and git push goes through as usual. Only your unpushed commits are rewritten, so nobody else is affected. If a replayed commit conflicts with theirs, the rebase stops, and you resolve it as in Rebase conflicts: fix the file, git add it and git rebase --continue, or back out with git rebase --abort.

If you'd rather git pull always worked this way, set it once: git config pull.rebase true. You met that setting in Fetching and pulling, set to false.

To bring a branch of your own up to date with main on origin, name it: on your branch, git pull --rebase origin main fetches main from origin and rebases your branch onto it, all in one go.

Replacing a branch you've pushed

Suppose you pushed menu yesterday, and today you rebased it onto the newest main. The rebase made copies, so your menu no longer contains the commits that origin has. A plain push is refused:

$ git push
To https://git.example/team/project.git
 ! [rejected]        menu -> menu (non-fast-forward)
error: failed to push some refs to 'https://git.example/team/project.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. If you want to integrate the remote changes,
hint: use 'git pull' before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

Don't follow that hint here. git pull would merge your old commits back in, next to their copies. You don't want to integrate the commits on origin. You want to replace them.

That's what git push --force-with-lease does:

$ git push --force-with-lease
To https://git.example/team/project.git
 + 9bb03b7...f555dfb menu -> menu (forced update)

origin's menu now matches yours, and the old commits fade.

The lease

The lease is your origin/menu: where your repository last saw menu on origin. --force-with-lease replaces menu on origin only if it's still there. If a teammate has pushed to menu since your last fetch, the push is refused, and nothing changes:

$ git push --force-with-lease
To https://git.example/team/project.git
 ! [rejected]        menu -> menu (stale info)
error: failed to push some refs to 'https://git.example/team/project.git'

Then:

1. git fetch to bring in what they pushed.
2. Look at it: git log --oneline origin/menu lists menu on origin, newest first. Your teammate's commits are on top, then your own old commits, the ones your rebase copied.
3. Copy their commits onto your menu, for example with git cherry-pick origin/menu.
4. git push --force-with-lease again.

Be careful with step 1. A fetch moves origin/menu, which renews the lease, so the next --force-with-lease would replace their work without a word. Always look at what you fetched before you force.

Never a plain --force

git push --force replaces the branch on origin whatever is there, so it can silently throw away a teammate's work. Lessons and Checkpoints don't run it. Use --force-with-lease whenever you mean to replace a branch.

Whose branch is it?

Rewrite a pushed branch only when it's yours, and tell anyone who has it, because their copies still have the old commits. Never rewrite main or another branch the whole team builds on. For those, merge, or use git revert from Undoing Things.