Operation: Restore Checkpoint
Relevant source files
The following files were used as context for generating this wiki page:
Operation: Restore Checkpoint is a core system process in chkpt that reverts a workspace to a previously saved state. It utilizes content-addressable storage and incremental diffing to minimize disk I/O, ensuring that only modified, missing, or extra files are processed during the restoration. This operation is designed to be atomic and safe, frequently used before risky operations like large refactors or dependency updates.
Sources: README.md:5-15, crates/chkpt-core/src/ops/restore.rs:373-379
Workflow Overview
The restoration process follows a structured sequence of state resolution, comparison, and file manipulation.
The diagram shows the logical flow from ID resolution to the final workspace update.
Sources: crates/chkpt-core/src/ops/restore.rs:382-414
Execution Phases
1. Snapshot Resolution
The system first identifies the target snapshot. Users can provide a specific UUID, a prefix, or the keyword latest. The MetadataCatalog resolves these references to a concrete snapshot ID.
Sources: crates/chkpt-core/src/ops/restore.rs:389-391, crates/chkpt-cli/src/main.rs:165-180
2. State Comparison (Diffing)
The core logic compares the Target State (extracted from the snapshot's manifest or tree) against the Current State (obtained by scanning the physical workspace).
| Category | Condition | Action |
|---|---|---|
| Added | File exists in Snapshot but not Workspace | Created/Extracted from packs |
| Changed | File exists in both but hashes or types differ | Overwritten with snapshot version |
| Removed | File exists in Workspace but not Snapshot | Deleted from workspace |
| Unchanged | Hashes and metadata match | No action taken |
Sources: crates/chkpt-core/src/ops/restore.rs:315-356, crates/chkpt-cli/src/main.rs:205-212
3. Data Retrieval and Application
Files are restored from packs stored in the .chkpt directory. The system builds RestoreTasks which are sorted by their location within pack files to optimize disk read patterns.
The sequence illustrates how data moves from content-addressed packs back into the workspace.
Sources: crates/chkpt-core/src/ops/restore.rs:218-245, crates/chkpt-core/src/ops/restore.rs:136-160
Implementation Details
Data Structures
RestoreOptions
Configures the behavior of the operation.
pub struct RestoreOptions {
pub dry_run: bool,
pub progress: ProgressCallback,
}
Sources: crates/chkpt-core/src/ops/restore.rs:19-22
RestoreResult
Returns the statistics of the operation to the caller.
pub struct RestoreResult {
pub snapshot_id: String,
pub files_added: u64,
pub files_changed: u64,
pub files_removed: u64,
pub files_unchanged: u64,
}
Sources: crates/chkpt-core/src/ops/restore.rs:25-31
Parallelization
To maximize performance, especially on large repositories like the Linux kernel, file restoration and removal are parallelized using std::thread::scope. The number of workers is determined by available_parallelism.
Sources: crates/chkpt-core/src/ops/restore.rs:136-140, crates/chkpt-core/src/ops/restore.rs:448-452
Special Handling: Symlinks
On Unix platforms, symlinks are handled by reading the target path from the blob storage and using std::os::unix::fs::symlink. If a file type changes from a regular file to a symlink (or vice versa), the existing file is removed before the new type is created.
Sources: crates/chkpt-core/src/ops/restore.rs:188-212, crates/chkpt-core/tests/restore_test.rs:163-188
Directory Cleanup
After files are removed, the system performs a "deepest-first" recursive cleanup of empty parent directories to ensure the workspace remains clean and matches the snapshot structure exactly.
Sources: crates/chkpt-core/src/ops/restore.rs:567-595
Safety and Best Practices
The CLI and plugins enforce a "Dry Run First" policy. Users are encouraged to preview changes before applying them.
- Dry Run: Reports the number of files to be added, changed, or removed without touching the disk.
- Locking: The operation acquires a
ProjectLockto prevent concurrent modifications to the store or workspace. - Atomic Index Update: The SQLite index is updated only after files are successfully restored to ensure incremental saves remain consistent.
Sources: crates/chkpt-cli/skills/chkpt/references/cli-commands.md:55-75, crates/chkpt-core/src/ops/restore.rs:385-387, crates/chkpt-napi/test/e2e.spec.ts:58-65
Conclusion
The Restore Checkpoint operation provides a high-performance safety net for developers. By combining content-addressed deduplication with parallelized I/O and intelligent directory cleanup, it allows near-instant recovery of complex workspace states without the overhead of traditional version control branching.