Gitility.Bundle (Gitility v0.2.0)

Copy Markdown View Source

Deterministic single-file, read-only Git repositories.

A full-repository bundle contains raw pack/index pairs plus a direct reference snapshot. PackFetch hydration bundles are ODB-only artifacts with zero reference rows; use write/2 when the reference snapshot is required. Publishing writes a complete same-directory temporary file, syncs it, and atomically renames it over the destination. Erlang exposes no portable directory-fsync operation, so the artifact is always complete-or-absent but rename durability across sudden power loss remains platform-dependent.

Opening starts one supervision tree containing an eager PackFetch object store and a pinned reference provider. Every open is pinned to one bundle generation for its lifetime: refresh is a no-op, and moving to a replacement generation requires opening the path again. The bundle itself is only ever opened read-only and no sidecar is created beside it.

Summary

Functions

info(path)

Returns format, generation, metadata, counts, and size without hydrating objects.

open(path, opts \\ [])

Starts a linked bundle supervisor and returns its repository handle.

repository(supervisor)

Returns the repository handle owned by a running bundle supervisor.

start_link(opts)

Starts the bundle's PackFetch and RefDB under one supervisor.

verify(path)

Streams every contained section and verifies its recorded sha256.

write(path, opts)

Publishes a complete local repository as one deterministic bundle file.

Functions

info(path)

@spec info(Path.t()) :: {:ok, map()} | {:error, Gitility.Error.t()}

Returns format, generation, metadata, counts, and size without hydrating objects.

open(path, opts \\ [])

@spec open(
  Path.t(),
  keyword()
) :: {:ok, Gitility.Repository.t()} | {:error, Gitility.Error.t()}

Starts a linked bundle supervisor and returns its repository handle.

repository(supervisor)

@spec repository(pid() | GenServer.name()) ::
  {:ok, Gitility.Repository.t()} | {:error, Gitility.Error.t()}

Returns the repository handle owned by a running bundle supervisor.

start_link(opts)

@spec start_link(keyword()) :: Supervisor.on_start()

Starts the bundle's PackFetch and RefDB under one supervisor.

:path is required. PackFetch destination, runtime, limits, concurrency, request timeout, hydration ceiling, and memory ceiling options are passed through with their normal defaults.

verify(path)

@spec verify(Path.t()) :: :ok | {:error, Gitility.Error.t()}

Streams every contained section and verifies its recorded sha256.

write(path, opts)

@spec write(
  Path.t(),
  keyword()
) :: {:ok, Gitility.Bundle.Receipt.t()} | {:error, Gitility.Error.t()}

Publishes a complete local repository as one deterministic bundle file.

:source must be {:repository, directory}. Optional metadata is supplied with :source_identity, :publisher, and :created_at; timestamps are never synthesized. :git_executable selects the executable used to pack loose objects and to peel SHA-256 tags while the engine cannot do so.