| Message ID | 3265f41bcab7202991da5a7a160a85820fbff0c4.1646725188.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | sparse-checkout: make cone mode the default | expand |
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? Thanks, -Stolee
On Tue, Mar 8, 2022 at 6:30 AM Derrick Stolee <derrickstolee@github.com> wrote: > > 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.
diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt index 883b7f4c44f..2cfb1d8f599 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -136,6 +136,42 @@ paths to pass to a subsequent 'set' or 'add' command. However, the disable command, so the easy restore of calling a plain `init` decreased in utility. +EXAMPLES +-------- +`git sparse-checkout set MY/DIR1 SUB/DIR2`:: + + Change to a sparse checkout with all files (at any depth) under + MY/DIR1/ and SUB/DIR2/ present in the working copy (plus all + files immediately under MY/ and SUB/ and the toplevel + directory). If already in a sparse checkout, change which files + are present in the working copy to this new selection. Note + that this command will also delete all ignored files in any + directory that no longer has either tracked or + non-ignored-untracked files present. + +`git sparse-checkout disable`:: + + Repopulate the working directory with all files, disabling sparse + checkouts. + +`git sparse-checkout add SOME/DIR/ECTORY`:: + + Add all files under SOME/DIR/ECTORY/ (at any depth) to the + sparse checkout, as well as all files immediately under + SOME/DIR/ and immediately under SOME/. Must already be in a + sparse checkout before using this command. + +`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. + INTERNALS -- SPARSE CHECKOUT ---------------------------- @@ -154,12 +190,6 @@ directory, it updates the skip-worktree bits in the index based on this file. The files matching the patterns in the file will appear in the working directory, and the rest will not. -To enable the sparse-checkout feature, run `git sparse-checkout set` to -set the patterns you want to use. - -To repopulate the working directory with all files, use the -`git sparse-checkout disable` command. - INTERNALS -- CONE PATTERN SET -----------------------------