[MirageOS-devel] Irmin API newbie questions

[Thomas Leonard <talex5@xxxxxxxxx>]

I'm trying to understand the Irmin API. The current documentation is
good, but I'm still having trouble with some of the concepts. I'm
looking at these sources:

  https://mirage.github.io/irmin/
  https://github.com/mirage/irmin/wiki/Using-the-Irmin-API


(BTW, I think it might be useful to add the equivalent git command
next to functions in the documentation, since most people will
understand that already)


Anyway, my questions:


The BASIC docs are missing
(https://mirage.github.io/irmin/Irmin.BASIC.html), but the code shows:

  type ('a, 'b) basic = (module BASIC with type key = 'a and type value = 'b)

It seems that using Irmin.Contents.String gets me "key = string list",
but "step" remains abstract. How do I use cons, decons, etc?


If I have a RW store, I can watch a key:

  val watch : t -> key -> value option Lwt_stream.t

Presumably, I also need to take care to stop watching it when I'm
done, otherwise the stream will grow without limit, right? I guess
there should be an unwatch, or maybe this should be a React signal or
something.


I got a bit confused when I reached the BC page:

  https://mirage.github.io/irmin/Irmin.BC.html

It uses 'tag' to mean a pointer to a commit that is updates on each
operation (i.e. what Git would call a 'branch'). I realise that tags
and branches are the same thing internally, but 'branch' seems to
capture better what Irmin is using them for ("The tag value is updated
every time the store is updated, so every handle connected or which
will be connected to the same tag will see the changes."). [ BTW,
what's a "handle"? ]


val update_tag : t -> tag -> unit Lwt.t
update_tag t tag updates t's current branch with the contents of the
branch named tag.

What does "update" mean here? Is this "git reset --hard tag"? A merge?
A "--ff-only" merge?


My mental model of Git is that the store is a DAG and I can append to
any branch. e.g. we have:

   git commit-tree <tree> [(-p <parent>)...] < changelog

If I'm understanding the Irmin API correctly, each "store"
(repository? branch?) has a current "tag" (branch) and I need to set
the tag I want to work on, e.g.

  val switch : Store.t -> tag -> unit Lwt.t

If I want to work on another branch without changing the current
branch for other users, I should "clone" the store:

  val clone_force : ('a -> Irmin.task) -> t -> tag -> ('a -> t) Lwt.t

But, this is not a "git clone", it's like "git branch tag" - a new
branch I can work on without affecting the repository's default
branch. It seems strange that Irmin has a mutable "current branch" at
all - this seems like a UI concept that's only needed for command-line
use (to save typing).


A "head" is defined as "a given store revision" (i.e. what Git would
call a commit). It wasn't clear to me at first whether a head was a
commit or an anonymous branch. e.g.

val rename_tag : t -> tag -> [ `Duplicated_tag | `Ok ] Lwt.t
Change the current tag name. Fail if a tag with the same name already
exists. The head is unchanged.

"The head is unchanged" suggests that heads might change in other
cases. Looking at the code, I see a "type head = Commit.key" in one
place, so I guess they're (usually?) commits. Does "head" here mean
"the default branch"?


Finally, how do I get history? e.g. if I want to show users the recent
changes to a document. I see a "slice" type, but it's not clear what I
can do with it.


Thanks!


-- 
Dr Thomas Leonard        http://0install.net/
GPG: 9242 9807 C985 3C07 44A6  8B9A AE07 8280 59A5 3CC1
GPG: DA98 25AE CAD0 8975 7CDA  BD8E 0713 3F96 CA74 D8BA

_______________________________________________
MirageOS-devel mailing list
MirageOS-devel@xxxxxxxxxxxxxxxxxxxx
http://lists.xenproject.org/cgi-bin/mailman/listinfo/mirageos-devel