Git submodules let you embed one repository inside another, pinned to an exact commit. This guide moves from basic setup to advanced maintenance and cleanup.
Start here if you're linking a repo for the first time, or cloning a project that already uses submodules.
Result: a .gitmodules file tracks the linked repo URL and path
If you cloned without --recurse-submodules, or need the latest submodule commits, run these in order.
Use these to check submodule health, and resync local config after .gitmodules URLs change.
Removing a submodule takes three steps, done in order. Keep these notes in mind whenever you work with submodules.
.gitmodules tracks the linked repo URL and path The parent repo stores a gitlink (pointer) to an exact submodule commit, not a live branch Always commit inside the submodule first, then commit the updated pointer in the parent repo
Removing a submodule is destructive: double-check the path before running rm -rf on .git/modules.