DeepSeek TUI Workspace Rollback with Side-Git Snapshots: Complete Implementation Guide

DeepSeek TUI implements workspace rollback by maintaining an isolated side-git repository that captures lightweight snapshots of the entire workspace before each LLM turn, enabling users to revert changes without touching the project's own version control history.

DeepSeek TUI protects your project's Git integrity by never writing to your repository. Instead, it creates a side-git snapshot system that tracks every file change in a separate Git database stored under ~/.deepseek/snapshots/. This architecture provides atomic undo capabilities for any tool execution or file modification while completely isolating the conversation history from your source control.

How Side-Git Snapshots Work in DeepSeek TUI

The snapshot system operates through a dedicated Rust module that wraps Git operations to ensure zero interference with your working repository. According to the DeepSeek-TUI source code, the implementation lives in crates/tui/src/snapshot/repo.rs and manages the entire lifecycle of workspace versioning.

Snapshot Repository Initialization

When the TUI initializes, it calls SnapshotRepo::open_or_init, which creates a side-git directory at ~/.deepseek/snapshots/<project_hash>/<worktree_hash>/.git if it does not exist. This method configures a stable Git identity (deepseek-snapshots <snapshots@deepseek-tui.local>) to ensure commits remain isolated from your global Git configuration (snapshot/repo.rs, lines 60-78).

The repository uses explicit Git path arguments (--git-dir and --work-tree) on every invocation to guarantee that all Git operations target only the side repository, never your project’s .git folder (snapshot/repo.rs, lines 9-12).

Capturing Workspace State

Before each LLM turn, the engine executes repo.snapshot(label), which performs the following atomic operations:

1. Stages all workspace files using git add -A
2. Writes a tree object representing the complete workspace state
3. Creates a commit using git commit-tree
4. Updates HEAD to point to the new commit

This process generates a SnapshotId (SHA-1 hash) that uniquely identifies the workspace state (snapshot/repo.rs, lines 24-85). The crates/tui/src/tui/ui.rs file triggers this automatically via build_session_snapshot at the start of each turn, ensuring every operation has a rollback point.

Restoring Snapshots via the /restore Command

DeepSeek TUI exposes snapshot management through the /restore slash command, implemented in crates/tui/src/commands/restore.rs. This command provides both inspection and rollback capabilities.

Listing Available Snapshots

Running /restore without arguments queries the side-git repository for the most recent 10 commits and displays them as a numbered list using format_listing. Each entry shows the snapshot index, commit message, and timestamp (commands/restore.rs, lines 84-94).

/restore

# Output:

# 1: pre-turn: before applying patch (2 minutes ago)

# 2: post-turn: tool execution complete (5 minutes ago)

Executing Workspace Rollbacks

To revert to a specific state, use /restore <N> where N is the snapshot index. The command first verifies that the session operates in trusted mode (Yolo mode or explicit /trust on) to prevent accidental destructive operations (commands/restore.rs, lines 60-70).

Once authorized, the system calls repo.restore(&id), which executes git checkout <sha> -- :/ to restore every file from the snapshot tree into your working directory. This operation modifies only the workspace files, leaving your project's Git history untouched (snapshot/repo.rs, lines 87-92).

/restore 1  # Revert to the most recent snapshot

/restore 3  # Revert to the third most recent snapshot

If you attempt to restore outside trusted mode, the system refuses with a clear message:

Refusing to restore snapshot #2 outside trusted mode.
Run `/trust on` or `/yolo` first, then re-run `/restore 2`.

Safety Mechanisms and Isolation Guarantees

DeepSeek TUI implements multiple defensive layers to ensure snapshot operations remain safe and isolated.

Complete Directory Isolation: The side-git repository lives entirely under ~/.deepseek/, physically separate from your project tree. This guarantees that snapshot metadata never contaminates your source control.

Git Context Enforcement: Every Git subprocess invocation explicitly sets both --git-dir (pointing to ~/.deepseek/snapshots/.../.git) and --work-tree (pointing to your project root). This dual-flag approach ensures Git cannot accidentally target your project's repository.

Permission-Based Restoration: The trusted mode requirement acts as a safety gate. As implemented in crates/tui/src/commands/restore.rs, the system checks the session trust level before allowing any checkout operation, preventing LLM-triggered or accidental rollbacks.

Tool-Level Reversion: Beyond slash commands, crates/tui/src/tools/revert_turn.rs exposes a revert_turn tool that LLM agents can invoke programmatically, subject to the same trust checks and safety guarantees.

Code Implementation Examples

To interact with the snapshot system programmatically, import the SnapshotRepo struct and manage workspace states directly:

use deepseek_tui::snapshot::SnapshotRepo;
use std::path::Path;

// Initialize or reuse the side-git snapshot repository for the current workspace.
let workspace = Path::new("/my/project");
let repo = SnapshotRepo::open_or_init(workspace)?;

// Capture a snapshot before a risky operation.
let snap_id = repo.snapshot("pre-turn: before applying patch")?;

// ... Execute tools, modify files, etc. ...

// Roll back to the captured snapshot.
repo.restore(&snap_id)?;
println!("Workspace rolled back to snapshot {}", snap_id.0);

Configuration options for snapshot retention and enabling/disabling the feature are documented in docs/CONFIGURATION.md under the snapshots configuration section.

Summary

• DeepSeek TUI creates isolated side-git repositories under ~/.deepseek/snapshots/ to track workspace changes without modifying your project's Git history.
• The SnapshotRepo::open_or_init method initializes these repositories with isolated Git identities, while repo.snapshot(label) captures atomic workspace states before each LLM turn.
• Users restore states via the /restore slash command or the revert_turn tool, both requiring trusted mode to prevent accidental data loss.
• Safety guarantees include explicit --git-dir and --work-tree flags on all Git operations, physical directory isolation, and permission-based rollback gates.
• The implementation resides primarily in crates/tui/src/snapshot/repo.rs and crates/tui/src/commands/restore.rs, as detailed in docs/ARCHITECTURE.md.

Frequently Asked Questions

Where are DeepSeek TUI snapshots stored?

Snapshots are stored in a side-git repository located at ~/.deepseek/snapshots/<project_hash>/<worktree_hash>/.git. This location ensures complete isolation from your project directory, preventing any interference with your existing version control.

Does using side-git snapshots affect my project's Git history?

No. DeepSeek TUI never writes to your project's .git directory. All snapshot commits occur in the isolated side-git repository under ~/.deepseek/. The system uses explicit Git flags (--git-dir and --work-tree) to ensure all operations target only the snapshot database, leaving your source control history pristine.

Why does /restore require trusted mode?

The trusted mode requirement (Yolo or explicit /trust on) acts as a safety gate to prevent accidental destructive rollbacks. As implemented in crates/tui/src/commands/restore.rs, this check ensures that restoring previous workspace states requires explicit user consent, protecting against unintended data loss from LLM-generated commands or mistaken inputs.

Can I configure how many snapshots DeepSeek TUI retains?

Yes. Snapshot retention policies and enablement settings are controlled through the snapshots configuration section in your DeepSeek TUI configuration file, as documented in docs/CONFIGURATION.md. You can adjust settings to control automatic snapshot creation frequency and storage limits.

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