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.

Size calculation

The project overview page shows the size of all files in the repository, including repository files, artifacts, and LFS. This size is updated every 15 minutes.

The size of a repository is determined by computing the accumulated size of all files in the repository. This calculation is similar to executing du --summarize --bytes on your repository’s hashed storage path.

Size and storage limits

Administrators can set a repository size limit for GitLab Self-Managed. For GitLab SaaS, size limits are pre-defined.

When a project reaches its size limit, certain operations like pushing, creating merge requests, and uploading LFS objects are restricted.

Before you rewrite Git history

Before you rewrite the Git history and remove data from a repository, you must take into account the information in the following sections.

Local clones must be changed

Everyone who has a clone of the repository must either:

• Delete their local copy and clone a new copy of the repository.
• Fetch all remote changes and ensure all ongoing work is rebased on top of that.

When not done properly, users pushing local changes can revive files that were supposed to be deleted.

Running pipelines can cause cleanup to fail

When there are still pipelines running during a cleanup, they can interact with the repository and can cause the cleanup to not work properly.

Garbage collection grace period

GitLab runs Git garbage collection with a grace period of 30 minutes. This process cleans up objects that are both:

• Not reachable from any reference.
• At least 30 minutes old.

If the data you wanted to remove is reachable from any commit or is less than 30 minutes old, Git garbage collection will not remove it.

As a result, you must wait at least 30 minutes before selecting Prune unreachable objects after running housekeeping.

History cannot be rewritten on forked project

The builtin methods cannot be used on repositories that are forked. The way GitLab objects are stored across forks makes it impossible for Git to garbage collect objects that are shared between forks.

Workaround: Archive the project

If you archive before doing the cleanup, the repository will be read-only. This will ensure no one will make changes while the cleanup is in progress.

Archiving a repository will also remove the fork relation. This would allow you the clean up data. But if the data was pulled up into a fork, cleanup would need to happen there as well.

Methods to reduce repository size

The following methods are available to reduce the size of a repository:

• Purge files from history: Remove large files from the entire Git history.
• Clean up repository: Remove internal Git references and unreferenced objects.
• Remove blobs: Permanently delete blobs containing sensitive or confidential information.

Before you reduce your repository size, you should create a full backup of your repository. These methods are irreversible and can potentially affect your project’s history and data.

When you reduce your repository size with any of the available methods, you don’t need to block access to your project. You can perform these operations while your project remains accessible to users. These methods don’t have any known performance implications and don’t cause downtime. However, you should perform these actions during periods of low activity to minimize the potential impact on users.

Purge files from repository history

You can purge files with git filter-repo to remove large files from Git history. Do not use this method to remove sensitive data like passwords or keys. Instead use remove blobs or redact text.

This process:

• Modifies the entire Git history.
• Might affect open merge requests.
• Might affect existing pipelines.
• Requires re-cloning of local repositories.
• Does not affect LFS objects.
• Does not specify commit signatures.
• Is irreversible.

Clean up repository

Use this method to remove internal Git references and unreferenced objects from your repository. Do not use this method to remove sensitive data. Instead use Remove blobs.

This process:

• Runs git gc --prune=30.minutes.ago to remove unreferenced objects.
• Unlinks unused LFS objects, freeing storage space.
• Recalculates repository size on disk.
• Is irreversible.

Prerequisites:

• The list of objects to remove. Use the git filter-repo to produce a list of objects in acommit-map file.

To clean up a repository:

1. On the left sidebar, select Search or go to and find your project. If you’ve turned on the new navigation, this field is on the top bar.

2. Go to Settings > Repository.

3. Expand Repository maintenance.

4. Upload the list of objects to remove. For example, the commit-map file in the filter-repo directory.

   If your commit-map file is too large, the background cleanup process might time out and fail. As a result, the repository size isn’t reduced as expected. To address this, split the file and upload it in parts. Start with 20000 and reduce as needed. For example:

   split -l 20000 filter-repo/commit-map filter-repo/commit-map-

5. Select Start cleanup.

GitLab sends an email notification with the recalculated repository size after the cleanup completes.

Remove data from a repository

To remove sensitive or confidential data from a repository, use one of these methods:

• To remove the files completely, remove blobs.
• To keep the files, but replace confidential text with the replacement text ***REMOVED***, redact text.

Remove blobs

A Git binary large object (blob) stores file contents without metadata. Each blob has a unique SHA hash that represents a specific version of a file in the repository.

Use this method to permanently delete blobs that contain sensitive or confidential information.

This process:

• Rewrites Git history.
• Drops commit signatures.
• Might cause open merge requests to fail to merge, requiring a manual rebase.
• Might cause pipelines referencing old commit SHAs to break.
• Might affect historical tags and branches based on old commit history.
• Requires re-cloning of local repositories.
• Is irreversible.

Prerequisites:

• You must have the Owner role for the project
• A list of object IDs to remove.
• Your project must not be:
  • A fork of a public upstream project.
  • A public upstream project with downstream forks.

To remove blobs from your repository:

1. On the left sidebar, select Search or go to and find your project. If you’ve turned on the new navigation, this field is on the top bar.
2. Select Settings > Repository.
3. Expand Repository maintenance.
4. Select Remove blobs.
5. Enter a list of blob IDs to remove, each ID on its own line.
6. Select Remove blobs.
7. On the confirmation dialog, enter your project path.
8. Select Yes, remove blobs.
9. On the left sidebar, select Settings > General.
10. Expand the section labeled Advanced.
11. Select Run housekeeping. Wait at least 30 minutes for the operation to complete.
12. In the same Settings > General > Advanced section, select Prune unreachable objects. This operation takes approximately 5-10 minutes to complete.

Get a list of object IDs

To remove blobs, you need a list of objects to remove. To get these IDs, use the ls-tree command or use the Repositories API list repository tree endpoint. The following instructions use the ls-tree command.

Prerequisites:

• The repository must be cloned to your local machine.

To get a list of blobs at a given commit or branch sorted by size:

1. Open a terminal and go to your repository directory.

2. Run the following command:

   git ls-tree -r -t --long --full-name <COMMIT/BRANCH> | sort -nk 4

   Example output:

   100644 blob 8150ee86f923548d376459b29afecbe8495514e9  133508 doc/howto/img/remote-development-new-workspace-button.png
   100644 blob cde4360b3d3ee4f4c04c998d43cfaaf586f09740  214231 doc/howto/img/dependency_proxy_macos_config_new.png
   100644 blob 2ad0e839a709e73a6174e78321e87021b20be445  216452 doc/howto/img/gdk-in-gitpod.jpg
   100644 blob 115dd03fc0828a9011f012abbc58746f7c587a05  242304 doc/howto/img/gitpod-button-repository.jpg
   100644 blob c41ebb321a6a99f68ee6c353dd0ed29f52c1dc80  491158 doc/howto/img/dependency_proxy_macos_config.png

   The third column in the output is the object ID of the blob. For example: 8150ee86f923548d376459b29afecbe8495514e9.

Redact text from repository

Permanently delete sensitive or confidential information that was accidentally committed, ensuring it’s no longer accessible in your repository’s history. Replaces a list of strings with ***REMOVED***.

While redacting files in GitLab removes exposed secrets, it also:

• Rewrites Git history. Historical tags and branches based on the old commit history might not function correctly.
• Is destructive. Existing local clones are incompatible with the updated repository and must be re-cloned.
• Updates commit hashes because the redaction updates their content.
• Drops commit signatures during the rewrite process.
• Breaks features that depend on commit hashes, including:
  • Open merge requests. Open merge requests might fail to merge, and require a manual rebase.
  • Links to previous commits, which results in 404 errors.
• Might break pipelines that reference old commit SHAs and require reconfiguration.

For better repository integrity, you should instead:

• Revoke or rotate exposed secrets.
• Implement the secret detection capabilities of GitLab.

This approach:

• Proactively prevents future secret leaks.
• Maintains Git history while ensuring security compliance.

For more information, see secret push protection.

Alternatively, to completely delete specific files from a repository, see Remove blobs.

Prerequisites:

• You must have the Owner role for the project.

To redact text from your repository:

1. On the left sidebar, select Search or go to and find your project. If you’ve turned on the new navigation, this field is on the top bar.
2. Select Settings > Repository.
3. Expand Repository maintenance.
4. Select Redact text.
5. On the drawer, enter the text to redact. Regexes and glob patterns are accepted.
6. Select Redact matching strings.
7. On the confirmation dialog, enter your project path.
8. Select Yes, redact matching strings.
9. On the left sidebar, select Settings > General.
10. Expand Advanced.
11. Select Run housekeeping. Wait at least 30 minutes for the operation to complete.
12. In the same Settings > General > Advanced section, select Prune unreachable objects. This operation takes approximately 5-10 minutes to complete.

Troubleshooting

These sections have solutions for issues you might encounter.

Incorrect repository statistics shown in the GUI

If the repository size or commit number displayed in the GitLab interface differs from the exported .tar.gz or local repository:

1. Ask a GitLab administrator to force an update using the Rails console.

2. The administrator should run the following commands:

   p = Project.find_by_full_path('<namespace>/<project>')
   p.statistics.refresh!

3. To clear project statistics and trigger a recalculation:

   p.repository.expire_all_method_caches
   UpdateProjectStatisticsWorker.perform_async(p.id, ["commit_count","repository_size","storage_size","lfs_objects_size","container_registry_size"])

4. To check the total artifact storage space:

   builds_with_artifacts = p.builds.with_downloadable_artifacts.all
   
   artifact_storage = 0
   builds_with_artifacts.find_each do |build|
     artifact_storage += build.artifacts_size
   end
   
   puts "#{artifact_storage} bytes"

Space not being freed after cleanup

If you’ve completed a repository cleanup process but the storage usage remains unchanged:

• Be aware that unreachable objects remain in the repository for a two-week grace period.
• These objects are not included in exports but still occupy file system space.
• After two weeks, these objects are automatically pruned, which updates storage usage statistics.
• To expedite this process, ask an administrator to run the ‘Prune Unreachable Objects’ housekeeping task.

Blobs are not removed

When blobs are successfully removed, GitLab adds an entry in the project audit logs and sends an email notification to the person who initiated the action.

If the blob removal fails, GitLab sends an email notification to the initiator with the subject <project_name> | Project history rewrite failure. The email body contains the full error message.

Possible errors and solutions:

• validating object ID: invalid object ID:

  The object ID list contains a syntax error or an incorrect object ID. To resolve this:

  1. Regenerate the object IDs list.
  2. Re-run the blob removal steps.

• source repository checksum altered:

  This occurs when someone pushes a commit during the blob removal process. To resolve this:

  1. Temporarily block all pushes to the repository.
  2. Re-run the blob removal steps.
  3. Re-enable pushes after the process completes successfully.

Repository size limit reached

If you’ve reached the repository size limit:

• Try removing some data and making a new commit.
• If unsuccessful, consider moving some blobs to Git LFS or removing old dependency updates from history.
• If you still can’t push changes, contact your GitLab administrator to temporarily increase the limit for your project.
• As a last resort, create a new project and migrate your data.