git revert

This page covers what git revert does, the options it accepts, a complete worked example, how it differs from git reset, how to revert a merge commit, and how to resolve the conflicts a revert can produce.

Description

The git revert command is a forward-moving undo operation. Unlike commands such as git reset, it does not rewrite history. Instead of deleting or moving commits, it calculates the inverse of the changes a target commit introduced and records that inverse as a new commit on top of the current branch.

Because nothing is removed from the history, git revert is the safe way to undo work that you have already pushed to a shared repository: everyone who has the original commit keeps it, and the revert simply adds a follow-up commit that cancels it out. This preserves the full revision history, which matters for auditability and for clean collaboration.

A few things to keep in mind:

• A revert needs a commit reference to know what to undo. Running git revert with no argument fails.
• A revert leaves the working tree in the state you would have if that commit had never happened (relative to the surrounding commits) — not necessarily an empty diff, because later commits may still touch the same lines.
• Reverting a revert re-applies the original change, since the inverse of an inverse is the original.

When to use git revert

Reach for git revert when:

• The commit you want to undo is already published (pushed, opened in a pull request, or pulled by teammates).
• You want to undo a single specific commit somewhere in the middle of history without touching the commits that came after it.
• You need an auditable record that a change was deliberately reversed.

Prefer git reset when the commit is local and unpublished and you simply want it gone, or git commit --amend when you only need to fix the most recent (unpushed) commit.

Options

Examples

# Stage the reverted changes without committing them (useful for review)
git revert -n HEAD

# Revert a merge commit against its first parent
git revert -m 1 <merge-commit-hash>

How it works

Like git checkout and git reset, git revert also takes a specified commit but it does not move reference pointers to this commit. The revert operation takes the specified commit, inverses the modifications from that commit and creates a new revert commit.

Here is an example of creating a repository:

git revert command

mkdir git_revert_example
cd git_revert_example/
git init .
#Initialized empty Git repository in /git_revert_example/.git/
touch w3docs_file
git add w3docs_file
git commit -m "original commit"
#[master (root-commit) 299b15f] original commit
#1 file changed, 0 insertions(+), 0 deletions(-)
#create mode 100644 w3docs_file
echo "original content" >> w3docs_file
git commit -m "add new content to w3docs_file"
#[master 3602d88] add new content to w3docs_file
#1 file changed, 1 insertion(+)
echo "prepended line content" >> w3docs_file
git commit -m "prepend content to w3docs file"
#[master 86bb32e] prepend content to w3docs file
#1 file changed, 1 insertion(+)
git log --oneline
#86bb32e prepend content to w3docs file
#3602d88 add new content to w3docs file
#299b15f original commit

In this example, a repository is initialized in a newly created directory named git_revert_example. There are 3 commits to the repository in which a file named w3docs_file is added. Its content has been changed twice. We use git log at the end of the repository set up to show all 3 commits in the commit history. Now we can invoke git revert:

git revert

git revert HEAD
#[master b9cd081] Revert "prepend content to w3docs file"
#1 file changed, 1 deletion(-)

git revert will not work without passing a commit reference. In the example above we passed the HEAD reference to revert the last commit. A revert creates a new commit and opens the configured system editor so you can edit its message (pass --no-edit to accept the default). We can use git log and see the new commit appended on top of the previous history:

git log --oneline

git log --oneline
#b9cd081 Revert "prepend content to w3docs file"
#86bb32e prepend content to w3docs file
#3602d88 add new content to w3docs_file
#299b15f original commit

After the revert, the "prepend" commit (86bb32e) is still in the project history. git revert added a new commit (b9cd081) that undoes its changes rather than deleting it. That is the key difference from git reset.

Reverting without committing

Pass -n (--no-commit) when you want to undo several commits in one combined revert, or inspect the inverse changes before recording them. Git stages the inverse modifications but stops short of creating a commit, leaving you in control:

# Stage the inverse of the last two commits, then commit once
git revert -n HEAD~1 HEAD
git status        # review the staged changes
git commit -m "Roll back the last two changes"

When you list more than one commit (or a range), Git applies a revert for each. Without -n it would create one commit per revert; with -n they are combined into the single commit you create yourself.

Reverting a merge commit

A merge commit has two parents, so Git cannot tell on its own which side you want to keep. You must say which parent represents the "mainline" to revert back to using -m <parent-number>. Parent numbers start at 1:

# Undo a merge, keeping the first parent (usually the branch you merged into)
git revert -m 1 <merge-commit-hash>

In a typical "merge a feature branch into main" scenario, parent 1 is main and parent 2 is the feature branch, so -m 1 discards the feature branch's changes.

Resolving a revert conflict

If later commits modified the same lines the revert is trying to undo, Git stops with a conflict — just like a merge conflict. Edit the marked files, stage them, then finish the in-progress revert:

git revert HEAD~2
# CONFLICT (content): Merge conflict in w3docs_file
# error: could not revert 4f2a1c0... change w3docs_file
# resolve the conflict markers in the file, then:
git add w3docs_file
git revert --continue   # records the revert commit

# Or, to back out of the whole operation:
git revert --abort

Resetting vs. reverting

The git revert command undoes a commit by adding a new commit, while git reset rewrites history by moving the branch pointer back and discarding the commits after it.

Reverting is the safe choice for commits that have already been published to a shared repository, and it lets you target a specific commit anywhere in the history. Avoid git revert on private, unpublished commits where git reset is simpler and cleaner.

Related commands

• git reset — move the branch pointer and discard later commits (history-rewriting undo).
• git commit --amend — fix the most recent unpushed commit.
• git checkout — discard uncommitted changes in the working tree.
• git cherry-pick — the opposite operation: apply a commit's changes onto the current branch.

Practice