From ed3bfa2dc37cda43bb404552371b743b33800882 Mon Sep 17 00:00:00 2001 From: Romain Calascibetta Date: Mon, 31 Oct 2022 16:47:52 +0100 Subject: [PATCH] Improve the documentation and the README.md --- README.md | 28 +++++++++++++--------------- src/git_kv.mli | 37 ++++++++++--------------------------- 2 files changed, 23 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 45ae3ed..490850f 100644 --- a/README.md +++ b/README.md @@ -47,27 +47,25 @@ let _ = The user can manipulate the repository as an [RW][mirage-kv-rw] repository. Any change to the repository requires a new commit. These changes will be sent to -the remote repository by default. If the user does not want to push -modifications, they can use `Git_kv.Make.Local` which provide functions without -`push`. If the user knows that they will do many changes and they don't want to -change all of them and do a `push` only at the end, they can use -`Git_kv.Make.change_and_push`. +the remote repository. The user can _fold_ any changes into one commit if he/she +wants. ```ocaml module Store = Git_kv.Make (Pclock) -let new_file_locally_and_remotely t = +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_file_locally t = - Git_kv.pull t >>= fun _diff -> - Store.Local.set t Mirage_kv.Key.(empty / "foo") "foo" >>= fun () -> - ... - -let push_operations t = - Store.change_and_push t @@ fun t -> - Store.set t Mirage_kv.Key.(empty / "bar") "bar" >>= fun () -> - Store.remove t Mirage_kv.Key.(empty / "foo") +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. *) ``` [mimic]: https://dinosaure.github.io/mimic/mimic/index.html diff --git a/src/git_kv.mli b/src/git_kv.mli index 9fa4aac..f481c64 100644 --- a/src/git_kv.mli +++ b/src/git_kv.mli @@ -15,37 +15,20 @@ {2: Pushing and synchronisation.} - The user can modify the repository (add files, remove files, etc.). They - can do this locally (with the {!module:Make.Local} module) and thus assume - a possible desynchronisation between the remote repository and what exists - locally or they can share these changes with the remote repository (default - behavior). - - In the latter case, the notion of {i merge} and conflicts is not handled by - our implementation. This means that if the remote repository is manipulated - by another instance than yours, it can result in conflicts that will make - the above functions fail. - - The only check done by the remote Git repository when you want to submit - your change is the ability to find a path between a commit available - remotely, the commit-graph given by the transmission, and your last commit. - In that way, our [push] is most similar to a [git push --force]! - - To save I/O, the {!val:Make.change_and_push} operation allows you to do - some change into a closure and the implementation will push only at the end - of this closure. By this way, you can {!val:Make.set}, {!val:Make.rename} - or {!val:Make.remove} without a systematic [push] on these actions. Only - one will be done at the end of your closure. + The user can modify the repository (add files, remove files, etc.). Each + change produces a commit and after each change we try to transfer them to + the remote Git repository. If you want to make multiple changes but contain + them in a single commit and only transfer those changes once, you should + use the {!val:Make.batch} function. {2: Serialization of the Git repository.} Finally, the KV-store tries to keep the minimal set of commits required - between you and the remote repository. In other words, only {i un}pushed - changes are kept by the KV-store. However, if these changes are not pushed, - they will be stored into the final state produced by {!val:to_octets}. In - other words, the more changes you make out of sync with the remote - repository (without pushing them), the bigger the state serialization will - be. *) + between you and the remote repository. Only {i un}pushed changes are kept + by the KV-store. However, if these changes are not pushed, they will be + stored into the final state produced by {!val:to_octets}. In other words, + the more changes you make out of sync with the remote repository (without + pushing them), the bigger the state serialization will be. *) type t (** The type of the Git store. *)