TraceDocs
Get Trace

Documentation / Projects and Collaboration

Version History & Rollback

Review available native snapshots and understand what rollback does not restore.

Overview

Native Trace can record AI-edit snapshots and offer history-based restore. Editor Undo, conversation controls and cloud publication history are different mechanisms. Check which one a control actually uses before restoring.

Local History

With incremental backup enabled, local history stores successful snapshots in the project's .history/ directory. Local snapshot creation and readback can work offline without a cloud account.

How It Works

Snapshot creation captures the eligible saved project files and records them in local history. Native .trace_sch / .trace_pcb and their paired .xo drawings belong together. Inspect the selected snapshot's changed files rather than assume it includes every file, private note, external library or unsaved buffer.

The chosen backup format matters. ZIP-backup mode does not keep extending incremental .history/; existing history may remain available to browse. Retention and manual deletion can remove snapshots.

Background Saves

Background recording can fail because of disk space, locks, write failures or missing files. A later successful snapshot captures a later state, not necessarily the intermediate edit you wanted. Successful snapshot recording does not make a partially failed multi-file save electrically consistent.

Before a major change, verify a usable snapshot or make an independent backup. Do not rely on “every edit is recoverable.”

Cloud Sync

Some supported conversation/version flows upload saved design content. They depend on account access, successful upload and the available restore path. They are separate from Workspaces cloud revisions and are not a complete backup of a local project directory.

When Cloud Versions Are Created

An AI-edit version is usable only if its save/upload completed and the needed content remains available. A message containing a version reference does not prove its local or cloud files can still be restored.

Cross-Device Access

Use the signed-in account's supported version/history view to inspect available cloud content. Do not assume another device has your local .history/, paired drawings, dependencies or unsaved changes. Adding a project to Workspaces does not silently share the source's earlier personal chats/history.

Per-Message Undo

Where offered by native Trace, a message rollback can use a recorded design version. Messages without a usable prior version cannot promise design restore. Chat history can change independently of whether the design restore succeeds.

How to Undo

  1. Wait for active editing to stop and check the intended project/conversation.
  2. Inspect the available rollback/history control and target version.
  3. Preserve current work you might need, including native drawings.
  4. Request restore and read its result.
  5. Inspect actual files and editor content, then rerun relevant ERC/DRC checks.

Do not infer restore success from shortened chat history. A rollback is not a guaranteed reversal of every tool effect, library installation, paid task or cloud operation.

Version ID Semantics

A recorded edit version describes the state after that edit. A before-message rollback may search backward for a prior recorded edit; it is not necessarily the immediately preceding message. Inspect the available target, especially when intervening messages were questions or contained no design edits.

Restore Dialog

In the native project manager's Full interface, use File → Restore Project from Local History... to browse restore targets. Use View → Panels → Local History to show the history panel.

What the Dialog Shows

Review the timestamp, summary and changed files. A hash identifies a snapshot, not engineering approval. Check that the required native design/sidecar content is present before selecting it.

How to Access

With the intended project open in the native manager's Full interface, choose File → Restore Project from Local History..., select the intended snapshot and review the restore prompt. The restore action requires enabled incremental local history and an existing history for that project. Follow any editor-close or file-lock instructions; do not override locks or save stale editor buffers over restored files.

AI Edit Undo/Redo

Native AI-edit undo/redo and schematic/PCB manual Undo have different scope and lifetimes. Reloading or closing a project can affect editor undo availability. Check the control and result; do not assume one conversation's undo is isolated from another conversation editing the same files.

In Trace Plugin for Altium/KiCad, “undo to message” changes conversation history; it does not restore CAD. Host Undo and supported file backups are separate. Editing/resending a prompt is a new turn, not a design rollback.

Native CLI and history

Use the native trace-cli supplied with the Trace app, not older developer CLI guidance. Install Trace and sign in to the main app first for hosted chat and cloud Workspaces commands. The CLI shares that session; expiry requires desktop refresh/sign-in.

The native command tree has no separate versions or local-history restore command. Use the desktop history view for those snapshots. In compatible builds, trace-cli workspaces provides saved-content review, local Commit, cloud Push and original-operation receipt reads for a registered checkout. Those are not chat-message rollback.

trace-cli workspaces review --project /absolute/design.kicad_pro --json
trace-cli workspaces receipt --project /absolute/design.kicad_pro --request-id ORIGINAL_UUID --json

Use the installed executable path and the exact original operation ID. Receipt reads observe; they never repeat a write. A headless success verifies saved-file effects without claiming a GUI open or reload. Local ERC/DRC and exports do not technically need sign-in and can help review restored saved files, but they are not a complete engineering certification.

Best Practices

  • Use Plan to review proposed work, not as a guarantee of complete undo.
  • Verify a current backup before redesign, restore or destructive discard.
  • Keep native design files, paired .xo and required dependencies together.
  • Retain .history/ if you need local snapshots; do not assume cloud publication copied it.
  • For uncertain Push, Add, Move, Restore or PR outcomes, use Workspaces recovery, not message rollback.