Re: [PATCH 6/9] git-sparse-checkout.txt: add a new EXAMPLES section

From: Elijah Newren <newren@gmail.com>
Date: Mar 12, 2022, 01:58 UTC
Message-ID: <CABPp-BGfke=t99wY2OQuG3SnbFhRd1zpPFW8JqEBN-wANgVM1A@mail.gmail.com>
In-Reply-To: <5c59964a-a3ce-3723-8044-16727d9d3170@github.com>

On Tue, Mar 8, 2022 at 6:30 AM Derrick Stolee <derrickstolee@github.com> wrote:

Show 25 quoted lines

>
> On 3/8/2022 2:39 AM, Elijah Newren via GitGitGadget wrote:
> > From: Elijah Newren <newren@gmail.com>
> >
> > Since many users like to learn from examples, provide a section in the
> > manual with example commands that would be used and a brief explanation
> > of what each does.
>
> Examples are great!
>
> > +`git sparse-checkout reapply`::
> > +
> > +     It is possible for commands to update the working tree in a way
> > +     that does not respect the selected sparsity directories, either
> > +     because of special cases (such as hitting conflicts when
> > +     merging/rebasing), or because some commands didn't fully support
> > +     sparse checkouts (e.g. the old `recursive` merge backend had
> > +     only limited support).  This command reapplies the existing
> > +     sparse directory specifications to make the working directory
> > +     match.
>
> This focuses on how a Git command might cause extra data, but it
> doesn't mention how other tools might create ignored files outside
> of the sparse-checkout and this will clean them up. Do you want to
> add that, or do you prefer focusing on just Git reasons?

Does that happen in a significant number of cases?  Prior to
en/present-despite-skipped, it was essentially a null set of cases.
After it, we'd need:
   * the file to be tracked (reapply doesn't touch untracked or ignored files)
   * the file to have been SKIP_WORKTREE prior to the other tool modifying it
   * the file has to have its contents match what is staged in the index
and then reapply would clean the file out.

I guess there is kind of a converse case of someone manually removing the SKIP_WORKTREE bit via direct manipulation using `git update-index --no-skip-worktree $PATH` and removing the file locally, and then using `reapply` to get it back, but that seems like a really unlikely usecase.

 Maybe if I just made a simple tweak to the wording:

...selected sparsity directories. This can come from tools external to Git writing files, or even affect Git commands because of either special cases...

does that sound good? I'll submit a re-roll with that but I'm open to alternative wordings.