git pack-objects

The compression engine behind clone, fetch, push, gc.

🎯 What & why

The compression engine behind clone, fetch, push, and gc. Reads object SHAs on stdin and emits a delta-compressed packfile (and matching .idx) either to disk or to stdout.

🧠 Mental model

pack-objects is where Git turns a set of objects into wire bytes. Every porcelain that ships objects shells out to it; tuning its flags is how you tune clone/fetch performance and disk layout.

🛠️ Synopsis

git pack-objects [options] <base-name> < object-list
git pack-objects --stdout [options] < object-list > pack.pack
# common knobs:
#   --depth=<n> --window=<n> --max-pack-size=<n> --threads=<n>
#   --include-tag --all-progress --write-bitmap-index
#   --keep-pack=<name> --filter=<spec>

🎚️ Switches & options

Flag	What it does
`--stdout`	Emit the pack on stdout instead of writing <base-name>.pack/.idx.
`--depth=<n>`	Max delta chain length (default 50); deeper = smaller pack, slower access.
`--window=<n>`	How many candidate objects to consider for delta base (default 10).
`--max-pack-size=<n>`	Split pack into multiple files at this size (e.g. 2g).
`--threads=<n>`	Parallelism for delta search; defaults to pack.threads / cores.
`--include-tag`	Include any tag that points at an object already in the pack.
`--all-progress`	Show progress for the entire writeout, not just delta search.
`--write-bitmap-index`	Also write a .bitmap reachability index next to the pack.
`--keep-pack=<name>`	Treat <name>.pack as 'do not reuse'; force fresh deltas elsewhere.
`--filter=<spec>`	Partial-clone filter (e.g. blob:none, tree:0) to omit objects.

💡 Use cases

Generating a one-off pack to ship objects out-of-band (mirror seeding, air-gap transfer).
Tuning depth/window/threads on the server to trade CPU for smaller fetches.
Writing a reachability bitmap to accelerate future clone/fetch negotiation.
Producing partial-clone packs with --filter for shallow/blobless mirrors.

🧪 Examples

Pack everything reachable from HEAD to stdout

git rev-list --objects HEAD | git pack-objects --stdout > out.pack

Tight pack with deep deltas and a bitmap

git rev-list --all --objects | git pack-objects --depth=250 --window=250 --write-bitmap-index pack/all

Cap pack size at 2 GiB and parallelise

git rev-list --all --objects | git pack-objects --max-pack-size=2g --threads=8 pack/split

Blobless partial-clone pack

git rev-list --all --objects | git pack-objects --filter=blob:none --stdout > blobless.pack

🎓 Recommendations

On hosting servers, pair --write-bitmap-index with multi-pack-index --bitmap for fastest fetches.
Tune via config (pack.window, pack.depth, pack.threads, pack.windowMemory) instead of memorising flags.
Use --keep-pack on a known-good base pack so repacks do not destabilise existing deltas.

🪤 Common pitfalls

Very large --depth/--window values explode CPU and RAM with diminishing pack-size returns.
--filter packs are only useful to clients that understand partial clone; serving them to old clients breaks fetches.
Forgetting to also write the .idx (i.e. --stdout without index-pack on the receiver) leaves an unusable pack.

🔗 Related modules

📝 Quiz

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