How to use commit-map and ref-map output files in Gitlab repository?

[maximetinu]

Hi folks, ✋

First of all, congrats to @newren and all the contributors for such a great tool. It's has allowed me to easily clean up a git history with some large binaries that were submitted by mistake. I have a few questions about how to use it in a Gitlab repository though, having chosen to push the new history to the same repository to keep all MRs, Issues, Wikis, etc.

I don't quite understand how to use these two produced files: the commit-map and the ref-map files. I'm running the command in a Gitlab repository as instructed by this Gitlab documentation: https://docs.gitlab.com/ee/user/project/repository/reducing_the_repo_size_using_git.html#repository-cleanup

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)?

I know some of these things may rather belong to the Gitlab forums, but I feel I can have better answers from the filter-repo community.

Thank you very much in advance! 😄