Please check gitlab-tutorial

Skip to content

Repository size

DETAILS: Tier: Free, Premium, Ultimate Offering: GitLab.com, 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:

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 self-managed instances. For GitLab.com, 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.

Methods to reduce repository size

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

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.

For more information, see use Git to purge files from repository history.

Clean up repository

Use this method to remove internal Git references and unreferenced objects.

This process:

  • Removes any internal Git references to old commits.
  • Runs git gc --prune=30.minutes.ago against the repository to remove unreferenced objects.
  • Unlinks any unused LFS objects attached to your project, freeing up storage space.
  • Recalculates the size of your repository on disk.

WARNING: Removing internal Git references causes associated merge request commits, pipelines, and change details to become unavailable.

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.

  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 files

Use this method to permanently delete files containing sensitive or confidential information from your repository.

NOTE: To replace strings with ***REMOVED***, see Redact information.

Prerequisites:

To remove blobs from your repository:

  1. On the left sidebar, select Search or go to and find your project.
  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.

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 files 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.

Troubleshooting

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"])

  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.

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.

NOTE: Deleting files in a new commit doesn't reduce repository size immediately, as earlier commits and blobs still exist. To effectively reduce size, you must rewrite history using a tool like git filter-repo.