Exgit.Index (exgit v0.1.0)

Copy Markdown View Source

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

Experimental

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).

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.

Summary

Types

t()

Functions

entries(index)

Return the list of entries in a parsed index.

parse(data, opts \\ [])

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

read(path, opts \\ [])

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

Types

t()

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

Functions

entries(index)

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

Return the list of entries in a parsed index.

parse(data, opts \\ [])

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

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

read(path, opts \\ [])

@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.