[PATCH] gitsubmodules: add '--recurse-submodules' for 'ls-files'

Philippe Blain via GitGitGadget· Oct 4, 2020, 01:17 UTC · lore

From: Philippe Blain <levraiphilippeblain@gmail.com>

`git ls-files` was never taught to respect the `submodule.recurse` configuration variable, and it seems it is too late now to change that [1], but still the command is mentioned in 'gitsubmodules(7)' as if it does respect that config.

Adjust the call in 'gitsubmodules(7)' by adding the '--recurse-submodules' flag.

While at it, uniformize the capitalization in that file, and use backticks instead of quotes for Git commands and configuration variables.

[1] https://lore.kernel.org/git/pull.732.git.1599707259907.gitgitgadget@gmail.com/T/#u

Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
    gitsubmodules: add '--recurse-submodules' for 'ls-files'

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-861%2Fphil-blain%2Fgitsubmodules-ls-files-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-861/phil-blain/gitsubmodules-ls-files-v1
Pull-Request: https://github.com/git/git/pull/861

 Documentation/gitsubmodules.txt | 23 +++++++++++++----------
 1 file changed, 13 insertions(+), 10 deletions(-)

Show changes to Documentation/gitsubmodules.txt +13 −10

diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt
index f9f4e65c9e..891c8da4fd 100644
--- a/Documentation/gitsubmodules.txt
+++ b/Documentation/gitsubmodules.txt
@@ -225,10 +225,10 @@ presence of the .url field.
 Workflow for a third party library
 ----------------------------------
 
-  # add a submodule
+  # Add a submodule
   git submodule add <url> <path>
 
-  # occasionally update the submodule to a new version:
+  # Occasionally update the submodule to a new version:
   git -C <path> checkout <new version>
   git add <path>
   git commit -m "update submodule to new version"
@@ -246,20 +246,23 @@ Workflow for an artificially split repo
   # regular commands recurse into submodules by default
   git config --global submodule.recurse true
 
-  # Unlike the other commands below clone still needs
+  # Unlike most other commands below, clone still needs
   # its own recurse flag:
   git clone --recurse <URL> <directory>
   cd <directory>
 
   # Get to know the code:
   git grep foo
-  git ls-files
+  git ls-files --recurse-submodules
+
+[NOTE]
+`git ls-files` also requires its own `--recurse-submodules` flag.
 
   # Get new code
   git fetch
   git pull --rebase
 
-  # change worktree
+  # Change worktree
   git checkout
   git reset
 
@@ -267,12 +270,12 @@ Implementation details
 ----------------------
 
 When cloning or pulling a repository containing submodules the submodules
-will not be checked out by default; You can instruct 'clone' to recurse
-into submodules. The 'init' and 'update' subcommands of 'git submodule'
+will not be checked out by default; you can instruct `clone` to recurse
+into submodules. The `init` and `update` subcommands of `git submodule`
 will maintain submodules checked out and at an appropriate revision in
-your working tree. Alternatively you can set 'submodule.recurse' to have
-'checkout' recursing into submodules (note that 'submodule.recurse' also
-affects other git commands, see linkgit:git-config[1] for a complete list).
+your working tree. Alternatively you can set `submodule.recurse` to have
+`checkout` recursing into submodules (note that `submodule.recurse` also
+affects other Git commands, see linkgit:git-config[1] for a complete list).
 
 
 SEE ALSO

base-commit: 306ee63a703ad67c54ba1209dc11dd9ea500dc1f

-- 
gitgitgadget

Junio C Hamano· Oct 4, 2020, 19:55 UTC · re: Philippe Blain via GitGitGadget · lore

Re: [PATCH] gitsubmodules: add '--recurse-submodules' for 'ls-files'

"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 17 quoted lines

> @@ -246,20 +246,23 @@ Workflow for an artificially split repo
>    # regular commands recurse into submodules by default
>    git config --global submodule.recurse true
>  
> -  # Unlike the other commands below clone still needs
> +  # Unlike most other commands below, clone still needs
>    # its own recurse flag:
>    git clone --recurse <URL> <directory>
>    cd <directory>
>  
>    # Get to know the code:
>    git grep foo
> -  git ls-files
> +  git ls-files --recurse-submodules
> +
> +[NOTE]
> +`git ls-files` also requires its own `--recurse-submodules` flag.

Makes sense.  Thanks, will queue.

patchgitsubmodules: add '--recurse-submodules' for 'ls-files'