Measure Object Storage with git count-objects

Someone says your repository feels bloated and you should "just run gc", but you would like a number first. This guide gives you a read-only report of loose objects, pack files, duplicate packable objects and unrecognised files, so you can decide whether maintenance is needed without touching anything. 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 here needs sudo.

If the repository is unreadable, fix its ownership or access policy through your normal administration process. Do not paper over it with a one-off root-owned maintenance run.

1. Check the installed command

Run the version check from any directory. It is ordinary and read-only:

$ 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

You invoke it as git count-objects, although the 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 with no options:

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

• First number: the count of unpacked, or loose, object files.
• Second number: the disk space those loose objects use, in KiB in this version.
• What it leaves out: the pack files. A small loose-object number does not mean the whole object database is small.

Your numbers will differ. Treat the output as a measurement, not a hint 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 know what the loose-object count really 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

Each field measures something different:

• count and size: loose objects and their size in KiB.
• in-pack: objects stored in pack files. This installed Git version also prints packs, the number of pack files.
• size-pack: the space those packs use, in KiB.
• prune-packable: loose objects that are also present in packs. They are candidates for git prune-packed.
• garbage: 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 holds an absolute path, which may be quoted with C-style escapes if it contains non-printable characters.

4. Make sizes easier to scan

Add -H when raw KiB values are harder to read than a human-friendly 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 only changes how sizes are printed. It does not change which objects are counted and it does not clean anything up. Keep -v too, because -H on its own does not request the detailed field list.

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 in a pack, so the separate git prune-packed command could remove them.

This guide stops before that command. Pruning changes the object database and can remove objects that no ref currently reaches but that are still useful for recovery.

A large in-pack value is not a fault either. Packs are the normal compact storage format. The report helps you tell loose-object build-up from the space packs already occupy.

6. Check for alternates before comparing repositories

If the verbose report includes an alternate: line, some objects come from another object database. Record those paths before you move, archive or measure the repository as if it stood alone:

$ 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 make sure 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 holds a useful report, pick a different name first.

After any separately planned maintenance, run git count-objects -vH again and compare the fields. A successful command does not prove the change was a good idea, so check repository behaviour and your backup as well.