Module Irmin

Irmin public API.

Irmin is a library to design and use persistent stores with built-in snapshot, branching and reverting mechanisms. Irmin uses concepts similar to Git but it exposes them as a high level library instead of a complex command-line frontend. It features a bidirectional Git backend, where an application can read and persist its state using the Git format, fully-compatible with the usual Git tools and workflows.

Irmin is designed to use a large variety of backends. It is written in pure OCaml and does not depend on external C stubs; it is thus very portable and aims to run everywhere, from Linux to browser and MirageOS unikernels.

Consult the basics and examples of use for a quick start. See also the documentation for the unix backends.

Release 2.2.0 - %%HOMEPAGE%%

val version : string

The version of the library.


module Type : sig ... end

Dynamic types for Irmin values.

module Info : sig ... end

Commit info are used to keep track of the origin of write operations in the stores. Info models the metadata associated with commit objects in Git.

module Merge : sig ... end

Merge provides functions to build custom 3-way merge operators for various user-defined contents.

module Diff : sig ... end

Differences between values.

type 'a diff = 'a Diff.t

The type for representing differences betwen values.

Low-level Stores

module type CONTENT_ADDRESSABLE_STORE = sig ... end

Content-addressable backend store.

module type APPEND_ONLY_STORE = sig ... end

Append-only backend store.

module type ATOMIC_WRITE_STORE = sig ... end

Atomic-write stores.

User-Defined Contents

module Path : sig ... end

Store paths.

module Hash : sig ... end

Hashing functions.

module Metadata : sig ... end

Metadata defines metadata that is attached to contents but stored in nodes. The Git backend uses this to indicate the type of file (normal, executable or symlink).

module Contents : sig ... end

Contents specifies how user-defined contents need to be serializable and mergeable.

module Branch : sig ... end

User-defined branches.

type remote = ..

The type for remote stores.

type config

The type for backend-specific configuration values.

Every backend has different configuration options, which are kept abstract to the user.

module Private : sig ... end

Private defines functions only useful for creating new backends. If you are just using the library (and not developing a new backend), you should not use this module.

High-level Stores

exception Closed

The exception raised when any operation is attempted on a closed store, except for S.close, which is idempotent.

module type S = sig ... end

Irmin stores.

module Json_tree : functor (Store : S with type contents = Contents.json) -> sig ... end

Json_tree is used to project JSON values onto trees. Instead of the entire object being stored under one key, it is split across several keys starting at the specified root key.

module type S_MAKER = functor (M : Metadata.S) -> functor (C : Contents.S) -> functor (P : Path.S) -> functor (B : Branch.S) -> functor (H : Hash.S) -> S with type key = P.t and type step = P.step and type metadata = M.t and type contents = C.t and type branch = B.t and type hash = H.t and type Private.Sync.endpoint = unit

S_MAKER is the signature exposed by any backend providing S implementations. M is the implementation of user-defined metadata, C is the one for user-defined contents, B is the implementation for branches and H is the implementation for object (blobs, trees, commits) hashes. It does not use any native synchronization primitives.

module type KV = S with type key = string list and type step = string and type branch = string

KV is similar to S but chooses sensible implementations for path and branch.

module type KV_MAKER = functor (C : Contents.S) -> KV with type contents = C.t

KV_MAKER is like S_MAKER but where everything except the contents is replaced by sensible default implementations.


val remote_store : (module S with type t = 'a) -> 'a -> remote

remote_store t is the remote corresponding to the local store t. Synchronization is done by importing and exporting store slices, so this is usually much slower than native synchronization using Store.remote but it works for all backends.

module type SYNC = sig ... end

SYNC provides functions to synchronize an Irmin store with local and remote Irmin stores.

module Sync : functor (S : S) -> SYNC with type db = S.t and type commit = S.commit

The default Sync implementation.


Syncing with a remote

Mergeable logs


module Dot : functor (S : S) -> Dot.S with type db = S.t

Dot provides functions to export a store to the Graphviz `dot` format.


module type APPEND_ONLY_STORE_MAKER = functor (K : Type.S) -> functor (V : Type.S) -> sig ... end

APPEND_ONLY_STORE_MAKER is the signature exposed by append-only store backends. K is the implementation of keys and V is the implementation of values.

module type CONTENT_ADDRESSABLE_STORE_MAKER = functor (K : Hash.S) -> functor (V : Type.S) -> sig ... end

CONTENT_ADDRESSABLE_STOREMAKER is the signature exposed by content-addressable store backends. K is the implementation of keys and V is the implementation of values.

module Content_addressable : functor (S : APPEND_ONLY_STORE_MAKER) -> functor (K : Hash.S) -> functor (V : Type.S) -> sig ... end
module type ATOMIC_WRITE_STORE_MAKER = functor (K : Type.S) -> functor (V : Type.S) -> sig ... end

ATOMIC_WRITE_STORE_MAKER is the signature exposed by atomic-write store backends. K is the implementation of keys and V is the implementation of values.

Simple store creator. Use the same type of all of the internal keys and store all the values in the same store.

module Make_ext : functor (CA : CONTENT_ADDRESSABLE_STORE_MAKER) -> functor (AW : ATOMIC_WRITE_STORE_MAKER) -> functor (Metadata : Metadata.S) -> functor (Contents : Contents.S) -> functor (Path : Path.S) -> functor (Branch : Branch.S) -> functor (Hash : Hash.S) -> functor (Node : Private.Node.S with type metadata = Metadata.t and type hash = Hash.t and type step = Path.step) -> functor (Commit : Private.Commit.S with type hash = Hash.t) -> S with type key = Path.t and type contents = Contents.t and type branch = Branch.t and type hash = Hash.t and type step = Path.step and type metadata = Metadata.t and type Key.step = Path.step and type Private.Sync.endpoint = unit
module Of_private : functor (P : Private.S) -> S with type key = P.Node.Path.t and type contents = P.Contents.value and type branch = P.Branch.key and type hash = P.Hash.t and type step = P.Node.Path.step and type metadata = P.Node.Val.metadata and type Key.step = P.Node.Path.step and type repo = P.Repo.t and type slice = P.Slice.t and module Private = P

Advanced store creator.