Published: 27 Jul 2022
Built-in Snapshotting - backup and restore
Storage Agnostic - you can use Irmin on top of your own storage layer
Custom Datatypes - (de)serialization for custom data types, derivable via
Highly Portable - runs anywhere from Linux to web browsers and Xen unikernels
Git Compatibility -
irmin-gituses an on-disk format that can be inspected and modified using Git
Dynamic Behavior - allows the users to define custom merge functions, use in-memory transactions (to keep track of reads as well as writes) and to define event-driven workflows using a notification mechanism
API documentation can be found online at https://mirage.github.io/irmin
Please ensure to install the minimum
ocaml versions. Find the latest version and install instructions on ocaml.org.
To install Irmin with the command-line tool and all optional dependencies using
opam install irmin-unix
A minimal installation containing the reference in-memory backend can be installed by running:
opam install irmin
The following packages have been made available on
irmin- the base package, plus an in-memory storage implementation
irmin-chunk- chunked storage
irmin-fs- filesystem-based storage using
irmin-git- Git compatible storage
irmin-graphql- GraphQL server
irmin-http- a simple REST interface
irmin-mirage- mirage compatibility
irmin-mirage-git- Git compatible storage for mirage
irmin-mirage-graphql- mirage compatible GraphQL server
irmin-unix- unix compatibility
irmin-pack- compressed, on-disk, posix backend
ppx_irmin- PPX deriver for Irmin content types (see README_PPX.md)
irmin-containers- collection of simple, ready-to-use mergeable data structures
To install a specific package, simply run:
opam install <package-name>
To install the development version of Irmin in your current
opam switch, clone this repository and
opam install the packages inside:
git clone https://github.com/mirage/irmin cd irmin/ opam install .
Below is a simple example of setting a key and getting the value out of a Git-based, filesystem-backed store.
open Lwt.Syntax (* Irmin store with string contents *) module Store = Irmin_unix.Git.FS.KV (Irmin.Contents.String) (* Database configuration *) let config = Irmin_git.config ~bare:true "/tmp/irmin/test" (* Commit author *) let author = "Example <email@example.com>" (* Commit information *) let info fmt = Irmin_unix.info ~author fmt let main = (* Open the repo *) let* repo = Store.Repo.v config in (* Load the main branch *) let* t = Store.main repo in (* Set key "foo/bar" to "testing 123" *) let* () = Store.set_exn t ~info:(info "Updating foo/bar") [ "foo"; "bar" ] "testing 123" in (* Get key "foo/bar" and print it to stdout *) let+ x = Store.get t [ "foo"; "bar" ] in Printf.printf "foo/bar => '%s'\n" x (* Run the program *) let () = Lwt_main.run main
The example is contained in examples/readme.ml It can be compiled and executed with dune:
$ dune build examples/readme.exe $ dune exec examples/readme.exe foo/bar => 'testing 123'
The examples directory also contains more advanced examples, which can be executed in the same way.
The same thing can also be accomplished using
irmin, the command-line application installed with
irmin-unix, by running:
$ echo "root: ." > irmin.yml $ irmin init $ irmin set foo/bar "testing 123" $ irmin get foo/bar testing 123
irmin.yml allows for
irmin flags to be set on a per-directory basis. You can also set flags globally using
irmin help irmin.yml for further details.
irmin --help for list of all commands and either
irmin <command> --help or
irmin help <command> for more help with a specific command.
Feel free to to report any issues using the GitHub bugtracker.
See the LICENSE file.
Development of Irmin was supported in part by the EU FP7 User-Centric Networking project, Grant No. 611001.