Unix backends for Irmin
Module type
Class type
Library irmin-unix
Module Irmin_unix . Git . Maker . Make . Tree
val path_t : path Irmin.Type.t
val step_t : step Irmin.Type.t
val metadata_t : metadata Irmin.Type.t
val contents_t : contents Irmin.Type.t
val contents_key_t : contents_key Irmin.Type.t
val node_t : node Irmin.Type.t
val hash_t : hash Irmin.Type.t

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

Trees are like staging area in Git: they are immutable temporary non-persistent areas (they disappear if the host crash), held in memory for efficiency, where reads are done lazily and writes are done only when needed on commit: if you modify a key twice, only the last change will be written to the store when you commit.


val empty : unit -> tree

empty () is the empty tree. The empty tree does not have associated backend configuration values, as they can perform in-memory operation, independently of any given backend.

val singleton : path -> ?metadata:metadata -> contents -> tree

singleton k c is the tree with a single binding mapping the key k to the contents c.

val of_contents : ?metadata:metadata -> contents -> tree

of_contents c is the subtree built from the contents c.

val of_node : node -> tree

of_node n is the subtree built from the node n.

type elt = [
| `Node of node
| `Contents of contents * metadata

The type for tree elements.

val v : elt -> tree

General-purpose constructor for trees.

val kinded_hash_t : [ `Contents of hash * metadata | `Node of hash ] Irmin.Type.t
val pruned : [ `Contents of hash * metadata | `Node of hash ] -> tree

pruned h is a purely in-memory tree with the hash h. Such trees can be used as children of other in-memory tree nodes, for instance in order to compute the hash of the parent, but they cannot be dereferenced.

Any operation that would require loading the contents of a pruned node (e.g. calling find on one of its children) will instead raise a Pruned_hash exception. Attempting to export a tree containing pruned sub-trees to a repository will fail similarly.

val kind : tree -> path -> [ `Contents | `Node ] option Lwt.t

kind t k is the type of s in t. It could either be a tree node or some file contents. It is None if k is not present in t.

val is_empty : tree -> bool

is_empty t is true iff t is empty (i.e. a tree node with no children). Trees with kind = `Contents are never considered empty.


val diff : tree -> tree -> (path * (contents * metadata) Irmin.Diff.t) list Lwt.t

diff x y is the difference of contents between x and y.

Manipulating Contents

exception Dangling_hash of {
context : string;
hash : hash;

The exception raised by functions that can force lazy tree nodes but do not return an explicit or_error.

exception Pruned_hash of {
context : string;
hash : hash;

The exception raised by functions that attempts to load pruned tree nodes.

exception Portable_value of {
context : string;

The exception raised by functions that attemps to perform IO on a portable tree.

type error = [
| `Dangling_hash of hash
| `Pruned_hash of hash
| `Portable_value
type 'a or_error = ( 'a, error ) result
module Contents : sig ... end

Operations on lazy tree contents.

val mem : tree -> path -> bool Lwt.t

mem t k is true iff k is associated to some contents in t.

val find_all : tree -> path -> (contents * metadata) option Lwt.t

find_all t k is Some (b, m) if k is associated to the contents b and metadata m in t and None if k is not present in t.

val length : tree -> ?cache:bool -> path -> int Lwt.t

length t key is the number of files and sub-nodes stored under key in t.

It is equivalent to List.length (list t k) but backends might optimise this call: for instance it's a constant time operation in irmin-pack.

cache defaults to true, see caching for an explanation of the parameter.

val find : tree -> path -> contents option Lwt.t

find is similar to find_all but it discards metadata.

val get_all : tree -> path -> (contents * metadata) Lwt.t

Same as find_all but raise Invalid_arg if k is not present in t.

val list : tree -> ?offset:int -> ?length:int -> ?cache:bool -> path -> (step * tree) list Lwt.t

list t key is the list of files and sub-nodes stored under k in t. The result order is not specified but is stable.

offset and length are used for pagination.

cache defaults to true, see caching for an explanation of the parameter.

val get : tree -> path -> contents Lwt.t

Same as get_all but ignore the metadata.

val add : tree -> path -> ?metadata:metadata -