A gentle introduction to interactive git rebase

Introduction

It may be fair to assume that almost every development team uses git for version control and to collaborate on code. Incorporating git into your workflow for the first time can be quite daunting. Another related challenge is trying to get your head around rebasing. In this tutorial, we will learn a practical beginner’s workflow that utilises interactive rebasing.

Prerequisites

To follow along, you will need to have git installed. You can head to their website and download the version that suits your environment.

If you’re unfamiliar with vim commands, you can check out the little table of commands at the end of this article to get a small crash course.

Thoughts about pull requests

Before we dive into the meat of this walkthrough, let’s take a moment to talk about pull requests. I find it helpful to think about a pull request as if I were documenting a potion recipe that I’d like to eventually pass on to my future self.

Having this mental model helps me organise my commits to tell a coherent story. It helps me decide the sequence and composition of my commits.

Creating a new branch

Beginning a new task means we’ll need to create a new branch. At this point, we can pick our base branch. By default, our base branch would either be the main branch or the develop branch. Occasionally, we may choose another feature branch as our base. Regardless of the base branch we choose, we’ll want to make sure it’s up-to-date before creating our new branch.

For this example, we have decided to base our work off of develop. We can checkout develop and once we’re on develop, we can pull the latest changes:

git checkout develop
git pull --rebase --autostash

The --rebase and --autostash flags are a nice way to avoid conflicts when pulling changes. If you have uncommitted local changes, they are stashed before the rebase.

💡 I personally use the git pull --rebase --autostash command a lot, so I have saved it as an alias called git up. If you’d also like to do this, you can run this in your terminal:
git config --global alias.up 'pull --rebase --autostash'

Once our chosen base branch has the latest changes, we can create our new branch:

git checkout -b feature/potion-for-posterity

Writing commit messages

As we happily code away, we should remember to periodically commit our changes to avoid unexpectedly losing our work. It is a good idea to make small, but frequent, commits. It is also a good idea to group relevant changes under a commit message that is descriptive and applicable. Remember, these are messages we are writing for our future selves, so they should act as documentation.

Calling back to our potion analogy, our commit messages should read like simple instructions for a recipe or a to-do list. Some examples of commit messages could be:

• Add Posterity model
• Add Posterity controller
• Add migration for Posterity
• Add tests for Posterity

We can add and commit our changes by running the following commands and writing our message in the resulting editor:

git add .
git commit

Git allows us to write our commit messages inline by using the -m flag. However, writing our commit message in the editor lets us see when our message has gotten too long. In the screenshot below, we can see that the commit message text has changed colour to let us know we’re exceeded the recommended character limit. There is no rule that requires us to adhere to this character limit, it’s just a personal preference.

💡 Having this length constraint means we won’t have to expand it to see the full message on Github. It’s not a big deal, though, just a matter of preference.

Handling changes coming into the base branch

It is normal to have teammates merging their work into the base branch throughout the course of a work day, especially if the base branch is develop. To avoid potential conflicts later on, we’ll want to make sure we’re keeping up-to-date with the latest changes when we can. It is a good idea to periodically reset our base branch.

To do this, we can commit or stash the changes on our current branch. We can push these changes up to Github just to be extra safe. Once the changes are safe and out of the way, we can checkout our base branch and pull the latest changes. As a reminder, our base branch is develop for this example, but it can be any other arbitrary branch as well.

git checkout develop
git up # alias for `git pull --rebase --autostash`

Once our base branch has all the latest changes, we can switch back to our working branch and rebase against our base branch

git checkout feature/potion-for-posterity
git rebase origin/develop

Interactive rebase

When we use rebase, we can think of it as resetting our base branch. Rebasing helps us keep our commit history clean. As we talked about in the beginning, a PR is a recipe for a potion we’d like to pass along to our future selves or to other developer friends. So it should read like documentation.

A rebase can be done manually or