The documentation of 'git submodule update' has several problems:
1) It mentions that value 'none' of submodule.$name.update can be
overridden by --checkout, but other combinations of configuration
values and command line options are not mentioned.
2) The documentation of submodule.$name.update is scattered across three
places, which is confusing.
3) The documentation of submodule.$name.update in gitmodules.txt is
incorrect, because the code always uses the value from .git/config
and never from .gitmodules.
4) Documentation of --force was incomplete, because it is only effective
in case of checkout method of update.
Fix all these problems by documenting submodule.*.update in
git-submodule.txt and make everybody else refer to it.
Helped-by: Junio C Hamano <gits...@pobox.com>
Helped-by: Jens Lehmann <jens.lehm...@web.de>
Signed-off-by: Michal Sojka <sojk...@fel.cvut.cz>
---
Documentation/config.txt | 15 ++++++----
Documentation/git-submodule.txt | 66 ++++++++++++++++++++++++++++-------------
Documentation/gitmodules.txt | 21 ++++++-------
3 files changed, 65 insertions(+), 37 deletions(-)
diff --git a/Documentation/config.txt b/Documentation/config.txt
index ae6791d..fb2ae37 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -2411,12 +2411,17 @@ 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';
+ 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.
+
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 updating strategy 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
diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 8e6af65..067d616 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -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 methods 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 recoded 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 method),
+ 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.
diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt
index f6c0dfd..7e8fb87 100644
--- a/Documentation/gitmodules.txt
+++ b/Documentation/gitmodules.txt
@@ -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 method 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.
--
2.1.4
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
