File Too Large to Push

The symptom

What you see

Terminal 
$ remote: error: GH001: Large files detected. You may want to try Git Large File Storage.
$ remote: error: File assets/demo.mp4 is 123.45 MB; this exceeds GitHub's file
$ remote: error: size limit of 100.00 MB
In VS Code
  1. The push fails with the same GH001 text in a Git error toast

This is GitHub's reply, not commands to run.

There's a slower-motion version of the same problem: you committed node_modules, and the push uploads tens of thousands of files, crawls for minutes, and sometimes fails outright.

What it means

GitHub refuses any single file over 100 MB. The catch that surprises everyone: the limit applies to your history, not just your current folder. Once a big file is committed, deleting it from the folder isn't enough — the commit still carries it, and the push still fails. You have to remove it from the commit itself.

It's in your last commit: back it out

Untrack, amend, push

Terminal 
$ git rm --cached assets/demo.mp4
$ # add the file to .gitignore, then rewrite the last commit:
$ git commit --amend --no-edit
$ git push
In VS Code
  1. Add the file to .gitignore first (see Ignore Files)
  2. The untrack step has no one-click UI — use the integrated terminal (Terminal → New Terminal)

rm --cached removes the file from Git's tracking only — it stays on your disk.

The node_modules edition

Stop tracking node_modules

Terminal 
$ git rm -r --cached node_modules
$ # add node_modules/ to .gitignore, then:
$ git commit -m "Stop tracking node_modules"
$ git push
In VS Code
  1. Same recipe: .gitignore first, then the terminal
  2. Afterwards the Source Control panel stops listing thousands of files

Anyone who clones your repo just runs npm install to recreate node_modules.

It's buried deeper in history

If the big file was committed several commits ago, amending the last commit won't reach it — every commit since still contains it. Truly scrubbing a file from history needs a history-rewriting tool like git filter-repo, which is beyond this guide. For a young repo with little history, the pragmatic fix is often simpler: start a fresh repo without the file and push that.

Genuinely need big files? Git LFS

Git LFS (Large File Storage) is the official answer for repos that really do ship videos, datasets or design files. It stores the big files outside normal Git history and keeps lightweight pointers in the repo — after installing it, git lfs track "*.psd" routes those files through LFS automatically. Worth it for design/data-heavy projects; overkill for a stray video that shouldn't have been committed.

Tip: the cheapest fix is prevention — a good .gitignore from day one keeps node_modules, builds and giant assets out before they ever reach a commit.

Up next: that wall of "LF will be replaced by CRLF" warnings on Windows — and why it's not a problem.

FAQ

Frequently Asked Questions

Why does GitHub reject files over 100 MB?
GitHub enforces a hard per-file limit of 100 MB on normal pushes (the GH001 error). Big binaries bloat every clone forever, so GitHub points you to Git LFS instead.
I deleted the big file but the push still fails — why?
The file is still inside a commit, and a push uploads history, not just the current folder. Untrack it with git rm --cached and rewrite the commit with git commit --amend — or, if it's buried deeper, the history itself needs rewriting.
Should node_modules be committed to Git?
No — it's thousands of reinstallable files. Add node_modules/ to .gitignore; anyone who clones the repo recreates it with npm install.
What is Git LFS?
Git Large File Storage stores big files outside normal Git history and keeps small pointers in the repo. After installing it, git lfs track "*.psd" routes matching files through LFS automatically. Worth it for design or data-heavy projects.