ver organizes everything around three ideas: contexts, snapshots, and chunks.
Contexts
A context is a named pairing of:
- a filesystem backend, where blob chunks, the head pointer, and the snapshot history are stored;
- a KV backend, where snapshot metadata, snapshot names, and in-progress merges live.
Contexts are declared in ~/.ver/contexts.toml. One of them is marked current; every ver command operates on the current context unless told otherwise.
| Filesystem backend | ver ctx scaffold --fs |
Blob storage |
|---|---|---|
| Local disk | local |
<base>/.ver/blobsdb/ |
| Amazon S3 | s3 |
bucket |
| Google Cloud Storage | gcs |
bucket |
| Azure Blob Storage | azure |
container |
| KV backend | ver ctx scaffold --kv |
Storage |
|---|---|---|
| Embedded | embedded |
a local redb file |
| Redis | redis |
a Redis server |
Two validation rules matter:
- An embedded KV can only pair with a local filesystem. A redb file on your laptop makes no sense for blobs in a bucket, so remote filesystems need Redis.
- Local
base_directoryandredb_pathmust be absolute paths.
Because contexts are just backend pairings, two contexts can point at the same project through different storage. That is what makes sync and merge possible.
Snapshots
A snapshot is a map from file paths to lists of chunks, plus:
parent_ids: the snapshots it descends from (one for a normal snapshot, two for a merge);partial: whether it describes the whole project or only some files.
Snapshots are serialized and stored in the KV backend under their content hash, so a snapshot’s ID is its BLAKE3 hash. Names (my-first-snapshot) are just pointers to IDs, and you can use either interchangeably on the CLI.
The head pointer (.ver/head in the filesystem backend) records which snapshot the project currently sits on.
Chunks
When you snapshot a file, ver:
- Splits it with FastCDC content-defined chunking (64 KiB min, 256 KiB average, 1 MiB max). Chunk boundaries depend on content, not position, so editing the middle of a file only changes the chunks around the edit.
- Hashes each chunk with BLAKE3. The hash is the chunk’s address in the blob store.
- Compresses each chunk with zstd and writes it to
.ver/blobsdb/<hash>.
Identical content is never stored twice, within one file or across the whole project.
What goes where
| Data | Backend | Location |
|---|---|---|
| Blob chunks | filesystem | .ver/blobsdb/<blake3-hash> |
| Head pointer | filesystem | .ver/head |
| Snapshot history entries | filesystem | .ver/snapshots_history/<snapshot-id> |
| Snapshot contents | KV | snapshots table / snapshots/ namespace |
| Name → snapshot ID | KV | names table / names namespace |
| Partial merges | KV | partial_merges table / partial_merges namespace |
Ignoring files
Create a .verignore file at the project root. It follows .gitignore syntax. The .ver/ directory itself is always excluded from snapshots.