hexz_cli/cmd/data/mod.rs
1//! Data operation commands for archive management.
2//!
3//! This module provides commands for creating, inspecting, and analyzing Hexz
4//! archives. Archives (`.hxz` files) are the primary storage format for snapshots,
5//! containing compressed, deduplicated, and optionally encrypted data.
6//!
7//! # Available Commands
8//!
9//! - [`pack`]: Create archives from raw disk images or memory dumps
10//! - [`build`]: Build archives from source directories with profiles
11//! - [`inspect`]: Inspect archive metadata (header, index, compression stats)
12//! - [`diff`]: Compare block hashes between two archives
13//! - [`ls`]: List archives in a directory as a lineage tree
14//! - [`analyze`]: Run DCAM analysis to optimize CDC parameters (diagnostics)
15//! - [`overlay`]: Inspect FUSE overlay files (diagnostics)
16//!
17//! # Workflow Example
18//!
19//! ```bash
20//! # Save two checkpoints then compare them
21//! hexz diff base.hxz finetuned.hxz
22//!
23//! # List all checkpoints in a directory as a lineage tree
24//! hexz ls ./checkpoints/
25//!
26//! # Inspect a single archive
27//! hexz inspect snapshot.hxz --json
28//! ```
29//!
30//! # Archive Format
31//!
32//! Archives consist of:
33//! - **Header**: Magic bytes, version, flags, encryption metadata
34//! - **Index**: B-tree or hash-based block index for fast lookups
35//! - **Data**: Compressed, deduplicated blocks
36//! - **Signature**: Optional Ed25519 signature (if signing enabled)
37//!
38//! # Performance Considerations
39//!
40//! - **CDC vs Fixed**: CDC provides better deduplication but slower packing
41//! - **Compression**: LZ4 is faster, Zstandard has higher ratios
42//! - **Dictionary Training**: Improves Zstandard compression by 10-30%
43//! - **Block Size**: Larger blocks = less overhead, worse deduplication
44
45pub mod build;
46pub mod convert;
47pub mod diff;
48pub mod inspect;
49pub mod ls;
50pub mod pack;
51
52#[cfg(feature = "diagnostics")]
53pub mod analyze;
54
55#[cfg(feature = "diagnostics")]
56pub mod overlay;