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

Parser for git's on-disk index format (`.git/index`).

> #### Experimental {: .warning}
>
> The index module is **read-only** and exists for forensic
> inspection / staging-area debugging — not for writing back
> staged changes. The API, error shapes, and bounds are subject
> to change in any 0.x release. If you're building on this, pin
> a specific version and monitor the CHANGELOG.
>
> Exgit does not currently support committing FROM a populated
> index; callers that want a commit workflow build trees
> directly via `Exgit.Object.Tree.new/1` and commit via
> `Exgit.Object.Commit.new/1`.

Supports index versions **2 and 3**. Version 4 (name-prefix compression)
is explicitly rejected rather than silently misparsed — see
[gitformat-index(5)](https://git-scm.com/docs/gitformat-index).

All parse errors are returned as `{:error, _}`; malformed inputs never
raise.

## Bounds

  * `:max_entries` — maximum number of entries the parser will
    attempt to decode. A hostile index with `count = 2^32-1`
    would otherwise trigger billions of iterations. Default
    1,000,000 — comfortably above any real monorepo
    (linux/linux is ~75k).
  * `:max_bytes` — maximum input size. Default 512 MiB. Paired
    with `:max_entries` as defense-in-depth.
  * `:verify_checksum` — when `true` (default), verify the
    trailing SHA-1 checksum and reject corrupt indexes. Disable
    only for forensic analysis of known-corrupt files.

# `t`

```elixir
@type t() :: %Exgit.Index{entries: [Exgit.Index.Entry.t()], version: 2 | 3}
```

# `entries`

```elixir
@spec entries(t()) :: [Exgit.Index.Entry.t()]
```

Return the list of entries in a parsed index.

# `parse`

```elixir
@spec parse(
  binary(),
  keyword()
) :: {:ok, t()} | {:error, term()}
```

Parse index bytes. See moduledoc for the option set and bounds.

# `read`

```elixir
@spec read(
  Path.t(),
  keyword()
) :: {:ok, t()} | {:error, term()}
```

Read and parse `<path>/.git/index` (or any index file path).

See the moduledoc for options and caveats.

---

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