vblt.org
forked from
gazagnaire.org/irmin
Persistent store with Git semantics: lazy reads, delayed writes, content-addressing
1(** High-level store interface.
2
3 Combines backend, tree, and commit operations into a unified API. *)
4
5(** {1 Store Functor} *)
6
7module Make (F : Codec.S) : sig
8 type t
9 (** A store instance. *)
10
11 type hash = F.hash
12
13 module Tree : module type of Tree.Make (F)
14 module Commit : module type of Commit.Make (F)
15
16 (** {2 Construction} *)
17
18 val create : backend:hash Backend.t -> t
19 (** [create ~backend] creates a store backed by [backend]. *)
20
21 (** {2 Tree Operations} *)
22
23 val tree : t -> ?at:hash -> unit -> Tree.t
24 (** [tree t ?at ()] returns a tree. If [at] is given, returns the tree at that
25 commit. Otherwise returns an empty tree. *)
26
27 val checkout : t -> branch:string -> Tree.t option
28 (** [checkout t ~branch] returns the tree at the head of [branch]. *)
29
30 (** {2 Commit Operations} *)
31
32 val commit :
33 t ->
34 tree:Tree.t ->
35 parents:hash list ->
36 message:string ->
37 author:string ->
38 hash
39 (** [commit t ~tree ~parents ~message ~author] creates a commit. This is when
40 delayed tree writes actually happen. *)
41
42 (** {2 Branch Operations} *)
43
44 val head : t -> branch:string -> hash option
45 (** [head t ~branch] returns the head commit of [branch]. *)
46
47 val set_head : t -> branch:string -> hash -> unit
48 (** [set_head t ~branch h] sets the head of [branch] to [h]. *)
49
50 val branches : t -> string list
51 (** [branches t] returns all branch names. *)
52
53 val update_branch : t -> branch:string -> old:hash option -> new_:hash -> bool
54 (** [update_branch t ~branch ~old ~new_] atomically updates [branch] if its
55 current head matches [old]. *)
56
57 (** {2 Ancestry Queries} *)
58
59 val is_ancestor : t -> ancestor:hash -> descendant:hash -> bool
60 (** [is_ancestor t ~ancestor ~descendant] checks commit ancestry. *)
61
62 val merge_base : t -> hash -> hash -> hash option
63 (** [merge_base t h1 h2] finds the common ancestor of two commits. *)
64
65 val commits_between : t -> base:hash -> head:hash -> int
66 (** [commits_between t ~base ~head] counts commits from [base] to [head]. *)
67
68 (** {2 Diff} *)
69
70 type diff_entry =
71 [ `Add of Tree.path * hash
72 | `Remove of Tree.path
73 | `Change of Tree.path * hash * hash ]
74
75 val diff : t -> old:hash -> new_:hash -> diff_entry Seq.t
76 (** [diff t ~old ~new_] computes the difference between two trees. *)
77
78 (** {2 Low-level} *)
79
80 val backend : t -> hash Backend.t
81 (** [backend t] returns the underlying backend. *)
82
83 val read_commit : t -> hash -> Commit.t option
84 (** [read_commit t h] reads a commit by hash. *)
85
86 val read_tree : t -> hash -> Tree.t
87 (** [read_tree t h] returns a lazy tree at [h]. *)
88end
89
90(** {1 Pre-instantiated Stores} *)
91
92module Git : module type of Make (Codec.Git)
93(** Git-format store with SHA-1 hashes. *)
94
95module Mst : module type of Make (Codec.Mst)
96(** MST-format store with SHA-256 hashes. *)