SYNOPSIS
--------
[verse]
-'git submodule' [--quiet] add [-b <branch>] [-f|--force] [--name <name>]
- [--reference <repository>] [--depth <depth>] [--] <repository> [<path>]
+'git submodule' [--quiet] add [<options>] [--] <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]
- [-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] update [<options>] [--] [<path>...]
+'git submodule' [--quiet] summary [<options>] [--] [<path>...]
'git submodule' [--quiet] foreach [--recursive] <command>
'git submodule' [--quiet] sync [--recursive] [--] [<path>...]
+'git submodule' [--quiet] absorbgitdirs [--] [<path>...]
DESCRIPTION
COMMANDS
--------
-add::
+add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--depth <depth>] [--] <repository> [<path>]::
Add the given repository as a submodule at the given path
to the changeset to be committed next to the current
project: the current project is termed the "superproject".
+
<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 origin
+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).
-If the superproject doesn't have an origin configured
++
+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.
+
superproject's URL needs to be provided: git-submodule will correctly
locate the submodule using the relative URL in .gitmodules.
-status::
+status [--cached] [--recursive] [--] [<path>...]::
Show the status of the submodules. This will print the SHA-1 of the
currently checked out commit for each submodule, along with the
submodule path and the output of 'git describe' for the
linkgit:git-status[1] and linkgit:git-diff[1] will provide that information
too (and can also report changes to a submodule's work tree).
-init::
+init [--] [<path>...]::
Initialize the submodules recorded in the index (which were
- added and committed elsewhere) by copying submodule
- names and urls from .gitmodules to .git/config.
- Optional <path> arguments limit which submodules will be initialized.
- It will also copy the value of `submodule.$name.update` into
- .git/config.
- The key used in .git/config is `submodule.$name.url`.
- This command does not alter existing information in .git/config.
- 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.
-
-deinit::
+ added and committed elsewhere) by setting `submodule.$name.url`
+ in .git/config. It uses the same setting from .gitmodules as
+ a template. If the URL is relative, it will be resolved using
+ the default remote. If there is no default remote, the current
+ repository will be assumed to be upstream.
++
+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.
++
+When present, it will also copy the value of `submodule.$name.update`.
+This command does not alter existing information in .git/config.
+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 defintion of default remote.
+
+deinit [-f|--force] (--all|[--] <path>...)::
Unregister the given submodules, i.e. remove the whole
`submodule.$name` section from .git/config together with their work
tree. Further calls to `git submodule update`, `git submodule foreach`
If `--force` is specified, the submodule's working tree will
be removed even if it contains local modifications.
-update::
+update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--] [<path>...]::
+
--
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:
+configuration variable. The command line option takes precedence over
+the configuration variable. if neither is given, a checkout is performed.
+update procedures supported both from the command line as well as setting
+`submodule.<name>.update`:
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'.
+ checked out in the submodule on a detached HEAD.
+
If `--force` is specified, the submodule will be checked out (using
`git checkout --force` if appropriate), even if the commit specified
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'.
+ onto the commit recorded in the superproject.
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'.
+ into the current branch in the submodule.
+
+The following procedures are only available via the `submodule.<name>.update`
+configuration variable:
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'.
+ superproject) is executed. When `submodule.<name>.update`
+ is set to '!command', the remainder after the exclamation mark
+ is the custom command.
-When no option is given and `submodule.<name>.update` is set to 'none',
-the submodule is not updated.
+ 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
If `--recursive` is specified, this command will recurse into the
registered submodules, and update any nested submodules within.
--
-summary::
+summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...]::
Show commit summary between the given commit (defaults to HEAD) and
working tree/index. For a submodule in question, a series of commits
in the submodule between the given super project commit and the
Using the `--submodule=log` option with linkgit:git-diff[1] will provide that
information too.
-foreach::
+foreach [--recursive] <command>::
Evaluates an arbitrary shell command in each checked out submodule.
The command has access to the variables $name, $path, $sha1 and
$toplevel:
the processing to terminate. This can be overridden by adding '|| :'
to the end of the command.
+
-As an example, +git submodule foreach \'echo $path {backtick}git
-rev-parse HEAD{backtick}'+ will show the path and currently checked out
-commit for each submodule.
+As an example, the command below will show the path and currently
+checked out commit for each submodule:
++
+--------------
+git submodule foreach 'echo $path `git rev-parse HEAD`'
+--------------
-sync::
+sync [--recursive] [--] [<path>...]::
Synchronizes submodules' remote URL configuration setting
to the value specified in .gitmodules. It will only affect those
submodules which already have a URL entry in .git/config (that is the
If `--recursive` is specified, this command will recurse into the
registered submodules, and sync any nested submodules within.
+absorbgitdirs::
+ If a git directory of a submodule is inside the submodule,
+ move the git directory of the submodule into its superprojects
+ `$GIT_DIR/modules` path and then connect the git directory and
+ its working directory by setting the `core.worktree` and adding
+ a .git file pointing to the git directory embedded in the
+ superprojects git directory.
++
+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::
--branch::
Branch of repository to add as submodule.
The name of the branch is recorded as `submodule.<name>.branch` in
- `.gitmodules` for `update --remote`.
+ `.gitmodules` for `update --remote`. A special value of `.` is used to
+ indicate that the name of the branch in the submodule should be the
+ same name as the current branch in the current repository.
-f::
--force::
clone with a history truncated to the specified number of revisions.
See linkgit:git-clone[1]
+--[no-]recommend-shallow::
+ This option is only valid for the update command.
+ The initial clone of a submodule will use the recommended
+ `submodule.<name>.shallow` as provided by the .gitmodules file
+ by default. To ignore the suggestions use `--no-recommend-shallow`.
+
-j <n>::
--jobs <n>::
This option is only valid for the update command.