Exgit.Filter (exgit v0.1.0)

Partial-clone filter specs (git protocol v2 filter capability).

Filters tell the server to omit certain objects from the packfile it sends. The classic use case is {:blob, :none} ("blobless clone"), which skips all blobs — an agent that only needs to list files or traverse history doesn't pay the cost of fetching file contents it will never read.

Supported specs

:none — no filter. Default.
{:blob, :none} — server omits all blobs. Encoded as "blob:none".
{:blob, {:limit, bytes_or_string}} — server omits blobs larger than the given size. bytes_or_string is either an integer byte count (1024) or a human-readable string ("1m", "100k"). Encoded as "blob:limit=<value>".
{:tree, depth} — server omits trees deeper than depth. Encoded as "tree:<depth>". Depth 0 means commits only.
{:raw, "<spec>"} — escape hatch for specs we haven't modelled. Passed to the server verbatim.

Errors

encode/1 validates specs up front. An invalid spec returns {:error, {:invalid_filter, reason}} rather than reaching the wire.

Summary

Types

spec()

Functions

encode(other)

Validate and encode a filter spec. Returns :none for :none, otherwise {:ok, wire_string} or {:error, {:invalid_filter, _}}.

Types

spec()

@type spec() ::
  :none
  | {:blob, :none}
  | {:blob, {:limit, pos_integer() | String.t()}}
  | {:tree, non_neg_integer()}
  | {:raw, String.t()}

Functions

encode(other)

@spec encode(spec()) :: :none | {:ok, String.t()} | {:error, term()}

Validate and encode a filter spec. Returns :none for :none, otherwise {:ok, wire_string} or {:error, {:invalid_filter, _}}.