GitHub Push Rejected: "File Exceeds 100 MB" (GH001) — Fix It With filter-repo or LFS

When attempting to push a repository to GitHub, a common error encountered is an error message indicating that a file's size exceeds GitHub's file size limit of 100 MB. This issue does not get resolved simply by deleting the offending file and committing a new change. The error occurs because Git retains the file from earlier commits, and GitHub rejects the entire push.

To resolve this issue, two primary approaches can be taken: using git filter-repo or moving the file to Git LFS.

Option A involves using git filter-repo to remove the problematic file entirely from the repository's history. This method is recommended when the file was committed accidentally and does not belong in the repository. It should be noted that this approach requires installing git-filter-repo, working on a fresh clone of the repository, and then forcing a push to the GitHub repository.

Using this method will rewrite every commit hash from the first affected commit onward, which may require collaborators to reset their local clones or open pull requests to break.

Option B suggests keeping the file in the repository but moving it to Git LFS instead. This approach is suitable when the file is legitimately part of the project, such as design assets or test fixtures. To implement this method, users must install Git LFS, rewrite all history to create LFS pointers for matching files, and then force-push the changes to GitHub. This method retains the file as part of the version-controlled history but incurs ongoing storage and bandwidth costs associated with LFS on GitHub.

In summary, the choice between these two options depends on the nature of the file in question and the ongoing cost considerations. Accidental commits of large dumps, build outputs, .env files, or node_modules are best addressed using git filter-repo --invert-paths, while large assets that must be versioned should utilize git lfs migrate import. Developers should also consider the implications of rewriting history and the associated cost of using LFS on GitHub.