Reduce repository size

Repositories in Bitbucket Cloud have a size limitation of 2GB. Once that limitation is reached, the repository will be placed in read-only mode which means that you can only push previous commits and no new commits.

If you have exceeded the 1GB soft limit or are just looking to reduce the size of your repository, skip to the Bitbucket repository maintenance of this document.

Remove the repository limitation

The following procedure helps you remove the push limitation from a repository; however, you should still complete the process to maintain and clean up your Git repository as outlined in this document to completely resolve the issue.

Before you begin

  • Back up your repository - One way to create a backup is to clone your repository using the --mirror flag, and zip the entire clone.

  • Communicate repository maintenance with your team or repository collaborators and followers.

  1. Pull the latest version of your repository from Bitbucket using the git pull --all command. Make sure you back up your repository.

  2. Reset the head of your repository’s history using the git reset --hard HEAD~N where ‘N' is the number of commits you want to take the head back. In the following example, the head would be set back one commit to the last commit in the repository’s history. This is the most common approach taken, as the last commit pushed is more than likely the commit that put your repository over the 2GB size limitation.

Resetting the head this way, then force pushing the change in the next step, will permanently delete all the changes in the commit(s). This is a destructive operation so back up any files you've added before proceeding.

git reset --hard HEAD~1

3. Push the change to Bitbucket using git push --force to force push the change.

git push --force

4. After you push your changes, contact Support to run a git gc on the server for you. This is git garbage collection and will rewrite the history to reflect the change in the size of your repository. For more information on git gc, check out our Git gc tutorial.

Bitbucket repository maintenance

To prevent your repository from hitting the 2GB limit again or to reduce the size of and maintain your repository, complete a maintenance cycle on your repository.

Bitbucket repository limits

To provide the best and fastest service for all our users we have the following repository size limits.

  • Soft limit 1 GB: At this point we let you know you're getting to the higher end of an effective repository size and you might want to perform maintenance to keep from hitting the hard limit.

  • Hard limit 2 GB: This is essentially a repository size stop sign we'll limit what you can do until you reduce your repository size.

Find the size of your Bitbucket repository

In Bitbucket

To check the relative size of your repository in Bitbucket, click Settings from the menu on the left side of the repository, which opens the Repository details page, then look for the Size line located under the repository’s name.

Ideally, you should keep your repository size to between 100MB and 300MB. To give you some examples: Git itself is 222MB, Mercurial itself is 64MB, and Apache is 225MB. You can check out these open source repositories here:

From the command line

You can also use the command line to find the size of your repository on your local system.

For Git, you can use the following command: git count-objects -vH.

This should return a result similar to the following:

$ git count-objects -v 
count: 0
size: 0
in-pack: 478
packs: 1
size-pack: 92
prune-packable: 0
garbage: 0

The size-pack value is the size of your repository when it is pushed to a remote server like Bitbucket. The size-pack value is in kilobytes. So, in the above example the repository is not even 1 MB.

Maintaining or cleaning up a Git repository

One of the most common and recommended ways to clean up your repository is by installing and using the BFG Repo-Cleaner. The BFG Repo-Cleaner is specifically designed for removing unwanted data, like big files or passwords from Git repositories, so it has a simple flag that will remove any large historical (not-in-your-current-commit) files: '--strip-blobs-bigger-than'.

Please note that rewriting history will change the commits IDs. As a result, pull requests that reference such commits whose ID has been changed, will lose the info related to those commits, and also any comments.

If you would like to keep the pull request history, we suggest that you push the clean version of your repo to a newly created repo, instead of the existing one.

  1. Install BFG.

  2. Navigate to your repository: cd repository_name.

  3. Change to the branch you want to remove the large file from: git checkout master.

  4. Create a commit removing the large file from the branch, if it still exists:

    git rm path/to/large_file.mpg
     git commit -m 'Remove large file'

5. Rewrite history: bfg --delete-files path/to/big_file.mpg.

Garbage collecting dead data

  1. Prune all of the reflog references from this point back (unless you’re explicitly only operating on one branch) and repack the repository by running the following command: git -c -c gc.autodetach=false -c gc.autopacklimit=1 -c gc.garbageexpire=now -c gc.reflogexpireunreachable=now gc --prune=all.

  2. Push all your changes back to the Bitbucket repository: git push --all --force && git push --tags --force.

After you push your changes, contact Support to run a git gc on the server for you. This is git garbage collection which runs housekeeping tasks on the repository to reflect the change in the size.

Other methods for cleaning up and maintaining repository size

Using git filter-branch to rewrite history

For more information and steps to help you rewrite your repository history using git filter-branch, see Git Tools - Rewriting History.

Maintain repository size by deleting files

Deleting unused files is a good way to reduce repository size. Remember deleting a file does not remove it from history but does reduce the current version of the repository. Every clone still contains the old file if you need to retrieve it. When looking at files to delete, consider the following:

  • SQL dumps

  • Large media assets

  • Compiled versions of your applications

  • Third party libraries and dependencies (jars, dlls, gem, etc.)

  • Completely unneeded large files in history

Binary files are always candidates. DVCS systems are not good candidates for storing binary files. Consider hosting these on file hosting service such as Google Drive, Dropbox, or Carbonite.

Split a repository into project repositories

You can reduce your repository size by splitting a repository by code projects. This requires that you understand how your projects references each other. For example, if you have four projects that don't reference each other in one large repository, you split these up into four smaller repositories.

For a procedure on splitting a repository, see Split a repository in two.

Last modified on May 20, 2019

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.