What had to happen has happened. Yesterday Bruno published a commit on main that changes how tasks are stored in localStorage, and this morning Ana has discovered that users who already had tasks saved find their list emptied when they open the application. The commit has been on git.example.com for fourteen hours, Ana and Carla have it downloaded, and on top of that there are three more commits above it.

Everything we have learned in this module rewrites history, and the golden rule expressly forbids that in this situation: that commit is already public. It cannot be rebased, it cannot be removed with a rebase -i, it cannot be made to disappear.

Git has an answer for this, and it is elegant precisely because it does not fight immutability but accepts it: the commit is not deleted, another one is added that applies the opposite change. The history grows instead of shrinking, nobody has to force anything, and there is a public record that it was undone and why.

That is git revert, and it is the only safe way of undoing something that is already published. With it we close the module.

1. What git revert does
2. Reverting Bruno's commit
3. revert versus reset versus --amend
4. Reverting several commits and ranges
5. -n: grouping several reverts into one commit
6. Conflicts while reverting
7. Reverting a merge commit: -m 1 and -m 2
8. The problem of the reverted branch that will not go back in
9. Reverting a revert
10. When to revert and when not to

Git works out the diff that <sha> introduced, inverts it (what it added, it removes; what it removed, it adds) and creates a new commit with that inverse change on the tip of your branch.

Commit 4f8a2e6 (highlighted) is the one that broke things. 3e7f1a8 is its revert: it undoes its effect without touching anything in between. All six commits are still there, in the same order, with the same hashes.

The three properties that set it apart from everything else in the module:

That last point is often misread. Somebody says "I want it to disappear, not to be left in the history". But leaving a record is the right thing: six months from now, when somebody looks at why that functionality is not there, the history will tell them. A deleted commit explains nothing; a reverted commit with a good message explains everything.

The starting situation:

The culprit is 4f8a2e6. First, look at it:

There is the bug: the storage key was changed without migrating the existing data. Now, the revert:

Git opens the editor with a proposed message:

Ana fills it out, because the default message says what but not why:

The new commit's diff is exactly the inverse of the original:

And now the best part of all:

An ordinary push, with no --force, no --force-with-lease, and nobody having to be told to rewrite anything. Carla and Bruno will run git pull, receive one more commit and everything will work. That is the value of revert: undoing at no social cost.

git revert options:

All three "undo" things and they are constantly confused. The key difference is whether they touch the existing history, and that determines which you can use on published work.

The way to decide, in one question: is what I want to undo already on the server where others may have it?

• Yes → git revert. There is no safe alternative.
• No → reset or --amend are cleaner, because the result does not drag along an undo commit nobody cares about.

An example that clarifies the difference in outcome. History A → B → C, and we want to remove B:

Note the important detail about reset: it takes C with it too, because it moves the branch to A and everything after that is left orphaned. To remove only B while keeping C you have to rebase, not reset.

git reset is far more than fits here. It has three modes — --soft, --mixed and --hard — which behave very differently depending on which of the three areas from lesson 01-03 they affect, and it is the central tool for undoing local work. All of that, with the full tables and procedures, is the subject of lesson 09-02: Undoing Changes. Here we only needed the conceptual contrast: reset rewrites, revert does not.

git revert accepts several commits and ranges, with the same notation as lesson 02-06:

One fundamental detail: Git reverts them in reverse order, from the most recent to the oldest. That is the correct thing and what avoids unnecessary conflicts: if C builds on B, you have to undo C before B. That is why git revert HEAD~3..HEAD produces three revert commits in this order:

Three commits undone, three revert commits, and a history that tells exactly what happened. If you would rather it were just one, on to the next section.

Three revert commits in a row are usually noise: what happened conceptually was one decision ("we are taking the filter feature out"), not three. -n (--no-commit) applies the inverse changes to the index without committing, and you commit at the end:

One commit, one message, one decision. It is almost always the best way of reverting a set of related commits.

While you are in the middle of a revert -n, the repository is in a special state (there is a .git/REVERT_HEAD file). If you have second thoughts:

A revert is, underneath, a merge: Git tries to apply an inverse patch onto a context that may have changed since. If the code you want to undo has been modified afterwards, it conflicts.

The mechanics of resolution are the usual ones (lesson 03-05). What is specific:

As with cherry-pick (lesson 05-03), here ours and theirs are NOT inverted: ours is your branch, theirs is the inverse change being applied. The inversion was a peculiarity of rebase.

And a warning worth taking to heart: when a revert conflicts, stop and think. The conflict is telling you that somebody built on top of what you want to undo. Reverting by brute force can leave code calling a function that has just disappeared. Check who depends on it before carrying on:

-S is the pickaxe search from lesson 02-06, and here it is exactly the right tool.

This is the case that trips everybody up the first time.

Why it fails. Reverting means applying the inverse diff. But a merge commit has two parents, and therefore two possible diffs: one against the first parent and one against the second. Git cannot guess which you want, so it refuses and forces you to say.

The merge commit's parents, in order:

The first parent is always the destination branch, because the merge commit was created while you were standing on it. The second (and subsequent ones, in an octopus merge) are the branches brought in.

-m 1 means: "keep parent 1's line", that is, undo everything the merged branch contributed and keep main as it was. That is what you want 99% of the time.

-m 2 would do the opposite: undo what main contributed and keep the branch. It is an extremely rare operation and almost always means you have picked the wrong command.

The mnemonic: -m 1 = "keep the mainline, throw away what I brought in".

A practical tip: before reverting a merge, look at its parents. git log --format='%h %p %s' -1 <sha> gives them to you in a second, and git show <sha>^1 / git show <sha>^2 shows you each one. Two commands and you avoid the mistake.

Here comes the subtle consequence, the one that bites weeks later, and the reason reverting a merge deserves a section of its own.

Bruno reverted the merge of feature/pending-filter. A fortnight later he fixes the counter problem and wants to integrate the branch again:

"Already up to date", and there is no sign of the filter on main. Bewildering.

Why it happens. Remember the three-way merge of lesson 03-03: Git finds the common ancestor and compares. But the common ancestor of main and feature/pending-filter is now the reverted merge itself (c2a8f1e), because that merge is still in the history and makes all of the branch's commits reachable from main.

From the graph's point of view, those commits are already integrated. That their content was undone afterwards by 4d7c1a9 is irrelevant to the calculation: Git reasons about reachability, not about content.

The highlighted commit is the revert. The branch is connected to main's graph; the content is not.

And if Bruno adds new commits to the branch and merges again, the result is worse still: only the new commits go in, on top of a main that is missing the base they were expecting. Code calling functions that do not exist, and no conflict to warn you.

The three solutions, in order of preference:

A. Revert the revert. The simplest and the one used almost always:

That brings the branch's content back to main. From then on, the new commits Bruno makes on the branch will merge normally. The history looks a little comical — a "Revert of the Revert" — but it is correct, honest and safe. If you like, edit the message to explain it:

B. Redo the branch on top of the current main. If the branch was short, creating a new branch from main and bringing the commits over with git cherry-pick (lesson 05-03) gives a cleaner history:

The new commits have new hashes, they are not reachable from main, and the later merge works normally.

C. Force the merge, ignoring the ancestor. It exists, but it is hardly ever a good idea; we mention it so that you recognise it if you see it:

The underlying lesson, and it deserves underlining:

Reverting a merge undoes the content, not the topology. The graph still says that branch was integrated.

That is why, when a whole branch has to come out and it is known that it will come back, many teams prefer to revert the individual commits rather than the merge, or simply not to merge until they are sure. And that is why it is worth knowing this before reverting a merge, not afterwards.

We have already used it in the previous section, but it is worth stating: a revert is a perfectly ordinary commit, so it can be reverted.

The result is that the original change comes back. It is the canonical way of saying "I was too hasty in undoing this".

And since it is symmetrical, it works as many times as you like: reverting the revert of the revert undoes it again. Each step is a new commit, nobody forces anything and the history tells the complete sequence of decisions. Inelegant, but rigorously safe.

And two matters of judgement that are not technical:

Revert early. If something is broken on main, reverting first and diagnosing afterwards is almost always the right call. A broken main blocks the whole team; the reverted commit is not lost and can be reintroduced once fixed. It is a decision about service, not about pride.

Write down why. The automatic message (This reverts commit ...) says what was undone but not why. Adding three lines explaining the reason and what would be needed to try again turns a revert into useful information six months from now. Message conventions are the subject of lesson 08-01, but this particular case is worth mentioning here: an unexplained revert is one of the most frustrating entries you can find in a history.

Mistake 1: using reset instead of revert on published work. It is the fast lane to the scenario in section 9 of lesson 05-01: push --force, colleagues with divergent histories and an afternoon of coordination. If it is on the server, revert.

Mistake 2: trying to revert a merge without -m. Git fails with a clear message. Remember: -m 1 in 99% of cases.

Mistake 3: getting the order of the parents wrong. -m 1 is the branch you were on (usually main); -m 2 is the one you brought in. Check with git show --format='%h %p %s' -s <sha> before deciding.

Mistake 4: assuming that after reverting a merge the branch will go back in by itself. It will not: Already up to date. You have to revert the revert or redo the branch.

Mistake 5: accepting the default message and leaving it at that. It says what, not why. Thirty seconds of explanation save a future investigation.

Mistake 6: reverting a commit others built on without checking the dependencies. You can leave code calling something that no longer exists. Use git log -S and git log <sha>..HEAD -- <file> first.

Mistake 7: reverting on the wrong branch. git revert acts on the current branch. Check with git status before launching it, especially if you have just been looking at another branch.

Tip 1: always look at the commit before reverting it. git show <sha> takes three seconds and tells you whether the change is self-contained or drags half the project with it.

Tip 2: for several related commits, use -n and commit once. One decision, one commit.

Tip 3: if the revert conflicts, read it as a signal. Somebody built on top. It may be that the right way out is not to revert but to fix forwards.

Tip 4: reverting is reversible. If you were too hasty, a git revert on the revert brings everything back. Nothing you do with this command is unrecoverable.

Tip 5: on main, revert first and think afterwards. Restoring the service is the priority; the diagnosis can be done calmly on a branch.

In a repository with five commits, of which the third introduces a bug:

1. Revert the third commit with a message explaining the reason.
2. Demonstrate that none of the earlier hashes has changed.
3. Demonstrate that the file's content is what it was before that commit, apart from what the fourth and fifth contributed.
4. Compare conceptually with what would have happened using git reset --hard on the second commit (there is no need to run it on the main branch: do it on a copy).

1. Create a branch with two commits and merge it into main with --no-ff.
2. Add one more commit to main.
3. Revert the merge with -m 1 and check that the branch's content has disappeared.
4. Try to merge the branch again and observe the message.
5. Resolve it by reverting the revert and check that the content comes back.
6. Draw (or describe) the resulting graph.

With a branch that has four commits on top of main, revert the last three in a single commit using -n. Verify with git show --stat that the resulting commit contains the revert of all three, and with git diff that the state of the project matches the one after the first.

Solution 1:

The five original commits keep their hashes; only one has been added on top.

ERROR has gone and the lines from Four and Five are preserved.

The reset has swept away Three, Four and Five: it moves the branch, it does not undo one specific change. And if that branch were published, the push would be rejected and would have to be forced.

Solution 2:

filter.js has gone: the branch's content is undone.

There is the problem: the graph says it is already integrated.

The content is back.

Eight commits telling the whole story: it went in, it came out, it went back in. Nothing has been rewritten and nobody has forced anything.

Solution 3:

One single revert commit and a state identical to that of the first commit in the series, without having touched a single hash.

git revert is the missing piece: the way of undoing that respects the golden rule. The essentials:

• Reverting does not delete: it adds. Git creates a new commit with the inverse change. No existing hash changes, the push does not have to be forced and there is a public record of the decision.
• It is the only safe way of undoing something published. reset and --amend rewrite history and are only good for work that is still yours; lesson 09-02 covers reset thoroughly.
• It accepts several commits and ranges, which it reverts from the most recent to the oldest; -n lets you accumulate several reverts and commit them as a single decision.
• Conflicts are resolved as always, with --continue, --skip and --abort, and here ours/theirs are not inverted. A conflict while reverting usually means somebody built on top: stop and look.
• Reverting a merge requires -m to choose the mainline parent: -m 1 (the branch you were on, nearly always main) or -m 2 (the one you brought in, extremely rare).
• Reverting a merge undoes the content, not the topology. The branch is still reachable, so merging it again says Already up to date. It is resolved by reverting the revert, or by redoing the branch with cherry-pick.
• Everything is reversible: a revert is an ordinary commit and can itself be reverted.
• And the judgement call: on main, revert first and diagnose afterwards, and always explain why.

With this lesson you close the block of advanced operations. Looking back at what has changed in the way you work:

• git rebase to reapply commits onto a different base and obtain a linear history, knowing that it creates new commits.
• git rebase -i to reorder, join, split, rename and remove commits before publishing them, with --fixup/--autosquash as the daily flow and --exec as the validation net.
• git cherry-pick to transplant specific commits between branches that are not going to be merged, with -x to leave a trail and git cherry to detect duplicates.
• git stash to set half-finished work aside for minutes or hours, with -u for untracked files and git stash branch when it no longer fits.
• Annotated tags to mark versions permanently, with SemVer, --follow-tags and git describe.
• git revert to undo what is published without rewriting anything.

And above all of them, the golden rule: do not rewrite history you have already published and that others may hold. Rebase and interactive rebase, before publishing. Cherry-pick and revert, always safe. It is the line that separates expert use from reckless use.

The team now knows how to build the history and how to manipulate it with judgement. What it lacks now is learning how to get value out of it.

Because task-manager's history is an enormous database of information that we have barely queried so far. Written in it is who wrote each line and why, in which exact commit something that used to work stopped working, and what checks each commit ought to pass before it exists. And there are new problems: the project is beginning to depend on an internal library that lives in its own repository, and Carla needs to work on two branches at once without spending the day running stash.

In module 6: Git Tools and Techniques we shall see hooks for automating checks on every commit and every push, git bisect for finding by binary search the exact commit that introduced a bug, git blame for reconstructing the history of each line, aliases and the advanced git log formats for querying all of that comfortably, submodules for composing projects out of several repositories, and git worktree for having several working copies of the same repository at once.

We begin with automation, in lesson 06-01: Using Git Hooks.