Pushing Git Submodule Commits Automatically

5 February 2026 by Phillip Johnston

We all know it: working with submodules is a frustrating experience.

Something I’ve done so often is make changes locally in a submodule, commit them, update the pointer in the container repo… but completely forget to push the submodule. Now I’ve broken the repo state for everyone!

I just learned about a helpful git command option and configuration setting to avoid this fiasco.

First, you can use two options:

git push --recurse-submodules=on-demand
# Above will push each submodule that the main repository references, then push the main repository
git push --recurse-submodules=check
# Above will cause the push to fail if any submodule has commits that need to be pushed

The on-demand option is what I want for my development, while the check option is preferable in contexts where submodules with commits would be unexpected – like on a CI server.

Thankfully, you can also set this as default behavior with git:

git config push.recurseSubmodules on-demand
# Above sets the option locally
git config --global push.recurseSubmodules on-demand
# Above will apply it as the default for this machine

Related

• git