panel 1

Illustration of a smiling stick figure with curly hair.

person: I find submodules confusing and I avoid them if possible, but here’s what I’ve learned from other people’s writing on submodules

(especially Dmitry Mazin’s great “Demystifying Git Submodules” post)

submodules let you store another git repository as a subdirectory

git submodule add
   https://github.com/jvns/myrepo
   ./myrepo

(jvns is the remote, myrepo is the local path)

Git will store the commit ID and URL of the submodule

gotcha: cloning a repository doesn’t download its submodules

To get the submodules, you can run this after cloning the repository:

git submodule update --init

gotcha: git pull and git checkout don’t update submodules gotcha: git pull and git checkout don’t update submodules

To actually update them, you have to run:

git submodule update

every single time you switch branches or pull

gotcha: git submodule update puts the submodule in detached HEAD state

might not be a big deal if you’re only using the submodule in a read-only way, but seems like it could get weird if you’re editing it

some submodule config options

automatically update submodules after a pull/checkout:

submodule.recurse true

show which commits were added/removed in git diff/git status:

status.submoduleSummary true
diff.submodule log