Complete Guide to Migrating a Git Repository from Bitbucket to GitHub: Preserving All Branches and Full History

Introduction

In software development, migrating code repositories is a common task, such as moving from Bitbucket to GitHub. This migration involves not just transferring code but also preserving the complete version history, all branches, and tags. Based on Git's underlying mechanisms, this article presents a reliable method to achieve this, ensuring a seamless and lossless data transfer.

Git Mirror Cloning and Pushing Mechanism

Git provides the git clone --mirror command to create a full mirror of a repository. Unlike a regular clone, a mirror clone copies all references, including branches, tags, and remote-tracking branches, resulting in a bare repository that lacks a working directory and stores only Git objects and references, ideal for backup or migration. Here is an example command:

git clone --mirror https://bitbucket.org/exampleuser/repository-to-mirror.git

After executing this command, a directory named repository-to-mirror.git is created, containing all data from the original repository. Next, the cloned repository needs to be pushed to a new remote, such as GitHub. Use the git remote set-url --push origin command to update the push URL:

cd repository-to-mirror.git
git remote set-url --push origin https://github.com/exampleuser/mirrored

Then, push all references to the new repository with git push --mirror:

git push --mirror

This command pushes all branches, tags, and commit history, ensuring the new repository is identical to the original. Technically, the --mirror option maps local references to remote ones, avoiding the tedious manual handling of each branch.

GitHub Import Tool as an Alternative

In addition to the command-line method, GitHub offers an online import tool to simplify migration. Users can directly visit GitHub Importer, enter the Bitbucket repository URL, and let the system handle the import. This approach is suitable for users unfamiliar with Git commands or for smaller repositories. However, note that the import tool may fail with unclear error messages for repositories containing large files. In such cases, using the command-line method or contacting GitHub support is recommended.

Considerations During Migration

Several key points should be considered during migration. First, ensure proper access permissions for both the source (Bitbucket) and target (GitHub) repositories, such as using HTTPS or SSH protocols. Second, if the repository includes submodules or large binary files, additional steps might be needed. For example, for large files, Git LFS (Large File Storage) can be used for optimization. After migration, verify the integrity of the new repository by comparing commit hashes or running tests.

Code Examples and In-Depth Analysis

To illustrate the migration process more clearly, here is a complete script example incorporating the above commands:

# Clone a mirror of the Bitbucket repository
git clone --mirror https://bitbucket.org/exampleuser/old-repo.git
# Enter the cloned repository directory
cd old-repo.git
# Update the push URL to GitHub
git remote set-url --push origin https://github.com/exampleuser/new-repo.git
# Push all references to GitHub
git push --mirror

This script automates the migration process, reducing human error. From Git's internal mechanism, the --mirror option works by copying all files in the refs/ directory to ensure every reference is preserved. During the push, Git uploads these references to the remote server and reconstructs the repository structure on the server side.

Conclusion

Migrating a Git repository from Bitbucket to GitHub involves multiple steps, but using git clone --mirror and git push --mirror commands enables efficient and complete data transfer. This article explains the workings of these commands in detail and provides practical guidance. Additionally, GitHub's import tool serves as a complementary solution, offering flexibility for different scenarios. Regardless of the method chosen, the key is to ensure data integrity and consistency to support ongoing software development workflows.