In Progress
Unit 1, Lesson 1
In Progress

Git Storytelling – Part 2

In the previous episode in this series, guest chef Brooke Kuhlmann showed us how to tell better stories about our code using git interactive rebasing. Today, he’s back to take things a step further. He’ll demonstrate how we can use git’s `fixup` and `rebase` to rewrite the timeline into a more coherent narrative before it’s shared with others.

Video transcript & code

Episode II





If you recall, in the previous episode, we used Git Interactive Rebase to reword several commits that where hard to understand what they were for and why they were important.

Let's take a look at our Git history to recap where we left off:


Those last three commits on the tutorial feature branch are what we reworded in the previous episode. Here's a detailed view:


We can go a step further, though. If you noticed, those last two commits are practically fixups to the original commit on the feature branch. While we made them more descriptive, it would be better to apply those fixes to the original implementation and magically erase away our earlier mistakes!

We can use fixup via Git Interactive Rebase to do this:

git rebase --interactive

There. Now we have a single commit that tells the story of how we implemented this script.


Members of our team now have fewer commits to review. Plus, we have a clean Git history that allows future maintainers to get up to speed faster.

Let's run our implementation again, to double check all is well:

ruby add.rb 4 5

Due to the fact that this repository hasn't been pushed to a remote server or shared with anyone, there is something else I'd like to do. I want to fix the first two commits on the master branch as those commits suffer from the same problems we fixed on the tutorial branch.

Let's start by merging our changes from the tutorial branch onto the master branch:

git switch master
git merge tutorial
git branch --delete --force tutorial

Now that we have a single master branch we can use interactive rebase to fix up our repository and prepare it for public release. This, by the way, is one of my favorite techniques to use before going public.

It's important to note that you should only use this technique on an unpublished repository because when we use interactive rebase on master like this, it would make it incompatible with anyone sharing this repository due to the SHAs being changed. In other words, no one would have a common history to rebase onto.

Again, I can't emphasis this enough, never do this in a team setting or on a master branch that has been shared.

OK, with that word of caution aside, let's begin by looking at those first two commits on the master branch.

cat .gitignore
git diff ^ 

So the first commit is setting up the Git ignore file while the second commit adds an empty add.rb script.

There are two tasks we need to do there. The first commit should be reworded to explain the Git ignore file better while the last commit and the commit we just merged from the recently deleted tutorial branch are really the same thing. So we'll reword the first commit and squash the last two.

To pull this off, we'll pass --root to Git Interactive Rebase which allows us to rebase from the very first commit made to the repository:

git rebase --interactive --root

Added Git ignore file

Allows us to ignore any file with a *.cast extension (i.e. Asciicast)

ruby add.rb 5 2

There. Now, we have repository with our Ruby script that implements adding two numbers together. Our Git history is clean and well written for sharing with the world.

I hope this helps emphasize how your Git commits can tell a compelling story and serve as helpful documentation for yourself and others.

If you take the time write write good commits your team members will enjoy working with you ...and your future self will thank you when your memory fades.

That's all for today.

Until next time...

Happy Hacking!