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.

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.
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 -20Reproduce the failure in a throwaway repository:
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 historyThe 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.
# 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 --tagsKey Comparison Table
| Approach | Rewrites history | Keeps the file | Collaborators must re-clone | Free-tier limits |
|---|---|---|---|---|
| Delete and commit | no | no, gone from tip only | no | fails, blob still in history |
filter-repo --invert-paths | yes | no | yes | none beyond repo size |
filter-repo --strip-blobs-bigger-than | yes | no | yes | none |
git lfs migrate import --above | yes | yes, in LFS | yes | 1 GB storage, 1 GB/month bandwidth |
| BFG Repo-Cleaner | yes | no | yes | none |
| New repository, squashed | yes | no, unless re-added | yes | none |
| Command | Removes | Leaves refs | Typical use |
|---|---|---|---|
--path file --invert-paths | one path everywhere | rewritten | a specific leaked file |
--strip-blobs-bigger-than 100M | all large blobs | rewritten | unknown offender |
--path-glob '*.parquet' | matching paths | rewritten | a file type |
--replace-text secrets.txt | string contents | rewritten | a committed key |
git rm --cached file | index only | unchanged | the 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.
git for-each-ref --format='%(refname)' | sed -n '1,40p'
git tag -l | head2. filter-repo removed the remote
The tool deletes origin after rewriting, deliberately, so an accidental git push cannot publish a half-finished rewrite.
git remote add origin git@github.com:you/demo.git
git push --force --all
git push --force --tagsIf 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.
git lfs install
git lfs migrate import --include="*.psd,*.zip,*.parquet" --everything
git lfs ls-files | head*.psd filter=lfs diff=lfs merge=lfs -text
*.parquet filter=lfs diff=lfs merge=lfs -textThe .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.
git count-objects -vH6. Preventing the next one
A pre-commit hook rejects large files before they become history, which is the only point where removal is free.
# .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; }
doneCommit 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 rmand 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-reporun on a clone with uncommitted work. The tool replaces the branch; a dirty tree loses changes.- LFS without
.gitattributescommitted first. New files are stored as full blobs and the push fails again. filter-repo --forceon a repository with an importantorigin. 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 toolsSmall utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Git guides
All Git guidesGit Tags: Lightweight vs Annotated and SemVer Release Tags
An annotated tag stores the tagger, date, and message; describe and --follow-tags only use those. How v:refname sorting and versionsort.suffix fix pre-release order.
Git Detached HEAD and Non-Fast-Forward Push Rejected
A detached HEAD records commits on no branch, and a rejected push protects commits you do not have. Recover with a branch and reflog; integrate before pushing.
Git detected dubious ownership: Docker, Compose, and CI Fixes
A bind mount keeps the host UID and the container runs as root, so Git stops before reading a single object. Trust the path Git resolves, not the one you mounted.
Git config: Aliases, rerere, and Credential Helpers
Five config scopes decide one value at a time. Aliases are user-level shorthand, rerere records conflict resolutions, and credential helpers choose where your secret lives.
More in Git
All Git guidesThe guides filed next to this one in Git, in library order.