git-kv/README.md

Git-kv, a simple Key-Value store synchronized with a Git repository

This library is a simple implementation of a Git repository that can be read and/or modified. It offers two ways to create such a local repository:

1. The local repository can be created in a serialized state
2. The local repository can be created from a remote repository

The first method has the advantage of not requiring an internet connection. The serialized state can be created with the mgit tool:

$ mgit https://github.com/mirage/mirage <<EOF
> save db.pack
> quit
$ ls db.pack
db.pack

The disadvantage is that the serialized state may be out of sync with the state of the remote repository. In this case, the user has access to the pull function, which allows the internet state of the local repository to be re-synchronised with the remote repository.

let contents_of_file filename =
  let ic = open_in filename in
  let ln = in_channel_length ic in
  let rs = Bytes.create ln in
  really_input ic rs 0 ln ;
  Bytes.unsafe_to_string rs

let _ =
  Git_kv.of_octets ctx 
    ~remote:"git@github.com:mirage/mirage.git"
    (contents_of_file "db.pack") >>= fun t ->
  Git_kv.pull t >>= fun diff ->
  ...

The second method initiates a connection to the remote repository in order to download its state and reproduce a synchronised internal state. The type of connections supported are described in the given ctx. We recommend the tutorial about Mimic to understand its use.

let _ =
  Git_kv.connect ctx "git@github.com:mirage/mirage.git" >>= fun t ->
  ...

The user can manipulate the repository as an RW repository. Any change to the repository requires a new commit. These changes will be sent to the remote repository. The user can fold any changes into one commit if he/she wants.

module Store = Git_kv.Make (Pclock)

let new_file t =
  Store.set t Mirage_kv.Key.(empty / "foo") "foo" >>= fun () ->
  (* XXX(dinosaure): a commit was created and sended to the
     remote repository. *)
  ...

let new_files_batched t =
  Store.batch t @@ fun t ->
  Store.set t Mirage_kv.Key.(empty / "foo" "foo") >>= fun () ->
  Store.set t Mirage_kv.Key.(empty / "bar" "bar")
(* XXX(dinosaure): multiple files are added into the local repository
   but they are committed only at the end of the given function
   to [batch]. That's say, only one commit was made and sended to the
   remote Git repository. *)