Recently I’ve been working with projects that use GitHub submodules. According to GitHub, submodules “allow you to include or embed one or more repositories as a sub-folder inside another repository.” Submodules help us keep code dry when functionality is shared across multiple repositories.
Imagine you are growing 5 different flowers (representing repositories). There is no reason to create a different pot for every flower. With a submodule (representing the pot), your distinct flowers are able to grow at their own pace while sharing one pot, since all flowers need common elements: water, sunlight, fertilizer, etc.
However, what happens when you want to update a major dependency in one of your applications, like Wagtail, while other repositories still require an outdated version? There are different ways to approach this, but in this piece we will create a branch in the submodule. That branch will run the updated version of the Wagtail and have the parent repository reference that same branch, while the main branch in the submodule remains unchanged. Thus, the other applications remain unnafected.
First, create a branch in the submodule. Since we will use a Wagtail upgrade as an example, let’s call the branch wagtail-4-upgrade. Make your code changes: fix imports, tests, etc. then commit and push your changes to wagtail-4-upgrade. In the parent repository find & open the .gitmodules file - the file should be located in the top-level directory.
[submodule "apps/submodule_app"]
path = apps/submodule_app
url = git@github.com:githubexampleurl.git
The .gitmodules file is used for “defining submodule properties.” To point the parent repository to a specific branch in the submodule, define a branch in the .gitmodules file, underneath the url (the branch name must be the same as the submodule branch):
[submodule "apps/submodule_app"]
path = apps/submodule_app
url = git@github.com:githubexampleurl.git
branch = wagtail-4-upgrade # new line
It’s as simple as that. The final step is pulling the changes. First, ensure that there are no local staged changes in the branch of the parent repository. Then run the following command on your terminal:
> git submodule update --remote
The parent repository is now running the changes of the wagtail-4-upgrade branch.
I hope this was useful. Happy coding.