Getting Started

This is a brief tutorial to start playing with Irmin and its command-line tool.

Using the In-Memory Backend

Let's start by creating a new Irmin instance, which stores its data in memory. To do this, we can use the irmin command-line tool, which is an easy-way to access the Irmin libraries and APIs. The command-line tool is availble only if git and cohttp are also installed (eg. you need to run opam install git cohttp irmin).

$ mkdir /tmp/irmin-mem && cd /tmp/irmin-mem
$ irmin init -d -v -s mem # Start a server (-d) in-memory (-s mem) and display some events (-v)
2015-02-05 11:30:38.119              INFO : daemon: http://localhost:8080
Server started on port 8080.

You can now open a new terminal, tell Irmin to use by a remote HTTP store (-s http) located at http://127.0.0.1:8080 (--uri ...) and start writing few things in the store.

$ irmin write a/b foo -s http --uri http://127.0.0.1:8080
$ irmin write a/c bar -s http --uri http://127.0.0.1:8080

You can then inspect the store contents:

$ irmin tree -s http --uri http://127.0.0.1:8080
/a/b..............................................................................."foo"
/a/c..............................................................................."bar"
$ irmin read a/b -s http --uri http://127.0.0.1:8080
foo

Keep writing -s http --uri http://127.0.0.1:8080 could be annoying, so the Irmin command-line has basic support for local configuration file. Create an .irminconfig file with the following contents:

store=http
uri=http://127.0.0.1:8080

and irmin tree should work as expected.

This state looks good, so we want to keep track of it if later something bad happens to the database.

$ STATE=`irmin snapshot`
$ irmin write a/b notfoo
# [...]
$ irmin revert $STATE
$ irmin tree
/a/b..............................................................................."foo"
/a/c..............................................................................."bar"

Under the hood there are three different kind of objects that are stored in the database. First the raw objects (or blobs) are the one that are directly provided by the user (or the application). That's foo and bar here. There are tree objects, which are similar to filesystem inodes, which are used by Irmin to keep track of directories. Finally, there are commit objects, which are used to keep track of the state history (and are useful to snapshot and rollback).

You can see the relation between this objects by dumping the database state in a .dot file.

$ irmin dot thestate
$ cat thestate.dot
# [..] A graphivz graph
$ open thestate.png`

TODO: explain how to read diagram FIXME: irmin dot is not working properly for the HTTP backend (#135)

You can also access the daemon state by opening your browser to http://127.0.0.1:8080 directly which is a classical JSON CRUD interface. It will list the possible operations. For instance, you can read the store contents directy:

$ curl http://127.0.0.1:8080/read/a/b
{"result":"foo"}

Now you can switch back to the first terminal (where you started the Irmin daemon). You will see a lot of activity has been going on in there as it was busy dealing with the requests you just made. If you kill the daemon and restart it again, you will notice that all the state is lost. This is expected, as you run the daemon using -m (i.e. backing the database store in memory). If you want to persist data across daemon reboots, read the next section.

The Git Backend

The really cool thing about Irmin is that it speaks Git fluently. This means that you can remove -s mem (or replacing it by -s git, which is the default store type) and do exactly the same thing as in the previous section. Then you will be able to use the usual git command-line tool to inspect, modify and add new elements to the store.

For instance, let's start a new Irmin instance.

$ mkdir /tmp/irmin-git && cd /tmp/irmin-git
$ irmin init -d -v
2015-02-05 11:48:43.705 unix         INFO : Writing /private/tmp/foo/.git/HEAD)
2015-02-05 11:48:43.706              INFO : daemon: http://localhost:8080
Server started on port 8080.

You can then add some data in a new terminal:

$ cat .irminconfig
store=http
uri=http://127.0.0.1:8080
$ irmin write a/b foo
$ irmin write a/c bar

It's now really easy to inspect the history using the usual Git worklow:

$ cd /tmp/irmin-git
$ git log
commit 199669c2d8df15fbae0a3d3f5307b024d893f0d6
Author: Irmin piana-3.local.[62057] <[email protected]>
Date:   Thu Feb 5 11:48:43 2015 +0000

    Initialising the HTTP server.

commit 9421b95e8b28b075a739e29474fd1639e2da45e9
Author: Irmin piana-3.local.[62057] <[email protected]>
Date:   Thu Feb 5 11:48:43 2015 +0000

    Initialising the HTTP server.

$ git show 1996
commit 199669c2d8df15fbae0a3d3f5307b024d893f0d6
Author: Irmin piana-3.local.[62057] <[email protected]>
Date:   Thu Feb 5 11:48:43 2015 +0000

    Initialising the HTTP server.

diff --git a/a/c b/a/c
new file mode 100644
index 0000000..ba0e162
--- /dev/null
+++ b/a/c
@@ -0,0 +1 @@
+bar
\ No newline at end of file

FIXME: improve the commit messages (#136) That translation is bidirectional. That means that any change you make in the repository will be reflected in the Irmin world.

$ tree
.
├── a
    ├── b
    └── c

1 directory, 2 files
$ echo "Hello world" >> a/b
$ git commit -a -m "Test"
[master ed406fe] Test
 1 file changed, 1 insertion(+), 1 deletion(-)
$ irmin tree
/a/b..............................................................................."fooHello world\n"
/a/c............................................................................................"bar"
$ git rev-parse HEAD
ed406fe7854317f511b746439f6f25adb89d3dd8
$ irmin snapshot
ed406fe7854317f511b746439f6f25adb89d3dd8

This enables an application to pull/push the state of its database.

TODO: more next