Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 78 ยท Rewriting History

Interactive Rebase

Master git rebase -i: pick, reword, edit, squash, fixup, drop and exec, reorder commits, script the todo list with GIT_SEQUENCE_EDITOR and clean up a branch before review.

Real work is messy. You commit "WIP", then "fix typo", then "oops, forgot a file", and by the end your branch tells a story nobody wants to review. Interactive rebase is the editor for that story. It lists the commits of a range as a plan (the todo list), lets you change the plan, and then replays the commits accordingly: reorder them, merge several into one, reword a message, stop to edit a commit, or drop one entirely.

If you have not read Rebasing, do that first: interactive rebase is the same replay machinery with a plan you can edit, and the same golden rule applies. Only rewrite commits that are yours and not yet shared.

Starting an interactive rebase

You name the commit just before the first one you want to change:

TEXT
git rebase -i HEAD~4      # the last four commits
git rebase -i main        # every commit on this branch that is not on main
git rebase -i --root      # everything, including the first commit

Git opens your editor with one line per commit, oldest first (the opposite of git log):

TEXT
pick 1a2b3c4 # Add login form
pick 5d6e7f8 # WIP
pick 9a0b1c2 # Fix typo
pick 3d4e5f6 # Add validation

# Rebase 8e9f0a1..3d4e5f6 onto 8e9f0a1 (4 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup [-C | -c] <commit> = like "squash" but keep only the previous
#                    commit's log message, unless -C is used ...
# x, exec <command> = run command (the rest of the line) using shell
# d, drop <commit> = remove commit

(That block is read-only: it shows what an editor window looks like. The exact comment text varies a little between Git versions.) You edit the words at the start of the lines, save and close the editor, and Git carries out the plan from the top to the bottom. If you delete a line, that commit is dropped. If you delete everything, or leave the file empty, the rebase is cancelled.

Working in our sandbox: GIT_SEQUENCE_EDITOR

There is no interactive editor in this tutorial's runner, and in real life you often want to automate a rebase in a script. Git calls an "editor" program with the todo file as its argument, so you can supply your own program. The variable GIT_SEQUENCE_EDITOR names the editor used just for the todo list (while GIT_EDITOR is used for commit messages). A tiny script that prints the plan lets us look at it:

Bash See the todo list Git produces

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The plan lists the four commits oldest first, each starting with pick followed by the short hash and the subject. Because our fake editor changed nothing, every commit was picked as it was and the rebase finished without rewriting anything meaningful. (Hashes of re-applied commits stay the same if the parent and content are identical.)

From here on we will use sed inside a small editor script to change the plan. That is the same as you typing in the editor, only repeatable. In practice you edit the file by hand.

The commands

Command Short What it does
pick p keep the commit as it is
reword r keep the changes, stop to edit the message
edit e stop after applying the commit so you can change it (amend, split)
squash s merge into the previous commit and combine both messages
fixup f merge into the previous commit and discard this commit's message
drop d delete the commit and its changes
exec x run a shell command at this point; stop if it fails
break b stop here (continue later with git rebase --continue)
label, reset, merge rebuild merge commits (used by --rebase-merges)

Squash and fixup: merge commits together

A commit marked squash or fixup is combined with the one above it in the list. So the line must come after the commit it joins. fixup is for "this is just a correction, I do not need its message"; squash stops to let you write a combined message.

Bash Squash WIP commits into one with fixup

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Four commits became two: Add login form now contains the final version of login.txt (fixed), and the messages WIP and Fix typo are gone. With squash instead of fixup, Git would have opened the message editor with all three messages together so you could write a new one.

Reword: fix a message

reword replays the commit unchanged and then opens the message editor. In a script, set GIT_EDITOR to a program that overwrites the file it is given.

Bash Reword an old commit message

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Only the first of the two commits was reworded. Notice that rewording the message changes that commit's hash and therefore every commit after it. This is why you must not rewrite published history.

Reorder and drop

Moving a line moves the commit; deleting it (or writing drop) removes it. If the moved commit changes the same lines as its neighbours, the replay hits a conflict and stops, like in a normal rebase.

Bash Reorder commits and drop one

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Add b now comes before Add a, and the debug commit is gone with its file. The sed expression holds line 1, deletes it, and appends it after line 2: a classic way to swap two lines.

Edit: stop and change a commit

edit pauses the rebase right after applying that commit. You are then in a normal state and can run git commit --amend, add more files, or split the commit. When finished, git rebase --continue carries on.

Bash Stop at a commit with edit and add a forgotten file

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The first lines of output say that the rebase stopped at the Add feature commit and that you can amend it. After the amend, the forgotten file belongs to that commit (the --stat view lists it), and git rebase --continue re-applied Add docs on top.

Exec: test every commit

An exec line runs a command in between commits and stops the rebase if it fails. The one-line version is git rebase -x "<command>", which inserts an exec after every commit. It is an excellent way to make sure each commit of a series still builds and passes tests, a property that git bisect later depends on (see Finding Bugs with git bisect).

Bash Run a check after each commit with rebase -x (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Git ran the test after every replayed commit. It passed for Base and Step 1, failed after Step 2, and stopped there so that you can fix that commit (git commit --amend, then git rebase --continue). Nothing after the failing commit had been applied yet. --abort returned the branch to the original four commits.

Fixup commits and --autosquash

Instead of editing the todo list by hand, you can mark corrections as you make them:

TEXT
git commit --fixup=<commit>     # creates "fixup! <subject of that commit>"
git commit --squash=<commit>    # creates "squash! <subject>"
git rebase -i --autosquash main # puts them in the right place with the right command

With --autosquash Git rewrites the plan for you: every fixup! commit is moved directly below its target and marked fixup. If you open the editor, you only need to save. Set git config --global rebase.autosquash true to make it the default. When you do not care to inspect the plan, use GIT_SEQUENCE_EDITOR=: (the shell no-op) to accept it unchanged, as in the previous lesson.

Bash Autosquash a fixup commit into its target

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Look at the plan: the fixup line sits directly below Add parser, and Add renderer and Add CLI follow it. That happened with no manual editing. The subject fixup! Add parser told Git where the commit belonged, which is why the subject must be left intact.

Cleaning a branch before review

A typical routine before opening a pull request:

  1. git fetch and git rebase -i origin/main (or whatever your base branch is).
  2. fixup the "oops" commits, reword vague messages, drop debugging commits, and reorder so related changes sit together.
  3. Run the test suite, or use git rebase -x "<test command>" origin/main so that every commit is checked.
  4. git push --force-with-lease to update the branch you opened the pull request from.

The aim is not to hide history but to make each commit one understandable step, so that reviewers (and git bisect and git blame later) can follow it. See Making Good Commits.

Recovering from a bad rebase

  • git rebase --abort while the rebase is still running puts everything back.
  • After it finished, git reflog shows where the branch was before. Reset to that entry: git reset --hard 'HEAD@{5}' (see The Reflog). Right after a rebase, ORIG_HEAD points at the old tip too.
  • If you lose track, run git status: it tells you if you are in the middle of a rebase, and which commands are available.

Everything in this lesson rewrites commits. Do it on branches that only you use. If you must rewrite a pushed branch, announce it, and use git push --force-with-lease.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. In the interactive rebase todo list, in which order are the commits shown?

    The list is oldest first because Git re-applies commits in the order they originally happened. That is the reverse of git log.
  2. 2. What is the difference between squash and fixup?

    Both meld the commit into the one above. squash combines the messages and opens an editor, while fixup silently keeps only the earlier message.
  3. 3. Which variable lets a script supply its own program to edit the todo list?

    GIT_SEQUENCE_EDITOR names the program used for the todo list, while GIT_EDITOR is for commit messages.
  4. 4. What does git commit --fixup=<commit> followed by git rebase -i --autosquash do?

    The fixup! subject tells autosquash which commit it belongs to. Git reorders the plan and marks the line as fixup.
  5. 5. You deleted all lines of the todo list and saved. What happens?

    An empty todo list aborts the rebase. To delete a commit you must write drop (or remove just its line).

Summary

  • git rebase -i <base> shows the commits after <base> as a todo list, oldest first, and replays them as you edit the plan.
  • pick, reword, edit, squash, fixup, drop and exec cover nearly every cleanup; moving lines reorders commits.
  • GIT_SEQUENCE_EDITOR (todo list) and GIT_EDITOR (messages) make rebases scriptable; GIT_SEQUENCE_EDITOR=: accepts the generated plan.
  • git commit --fixup plus --autosquash is the lightweight way to keep corrections with their target commit; git rebase -x tests each commit.
  • Use --abort during a rebase and the reflog or ORIG_HEAD afterwards to undo it.
  • Rewrite only unshared history, and push with --force-with-lease if you must.

Next: Amending, Splitting and Rewriting Commits