git-pack-refs

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

--all
    Pack all refs found in refs/, including those under refs/remotes/ and refs/stash/. By default, only refs/heads/, refs/tags/, and refs/notes/ are packed.

--prune
    After successfully packing loose refs, remove the original loose ref files. This is crucial for actual disk space saving and reduction of the number of files in the repository.

git-pack-refs is a Git plumbing command designed to optimize the storage of references (like branches, tags, and notes). Git stores references either as individual files (loose refs) in the .git/refs/ directory hierarchy or as entries within a single, optimized file called .git/packed-refs. This command converts loose references into this packed format. Packing references significantly improves performance for operations that involve iterating over many references, such as listing all branches or tags, by reducing the number of files Git needs to open and read. It also conserves disk space by consolidating many small files into one. While new references or updates to existing ones are initially created as loose refs, git-pack-refs can be run manually or, more commonly, is invoked automatically as part of git gc (garbage collection) to keep the repository efficient.

This command is primarily an internal Git plumbing command, usually invoked automatically by git gc. Manual execution is generally not required unless specific repository optimization or debugging is needed.
New loose refs will always be created upon ref updates (e.g., git branch, git update-ref), even if a packed ref for that name already exists. git pack-refs must be run again (with --prune) to consolidate and clean up these new loose refs.

When git-pack-refs runs, it creates or updates the .git/packed-refs file. This file stores references in a sorted list, with each line containing the SHA-1 or SHA-256 object name followed by the reference name. When Git looks up a reference, it first checks for a loose ref file (e.g., .git/refs/heads/master). If a loose ref exists, it takes precedence. If not, Git then consults the .git/packed-refs file for the reference.

The concept of packing references is fundamental to Git's scalability and efficiency, particularly for repositories with a large number of branches and tags. It was introduced early in Git's development to optimize performance and disk usage by consolidating numerous small ref files into a single, quickly readable file. It remains a core component of Git's internal maintenance routines, primarily managed via the git gc command.

git-gc(1), git-update-ref(1), git-show-ref(1)