Submodules

A submodule is a separate Git repository tracked at a specific revision inside a parent repository.

In other words, one repository can include another repository as a nested dependency without merging their histories into one repository.

Why projects use submodules

Projects use submodules when they want to include another repository while keeping it as its own independent Git project.

That can be useful when:

• A project depends on another repository maintained separately.
• A shared component is reused across multiple repositories.
• The parent project wants to control exactly which revision of the nested repository it uses.

Submodules are one way to connect repositories, but they are often more advanced than basic Git workflows.

What the parent repository stores

The parent repository does not copy the full submodule history into its own normal file history.

Instead, it records a reference to a specific commit of the submodule repository. That means the parent repository is effectively saying, "Use that exact version of the nested repository here."

When the submodule is updated, the parent repository records a new reference to a newer submodule commit.

Why submodules can be confusing

Submodules are powerful, but they add another layer of Git state to keep track of.

When working with submodules, you often need to remember that:

• The parent repository and the submodule are separate repositories.
• Each one has its own history and status.
• Updating the submodule contents is different from committing the parent repository's reference to it.

What to watch for

If a repository uses submodules, common things to watch for are:

• Cloning the repository in a way that also initializes the submodules.
• Noticing when the parent repository points to a different submodule commit than the one currently checked out.
• Remembering to commit both the submodule changes and the parent repository's updated submodule reference when needed.

If you are new to Git, it is enough to understand that a submodule is a linked repository inside another repository, and that it has to be managed a little more carefully than normal files.