Skip to main content

Module diff

hexz_cli::cmd::data

Module diff 

Source
Expand description

Show differences in overlay and identify modified blocks.

This command analyzes overlay files created by the FUSE mount (in read-write mode) to display which blocks have been modified, providing statistics about write activity and changed data. The overlay mechanism tracks writes at 4 KiB granularity, allowing efficient copy-on-write semantics without modifying the base snapshot.

§Overlay Format

When mounting a snapshot in read-write mode, two files are created:

Overlay File (.overlay):

  • Contains modified 4 KiB blocks written by the VM/guest
  • Sparse file with blocks at their original logical offsets
  • Only modified blocks consume disk space

Metadata File (.meta):

  • Contains a sorted list of modified block indices (8 bytes each)
  • Used to quickly enumerate changed blocks without scanning the overlay
  • Format: array of u64 block numbers in little-endian encoding

§Use Cases

  • Change Tracking: Identify what data has been modified during VM execution
  • Incremental Commits: Determine which blocks need to be merged into new snapshot
  • Debugging: Investigate unexpected writes or storage growth
  • Capacity Planning: Estimate commit size before running vm commit
  • File-Level Analysis: Map modified blocks to files (future enhancement)

§Output Modes

Default Mode (Summary): Displays basic statistics:

  • Total number of modified blocks
  • Estimated data size changed

Blocks Mode (--blocks): Shows overlay statistics with human-readable sizes.

Files Mode (--files): Lists individual modified block indices. File-level resolution (mapping blocks to filesystem inodes) is not yet implemented.

§Comparison to Other Diff Tools

Unlike traditional file diffs (e.g., diff, rsync --dry-run):

  • Operates at block level, not file level
  • Does not require mounting or filesystem parsing
  • Fast: reads only the small metadata file, not entire overlay
  • Shows raw block changes, not semantic file differences

§Common Usage Patterns

# Show summary of changes
hexz diff overlay.img

# Show detailed block statistics
hexz diff overlay.img --blocks

# List all modified block indices
hexz diff overlay.img --files

# Estimate commit size before running vm commit
hexz diff vm-state.overlay --blocks
# Output: "Modified Blocks: 5120 | Total Changed Data: 20.0 MB"

Functions§

run
Executes the diff command to analyze overlay modifications.