Synopsis
git pack-refs [--all] [--no-prune]Description
The git pack-refs command consolidates many individual ref files (one per branch/tag in .git/refs/) into a single .git/packed-refs file. This is faster on filesystems where opening many small files is slow (older Windows, networked filesystems), and reduces filesystem load for repos with thousands of refs.
In day-to-day use, git pack-refs integrates closely with shell aliases, editor plugins, and continuous integration. Power users often add aliases that combine flags they always pass, or wrap the command in scripts that enforce team conventions. Output formatting can be customized via Git config — pretty formats, color schemes, and pager behavior are all tunable. When something goes wrong, the first diagnostic step is usually to re-run the command with GIT_TRACE=1 in the environment, which reveals the underlying plumbing calls. For unusual situations, the --help output (git pack-refs --help) opens the full manual page with details on every option, including those rarely used in casual workflows but essential for debugging or scripting at scale.
Understanding how git pack-refs interacts with the rest of Git's data model — the object database, the index, refs, and the working tree — pays dividends. Each command operates on some subset of these pieces, and knowing which it touches helps predict outcomes and recover from mistakes. Reading the official Git documentation alongside hands-on practice in a throwaway repository is the fastest way to internalize the nuances. Most production issues with Git stem from one of three causes: surprising default behavior, partial network operations, or rewriting history that was already shared. A working mental model of git pack-refs's side effects helps avoid all three.
When to Use
Most repos don't need manual pack-refs — git gc runs it as part of maintenance. Reach for it directly when scripting performance optimizations on huge ref sets.
Common Options
| Option | Description |
|---|---|
--all | Pack all refs (default packs only branches and tags). |
--no-prune | Don't remove individual ref files after packing. |
Examples
git pack-refs --all
# Pack every ref into packed-refs
ls .git/refs/heads/ | wc -l
# After packing, individual files are removed
git pack-refs
# Default: pack branches and tagsCommon Mistakes
Editing packed-refs by hand can corrupt the repository — use git update-ref. After pack-refs, scripts that look for individual files in .git/refs/heads/ fail. Use git for-each-ref for a portable lookup. git help pack-refs opens the full manual page with comprehensive coverage of every option and edge case; it remains the authoritative reference whenever the summary on this page leaves a question unanswered. For team workflows, capturing how your project uses this command in a CONTRIBUTING document avoids repeated onboarding questions and keeps everyone aligned on conventions.
Related Commands
git gc, git update-ref, git for-each-ref, git maintenance