How to Rebase in Git: Explained Step-by-Step

Rebase is a powerful Git utility that facilitates software engineers, developers, and programmers to simplify the merge process. Whether it is your first time using the rebase Git command, or have issues completing a rebase, it can be challenging at the beginning if you are not used to rebasing.

In this article we are going to explain what rebase does in Git. Then, we will show you the steps to follow when starting a rebase in Git. Finally, we will explain the reasons why you should consider using the rebase command more often.

How Git rebase Works

Git rebase is the process of updating a series of commits of an existing branch to a new base commit. Unfortunately, explaining Git concepts doesn’t make too much sense or is hard to understand without a proper visualization of a git tree diagram. Hopefully, the following diagram will help you understand what git rebase does.

Explanation of what git rebase does

During software development, it is typical to have a master or a main branch and multiple feature branches. Whenever we create a feature branch, the feature branch is created off of a specific branch, typically the latest commit of the master branch.

As there are more people working on a project, other feature branches are created. Let’s say, you created feature branch A, and someone else created feature branch B. In this scenario, we are going to assume someone in the team has finished their development in feature B branch. Hence, it is normal for that person to merge the feature B branch to the master branch to update the main codebase typically used for production deployments.

Meanwhile, you have been working in feature A branch. However, since there are new changes in master branch after merging feature B branch, feature A branch no longer has the latest changes from master branch. Hence, in case you decide to merge feature A branch to master, there is a possibility of running into conflicts.

If you use the rebase command onto master branch, you will update feature A branch base commit. In other words, you would get all of the latest changes from master branch in feature A branch as if those commits happened first prior to you making commits to feature A branch, making sure feature A branch is up to date with master branch.

The rebase commands have different configurations that can be used prior to starting rebasing. However, to start a rebase the only thing you should know is the name of the branch you are rebasing onto.

git rebase <branch rebasing onto>

Steps to rebase in Git

Now that you understand what the rebase does in Git, we will show you the steps to follow when starting a rebase. For the sake of making it simpler to follow, we are going to have as a reference the following diagram.

Example of a repository with a login-page branch

*Notice in the git tree structure we have a login-page branch and a master branch.

These are the steps to rebase a branch in Git.

1. Checkout feature branch

Make sure to be in the feature branch that you want to rebase.

git checkout login-page
Check out the login-page branch

2. Pull feature branch latest commits

We are going to pull the latest commits of the feature branch from the remote repository, even if you think you already have the latest commits in the local repository.

git pull

3. Remove any unstaged commits from feature branch (optional)

There might be changes in the local repository that have not been committed yet. If that is your case you have a couple of options. Either reset the branch and delete those changes or stash them.

I typically stash the changes in case I need to those changes after rebasing the branch unless I have added some logs to facilitate debugging.

git stash

4. Checkout branch you are planning to rebasing onto

Switch the current branch to the branch you are planning to rebase onto. It is common to rebase onto master branch. However, you can rebase to any other branch as well. For this tutorial, we will checkout master branch.

git checkout master
Check out the master branch

5. Pull latest commits of branch you are planning to rebase onto

Pull the latest commits of the branch you are planning to rebase onto from the remote repository. This step is very important as it will use the last commit from that branch to set a new base commit of the feature branch.

git pull
Pulling latest changes from the master branch

6. Checkout feature branch

After getting the latest commits of the branch you are rebasing onto, you are going to switch back to the feature branch

Checkout the login-page branch after pulling the latest from the master branch

7. Start rebase

Start to rebase in the feature branch by using the name of the branch you are rebasing onto.

git rebase master

8. Fix conflicts during rebase or skip to continue rebase, or abort the rebase (optional)

There can be conflicts that need to be resolved during a rebase. If you run into conflicts, the terminal will display a message starting with the word CONFLICT Merge conflict in followed by the path of the file with conflicts.

Open the file and resolve conflicts. Once conflicts are resolved, make sure to stage the file.

git add ./path/of/file/with/conflicts

Verify the conflicted files are staged using the status command.

git status

After that, make sure to to not commit those changes. Instead, you want to continue the rebase as the rebase hasn’t finished yet.

git rebase --continue

In the case you don’t want to bypass the commit that caused the conflict, you can skip it.

git rebase --skip

Finally, you can always opt to

10. Once you finish rebasing, DO NOT pull, but push immediately to remote

You will see the rebase is completed because the terminal will throw the following message:

Successfully rebased and updated

At that point, the feature branch in your local repository is rebased. Hence, the base commit of the feature branch is updated. However, the feature branch in the remote repository still doesn’t have the base commit updated.

If you decide to pull the latest commits from the remote repository, it will cause conflicts, as the base commits from both repositories, are not the same. Therefore, we need to force to push local repository commits to remote.

It is highly recommended to use --force-with-lease than to use --force when pushing to remote after a rebase as --force overwrites the remote branch with a local branch. While in theory --force-with-lease has a similar outcome, it is a safer option as it won’t overwrite any commits on the remote branch that someone else might have added while you were rebasing. This will save headaches in case you overwrite someone else’s code and have to find out what was overwritten.

git push --force-with-lease

*In case the push --force-with-lease fails, my recommendation is to do a hard reset of the feature branch in the local repository to match the remote repository. Then, start the rebase all over again.

Reasons why you should rebase more often

Adopting the usage of the rebase command can have positive effects when done correctly. Here is a list of some of the benefits when you and your team rebase more often

  • It allows to maintain a linear project history
  • Rebase allows for safer/simpler merges
  • Prevent the possibilities programmatic test from failing after merging
  • It reduces merge conflicts
  • Rebase helps to keep up to date commits from on another branch as you work in your local feature branch

The Dangers of Rebasing

Just like any other tool, there can be dangers of using it when not done correctly, and rebasing is not the exception. Here are some problems you can face when using rebase.

  • Rebase can rewrite the commit history as you can’t update remote using only push, but instead you have to force push
  • There could be a lot of merge conflicts during a rebase if a branch is not rebased often

Conclusion

All in all, rebase is a powerful tool not many developers are aware of or not sure how to use it as it helps to keep commits up to date in relation to another branch, reducing and even removing the existence of merge conflicts. However, using the rebase command can have negative effects if the developer is not sure of how to use it as contrary to merging, rebase doesn’t preserve the commit history.

Interested in Learning more about Git?

I wrote other articles explaining how to use other git commands, and I thought you might be interested in reading some of them since you are reading this.

Did you like this article?

Share your thoughts by replying on Twitter of Become A Better Programmer or to personal my Twitter account.