Re: [MirageOS-devel] Irmin API newbie questions

[Thomas Gazagnaire <thomas@xxxxxxxxxxxxxx>]

Hi,

I've made a new release of Irmin (0.9.4) with better concurrency properties, 
that I've tried to explain what these properties are on the wiki:

https://github.com/mirage/irmin/wiki/concurrency

That release also fixes the performance issues you found with the computation 
of lcas. I'm working on fixing the other issues you found[1], and I'd 
especially like to improve the watch / notification API based on your very 
useful comments.

I've also started a roadmap page to get a sense of what needs to be done for 
1.0:

https://github.com/mirage/irmin/wiki/Roadmap

And a list of the current and past (summer) projects related to Irmin (not 
really part of the 1.0 process, but can lead to interesting features for the 
next releases):

https://github.com/mirage/irmin/wiki/Projects

Best,
Thomas

[1] https://github.com/mirage/irmin/issues?q=is%3Aopen+is%3Aissue+label%3Abug




> On 9 Feb 2015, at 12:03, Thomas Leonard <talex5@xxxxxxxxx> wrote:
> 
> 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


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