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.
- Delete the relevant section from the
.gitmodules
file. - Stage the
.gitmodules
changes:git add .gitmodules
. - Delete the relevant section from
.git/config
. - Remove the submodule files from the working tree and index:
git rm --cached path_to_submodule
(no trailing slash). - Remove the submodule's
.git
directory:rm -rf .git/modules/path_to_submodule
. - Commit the changes:
git commit -m "Removed submodule <name>"
. - Delete the now untracked submodule files:
rm -rf path_to_submodule
.