Git Revert: Recording a History-Preserving Reversal

Basic

What git revert changes

`git revert` reverses the changes introduced by an existing commit by creating a new commit. Unlike `git reset`, it does not move the current branch tip backward. Unlike `git restore`, it is a history operation that records the reversal in the commit graph.

git revert HEAD
git log --oneline --decorate -3

HEAD contains a commit whose changes should be undone while preserving the existing history.?A new commit records the reversal and HEAD advances to that new commit.

Reverting the current commit

When the target is `HEAD`, Git computes the inverse of that commit relative to its parent and records the result as a new commit. In a clean repository, the new commit becomes the new `HEAD`, while the reverted commit remains an ancestor. The working tree and index must satisfy the cleanliness requirements of the revert operation.

git status --short
git revert HEAD
git log --oneline --decorate -3

HEAD points to the commit whose effect should be reversed.?HEAD points to a new commit whose parent is the formerly current commit.

The new commit reverses a patch, not an object identity

A revert does not make the selected commit disappear and does not copy an earlier snapshot over the branch tip. It applies the inverse of the selected commit’s changes to the current state and records that result as a new commit. Later changes remain part of the current history unless they conflict with the reversal.

git show --no-patch HEAD
git show --no-patch HEAD^
git diff HEAD^ HEAD

A selected commit introduced a known change and the current branch contains that change.?The new commit introduces the inverse patch while retaining the selected commit in history.

Reverting an earlier commit

The target does not have to be `HEAD`. For example, `git revert HEAD~1` asks Git to reverse the changes introduced by the parent of the current commit while retaining the newer commit. If later changes overlap the selected change, Git may stop for conflict resolution instead of producing the revert immediately.

git revert HEAD~1
git status --short
git log --oneline --decorate -4

The current branch has a newer commit after the target.?The newer commit remains in history; the revert commit is added after it.

Clean state and conflicts

The official documentation requires a clean working tree relative to `HEAD` before starting a revert. A revert can also produce conflicts when the inverse patch cannot be applied cleanly to the current state. Do not teach a revert as a guaranteed one-command operation: inspect status, resolve conflicts when necessary, and continue or abort using the documented revert sequence.

git status --short
git revert <commit>
git status --short

The selected commit changed lines that later history also changed.?Git reports conflicts and leaves the repository in an in-progress revert state.

Revert in progress: continue, skip, abort

When reverting a sequence and a conflict interrupts the operation, Git provides `--continue`, `--skip`, `--abort`, and `--quit` for controlling the in-progress operation. These controls belong to the revert state machine: resolve and stage the conflict before continuing, skip the current commit when appropriate, or abort to return to the pre-revert state. `--quit` stops the sequencer without restoring the pre-sequence state.

git revert --continue
git revert --skip
git revert --abort
git revert --quit

A revert is paused because its inverse patch conflicted; the conflict has now been resolved and staged.?The revert sequence continues and can create the appropriate new commit.

Reverting a merge commit

A merge commit has multiple parents, so Git needs to know which parent represents the mainline for the reversal. `git revert -m <parent-number> <merge-commit>` selects that parent. The parent number starts at 1. This is an advanced operation and should only be used when the intended mainline is understood; the lesson uses the option to explain the model rather than treating it as a casual recovery command.

git rev-list --parents -1 <merge-commit>
git revert -m 1 <merge-commit>

A merge commit has two or more parents.?The chosen parent defines the mainline against which Git computes the inverse.

Choosing between restore, reset, and revert

Use the state that must change as the deciding question. `git restore` corrects selected working-tree and/or index paths without rewriting history. `git reset` can move the current branch tip and/or reset the index and working tree depending on its form. `git revert` keeps the existing history and adds a new commit that reverses an earlier change. These are different state transformations, not interchangeable “undo” commands.

git restore -- path/to/file
git reset HEAD~1
git revert <commit>

You need the branch history to retain the original commit and explicitly record its reversal.?A new revert commit is added after the existing history.

Practice what you learned

Use the dedicated Git code-completion exercise for this lesson.

Official-source boundary

This lesson is based only on the official Git documentation for `git revert`, the official Git revision syntax, and the official Git user manual. It deliberately does not teach reflog recovery, merge strategy selection, or broad history-transformation workflows here. The local verification executable is Git 2.47.3; the current official documentation baseline is Git 2.56.0.