module C : Irmin.Contents.SIrmin stores are tree-like read-write stores with extended capabilities. They allow an application (or a collection of applications) to work with multiple local states, which can be forked and merged programmatically, without having to rely on a global state. In a way very similar to version control systems, Irmin local states are called branches.
There are two kinds of store in Irmin: the ones based on persistent named branches and the ones based temporary detached heads. These exist relative to a local, larger (and shared) store, and have some (shared) contents. This is exactly the same as usual version control systems, that the informed user can see as an implicit purely functional data-structure.
The type for key steps.
The type for store keys. A key is a sequence of steps.
type contents = C.tThe type for store contents.
Type for persistent branch names. Branches usually share a common global namespace and it's the user's responsibility to avoid name clashes.
The type for errors associated with functions computing least common ancestors
The type for errors for fast_forward.
module Repo : sig ... endRepositories.
empty repo is a temporary, empty store. Becomes a normal temporary store after the first update.
master repo is a persistent store based on r's master branch. This operation is cheap, can be repeated multiple times.
of_branch r name is a persistent store based on the branch name. Similar to master, but use name instead Branch.S.master.
of_commit c is a temporary store, based on the commit c.
Temporary stores do not have stable names: instead they can be addressed using the hash of the current commit. Temporary stores are similar to Git's detached heads. In a temporary store, all the operations are performed relative to the current head and update operations can modify the current head: the current stores's head will automatically become the new head obtained after performing the update.
tree t is t's current tree. Contents is not allowed at the root of the tree.
module Status : sig ... endStatus provides base functions for store statuses.
module Head : sig ... endManaging the store's heads.
module Commit : sig ... endCommit defines immutable objects to describe store updates.
Managing store's trees.
module Tree : sig ... endTree provides immutable, in-memory partial mirror of the store, with lazy reads and delayed writes.
module Contents : sig ... endContents provides base functions for the store's contents.
kind is Tree.kind applied to t's root tree.
list t is Tree.list applied to t's root tree.
mem_tree t is Tree.mem_tree applied to t's root tree.
find_all t is Tree.find_all applied to t's root tree.
get_all t is Tree.get_all applied on t's root tree.
find_tree t is Tree.find_tree applied to t's root tree.
type 'a transaction =
?allow_empty:bool ->
?strategy:[ `Set | `Test_and_set | `Merge ] ->
?max_depth:int ->
?n:int ->
info:Irmin.Info.f ->
'a ->
unit Lwt.tThe type for transactions.
with_tree t k ~info f replaces atomically the subtree v under k in the store t by the contents of the tree f v, using the commit info info ().
If v = f v and allow_empty is unset (default) then, the operation is a no-op.
If v != f v and no other changes happen concurrently, f v becomes the new subtree under k. If other changes happen concurrently to that operations, the semantics depend on the value of strategy:
strategy = `Set, the last write wins.strategy = `Test_and_set (default), the transaction is restarted.strategy = `Merge, concurrent changes are merged with f
v. If the merge has a conflict, the transaction is restarted.Note: Irmin transactions provides snapshot isolation guarantees: reads and writes are isolated in every transaction, but only write conflicts are visible on commit.
val set : t -> key -> ?metadata:metadata -> contents transactionset t k ~info v is with_tree t k ~info (fun tree -> Tree.add
tree [] v).
val set_tree : t -> key -> tree transactionset_tree t k ~info v is with_tree t k ~info (fun tree ->
Tree.add_tree tree [] v).
val remove : t -> key transactionremove t i k is with_tree t i k (fun tree -> Tree.remove tree
[]).
clone ~src ~dst makes dst points to Head.get src. dst is created if needed. Remove the current contents en dst if src is empty.
watch t f calls f every time the contents of t's head is updated.
Note: even if f might skip some head updates, it will never be called concurrently: all consecutive calls to f are done in sequence, so we ensure that the previous one ended before calling the next one.
val watch_key :
t ->
key ->
?init:commit ->
((commit * tree) Irmin.diff -> unit Lwt.t) ->
watch Lwt.twatch_key t key f calls f every time the key's value is added, removed or updated. If the current branch is deleted, no signal is sent to the watcher.
type 'a merge =
info:Irmin.Info.f ->
?max_depth:int ->
?n:int ->
'a ->
(unit, Irmin.Merge.conflict) Result.result Lwt.tThe type for merge functions.
merge ~into i t merges t's current branch into x's current branch using the info i. After that operation, the two stores are still independent. Similar to git merge <branch>.
lca ?max_depth ?n msg t1 t2 returns the collection of least common ancestors between the heads of t1 and t2 branches.
max_depth is the maximum depth of the exploration (default is max_int). Return Error `Max_depth_reached if this depth is exceeded.n is the maximum expected number of lcas. Stop the exploration as soon as n lcas are found. Return Error
`Too_many_lcas if more lcas are found.val lcas_with_branch :
t ->
?max_depth:int ->
?n:int ->
branch ->
(commit list, lca_error) Result.result Lwt.tSame as lcas but takes a branch ID as argument.
val lcas_with_commit :
t ->
?max_depth:int ->
?n:int ->
commit ->
(commit list, lca_error) Result.result Lwt.tSame as lcas but takes a commit ID as argument.
module History : Graph.Sig.P with type V.t = commitAn history is a DAG of heads.
history ?depth ?min ?max t is a view of the history of the store t, of depth at most depth, starting from the max (or from the t's head if the list of heads is empty) and stopping at min if specified.
module Branch : sig ... endManipulate branches.
Key provides base functions for the stores's paths.
module Metadata : Irmin.Metadata.S with type t = metadataMetadata provides base functions for node metadata.
val step_t : step Irmin.Type.tstep_t is the value type for step.
val key_t : key Irmin.Type.tkey_t is the value type for key.
val metadata_t : metadata Irmin.Type.tmetadata_t is the value type for metadata.
val contents_t : contents Irmin.Type.tcontents_t is the value type for contents.
val node_t : node Irmin.Type.tnode_t is the value type for node.
val tree_t : tree Irmin.Type.ttree_t is the value type for tree.
val commit_t : Repo.t -> commit Irmin.Type.tcommit_t r is the value type for commit.
val branch_t : branch Irmin.Type.tbranch_t is the value type for branch.
val slice_t : slice Irmin.Type.tslice_t is the value type for slice.
val kind_t : [ `Node | `Contents ] Irmin.Type.tkind_t is the value type for values returned by kind.
val kinde_t : [ `Empty | `Node | `Contents ] Irmin.Type.tkind_t is like kind_t but also allow `Empty values.
val lca_error_t : lca_error Irmin.Type.tlca_error_t is the value type for lca_error.
val ff_error_t : ff_error Irmin.Type.tff_error_t is the value type for ff_error.
module Private : sig ... endPrivate functions, which might be used by the backends.