lfs-size-track

Git LFS decides by path pattern which files it stores: git lfs track "*.psd". Large files with a common extension (.json, .bin, .bam), files without an extension, or files that appear in unexpected places end up in Git history before anyone notices. Afterwards only a history rewrite removes them.

lfs-size-track decides by size. As a pre-commit hook it checks every staged file. A file above the threshold that is not already handled by LFS gets tracked by its exact path with git lfs track --filename and is staged again as an LFS pointer, so the commit contains the pointer and the .gitattributes entry. Smaller files are not touched.

It works with the stock git-lfs client on every machine; nobody needs a patched version.

Why

git-lfs/git-lfs#282 "support tracking by file size" has been open since 2015, with 176 reactions and 135 comments (as of 2026-10-21). That makes it the most discussed open issue in the project. Typical cases from the thread:

• data files that share an extension with small test fixtures (.bam in genomics)
• CocoaPods and other vendored binaries without an extension, whose names change with dependency updates
• game assets (Unity, Unreal) that grow past a limit after they were first committed

The maintainers suggest that Git itself would be the right place for a size filter. A pull request adding --min-size has been waiting for review since June 2026, and it would need the new client on every machine. The existing hook, lfs-auto-track, runs only through npm, husky and lint-staged, and a commenter in the issue asked for a version outside the npm ecosystem.

Install

pipx install git+https://github.com/Jwrede/lfs-size-track

Python 3.10+, git and git-lfs, no other dependencies.

As a plain Git hook

cd your-repo
git lfs install
git config lfs-size-track.threshold 10MB     # optional, default 10MB
lfs-size-track install                       # writes .git/hooks/pre-commit

With the pre-commit framework

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/Jwrede/lfs-size-track
    rev: v0.1.0
    hooks:
      - id: lfs-size-track
        args: ["--threshold", "10MB"]

Usage

$ git add "data/sample [1].bam" data/small.bam
$ git commit -m "add data"
lfs-size-track: data/sample [1].bam (52.4 MB) is now tracked by Git LFS
[main 3f2a1c0] add data

Commands:

Command	What it does
lfs-size-track hook	Run in a pre-commit hook. Tracks and restages large staged files.
lfs-size-track scan	List files in HEAD above the threshold that are stored in Git, not LFS, and print the git lfs migrate command to move them.
lfs-size-track scan --history	The same for every commit, for large files that were deleted later but still bloat the repository.
lfs-size-track install [--force]	Install the hook as .git/hooks/pre-commit. It refuses to overwrite another hook without --force.

Options for hook and scan:

• --threshold 500KB, 10MB or 1GiB (decimal and binary units). The default comes from git config lfs-size-track.threshold, else 10 MB.
• --exclude "vendor/*" skips paths that match a glob. It can be given more than once.

Behaviour and limits

• Files are tracked by exact path. Renaming such a file later needs a new commit through the hook, or git lfs track by hand.
• If a large file has unstaged changes as well, the hook does not restage it, because that would add the unstaged changes to the commit. It exits with code 1 and asks you to stage the file fully.
• A file that shrinks below the threshold stays in LFS. Moving files back out of LFS is a deliberate decision and is left to you.
• Each clone needs git lfs install, as with any LFS repository.

License

MIT