• Purge files from repository history

Reduce repository size

The size of a Git repository can significantly impact performance and storage costs. It can differ slightly from one instance to another due to compression, housekeeping, and other factors.

This page explains how to remove large files from your Git repository.

For more information about repository size, see:

• Repository size
  • How repository size is calculated
  • Size and storage limits
  • GitLab UI methods to reduce repository size

Purge files from repository history

Use this method to remove large files from the entire Git history.

It is not suitable for removing sensitive data like passwords or keys from your repository. Information about commits, including file content, is cached in the database, and remain visible even after they have been removed from the repository. To remove sensitive data, use the method described in Remove blobs.

Prerequisites:

• You must install git filter-repo.
• Optional. Install git-sizer.

To purge files from a GitLab repository:

1. Export the project that contains a copy of your repository, and download it.

   • For large projects, you can use the Project relations export API.

2. Decompress and extract the backup:

   tar xzf project-backup.tar.gz
   

3. Clone the repository using --bare and --mirror options:

   git clone --bare --mirror /path/to/project.bundle
   

4. Go to the project.git directory:

   cd project.git
   

5. Update the remote URL:

   git remote set-url origin https://gitlab.example.com/<namespace>/<project_name>.git
   

6. Analyze the repository using git filter-repo or git-sizer:

   • git filter-repo:

      git filter-repo --analyze
      head filter-repo/analysis/*-{all,deleted}-sizes.txt
     

   • git-sizer:

      git-sizer
     

7. Purge the history of your repository using one of the following git filter-repo options:

   • --path and --invert-paths to purge specific files:

     git filter-repo --path path/to/file.ext --invert-paths
     

   • --strip-blobs-bigger-than to purge all files larger than for example 10M:

     git filter-repo --strip-blobs-bigger-than 10M
     

   For more examples, see the git filter-repo documentation.

8. Back up the commit-map:

   cp filter-repo/commit-map ./_filter_repo_commit_map_$(date +%s)
   

9. Unset the mirror flag:

    git config --unset remote.origin.mirror
   

10. Force push the changes:

    git push origin --force 'refs/heads/*'
    git push origin --force 'refs/tags/*'
    git push origin --force 'refs/replace/*'
    

    For more information about references, see Git references used by Gitaly.

    This step fails for protected branches and protected tags. To proceed, temporarily remove protections.
11. Wait at least 30 minutes before the next step.
12. Run the clean up repository process. This process only cleans up objects that are more than 30 minutes old. For more information, see space not being freed after cleanup.