Registry
A registry is an S3-compatible bucket used to share fixtures between machines. See Configuration for setting one up (bucket, endpoint, region, path-style, per-registry AWS profile).
Managing registries (like git remotes)
bocal registry add origin s3://my-team-bocal --region us-east-1 # git remote add
bocal registry remotes # git remote -v
bocal registry remove staging # git remote remove
bocal push customer-a --registry origin
registry add validates the bucket with a live HeadBucket (using the resolved credentials, including --profile), so misconfiguration fails at add time. --global writes to ~/.config/bocal/config.toml for cross-project use. remotes marks the default (BOCAL_REGISTRY, else default) with a *.
Two different "lists":
registry remoteslists the registries you've configured;registry lslists the fixtures inside a bucket. Andregistry removeforgets a remote, whileregistry rmdeletes fixtures from one.
Sync model
Push
bocal push customer-a --tag v1
- Read the local tag's
fixture.toml+ all files, compute SHA-256 of each. - Upload every file to
s3://<bucket>/<prefix>customer-a/v1/(multipart for large files). - Last, upload
manifest.json— per-file SHA-256 plusservices,created_at,description,pushed_at,pushed_by.
Writing the manifest last makes the push atomic from a reader's point of view: a tag with no manifest is ignored by pull/diff/ls, so an interrupted push is never mistaken for a valid tag.
Pull
bocal pull customer-a --tag v1
- Fetch
manifest.json. - For each file: skip if a local copy already matches by SHA-256; otherwise download.
- Verify checksums after download.
Conflict handling
Pull without --force errors if a local tag exists and any file's SHA-256 differs from the remote — divergence is by checksum, never mtime. If everything matches, pull is a no-op. The error shows which files differ plus local vs remote provenance, and suggests --force (overwrite) or --tag (pull into a new tag). restore --pull applies the same rule but has no --force: a diverged local tag is a hard error telling you to resolve it first.
Listing
bocal registry ls scans the bucket for */*/manifest.json and renders one row per tag from the manifest alone (no fixture.toml fetch):
FIXTURE TAG SERVICES PUSHED AT PUSHED BY
customer-a latest postgres, dolt 2026-06-20 10:12 alice@...
customer-a v1 postgres, dolt 2026-06-18 09:44 francois@...
empty latest postgres 2026-06-15 14:01 francois@...
Deletion
bocal registry rm customer-a --tag experiment # one tag
bocal registry rm customer-a # whole fixture (all tags)
Deletes the manifest first (instantly invisible to readers), then the rest. The confirmation is louder than local rm because it removes the fixture for everyone with registry access. --yes skips it.
Two diffs
bocal diff <a> <b>— compare two local fixtures/tags (see Commands).bocal registry diff <name>— compare one tag, local vs remote, by checksum.
Concurrency
bocal serializes store-mutating operations on a single machine with per-fixture advisory locks. It does not coordinate two machines (or two pushes) writing the same tag to the registry — there it's last-writer-wins at the object level, surfaced afterward by the checksum-based pull conflict check.