Git Submodules
A submodule lets you include another Git repository as a subdirectory inside your own repository, while keeping its history completely separate. This is useful for sharing libraries across multiple projects.
Submodules pin a specific commit of the external repository, so your project always references an exact, reproducible version rather than always tracking its latest changes automatically.
git submodule add <url> <path>
git submodule update --init --recursiveAdding a submodule
Run `git submodule add <url> path` to add another repository as a submodule at the given path. This records the submodule's URL and commit in a `.gitmodules` file.
Cloning projects with submodules
When cloning a repository that has submodules, use `git clone --recurse-submodules <url>`, or run `git submodule update --init --recursive` afterward.
git submodule add https://github.com/user/shared-lib.git libs/shared-libCloning into 'libs/shared-lib'...Adds an external repository as a submodule inside the libs/shared-lib folder.
git clone --recurse-submodules https://github.com/user/main-project.gitCloning into 'main-project'...
Submodule 'libs/shared-lib' registered for path 'libs/shared-lib'Clones a project and automatically initializes and fetches all its submodules.
Key points
- A submodule embeds another Git repository inside your project.
- Submodules pin an exact commit, not the latest branch automatically.
- Submodule info is stored in a .gitmodules file.
- Cloning requires --recurse-submodules to also fetch submodule content.