git-sizer: measuring the Git repository you actually have

What git-sizer measures and who needs the numbers

git-sizer computes size-related statistics for a local Git repository and flags the ones that might cause problems or inconvenience. The README frames the whole tool around a list of failure shapes: a repository that is too big overall, too many references, too many objects, gigantic blobs, many slightly changed versions of large text files, gigantic trees, the same file repeated at many paths in one commit, absurdly long path names, and oddities such as annotated tags pointing at one another in long chains or octopus merges with dozens of parents.

The intended reader is someone who already has a repository and a suspicion. The README's own guidance gives thresholds rather than scores: repositories should ideally be under 1 GiB, and without special handling they start to get unwieldy over 5 GiB. References should be limited to a few tens of thousands at most. Directories should not exceed a couple of thousand entries. Those are the numbers git-sizer's output is meant to be read against, and the tool does not decide for you. It reports; you interpret.

That framing matters because the README is explicit that these practices are not wrong per se. Storing a large media asset, keeping a long tag chain or committing a huge XML file is a choice, and git-sizer quantifies the cost of that choice. If your statistics seem out of proportion to your project size, the README suggests adjusting how you use Git rather than reaching for a different version control system.

How git-sizer gets its numbers from a local clone

git-sizer does not read packfiles or the object database directly. The README states that it invokes git commands to examine the contents of your repository, and that the git command must therefore be in your PATH when you run git-sizer. That design decision explains most of the tool's behaviour: it is a wrapper around git's own plumbing, so it sees what git sees, including whatever the local clone contains.

The repository layout supports this. The top level holds a git/ directory alongside sizes/, counts/, meter/ and internal/, and go.mod lists github.com/github/go-pipe as a direct dependency, which is consistent with a tool that streams git subprocess output rather than parsing packfiles itself. The go.mod also pins github.com/cli/safeexec, the same helper the GitHub CLI uses to locate executables safely, and github.com/spf13/pflag for POSIX-style flags.

The practical consequence is that git-sizer is bounded by the clone in front of it. A shallow clone gives it less history to measure, which is why the README asks for a full, non-shallow clone. It also means the tool inherits git's version as a dependency: git 2.6 or newer is required, and the README states that requirement as a hard floor rather than a recommendation.

Installing git-sizer and running it on a first repository

The README gives two install paths. The recommended one is to download the ZIP for your platform from the releases page, unzip it, and move the executable (git-sizer or git-sizer.exe) into your PATH. The other is to build from source following docs/BUILDING.md. Building locally goes through the Makefile, whose default target builds bin/git-sizer with Go 1.17 or later, stamping the version from git describe.

make

That produces bin/git-sizer. The Makefile also defines cross-compilation targets, so make GOOS=windows GOARCH=amd64 builds a Windows binary from a non-Windows machine. Releases are built with make releases VERSION=1.2.3, which requires VERSION to be set on the command line.

Once the binary is on your PATH, change into a full, non-shallow clone and run it with no arguments. The README's example invocation is simply:

git-sizer

No options are required. The default output is tabular; the README's worked example adds --verbose so that all statistics are shown rather than only the flagged ones. If git-sizer is on your PATH you can also type git sizer, and because Git resolves the subcommand, you can pass Git options between the two words:

git -C /path/to/my/repo sizer

That last form is the convenient one when you want to point at a clone without cd-ing into it. What you should see is a table of metrics for the repository, with values that exceed the thresholds the README describes marked as problems. If you get an error about git not being found, the cause is the PATH requirement above, not a broken install.

Where git-sizer stops being useful

The clearest limitation is the one the README states as an instruction: you must run it in a full, non-shallow clone. There is no mode that inspects a remote repository over the network, which is why the related search phrase about checking a repository's size before cloning is not something this tool answers. If you need to know whether a clone is going to be enormous before you start it, git-sizer is the wrong instrument; you need whatever the hosting service exposes about the remote, or you clone and measure afterwards.

A second limitation is that git-sizer is a reporting tool. The README's suggestions are things you do elsewhere: move assets to Git-LFS or git-annex, delete unneeded tags and branches, stop storing compiler output, shard a directory with too many entries. Nothing in the repository layout suggests a rewrite or filter mode. If what you want is to strip large blobs out of history, git-sizer will tell you which blobs are large and then leave the work to you.

A third issue is that the interesting thresholds are advisory. The README says repositories should ideally be under 1 GiB and start to get unwieldy over 5 GiB, but a 900 MiB repository of source code and a 900 MiB repository of binaries are not the same problem, and the tool cannot tell you which one you have. Reading the flags without reading the metric categories will mislead you.

git-sizer against git count-objects and plain du

The obvious alternative is git count-objects, which is built into Git and reports the number and size of loose and packed objects. It is always available, needs no install, and answers the question "how much disk does this repository take" directly. The difference in approach is that count-objects summarizes storage, while git-sizer breaks the repository into named categories: references, objects, blobs, trees, and the pathological shapes such as one file repeated at many paths in a single commit. A repository can have a modest object count and still be miserable to check out, and count-objects will not tell you that.

du -sh .git is the cruder version of the same idea, and it is what most people reach for first. It measures bytes on disk, including packfiles, and says nothing about history traversal cost. Neither alternative flags anything: they report a number and stop. git-sizer's contribution is the flagging, which is to say the comparison of each metric against the thresholds in the README.

The trade-off is real in the other direction too. count-objects is one command with no dependency beyond git itself, and it works fine in a script that runs on every CI job. git-sizer needs a binary installed, wants a full clone, and produces a table meant for a human to read. If your question is "is this repo growing", count-objects in a cron job is the lighter answer. If your question is "why is this repo unpleasant", git-sizer is the one that names the reason.

Maintenance, licence and the cost of upgrading

The last push to the default branch was on 2026-09-10, so the repository is not archived and is being touched. The release history is a different story: v1.5.0 was published on 2021-11-16, v1.4.0 on 2021-04-23, and v1.3.0 on 2018-09-25. Anyone installing from a release ZIP is getting the v1.5.0 binary, and the gap between that release and current development is the thing to weigh. Building from source with make gets you the current tree instead, at the cost of a Go toolchain.

Upgrade cost is low for the binary itself. There is no server, no daemon and no configuration file to migrate; you replace the executable in your PATH. The Makefile's build flags are the only moving part, and it stamps the version with git describe --tags --always --dirty, so a source build reports a meaningful version string.

The licence is MIT, per the repository's LICENSE.md. That is permissive: it allows use, modification and redistribution provided the copyright notice and permission notice are retained. The Makefile comments note that release ZIPs do not include vendored code, so no third-party licence text is bundled with them. That is a description of what the repository does, not legal advice; if you redistribute git-sizer inside a product, read LICENSE.md and the licences of its Go dependencies yourself.

Editorial conclusion

Adopt git-sizer if you own a repository that clones slowly, packs badly or bloats working copies, and you want numbers before you decide what to rewrite. Do not adopt it if you need a size check before cloning, since it reads a full, non-shallow local clone, or if you want the tool to fix anything: it only reports. Verify first that git 2.6 or newer is on your PATH, because git-sizer shells out to git for every object it inspects.

Frequently asked questions

Official sources

1. github/git-sizer on GitHub
2. Issues
3. License: MIT
4. README
5. Releases