Guide

Advanced Topics

Deeper tooling for sandboxes, file sets, and power-user workflows.

File sets

A file set is a deterministic, content-addressable snapshot of a directory tree. Overplane captures it as a compact binary blob that records only what defines the content: each file's relative path, its permission bits, its raw size, and a short content hash — followed by the (snappy-compressed) file payloads. There are no timestamps, no ownership, and no duplicate paths, and entries are sorted in a single total order.

Because nothing non-deterministic is recorded, the same logical tree always produces the same content hash and the same bytes. The content hash is computed over the uncompressed manifest, so it is independent of the compression mode, and it is embedded in the blob and re-verified on load — any corrupted byte is detected.

A file-set delta is the difference between two file sets, expressed as set (add or replace a path with its full content) and del (remove a path) operations. Deltas are whole-file: a single changed byte re-sets the entire file (there is no partial/binary diffing), which keeps the format simple and deterministic.

Creating and inspecting

fileset create walks a directory into a blob. By default it honors .gitignore (with full nested semantics) and skips the .git directory; symlinks are followed to regular files. Use - as a blob path to read stdin or write stdout.

# Snapshot ./src into out.fset (gitignore respected, .git skipped):
overplane fileset create ./src out.fset

# Inspect entries, sizes, modes, hashes, and the content hash:
overplane fileset inspect out.fset

# Include everything and store uncompressed, streaming to stdout:
overplane fileset create --no-gitignore --include-git --store . - > all.fset

Extracting

fileset extract syncs a blob into a destination directory, restoring permission bits and creating directories. By default this is a clean sync: files on disk that are absent from the blob are deleted, and changed files are written in place so inotify watchers on unchanged paths keep their inodes. Pass --additive to overlay without deleting strays. A non-empty destination is refused unless --force is passed.

overplane fileset extract out.fset ./restored
overplane fileset extract --additive out.fset ./overlay

Diffing and applying

fileset diff computes the delta between two file sets, and fileset apply applies a delta to a base file set to reproduce the target. Applying the diff of two sets always reproduces the second set exactly (same content hash).

overplane fileset diff a.fset b.fset delta.fsd
overplane fileset apply a.fset delta.fsd rebuilt.fset
# rebuilt.fset is byte-for-byte identical to b.fset