provcat.stores.lakefs

The lakefs driver is the S3 driver plus the lakeFS REST API. It reads data through the S3 gateway of lakeFS, where the bucket is the repository and the first key segment is a ref: a branch, a tag or a commit. It asks the API three things that the gateway cannot answer:

• pin: the commit that a ref points at. pin turns lakefs://repo/main/path into lakefs://repo/<commit>/path, which never changes. A branch also holds uncommitted changes, which the S3 gateway shows and a pinned URI does not.
• ts: lakefs://repo/main/path?at=ts:2026-10-01 names the last commit of main made at or before that time. stat, ls and fetch pin it first, then read that commit.
• refs: whether a ref exists, so ls of an empty branch gives [], and a missing branch says so.

Options are those of the S3 driver, plus api_url. The default for api_url is endpoint_url followed by /api/v1. The API takes the same keys as the gateway, from the same AWS profile or environment.

Pins are kept in the cache, so --offline pins a branch or a time to the commit that the last online pin found.

Writes go to a branch, through the S3 gateway:

• put and delete change objects on a branch. The change is not committed, so a pinned URI does not show it.
• commit commits a branch, with a message and metadata, and returns the pinned URI of the new commit.
• branch makes a branch from a branch, a tag or a commit.
• merge merges a branch, a tag or a commit into a branch, and returns the pinned URI of the merge commit. It merges the source’s last commit, so uncommitted changes on a source branch stay behind.

A write to a commit or a tag is refused, because lakeFS cannot change one.