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 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 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 the remote repository. The user can _fold_ any changes into one commit if he/she
modifications, they can use `Git_kv.Make.Local` which provide functions without wants.
`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`.
```ocaml ```ocaml
module Store = Git_kv.Make (Pclock) 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 () -> 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 = let new_files_batched t =
Git_kv.pull t >>= fun _diff -> Store.batch t @@ fun t ->
Store.Local.set t Mirage_kv.Key.(empty / "foo") "foo" >>= fun () -> 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
let push_operations t = but they are committed only at the end of the given function
Store.change_and_push t @@ fun t -> to [batch]. That's say, only one commit was made and sended to the
Store.set t Mirage_kv.Key.(empty / "bar") "bar" >>= fun () -> remote Git repository. *)
Store.remove t Mirage_kv.Key.(empty / "foo")
``` ```
[mimic]: https://dinosaure.github.io/mimic/mimic/index.html [mimic]: https://dinosaure.github.io/mimic/mimic/index.html

37
src/git_kv.mli
View file

@ -15,37 +15,20 @@
{2: Pushing and synchronisation.} {2: Pushing and synchronisation.}
The user can modify the repository (add files, remove files, etc.). They The user can modify the repository (add files, remove files, etc.). Each
can do this locally (with the {!module:Make.Local} module) and thus assume change produces a commit and after each change we try to transfer them to
a possible desynchronisation between the remote repository and what exists the remote Git repository. If you want to make multiple changes but contain
locally or they can share these changes with the remote repository (default them in a single commit and only transfer those changes once, you should
behavior). use the {!val:Make.batch} function.
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.
{2: Serialization of the Git repository.} {2: Serialization of the Git repository.}
Finally, the KV-store tries to keep the minimal set of commits required 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 between you and the remote repository. Only {i un}pushed changes are kept
changes are kept by the KV-store. However, if these changes are not pushed, by the KV-store. However, if these changes are not pushed, they will be
they will be stored into the final state produced by {!val:to_octets}. In stored into the final state produced by {!val:to_octets}. In other words,
other words, the more changes you make out of sync with the remote the more changes you make out of sync with the remote repository (without
repository (without pushing them), the bigger the state serialization will pushing them), the bigger the state serialization will be. *)
be. *)
type t type t
(** The type of the Git store. *) (** The type of the Git store. *)