Frequently Asked Question

What are submodules and subtrees, and when should I use them?

A submodule is a pointer in your repository to a specific commit in a different Git repository, mounted at a path inside yours. git submodule add <url> path/ adds one; cloning a project with submodules requires git clone --recursive or a subsequent git submodule update --init. Your repository tracks the submodule's exact commit hash, so the build is reproducible, but the submodule's files are not part of your repository's history, they are fetched from elsewhere.

A subtree, in contrast, copies another project's files (and optionally its history) directly into a subdirectory of your repository. git subtree add --prefix=lib/foo <url> main --squash is the typical incantation. Your repository becomes self-contained; nobody needs to fetch anything extra, but you no longer have a clean pointer to upstream. Submodules are right when the dependency has its own lifecycle and you want a hard version pin; subtrees are right when you want one repository to git clone and have everything. Most teams find both fiddly enough that a proper package manager (npm, cargo, pip) is preferable when one exists.