# `Exgit.Filter`
[🔗](https://github.com/ivarvong/exgit/blob/v0.1.0/lib/exgit/filter.ex#L1)

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.

# `spec`

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

# `encode`

```elixir
@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, _}}`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*