submodule: improve documentation of update subcommand

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 <gitster@pobox.com>
Helped-by: Jens Lehmann <Jens.Lehmann@web.de>
Signed-off-by: Michal Sojka <sojkam1@fel.cvut.cz>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/config.txt b/Documentation/config.txt
index c08286e968ad057c288b72f77e877f42a640ae5f..1c0bae00524bc6c4405f2b2a3fc183c2c70f8493 100644 (file)
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -2303,12 +2303,16 @@ status.submodulesummary::
 
 submodule.<name>.path::
 submodule.<name>.url::
 
 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::
 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
 
 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 8e6af65da0e0f234315c42391a8bab42fc39abb6..2c25916f8f7cd0a7ca69c3b980d85251a29b681b 100644 (file)
--- 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::
 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 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 `--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
 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 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
 
 --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
        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.
 
        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 f6c0dfd0290a9b2174c645630998d2a62cdb9f5e..ac70eca321cd1747e2916646c691ac18cb4dbd97 100644 (file)
--- 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::
 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.
 
 submodule.<name>.branch::
        A remote branch name for tracking updates in the upstream submodule.