Basic Git Submodule Commands

Submodules are the built in way of Git to work on a project that contain multiple repositories. To be more precise: if you have a repository and you want to have the files of another repository available in a subfolder, you add that other repository as a submodule. This could be useful for pulling in a component that another team in your company is working on. It also comes in handy if you have different subprojects yourself that you want to work on those in isolation, but also on the overarching project that combines them. If you have a submodule in your project, you are not limited to reading the files, you can also create new commits and push them to the subprojects repository.

Adding a Submodule

This is described in the manual:

git submodule add git@remote/subrepo

This is a change that you can/have to commit in the main repo.

The files of the submodule are not automatically downloaded, the submodules must be initialized first:

git submodule update --init

Make Changes in a Submodule

As promised, you can make changes. Normally submodules are in a detached head state and you work will be overwritten without question. To change that, go into the submodule folder and checkout a new/existing branch the normal way.

Updating Submodules

git submodule update

If you’ve made changes in the subodule, they will get overwritten.

To prevent that:

git subodule update --merge --rebase

Or --merge if you want to merge the upstream changes with your own.

Push Submodule Changes

To see what needs to be pushed:

git push --recurse-submodules=check

This will give information on the command you cvan use. Spoiler, you can also go into the submodule folder and do git push there.

Removing a Submodule

This is a somewhat involved process.

Sources