Submodules - Repos Inside Repos

git submodule

A submodule embeds one entire Git repository inside another, pinned to one specific commit - typically used to include a shared library or a vendored dependency as source code, while keeping its own commit history completely separate from your project's history.

$ git submodule add https://github.com/org/shared-lib.git libs/shared
$ git clone --recurse-submodules <url>     # clone a repo WITH its submodules already populated
$ git submodule update --init --recursive  # fetch submodule contents after a plain clone

The crucial detail: the parent repo doesn't record "use whatever is on the submodule's main branch" - it records the submodule's exact commit hash at the time you added or last updated it. That pinning is deliberate: it means anyone building your project gets exactly the same version of the dependency you tested against, not whatever the dependency's maintainers happen to have pushed since.

Warning: Submodules are powerful but notoriously fiddly for newcomers. A plain git clone (without --recurse-submodules) leaves every submodule folder completely empty - Git only clones the parent repo's own reference to the submodule, not its contents. You must explicitly run --recurse-submodules on clone, or submodule update --init afterwards. Forgetting this and then wondering why a supposedly-included library folder is empty is the single most common submodule complaint.

Tip: For monorepo-style code sharing, many teams prefer alternatives to submodules entirely - private package registries, or git subtree - specifically because submodules add this kind of everyday friction. It's worth knowing submodules exist and how they behave, but reach for them deliberately, not by default.