package git

  1. Overview
  2. Docs
package git
Legend:
Library
Module
Module type
Parameter
Class
Class type

Parameters

module H : Digestif.S
module FS : sig ... end
module Inflate : sig ... end
module Deflate : sig ... end

Signature

include S with module Hash = Hash.Make(H) and module Inflate = Inflate and module Deflate = Deflate and module FS = FS
type t

The type of the git repository.

module FS = FS

The FS module used to make the implementation.

module Hash = Hash.Make(H)

The Digest module used to make the implementation.

module Inflate = Inflate

The Inflate module used to make the implementation.

module Deflate = Deflate

The Deflate module used to make the implementation.

module Value : Value.S with module Hash := Hash and module Inflate := Inflate and module Deflate := Deflate and module Blob = Blob.Make(Hash) and module Commit = Commit.Make(Hash) and module Tree = Tree.Make(Hash) and module Tag = Tag.Make(Hash) and type t = Value.Make(Hash)(Inflate)(Deflate).t

The Value module, which represents the Git object.

module Reference : Reference.IO with module Hash := Hash and module FS := FS

The Reference module, which represents the Git reference.

module HDec : Unpack.H with module Hash := Hash
module PDec : Unpack.P with module Hash := Hash and module Inflate := Inflate and module Hunk := HDec
module RPDec : Unpack.D with module Hash := Hash and module Inflate := Inflate and module Hunk := HDec and module Pack := PDec and module Mapper := FS.Mapper
module PEnc : Pack.P with module Hash := Hash and module Deflate := Deflate
module IDec : Index_pack.LAZY with module Hash := Hash
module IEnc : Index_pack.ENCODER with module Hash := Hash
module PInfo : Pack_info.S with module Hash := Hash and module Inflate := Inflate and module HDec := HDec and module PDec := PDec
module Packed_refs : Packed_refs.S with module Hash := Hash and module FS := FS
type kind = [
  1. | `Commit
  2. | `Tree
  3. | `Tag
  4. | `Blob
]

Kind of the packed Git object.

type error = [
  1. | `Delta of PEnc.Delta.error
  2. | `Pack_decoder of RPDec.error
  3. | `Pack_encoder of PEnc.error
  4. | `Pack_info of PInfo.error
  5. | `Idx_decoder of IDec.error
  6. | `Idx_encoder of IEnc.error
  7. | `Invalid_hash of Hash.t
  8. | `Invalid_reference of Reference.t
  9. | Error.Decoder.t
  10. | FS.error Error.FS.t
  11. | Inflate.error Error.Inf.t
  12. | Deflate.error Error.Def.t
  13. | Error.not_found
]

The type error.

val pp_error : error Fmt.t

Pretty-printer of error.

module Loose : LOOSE with type t = Value.t and type state = t and type error = error and module Hash := Hash and module Inflate := Inflate and module Deflate := Deflate and module FS := FS

The Loose module which represents any loose git object available in git repository.

module Pack : PACK with type t = RPDec.Object.t and type value = Value.t and type state = t and type error = error and module Hash := Hash and module FS := FS and module Inflate := Inflate and module HDec := HDec and module PDec := PDec and module RPDec := RPDec

The Pack module which represents any packed git object available in the git repository.

type buffer

The type for buffers.

val default_buffer : unit -> buffer
val buffer : ?ztmp:Cstruct.t -> ?etmp:Cstruct.t -> ?dtmp:Cstruct.t -> ?raw:Cstruct.t -> ?window:Inflate.window -> unit -> buffer

Build a buffer to read and write a Git object.

  • window is a buffer used by the Inflate module
  • ztmp is a buffer used to store the inflated flow
  • dtmp is a buffer used by the decoder to save the inflated flow (and keep it for an alteration)
  • raw is a buffer used to store the input flow

If not specified the cstruct are created with a size of 4 MiB.

Store functions can be used in a concurrency context only if the specified buffers are not used by another process. The deserialisation functions does not allocate any buffer and uses only the specified buffers to construct the OCaml value.

val dotgit : t -> Fpath.t

dotgit state is the current ".git" path used.

val root : t -> Fpath.t

root state is the current path of the repository.

val compression : t -> int

compression state is the current level of the compression used to write a git object.

val mem : t -> Hash.t -> bool Lwt.t

mem state hash is true if one object of the current repository state satisfies the predicate digest(object) = hash.

val list : t -> Hash.t list Lwt.t

list state is the list of all git objects available in the current repository state.

val read : t -> Hash.t -> (Value.t, error) Stdlib.result Lwt.t

read state hash is the Git object with hash hash from the current repository state. It de-serializes the git object to an OCaml value. This function needs some buffers, provided t's buffer function.

This function follows the same scheme of allocation of Loose.read if the requested git object is a loose git object or Pack.read if the requested git object is a packed git object. Otherwise, return an error.

val read_exn : t -> Hash.t -> Value.t Lwt.t

read_exn state hash is an alias of read but raise an exception (instead to return a Result) if the git object requested does not exist or if we catch any other errors.

val write : t -> Value.t -> (Hash.t * int, error) Stdlib.result Lwt.t

write state v writes as a loose git object v in the file-system. It serializes and deflates the value to a new file. which respect the internal structure of a git repository.

This function does not allocate any buffer and uses only the specified buffers to store the OCaml value to the file-system. Then, the OCaml value will be available by read state digest(v). Otherwise, return an error:

  • FS.File.error when we can not create a new file in the file-system.
  • Value.E.error when we can not serialize xor deflate the requested git loose object. This kind of error should be never happen.
val size : t -> Hash.t -> (int64, error) Stdlib.result Lwt.t

size state hash is the size of the git object such that digest(object) = hash. The size is how many byte(s) are needed to store the serialized (but not inflated) git object in bytes (without the header).

As read, size can return an error.

val read_inflated : t -> Hash.t -> (kind * Cstruct.t) option Lwt.t

read_inflated state hash is the non-compressed representaton of a Git object in the git repository xsstate. However, this function does not de-serialize the git object and returns the kind of the object and the raw-data inflated. Precisely, it decodes only the header.

This function follows the same scheme of allocation of Loose.read_inflated if the requested git object is a loose git object or Pack.read if the requested git object is a packed git object. Otherwise, return an error.

val write_inflated : t -> kind:kind -> Cstruct.t -> Hash.t Lwt.t

write_inflated state kind raw writes the git object in the git repository state and associates the kind to this object. This function does not verify if the raw data is well-defined (and respects the Git format). Then, this function returns the hash produced from the kind and the inflated raw to let the user to retrieve it.

If we retrieve any error error while the I/O operations, we raise 9by Lwt.fail a Failure which describe in a string the error encountered.

val contents : t -> ((Hash.t * Value.t) list, error) Stdlib.result Lwt.t

contents state returns an associated list between the hash and its bind git object. This list contains all git objects available in the current git repository state.

val fold : t -> ('a -> ?name:Path.t -> length:int64 -> Hash.t -> Value.t -> 'a Lwt.t) -> path:Path.t -> 'a -> Hash.t -> 'a Lwt.t

fold state f ~path acc hash iters on any git objects reachable by the git object hash which located in path (for example, if you iter on a commit, path should be "." - however, if you iter on a tree, path should be the directory path represented by your tree). For each git objects, we notice the path name (derived from path) if the object is a Blob or a Tree, the length or the git object (see size), the hash and the value.

If the hash points to:

  • Value.Blob.t: f is called only one time with the OCaml value of the blob.
  • Value.Tree.t: f is called firstly with the Ocaml value of the pointed tree by the hash hash. Then, we iter (and call f for each iteration) in the list of entries of the tree. Finally, we retrieve recursively all sub-tree objects and do an ascending walk. f is never called more than one time for each hash.
  • Value.Commit.t: f is called firstly with the OCaml value of the pointed commit by the hash hash. Then, it follozs recursively all parents of the current commit, Finallym it starts a fold inside the pointed root tree git object of each commit previously retrieved. f never called more than one time for each hash.
  • Value.Tag.t: f is called firstly with the OCaml value of the pointed tag by the hash hash. Then, it follows the git object pointed by the tag.

Any retrieved error is skipped.

val iter : t -> (Hash.t -> Value.t -> unit Lwt.t) -> Hash.t -> unit Lwt.t
module Ref : sig ... end
val clear_caches : t -> unit Lwt.t

clear_caches t drops all values stored in the internal caches binded with the git repository t.

val reset : t -> (unit, error) Stdlib.result Lwt.t

reset t removes all things of the git repository t and ensures it will be empty.

val has_global_watches : bool
val has_global_checkout : bool
val v : ?dotgit:Fpath.t -> ?compression:int -> ?buffer:((buffer -> unit Lwt.t) -> unit Lwt.t) -> FS.t -> Fpath.t -> (t, error) Stdlib.result Lwt.t

create ?dotgit ?compression ?buffer fs root creates a new store represented by the path root (default is "."), where the Git objects are located in dotgit (default is root / ".git" and when Git objects are compressed by the level (default is 4). If buffer is not set, use a Lwt_pool of default_buffer of size 4. fs is the storage backend state.

OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct