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 remotes lists the registries you've configured; registry ls lists the fixtures inside a bucket. And registry remove forgets a remote, while registry rm deletes fixtures from one.

Sync model

Push

bocal push customer-a --tag v1
  1. Read the local tag's fixture.toml + all files, compute SHA-256 of each.
  2. Upload every file to s3://<bucket>/<prefix>customer-a/v1/ (multipart for large files).
  3. Last, upload manifest.json — per-file SHA-256 plus services, 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
  1. Fetch manifest.json.
  2. For each file: skip if a local copy already matches by SHA-256; otherwise download.
  3. 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.