How To: Migrate Repositories with Submodules into Bitbucket

Summary

While using Git repositories, users might be using submodules in order to reference other projects within their repositories. Even though users can import parent repositories and the submodules as individual repositories, Bitbucket Cloud currently doesn't have a tool to link the submodule's URL in the repository history now that they have been changed to Bitbucket URLs, which could cause issues while checking out old commits.

Environment

The steps outlined in this article are applicable to repositories containing submodules being migrated to Bitbucket Cloud.

Solution

In order to achieve this, the git filter-branch command can help rewrite the repository history and make sure the Submodules are linked to previous commits.

1. Import the Parent Repository as well as the Submodule repositories to Bitbucket Cloud.

2. Clone the Bitbucket parent repository locally with the mirror flag: 

   1 $ git clone --mirror https://bitbucket.org/<workspace>/<parentRepo>.git

3. Run the following command to get the current Submodule pointer for your parent repository: 

   1 $ cat .gitmodules

   You will get an output similar to the one below. Copy the contents of the URL field and save it for later. 

   1 2 3 [submodule "reponame"] path = reponame url = <OLD_SUBMODULE_URL>

The next steps are supposed to be followed once for each Submodule the parent repository has.

1. Clone the Submodule repository once it's been imported to Bitbucket.

2. On the local clone, run the following command: 

   1 git filter-branch --tree-filter "find . -name '.gitmodules' -exec sed -i '' -e 's/<OLD_SUBMODULE_URL>/<NEW_SUBMODULE_URL>/g' {} \;"

   • The <OLD_SUBMODULE_URL> is the same one that was copied from the .gitmodules file in the parent repository. The <NEW_SUBMODULE_URL> is the Bitbucket Cloud repository URL for the submodule.

   • For both <OLD_SUBMODULE_URL> and <NEW_SUBMODULE_URL>,  the forward slashes "/" must be escaped with a backslash "\".

   • The empty single quotes ' ' after the -i flag only need to be added for macOS machines. Other operational systems don't require them. This is currently a limitation of the sed command.

3. Push back to Bitbucket: 

   1 $ git push