submodules

Submodules are a feature of Git that allow you to embed one repository inside another. They enable a project to track a specific commit of an external repository while keeping that repository’s history separate. The superproject holds a reference to the submodule’s commit and a separate subrepository maintains its own history.

The relationship is defined by the .gitmodules file at the root of the superproject and by a gitlink entry in the superproject’s tree. Each submodule is an independent Git repository with its own .git directory, while the superproject stores a pointer to a particular commit in the submodule. Cloning a repository with submodules requires extra steps, such as git clone --recurse-submodules or clone followed by git submodule update --init --recursive, to fetch and initialize the embedded repositories.

Typical workflows involve adding a submodule with git submodule add <url> <path>, which creates the .gitmodules file and places a pointer to the submodule’s commit in the superproject. To update a submodule, you can enter the submodule directory, fetch, and check out a newer commit, or use git submodule update --remote to advance the pointer automatically. After updating, you must commit changes in both the submodule (if it changed) and the superproject to record the new pointer.

Common considerations include the fact that submodule pointers are immutable until committed in the superproject, and that working with submodules can be confusing when a submodule is detached or when multiple developers work with different submodule states. Deinitializing or removing a submodule requires cleaning both the gitlink and the .gitmodules entry.

Submodules are often used to pin dependencies with separate histories or to integrate external projects without adopting a full monorepo. Alternatives include git subtree, vendor folders, or package managers, depending on the use case.