Exgit.Transport protocol (exgit v0.1.0)

Protocol for git transports — HTTP, file, and user-defined (e.g. SSH or in-memory). Any struct that implements this protocol can be used interchangeably with Exgit.clone/2, Exgit.fetch/3, and Exgit.push/3.

Required callbacks

capabilities/1 — returns the server's advertised capability map.
ls_refs/2 — lists refs with optional prefix: filters. Returns {:ok, refs, meta} where refs is always a list of {ref_name, sha} 2-tuples and meta carries protocol-v2 side- channel data (HEAD symref target, peeled tag targets, etc.).
fetch/3 — returns {:ok, pack_bytes, summary} given wants and optional haves:/depth:.
push/4 — performs ref updates and sends the given pack.

Summary

Types

ls_refs_meta()

Side-channel metadata from an ls_refs/2 call. Keys

ref_entry()

ref_update()

t()

All the types that implement this protocol.

Functions

capabilities(transport)

fetch(transport, wants, opts)

ls_refs(transport, opts)

push(transport, updates, pack, opts)

Types

ls_refs_meta()

@type ls_refs_meta() :: %{
  optional(:head) => String.t(),
  optional(:peeled) => %{required(String.t()) => binary()}
}

Side-channel metadata from an ls_refs/2 call. Keys:

:head — the ref name that HEAD symbolically points at (e.g. "refs/heads/main"), when the server advertises it via protocol-v2 symrefs. Absent for servers that don't, or for repositories with a detached HEAD.
:peeled — %{tag_ref => peeled_target_sha}. Only populated for annotated tags when the server sends peeled:<sha> in the ls-refs response. Useful for have negotiation.

Additional keys may be added in future versions; consumers should treat the map as open.

ref_entry()

@type ref_entry() :: {ref :: String.t(), sha :: binary()}

ref_update()

@type ref_update() ::
  {ref :: String.t(), old_sha :: binary() | nil, new_sha :: binary() | nil}

t()

@type t() :: term()

All the types that implement this protocol.

Functions

capabilities(transport)

@spec capabilities(t()) :: {:ok, map()} | {:error, term()}

fetch(transport, wants, opts)

@spec fetch(t(), [binary()], keyword()) :: {:ok, binary(), map()} | {:error, term()}

ls_refs(transport, opts)

@spec ls_refs(
  t(),
  keyword()
) :: {:ok, [ref_entry()], ls_refs_meta()} | {:error, term()}

push(transport, updates, pack, opts)

@spec push(t(), [ref_update()], binary(), keyword()) ::
  {:ok, map()} | {:error, term()}