--- title: "Git Rebase Under the Hood" date: "2022-09-17T18:27:01+00:00" summary: image: type: "article" url: "/acquia-cloud-platform/help/89051-git-rebase-under-hood" id: "01a5ec0e-0062-4164-918f-aad2af947f91" --- Like so many others who watch daily at my proverbial door for the next [golden drop of Git wisdom](/blog/streamline-drupal-development-effective-git-practices) to fall from my gilded lips, you've probably been waiting with breathless anticipation for me to talk about rebasing. (Or you're just here because you saw "git rebase" in the title and you're curious--I suppose anything is possible.) In any case, your interest is understandable. There are few Git skills at once more fundamental and less understood than rebasing. And no wonder, really--it's basically magic, and magicians don't readily give up their secrets. I've Googled hard, but I've sought in vain a good diagram that shows what's actually going on behind the scenes. Let's fix that, shall we? Join me now, as we embark on a perilous journey to understand Git rebase, armed with nothing but a terminal and a dream... And so it begins ---------------- First, we clone a repository for local development. `(you) $ git clone [remote]` ![Blue circles labeled 1, 2, 3 connected in a line, representing a sequence from "main."](https://acquia.widen.net/content/10bcf0a8-b1c3-4e1f-ae9b-1d4403168387/web/url_4516026ab6fd8c0c0e9bbe3a343264ef.png) I'll take that, thank you ------------------------- Then we create a feature branch to work on a new issue. `(you) $ git checkout -b feature` ![Diagram showing "main" branch with nodes 1, 2, 3, and "feature" branch diverging from node 3.](https://acquia.widen.net/content/106064fa-2bba-46be-8299-6b25b283d2b5/web/url_7dca51bb2a6d75f52b129db20c9d7d99.png) So long, suckers! ----------------- We do some work and commit our changes. `(you) $ [code, commit, etc.]` ![Diagram showing two branches, "main" and "feature," with nodes 1, 2, 3, A, B, C. Blue and yellow circles represent nodes.](https://acquia.widen.net/content/04826c6b-a18f-48f0-a4e2-ee39a71958b6/web/url_db6686086bdddb4cbd1a5d6f4fbd277f.png) Touché ------ But in the meantime, the upstream repository commits changes, too. Now we've diverged. `(you) $ git fetch [remote]` ![Flowchart with two branches: "main" (1-5) and "feature" (3-A-B-C). Blue and yellow circles represent nodes.](https://acquia.widen.net/content/becd464b-3d94-43ae-954b-0ae9f1d00acd/web/url_ea4b973e1491b72bc8f61d25959e230b.png) Let's do this thing! -------------------- Time to rebase. `(you) $ git rebase main` ![Diagram of a Git branching model with "main" and "feature" branches, showing commits 1-5, A-C.](https://acquia.widen.net/content/98af3c2a-64e2-4a9e-869a-1f6a29dfabb1/web/url_357793fd87abe2503c54cbf7ef61abcd.png) Shhh! This part's a secret -------------------------- Under the hood, Git creates an invisible working branch and checks it out, putting us into a kind of magical in-between state. `(git fairies) $ git checkout -b REBASE main` ![Git branching diagram showing main and feature branches, with a rebase merging commit 5 into the feature branch.](https://acquia.widen.net/content/2491ef89-8ad7-4a1e-a67f-4922633e4644/web/url_3c8ab461d78192b572ded83f34c798e8.png) Yoink! ------ Then it begins to "replay" the commits on the new branch. It finds the first one we have that our base branch doesn't and cherry-picks it. `(git fairies) $ git cherry-pick [A]` ![Diagram showing a Git branching model with main, feature, and rebase branches. Nodes labeled 1-5, A-C indicate commits.](https://acquia.widen.net/content/f56739f8-5014-43fc-ad0b-fdfcddd55685/web/url_cd3e3b356235ffc1d61c56ee3b173be3.png) Oh noes, merge conflicts! ------------------------- If there are merge conflicts, it stops and asks us to resolve them. ![Git branching diagram with main and feature branches, showing a rebase. Main has commits 1-5; feature has commits A-C.](https://acquia.widen.net/content/ab75ef20-1cfd-4566-857e-c7ab35a758c4/web/url_a4b5ee7e1156e8a7173597a101538683.png) Okay, carry on -------------- Once we do, we hand it back to Git to continue the process. `(you) $ git rebase --continue` ![Git branching diagram showing main and feature branches, with commits. Feature branch is rebased onto main, aligning commits A, B, and C.](https://acquia.widen.net/content/c4dc7ad2-6235-407d-86ed-84049d9ea427/web/url_1626a7f7e0e24b725d55aa283ee319df.png) Next, please ------------ It proceeds to the next commit and cherry-picks it. `(git fairies) $ git cherry-pick [B]` ![Git rebase diagram showing branches: main (1-5) and feature (3, A-C) with rebase onto main after commit 5.](https://acquia.widen.net/content/4f2224b4-602b-43d4-b9a9-e85041b6e16c/web/url_e433fc76121b2879b5a465b379140725.png) More conflicts?! (facepalm) --------------------------- If there are merge conflicts again, it stops and asks us to resolve them, just like before. ![Git branching diagram showing main and feature branches with commits. Rebase combines feature commits into main, altering commit history.](https://acquia.widen.net/content/d2ab9174-c903-421b-b77e-e500fd86c1d3/web/url_2c2a742af84a5ab0054e4da063342ec5.png) Grumble, grumble... ------------------- And, just like before, we do so and hand it back to Git to continue. `(you) $ git rebase --continue` ![Diagram showing a Git branch rebase. "Main" branch merges into "feature" branch, aligning commits.](https://acquia.widen.net/content/080336c6-5c1b-4663-a750-0e698aa4a164/web/url_8345765c4190506a94d7dfdde024cadc.png) You get the picture ------------------- The process continues until all of our commits have been copied over. `(you and the fairies) $ [...]` ![Flowchart illustrating a Git rebase process. Main branch progresses to 5, feature branch rebases, aligning commits A, B, C after main's commit 5.](https://acquia.widen.net/content/536e24fc-9f80-4a71-9e1f-d6fa08ddd5c4/web/url_f5adabc666c5c50c45191567cce73655.png) Order up! --------- Once it's finished, it overwrites our feature branch with the result and returns us to it. `(git fairies) $ git branch --force feature` ![Diagram showing Git branches: "main" with commits 1-5, "feature" rebased from commit 5, followed by commits A, B, and C.](https://acquia.widen.net/content/281cf51d-51d3-4f32-bd78-4c222ea2d9d8/web/url_6bb6f9959693666793a8103815630b93.png) I was never here... ------------------- Then it deletes the hidden REBASE branch. `(git fairies) $ git branch -D REBASE` ![Flowchart of a Git branching model with "main" and "feature" branches, showing commits 1-5, and A-C.](https://acquia.widen.net/content/243afe39-bb74-4e0d-957d-fb32d87ce64f/web/url_2b02484662947cbc7b1389d2aa7a99b4.png) And we're done! Our commits now start from the current tip of the base branch, as if we had branched from there to begin with. Go ahead: take a bow.