git index-pack

Turns received pack into a usable indexed pack.

🎯 What & why

git index-pack builds the .idx sidecar file for a .pack so Git can random-access objects in it. Without an index, a packfile is just an opaque blob.

🧠 Mental model

fetch/clone receive a pack stream from the remote and hand it to index-pack to verify, resolve deltas, and emit pack-XXXX.idx. It is the receiving end of the wire protocol.

🛠️ Synopsis

git index-pack [-v] [-o <index>] [--keep[=<msg>]] [--threads=<n>] <pack>
git index-pack --stdin [--fix-thin] [--keep] [-o <index>] [<pack>]
git index-pack --check-self-contained-and-connected ...

🎚️ Switches & options

Flag	What it does
`-o <index>`	Write the index to <index> instead of pack-<sha>.idx alongside the pack.
`--index-version=<n>[,<offset>]`	Pick idx format version (1 or 2); v2 is the modern default.
`-v / --verify-stat`	Verbose progress / verify a pack and print stats.
`--keep[=<msg>]`	Create a .keep file so repack/gc won't merge/delete the pack.
`--fix-thin`	Append base objects so a 'thin' pack from the network becomes self-contained.
`--check-self-contained-and-connected`	Confirm pack stands alone and connects to existing history.
`--stdin`	Read the packfile from stdin (used by fetch/receive-pack).
`--threads=<n>`	Parallelize delta resolution; defaults to pack.threads.

💡 Use cases

Rebuilding a missing or corrupted .idx for an existing .pack.
Importing a pack received out-of-band (sneakernet, backup) into a repo.
Verifying pack integrity in CI before shipping a mirror.
Pinning a pack with --keep to protect it from git gc consolidation.

🧪 Examples

Index an existing pack

git index-pack -v .git/objects/pack/pack-abc123.pack

Index from stdin (like fetch does)

cat incoming.pack | git index-pack --stdin --fix-thin -o incoming.idx

Verify and stat a pack

git index-pack --verify-stat .git/objects/pack/pack-abc123.pack

Mark pack as keep

git index-pack --keep=mirror-2026-05 mirror.pack

🎓 Recommendations

Always pair --stdin with --fix-thin when ingesting from a remote; thin packs need bases.
Use --threads on big packs; delta resolution is CPU-bound and parallelizes well.
Run git verify-pack -v afterwards to spot-check the resulting .idx.

🪤 Common pitfalls

Indexing a thin pack without --fix-thin produces an index that references missing objects.
A stale .idx next to a newer .pack causes silent lookup misses; delete the .idx and re-run.
.keep files prevent repack from consolidating; forgetting to remove them bloats object storage.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.