mirror of
https://github.com/git/git
synced 2024-08-27 11:39:22 +00:00
Merge branch 'ms/submodule-update-config-doc' into maint
The interaction between "git submodule update" and the submodule.*.update configuration was not clearly documented. * ms/submodule-update-config-doc: submodule: improve documentation of update subcommand
This commit is contained in:
commit
30a52c1dcb
|
@ -2408,12 +2408,16 @@ status.submodulesummary::
|
|||
|
||||
submodule.<name>.path::
|
||||
submodule.<name>.url::
|
||||
The path within this project and URL for a submodule. These
|
||||
variables are initially populated by 'git submodule init'. See
|
||||
linkgit:git-submodule[1] and linkgit:gitmodules[5] for
|
||||
details.
|
||||
|
||||
submodule.<name>.update::
|
||||
The path within this project, URL, and the updating strategy
|
||||
for a submodule. These variables are initially populated
|
||||
by 'git submodule init'; edit them to override the
|
||||
URL and other values found in the `.gitmodules` file. See
|
||||
linkgit:git-submodule[1] and linkgit:gitmodules[5] for details.
|
||||
The default update procedure for a submodule. This variable
|
||||
is populated by `git submodule init` from the
|
||||
linkgit:gitmodules[5] file. See description of 'update'
|
||||
command in linkgit:git-submodule[1].
|
||||
|
||||
submodule.<name>.branch::
|
||||
The remote branch name for a submodule, used by `git submodule
|
||||
|
|
|
@ -154,27 +154,51 @@ 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`. `none` can be overridden by specifying
|
||||
`--checkout`. Setting the key `submodule.$name.update` to `!command`
|
||||
will cause `command` to be run. `command` can be any arbitrary shell
|
||||
command that takes a single argument, namely the sha1 to update to.
|
||||
+
|
||||
--
|
||||
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 `--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.
|
||||
|
||||
--
|
||||
summary::
|
||||
Show commit summary between the given commit (defaults to HEAD) and
|
||||
working tree/index. For a submodule in question, a series of commits
|
||||
|
@ -238,10 +262,12 @@ OPTIONS
|
|||
When running add, allow adding an otherwise ignored submodule path.
|
||||
When running deinit the submodule work trees will be removed even if
|
||||
they contain local changes.
|
||||
When running update, 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.
|
||||
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
|
||||
|
@ -302,7 +328,7 @@ the submodule itself.
|
|||
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
|
||||
`merge`, `rebase` or `none`.
|
||||
a value other than `checkout`.
|
||||
If the key `submodule.$name.update` is either not explicitly set or
|
||||
set to `checkout`, this option is implicit.
|
||||
|
||||
|
|
|
@ -38,18 +38,15 @@ submodule.<name>.url::
|
|||
In addition, there are a number of optional keys:
|
||||
|
||||
submodule.<name>.update::
|
||||
Defines what to do when the submodule is updated by the superproject.
|
||||
If 'checkout' (the default), the new commit specified in the
|
||||
superproject will be checked out in the submodule on a detached HEAD.
|
||||
If 'rebase', the current branch of the submodule will be rebased onto
|
||||
the commit specified in the superproject. If 'merge', the commit
|
||||
specified in the superproject will be merged into the current branch
|
||||
in the submodule.
|
||||
If 'none', the submodule with name `$name` will not be updated
|
||||
by default.
|
||||
|
||||
This config option is overridden if 'git submodule update' is given
|
||||
the '--merge', '--rebase' or '--checkout' options.
|
||||
Defines the default update procedure for the named submodule,
|
||||
i.e. how the submodule is updated by "git submodule update"
|
||||
command in the superproject. This is only used by `git
|
||||
submodule init` to initialize the configuration variable of
|
||||
the same name. Allowed values here are 'checkout', 'rebase',
|
||||
'merge' or 'none'. See description of 'update' command in
|
||||
linkgit:git-submodule[1] for their meaning. Note that the
|
||||
'!command' form is intentionally ignored here for security
|
||||
reasons.
|
||||
|
||||
submodule.<name>.branch::
|
||||
A remote branch name for tracking updates in the upstream submodule.
|
||||
|
|
Loading…
Reference in a new issue