Remove a file (maybe larger than GitHub's limit) from the git history (so you can push to GitHub again)

You commited a file, larger than GitHub's size limit. You push and get something like:

remote: error: File fpss.tar.gz is 135.17 MB; this exceeds GitHub's file size limit of 100 MB

You realize the problem, remove the file, commit then push again. But you still get the same error.

What's going on?

The large file is not on the tip of your project (you removed it) but it is still in Git's history. Makes sense: Git allows you to go back in time and recover old files, so there must be a record of it somewhere.

How do you fix this?

The solution is kind of brute force. You can rewrite the history. It sounds dangerous because it is. Below is a code snippet that should fix the problem but do read the potential problems. And if this isn't quite what you need, try reading the comments to this post, and the documentation of filter-branch.

git filter-branch --index-filter 'git rm -r --cached --ignore-unmatch <file/dir>' HEAD

This will delete everything in the history of that file. The problem is that the file is present in the history.

This command changes the hashes of your commits which can be a real problem, especially on shared repositories. It should not be performed without understanding the consequences.

--

Thanks @Clare2D for motivating this post.

No repository file or test is named. Start by reviewing the linked Stack Overflow discussion and git-filter-branch documentation, then locate where resources are maintained. Done means the Git history-cleanup guidance is added or revised with the risks and command usage accurately reflected.