git submodule: Usage, Options & Common CI Errors
git submodule embeds another repository at a fixed commit inside your repo.
Submodules are not fetched by a plain clone. CI must init and update them, often with private-repo auth.
What it does
git submodule tracks external repositories as nested checkouts pinned to a specific commit, recorded in .gitmodules and the parent tree.
Common usage
Terminal
git submodule update --init --recursive
git submodule sync --recursive # apply URL changes
git submodule add https://github.com/owner/lib.git libs/lib
git submodule status
git clone --recurse-submodules <url>Options
| Subcommand / flag | What it does |
|---|---|
| update --init | Initialize and fetch submodules |
| --recursive | Recurse into nested submodules |
| sync | Update submodule URLs from .gitmodules |
| --remote | Update to the latest upstream commit |
| add <url> <path> | Add a new submodule |
Common errors in CI
Empty submodule directories mean update --init was never run. fatal: could not read Username for a submodule means a private submodule needs credentials - provide a token or use insteadOf URL rewriting. In actions/checkout, set submodules: recursive and a token with access.
Related guides
git clone: Usage, Options & Common CI Errorsgit clone copies a remote repository into a new local directory. Reference for depth, branch, and submodule f…
git config: Usage, Options & Common CI Errorsgit config gets and sets Git configuration at system, global, and local scope. Reference for --global, --get,…
git fetch: Usage, Options & Common CI Errorsgit fetch downloads remote objects and refs without touching your working tree. Reference for --depth, --unsh…
Git "Host key verification failed" in CI - Fix known_hostsFix Git "Host key verification failed" in CI - the Git host is not in known_hosts, so SSH aborts before authe…