Operation: Delete and Garbage Collection
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Operation: Delete is a critical maintenance function within the chkpt ecosystem that allows users to remove specific workspace snapshots. Its primary purpose is to manage storage by removing references to snapshots and their associated metadata from the system's catalog. Because chkpt uses a content-addressable storage system with deduplication, the deletion of a single snapshot does not necessarily mean the immediate removal of all its data, especially if that data is shared with other snapshots.
This operation ensures that the catalog.sqlite remains efficient and that the user's list of available checkpoints is kept relevant. It is closely tied to the overall storage architecture, which includes trees, packs, and a SQLite-based index for incremental change detection.
Sources: README.md, CLAUDE.md, crates/chkpt-core/src/ops/save.rs:72-85
Delete Mechanics
The delete operation is exposed through multiple interfaces including the CLI, Node.js API, and MCP tools. When a deletion is triggered, the system targets a specific snapshot ID to remove it from the project's store.
Logical Flow of Deletion
The process involves identifying the snapshot, verifying its existence, and then purging its entries from the catalog. Notably, the system is designed to handle "partial" or "corrupted" stores gracefully—deletion can still proceed even if the physical snapshot or tree files have been manually removed from the disk.
The diagram shows the standard flow for a delete operation, emphasizing the locking mechanism to prevent concurrent modification issues.
Sources: crates/chkpt-core/tests/delete_test.rs:10-20, crates/chkpt-core/tests/delete_test.rs:69-80, crates/chkpt-cli/skills/chkpt/references/cli-commands.md
Key Data Structures and Functions
| Component | Responsibility | Source |
|---|---|---|
delete(path, id) | Core Rust function that orchestrates the removal of a snapshot. | crates/chkpt-core/src/ops/delete.rs |
deleteSnapshot(workspace, id) | NAPI binding for Node.js environments. | crates/chkpt-napi/__test__/e2e.spec.ts |
checkpoint_delete | MCP tool used by AI agents (like Claude Code) to manage snapshots. | crates/chkpt-plugin/skills/chkpt/SKILL.md |
MetadataCatalog | The SQLite-backed engine that handles the actual removal of rows from snapshots and snapshot_files. | crates/chkpt-core/src/ops/save.rs:83-84 |
Garbage Collection and Deduplication Safety
A fundamental design requirement of chkpt's deletion logic is Deduplication Safety. Since files (blobs) are content-addressed (via XXH3-128 or BLAKE3 depending on the version/context) and stored in packs, multiple snapshots may point to the same physical blob.
Shared Object Preservation
When a snapshot is deleted, the system ensures that blobs still referenced by other existing snapshots are not removed. This is verified through tests that save multiple versions of a file, delete the first snapshot, and confirm the second snapshot remains fully restorable.
This sequence illustrates how shared objects are preserved even after one of the referencing snapshots is removed.
Sources: crates/chkpt-core/tests/delete_test.rs:43-67, README.md
User Interface and Safety Constraints
The chkpt project enforces strict safety protocols for deletion, particularly when accessed through automated tools or CLI.
- Confirmation Requirement: Interfaces like the Claude Code plugin or CLI skills MUST list the checkpoint details and request explicit user confirmation before executing a delete command.
- Locking: All delete operations must acquire a
ProjectLocklocated in the.chkpt/stores/<project_id>/locksdirectory to ensure atomicity. - Error Handling: If a snapshot ID is invalid, the system returns a "Snapshot not found" error and suggests running
chkpt listto view valid IDs.
Sources: crates/chkpt-cli/skills/chkpt/SKILL.md, crates/chkpt-plugin/skills/chkpt/references/cli-commands.md, crates/chkpt-core/src/ops/save.rs:82
Summary
Operation: Delete in chkpt provides a safe and efficient way to manage workspace history. By leveraging the MetadataCatalog for logical deletion and maintaining deduplication safety, the system ensures that storage is managed without risking the integrity of remaining snapshots. The process is guarded by file-based locking and integrated into all project interfaces (CLI, NAPI, MCP) to provide a consistent management experience.