A Universal Guide to Migrating Git Repositories with LFS Across Platforms
Have you ever faced the daunting task of migrating a Git repository complete with LFS files? Recently, I embarked on this journey from Bitbucket to GitLab and hit a few snags along the way. In this post, I'll share the motivations, challenges, and ultimately the steps that led to a successful migration. Plus, some troubleshooting advice for any developer who might walk this path in the future.
The Path Less Traveled: Why This Approach?
My journey began with the need to move a repository from Bitbucket Server to GitLab. I initially tried GitLab's import feature, which is conveniently available when creating a new repo. However, this seemingly smooth road had a couple of potholes:
GitLab's import tool failed to correctly handle Git LFS files from Bitbucket
The feature doesn't work if the GitLab repository already exists, as it's only available during the creation of a new repo.
These hurdles necessitated a different approach.
Prerequisites
Before you dive into the migration process, ensure you have:
Read access to the old repository (Bitbucket in my case)
Write access to the new repository (GitLab)
Git and Git LFS installed on your local machine
Migration Steps
Here's a distilled version of the migration process, including the handling of Git LFS files:
1. Clone the Old Repository
Start by making a bare clone of the Bitbucket repository and navigate into the repository directory:
git clone --mirror <source-repo-URL>
cd <name-of-repo>.git
Replace <source-repo-URL> with the URL of the repository you're migrating from. This command creates a bare clone—a full copy of the repo data sans a working directory.
2. Add the GitLab Repository as a Remote
Add your new GitLab repository as a remote:
git remote add new_remote <new-repo-URL>
Assign your target repository as the new remote. Replace <new-repo-URL> with your destination repository's URL.
4. Handle LFS Files
Fetch all LFS files:
git lfs fetch --all
Then, push them to their new home:
git lfs push --all new_remote
5. Push to the New Repository
git push --mirror gitlab
Troubleshooting Common Roadblocks
Protected Branches: Temporarily unprotect branches in the destination repo settings if the push is blocked.
Default Branch: Temporarily remove the default branch in the destination repo settings if the push is blocked.
Final Thoughts
This migration method is a reliable fallback when conventional tools fail, especially for complex repositories with LFS files. It's a powerful approach that transfers the entirety of your repository's history to any platform of your choice. Just remember, with great power comes great responsibility: ensure you're ready to overwrite the destination before you unleash the --mirror command.
Happy coding, and may your migrations be ever in your favour!