--------
[verse]
'git submodule' [--quiet] add [-b <branch>] [-f|--force] [--name <name>]
- [--reference <repository>] [--] <repository> [<path>]
+ [--reference <repository>] [--
depth <depth>] [--] <repository> [<path>]
'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...]
'git submodule' [--quiet] init [--] [<path>...]
'git submodule' [--quiet] deinit [-f|--force] [--] <path>...
'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch]
- [-f|--force] [--rebase] [--reference <repository>]
- [--
merge] [--recursive] [--] [<path>...]
+ [-f|--force] [--rebase|--merge] [--reference <repository>]
+ [--
depth <depth>] [--recursive] [--] [<path>...]
'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>]
[commit] [--] [<path>...]
'git submodule' [--quiet] foreach [--recursive] <command>
-'git submodule' [--quiet] sync [--] [<path>...]
+'git submodule' [--quiet] sync [--
recursive] [--] [<path>...]
DESCRIPTION
it contains local modifications.
update::
- Update the registered submodules, i.e. clone missing submodules and
- checkout the commit specified in the index of the containing repository.
- This will make the submodules HEAD be detached unless `--rebase` or
- `--merge` is specified or the key `submodule.$name.update` is set to
- `rebase`, `merge` or `none`. `none` can be overridden by specifying
- `--checkout`.
+
+--
+Update the registered submodules to match what the superproject
+expects by cloning missing submodules and updating the working tree of
+the submodules. The "updating" can be done in several ways depending
+on command line options and the value of `submodule.<name>.update`
+configuration variable. Supported update procedures are:
+
+ checkout;; the commit recorded in the superproject will be
+ checked out in the submodule on a detached HEAD. This is
+ done when `--checkout` option is given, or no option is
+ given, and `submodule.<name>.update` is unset, or if it is
+ set to 'checkout'.
++
+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.
+
+ rebase;; the current branch of the submodule will be rebased
+ onto the commit recorded in the superproject. This is done
+ when `--rebase` option is given, or no option is given, and
+ `submodule.<name>.update` is set to 'rebase'.
+
+ merge;; the commit recorded in the superproject will be merged
+ into the current branch in the submodule. This is done
+ when `--merge` option is given, or no option is given, and
+ `submodule.<name>.update` is set to 'merge'.
+
+ custom command;; arbitrary shell command that takes a single
+ argument (the sha1 of the commit recorded in the
+ superproject) is executed. This is done when no option is
+ given, and `submodule.<name>.update` has the form of
+ '!command'.
+
+When no option is given and `submodule.<name>.update` is set to 'none',
+the submodule is not updated.
+
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 `--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
working tree/index. For a submodule in question, a series of commits
-b::
--branch::
Branch of repository to add as submodule.
- The name of the branch is recorded as `submodule.<path>.branch` in
+ The name of the branch is recorded as `submodule.<name>.branch` in
`.gitmodules` for `update --remote`.
-f::
When running add, allow adding an otherwise ignored submodule path.
When running deinit the submodule work trees will be removed even if
they contain local changes.
- When running update, throw away local changes in submodules when
- 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.
+ When running update (only effective with the checkout procedure),
+ throw away local changes in submodules when 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
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::
This option is only valid for the update command.
Don't fetch new objects from the remote site.
+--checkout::
+ This option is only valid for the update command.
+ Checkout the commit recorded in the superproject on a detached HEAD
+ in the submodule. This is the default behavior, the main use of
+ this option is to override `submodule.$name.update` when set to
+ a value other than `checkout`.
+ If the key `submodule.$name.update` is either not explicitly set or
+ set to `checkout`, this option is implicit.
+
--merge::
This option is only valid for the update command.
Merge the commit recorded in the superproject into the current branch
only in the submodules of the current repo, but also
in any nested submodules inside those submodules (and so on).
+--depth::
+ This option is valid for add and update commands. Create a 'shallow'
+ clone with a history truncated to the specified number of revisions.
+ See linkgit:git-clone[1]
+
+
<path>...::
Paths to submodule(s). When specified this will restrict the command
to only operate on the submodules found at the specified paths.