git submodule is a very useful tools in git to include other git repositories in one repository to handle cases such as library dependencies. In this post, I summarize some commonly used commands that I find useful for working with git submodule. For the list of full commands, check the git submodule manual.
Add a submodule
Table of Contents
To add a submodule, if it is the first time (that is, no submodule in the repository yet), under the root directory of the repository, run
git submodule init
git submodule status
git submodule add -f git@example.com/the-repo ./the-repowhich will add the new repository to ./the-repo.
To add other submodules, under the root directory of the repository, run
git submodule add -f git@example.com/the-repo ./the-repoGet submodules
By default, a git clone will not clone the submodule repositories. You may do it during clone by specifying options or further clone submodules in a cloned repository.
During clone
--recuisive will clone the submodules repositories too.
git clone --recursive git@example.org:repoIn a cloned repository
If you have cloned a repository and would like clone all its submodules, run
git submodule update --init --recursiveCheck out the master and update all submodules
foreach runs commands in each submodules. To check out the master and then git pull in each submodules:
git submodule foreach --recursive git checkout master
git submodule foreach --recursive git pullPush the version changes to origin
You may update the repository to update the submodules’ commits used by the repository (such as, updated a depended library inclued as a submodule).
# cd the git repository first (not in submodule)
git commit -am 'submodule updated'
git pushDelete a submodule
To delete a submodule from a repository, first
git submodule deinit ./the-repoto remove the submodule from the repository.
If you would like to remove the submodule directory and files too, run
git rm ./the-repo