Prepare large repositories for Bitbucket Cloud migration by reducing size
Platform Notice: Data Center Only - This article only applies to Atlassian apps on the Data Center platform.
Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
Learn how to prepare and reduce large Git repositories for Bitbucket Cloud migration. Explore key strategies, when to use them, and their pros and cons.
Solution
To help you migrate large repositories from Bitbucket Data Center to Bitbucket Cloud, this guide brings together best practices and recommended tools in one place. Use the steps below to prepare for a smooth migration:
Assess your current repository size and contents. For detailed instructions, see the knowledge article: Bitbucket Data Center Repository Sizing and Health Check Guide
If your server meets the conditions for a repack operation (as described in the article above) but the repack has not occurred, you can trigger it by making a reference (ref) change in Bitbucket Server. For example, create a new branch, add a tag, or make a test commit.
If the repack operation still does not start after a ref change, review your server configuration or contact support for further assistance.
Select the most effective method to reduce your repository size, based on your needs.
Follow the recommended steps to migrate your large repository efficiently to Bitbucket Cloud.
Important considerations before you begin
Guides for LFS migration and file deletion are for informational purposes only and are not covered by Atlassian Support.
Always back up your original repository before making any changes. This helps prevent data loss if the migration does not go as planned. For backup instructions, see the Data recovery and backups | Bitbucket Data Center 10.1 | Atlassian Documentation article.
Converting large files to Git LFS rewrites your repository’s history, including commit hashes. This may affect your internal workflows. Discuss these changes with your team and stakeholders before proceeding.
Perform all migration steps in a cloned copy of your repository. Do not run these steps directly on the Bitbucket Server repository directory.
Test the migration or deletion process in a test environment before applying changes to your production repository.
Below are some suggested methods, listed in recommended order of consideration.
1. Manual Git Garbage Collection (GC) / Repack
When to Choose This
Choose this option when the repository hasn’t been repacked or pruned in a long time. This can be applied to repositories with and without forks. It is helpful when the repository is large mainly because of accumulated unreachable objects, orphaned data, or old packfiles and not large historical files. This is the ideal first step before attempting more invasive cleanup.
Strengths and limitations
This approach does not rewrite history and hence is the most recommended way of reducing the repository size. This can significantly reduce size if the repo is inflated by unreachable objects. However, note that this requires a downtime, especially when performing this for multiple repositories by using an automated script. Also this will be ineffective if large files exist in the commit history and Bitbucket has recently run a repack operation.
Knowledge Articles
Bitbucket Data Center Repository Sizing and Health Check Guide
How to perform manual garbage collection on a repository in Bitbucket Server
Understanding git repack and git prune options in Bitbucket Data Center
2. Git LFS Migration
When to Choose This
This option will work when the repository contains many binary files (especially >50MB) that can be moved into Git LFS. It is good for scenarios where you need to keep history but store large files outside the main repository. Choose LFS migrate when binary files contribute heavily to repo size and history preservation is still important.
Strengths and limitations
Using LFS migration will significantly reduce the repository size by converting large files to pointers. This process rewrites commit history (hashes change). Old objects will remain until garbage collection (GC) prunes them and only if they are no longer referenced. Note that commits referenced directly or indirectly by open or historical pull requests (or other refs) remain reachable, so those objects will not be pruned by GC until those references are removed or updated.
Knowledge Articles
3. Git History Rewrite
(filter-repo, BFG Repo-Cleaner, filter-branch)
When to Choose This
This option is best when there are large or sensitive files in the git commit history or you want to remove entire directories or old artifacts from all commits. Use this when history contains files that no longer belong in the repository or when sensitive data must be removed.
Strengths and limitations
This approach can significantly reduce the size of the repository based on the size of the targeted objects. It also helps in removing unwanted or sensitive content from the repository commit history. Note that this will perform rewrites on all history (all hashes change) and the changes are more complex and riskier compared to GC or LFS. However, note that the objects which are directly or indirectly referenced by pull requests (or other refs) remain reachable and will not be pruned by GC until those references are removed or updated.
Knowledge Articles
Here’s a summary of approaches, along with some KB articles:
Identify Large Files and remove them from History. You can follow the steps in the knowledge article How To: Check your repository's size and identify large files.
Use git filter-repo or git filter-branch to rewrite history and remove large files or directories.
After rewriting history, force-push the cleaned repository.
The article How do I remove sensitive/unwanted content that was pushed to my Bitbucket Data Center instance? describes how to use git filter-branch.
Try using the BFG Repo-Cleaner http://rtyley.github.io/bfg-repo-cleaner/ which is an open-source tool that offers a simpler way of removing unwanted data from your repository's commit history when compared to using the git filter-branch command.
Both methods ultimately will end up rewriting the history of the repository.
4. Shallow Clone / Reduced-history Migration
When to Choose This
As a last resort, it is possible to achieve repository size reduction using git shallow clones. When trying to make the repository smaller, you will have to make a choice between the repository size vs history or the number of files: either some files have to "go" (to LFS which is not an option here or to be removed as shared in the above steps) or some history must be removed (shallow clone). Depending on the depth of the clone, we can decide the amount of git history that can be removed and migrate only this shallow clone to the cloud.
Strengths and limitations
This is the fastest way to shrink a very large repository. It is ideal for teams who only care about the current code as old history is lost. It is not suitable if historical commits need to be referenced later. In addition, pull requests and all other Bitbucket-specific metadata are lost.
Sample Commands
# Shallow clone, choose depth
git clone --depth=<DEPTH> <SOURCE_URL>
# Add new remote
git remote add new-origin <NEW_REPO_URL>
# Push current branch (limited history)
git push new-origin <current-branch>5. GC Tuning and Automated GC Execution
When to Choose This
You have many large number of repositories that need garbage collection and these repositories were not active enough such that the count and size of the commit objects did not meet the thresholds of the automatic garbage collection scheduled on the server.
Strengths and limitations
This approach will allow garbage collection using automation and tuning to work at a scale. Also this will not rewrite the git commit history. However, like manual repack, this operation will be ineffective if large files are embedded in history. It involves custom scripting, tuning and monitoring for the repositories involved.
Contact Support
You will need to contact our Support team to evaluate your repository configurations and to implement these changes.
6. Bitbucket cloud hosting storage plans
Bitbucket Cloud repositories are subject to storage limits based on the workspace plan:
Free plan
Total repository storage: 1 GB per workspace (across all repositories).
Standard and Premium plans
Total repository storage: Unlimited across all repositories in the workspace.
Per‑repository limit: Each individual repository is limited to 4 GB in size.
If a repository approaches the 4 GB limit, you should reduce its size before continuing to work with it. For strategies and tools to shrink large repositories in Bitbucket Cloud, see: Reduce repository size
When to Choose This
For customers under the Standard or Premium plans who have a strong business need for repositories larger than 4 GB, they can contact our Support team to discuss options. Support will review these cases individually; while we can’t guarantee that an increase will be granted, requests may be considered on a case‑by‑case basis.
How to Choose the Right Method for Very Large Repositories
Start With a Health Check. Always begin by analyzing the repository size breakdown, large paths in history, loose vs packed objects and binary files presence. This determines whether your repo is “bloated” or “inherently large.”
If the repository is eligible for a GC operation, start with a server triggered or a manual GC / Repack. Often this alone reduces size dramatically.
If the Repo Is Large Because of Binaries, go for Git LFS Migration. This preserves the commit history while moving large files out of the main Git repository store.
If the Repo Contains Unwanted Historical Data, use a History Rewrite. This will work for sensitive files and very large historical build artifacts.
If You Don’t Need Old History, you can use shallow clones. This is the fastest and lowest-risk path if historical commits have no value.
For Many Repositories, it is possible to automate the GC operation either by scripting the manual repack or tuning the GC configurations or triggering the repack conditions on the server.
Was this helpful?