package irmin

The type for Irmin repositories.

The type for Irmin stores.

The type for key steps.

The type for store keys. A key is a sequence of steps.

The type for store metadata.

The type for store contents.

The type for store nodes.

The type for store trees.

The type for object hashes.

Type for commit identifiers. Similar to Git's commit SHA1s.

Type for persistent branch names. Branches usually share a common global namespace and it's the user's responsibility to avoid name clashes.

Type for store slices.

The type for errors associated with functions computing least common ancestors

The type for errors for fast_forward.

Repositories.

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.

repo t is the repository containing t.

tree t is t's current tree. Contents is not allowed at the root of the tree.

Status provides base functions for store statuses.

status t is t's status. It can either be a branch, a commit or empty.

Managing the store's heads.

Object hashes.

Commit defines immutable objects to describe store updates.

Contents provides base functions for the store's contents.

Tree provides immutable, in-memory partial mirror of the store, with lazy reads and delayed writes.

kind is Tree.kind applied to t's root tree.

list t is Tree.list applied to t's root tree.

mem t is Tree.mem 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.

find t is Tree.find applied to t's root tree.

get_all t is Tree.get_all applied on t's root tree.

get t is Tree.get applied to t's root tree.

find_tree t is Tree.find_tree applied to t's root tree.

get_tree t k is Tree.get_tree applied to t's root tree.

hash t k

The type for write errors.

• Merge conflict.
• Concurrent transactions are competing to get the current operation committed and too many attemps have been tried (livelock).
• A "test and set" operation has failed and the current value is v instead of the one we were waiting for.

set t k ~info v sets k to the value v in t. Discard any previous results but ensure that no operation is lost in the history.

This function always uses Metadata.default as metadata. Use set_tree with `Contents (c, m) for different ones.

The result is Error `Too_many_retries if the concurrent operations do not allow the operation to commit to the underlying storage layer (livelock).

set_exn is like set but raise Failure _ instead of using a result type.

set_tree is like set but for trees.

set_tree is like set_exn but for trees.

remove t ~info k remove any bindings to k in t.

The result is Error `Too_many_retries if the concurrent operations do not allow the operation to commit to the underlying storage layer (livelock).

remove_exn is like remove but raise Failure _ instead of a using result type.

test_and_set ~test ~set is like set but it atomically checks that the tree is test before modifying it to set.

This function always uses Metadata.default as metadata. Use test_and_set_tree with `Contents (c, m) for different ones.

The result is Error (`Test t) if the current tree is t instead of test.

The result is Error `Too_many_retries if the concurrent operations do not allow the operation to commit to the underlying storage layer (livelock).

test_and_set_exn is like test_and_set but raise Failure _ instead of using a result type.

test_and_set_tree is like test_and_set but for trees.

test_and_set_tree_exn is like test_and_set_exn but for trees.

merge ~old is like set but merge the current tree and the new tree using old as ancestor in case of conflicts.

This function always uses Metadata.default as metadata. Use merge_tree with `Contents (c, m) for different ones.

The result is Error (`Conflict c) if the merge failed with the conflict c.

The result is Error `Too_many_retries if the concurrent operations do not allow the operation to commit to the underlying storage layer (livelock).

merge_exn is like merge but raise Failure _ instead of using a result type.

merge_tree is like merge_tree but for trees.

merge_tree is like merge_tree but for trees.

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:

• if strategy = `Set, use set and discard any concurrent updates to k.
• if strategy = `Test_and_set (default), use test_and_set and ensure that no concurrent operations are updating k.
• if strategy = `Merge, use merge and ensure that concurrent updates and merged with the values present at the beginning of the transaction.

Note: Irmin transactions provides snapshot isolation guarantees: reads and writes are isolated in every transaction, but only write conflicts are visible on commit.

with_tree_exn is like with_tree but raise Failure _ instead of using a return type.

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.

The type for store watches.

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.

watch_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.

unwatch w disable w. Return once the w is fully disabled.

The type for merge functions.

merge_into ~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>.

Same as merge but with a branch ID.

Same as merge but with a commit ID.

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.

Same as lcas but takes a branch ID as argument.

Same as lcas but takes a commit ID as argument.

An 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.

last_modified ?number c k is the list of the last number commits that modified key, in ascending order of date. depth is the maximum depth to be explored in the commit graph, if any. Default value for number is 1.

Manipulate branches.

Key provides base functions for the stores's paths.

Metadata provides base functions for node metadata.

step_t is the value type for step.

key_t is the value type for key.

metadata_t is the value type for metadata.

contents_t is the value type for contents.

node_t is the value type for node.

tree_t is the value type for tree.

commit_t r is the value type for commit.

branch_t is the value type for branch.

slice_t is the value type for slice.

kind_t is the value type for values returned by kind.

lca_error_t is the value type for lca_error.

ff_error_t is the value type for ff_error.

write_error_t is the value type for write_error.

Private functions, which might be used by the backends.

to_private_node n is the private node objects built using n. The operation can fetch the database to read an object as n could be represented as a hash. The result is None iff that hash doesn't exist in the database.

of_private_node r n is the node build from the private node object n.

to_private_commit c is the private commit object associated with the commit c.

of_private_commit r c is the commit associated with the private commit object c.

Save a content into the database

Save a tree into the database. Does not do any reads. If clear is set (it is by default), the tree cache will be cleared after the save.