Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Git Push Rejected GH001: Large Files and History Rewrite

The 100 MB limit applies to every blob in the pushed history, so deleting the file does not help. Find the object, rewrite with filter-repo, or migrate to LFS.

~5 min readGit
#Git#GitHub#Git LFS#Version Control
3D illustration of a commit chain with one oversized block wedged in it, a filter tool cutting it out and an LFS pointer tag beside it

Introduction & Quick Summary

Symptom. git push is rejected with a wall of remote: lines ending in remote: error: GH001: Large files detected. You may want to try Git Large File Storage - https://git-lfs.github.com. and remote: error: File data/events.parquet is 212.44 MB; this exceeds GitHub's file size limit of 100.00 MB. Deleting the file and committing the deletion does not help: the same push fails with the same file name.

Cause. Git stores every version of every file it has ever tracked, and a push transfers all reachable objects. The 100 MB limit is applied per blob anywhere in the pushed history, not to the current working tree, so a file added three commits ago and deleted since is still in the pack. The push is rejected before the objects are stored, which is why the branch looks clean locally and the remote refuses the whole branch.

Fix. Decide whether the file belongs in Git history at all. If it is a build artifact or a data dump, rewrite history to remove it with git filter-repo --strip-blobs-bigger-than 100M and force-push; if it is a real asset that must be versioned, move it to Git LFS with git lfs migrate import --above=100MB before the push. Either way the rewrite changes every commit hash after the offending blob, so it happens once, coordinated.

Core Mechanics, Signatures & Reproducible Setup

Find the blobs before choosing a fix. The rev-list walk lists every object reachable from any ref, which is exactly what the remote checks.

bash
git rev-list --objects --all \ | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' \ | awk '$1 == "blob" && $3 > 50*1024*1024 { printf "%.1f MB %s %s\n", $3/1048576, $2, $4 }' \ | sort -rn | head -20

Reproduce the failure in a throwaway repository:

bash
git init demo && cd demo dd if=/dev/urandom of=big.bin bs=1m count=120 git add big.bin && git commit -m "add data dump" git rm big.bin && git commit -m "remove data dump" git remote add origin git@github.com:you/demo.git git push -u origin main # rejected: the blob is still in history

The second commit does not matter. The object is reachable from the first, and the pack contains it.

git filter-repo is not part of Git itself and must be installed (pip install git-filter-repo or the distro package). It refuses to run on a repository with a remote configured unless --force is given, and it is designed to run on a fresh clone, because it replaces the history in place.

bash
# fresh mirror clone, no working tree, then rewrite git clone --mirror git@github.com:you/demo.git demo.git cd demo.git git filter-repo --strip-blobs-bigger-than 100M git push --force --all git push --force --tags

Key Comparison Table

ApproachRewrites historyKeeps the fileCollaborators must re-cloneFree-tier limits
Delete and commitnono, gone from tip onlynofails, blob still in history
filter-repo --invert-pathsyesnoyesnone beyond repo size
filter-repo --strip-blobs-bigger-thanyesnoyesnone
git lfs migrate import --aboveyesyes, in LFSyes1 GB storage, 1 GB/month bandwidth
BFG Repo-Cleaneryesnoyesnone
New repository, squashedyesno, unless re-addedyesnone
CommandRemovesLeaves refsTypical use
--path file --invert-pathsone path everywhererewrittena specific leaked file
--strip-blobs-bigger-than 100Mall large blobsrewrittenunknown offender
--path-glob '*.parquet'matching pathsrewrittena file type
--replace-text secrets.txtstring contentsrewrittena committed key
git rm --cached fileindex onlyunchangedthe mistake that started this

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. The blob is in a tag or a pull-request ref

--all covers branches and tags, and a force-push of --all --tags replaces both. A blob reachable only from a pull-request ref on the server is out of your reach; GitHub keeps those refs for closed PRs, and the only fix is to let the PR expire or delete it through the API, then re-push.

bash
git for-each-ref --format='%(refname)' | sed -n '1,40p' git tag -l | head

2. filter-repo removed the remote

The tool deletes origin after rewriting, deliberately, so an accidental git push cannot publish a half-finished rewrite.

bash
git remote add origin git@github.com:you/demo.git git push --force --all git push --force --tags

If a teammate has already pulled the old history, their push will reintroduce the blob. Every clone must be re-cloned, not merged, and a git fetch && git reset --hard origin/main keeps only the old objects in that clone's reflog, which git gc --prune=now then clears.

3. Git LFS instead of deletion

When the asset must live in the repository, migrate it rather than drop it. git lfs migrate import rewrites history so every past version of the matching paths becomes an LFS pointer.

bash
git lfs install git lfs migrate import --include="*.psd,*.zip,*.parquet" --everything git lfs ls-files | head
gitattributes
*.psd filter=lfs diff=lfs merge=lfs -text *.parquet filter=lfs diff=lfs merge=lfs -text

The .gitattributes file must be committed before anyone adds a matching file, or the next commit stores a real blob instead of a pointer. Check with git lfs status after a clone: a file that should be a pointer but is a blob means the attributes arrived too late.

4. The 100 MB blob is a legitimately large fixture

A 120 MB test fixture in a repository is a design problem, not a LFS problem. Generate it in CI, download it into a cache directory, or check in a 2 MB sample and a script that derives the rest. The cheapest fix is usually removing it from the loop entirely.

5. Repository size after a rewrite

Rewriting history removes the objects from reachability but not from the local object database. Run git gc --prune=now --aggressive on every clone, then check the server-side size in the repository settings — GitHub's storage recalculates on the next GC cycle, not immediately.

bash
git count-objects -vH

6. Preventing the next one

A pre-commit hook rejects large files before they become history, which is the only point where removal is free.

bash
# .git/hooks/pre-commit max=$((100*1024*1024)) git diff --cached --name-only --diff-filter=AM | while read -r f; do size=$(git cat-file -s ":$f" 2>/dev/null || echo 0) [ "$size" -gt "$max" ] && { echo "refusing $f ($size bytes)"; exit 1; } done

Commit the same check as a pre-receive hook or a CI step for a repository with more than one contributor, since local hooks are not installed by cloning.

Common Compilation/Runtime Mistakes & Version Gotchas

  • git rm and commit to fix it. The blob stays in history and the push keeps failing.
  • git commit --amend. Only rewrites the last commit; an older blob is untouched.
  • Force-pushing a rewrite without warning the team. Everyone with a clone reintroduces the old objects on their next push.
  • filter-repo run on a clone with uncommitted work. The tool replaces the branch; a dirty tree loses changes.
  • LFS without .gitattributes committed first. New files are stored as full blobs and the push fails again.
  • filter-repo --force on a repository with an important origin. The remote is removed by design; re-add it deliberately.
  • Assuming the LFS free tier is large. 1 GB of storage and 1 GB per month of bandwidth; a 200 MB asset pushed five times exhausts it.

Related tools. Find two versions of a rewritten file that differ by a single line with the text diff, verify a data fixture's CSV and JSON forms before deciding to keep it out of history with the CSV to JSON converter, and hash candidate assets to confirm two large files are byte-identical before removing one with the hash generator.

Try matching browser tools

All tools

Small utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Git guides

More in Git

All Git guides

The guides filed next to this one in Git, in library order.