Git Count-Objects: Inspect Repository Storage Before Cleanup

A large repository does not mean its extra data is disposable. Checked-out source, dependencies, build caches, and Git history are different storage components. Git count-objects helps inspect object storage before deciding whether maintenance is appropriate.

1. Start with a read-only measurement

git count-objects -vH
git count-objects -v

The count-objects manual defines verbose reporting and human-readable sizes. Without H, size fields use KiB, which is convenient for consistent comparisons.

Object counts are not source-file or commit counts. Repeated changes to an image can leave historical data unlike the size of its current working-tree version.

2. Pack size is not project size

Separate object storage from the entire project's disk footprint. This report does not total dependencies, build output, working-tree files, logs, and every other metadata component. Inspect Git LFS and submodule storage separately where applicable.

If the project directory is large but object storage is small, measure caches and build output using operating-system tools next. Git garbage collection cannot solve a large dependency directory outside its object database.

3. Identify the storage being measured

git rev-parse --git-dir
git rev-parse --git-common-dir
git rev-parse --is-shallow-repository

Git rev-parse identifies administrative and shared directories and shallow status. In a linked worktree, do not assume .git is a directory containing all objects. Record this context to avoid double-counting shared storage.

An alternate also means local figures alone cannot establish that a checkout is self-contained. Before copying it or retiring its source, validate independence through a separate backup-and-restoration procedure.

4. Interpret findings in context

Many loose objects: record the timing and recent operations. Investigate packing behavior; the count alone does not prove corruption.

Large packs: investigate binary history or committed generated data. Removing a file from today's checkout does not remove its historical content. History rewriting requires coordination with repository users and is not routine cleanup.

Nonzero garbage: preserve diagnostics and investigate repository state. Do not manually delete selected object-database files. During a storage incident, preserve a copy and evidence before attempting repairs.

5. Maintenance is separate from measurement

The git gc manual covers packing and cleanup, including risks from expiring objects too early while another process writes. Immediate pruning is therefore not a universal remedy.

Before maintenance, verify a restorable backup, temporary disk headroom, and coordination with other writers. Shared servers need an operator and an appropriate maintenance window. Afterwards, remeasure under comparable conditions and validate real operations rather than celebrating only a smaller number.

6. A compact diagnostic record

• Repository and checkout under investigation, without credentials.
• Git version, measurement time, shallow status, and worktree context.
• Count-objects output before and after relevant operations.
• Separate working-tree, dependency, and cache measurements.
• The actual symptom: low disk space, slow fetch, or slow local commands.
• A next step and responsible owner, without automatic deletion.

No single object-count threshold fits every project. Count-objects is valuable because it narrows the investigation: measure the right component, compare equivalent contexts, and understand affected data before maintenance.