-----------
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 linkgit: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.
+ For more information about submodules, see linkgit:gitsubmodules[7].
COMMANDS
--------
to the changeset to be committed next to the current
project: the current project is termed the "superproject".
+
-This requires at least one argument: <repository>. The optional
-argument <path> is the relative location for the cloned submodule
-to exist in the superproject. If <path> is not given, the
-"humanish" part of the source repository is used ("repo" for
-"/path/to/repo.git" and "foo" for "host.xz:foo/.git").
-The <path> is also used as the submodule's logical name in its
-configuration entries unless `--name` is used to specify a logical name.
-+
<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
the superproject is its own authoritative upstream and the current
working directory is used instead.
+
-<path> is the relative location for the cloned submodule to
-exist in the superproject. If <path> does not exist, then the
-submodule is created by cloning from the named URL. If <path> does
-exist and is already a valid Git repository, then this is added
-to the changeset without cloning. This second form is provided
-to ease creating a new submodule from scratch, and presumes
-the user will later push the submodule to the given URL.
+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.
+
-In either case, 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.
+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`.
status [--cached] [--recursive] [--] [<path>...]::
Show the status of the submodules. This will print the SHA-1 of the
init [--] [<path>...]::
Initialize the submodules recorded in the index (which were
added and committed elsewhere) by setting `submodule.$name.url`
- in .git/config. It uses the same setting from .gitmodules as
+ 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.
the explicit 'init' step if you do not intend to customize
any submodule locations.
+
-See the add subcommand for the defintion of default remote.
+See the add subcommand for the definition of default remote.
deinit [-f|--force] (--all|[--] <path>...)::
Unregister the given submodules, i.e. remove the whole
tree. Further calls to `git submodule update`, `git submodule foreach`
and `git submodule sync` will skip any unregistered submodules until
they are initialized again, so use this command if you don't want to
- have a local checkout of the submodule in your working tree anymore. If
- you really want to remove a submodule from the repository and commit
- that use linkgit:git-rm[1] instead.
+ have a local checkout of the submodule in your working tree anymore.
+
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 linkgit:git-rm[1] instead. See linkgit:gitsubmodules[7] for removal
+ options.
update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--] [<path>...]::
+
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
+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
Evaluates an arbitrary shell command in each checked out submodule.
The command has access to the variables $name, $path, $sha1 and
$toplevel:
- $name is the name of the relevant submodule section in .gitmodules,
+ $name is the name of the relevant submodule section in `.gitmodules`,
$path is the name of the submodule directory relative to the
superproject, $sha1 is the commit as recorded in the superproject,
and $toplevel is the absolute path to the top-level of the superproject.
sync [--recursive] [--] [<path>...]::
Synchronizes submodules' remote URL configuration setting
- to the value specified in .gitmodules. It will only affect those
+ to the value specified in `.gitmodules`. It will only affect those
submodules which already have a URL entry in .git/config (that is the
case when they are initialized or freshly added). This is useful when
submodule URLs change upstream and you need to update your local
--[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
+ `submodule.<name>.shallow` as provided by the `.gitmodules` file
by default. To ignore the suggestions use `--no-recommend-shallow`.
-j <n>::
FILES
-----
-When initializing submodules, a .gitmodules file in the top-level directory
+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 linkgit:gitmodules[5]
for details.
+ SEE ALSO
+ --------
+ linkgit:gitsubmodules[7], linkgit:gitmodules[5].
+
GIT
---
Part of the linkgit:git[1] suite