Demystifying git rebase: A workshop

Practical guide to learn about the git rebase command with a poem.

Image credit: **professortocat_v2 from **GitHub Octodex

git rebase is the process of reapplying commits on top of another base tip.

Birth of an idea

The git rebase command is quite complex and after several discussions during team meetings we discovered that some of us did not know how to use it properly. We were often avoiding the git rebase command out of fear, since this command can lead to all kinds of trouble if not used properly.

Some of the team members are working with git GUI clients, such as SourceTree or GitKraken, to work with a visual representation of their repositories. Some don’t know advanced use of some commands.

So, we decided it would be a good idea to organize a workshop to learn this all together since most of us had knowledge gaps on this similar subject.

I really wanted this to be less scholar and more fun, so I volunteered to create a hands-on workshop for the team.

I thought about using a poem. “The road not taken”, by Robert Frost.

Two roads diverged in a yellow wood,
And sorry I could not travel both
And be one traveler, long I stood
And looked down one as far as I could
To where it bent in the undergrowth;

Then took the other, as just as fair,
And having perhaps the better claim,
Because it was grassy and wanted wear;
Though as for that the passing there
Had worn them really about the same,

And both that morning equally lay
In leaves no step had trodden black.
Oh, I kept the first for another day!
Yet knowing how way leads on to way,
I doubted if I should ever come back.

I shall be telling this with a sigh
Somewhere ages and ages hence:
Two roads diverged in a wood, and I —
I took the one less traveled by,
And that has made all the difference.

Preparation

I simulated the work of a team contributing to the same poem, like so:

Each branch corresponded to a poem’s paragraph or a small part.

The different branches contained bad commits (in red), and commits to rearrange (in yellow).

The objective of the workshop was to recompose the full poem branch after branch, using the git rebase command. Commands, such as the git cherry-pick command, were forbidden.

When creating the workshop, one commit corresponded to only one line of the poem.

“P1/L3” was the line of the poem from paragraph 1 line 3: “And be one traveler, long I stood”.

The objective was to make it easier to resolve conflicts. They often occur when changes are made to the same line of a file.

To resolve a merge conflict, we usually have to choose which changes to incorporate, so I indicated the number of the line for each line of the poem (see below).

The poem was an excuse to use the git rebase command. The workshop was not focused on conflict resolutions.

The workshop

Each member of the dev team set up their environment, cloning the repository:

https://github.com/coralieco/workshop-git-rebase

This workshop is a practical guide to train on a complex command using git rebase. Everyone was allowed to read the documentation or to ask help live. It was not a competition, but the workshop had to be completed in one hour or less :)

We started the workshop together, rebasing the first paragraph as a first example. This was to make sure everyone understood the rules and the methods to go along with the rest of the workshop.

Then, everybody had to complete the workshop. Using the git rebase command, and more particularly the — interactive option.

From documentation:

With the interactive rebase tool, you can then stop after each commit you want to modify and change the message, add files, or do whatever you wish. You can run rebase interactively by adding the -i option to git rebase. You must indicate how far back you want to rewrite commits by telling the command which commit to rebase onto.

There is one option I particularly liked, so I suggested to the team to use it to rebase the poem into paragraph 4 without rebasing it into the parent paragraph (see diagram below) : git rebase -onto

git rebase documentation)

As there was different levels of progression in the team, I corrected one paragraph every 10–15 minutes approximately, so everyone could follow.

At the end, I sent a detailed correction of the commands I used to reconstitute the poem. Some of the dev team members felt the need to redo the workshop at home in order to really benefit from this exercise.

Conclusion

• Git rebase interactive gives us the opportunity to alter individual commits.

• Git rebase is great to maintain a linear project history, clean and meaningful, we must not be afraid to use it :)

• Practical workshops are really successful to learn a new subject: we were not petrified to use it on Appaloosa project.

Overall, we were all happy of the format. We all enjoyed spending this time together and we would like to continue organizing similar workshops in the future.

Thanks to Appaloosa Team!
This article was written by Coralie Collignon of Appaloosa’s dev team.