Git Submodules

Note

It’s quite likely that if you’re using submodules, you’re doing so because you really want to work on the code in the submodule at the same time as you’re working on the code in the main project (or across several submodules).

Otherwise, you would probably instead be using a simpler dependency management system (such as Maven or Rubygems).

Starting with Submodules

git submodule add https://github.com/chaconinc/DbConnector

.gitmodules file:

 [submodule "DbConnector"]
     path = DbConnector
     url = https://github.com/chaconinc/DbConnector

git diff --cached --submodule

Cloning a Project with Submodules

git clone https://github.com/chaconinc/MainProject, then;
git submodule init + git submodule update or;
git submodule update --init --recursive or;
git clone --recurse-submodules https://github.com/chaconinc/MainProject

Working on a Project with Submodules

Pulling in Upstream Changes from the Submodule Remote

git config --global diff.submodule log
git config status.submodulesummary 1
git submodule update --remote

Pulling Upstream Changes from the Project Remote

git pull --recurse-submodules or;
git config submodule.recurse true.

Working on a Submodule

You need to go into each submodule and check out a branch to work on. Then you need to tell Git what to do if you have made changes and then git submodule update --remote pulls in new work from upstream. The options are that you can merge them into your local work, or you can try to rebase your local work on top of the new changes.

cd DbConnector/
git checkout stable
cd ..
git submodule update --remote --merge or git submodule update --remote --rebase

Publishing Submodule Changes

git push --recurse-submodules=check
1. The check option will make push simply fail if any of the committed submodule changes haven’t been pushed.
2. You can make this behavior the default by doing git config push.recurseSubmodules check.
git push --recurse-submodules=on-demand.
1. You can make this behavior the default by doing git config push.recurseSubmodules on-demand.

Submodule Tips

Useful Aliases

$ git config alias.sdiff '!'"git diff && git submodule foreach 'git diff'"
$ git config alias.spush 'push --recurse-submodules=on-demand'
$ git config alias.supdate 'submodule update --remote --merge'

Issues with Submodules

Switching branches

Tip

It’s a good idea to always git checkout --recurse-submodules when your project has submodules.

Luckily, you can tell Git (>=2.14) to always use the --recurse-submodules flag by setting the configuration option submodule.recurse: git config submodule.recurse true. As noted above, this will also make Git recurse into submodules for every command that has a --recurse-submodules option (except git clone).