Skip to main content

Explanation

Welcome to the Explanation section of the vcs documentation. Here, we delve into the details of how vcs works, its design principles, and our future plans. This section is intended to provide a deeper understanding of the project for developers and contributors.

Design principles​

Vcs is designed to be backend-agnostic and concurrency-runtime independent. It's compatible with both Eio and OCaml Stdlib runtimes. We plan to explore the feasibility of supporting luv and miou runtimes as separate future work.

The concurrency runtime must be compatible with programs written in a direct style. Runtime based on monadic concurrent models such as Async and Lwt are purposely left outside of the scope of this project.

How It Works​

Vcs is an interface composed of Traits, each providing different functionalities associated with Git operations. The dynamic dispatch implementation of Vcs is powered by the provider library.

Architecture​

The vcs repository contains several components:

  • vcs: The main entry point of the library. Marked with a * to indicate no runtime dependencies.
  • user-lib: A placeholder in the diagram for any library that uses Vcs. Also marked with a * to indicate no runtime dependencies.
  • executable: A placeholder for a runtime component based on user-lib that commits to a specific provider and concurrency model.
  • vcs-git-provider: A IO-free library that parses the output of a git cli process.
  • vcs-git-eio: An instantiation of Vcs_git_provider based on an Eio runtime.
  • vcs-git-blocking: An instantiation of Vcs_git_provider based on the OCaml Stdlib.

Relation to ocaml-git​

ocaml-git is a pure OCaml implementation of the Git format and protocol. In the Vcs framework, an Eio compatible ocaml-git is a potential provider for the interface. We plan to create a Vcs provider based on ocaml-git in the future.