SYNOPSIS
--------
[verse]
-'git submodule' [--quiet] add [-b branch] [-f|--force]
+'git submodule' [--quiet] add [-b <branch>] [-f|--force] [--name <name>]
[--reference <repository>] [--] <repository> [<path>]
'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...]
'git submodule' [--quiet] init [--] [<path>...]
-'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--rebase]
+'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch] [--rebase]
[--reference <repository>] [--merge] [--recursive] [--] [<path>...]
'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>]
[commit] [--] [<path>...]
initialized, `+` if the currently checked out submodule commit
does not match the SHA-1 found in the index of the containing
repository and `U` if the submodule has merge conflicts.
- This command is the default command for 'git submodule'.
+
If `--recursive` is specified, this command will recurse into nested
submodules, and show their status as well.
+
If `--recursive` is specified, this command will recurse into the
registered submodules, and update any nested submodules within.
++
+If `--force` is specified, the submodule will be checked out (using
+`git checkout --force` if appropriate), even if the commit specified in the
+index of the containing repository already matches the commit checked out in
+the submodule.
summary::
Show commit summary between the given commit (defaults to HEAD) and
-b::
--branch::
Branch of repository to add as submodule.
+ The name of the branch is recorded as `submodule.<path>.branch` in
+ `.gitmodules` for `update --remote`.
-f::
--force::
This option is only valid for add and update commands.
When running add, allow adding an otherwise ignored submodule path.
When running update, throw away local changes in submodules when
- switching to a different commit.
+ switching to a different commit; and always run a checkout operation
+ in the submodule, even if the commit listed in the index of the
+ containing repository matches the commit checked out in the submodule.
--cached::
This option is only valid for status and summary commands. These
(the default). This limit only applies to modified submodules. The
size is always limited to 1 for added/deleted/typechanged submodules.
+--remote::
+ This option is only valid for the update command. Instead of using
+ the superproject's recorded SHA-1 to update the submodule, use the
+ status of the submodule's remote tracking branch. The remote used
+ is branch's remote (`branch.<name>.remote`), defaulting to `origin`.
+ The remote branch used defaults to `master`, but the branch name may
+ be overridden by setting the `submodule.<name>.branch` option in
+ either `.gitmodules` or `.git/config` (with `.git/config` taking
+ precedence).
++
+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`.
+
-N::
--no-fetch::
This option is only valid for the update command.
Initialize all submodules for which "git submodule init" has not been
called so far before updating.
+--name::
+ This option is only valid for the add command. It sets the submodule's
+ name to the given string instead of defaulting to its path. The name
+ must be valid as a directory name and may not end with a '/'.
+
--reference <repository>::
This option is only valid for add and update commands. These
commands sometimes need to clone a remote repository. In this case,