Re: [PATCH 1/9] sparse-checkout: create builtin with 'list' subcommand

[Elijah Newren <newren@gmail.com>]

On Tue, Aug 20, 2019 at 8:13 AM Derrick Stolee via GitGitGadget
<gitgitgadget@gmail.com> wrote:
<snip>
> The documentation provided is adapted from the "git read-tree"
> documentation with a few edits for clarity in the new context.
> Extra sections are added to hint toward a future change to
> a moer restricted pattern set.

s/moer/more/

<snip>
> +"Sparse checkout" allows populating the working directory sparsely.
> +It uses the skip-worktree bit (see linkgit:git-update-index[1]) to tell
> +Git whether a file in the working directory is worth looking at. If
> +the skip-worktree bit is set, then the file is ignored in the working
> +directory. Git will not populate the contents of those files, which
> +makes a sparse checkout helpful when working in a repository with many
> +files, but only a few are important to the current user.
> +
> +The `$GIT_DIR/info/sparse-checkout` file is used to define the
> +skip-worktree reference bitmap. When Git updates the working
> +directory, it resets the skip-worktree bit in the index based on this
> +file. If an entry
> +matches a pattern in this file, skip-worktree will not be set on
> +that entry. Otherwise, skip-worktree will be set.
> +
> +Then it compares the new skip-worktree value with the previous one. If
> +skip-worktree turns from set to unset, it will add the corresponding
> +file back. If it turns from unset to set, that file will be removed.

I had to read this twice for it to make sense.  Not sure I have a real
good suggestion here, the name "skip-worktree" instead of e.g
"wanted-in-worktree" just naturally leads us into sentences with one
negation automatically and we sometimes have to add more.

Maybe just replace the last two paragraphs with:

The `$GIT_DIR/info/sparse-checkout` file is used to define the
skip-worktree reference bitmap. When Git updates the working
directory, it updates the skip-worktree bits in the index based on this
file and removes or restores files in the working copy to match.

> +
> +## FULL PATTERN SET
> +
> +By default, the sparse-checkout file uses the same syntax as `.gitignore`
> +files.
> +
> +While `$GIT_DIR/info/sparse-checkout` is usually used to specify what
> +files are in, you can also specify what files are _not_ in, using
> +negate patterns. For example, to remove the file `unwanted`:

s/in/included/?

> +Another tricky thing is fully repopulating the working directory when you
> +no longer want sparse checkout. You cannot just disable "sparse
> +checkout" because skip-worktree bits are still in the index and your working
> +directory is still sparsely populated. You should re-populate the working
> +directory with the `$GIT_DIR/info/sparse-checkout` file content as
> +follows:
> +
> +----------------
> +/*
> +----------------

Can we just get rid of this part of the documentation, since there
will be a sparse-checkout command to disable/undo/reset?  However, it
could be useful to mention cases when disabling/undoing/resetting a
sparse-checkout won't work, if there are some.  For example, with the
previous read-tree implementation, you could not undo the sparse
checkout if the index had any unstaged entries, and you couldn't undo
it if there were any files present that corresponding to the sparse
patterns (for fear they'd be overwritten -- however, every once in a
while someone tried to desparsify, it failed e.g. due to the disk
becoming full, and then after freeing up space there were zillions of
files that exactly matched what de-sparsifying would have put there
but the command wanted the user to manually delete them first.)

> +
> +Then you can disable sparse checkout. Sparse checkout support in 'git
> +read-tree' and similar commands is disabled by default. You need to
> +set `core.sparseCheckout` to `true` in order to have sparse checkout
> +support.

...and get rid of this paragraph because I'd expect git
sparse-checkout to come with a subcommand (init/add/whatever) to set
this for the user?  Unless maybe you want to add some words about why
the command sets core.sparseCheckout...and related workspace related
stuff as we talked about elsewhere.

> +test_expect_success 'git sparse-checkout list (empty)' '
> +       git -C repo sparse-checkout list >list 2>err &&
> +       test_line_count = 0 list &&
> +       test_i18ngrep "failed to parse sparse-checkout file; it may not exist" err

Is that the error we want, rather than something like "This worktree
is not sparse (no sparse-checkout file exists and core.sparseCheckout
is false"?

> +'
> +
> +test_expect_success 'git sparse-checkout list (populated)' '
> +       test_when_finished rm -f repo/.git/info/sparse-checkout &&
> +       cat >repo/.git/info/sparse-checkout <<-EOF &&
> +               /folder1/*
> +               /deep/
> +               **/a
> +               !*bin*
> +       EOF
> +       git -C repo sparse-checkout list >list &&
> +       cat >expect <<-EOF &&
> +               /folder1/*
> +               /deep/
> +               **/a
> +               !*bin*
> +       EOF
> +       test_cmp expect list

I have a `./sparsify --stats` that reports
   You are now in a sparse checkout with only 3499 of the 53625 files.
or
  You are not in a sparse checkout.

and I have a --info option that reports both the stats and the list of
sparse paths similar to this sparse-checkout list command.  The stats
aren't important, I guess, but seem nice for the user.  I don't know
if you want to include anything like that in this or another command,
but just thought I'd mention it.