Version Control with Git, 2nd Edition

Chapter 17. Submodule Best Practices

Submodules are a powerful, but sometimes perceived as complex piece of the Git toolchain. Submodules are, at the highest level, a facility for the composition of Git repositories (Figure 17-1).

Figure 17-1. Nested repos

But unlike some of their non-Git cousins such as SVN Externals, they default to offering greater precision, pointing not only at the network address of the nested repository, but also to the commit hash of the nested repository (Figure 17-2).

Figure 17-2. Nested repos pointing to precise revision

Because each commit ref has, within a repo, a unique identifier to a specific point in the graph and all parent states that led up to that point, pointing to the ref of another repo records that precise state in the commit history of the parent project.

Submodule Commands

Although Chapter 16 provides an exhaustive list of commands, a quick recap of the basic submodule actions is helpful:

git submodule add address localdirectoryname

Register a new submodule for this superproject and, optionally, express it in the specified folder name (can be a subfolder path relative to the root of the project).

git submodule status

Summary of the commit ref and dirtiness state of all submodules at this project level.

git submodule init

Use the .gitmodules long-term ...