git-unix 2.1.0 · OCaml Package

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

type t = Value.t

The type of the loosed Git object.

type state = t

The type for the state of a Git store.

type kind = [

| `Commit
| `Tree
| `Tag
| `Blob

]

Kind of the loosed Git object.

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

The Value module, which represents the Git object.

type error = error

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

mem state hash is true iff there is an object such that digest(object) = hash. This function is the same as lookup state hash <> None.

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

list state is the list of all the available git loose objects in state. The list returned does not contain all git objects available in your repository but only which loosed one.

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

read state hash is the git loose object in state such that digest(result) = hash.

Can return an error:

FS.File.error when we can not access to the git object in the file-system (because it does not exist or the structure of the git repository is wrong).
Value.D.error when we can not de-serialize xor inflate the requested git loose object. That means, the git loose object does not respect the Git format.

val size : state -> Hash.t -> (int64, error) Stdlib.result Lwt.t

size t hash is the size of the git loose object which respects the predicate 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 write : state -> t -> (Hash.t * int, error) Stdlib.result Lwt.t

write state v writes v as a loose git object in the file-system.

This function does not allocate any buffer and uses only the specified buffers in state's buffer. Once the write is done, v becomes available by read state digest(v).

Can 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.

The current implementation does not limit the memory consumption of the deflate computation (i.e. zlib and the flush method). Depending of the object v, the process can consume a lot of memory.

val write_inflated : state -> 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 by Lwt.fail a Failure which describe in a string the error encountered.

val read_inflated : 
  state ->
  Hash.t ->
  (kind * Cstruct.t, error) Stdlib.result Lwt.t

read_inflated state hash can retrieve a git loose object from the file-system. 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 allocate only one buffer in the major-heap and uses only the specified buffers to compute the raw-data in the allocated Cstruct.t. The raw-data respects the predicate digest(header + raw-data) = hash.

Can return an error:

FS.File.error when we can not access to the git object in the file-system (because it does not exist or the structure of the git repository is wrong).
Value.D.error when we can not de-serialize xor inflate the requested git loose object. That means, the git loose object has a wrong header or it is corrupted.

val read_inflated_wa : 
  Cstruct.t ->
  state ->
  Hash.t ->
  (kind * Cstruct.t, error) Stdlib.result Lwt.t

read_inflated_wa result state h is the Git loose object with the hash h. 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 needs some buffers, provided by decoder as well as result, a buffer to store the result.

The suffix wa refers to: Without Allocation. Indeed, this function allocates only any data in the minor-heap. All other needed OCaml objects must be noticed by the client. However, the client needs to provide a well sized result (otherwise, the client can retrieve an error). He can get this information by size.

The raw-data respects the predicate digest(header + raw-data) = h.

Can return an error:

FS.File.error when we can not access to the git object in the file-system (because it does not exist or the structure of the git repository is wrong).
Value.D.error when we can not de-serialize xor inflate the requested git loose object. That means, the git loose object has a wrong header or it is corrupted.

In a server context, this function should be used to limit the allocation.

module D : sig ... end

The decoder of the Git object. We constraint the input to be an Inflate.window and a

module E : sig ... end

The encoder (which uses a Minienc.encoder) of the Git object. We constraint the output to be a

package git-unix