Grouping multiple repositories with git submodules

A while back I had to make some changes to a couple of existing microservices that were new to me. People would always refer to any of them only by the name of the bounded context that they were a part of: the Message Center. 

Not sure where to find the repositories, I searched for message center in gitlab thinking there should be a project, folder, repo, or something like that. But alas, I was unable to find anything.

After some detective work – spitting through Confluence, sigh – I did manage to find which microservices the Message Center was supposed to consist of. Sadly, the repositories were not grouped together in gitlab, but rather all over the place…

For my sanity, and especially for the sanity of those to come after me, I wanted a single repo for the Message Center that would also hold – or at least link to – the other repositories, so that upon cloning the one repo you would also get the others for free. A bit like maven supports multi-module projects.

Fortunately, git does have a tool called submodules. 

So this is what I did.
First of all, I created a new repository in gitlab called message-centre.
Next, I added each of the existing repositories as a git submodule:
git submodule add git@gitlab.com:path/to/repo.git

After this, there were several subfolders added into which the various projects had been cloned. Also, a file called .gitmodules was added. This configuration file  stores the mapping between the project’s URL and the local subdirectory it’s been pulled into.

Project structure of a repo with git submodules

So now, all projects have been finally grouped together, allowing any developer cloning the Message Center repository for the first time, to use the recursive option to clone all the repos in one go:
git clone --recursive git@gitlab.com:path/to/message-center.git

From then on, instead of regular git pull, you can issue git pull --recurse-submodules for recursively fetching the submodules.

For more details on submodules, have a look at the git-scm book.