GIT Submodules - Git Series 7

Git submodules are a way to include one Git repository inside another by pinning the submodule directory to a specific commit. That design sounds straightforward—update the submodule by changing which commit the parent repo points to—but it’s also the source of most of the friction people associate with submodules. The core reason they’re hated is that they introduce a second layer of Git state (the parent repo’s branch/commit and the submodule’s pinned commit) that often falls out of sync during normal team workflows.

Submodules get confusing fast because they require different commands and habits than the usual Git flow. Switching branches in the parent repository does not automatically update the submodule contents. This is intentional: the submodule might contain local changes that still need committing, so Git avoids silently overwriting them. In practice, that means developers can pull or switch branches and suddenly see the submodule marked as “modified” even though they didn’t touch it—because the parent repo now expects a different pinned commit inside the submodule directory.

A second major pain point is structural misuse. Teams sometimes use submodules to split what should be one repository into multiple repositories. That turns routine changes into multi-repo coordination: edits must be committed in the submodule, then the parent repo must be updated to point at the new submodule commit, often involving multiple pull requests and careful ordering. The result is more review overhead and more opportunities for mistakes.

The transcript’s practical advice centers on preventing those failure modes. Submodules should link independent repositories—code that can be developed, tested, released, and versioned on its own. If two codebases must constantly move together, the structure likely needs rethinking rather than adding submodules. Good documentation matters too, especially a rule like “update a submodule in a single commit” so the parent repo’s history clearly records “submodule X moved from version 1.5 to 1.6.” Finally, dependency upgrades should be maintained actively because changing the pinned commit can break builds.

The terminal demo reinforces how the workflow behaves. After adding a submodule, the parent repo records only a single commit reference, while the submodule repository maintains its own commit history. Checking out a specific submodule version (e.g., version 1.0) and committing in the parent updates the pinned state. Later, switching the submodule to another version (e.g., version 2) makes the parent repo show the submodule directory as modified; committing in the parent records the new pinned commit.

The demo also shows the classic “modified subproject” confusion when switching parent branches: the submodule stays on the previously pinned version until running `git submodule update`, which checks out the commit the parent expects. Another failure scenario appears when someone makes a change inside the submodule but forgets to push it: teammates can’t fetch the pinned commit, causing submodule update failures. Tests can catch this early because CI will attempt to fetch the parent’s pinned submodule commit; if it’s missing, the pipeline fails and the missing push/version update becomes obvious.

Overall, submodules aren’t inherently broken—they’re just easy to misuse. Used for stable external dependencies with clear versioning and disciplined update practices, they can work cleanly. Used as a substitute for proper repository design or without team-wide workflow alignment, they create confusing diffs, broken builds, and rollback-worthy mistakes.