Version Control with Git, 3rd Edition

Chapter 15. Submodules

It’s common to have a lot of applications that rely on one utility library or set of libraries. In such situations, you want each of your applications to be developed, shared, branched, and merged in its own Git repository, either because that’s the logical unit of separation or perhaps because of code ownership issues.

But dividing your applications in this way creates a problem. Each application relies on a particular version of the shared library, and you need to keep track of exactly which version. If someone upgrades the library by accident to a version that hasn’t been tested, they might end up breaking your application. Furthermore, the utility library isn’t developed all by itself; usually people are tweaking it to add new features that they need in their own applications. Eventually, they want to share those new features with everybody else writing other applications; that’s what a utility library is for.

Several strategies are commonly used in an attempt to address this issue, including conducting partial checkouts, importing dependent code directly into the project, or even copying the dependent project as a subfolder in the project. But these are not elegant solutions; in fact, some people view them as “hacks.”

Git addresses this issue with submodules. A submodule is simply a project that is part of your Git repository but also exists independently in its own source control repository. Git’s mechanism for indicating a direct reference ...