As software projects mature and accumulate years of commit history, continuous integration artifacts, and accidental commits of large datasets, Git repositories can grow sluggish, consume excessive disk space, and fail during network fetches or pushes to platforms like GitHub and GitLab. In Linux, git-sizer is a specialized open-source diagnostic utility developed by GitHub engineers to calculate detailed size metrics for Git repositories and flag architectural bottlenecks before they cause repository corruption or performance degradation.
Why Standard Git Commands Fall Short for Size Audits
While checking the disk footprint of a .git directory using du -sh .git provides the overall compressed storage consumption, it provides no structural insight into why a repository is bloated. A repository might be slow due to a small number of massive 500 MB binary blobs, or conversely, because it contains millions of tiny 1 KB files, an excessively deep directory hierarchy, or hundreds of thousands of loose trees that overload Git’s internal graph traversal algorithms.
git-sizer evaluates a repository against standard Git scalability limits and assigns a danger rating (from 1 to 30 stars, ★) to any metric that deviates from optimal thresholds, inspecting:
- Total Counts: Commit count, tree count, blob count, and tag references.
- Maximum Sizes: Largest individual commit, largest tree object, and largest binary blob.
- Directory Depths: Maximum directory tree nesting depth and maximum entries per individual directory tree.
- History Structure: Maximum commit history depth, merge commit topologies, and commit message sizes.
Installing git-sizer on Linux Distributions
git-sizer is compiled as a standalone Go binary and can be installed via precompiled archives or built from source.
Method 1: Installing Precompiled Binary Releases
Download the latest official x86_64 or ARM64 Linux release from the GitHub releases repository:
# Create temporary directory and download release archive
cd /tmp
wget https://github.com/github/git-sizer/releases/download/v1.5.0/git-sizer-1.5.0-linux-amd64.zip
# Unzip and install binary into system executable path
unzip git-sizer-1.5.0-linux-amd64.zip
sudo install -m 755 git-sizer /usr/local/bin/
# Clean up
rm -f git-sizer-1.5.0-linux-amd64.zipMethod 2: Installing via Go
If Go is configured on your Linux system, install directly using the Go toolchain:
go install github.com/github/git-sizer@latestVerify that git-sizer is properly recognized in your terminal by executing:
git-sizer --versionRunning a Health and Size Audit on a Repository
To inspect a Git repository, navigate to the root directory of your project and run the git-sizer command without any arguments:
cd ~/projects/my-enterprise-repo
git-sizerInterpreting the Standard Output
If the repository is healthy and adheres to standard Git performance guidelines, git-sizer outputs a clean summary table showing counts and sizes without warning stars:
| Metric Category | Key Evaluated Item | Healthy Threshold | Potential Hazard if Exceeded |
|---|---|---|---|
| Blobs | Max blob size | < 50 MB | Triggers GitHub 100 MB hard reject; slows down network clones and delta compression |
| Trees | Max tree entries | < 2,000 files/dir | Degrades File Explorer and Finder performance; slows down path lookups |
| Hierarchy | Max tree depth | < 15 levels | Causes path-length buffer issues on Windows workstations; impacts recursion |
| History | Commit count | < 500,000 commits | Increases git log and git blame graph calculation latency |
Using Verbose Mode for Detailed Threshold Inspection
To view comprehensive statistics for every tracked metric—even those that pass without warning—pass the --verbose flag:
git-sizer --verboseTo lower the warning threshold and audit repositories before minor issues escalate, adjust the threshold scale:
# Flag any metric that exceeds 25% of the recommended maximum limit
git-sizer --threshold=warningRemediating Flagged Bottlenecks
When git-sizer highlights severe warning stars (★★★★), take targeted corrective action based on the specific metric flagged:
1. Excessive Blob Sizes (Large Binaries)
If git-sizer warns about massive blobs, migrate existing large assets to Git LFS (Large File Storage) and use git-filter-repo to rewrite past commits, excising the historic binary bloat from the repository’s packfiles.
2. Too Many Loose Objects and Unpacked History
If total object counts are high relative to commits, pack loose objects and clean dangling references:
git reflog expire --expire=now --all
git gc --prune=now --aggressive3. Massive Tree Counts from Build Artifacts
If tree entries are excessively high, inspect past commits for mistakenly tracked node_modules/, Python virtual environments, or compiled binary dependencies, and ensure they are added to .gitignore.