How can I remove a large file from my commit history?

Deleting a file completely from your Git history

If you've committed a large file to your repository that takes up a large amount of disk space, simply removing it in a commit will not actually help.

This is because Git doesn't actually fully delete the file when you remove it from your working directory. It'll be stored in Git's history incase you want to restore it.

Git's filter-branch to the rescue

Let's say in a previous commit you've accidentally added a 15MB photo of your CEO called ceo.jpg. To completely remove the file from the repository, you'll need to run the following command in your project's directory:

git filter-branch --force --index-filter \
  'git rm --cached --ignore-unmatch path/to/ceo.jpg' \
  --prune-empty --tag-name-filter cat -- --all

You should see output like this if the file was successfully removed:

Rewrite ee94db7633e1bf370512d95e5ab57b851ad6c8cf (5/5)
Ref 'refs/heads/master' was rewritten

Update your .gitignore file

At this point, it's recommended that you update your .gitignore file to prevent that file from accidentally being committed again in the future.

Note: We've written a beginner's guide to .gitignore files.

Force push to your remotes

If you've pushed the large file to a remote host (like GitHub), you'll need to force push the changes to update all the rewritten commits.

Doing a force push, especially when working with other developers can be dangerous. So, if you've got experienced Git users on your team, consult with them before following this step or read up on the consequences of force pushing.

Once you're ready, run this command:

git push origin --force --all

Note: The space won't necessarily be reclaimed on the host immediately. You'll need to wait for garbage collection to be run before the size is recalculated.

Proudly powered by Katapult. Running on 100% renewable energy.