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

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, 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 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 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, 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:

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):

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:

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:

-- 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:

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 and go/libraries/doltcore/sqle/dprocedures/dolt_revert.go.
• Three-Way Merge: The underlying algorithm in 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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}