robur/git-kv
4
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

Improve the documentation and the README.md

Browse source
This commit is contained in:
Romain Calascibetta 2022-10-31 16:47:52 +01:00
parent 64fc2402ab
commit ed3bfa2dc3
2 changed files with 23 additions and 42 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
README.md
View file

@ -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

37
src/git_kv.mli
View file

@ -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. *)