SYNOPSIS
--------
[verse]
-'git-submodule' [--quiet] [-b branch] add <repository> [<path>]
-'git-submodule' [--quiet] [--cached] [status|init|update] [--] [<path>...]
+'git-submodule' [--quiet] add [-b branch] [--] <repository> [<path>]
+'git-submodule' [--quiet] status [--cached] [--] [<path>...]
+'git-submodule' [--quiet] init [--] [<path>...]
+'git-submodule' [--quiet] update [--init] [--] [<path>...]
+'git-submodule' [--quiet] summary [--summary-limit <n>] [commit] [--] [<path>...]
COMMANDS
--------
add::
Add the given repository as a submodule at the given path
- to the changeset to be committed next. In particular, the
- repository is cloned at the specified path, added to the
+ to the changeset to be committed next. If path is a valid
+ repository within the project, it is added as is. Otherwise,
+ repository is cloned at the specified path. path is added to the
changeset and registered in .gitmodules. If no path is
specified, the path is deduced from the repository specification.
+ If the repository url begins with ./ or ../, it is stored as
+ given but resolved as a relative path from the main project's
+ url when cloning.
status::
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 gitlink:git-describe[1] for the
+ submodule path and the output of linkgit:git-describe[1] for the
SHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not
initialized and `+` if the currently checked out submodule commit
does not match the SHA-1 found in the index of the containing
init::
Initialize the submodules, i.e. register in .git/config each submodule
- path and url found in .gitmodules. The key used in git/config is
- `submodule.$path.url`. This command does not alter existing information
+ name and url found in .gitmodules. The key used in .git/config is
+ `submodule.$name.url`. This command does not alter existing information
in .git/config.
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.
++
+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.
+summary::
+ 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
+ index or working tree (switched by --cached) are shown.
OPTIONS
-------
Branch of repository to add as submodule.
--cached::
- Display the SHA-1 stored in the index, not the SHA-1 of the currently
- checked out submodule commit. This option is only valid for the
- status command.
+ This option is only valid for status and summary commands. These
+ commands typically use the commit found in the submodule HEAD, but
+ with this option, the commit stored in the index is used instead.
+
+-n, --summary-limit::
+ This option is only valid for the summary command.
+ Limit the summary size (number of commits shown in total).
+ Giving 0 will disable the summary; a negative number means unlimited
+ (the default). This limit only applies to modified submodules. The
+ size is always limited to 1 for added/deleted/typechanged submodules.
<path>::
Path to submodule(s). When specified this will restrict the command
-----
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 $GIR_DIR/config. The key
-to each submodule url is "module.$path.url".
+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.
AUTHOR
GIT
---
-Part of the gitlink:git[7] suite
+Part of the linkgit:git[7] suite