On Tue, Aug 20, 2019 at 8:13 AM Derrick Stolee via GitGitGadget <gitgitgadget@xxxxxxxxx> 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.
