An Introduction to Git Rebase: A Tutorial

A month ago, I posted on twitter that I was learning git rebase at work and how scary it felt.

It got a lot of engagement from people feeling similarly about rebasing and some in the same boat as me where they felt that they didn't understand it.

A month later, practicing, watching A LOT of videos on it and rebasing almost every day, it's not so scary anymore. So I wanted to write up a tutorial on the best way I understand it in hopes that it helps you, too.

Git Rebase

The first thing to understand about git rebase is that it's designed to integrate changes from one branch into another branch. Rebasing will take all of the commits you've made on your feature branch and move them on top of the master commits that other team members have made while you were working in your branch. As a result, you'll have a nice clean tree, like so in the image, where my_awesome_feature_branch is your branch after rebasing with the master branch.

Here's HOW to Rebase

Let's say that that you got assigned to work on a really awesome feature on a massive project. This project is called The Really Cool Project. The first thing you'll always want to do is make sure that the local master is in sync with your remote master branch.

1. Open up your terminal, go into the project folder, and on your local machine, you'd want to run

git pull

Your local master branch should be up to date with the remote master.

1. Next, you'll want to checkout into a new branch so that you can work on your feature without disrupting the master branch.

Run the following command

git checkout -b my_awesome_feature_branch

Now you should be in your feature branch, ready to build that awesome feature for your project.

You've decided that you want to add and style the title of this feature. So you make a commit within your branch

git add .
git commit -m "feature/add-title"
git push origin my-awesome-feature-branch

Your local branch now looks like this

After making your first commit, you continue to work in your feature in your branch, adding more code and making progress on this cool project. You make another commit so your branch now looks like:

While you're working on your awesome feature, the rest of the team is working on some cool features too and they're merging their features to the remote master branch. Your teammate built a cool NavBar and finished it in two days, so it got merged into the remote master, while your other teammate built a cool Footer feature and it's also merged into the master branch. The git tree now looks like

The remote master is not in sync with your local master anymore. And your feature branch is now behind and doesn't have the latest changes made in the development environment. You add another commit to your branch and decide that you're ready to merge your feature with master.

What you need to do now is rebase so that your feature branch is in sync with the remote master and that you're up-to-date with the latest changes to the master. This is the flow you'd want to run:

git checkout master
git pull

I now have all of my teams changes on my local branch

Time to REBASE!

So now I want to make sure that my feature branch will also be in sync with those changes so I'll check back out to it.

git checkout my-awesome-feature-branch
git rebase master

What just happened is that your changes have been integrated with the latest master branch. Assuming that you don't have any conflicts in your files, you're ready to merge into master. If you DO have a conflict in your branch, git will let you know and you'll have to resolve those conflicts. Usually those happen when you and another developer worked on a feature that required you to make changes in the same file.

Follow Up Reading:

• Official Git Documentation

Comments

[Michael Currin]

Note that if you are rebasing on a remote master, you have to do a pull first, as in the tutorial. Which is tedious to do regularly.

git checkout master
git pull
git checkout my-feat
git rebase master

You can also do it this way, without updating local master.

git checkout my-feat
git fetch
git rebase origin/master

Or simply, in even fewer commands

git checkout my-feat
git pull --rebase origin master

Then do

git push 

Implied to be

git push origin my-feat

Note that all the approaches here have the same outcome. And they are safe to do repeatedly and doesn't require a force push. As they only rebase unpushed commits, which is the golden rule of rebasing. See article for more info that rule.

[Zahra Khan]

This is amazing, thank you!

[Andrey Kondratyuk]

Quick question: after you checkout and pull the master branch, you have all of the code from both branches in your code editor right? If there is a code conflict at this point, don’t you have to choose which version to keep?

Is the goal of rebase to make it easier to make sense of each individual commit and make undoing a change easier?

The art/diagrams are great btw.

[Zahra Khan]

Hey! Great question!

When you checkout and pull down code from the master branch, you have all the code from the remote master (which is everything everyone else is working on) into your local master branch so your branch matches and is up-to-date with the all the work that's being merged into the project as a whole.

I haven't experienced a code conflict with master/develop branches because when you're working in a feature branch, before merging, the team has to review it to make sure there aren't conflicts. BUT hypothetically, if there IS a conflict, you have to choose which change you'd like to keep. I've experienced conflicts in my feature branch, and then I have to decide which change makes sense to keep.

Conflicts are still something I'm terrified of haha and practicing solving to get better at so I wish I had a better explanation for it.

The goal of rebase is to have a cleaner branch history and keeping track of the commits you're making.

I hope this helps! Lmk if I made any sense haha

Thanks btw, appreciate it!

[Andrey Kondratyuk]

Yup, that really helps. Thank you.

[Fabiana Asara]

A nice and simple explanation of rebase !!
Thanks 🙌🏻

[nouman shah]

Great and Useful..

[simonas88]

Here's an idea for the next article: try to rebase a branch which is an indirect child of master onto master

[pratik-sinha]

What if I just pull the master branch in my feature branch won't I get the latest updates?

[Zahra Khan]

Sure but every time I've done this I've also gotten other peoples commits and updates in my feature branch when I did a force push. This could be difficult to keep track of your commits and the work you did. Especially if you're asking your team to review your code.