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.
This patch fixes all these problems. Now, submodule.$name.update is
fully documented in git-submodule.txt and the other files just refer to
it. This is based on discussion between Junio C Hamano, Jens Lehmann and
myself.
Signed-off-by: Michal Sojka <sojk...@fel.cvut.cz>
---
Documentation/config.txt | 15 +++++++----
Documentation/git-submodule.txt | 58 +++++++++++++++++++++++++++++------------
Documentation/gitmodules.txt | 18 +++++--------
3 files changed, 57 insertions(+), 34 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..72c6fb2 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -154,14 +154,36 @@ 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` in .git/config:
+
+ checkout;; the new 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'.
+
+ 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
@@ -170,10 +192,11 @@ 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.
+If `--force` is specified and the checkout method of update is used, 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
@@ -238,10 +261,11 @@ 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 and the checkout method is used, 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 +326,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`.
+ other value 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..a51183c 100644
--- a/Documentation/gitmodules.txt
+++ b/Documentation/gitmodules.txt
@@ -38,18 +38,12 @@ 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 what to do when the submodule is updated by the
+ superproject. This is only used by `git submodule init` to
+ initialize the variable of the same name in .git/config.
+ Allowed values here are 'checkout', 'rebase', 'merge' or
+ 'none'. See description of 'update' command in
+ linkgit:git-submodule[1] for their meaning.
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
