libra index-pack

Build a .idx index file for an existing .pack archive.

Synopsis

libra index-pack [OPTIONS] [<PACK_FILE>]

Description

libra index-pack reads a Git pack file and generates a corresponding pack index (.idx) file. The index file provides O(1) random access to objects within the pack by mapping object hashes to byte offsets.

Without -o, the output file name is derived by replacing the .pack extension with .idx. The default index format is version 1 (SHA-1 fan-out table plus offset/hash pairs). Version 2 (with CRC32 checksums and support for large offsets) can be requested with --index-version 2.

With --stdin, Libra reads pack bytes from standard input. This mode requires -o <PATH> because there is no input file name to derive the index path from. Libra persists the stdin pack beside the index by replacing the output path's extension with .pack, then builds the requested .idx from that saved pack.

With --keep, Libra also writes a .keep file beside the pack. Bare --keep creates an empty keep file; --keep=<MSG> writes the message followed by a newline, matching Git's keep-file convention.

Git-style --progress and --no-progress are accepted for script compatibility. They use Libra's existing global progress mode and do not add a separate index-pack progress stream.

--fix-thin is accepted for Git compatibility and is a no-op. A thin pack carries REF_DELTA objects whose base objects are not in the pack; completing it means resolving those bases from the repository and appending them. Libra's pack decoder requires self-contained packs (it has no external-delta-base resolver) and never produces thin packs, so any pack that indexes successfully already has no external bases to add — exactly the case where Git's --fix-thin also does nothing. Resolving external delta bases (true thin-pack completion) is not supported.

This is a low-level plumbing command. It is used internally by libra fetch and libra clone after receiving pack data over the wire, and can be invoked manually to rebuild missing or corrupt index files.

Options

Examples

# Build an index with default settings (version 1, auto-named)
libra index-pack objects/pack/pack-abc123.pack

# Specify a custom output path
libra index-pack pack-abc123.pack -o /tmp/pack-abc123.idx

# Read a pack stream from stdin and generate /tmp/incoming.idx
cat incoming.pack | libra index-pack --stdin -o /tmp/incoming.idx

# Force version 2 index format
libra index-pack pack-abc123.pack --index-version 2

# Keep the pack from pruning after rebuilding its index
libra index-pack --keep="manual recovery" pack-abc123.pack

# Accept Git-style progress flags used by scripts
libra index-pack --progress pack-abc123.pack
libra index-pack --no-progress pack-abc123.pack

# Accept Git's thin-pack completion flag (no-op on Libra's self-contained packs)
libra index-pack --fix-thin pack-abc123.pack

# JSON output for scripting
libra index-pack pack-abc123.pack --json

Common Commands

libra index-pack pack-123.pack
libra index-pack pack-123.pack -o pack-123.idx
libra index-pack --stdin -o pack-123.idx
libra index-pack --keep pack-123.pack
libra index-pack --progress pack-123.pack
libra index-pack --no-progress pack-123.pack
libra index-pack --fix-thin pack-123.pack
libra index-pack pack-123.pack --index-version 2
libra index-pack pack-123.pack --json

Human Output

On success, human mode prints the generated index path:

/tmp/pack-123.idx

--quiet suppresses stdout.

Structured Output (JSON examples)

{
  "ok": true,
  "command": "index-pack",
  "data": {
    "pack_file": "/tmp/pack-123.pack",
    "index_file": "/tmp/pack-123.idx",
    "index_version": 1,
    "keep_file": null
  }
}

Version 2 example:

{
  "ok": true,
  "command": "index-pack",
  "data": {
    "pack_file": "/tmp/pack-123.pack",
    "index_file": "/tmp/pack-123.idx",
    "index_version": 2,
    "keep_file": null
  }
}

Keep-file example:

{
  "ok": true,
  "command": "index-pack",
  "data": {
    "pack_file": "/tmp/pack-123.pack",
    "index_file": "/tmp/pack-123.idx",
    "index_version": 1,
    "keep_file": "/tmp/pack-123.keep"
  }
}

Stdin example:

{
  "ok": true,
  "command": "index-pack",
  "data": {
    "pack_file": "/tmp/stdin-pack.pack",
    "index_file": "/tmp/stdin-pack.idx",
    "index_version": 1,
    "keep_file": null
  }
}

Design Rationale

Why expose this low-level command?

Pack indexing is a plumbing operation that most users never invoke directly. Libra exposes it for three reasons:

1. Debuggability. When a fetch or clone fails partway through, the user may have a valid .pack file but no .idx. Exposing index-pack lets them recover without re-downloading.
2. Agent workflows. AI agents that manage pack files (e.g., for tiered cloud storage with S3/R2) need a programmatic way to generate indices. The --json output makes this scriptable.
3. Git compatibility. Tools and scripts in the Git ecosystem expect index-pack to exist. Providing it means Libra can be a drop-in replacement in CI pipelines that call plumbing commands.

Why a separate verify-pack command?

Git exposes verification through both verify-pack and some index-pack workflows. Libra keeps index generation and verification separate: index-pack writes an index, while verify-pack performs a read-only consistency check between an existing .idx and its .pack.

Why limited index versions?

Libra supports version 1 and version 2, which cover the two formats defined in the Git pack-index specification. Version 1 is compact and sufficient for packs under 2 GB (offsets are 32-bit). Version 2 adds CRC32 checksums per object and a 64-bit offset table for large packs. There is no version 3 in the Git spec, so Libra does not invent one. The default is version 1 for simplicity and because most Libra-managed packs are well under the 2 GB threshold. Version 1 also avoids the dependency on CRC32 computation, keeping the fast path lean.

Why does version 1 require SHA-1?

The version 1 index format predates Git's SHA-256 transition and hard-codes 20-byte hash slots. Libra enforces this constraint at runtime: if the repository is configured for a non-SHA-1 hash, version 1 index generation fails with a clear error. Version 2 is the path forward for alternative hash algorithms.

Parameter Comparison: Libra vs Git vs jj

Error Handling