summaryrefslogtreecommitdiff
path: root/Documentation/git-submodule.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/git-submodule.txt')
-rw-r--r--Documentation/git-submodule.txt81
1 files changed, 49 insertions, 32 deletions
diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 9226c43..4a4cede 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -9,18 +9,15 @@ git-submodule - Initialize, update or inspect submodules
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
@@ -61,7 +58,7 @@ if you choose to go that route.
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".
@@ -102,7 +99,7 @@ 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::
+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
@@ -119,7 +116,7 @@ submodules with respect to the commit recorded in the index or the HEAD,
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.
@@ -134,7 +131,7 @@ init::
the explicit 'init' step if you do not intend to customize
any submodule locations.
-deinit::
+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`
@@ -150,20 +147,20 @@ 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.
-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
@@ -171,23 +168,21 @@ 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'.
+ 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
@@ -196,7 +191,7 @@ submodule with the `--init` option.
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
@@ -209,7 +204,7 @@ summary::
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:
@@ -230,7 +225,7 @@ 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.
-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
@@ -244,6 +239,20 @@ sync::
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::
@@ -258,7 +267,9 @@ OPTIONS
--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::
@@ -384,6 +395,12 @@ for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully.
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.