In the previous lesson we used git rebase for one thing only: changing a branch's base. But the mechanism underneath — breaking a branch down into a list of commits and applying them again one by one — allows a great deal more if somebody lets you edit that list before it runs.

That is git rebase -i. Git opens a text file containing the commits it is about to reapply, one per line, and waits for you to decide what to do with each: leave it as it is, change its message, join it with the one before, split it in two, move it somewhere else or delete it. When you save and close, Git carries out your instructions to the letter.

It is the tool that turns a real branch — with its second thoughts, its backtracking and its wips — into a sequence of commits somebody else can read and understand. Bruno needs it right now: his feature/csv-export branch has six commits, three of them called fix, wip 2 and wip 3, and he wants to publish it for review.

And with it comes back, stronger than ever, the golden rule: interactive rebase rewrites commits, so it applies only to work you have not yet published (or to a published branch that only you use and about which you can warn people).

1. What the to-do list is
2. The available commands
3. The starting point: Bruno's branch
4. A full session: from six commits to two
5. squash versus fixup
6. Reordering and removing commits
7. Splitting a commit in two with edit
8. Changing just a message with reword
9. --autosquash: commit --fixup and commit --squash
10. --exec: validating every commit
11. break, label, reset and merge
12. What to do if you get lost halfway

When you launch an interactive rebase, Git prepares the list of commits it is going to reapply and opens it in your editor:

Three details to take in before touching anything:

• The order is chronological ascending: the oldest commit at the top. That is the opposite of git log, which shows the most recent first. This inversion is beginners' number-one source of mistakes.
• The lines run from top to bottom. Reordering lines reorders commits.
• Deleting a line is the same as drop: that commit disappears. Git warns you in capitals for a reason.

And a point about the argument: git rebase -i main means "reapply onto main everything that is on my branch and not on main", just as in the previous lesson. If you only want to touch the last N commits of the branch you are on, without changing the base, you use:

Careful with that second one: git rebase -i <commit> does not include <commit> in the list, because <commit> is the base. To touch the last four commits, the base is the fifth counting back from the end: HEAD~4.

If your default editor is not the one you want, you change it with git config --global core.editor "code --wait" (or nano, vim, whatever you use). It was explained in lesson 01-05, and here you will be grateful for it.

The first four cover 95% of real use. drop and exec turn up from time to time. break is a convenience. label, reset and merge only appear when you use --rebase-merges to rebuild a history containing merges, and we shall not need them day to day: it is enough to know what they mean if you come across them.

A note on squash and fixup: they join with the previous commit in the list, that is, with the line above. That is why they can never be the first line (there is nothing to join with) and why the order matters so much.

Bruno has spent a week on exporting tasks to CSV. The branch works, but the history is a shambles:

With --stat you can see what is really in each one:

Read calmly, the branch does two independent things:

1. A function that converts the task list to CSV and downloads it (app.js): commits 1, 3, 4, 5 and 6.
2. A button in the interface that calls it (index.html + styles.css): commit 2.

Bruno's aim is to end up with exactly those two commits, in that order, with messages that explain what they do. And the important part: the final content of the branch is not going to change by a single line. A well-executed interactive rebase reorganises how the story is told, not what ends up there.

That is the hash of the tree at the tip of the branch. When the rebase finishes it must be the same. It is the best quality control there is for this operation.

Bruno launches the interactive rebase:

And edits the list that appears. The first job is to reorder so that what belongs together sits together, and then to decide the command for each line. This is how the file looks before saving:

Read it from top to bottom like a recipe:

1. pick b1c4f80 — apply the first commit as it is. It will be the basis of the final export commit.
2. squash c8f2b47 — join it with the previous one, and let me combine the messages.
3. fixup 2a7f4c1 — join it with the previous one and throw its message away (fix contributes nothing).
4. fixup 9e3b8d6 — the same with wip 2.
5. fixup 5c1a9f2 — the same with wip 3.
6. pick 3d6e9a1 — the button commit, moved to the end, stays as it is for now.

On saving and closing, Git starts running. At the squash step it stops and opens the editor with the two messages:

Bruno deletes all of that and writes a decent message:

He saves, closes, and the rebase carries on. The three fixups ask nothing. At the end:

The second one's message still needs polishing, but we shall see that in section 8. First, the check we promised:

Identical to the one from before the rebase. The branch's content has not changed; only its history has. That is the guarantee that makes this operation reasonable rather than reckless.

Both join a commit with the previous one. The only difference is in the message, but it determines which to use in each case:

In practice: if the message of the commit you are absorbing is worth anything, squash; if it is rubbish (fix, wip, now it works, semicolon), fixup. And since a squash of five commits forces you to clean up five messages by hand in the editor, as soon as you have three or more it usually pays to use fixup on all of them and write the message once with reword.

You have already seen reordering: in Bruno's session, moving 3d6e9a1 from second position to last was enough to group the work by topic.

Removing is just as straightforward: put drop in front of the line, or delete the line entirely. The two forms are equivalent; drop is preferable because it leaves a visible record of the intention and avoids deleting a line by accident:

Two warnings that apply to both operations:

• Reordering and removing can cause conflicts. If commit c8f2b47 modified a line that b1c4f80 had just created and you separate them, the second one no longer finds the context it expected. It is resolved like any rebase conflict (lesson 05-01): resolve, git add, git rebase --continue. Remember that the ours/theirs sides are still inverted.
• Removing a commit from the middle leaves the branch with fewer changes, not necessarily with less code that is needed. If you drop the commit that created a function and keep the one that calls it, the branch no longer builds. --exec (section 10) exists precisely to detect that.

This is interactive rebase's star turn and the one that impresses most the first time. Suppose Bruno looks at d72e6b8 and decides it mixes two things: the function that generates the CSV and the one that triggers the download. He wants to split it.

Step 1: mark the commit with edit.

Git applies the commit and stops:

Step 2: undo the commit but keep its changes.

This is what does the magic: git reset with no options (equivalent to --mixed) moves HEAD one commit back and leaves all the changes in the working tree, unstaged. The commit has gone; its content is still in the file. It is the only appearance of reset in this module; its three modes and its use as an undo tool are studied thoroughly in lesson 09-02.

Step 3: stage and commit in parts. This is where git add -p comes in, which you learned in lesson 02-04: staging only some hunks of the file.

Bruno accepts with y the hunks belonging to the tasksToCSV function and rejects with n those belonging to downloadFile. Then:

And the rest:

Step 4: carry on.

One commit has become two, without losing a line. Note that the commit after it (a3f9c14 → f04b7e2) has changed hash too: by inserting commits before it, its parent is a different one, and you know by now what that implies.

Trick: if when you run git reset HEAD^ you realise the split is not clean (the changes are interleaved within the same function), you can edit the files by hand before each commit. You are not obliged to make each half an exact subset of the original; only to make the end result the same. Verify it with the rev-parse HEAD^{tree} trick.

The button commit's message is terse and says nothing about where the button goes. To change only the message, without touching anything else:

Git applies the first two, and at the third it opens the editor with the current message. Bruno changes it to:

He saves, closes, and that is that:

Three commits, three messages that explain what each one does, and a branch ready to publish and to be reviewed.

A note for the most frequent case: if the commit you want to rewrite is the last one, you do not need an interactive rebase. git commit --amend (lesson 02-04) does the same with less ceremony. reword is for the ones further back.

What makes a good commit message — the imperative, the subject line, the body, the trailers — is the subject of lesson 08-01. Here we are concerned only with the mechanism of changing it.

There is a far more comfortable flow than marking fixup by hand, and it consists of deciding it at the moment you make the commit, while you still remember which commit it is correcting.

Imagine Bruno is working and spots a typo in commit 6e1d9f3, which he made two days ago. Instead of creating a commit called fix:

Git has created an ordinary commit, but with a special message: fixup! followed by the subject of the commit it corrects. That prefix is a marker Git knows how to interpret.

And now for the pretty part:

The list that appears comes already ordered and with the commands filled in:

Bruno only has to save and close without touching anything. Git has moved the correcting commit right behind its target and marked it as fixup.

So that you do not have to remember --autosquash every time:

And a warning: --autosquash pairs commits by the text of the subject, not by the hash. If two commits on the branch have exactly the same subject, the pairing can be ambiguous. In practice it almost never happens, and you can always review the list before saving (which is exactly what the editor is asking you to do).

This flow — work, correct with --fixup, and flatten everything with a rebase -i --autosquash just before publishing — is probably the most productive way to use Git day to day. It frees you from thinking about the history while you are programming, and lets you tidy it up in one go at the end.

A clean history that does not build is worth nothing. When you reorder, join or split commits, it is easy for an intermediate one to end up broken: the one that calls a function that does not exist yet, the one that imports a module which arrives two commits later.

--exec runs a command after every reapplied commit and stops the rebase if the command returns a non-zero exit code:

Git automatically inserts an exec line after each pick:

If the second npm test fails:

The rebase stops at that point, with the repository in exactly the state of that commit. You can fix whatever it is, run git commit --amend, and carry on.

You can also write the exec lines by hand wherever you like, instead of after every commit. And it does not have to be a test suite; any quick check will do:

That last line is a small guard: it fails if there is a forgotten console.log left. Automating this sort of check permanently, so that it runs by itself on every commit, is the subject of hooks (lesson 06-01).

Three less frequent commands, but it is worth recognising them.

break stops the rebase at that point without doing anything else. It is a deliberate pause:

Useful for looking at the state of the project in the middle of the sequence, running something by hand or simply drawing breath. You carry on with git rebase --continue.

label, reset and merge only appear when you use git rebase -i --rebase-merges, which rebuilds a history preserving its merge commits instead of flattening it. Git then generates a list looking like this:

It reads like this: label X saves a marker at the current point, reset X goes back to that marker, and merge -C <sha> X creates a merge commit with the branch marked as X, reusing the message of commit <sha>. It is a small language for describing a graph. You will hardly ever need it; it is enough not to be alarmed if it turns up.

A long interactive rebase can turn into a maze: four conflicts, an edit half done and the feeling of not knowing where you are. Ways out, from the least to the most drastic:

1. Ask where you are. git status during an interactive rebase is extraordinarily informative:

It tells you what has been done and what is left. The live list is also in .git/rebase-merge/git-rebase-todo, and git rebase --edit-todo opens it so you can change what remains to be done without aborting. It is the elegant way out when you realise halfway through that you planned badly:

2. See what is failing right now.

It shows the commit being applied, with its full diff. Very useful when the conflict makes no sense at first glance.

3. Abort.

It undoes the whole rebase and returns the branch to its original state, with the original hashes. It is safe, it is instantaneous and it leaves no trace. When in doubt, abort: replanning the list with a clear head takes two minutes; untangling a badly handled rebase, much longer.

4. If you have already finished and the result is a disaster. This is where the safety net comes in: the original commits are still in the object database and the reflog records where your branch was before you started. The full procedure for going back is the subject of lesson 09-04. And the same cheap reflex as always, which saves you having to use it:

Mistake 1: reading the list as though it were git log. In the editor, the oldest commit is at the top. Marking squash on the wrong line because of this inversion is mistake number one.

Mistake 2: putting squash or fixup on the first line. There is no previous commit to join with and the rebase fails before it starts. The first line is always pick, reword, edit or drop.

Mistake 3: deleting a line by accident. That commit disappears. Use an explicit drop when you mean to remove one, and if you delete a line by mistake, close the editor without saving: Git aborts the rebase.

Mistake 4: interactively rebasing a branch that is already published and shared. The golden rule has no convenient exceptions. If other people work on that branch, do not rewrite it.

Mistake 5: running git commit instead of git rebase --continue after resolving a conflict. Except in the edit flow (where you do commit yourself), the one that creates the commit is the rebase.

Mistake 6: forgetting that a rebase runs the hooks. If you have a slow pre-commit, a rebase of twenty commits runs it twenty times. --no-verify disables it, with the responsibility that implies.

Mistake 7: flattening everything into one gigantic commit "so that it looks clean". A 900-line commit saying "Add the export" is as useless as six commits called wip. The aim is for each commit to be one complete, comprehensible change, not for there to be only one.

Tip 1: check the tree before and after. git rev-parse HEAD^{tree} must match if your intention was only to reorganise. If it does not match, you have lost or duplicated something.

Tip 2: adopt --fixup from today. As soon as you have the reflex of correcting with git commit --fixup <sha> instead of with a commit called fix, the final tidy-up becomes trivial. Enable rebase.autoSquash true.

Tip 3: do small, frequent interactive rebases. Cleaning up five commits is comfortable; cleaning up forty is not. A rebase -i at the end of each day's work on a branch is an excellent habit.

Tip 4: use --exec when you reorder or split. It is the only cheap way of knowing that no intermediate commit has been left broken.

Tip 5: review the list before saving, always. That open editor is not a formality: it is your last chance to see the whole plan before it runs.

When it is worth tidying up and how much — whether the team insists on a linear history, whether each branch is squashed into one commit when it is integrated, whether rewriting is forbidden — is not a technical decision but a matter of team policy, and it is dealt with in lesson 08-02: Keeping a Clean History.

Create a repository with a main branch (one commit) and a feature/report branch with these five commits, in this order:

1. Start the report (creates report.js with a function)
2. Add report styles (creates report.css)
3. more stuff (extends report.js)
4. wip (touches report.js)
5. fix (touches report.js)

With a single git rebase -i, leave the branch with two commits: one with everything belonging to report.js and a decent message, and another with the styles. Demonstrate with git rev-parse HEAD^{tree} that the final content has not changed.

Starting from the result of exercise 1, split the report.js commit in two: one with the data generation and another with the rendering. Use edit, git reset HEAD^ and git add -p.

On a new branch with three commits:

1. Deliberately introduce a syntax error in the second commit.
2. Carry on working and make a third, ordinary commit.
3. Correct the error with git commit --fixup <sha of the second>.
4. Apply it with git rebase -i --autosquash.
5. Launch another rebase with --exec "node --check file.js" and check that all three commits now pass validation.

Solution 1:

The edited list (the report.js commits together at the top, the styles at the end):

Then a second pass for the message (or mark reword on the first line from the outset):

New message: Add the generation and rendering of the report.

The tree matches the one noted down: only the history has changed.

Solution 2:

(The file was new in that commit, so it appears as untracked. If it already existed, it would show as M.)

If git add -p does not offer separable hunks because the file is new, use git add -N report.js first: it registers the file in the index as empty and allows its content to be split into hunks.

Solution 3:

The list comes ready-made; you only have to save:

Had you run it before the --autosquash, the second exec would have failed and the rebase would have stopped at the broken commit.

Interactive rebase is the history repair shop. What we have learned:

• git rebase -i <base> opens a to-do list with the commits that are going to be reapplied, from oldest to most recent, and carries out whatever you write in it from top to bottom.
• The four commands you will always use are pick (leave it), reword (change the message), edit (stop to modify or split) and squash/fixup (join with the previous one, keeping or discarding the message). drop removes and exec validates.
• Reordering lines reorders commits and lets you group by topic what was done out of order; deleting a line removes the commit.
• Splitting a commit is edit + git reset HEAD^ + several git add -p and git commit + git rebase --continue. It is the most powerful operation of the lot.
• git commit --fixup <sha> with rebase -i --autosquash turns the clean-up into a formality: you mark the corrections as you go and Git places them on its own. Enable it with rebase.autoSquash true.
• --exec runs a check after every commit and stops the rebase if it fails: the only cheap way of guaranteeing that no intermediate commit is left broken.
• If you get lost: git status says where you are, git rebase --edit-todo replans what is left, --show-current-patch shows what is failing and --abort undoes it all without a trace.
• git rev-parse HEAD^{tree} before and after is the best verification that you have reorganised the history without altering the content.
• And above all: the golden rule. This is done before publishing.

Rebase and interactive rebase always work with the set of commits on a branch. But sometimes what you need is far more surgical: to take one specific commit from one place to another, leaving everything else where it is.

Ana is going to need it tomorrow. She has fixed a bug on main that causes the focus to be lost when a task is deleted, and it turns out that version 1.x, still deployed at the client, has the same bug and lives on a separate maintenance branch. She does not want to merge the whole of main into it: she wants that commit and nothing else.

That is what git cherry-pick is for, and we shall see it in lesson 05-03: Cherry-Picking Commits.