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.txt159
1 files changed, 132 insertions, 27 deletions
diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index b72964947a..2c25916f8f 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -9,16 +9,18 @@ git-submodule - Initialize, update or inspect submodules
SYNOPSIS
--------
[verse]
-'git submodule' [--quiet] add [-b branch] [-f|--force]
- [--reference <repository>] [--] <repository> [<path>]
+'git submodule' [--quiet] add [-b <branch>] [-f|--force] [--name <name>]
+ [--reference <repository>] [--depth <depth>] [--] <repository> [<path>]
'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...]
'git submodule' [--quiet] init [--] [<path>...]
-'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--rebase]
- [--reference <repository>] [--merge] [--recursive] [--] [<path>...]
+'git submodule' [--quiet] deinit [-f|--force] [--] <path>...
+'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch]
+ [-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
@@ -43,9 +45,9 @@ if you choose to go that route.
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` 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.
+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').
@@ -75,6 +77,8 @@ 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 ./
@@ -91,7 +95,7 @@ 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
+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.
@@ -112,7 +116,6 @@ status::
initialized, `+` if the currently checked out submodule commit
does not match the SHA-1 found in the index of the containing
repository and `U` if the submodule has merge conflicts.
- This command is the default command for 'git submodule'.
+
If `--recursive` is specified, this command will recurse into nested
submodules, and show their status as well.
@@ -123,8 +126,10 @@ 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::
- Initialize the submodules, i.e. register each submodule name
- and url found in .gitmodules into .git/config.
+ 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`.
@@ -135,24 +140,65 @@ init::
the explicit 'init' step if you do not intend to customize
any submodule locations.
+deinit::
+ 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`
+ 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 work tree anymore. If
+ you really want to remove a submodule from the repository and commit
+ that use linkgit:git-rm[1] instead.
++
+If `--force` is specified, the submodule's work tree will be removed even if
+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`.
+
+--
+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 the configuration key `submodule.$name.update` is set to `none` the
-submodule with name `$name` will not be updated by default. This can be
-overriden by adding `--checkout` to the command.
-
+--
summary::
Show commit summary between the given commit (defaults to HEAD) and
working tree/index. For a submodule in question, a series of commits
@@ -190,7 +236,7 @@ commit for each submodule.
sync::
Synchronizes submodules' remote URL configuration setting
to the value specified in .gitmodules. It will only affect those
- submodules which already have an url entry in .git/config (that is the
+ 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
repositories accordingly.
@@ -207,13 +253,21 @@ OPTIONS
-b::
--branch::
Branch of repository to add as submodule.
+ The name of the branch is recorded as `submodule.<name>.branch` in
+ `.gitmodules` for `update --remote`.
-f::
--force::
- This option is only valid for add and update commands.
+ This option is only valid for add, deinit and update commands.
When running add, allow adding an otherwise ignored submodule path.
- When running update, throw away local changes in submodules when
- switching to a different commit.
+ When running deinit the submodule work trees will be removed even if
+ they contain local changes.
+ 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
@@ -233,11 +287,51 @@ OPTIONS
(the default). This limit only applies to modified submodules. The
size is always limited to 1 for added/deleted/typechanged submodules.
+--remote::
+ This option is only valid for the update command. Instead of using
+ the superproject's recorded SHA-1 to update the submodule, use the
+ status of the submodule's remote-tracking branch. The remote used
+ is branch's remote (`branch.<name>.remote`), defaulting to `origin`.
+ The remote branch used defaults to `master`, but the branch name may
+ be overridden by setting the `submodule.<name>.branch` option in
+ either `.gitmodules` or `.git/config` (with `.git/config` taking
+ precedence).
++
+This works for any of the supported update procedures (`--checkout`,
+`--rebase`, etc.). The only change is the source of the target SHA-1.
+For example, `submodule update --remote --merge` will merge upstream
+submodule changes into the submodules, while `submodule update
+--merge` will merge superproject gitlink changes into the submodules.
++
+In order to ensure a current tracking branch state, `update --remote`
+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
@@ -262,6 +356,11 @@ OPTIONS
Initialize all submodules for which "git submodule init" has not been
called so far before updating.
+--name::
+ This option is only valid for the add command. It sets the submodule's
+ name to the given string instead of defaulting to its path. The name
+ must be valid as a directory name and may not end with a '/'.
+
--reference <repository>::
This option is only valid for add and update commands. These
commands sometimes need to clone a remote repository. In this case,
@@ -276,6 +375,12 @@ for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully.
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.