package carton

  1. Overview
  2. Docs
Implementation of PACKv2 file in OCaml

Install 

dune-project
 Dependency

git.robur.coop Readme Changelog MIT License Edit opam file Versions (8)

Authors

  1. R
    Romain Calascibetta <romain.calascibetta@gmail.com>

Maintainers

  1. R
    Romain Calascibetta <romain.calascibetta@gmail.com>

Sources

carton-1.4.0.tbz
sha256=431e7df0e1c25209e502bec2125218921ce2652390d82c4fbd973655814ac247
sha512=f0dafcb8b175605164f2b177f3e4cb22485abdfadb2c36178c81e838c76e28d3a038d63ecbe2c649bbd70c1520ea81db954b9af0bd531b11a8ec08c25a60e95a

doc/carton.bundle/Bundle/index.html

Module BundleSource

Decoder and encoder of a git-bundle file.

A bundle is a plain text header followed by a PACK stream:

bundle       = signature *capability *prerequisite *reference LF pack
signature    = "# v2 git bundle" LF / "# v3 git bundle" LF
capability   = "@" key ["=" value] LF          ; v3 only
prerequisite = "-" obj-id SP comment LF
reference    = obj-id SP refname LF

This module only deals with the header.

Sourcetype version = [
  1. | `V2
  2. | `V3
]

The type of bundle versions.

Sourcetype capability = [
  1. | `Object_format of string
    (*

    "sha1" or "sha256".

    *)
  2. | `Filter of string
    (*

    A partial-clone filter specification.

    *)
  3. | `Unknown of string * string option
    (*

    Any other key/value.

    *)
]

The type of capabilities (only for `V3 bundles).

Sourcetype t

The type of bundle headers.

Sourceval make : ?version:version -> ?ref_length:int -> ?capabilities:capability list -> ?prerequisites:(Carton.Uid.t * string option) list -> (string * Carton.Uid.t) list -> t

make ?version ?ref_length ?capabilities ?prerequisites references is the header advertising references (an association list from a full reference name such as "refs/heads/main" to the unique identifier it points to).

Sourceval version : t -> version
Sourceval capabilities : t -> capability list
Sourceval prerequisites : t -> (Carton.Uid.t * string option) list
Sourceval references : t -> (string * Carton.Uid.t) list
Sourceval ref_length : t -> int

ref_length t is the size (in bytes) of the unique identifiers used by t. It can be given as such to Carton.First_pass.of_seq.

Sourceval is_thin : t -> bool

is_thin t tells whether the PACK stream which follows t may be thin.

Sourceval pp : Format.formatter -> t -> unit

Pretty printer of t.

Decoding a bundle.

Sourcetype decoder

The type for decoders.

Sourcetype src = [
  1. | `String of string
  2. | `Manual
]

The type for input sources. With a `Manual source the client must provide input with src.

Sourcetype decode = [
  1. | `Await of decoder
  2. | `Header of t * decoder
  3. | `Pack of string * decoder
  4. | `End
  5. | `Malformed of string
]

The type for decoding results. `Header is emitted exactly once, as soon as the empty line which terminates the header has been seen. Everything which follows is emitted verbatim as `Pack chunks until the end of the input.

Sourceval decoder : ?ref_length:int -> ?max_header_size:int -> src -> decoder

decoder ?ref_length ?max_header_size src is a decoder reading a bundle from src.

ref_length forces the size (in bytes) of the unique identifiers instead of deducing it from the `Object_format capability. max_header_size (which defaults to 0x100000) bounds the number of bytes the header is allowed to take — it protects against a stream which would never send the empty line terminating the header.

Sourceval decode : decoder -> decode
Sourceval src : decoder -> Bstr.t -> int -> int -> decoder
Sourceval src_rem : decoder -> int

src_rem decoder returns how many byte(s) are not yet processed by the given decoder.

Sourceval of_seq : ?ref_length:int -> ?max_header_size:int -> string Seq.t -> [ `Header of t | `Pack of string ] Seq.t

of_seq seq analyses the bundle stream given by seq. The `Header value is yielded first, then the PACK stream chunk by chunk.

  • raises Failure

    if the bundle is malformed.

Sourceval split : ?ref_length:int -> ?max_header_size:int -> string Seq.t -> (t * string Seq.t, [> `Msg of string ]) result

split seq forces the header of the bundle stream seq and returns it along with the remaining PACK stream, which can then be given to Carton.First_pass.of_seq.

NOTE: the returned sequence is not persistent.

Encoding a bundle.

Sourceval check : t -> (unit, [> `Msg of string ]) result

check t verifies that t can be serialized.

Sourceval to_string : t -> string

to_string t is the serialization of the header t, empty line included.

Sourceval to_seq : t -> string Seq.t -> string Seq.t

to_seq t pack is the bundle stream made of the header t followed by the PACK stream pack.