Q: Your team uses Git submodules to include a shared library in three different services. A developer reports that after cloning, the submodule directory is empty. What happened, and how do you manage submodules correctly?

git clone does not initialize submodules by default — it clones the parent repo and creates the submodule directory, but leaves it empty. The fix:

• The parent repo stores a .gitmodules file (URL + path mapping) and a special tree entry recording the *exact* commit SHA the submodule should point to.
• git submodule update checks out that pinned commit inside the submodule directory — it puts the submodule in detached HEAD state.
• To update the submodule to its latest upstream commit: cd && git pull origin main, then go back to the parent repo and git add && git commit to record the new SHA.
• Forgetting --recurse-submodules on clone, pull, and checkout — configure globally: git config --global submodule.recurse true.

Or clone with submodules from the start: How submodules work: Common pitfalls: Many teams eventually migrate away from submodules to package managers (npm, pip, Maven) or monorepo approaches because submodules add significant cognitive overhead.

git submodule update --init --recursive

• Committing without updating the submodule pointer — you update the library but forget to commit the new SHA in the parent repo. Other developers don't get the update.
• Nested submodules — always use --recursive.