- Install a repository's specified submodules:
git submodule update --init --recursive
- Add a git repository as a submodule:
git submodule add [repository_url]
- Add a git repository as a submodule at the specified directory:
git submodule add [repository_url] [path/to/directory]
- Update every submodule to its latest commit:
git submodule foreach git pull
git submodule [--quiet] add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--depth <depth>] [--] <repository> [<path>] git submodule [--quiet] status [--cached] [--recursive] [--] [<path>...] git submodule [--quiet] init [--] [<path>...] git submodule [--quiet] deinit [-f|--force] (--all|[--] <path>...) git submodule [--quiet] update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--] [<path>...] git submodule [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...] git submodule [--quiet] foreach [--recursive] <command> git submodule [--quiet] sync [--recursive] [--] [<path>...]
Inspects, updates and manages submodules.
A submodule allows you to keep another Git repository in a subdirectory of your repository. The other repository has its own history, which does not interfere with the history of the current repository. This can be used to have external dependencies such as third party libraries for example.
When cloning or pulling a repository containing submodules however, these will not be checked out by default; the init and update subcommands will maintain submodules checked out and at appropriate revision in your working tree.
Submodules are composed from a so-called gitlink tree entry in the main repository that refers to a particular commit object within the inner repository that is completely separate. A record in the .gitmodules (see gitmodules(5)) file at the root of the source tree assigns a logical name to the submodule and describes the default URL the submodule shall be cloned from. The logical name can be used for overriding this URL within your local repository configuration (see submodule init).
Submodules are not to be confused with remotes, which are other repositories of the same project; submodules are meant for different projects you would like to make part of your source tree, while the history of the two projects still stays completely independent and you cannot modify the contents of the submodule from within the main project. If you want to merge the project histories and want to treat the aggregated whole as a single project from then on, you may want to add a remote for the other project and use the subtree merge strategy, instead of treating the other project as a submodule. Directories that come from both projects can be cloned and checked out as a whole if you choose to go that route.
When initializing submodules, a .gitmodules file in the top-level directory of the containing repository is used to find the url of each submodule. This file should be formatted in the same way as $GIT_DIR/config. The key to each submodule url is "submodule.$name.url". See gitmodules(5) for details.