git multi-pack-index

MIDX. Big perf win on giant repos with many packs.

🎯 What & why

Manages the multi-pack-index (MIDX), an index across all packfiles in a repo. On giant repos with many packs it dramatically speeds up object lookup and enables cross-pack reachability bitmaps.

🧠 Mental model

Without MIDX, Git probes pack .idx files one by one to find an object. MIDX is a single index that maps every object to its owning pack and offset. git maintenance turns this on and keeps it fresh for you.

🛠️ Synopsis

git multi-pack-index [--object-dir=<dir>] [--no-progress] <subcommand>
  write [--bitmap] [--preferred-pack=<name>]
  verify
  expire
  repack [--batch-size=<bytes>]

🎚️ Switches & options

Flag	What it does
`--object-dir=<dir>`	Operate on a non-default object directory (e.g. an alternate).
`--no-progress`	Suppress progress output; useful in scripts and CI.
`--bitmap`	Write a MIDX reachability bitmap alongside the index (write subcommand).
`--preferred-pack=<name>`	Hint MIDX/bitmap generation toward a specific pack.
`--batch-size=<bytes>`	Cap how much repack consolidates per invocation.
`expire`	⚠️ Removes packfiles whose objects are fully covered by other packs.

📦 Subcommands

write — Generate or refresh the MIDX from current packs.

git multi-pack-index write --bitmap

verify — Sanity-check the MIDX file against the packs it references.

git multi-pack-index verify

expire — Drop packs that contribute no unique objects to the MIDX.

git multi-pack-index expire

repack — Coalesce small packs into larger ones, MIDX-aware.

git multi-pack-index repack --batch-size=1g

💡 Use cases

Speeding up object lookup on monorepos that accumulate hundreds of packfiles.
Server-side hosting: combining MIDX bitmaps with pack-objects for fast clone/fetch.
Maintenance pipelines that prune stale packs without a full git gc.
Diagnosing pack layout problems via verify on a bad mirror.

🧪 Examples

Write a MIDX with a reachability bitmap

git multi-pack-index write --bitmap

Verify the MIDX is consistent

git multi-pack-index verify

Coalesce small packs incrementally

git multi-pack-index repack --batch-size=2g && git multi-pack-index expire

Operate on an alternate ODB

git multi-pack-index --object-dir=/srv/git/shared/objects write

🎓 Recommendations

Prefer git maintenance run --task=incremental-repack; it manages MIDX automatically.
On hosting servers, write MIDX with --bitmap to accelerate fetch negotiation.
Run verify after relocating or rsync-ing packs into a repo.

🪤 Common pitfalls

expire deletes packfiles; never run it on a repo whose packs are referenced via alternates you do not control.
MIDX is only useful with multiple packs; on a freshly gc'd single-pack repo it is a no-op overhead.
Bitmap generation can be memory-hungry on huge repos; size your maintenance host accordingly.

🔗 Related modules

📝 Quiz

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