Git submodules are useful, but their UX is a bit intrusive for users who aren’t even interacting with the submodules. Here’s a list of the two common ones I often run into. (Let me know if there’s anything else that folks often run into!)

## I cloned a repo containing submodules, but there’s nothing in them!

This happens if you clone a submodule without the --recursive flag. The solution is to run

git submodule update --init --recursive

which will initialize everything.

I figure the main reason this is not the default is that cloning submodules can waste a lot of time, disk space, and/or bandwidth if you don’t actually need the submodules.

## Why are submodules showing up in git status even though I never touched them?

This can happen after git pull, git checkout, or git reset, which change the working tree but do not update the submodules, causing them to lag behind. In git status, the problem manifests as:

modified:   mysubmodule (new commits)

If you are sure you didn’t change any file within the submodules, you can update them using

git submodule update --recursive

I’m not sure why this isn’t the default. Perhaps it’s to avoid accidentally losing changes within the submodules?