Measure Git Object Storage Before You Repack

You will finish with a read-only report of a Git repository's loose objects, pack files, duplicate packable objects and unrecognised files. That gives you evidence for deciding whether maintenance is needed, without changing the repository. The examples use Git 2.43.0 from Ubuntu package git 1:2.43.0-1ubuntu7.3 and its matching git-man package.

Allow about ten minutes. You need Git installed and read access to the repository. No command in this guide needs sudo. Use elevated privileges only if the repository itself is unreadable, and prefer fixing its ownership or access policy through your normal administration process rather than making a one-off root-owned maintenance run.

1. Check the installed command

Run the version check from any directory. This is an ordinary, read-only command:

$ git --version
git version 2.43.0
$ dpkg-query -W -f='${Package} ${Version}\n' git git-man
git 1:2.43.0-1ubuntu7.3
git-man 1:2.43.0-1ubuntu7.3

The command is invoked as git count-objects, although its manual page is named git-count-objects(1). The installed manual documents the -v or --verbose report and the -H or --human-readable size format.

2. Read the compact report

Change to the repository whose object database you want to inspect, then run the command without options:

$ cd /path/to/repository
$ git count-objects
4570 objects, 39840 kilobytes

The first number is the count of unpacked, or loose, object files. The second is the disk space consumed by those loose objects, reported in KiB by this version. This compact form does not describe the pack files, so a small loose-object number does not mean the whole object database is small.

Your numbers will be different. Treat the output as a measurement, not a recommendation to delete files. git count-objects does not repack, prune or otherwise modify the repository.

3. Request the full object report

Use -v when you need to decide what the loose-object count means:

$ git count-objects -v
count: 4570
size: 39840
in-pack: 6840
packs: 1
size-pack: 3424
prune-packable: 0
garbage: 0
size-garbage: 0

The fields are measured in different ways:

• count and size describe loose objects and their size in KiB.
• in-pack counts objects stored in pack files. packs is also printed by this installed Git version and counts the pack files.
• size-pack is the space used by those packs, in KiB.
• prune-packable counts loose objects that are also present in packs. They are candidates for git prune-packed.
• garbage counts files in the object database that are neither valid loose objects nor valid packs. size-garbage gives their size in KiB.

An alternate: line may appear more than once when the repository uses alternate object databases. Each line contains an absolute path. The path may be quoted with C-style escapes if it contains non-printable characters.

A non-zero garbage value is a reason to investigate before deleting anything. It can represent an interrupted operation, a file with an unexpected name, or data that another Git process has not finished handling. First identify the repository and inspect its object directory during a quiet period.

4. Make sizes easier to scan

Add -H when the raw KiB values are less useful than a human-readable display:

$ git count-objects -vH
count: 4570
size: 38.91 MiB
in-pack: 6840
packs: 1
size-pack: 3.34 MiB
prune-packable: 0
garbage: 0
size-garbage: 0 bytes

-H changes the way sizes are printed. It does not change which objects are counted, and it does not make the command perform cleanup. Keep -v as well: the human-readable option changes sizes but does not request the detailed field list on its own.

Output units and rounding can vary with the values being reported. For scripts, parse the field names and do not assume every size ends in the same unit when -H is used. For a quick terminal check, the labels are more useful than comparing formatted strings.

5. Interpret packable objects carefully

prune-packable is the field most likely to be misread. It does not count all loose objects. It counts loose objects whose contents are already represented in a pack, so they can potentially be removed by the separate git prune-packed command.

This guide stops before that command. Pruning changes the object database and can remove objects that are not currently reachable from a ref but are still useful for recovery. If you later choose a maintenance operation, first confirm that important work is committed or otherwise backed up, inspect the exact command's manual page, and take a repository backup. Do not copy a cleanup command into an unattended job solely because prune-packable is non-zero.

Similarly, a large in-pack value is not a fault. Packs are the normal compact storage format. The report helps you distinguish loose-object accumulation from the space already occupied by packs.

6. Check for alternates before comparing repositories

If the verbose report includes an alternate: line, some objects are supplied by another object database. Record those paths before moving, archiving or measuring the repository as if it were self-contained:

$ git count-objects -v | sed -n '/^alternate:/p'
alternate: /srv/git/shared-objects

The sed command only filters the report for display. It does not alter Git configuration or the alternate object database. Check each reported path with your normal filesystem tools and confirm that any backup plan includes it when the repository depends on it.

7. Record a repeatable baseline

For a before-and-after comparison, save the report to a new file rather than overwriting an existing maintenance record:

$ git count-objects -vH > /tmp/git-count-objects-before.txt
$ test -s /tmp/git-count-objects-before.txt && cat /tmp/git-count-objects-before.txt
count: 4570
size: 38.91 MiB
in-pack: 6840
packs: 1
size-pack: 3.34 MiB
prune-packable: 0
garbage: 0
size-garbage: 0 bytes

The redirection creates or replaces only the named temporary file. If that file already contains a useful report, choose a different name first. After any separately planned maintenance operation, run git count-objects -vH again and compare the fields. A successful command is not proof that a maintenance change was desirable; check repository behaviour and your backup as well.