Skip to content

Instantly share code, notes, and snippets.

@zshipko

zshipko/irmin-2.0-migration-guide.md

Last active August 28, 2020 14:15
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save zshipko/88b4ef34815624ca7dbffd809e8eeec7 to your computer and use it in GitHub Desktop.
Save zshipko/88b4ef34815624ca7dbffd809e8eeec7 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
irmin-2.0-migration-guide.md

Irmin 2.0 Release

The Irmin team is happy to announce the 2.0.0 release of Irmin, an OCaml library and command-line tool for building Git-like databases. This release includes many improvements made to the usability and consistency of the API in addition to some new features. A website and tutorial have also been created: irmin.io!

Updates

  • Added irmin-graphql package for serving Irmin data over GraphQL
    • You can also use irmin graphql on the command-line to start a server
  • Added irmin-test package to enable external Irmin backends to reuse the existing test suite
  • Irmin.Contents.Json and Irmin.Contents.Json_value content types were added
  • Irmin.Json_tree allows for JSON objects to be written as trees
  • The custom config file format has been changed to YAML and it is now possible to create a global configuration file (~/.irmin/config.yml)
  • Updates to Irmin.Type combinator to simplify the creation of custom contents
  • Upgraded to irmin-git 2.0
  • Lots of bugfixes!
  • See CHANGES.md for a full list

Migration Guide

Irmin 2.0 cleans up many of the rough edges found in Irmin 1.x, because of this there are a few breaking changes that need to be addressed in order to upgrade.

Command line application

Command names

Many commands have been renamed to match the corresponding action in the OCaml API:

  • read was changed to get
  • write was changed to set

.irminconfig

The .irminconfig file has been replaced by irmin.yml - the format has also changed to YAML. This means you will need to convert your existing .irminconfig files to YAML, which in most cases means changing the = seperator to an :.

A new global configuration file at ~/.irmin/config.yml has also been added. A .irmin.yml in the same directory (or passed as a command line argument) takes precedence over the global configuration.

OCaml library

Irmin.Contents.Cstruct

Irmin.Contents.Cstruct has been removed

  • If possible, switch to either Irmin.Contents.String or Irmin.Contents.Bytes
  • You can also use Irmin.Type.map to wrap the cstruct type if needed.

Irmin.Contents.S0

Irmin.Contents.S0 has been replaced with Irmin.Type.S

Irmin.Contents.S

pp and of_string are no longer needed when defining a content type. This is due to the addition of Irmin.Type.to_string and Irmin.Type.of_string.

Irmin.remote_uri

Irmin.remote_uri has been removed and has been moved into the Irmin store module when remote operations are supported. For example, Irmin_mem.S does not contain a remote function, however Irmin_unix.Git.S does.

  • Change all calls from Irmin.remote_uri to Store.remote

String conversion for Irmin.Type.t

Functions like Irmin.Contents.String.pp and Irmin.Contents.String.of_string have been removed in favor of more general string conversion provided by Irmin.Type.

  • Irmin.Type.t values can be encoded/decoded using Irmin.Type.to_string and Irmin.Type.from_string, Irmin.Type.to_json_string and Irmin.Type.from_json_string or Irmin.Type.to_bin_string and Irmin.Type.from_bin_string

Irmin.Type.like

Irmin.Type.like has been renamed to Irmin.Type.map.

A new Irmin.Type.like has also been added, which is a simplified version of Irmin.Type.map without the function parameters.

  • Switch Irmin.Type.like to Irmin.Type.map

Store.set

Store.sethas been moved toStore.set_exnandStore.set` new returns a result since it may fail.

  • Switch to Store.set_exn or handle the result value

Irmin.AO and Irmin.RW

As part of the effort to help clarify the API, Irmin.AO and Irmin.RW have been given more descriptive names:

Irmin.AO has been replaced with Irmin.CONTENT_ADDRESSABLE_STORE and Irmin.AO_MAKER has been replaced with Irmin.CONTENT_ADDRESSABLE_STORE_MAKER

Irmin.RW has been replaced with Irmin.ATOMIC_WRITE_STORE and Irmin.RW_MAKER has been replaced with Irmin.ATOMIC_WRITE_STORE_MAKER.

batch function

A batch function has been added as part of the backend definition. This can be used to control how groups of operations are processed.

Digestif

Executable applications using irmin will need to link digestif.c or digestif.ocaml at compile time.

  • Add digestif.c to the libraries section of your executable stanza

Irmin_mirage reorganization

irmin-mirage has been split into irmin-mirage, irmin-mirage-git and irmin-mirage-graphql to avoid forcing users to include unused dependencies.

  • If you're using Irmin_mirage.Git.* it should be replaced with Irmin_mirage_git.*

fetch/pull/push return a new status result

Irmin.Sync.fetch, Irmin.Sync.pull and Irmin.Sync.push now return a status value: [`Empty | `Head of commit].

  • Handle or ignore the result of the above functions depending on your application.
@aweis
Copy link

aweis commented May 1, 2019

irmin.io seems down for me

@zshipko
Copy link
Author

zshipko commented May 7, 2019

@aweis - It should just redirect to the irmin repository right now, the website is not set up yet.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment