Re: [PATCH v2 4/5] Update documentation related to sparsity and the skip-worktree bit

[Elijah Newren <newren@gmail.com>]

On Wed, Feb 16, 2022 at 1:23 AM Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
>
> On Fri, Jan 14 2022, Elijah Newren via GitGitGadget wrote:
>
> > From: Elijah Newren <newren@gmail.com>
> >
> > Make several small updates, to address a few documentation issues
> > I spotted:
> >   * sparse-checkout focused on "patterns" even though the inputs (and
> >     outputs in the case of `list`) are directories in cone-mode
> >   * The description section of the sparse-checkout documentation
> >     was a bit sparse (no pun intended), and focused more on internal
> >     mechanics rather than end user usage.  This made sense in the
> >     early days when the command was even more experimental, but let's
> >     adjust a bit to try to make it more approachable to end users who
> >     may want to consider using it.  Keep the scary backward
> >     compatibility warning, though; we're still hard at work trying to
> >     fix up commands to behave reasonably in sparse checkouts.
> >   * both read-tree and update-index tried to describe how to use the
> >     skip-worktree bit, but both predated the sparse-checkout command.
> >     The sparse-checkout command is a far easier mechanism to use and
> >     for users trying to reduce the size of their working tree, we
> >     should recommend users to look at it instead.
> >   * The update-index documentation pointed out that assume-unchanged
> >     and skip-worktree sounded similar but had different purposes.
> >     However, it made no attempt to explain the differences, only to
> >     point out that they were different.  Explain the differences.
> >   * The update-index documentation focused much more on (internal?)
> >     implementation details than on end-user usage.  Try to explain
> >     its purpose better for users of update-index, rather than
> >     fellow developers trying to work with the SKIP_WORKTREE bit.
> >   * Clarify that when core.sparseCheckout=true, we treat a file's
> >     presence in the working tree as being an override to the
> >     SKIP_WORKTREE bit (i.e. in sparse checkouts when the file is
> >     present we ignore the SKIP_WORKTREE bit).
> >
> > Note that this commit, like many touching documentation, is best viewed
> > with the `--color-words` option to diff/log.
> >
> > Signed-off-by: Elijah Newren <newren@gmail.com>
> > ---
> >  Documentation/git-read-tree.txt       | 12 +++--
> >  Documentation/git-sparse-checkout.txt | 76 ++++++++++++++++-----------
> >  Documentation/git-update-index.txt    | 57 +++++++++++++++-----
> >  3 files changed, 98 insertions(+), 47 deletions(-)
> >
> > diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
> > index 8c3aceb8324..99bb387134d 100644
> > --- a/Documentation/git-read-tree.txt
> > +++ b/Documentation/git-read-tree.txt
> > @@ -375,9 +375,14 @@ have finished your work-in-progress), attempt the merge again.
> >  SPARSE CHECKOUT
> >  ---------------
> >
> > +Note: The `update-index` and `read-tree` primitives for supporting the
> > +skip-worktree bit predated the introduction of
> > +linkgit:git-sparse-checkout[1].  Users are encouraged to use
> > +`sparse-checkout` in preference to these low-level primitives.
>
> I was honestly a bit confused about whether we were really referring to
> the git-update-index and git-read-tree commands here, or some
> sparse-checkout (re-)usage of the same as "primitives"

Neither, really.

>, but reading it
> again & the commit message we're just talking about the commands here.

I was trying to talk about just the small building blocks found in
git-update-index and git-read-tree commands that relate to sparse
checkouts (i.e. the --[no-]skip-worktree and
--[no-]ignore-skip-worktree-entries options to git-update-index, and
the ability to update the working tree according to
$GITDIR/info/sprse-checkout buried in `git read-tree -mu HEAD`).

> So this really just wants to assure readers that they're advised to use
> the shiny porcelain command instead of the plumbing.
>
> I think we should refer to these as e.g. "linkgit:git-update-index[1]"
> not "`update-index`" here, and call them e.g. "plumbing commands"
> instead of "primitives" here, which will address that (the reader
> wonders "what's a primitive?").

Perhaps:

Note: The skip-worktree capabilities in linkgit:git-update-index[1]
and `read-tree` predated the introduction of
linkgit:git-sparse-checkout[1].  Users are encouraged to use the
`sparse-checkout` command in preference to these plumbing commands for
sparse-checkout/skip-worktree related needs.

?

>
> > -Initialize and modify the sparse-checkout configuration, which reduces
> > -the checkout to a set of paths given by a list of patterns.
> > +This command is used to create sparse checkouts, which means that it
> > +changes the working tree from having all tracked files present, to only
> > +have a subset of them.  It can also switch which subset of files are
> > +present, or undo and go back to having all tracked files present in the
> > +working copy.
>
> In terms of prose I think it's preferred to keep matter-of-fact "Slices
> and dices apples, making them easier to eat" instead of "This command
> slices and dices apples, which means that it's easier to eat them".
>
> I've forgotten what the linguisting term for that is, but it's more
> consistent with our docs, and makes for easier reading.

So, s/means that it changes/change/ ?

> > +The subset of files is chosen by providing a list of directories in
> > +cone mode (which is recommended), or by providing a list of patterns
> > +in non-cone mode.
>
> As someone with light familiarity with sparse-checkout:
>
> I'm still not sure if this is telling me that it's preferred to list
> directories v.s. patterns, or if it's telling me it's better to operate
> in "cone mode" v.s. "non-cone mode", or some combination of the two.
>
> IOW I think peeling out that "(which is recommended)" and making it
> clearly refer to which (or both?) of the two we're talking about would
> be much better.

Much easier to fix when I resubmit the patch to change the default for
sparse-checkout to cone mode (i.e. when I resubmit
https://lore.kernel.org/git/e30119b96dfaf9fdb82039cab84f8b81caacc1de.1644712798.git.gitgitgadget@gmail.com/).
I can include the above changes too.

> > +When in a sparse-checkout, other Git commands behave a bit differently.
> > +For example, switching branches will not update paths outside the
> > +sparse-checkout directories/patterns, and `git commit -a` will not record
> > +paths outside the sparse-checkout directories/patterns as deleted.
>
> (I didn't read through the rest in any detail)