You have a long-running topic branch off of master. Every day or two you rebase the topic branch on top of master to keep it up-to-date.1 You have another branch off of topic in which you are doing incremental work that periodically gets committed to the topic branch. When you rebase topic on master, that incremental branch gets “orphaned”. You want to rebase it cleanly back on top of the topic branch.
Now with pictures. Here’s what you start with.
A---B---C master \ D---E topic origin/topic \ F incremental
(topic)$ git rebase master A---B---C master | \ | D'--E' topic \ D---E origin/topic \ F incremental (incremental)$ git rebase --onto topic origin/topic A---B---C master \ D'--E' topic \ F incremental
You may be thinking that rebasing
master then rebasing
topic would accomplish the same goal, like this:
(topic)$ git rebase master A---B---C master | \ | D'--E' topic \ D---E origin/topic \ F incremental (incremental)$ git rebase topic [UH-OH]
UH-OH means that you’re going to rewind to
E', then try replaying
F on top of
E'. That’s probably not what you want, and in all but the most trivial cases you’re going to wind up with messy conflicts. What you want is to permanently drop
E' have replaced them. Using
rebase --onto accomplishes that.
rerereto avoid reliving the same conflicts each time.