How to use git filter-repo's output files "commit-map" and "ref-map" to clean up the repository?

Hi folks, :raised_hand:

I am using git filter-repo to clean up some large binaries that I pushed to the repository by mistake. I don’t quite understand how to use these two produced files: the commit-map and the ref-map files. I’m following this Gitlab documentation: Reduce repository size | GitLab

In the “Repository Cleanup” section, they point out to, for example, upload a commit-map file to clean-up the repository.

To clean up a repository:

Go to the project for the repository.
Navigate to Settings > Repository.
Upload a list of objects. For example, a commit-map file created by git filter-repo which is located in the filter-repo directory.

If your commit-map file is larger than about 250KB or 3000 lines, the file can be split and uploaded piece by piece:

I have some questions here:

  • What does for example mean? What other instances of these kinds of files do filter-repo produce?
  • Should I do the same with the ref-map file?
  • Spoiler: I don’t think so. I have tried, but their structure is different, so Gitlab throws an error when running the clean-up with this file.
  • However, the the filter-repo documentation suggest that they’re the same kind of file, a mapping file maybe?
  • If I run the cleanup with the produced commit-map file, as the Gitlab’s documentation instructs, it causes my Merge Requests to break, since all the MRs still point towards the old commit hash. This is very undesirable because I can no longer look at old MR and see their changes. Is it an optional step? Can I avoid running it to keep my MRs?


  • Why does the Gitlab documentation state that the max file size is 250KB or 3000 lines but their UI says something different (A max of 40MB)?

Thank you very much in advance! :grinning_face_with_smiling_eyes: