Git Rebase Explained

Introduction

Rebase is a helpful git command that can be used to turn a branchy two-headed version history into an easy to follow linear one. A linear history is much easier for a human eye to follow and a human brain to understand. Rebase is a very safe command to use, despite some fear that people have about it.

This post should explain how rebase works and clear up any misunderstandings about it.

Rebase Basics

The short summary of rebase is that it cuts commits out of the git history and reconnects them somewhere else.

Let's say the common scenario comes up: you commit a change to the main branch of a repository, you then run git fetch, and in come a couple changes that other people made on the main branch. If your commit is version 46f and the others that just came in on the fetch are versions ef9 and 4a2, your version history might look like this:


The main branch now has two heads, 46f and 4a2. You can run git rebase to disconnect your commit from version d88 and connect it to 4a2. In one simple command the above version history morphs into this nice linear version history:


It's called rebase because 46f was based on d88 and now it is based on 4a2. Simple. Multiple head problem solved. That's all you need to know. If you really want to know more then read on.

Automating rebase

Most git users have been trained to run git pull instead of git fetch. That's because git pull does a git fetch and then usually follows that by a git merge if needed. You can tell git pull to do a rebase instead of a merge like so:

git pull --rebase

Or, you can configure git to always use rebase for git pull by running this command, which is highly recommended:

git config pull.rebase true

Then you don't need to add --rebase to your git pull command.

More Detail

You might be wondering how the rebase command does what it does. You might also have other questions like:

  • Does rebase change your commit?
  • Does it change the other commits (ef9 and 4a2, in our example)?
  • Can anything go wrong?
  • If so, what if something does go wrong?

If so, read on.

How It Works

I'm sure there are some gory details of how it works that I'm leaving out, but essentially rebase just does a merge and then deletes part of the history of the merge so that you get a simple linear history. If we start again with this:


And run rebase, it first does a merge to get this:


Then it removes the original 46f and any pointers to it. That's how you end up with this:


Knowing that, you can see that rebase does in fact change your original commit. If nothing else, your commit gets a new parent pointer. If 46f changed some of the same files that ef9 or 4a2 changed then those changes will have to be merged and there can even be merge conflicts. If that happens you can resolve the merge conflicts however you are used to doing that (I prefer kdiff3). Most rebases (like most merges) don't have any conflicts and it's very nearly a no-op. Just the parent pointer changes.

One thing to note is that the parent pointer change is still significant and that's why there is an asterisk on the new 46f commit. The commit ID will actually not stay the same after a rebase. Git computes the commit id based on the diff, your comments, and the parent(s) of the commit. The rebase command changed the parent of 46f so it will calculate a new commit ID. I left it the same in the diagram so it'd be easy to follow where the commit actually went.

Also note that only the commit(s) being rebased get changed. In our example, ef9 and 4a2 are the destination of the rebase but they aren't touched themselves at all.

If Things Go Wrong

Just like with some merges, some rebases can result in a multitude of merge conflicts or broken compiles or failing tests due to subtle code bugs. Sometimes when that happens you just want to get back to where you were before the merge or rebase. If a rebase goes horribly wrong and you want to abort, your old commits are all still there, they are just hidden by git. If you haven't finished resolving conflicts you can simply type git rebase --abort and everything will be restored. If you have completed the rebase but you remember the commit id of your original commit, you can run git checkout <commit-id> to get git to show you the original commit. If you don't remember the commit id, you can use the git reflog command to find the commit id and use git checkout to make git show it to you again.

Conclusion

Rebase is a very useful and safe git tool that keeps our version history clean and easy to understand. You can automatically use rebase for every git pull that you do by configuring git with this command:

git config pull.rebase true

Comments

Post a Comment

Popular posts from this blog

SystemVerilog Fork Disable "Gotchas"

This is a long post with a lot of SystemVerilog code. The purpose of this entry is to hopefully save you from beating your head against the wall trying to figure out some of the subtleties of SystemVerilog processes (basically, threads). Subtleties like these are commonly referred to in the industry as "Gotchas" which makes them sound so playful and fun, but they really aren't either. I encourage you to run these examples with your simulator (if you have access to one) so that a) you can see the results first hand and better internalize what's going on, and b) you can tell me in the comments if this code works fine for you and I'll know I should go complain to my simulator vendor. OK, I'll start with a warm-up that everyone who writes any Verilog or SystemVerilog at all should be aware of, tasks are static by default. If you do this: module top; task do_stuff ( int wait_time); #wait_time $display ( "waited %0d, then did stuff" , wa...
Read more

'git revert' Is Not Equivalent To 'svn revert'

I just learned that if you have some changes in your working tree that you want to get rid of, you don't type 'git revert' like you might guess. No, that's what cvs, subversion, mercurial, and bazaar (to name a few) use revert to mean, but not git. With git, revert is used to undo actual commits. Thankfully, you can undo your revert with another 'git revert', I just learned. So let me repeat to be clear, if you have changes to your working files that you want to abandon, DO NOT do this: git revert HEAD That will undo your last commit. Do this instead: git reset --hard HEAD I'm glad I have that straightened out now. I'm wondering if /etc was really a good place for me to start out playing with git. UPDATE: Nearly two years later and I'm still getting comments on this. I'm glad I've been able to help people out this way. The discussion in the comments is good, and one thing I'd like to point out is that I now always use...
Read more

SystemVerilog Streaming Operator: Knowing Right from Left

SystemVerilog has this cool feature that is very handy for converting one type of collection of bits into another type of collection of bits.  It's the streaming operator.  Or the streaming concatenation operator.  Or maybe it's the concatenation of streaming expressions (it's also called pack/unpack parenthetically).  Whatever you want to call it, it's nice.  If you have an array of bytes and you want to turn it into an int, or an array of ints that you want to turn into an array of bytes, or if you have a class instance that you want to turn into a stream of bits, then streaming is amazing.  What used to require a mess of nested for-loops can now be done with a concise single line of code. As nice as it is, getting the hang of the streaming operator is tough.  The SystemVerilog 1800-2012 LRM isn't totally clear (at least to me) on the details of how they work.  The statement from the LRM that really got me was this, "The stream_operator <...
Read more