git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
From: Elijah Newren <newren@gmail.com>
To: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
Cc: Elijah Newren via GitGitGadget <gitgitgadget@gmail.com>,
	Git Mailing List <git@vger.kernel.org>,
	Victoria Dye <vdye@github.com>, Derrick Stolee <stolee@gmail.com>,
	Lessley Dennington <lessleydennington@gmail.com>
Subject: Re: [PATCH v2 4/5] Update documentation related to sparsity and the skip-worktree bit
Date: Wed, 16 Feb 2022 08:21:31 -0800	[thread overview]
Message-ID: <CABPp-BF2d81f0va7x7fpEAFqJtjBgEr-UBY4QCAxrnjoFmdZ3g@mail.gmail.com> (raw)
In-Reply-To: <220216.86k0dvupv7.gmgdl@evledraar.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)

  reply	other threads:[~2022-02-16 16:21 UTC|newest]

Thread overview: 30+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-01-13 16:43 [PATCH 0/5] Remove the present-despite-SKIP_WORKTREE class of bugs (for sparse-checkouts) Elijah Newren via GitGitGadget
2022-01-13 16:43 ` [PATCH 1/5] t1011: add testcase demonstrating accidental loss of user modifications Elijah Newren via GitGitGadget
2022-01-13 16:43 ` [PATCH 2/5] unpack-trees: fix accidental loss of user changes Elijah Newren via GitGitGadget
2022-01-13 16:43 ` [PATCH 3/5] repo_read_index: clear SKIP_WORKTREE bit from files present in worktree Elijah Newren via GitGitGadget
2022-01-13 16:43 ` [PATCH 4/5] Update documentation related to sparsity and the skip-worktree bit Elijah Newren via GitGitGadget
2022-01-13 16:43 ` [PATCH 5/5] Accelerate clear_skip_worktree_from_present_files() by caching Elijah Newren via GitGitGadget
2022-01-13 23:35   ` Elijah Newren
2022-01-14 15:59 ` [PATCH v2 0/5] Remove the present-despite-SKIP_WORKTREE class of bugs (for sparse-checkouts) Elijah Newren via GitGitGadget
2022-01-14 15:59   ` [PATCH v2 1/5] t1011: add testcase demonstrating accidental loss of user modifications Elijah Newren via GitGitGadget
2022-02-16  8:51     ` Ævar Arnfjörð Bjarmason
2022-02-16 16:02       ` Elijah Newren
2022-01-14 15:59   ` [PATCH v2 2/5] unpack-trees: fix accidental loss of user changes Elijah Newren via GitGitGadget
2022-01-14 15:59   ` [PATCH v2 3/5] repo_read_index: clear SKIP_WORKTREE bit from files present in worktree Elijah Newren via GitGitGadget
2022-02-16  8:57     ` Ævar Arnfjörð Bjarmason
2022-02-16 16:08       ` Elijah Newren
2022-02-19  1:06     ` Jonathan Nieder
2022-02-19 16:42       ` Elijah Newren
2022-02-19 18:14         ` Jonathan Nieder
2022-02-20  5:28           ` Elijah Newren
2022-02-20 16:56       ` Derrick Stolee
2022-02-22 23:17         ` Jonathan Nieder
2022-01-14 15:59   ` [PATCH v2 4/5] Update documentation related to sparsity and the skip-worktree bit Elijah Newren via GitGitGadget
2022-02-16  9:15     ` Ævar Arnfjörð Bjarmason
2022-02-16 16:21       ` Elijah Newren [this message]
2022-01-14 15:59   ` [PATCH v2 5/5] Accelerate clear_skip_worktree_from_present_files() by caching Elijah Newren via GitGitGadget
2022-01-15  1:39     ` Victoria Dye
2022-02-16  9:32     ` Ævar Arnfjörð Bjarmason
2022-02-16 16:30       ` Elijah Newren
2022-02-17  4:40         ` Elijah Newren
2022-01-15  1:51   ` [PATCH v2 0/5] Remove the present-despite-SKIP_WORKTREE class of bugs (for sparse-checkouts) Victoria Dye

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=CABPp-BF2d81f0va7x7fpEAFqJtjBgEr-UBY4QCAxrnjoFmdZ3g@mail.gmail.com \
    --to=newren@gmail.com \
    --cc=avarab@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=gitgitgadget@gmail.com \
    --cc=lessleydennington@gmail.com \
    --cc=stolee@gmail.com \
    --cc=vdye@github.com \
    --subject='Re: [PATCH v2 4/5] Update documentation related to sparsity and the skip-worktree bit' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).