Reduce repository size
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
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:
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
.
Purging files is a destructive operation. Before proceeding, ensure you have a backup of the repository.
To purge files from a GitLab repository:
Export the project that contains a copy of your repository, and download it.
- For large projects, you can use the Project relations export API.
Decompress and extract the backup:
tar xzf project-backup.tar.gz
Clone the repository using
--bare
and--mirror
options:git clone --bare --mirror /path/to/project.bundle
Go to the
project.git
directory:cd project.git
Update the remote URL:
git remote set-url origin https://gitlab.example.com/<namespace>/<project_name>.git
Analyze the repository using
git filter-repo
orgit-sizer
:git filter-repo
:git filter-repo --analyze head filter-repo/analysis/*-{all,deleted}-sizes.txt
git-sizer
:git-sizer
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.Back up the
commit-map
:cp filter-repo/commit-map ./_filter_repo_commit_map_$(date +%s)
Unset the mirror flag:
git config --unset remote.origin.mirror
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.
Wait at least 30 minutes before the next step.
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.
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support