From 6bf4dc7f07d7732cf1d8b78b60d3b1645f23cfc1 Mon Sep 17 00:00:00 2001 From: Romain Calascibetta Date: Fri, 28 Oct 2022 11:56:11 +0200 Subject: [PATCH] Improve the documentation --- src/git_kv.mli | 34 +++++++++++++++++++++++++++++----- 1 file changed, 29 insertions(+), 5 deletions(-) diff --git a/src/git_kv.mli b/src/git_kv.mli index 42d62ee..13837b6 100644 --- a/src/git_kv.mli +++ b/src/git_kv.mli @@ -13,15 +13,39 @@ In the second case, the synchronisation can be done later with {!val:pull}. - The user can modify the repository (add files, remove files, etc.). He can - do this locally and thus assume a possible desynchronisation between the - remote repository and what exists locally or he can share these changes - with the remote repository with [{set,rename,remove}_and_push]. + {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 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.batch} 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.} + + 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. *) type t (** The type of the Git store. *)