NAME
git-submodule - Initialize, update or inspect submodules
SYNOPSIS
git submodule\n [--quiet] [--cached]
\ngit submodule\n [--quiet] add [<options>] [--] <repository> [<path>]
\ngit submodule\n [--quiet] status [--cached] [--recursive] [--] [<path>...]
\ngit submodule\n [--quiet] init [--] [<path>...]
\ngit submodule\n [--quiet] deinit [-f|--force] (--all|[--] <path>...)
\ngit submodule\n [--quiet] update [<options>] [--] [<path>...]
\ngit submodule\n [--quiet] set-branch [<options>] [--] <path>
\ngit submodule\n [--quiet] set-url [--] <path> <newurl>
\ngit submodule\n [--quiet] summary [<options>] [--] [<path>...]
\ngit submodule\n [--quiet] foreach [--recursive] <command>
\ngit submodule\n [--quiet] sync [--recursive] [--] [<path>...]
\ngit submodule\n [--quiet] absorbgitdirs [--] [<path>...]DESCRIPTION
Inspects, updates and manages submodules.
For more information about submodules, see gitsubmodules(7).
COMMANDS
With no arguments, shows the status of existing submodules. Several subcommands are available to perform operations on the submodules.
add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--] <repository> [<path>]
<repository> is the URL of the new submodule’s origin repository. This may be either an absolute URL, or (if it begins with ./ or ../), the location relative to the superproject’s default remote repository (Please note that to specify a repository foo.git which is located right next to a superproject bar.git, you’ll have to use ../foo.git instead of ./foo.git - as one might expect when following the rules for relative URLs - because the evaluation of relative URLs in Git is identical to that of relative directories).
The default remote is the remote of the remote-tracking branch of the current branch. If no such remote-tracking branch exists or the HEAD is detached, "origin" is assumed to be the default remote. If the superproject doesn’t have a default remote configured the superproject is its own authoritative upstream and the current working directory is used instead.
The optional argument <path> is the relative location for the cloned submodule to exist in the superproject. If <path> is not given, the canonical part of the source repository is used ("repo" for "/path/to/repo.git" and "foo" for "host.xz:foo/.git"). If <path> exists and is already a valid Git repository, then it is staged for commit without cloning. The <path> is also used as the submodule’s logical name in its configuration entries unless --name is used to specify a logical name.
The given URL is recorded into .gitmodules for use by subsequent users cloning the superproject. If the URL is given relative to the superproject’s repository, the presumption is the superproject and submodule repositories will be kept together in the same relative location, and only the superproject’s URL needs to be provided. git-submodule will correctly locate the submodule using the relative URL in .gitmodules.
If --ref-format <format> is specified, the ref storage format of newly cloned submodules will be set accordingly.
status [--cached] [--recursive] [--] [<path>...]
If --cached is specified, this command will instead print the SHA-1 recorded in the superproject for each submodule.
If --recursive is specified, this command will recurse into nested submodules, and show their status as well.
If you are only interested in changes of the currently initialized submodules with respect to the commit recorded in the index or the HEAD, git-status(1) and git-diff(1) will provide that information too (and can also report changes to a submodule’s work tree).
init [--] [<path>...]
Optional <path> arguments limit which submodules will be initialized. If no path is specified and submodule.active has been configured, submodules configured to be active will be initialized, otherwise all submodules are initialized.
It will also copy the value of submodule.$name.update, if present in the .gitmodules file, to .git/config, but (1) this command does not alter existing information in .git/config, and (2) submodule.$name.update that is set to a custom command is not copied for security reasons.
You can then customize the submodule clone URLs in .git/config for your local setup and proceed to git submodule update; you can also just use git submodule update --init without the explicit init step if you do not intend to customize any submodule locations.
See the add subcommand for the definition of default remote.
deinit [-f|--force] (--all|[--] <path>...)
When the command is run without pathspec, it errors out, instead of deinit-ing everything, to prevent mistakes.
If --force is specified, the submodule’s working tree will be removed even if it contains local modifications.
If you really want to remove a submodule from the repository and commit that use git-rm(1) instead. See gitsubmodules(7) for removal options.
update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter <filter-spec>] [--] [<path>...]
checkout
If --force is specified, the submodule will be checked out (using git checkout --force), even if the commit specified in the index of the containing repository already matches the commit checked out in the submodule.
rebase
merge
The following update procedures have additional limitations:
custom command
none
If the submodule is not yet initialized, and you just want to use the setting as stored in .gitmodules, you can automatically initialize the submodule with the --init option.
If --recursive is specified, this command will recurse into the registered submodules, and update any nested submodules within.
If --ref-format <format> is specified, the ref storage format of newly cloned submodules will be set accordingly.
If --filter <filter-spec> is specified, the given partial clone filter will be applied to the submodule. See git-rev-list(1) for details on filter specifications.
set-branch (-b|--branch) <branch> [--] <path>, set-branch (-d|--default) [--] <path>
set-url [--] <path> <newurl>
summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...]
Using the --submodule=log option with git-diff(1) will provide that information too.
foreach [--recursive] <command>
As an example, the command below will show the path and currently checked out commit for each submodule:
git submodule foreach 'echo $sm_path `git rev-parse HEAD`'sync [--recursive] [--] [<path>...]
git submodule sync synchronizes all submodules while git submodule sync -- A synchronizes submodule "A" only.
If --recursive is specified, this command will recurse into the registered submodules, and sync any nested submodules within.
absorbgitdirs
A repository that was cloned independently and later added as a submodule or old setups have the submodules git directory inside the submodule instead of embedded into the superprojects git directory.
This command is recursive by default.
OPTIONS
-q, --quiet
--progress
--all
-b <branch>, --branch <branch>
-f, --force
--cached
--files
-n, --summary-limit
--remote
This works for any of the supported update procedures (--checkout, --rebase, etc.). The only change is the source of the target SHA-1. For example, submodule update --remote --merge will merge upstream submodule changes into the submodules, while submodule update --merge will merge superproject gitlink changes into the submodules.
In order to ensure a current tracking branch state, update --remote fetches the submodule’s remote repository before calculating the SHA-1. If you don’t want to fetch, you should use submodule update --remote --no-fetch.
Use this option to integrate changes from the upstream subproject with your submodule’s current HEAD. Alternatively, you can run git pull from the submodule, which is equivalent except for the remote branch name: update --remote uses the default upstream repository and submodule.<name>.branch, while git pull uses the submodule’s branch.<name>.merge. Prefer submodule.<name>.branch if you want to distribute the default upstream branch with the superproject and branch.<name>.merge if you want a more native feel while working in the submodule itself.
-N, --no-fetch
--checkout
--merge
--rebase
--init
--name
--reference <repository>
NOTE: Do not use this option unless you have read the note for git-clone(1)'s --reference, --shared, and --dissociate options carefully.
--dissociate
NOTE: see the NOTE for the --reference option.
--recursive
--depth
--[no-]recommend-shallow
-j <n>, --jobs <n>
--[no-]single-branch
<path>...
FILES
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.
SEE ALSO
gitsubmodules(7), gitmodules(5).
GIT
Part of the git(1) suite