On Tue, Mar 8, 2022 at 6:30 AM Derrick Stolee [off-list ref] wrote:

On 3/8/2022 2:39 AM, Elijah Newren via GitGitGadget wrote:

quoted

From: Elijah Newren <redacted>

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!

quoted

+`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.