git pack-refs

Turns hundreds of loose ref files into one. fsck-friendly.

🎯 What & why

git pack-refs collapses loose ref files (.git/refs/heads/foo, .git/refs/tags/v1, ...) into a single packed-refs file. On a repo with thousands of refs, this is the difference between snappy and molasses.

🧠 Mental model

Refs are normally one tiny file per ref. pack-refs is the same idea as packing objects: trade many syscalls for one. Git transparently reads from either location.

🛠️ Synopsis

git pack-refs [--all] [--no-prune] [--auto]

🎚️ Switches & options

Flag	What it does
`--all`	Pack all refs, not just tags. You almost always want this.
`--no-prune`	Keep loose refs after packing. Default is to delete them.
`--prune`	(Default) delete loose refs once packed. Saves the inodes.
`--auto`	(Git 2.34+) Pack only if heuristics say it's worth it. What `gc` uses.
`--no-prune`	⚠️ Doubles disk usage for refs and is rarely what you want outside of debugging.

💡 Use cases

Repo with thousands of branches/tags is slow on ls-remote or shell tab-completion.
Server-side housekeeping after a big import or fetch from many remotes.
Filesystems that hate small files (Windows, some network mounts) — packing is a huge win.
Right before tarballing a .git directory — fewer files, smaller archive.

🧪 Examples

Pack everything, prune loose copies

git pack-refs --all

What gc runs internally

git pack-refs --all --prune

Inspect the result

cat .git/packed-refs

Keep loose copies (debugging only)

git pack-refs --all --no-prune

🎓 Recommendations

Don't run this manually on a healthy repo — git gc handles it. Reach for it when you've imported a swarm of refs.
On servers, schedule git gc --auto rather than pack-refs directly; the heuristics are usually right.
After packing, .git/refs/heads/ may be nearly empty — that's fine. git show-ref still works.

🪤 Common pitfalls

A new ref written after packing is loose again. Refs created during/after pack-refs aren't magically packed.
Concurrent writers can race the pack. Git handles it with locks, but custom hooks reading .git/refs/... directly may break — always use git for-each-ref.
packed-refs is a flat text file; editing it by hand is asking for trouble. Use git update-ref / git pack-refs.

🔗 Related modules

📝 Quiz

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