Rebase¶
In 1 minute
- Your branch started from an old
main. Since then,maingot new commits. Rebase moves your work so it starts from the newestmain. git rebase maincopies your commits, one by one, on top ofmain. The copies get new hashes.- Afterwards, merging into
mainis a simple fast-forward: the history is one straight line, with no merge commit. - Golden rule: only rebase commits that are only on your computer. Never rebase commits other people already have.
- A rebase can hit a conflict too. Fix the file,
git add, thengit rebase --continue(orgit rebase --abortto cancel).
Previously in Bazaar: Neha merged the Diwali sale and fixed a real conflict with Rohan. The history now has merge "bubbles".
1. Why learn this?¶
Rohan is building free delivery for Bazaar: no delivery charge on carts of ₹999 or more. He started his branch on Wednesday morning.
On Wednesday afternoon, Neha added a commit to main. Rohan's branch is now out of date: it doesn't have Neha's change.
He has two ways to catch up. Merge (Lesson 3) works, but adds another merge commit. Rebase gives a cleaner story. Many teams prefer it, so you'll meet it in your first job.
2. The concept¶
The situation, as a picture¶
Read each picture from left (old) to right (new). Each code is a commit.
79d769b ── f46d2ff ← free-delivery (Rohan, 2 commits)
/
... ── 3d5cfad
\
f2939ea ← main (Neha's new commit)
Rohan's two commits start from 3d5cfad. But main has moved on to f2939ea.
What rebase does¶
Rebase means "re-base": give my commits a new starting point (a new base). Git does three things:
- It sets Rohan's two commits aside.
- It moves
free-deliveryto the newestmaincommit,f2939ea. - It replays Rohan's commits on top, one by one, as if he had written them just now.
One straight line. Rohan's work now sits after Neha's commit.
Real output:
New hashes: rebase makes copies¶
Look closely: 79d769b became 96286bf, and f46d2ff became 27ff12f.
$ git log --format="%h %an: %s" -4
27ff12f Rohan Mehta: Add delivery examples
96286bf Rohan Mehta: Add delivery charge rule
f2939ea Neha Kapoor: Add the support email to the README
3d5cfad Neha Kapoor: Add Diwali sale prices
Same message, same author, same change. But a new hash. Why? A hash is made from everything in a commit, including its parent. The parent changed, so the hash changed. So these are really new commits: copies of the old ones.
Then: a fast-forward¶
Now main is simply behind free-delivery. Merging is a fast-forward (Lesson 3):
$ git switch main
$ git merge free-delivery
Updating f2939ea..27ff12f
Fast-forward
delivery.py | 17 +++++++++++++++++
1 file changed, 17 insertions(+)
create mode 100644 delivery.py
$ git log --oneline --graph
* 27ff12f Add delivery examples
* 96286bf Add delivery charge rule
* f2939ea Add the support email to the README
* 3d5cfad Add Diwali sale prices
* 66d2406 Add Steel Water Bottle to the catalog
* 7bb892c Add product catalog with 4 products
No |\ bubbles. Anyone reading this history sees one clear story.
Merge or rebase? Side by side¶
Both bring Neha's change into Rohan's work. The files end up the same. Only the history looks different.
git merge main |
git rebase main |
|
|---|---|---|
| What it does | adds a merge commit joining both lines | copies your commits on top of main |
| History | true record, with bubbles | one straight line |
| Your commits' hashes | stay the same | change (new copies) |
| Safe on shared commits? | yes, always | no (see the golden rule) |
Neither is "wrong". Teams pick one style. A common habit: rebase your own branch to bring it up to date, then merge it into main.
The golden rule¶
Only rebase commits that nobody else has.
Why? Rebase throws away the old commits and makes new copies. Suppose Rohan had already shared 79d769b with Neha (on GitHub, next lesson).
Neha builds on 79d769b. Then Rohan rebases, and 79d769b "disappears" from his branch, replaced by 96286bf.
Now two versions of the same work exist. Neha's next merge brings back the old copies, and the history becomes a mess of duplicates.
So: rebase before you share your branch, or only on a branch that is just yours. When in doubt, merge.
An analogy¶
You're writing chapter 5 of a group notebook. While you write, your friend adds chapter 4.
- Merge = you staple your chapter after the notebook, with a note: "chapter 5 was written before chapter 4 existed". True, but messy.
- Rebase = you rewrite your chapter on fresh pages after chapter 4, as if you'd started after it. Clean, but they're new pages.
Where it breaks: if your friends already photocopied your old pages, now there are two versions going around. That's the golden rule.
Questions you may have¶
Did rebase delete Rohan's old commits? Not right away. They still exist in .git, but no branch points to them, so git log doesn't show them.
Git cleans such commits up after some weeks. Until then, git reflog can find them (see Going deeper).
Do I run git rebase main on main? No. Stand on your branch (free-delivery) and rebase it onto main. Rebase changes the branch you're on.
Does git pull have anything to do with this? Yes, in the next lesson: git pull --rebase uses rebase to bring in other people's commits.
3. See it in action¶
Press Play to watch Rohan's rebase. The grey boxes are the old commits that got left behind.
Then pick Type your own commands and compare: git switch -c idea, git commit -m "A", git switch main, git commit -m "B",
git switch idea, then git rebase main.
4. Code example¶
The file on Rohan's branch. Money in integer paise, and one simple rule:
"""Delivery charge for a Bazaar order. Free delivery when the cart is ₹999 or more."""
FREE_DELIVERY_FROM_PAISE = 99900 # ₹999, in paise (never float for money)
DELIVERY_CHARGE_PAISE = 4900 # ₹49
def delivery_charge(cart_total_paise):
if cart_total_paise >= FREE_DELIVERY_FROM_PAISE:
return 0
return DELIVERY_CHARGE_PAISE
if __name__ == "__main__":
from products import PRODUCTS, rupees
for p in PRODUCTS[:3]: # three example carts, one product each
charge = delivery_charge(p["price_paise"])
print(f"Cart {rupees(p['price_paise']):>6} ({p['name']}): delivery {rupees(charge) if charge else 'free'}")
$ python3 delivery.py
Cart ₹999 (Red Running Shoes): delivery free
Cart ₹649 (Cotton Kurta): delivery ₹49
Cart ₹299 (Masala Box): delivery ₹49
The whole lesson as commands:
git switch free-delivery # stand on YOUR branch
git rebase main # copy my commits on top of the newest main
python3 delivery.py # still works? (always test)
git switch main
git merge free-delivery # Fast-forward: one straight line
git branch -d free-delivery
5. Under the hood¶
Which commits get copied?¶
Before the rebase, ask Git: "which commits are on my branch but not on main?"
$ git log --format="%h %an: %s" main..free-delivery
f46d2ff Rohan Mehta: Add delivery examples
79d769b Rohan Mehta: Add delivery charge rule
main..free-delivery means "in free-delivery, but not in main". These two commits are exactly what rebase replays.
A conflict during rebase¶
Rohan has a second branch, rohan-readme. It adds a line to the end of README.md. Neha also added a line there. Rebasing it:
$ git rebase main
Auto-merging README.md
CONFLICT (content): Merge conflict in README.md
error: could not apply 99a09b3... Explain delivery charges in the README
hint: Resolve all conflicts manually, mark them as resolved with
hint: "git add/rm <conflicted_files>", then run "git rebase --continue".
hint: You can instead skip this commit: run "git rebase --skip".
hint: To abort and get back to the state before "git rebase", run "git rebase --abort".
hint: Disable this message with "git config advice.mergeConflict false"
Could not apply 99a09b3... Explain delivery charges in the README
It's the same kind of conflict as in Lesson 3, with the same markers:
<<<<<<< HEAD
Help: support@bazaar.example
=======
Delivery: free from ₹999, otherwise ₹49.
>>>>>>> 99a09b3 (Explain delivery charges in the README)
Careful, it's flipped: during a rebase, HEAD (top) is main's version, and the bottom is your commit being replayed.
That's because Git is standing on main and adding your commit to it.
Here both lines should stay. The fix has three steps:
- Edit
README.md: keep both lines, delete the three marker lines. git add README.mdgit rebase --continue(Git may open the editor with the commit message: just save and close)
$ git rebase --continue
[detached HEAD 1ef2d2e] Explain delivery charges in the README
1 file changed, 1 insertion(+)
Successfully rebased and updated refs/heads/rohan-readme.
(detached HEAD is normal while a rebase is running: Git builds the copies first, then moves your branch to them.)
If you have several commits, Git stops at each one that conflicts. Repeat: fix, add, --continue. git rebase --abort cancels everything.
Going deeper: reflog, your safety net
git reflog lists every place HEAD has been, even commits no branch points to any more:
$ git reflog -6
27ff12f HEAD@{0}: merge free-delivery: Fast-forward
f2939ea HEAD@{1}: checkout: moving from free-delivery to main
27ff12f HEAD@{2}: rebase (finish): returning to refs/heads/free-delivery
27ff12f HEAD@{3}: rebase (pick): Add delivery examples
96286bf HEAD@{4}: rebase (pick): Add delivery charge rule
f2939ea HEAD@{5}: rebase (start): checkout main
Read it bottom-up: the rebase started from main, picked (replayed) each commit, and finished. The old commits still exist:
git cat-file -t f46d2ff prints commit.
A rebase went wrong and you want the old branch back? Find the old hash in the reflog, then:
git switch -c rescue f46d2ff. The reflog is only on your computer. By default it keeps entries for 90 days (30 days for commits no branch can reach).
Going deeper: interactive rebase (cleaning up your own commits)
git rebase -i main opens a list of your commits in the editor, one per line, each starting with pick:
Change the word in front to tell Git what to do with each commit, then save:
| Word | Effect |
|---|---|
pick |
keep it as it is |
reword |
keep it, but change the message |
squash |
join it into the commit above (both messages kept, for you to edit) |
fixup |
join it into the commit above, drop its message |
drop |
remove it |
You can also reorder lines. It's the tool for turning "WIP", "typo", "fix again" into a few clean commits before you share them. Same golden rule: only on commits nobody else has.
Going deeper: rebase options and force-push
git rebase --onto main old-base my-branch: move only part of a branch.git pull --rebase: fetch other people's commits, then replay yours on top (Lesson 5).git config --global pull.rebase truemakes it the default.git rebase --autostash: put uncommitted changes aside before the rebase and bring them back after.- If you rebase a branch you already pushed to GitHub, a normal push is refused, because the history changed.
git push --force-with-leaseoverwrites it, but only if nobody else pushed in the meantime. Use it only on your own branch, never onmain. (Plain--forcedoesn't check, and can delete a teammate's work.)
6. Lab¶
Lab folder: labs/03-git-and-github/04-rebase/
This time you're Rohan, on his laptop. The repository is ready, with the same hashes for everyone: main (Neha's newest commit f2939ea),
your free-delivery branch (2 commits), and rohan-readme. Look at the split, rebase free-delivery onto main, notice the new hashes,
test delivery.py, fast-forward main, and then (optional) fix a conflict during a rebase.
When you finish, run bash test_lab.sh (from your computer). You should see ALL CHECKS PASSED.
7. Common mistakes¶
- Rebasing a branch others already have. Duplicate commits and confused teammates. Fix: rebase only commits that are just yours; otherwise merge.
- Running
git rebase mainwhile onmain. Rebase changes the branch you're on. Fix:git switch free-deliveryfirst. - Forgetting
--continue. After fixing a conflict andgit add, the rebase is still paused. Fix:git statussaysrebase in progress; rungit rebase --continue. - Using
git commitin the middle of a rebase. It makes an extra commit. Fix: aftergit add, usegit rebase --continue. - Panicking because "my commits are gone". They have new hashes, or they're in the reflog. Fix:
git log, thengit reflog.
8. Quiz¶
9. What's next¶
Next: putting Bazaar's repository on GitHub, sharing branches with push and pull, and reviewing work with pull requests: GitHub and pull requests.
In one line: on your branch, git rebase main copies your commits (with new hashes) on top of the newest main, so the history stays
one straight line; never rebase commits other people already have.
Cheat sheet¶
| Task | Command |
|---|---|
Bring my branch up to date with main |
git switch my-branch then git rebase main |
| Which commits will be replayed? | git log --oneline main..my-branch |
| After fixing a conflict | git add <file> then git rebase --continue |
| Skip the commit that conflicts | git rebase --skip |
| Cancel the whole rebase | git rebase --abort |
| Find "lost" commits | git reflog |
| Clean up my commits before sharing | git rebase -i main |
| Merge | Rebase | |
|---|---|---|
| History | true record, with bubbles | straight line |
| Hashes | unchanged | new copies |
| On shared commits | safe | never |
Next in Bazaar: Neha and Rohan swap code by copying folders around. Each laptop has a different history, and nobody reviews anything. Bazaar's code needs one shared home online, and a way to review changes before they reach
main: GitHub and pull requests.