Improve documentation concerning the status.submodulesummary setting

'git status' and 'git commit' can be told to also show the output of "git
submodule summary" by setting the "status.submodulesummary" config option.
But status and commit also honor the "diff.ignoreSubmodules" and the
"submodule.<name>.ignore" settings, which then disable the summary partly
or completely. This - and the fact that the last two settings do not
affect the "git submodule" commands at all - is not well documented.

Extend the documentation in those places where "status.submodulesummary",
"diff.ignoreSubmodules" and "submodule.<name>.ignore" are described to
better explain these dependencies.

Thanks-to: Matthieu Moy <Matthieu.Moy@grenoble-inp.fr>
Signed-off-by: Jens Lehmann <Jens.Lehmann@web.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/config.txt b/Documentation/config.txt
index ec57a15ac5da284f35ced4441e2315fec9b05e2d..424aa51edbffaf23026926dbe44a62a3fab6ac9b 100644 (file)
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -2142,7 +2142,14 @@ status.submodulesummary::
        If this is set to a non zero number or true (identical to -1 or an
        unlimited number), the submodule summary will be enabled and a
        summary of commits for modified submodules will be shown (see
-       --summary-limit option of linkgit:git-submodule[1]).
+       --summary-limit option of linkgit:git-submodule[1]). Please note
+       that the summary output command will be suppressed for all
+       submodules when `diff.ignoreSubmodules` is set to 'all' or only
+       for those submodules where `submodule.<name>.ignore=all`. To
+       also view the summary for ignored submodules you can either use
+       the --ignore-submodules=dirty command line option or the 'git
+       submodule summary' command, which shows a similar output but does
+       not honor these settings.
 
 submodule.<name>.path::
 submodule.<name>.url::
@@ -2177,7 +2184,8 @@ submodule.<name>.ignore::
        submodules that have untracked files in their work tree as changed.
        This setting overrides any setting made in .gitmodules for this submodule,
        both settings can be overridden on the command line by using the
-       "--ignore-submodules" option.
+       "--ignore-submodules" option. The 'git submodule' commands are not
+       affected by this setting.
 
 tar.umask::
        This variable can be used to restrict the permission bits of

diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt
index ac770502553d9b4d3d1176f63ad01791736602a8..223b9310df0990accdb0d43b096bd52856f56bef 100644 (file)
--- a/Documentation/diff-config.txt
+++ b/Documentation/diff-config.txt
@@ -73,7 +73,11 @@ diff.ignoreSubmodules::
        Sets the default value of --ignore-submodules. Note that this
        affects only 'git diff' Porcelain, and not lower level 'diff'
        commands such as 'git diff-files'. 'git checkout' also honors
-       this setting when reporting uncommitted changes.
+       this setting when reporting uncommitted changes. Setting it to
+       'all' disables the submodule summary normally shown by 'git commit'
+       and 'git status' when 'status.submodulesummary' is set unless it is
+       overridden by using the --ignore-submodules command line option.
+       The 'git submodule' commands are not affected by this setting.
 
 diff.mnemonicprefix::
        If set, 'git diff' uses a prefix pair that is different from the

diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 9046df98a03fe11a203f06d79be0128309a201c5..a4acaa038cd4255c91df1a03c16c6a396f0c1219 100644 (file)
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -210,7 +210,13 @@ directory.
 If `status.submodulesummary` is set to a non zero number or true (identical
 to -1 or an unlimited number), the submodule summary will be enabled for
 the long format and a summary of commits for modified submodules will be
-shown (see --summary-limit option of linkgit:git-submodule[1]).
+shown (see --summary-limit option of linkgit:git-submodule[1]). Please note
+that the summary output from the status command will be suppressed for all
+submodules when `diff.ignoreSubmodules` is set to 'all' or only for those
+submodules where `submodule.<name>.ignore=all`. To also view the summary for
+ignored submodules you can either use the --ignore-submodules=dirty command
+line option or the 'git submodule summary' command, which shows a similar
+output but does not honor these settings.
 
 SEE ALSO
 --------

diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt
index 6a1ca4abad73631c13a4d074deb11102289a0d43..f7be93f6317c7170af642c43d107a6617eb33a18 100644 (file)
--- a/Documentation/gitmodules.txt
+++ b/Documentation/gitmodules.txt
@@ -75,7 +75,8 @@ submodule.<name>.ignore::
        the superproject, the setting there will override the one found in
        .gitmodules.
        Both settings can be overridden on the command line by using the
-       "--ignore-submodule" option.
+       "--ignore-submodule" option. The 'git submodule' commands are not
+       affected by this setting.
 
 
 EXAMPLES