Trying out git submodules

Organizing code into multiple git repositories remains one of the most charming organization methods available to developers. Multiple repositories work best when teams logically isolate their work together and away from others, but this system may break down when teams develop dependencies on each other's work.

Perhaps, a team writes helm charts and deploys them from one repository, but code that the helm chart deploys exists in another. Git submodules provide an oft overlooked method for mitigating cognitive load when managing dependent repositories.

When following this tutorial feel free to fork my example repository, [e-mail]:Freyert/submodule_example.git, and follow along.

Getting started with submodules is actually fairly easy:

git submodule add [e-mail]:left-pad/left-pad.git

• NOTE: left-pad is no longer maintained.

This clones the remote repository into the current directory and adds configuration to .gitmodules at the git repository’s root. Git add and git commit these changes then push to the remote repository.

Now remove the cloned version of the repository and try cloning down the repository again. Notice that the submodule resources were not cloned down from the submodule’s repository. This may not make sense, but imagine a repository with hundreds of submodules. Pulling only the submodules required saves a lot of time. Here is one way to clone a submodule:

git submodule update --init

This initializes and updates the git submodule, therefore fetching the remote code. If the work environment generally requires all submodules when cloning the repository, more recent versions of git allow this command:

git clone [e-mail]:Freyert/submodule_example.git --recurse-submodules

That should suffice for a quick taste of submodules to peak interest. Managing dependencies through submodules introduces its own complexity which is why almost every system today includes dependency management frameworks. Think NPM for nodejs or Ruby Gems for Ruby. When considering submodules weigh the cost of using submodules against the cost of introducing a dependency management system. Most of the time dependency management wins, but submodules do have some advantages that are worth learning about.

More Reading

• Stackoverflow: How to "git clone" including submodules?
• Pro Git: Chapter 7.11 Submodules
• Git Command Reference: git-submodule
  • Good resource for all git submodule commands.
• Git Reference: gitsubmodules
  • Good resource for configuring submodules.

Cover Image of the git logo is attributed to Jason Long, CC BY 3.0 https://creativecommons.org/licenses/by/3.0, via Wikimedia Commons the image was retrieved on January 2, 2021 from https://commons.wikimedia.org/wiki/File:Git-logo.svg