On Wed, Feb 16, 2022 at 1:23 AM Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> wrote: > > On Fri, Jan 14 2022, Elijah Newren via GitGitGadget wrote: > > > From: Elijah Newren <newren@xxxxxxxxx> > > > > 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@xxxxxxxxx> > > --- > > 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@xxxxxxxxx/). 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)
