# How to Revert Changes in Dolt: CLI and SQL Methods Explained

> Learn to revert changes in Dolt using the CLI dolt revert command or SQL CALL DOLT_REVERT() to undo commits by applying inverse changes. Master Dolt version control.

- Repository: [DoltHub/dolt](https://github.com/dolthub/dolt)
- Tags: how-to-guide
- Published: 2026-03-14

---

**Use the `dolt revert` command from the CLI or execute `CALL DOLT_REVERT()` in SQL to undo the effects of previous commits by creating new commits that apply the inverse changes.**

Dolt is a version-controlled SQL database that combines Git-style branching and merging with relational data management. Whether you need to roll back a mistaken schema change or undo bad data ingestion, the revert functionality in `dolthub/dolt` provides a safe way to reverse history without rewriting it. This operation creates new commits rather than destroying old ones, preserving the complete audit trail of your database.

## How Dolt Revert Works Under the Hood

The revert implementation spans three architectural layers, from user interface to merge engine. Understanding this flow helps diagnose errors and optimize usage.

### The Three-Layer Architecture

- **CLI Front-end**: Located in [`go/cmd/dolt/commands/revert.go`](https://github.com/dolthub/dolt/blob/main/go/cmd/dolt/commands/revert.go), this layer parses command-line arguments, constructs a `CALL DOLT_REVERT` query string, and displays the resulting commit information via the pager.

- **SQL Stored Procedure**: The `dolt_revert` procedure defined in [`go/libraries/doltcore/sqle/dprocedures/dolt_revert.go`](https://github.com/dolthub/dolt/blob/main/go/libraries/doltcore/sqle/dprocedures/dolt_revert.go) validates the session state, resolves target commits using `NewCommitSpec` and `Resolve`, and forwards requests to the merge layer.

- **Merge Engine**: The core logic in [`go/libraries/doltcore/merge/revert.go`](https://github.com/dolthub/dolt/blob/main/go/libraries/doltcore/merge/revert.go) executes a **three-way merge** where:
  - **Base**: The commit being reverted (e.g., `HEAD~1`)
  - **Ours**: The current working root
  - **Theirs**: The parent of the base commit (the state before the target commit)

The engine calls `MergeRoots` with `IsCherryPick: false` to compute the inverse diff, updates the working root, and returns a human-readable revert message.

### Safety Constraints

According to the source code in [`go/libraries/doltcore/merge/revert.go`](https://github.com/dolthub/dolt/blob/main/go/libraries/doltcore/merge/revert.go), the operation aborts if `HasConflicts` or `HasConstraintViolations` returns true. Additionally, the stored procedure enforces that the working set must be clean—uncommitted changes trigger the error "You must commit any changes before using revert."

## Reverting Changes Using the Dolt CLI

The CLI provides the most straightforward interface for reverting commits, supporting single or multiple commit targets along with customization options.

### Revert a Single Commit

To undo the most recent commit:

```bash
dolt revert HEAD~1

```

This command resolves `HEAD~1` to a `*doltdb.Commit`, calculates the inverse changes via the merge engine, and automatically creates a new commit with the message `Revert "<original description>"`.

### Revert Multiple Commits

Process multiple commits in the order specified (oldest first recommended):

```bash
dolt revert HEAD~3 HEAD~2

```

The CLI builds a query string `CALL DOLT_REVERT('HEAD~3', 'HEAD~2')` and processes each commit sequentially through the three-way merge engine.

### Specify Custom Author and Message

Override the default Git-style configuration author and add context:

```bash
dolt revert -a "Jane Doe <jane@example.com>" -m "Undo accidental schema change" HEAD~1

```

The `-a` flag sets the author metadata, while `-m` provides a custom message that Dolt prepends with "Revert". The CLI then invokes `doDoltCommit` with `-a -m` flags to record the new state.

## Reverting Changes Using SQL

For applications and automated workflows, the stored procedure interface offers programmatic access to the same revert logic.

### Basic SQL Revert Syntax

Execute the revert operation within a SQL session:

```sql
-- Revert the most recent commit
CALL DOLT_REVERT('HEAD~1');

-- Revert multiple commits
CALL DOLT_REVERT('HEAD~3', 'HEAD~2');

```

The procedure performs identical validation and merge logic as the CLI path, ensuring consistency across interfaces.

### Advanced Options and Error Handling

Specify explicit author information through additional parameters:

```sql
CALL DOLT_REVERT('--author', 'Jane Doe <jane@example.com>', 'HEAD~1');

```

If the working set contains uncommitted changes, the procedure returns an error before reaching the merge engine. Similarly, if `merge.Revert` detects conflicts during the three-way merge, the operation aborts with the message "revert currently does not handle conflicts."

## Summary

- **Soft Undo**: Dolt revert creates new commits that apply inverse changes rather than deleting history, maintaining full audit capabilities.
- **Dual Interface**: Access the functionality via `dolt revert` CLI commands or `CALL DOLT_REVERT()` SQL procedures, both implemented in [`go/cmd/dolt/commands/revert.go`](https://github.com/dolthub/dolt/blob/main/go/cmd/dolt/commands/revert.go) and [`go/libraries/doltcore/sqle/dprocedures/dolt_revert.go`](https://github.com/dolthub/dolt/blob/main/go/libraries/doltcore/sqle/dprocedures/dolt_revert.go).
- **Three-Way Merge**: The underlying algorithm in [`go/libraries/doltcore/merge/revert.go`](https://github.com/dolthub/dolt/blob/main/go/libraries/doltcore/merge/revert.go) treats the target commit as base, its parent as theirs, and the current root as ours to calculate reversions.
- **Clean Working Set Required**: Both interfaces enforce that no uncommitted changes exist before processing, and abort immediately if merge conflicts occur.

## Frequently Asked Questions

### Can I revert a commit if there are uncommitted changes in my working set?

No. According to the implementation in [`go/libraries/doltcore/sqle/dprocedures/dolt_revert.go`](https://github.com/dolthub/dolt/blob/main/go/libraries/doltcore/sqle/dprocedures/dolt_revert.go), the stored procedure validates that the working set is empty before proceeding. You must first commit or stash your current changes using `dolt add . && dolt commit -m "save work"` before running revert.

### What happens if the revert operation encounters merge conflicts?

The operation aborts with an error. The `merge.Revert` function in [`go/libraries/doltcore/merge/revert.go`](https://github.com/dolthub/dolt/blob/main/go/libraries/doltcore/merge/revert.go) checks `HasConflicts` and `HasConstraintViolations` after computing the three-way merge. If either condition is true, the revert stops and reports that it currently does not handle conflicts, leaving the working set unchanged.

### How does Dolt revert differ from Git revert?

While the user interface mirrors Git's `git revert` command, Dolt's implementation operates entirely within the database engine. The SQL stored procedure `CALL DOLT_REVERT()` allows reverting directly from SQL clients and applications, and the merge logic is integrated with Dolt's root-based storage system rather than file system operations.

### Can I revert multiple commits in a single command?

Yes. Both the CLI and SQL interfaces accept multiple commit references. The CLI command `dolt revert HEAD~3 HEAD~2` processes commits in the order provided, applying a three-way merge for each. Similarly, `CALL DOLT_REVERT('HEAD~3', 'HEAD~2')` resolves and reverts each commit sequentially through the same merge engine.