Re: [PATCH v2 2/2] sparse-checkout: document interactions with submodules

[Elijah Newren <newren@gmail.com>]

On Fri, Dec 27, 2019 at 10:47 AM Derrick Stolee via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> From: Derrick Stolee <dstolee@microsoft.com>
>
> Junio asked what the behavior is between the sparse-checkout feature
> and the submodule feature.

Does this first sentence help future readers?  It is what spurred you
to write the documentation, but it seems like something that could
just be left out.

> The sparse-checkout builtin has not changed
> the way these features interact, but we may as well document it in
> the builtin docs.
>
> Using 'git submodule (init|deinit)' a user can select a subset of
> submodules to populate. This behaves very similar to the sparse-checkout
> feature, but those directories contain their own .git directory
> including an object database and ref space. To have the sparse-checkout
> file also determine if those files should exist would easily cause
> problems. Therefore, keeping these features independent in this way
> is the best way forward.
>
> Also create a test that demonstrates this behavior to make sure
> it doesn't change as the sparse-checkout feature evolves.
>
> Reported-by: Junio C Hamano <gitster@pobox.com>
> Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
> ---
>  Documentation/git-sparse-checkout.txt | 10 ++++++++++
>  t/t1091-sparse-checkout-builtin.sh    | 28 +++++++++++++++++++++++++++
>  2 files changed, 38 insertions(+)
>
> diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
> index dcca9ee826..2b7aaa0310 100644
> --- a/Documentation/git-sparse-checkout.txt
> +++ b/Documentation/git-sparse-checkout.txt
> @@ -164,6 +164,16 @@ case-insensitive check. This corrects for case mismatched filenames in the
>  'git sparse-checkout set' command to reflect the expected cone in the working
>  directory.
>
> +
> +SUBMODULES
> +----------
> +
> +If your repository contains one or more submodules, then those submodules will
> +appear based on which you initialized with the `git submodule` command. If
> +your sparse-checkout patterns exclude an initialized submodule, then that
> +submodule will still appear in your working directory.
> +
> +
>  SEE ALSO
>  --------
>
> diff --git a/t/t1091-sparse-checkout-builtin.sh b/t/t1091-sparse-checkout-builtin.sh
> index 37f6d8fa90..5572beeeca 100755
> --- a/t/t1091-sparse-checkout-builtin.sh
> +++ b/t/t1091-sparse-checkout-builtin.sh
> @@ -340,4 +340,32 @@ test_expect_success 'cone mode: set with core.ignoreCase=true' '
>         test_cmp expect dir
>  '
>
> +test_expect_success 'interaction with submodules' '
> +       git clone repo super &&
> +       (
> +               cd super &&
> +               mkdir modules &&
> +               git submodule add ../repo modules/child &&
> +               git add . &&
> +               git commit -m "add submodule" &&
> +               git sparse-checkout init --cone &&
> +               git sparse-checkout set folder1
> +       ) &&
> +       list_files super >dir &&
> +       cat >expect <<-EOF &&
> +               a
> +               folder1
> +               modules
> +       EOF
> +       test_cmp expect dir &&
> +       list_files super/modules/child >dir &&
> +       cat >expect <<-EOF &&
> +               a
> +               deep
> +               folder1
> +               folder2
> +       EOF
> +       test_cmp expect dir
> +'
> +
>  test_done
> --

I read over the rest, and not being a submodule user I'm not sure what
I'd expect.  But it certainly seems reasonable to document how these
features interact and that you haven't made any modifications in the
area.