Submodules - Repos Inside Repos

git submodule

A submodule embeds one Git repo inside another at a pinned commit - used to include a shared library or vendored dependency while keeping its history separate.

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

The parent repo records the submodule's exact commit, not a moving branch - so builds are reproducible.

Warning: Submodules are powerful but notoriously fiddly. A plain git clone leaves submodule folders empty - you must --recurse-submodules (or run submodule update --init). Forgetting this is the #1 submodule gotcha.

Tip: For monorepo-style code sharing many teams prefer alternatives (package registries, git subtree) because submodules add friction. Know them, but reach for them deliberately.