On Sat, Dec 4, 2021 at 1:48 PM Victoria Dye <vdye@xxxxxxxxxx> wrote:
>
> Elijah Newren via GitGitGadget wrote:
> > From: Elijah Newren <newren@xxxxxxxxx>
> >
> > As noted in the previous commit, using separate `init` and `set` steps
> > with sparse-checkout result in a number of issues. The previous commit
> > made `set` able to handle the work of both commands. Update the
> > documentation to reflect this, and mark `init` as deprecated.
> >
> > Signed-off-by: Elijah Newren <newren@xxxxxxxxx>
> > ---
> > Documentation/git-sparse-checkout.txt | 92 ++++++++++++++-------------
> > 1 file changed, 49 insertions(+), 43 deletions(-)
> >
> > diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
> > index 42056ee9ff9..d22c925ecf8 100644
> > --- a/Documentation/git-sparse-checkout.txt
> > +++ b/Documentation/git-sparse-checkout.txt
> > @@ -30,28 +30,35 @@ COMMANDS
> > 'list'::
> > Describe the patterns in the sparse-checkout file.
> >
> > -'init'::
> > - Enable the `core.sparseCheckout` setting. If the
> > - sparse-checkout file does not exist, then populate it with
> > - patterns that match every file in the root directory and
> > - no other directories, then will remove all directories tracked
> > - by Git. Add patterns to the sparse-checkout file to
> > - repopulate the working directory.
> > +'set'::
> > + Enable the necessary config settings
> > + (extensions.worktreeConfig, core.sparseCheckout,
> > + core.sparseCheckoutCone) if they are not already enabled, and
> > + write a set of patterns to the sparse-checkout file from the
> > + list of arguments following the 'set' subcommand. Update the
> > + working directory to match the new patterns.
> > +
> > -To avoid interfering with other worktrees, it first enables the
> > -`extensions.worktreeConfig` setting and makes sure to set the
> > -`core.sparseCheckout` setting in the worktree-specific config file.
> > +When the `--stdin` option is provided, the patterns are read from
> > +standard in as a newline-delimited list instead of from the arguments.
> > +
> > -When `--cone` is provided, the `core.sparseCheckoutCone` setting is
> > -also set, allowing for better performance with a limited set of
> > -patterns (see 'CONE PATTERN SET' below).
> > +When `--cone` is passed or `core.sparseCheckoutCone` is enabled, the
> > +input list is considered a list of directories instead of
> > +sparse-checkout patterns. This allows for better performance with a
> > +limited set of patterns (see 'CONE PATTERN SET' below). Note that the
> > +set command will write patterns to the sparse-checkout file to include
> > +all files contained in those directories (recursively) as well as
> > +files that are siblings of ancestor directories. The input format
> > +matches the output of `git ls-tree --name-only`. This includes
> > +interpreting pathnames that begin with a double quote (") as C-style
> > +quoted strings.
> > +
> > -Use the `--[no-]sparse-index` option to toggle the use of the sparse
> > -index format. This reduces the size of the index to be more closely
> > -aligned with your sparse-checkout definition. This can have significant
> > -performance advantages for commands such as `git status` or `git add`.
> > -This feature is still experimental. Some commands might be slower with
> > -a sparse index until they are properly integrated with the feature.
> > +Use the `--[no-]sparse-index` option to use a sparse index (the
> > +default is to not use it). A sparse index reduces the size of the
> > +index to be more closely aligned with your sparse-checkout
> > +definition. This can have significant performance advantages for
> > +commands such as `git status` or `git add`. This feature is still
> > +experimental. Some commands might be slower with a sparse index until
> > +they are properly integrated with the feature.
> > +
> > **WARNING:** Using a sparse index requires modifying the index in a way
> > that is not completely understood by external tools. If you have trouble
> > @@ -60,23 +67,6 @@ to rewrite your index to not be sparse. Older versions of Git will not
> > understand the sparse directory entries index extension and may fail to
> > interact with your repository until it is disabled.
> >
> > -'set'::
> > - Write a set of patterns to the sparse-checkout file, as given as
> > - a list of arguments following the 'set' subcommand. Update the
> > - working directory to match the new patterns. Enable the
> > - core.sparseCheckout config setting if it is not already enabled.
> > -+
> > -When the `--stdin` option is provided, the patterns are read from
> > -standard in as a newline-delimited list instead of from the arguments.
> > -+
> > -When `core.sparseCheckoutCone` is enabled, the input list is considered a
> > -list of directories instead of sparse-checkout patterns. The command writes
> > -patterns to the sparse-checkout file to include all files contained in those
> > -directories (recursively) as well as files that are siblings of ancestor
> > -directories. The input format matches the output of `git ls-tree --name-only`.
> > -This includes interpreting pathnames that begin with a double quote (") as
> > -C-style quoted strings.
> > -
> > 'add'::
> > Update the sparse-checkout file to include additional patterns.
> > By default, these patterns are read from the command-line arguments,
> > @@ -96,9 +86,27 @@ C-style quoted strings.
> >
> > 'disable'::
> > Disable the `core.sparseCheckout` config setting, and restore the
> > - working directory to include all files. Leaves the sparse-checkout
> > - file intact so a later 'git sparse-checkout init' command may
> > - return the working directory to the same state.
> > + working directory to include all files.
> > +
> > +'init'::
> > + Deprecated command that behaves like `set` with no specified paths.
> > + May be removed in the future.
>
> I'm on board with deprecating `init`, but one usage that's not covered by
> the updated `set` is toggling the sparse index *without* modifying the
> patterns. That likely won't matter to most users, but ones that assume `git
> sparse-checkout set --[no-]sparse-index` works the same way as `git
> sparse-checkout init --[no-]sparse-index` would find themselves losing their
> existing pattern set.
>
> Maybe `--[no-]sparse-index` should be added to `git sparse-checkout
> reapply`? For changing settings without updating patterns, that probably
> makes more sense than `init` or `set` anyway. If adding that option is
> outside the scope of what you want to do in this series, though, I'd be
> happy with a note somewhere in this documentation explicitly noting that
> `set` (unlike `init`) will change your patterns, even when toggling
> `index.sparse` (or `core.sparseCheckoutCone`).
I like that idea; reapply seems like the right place to allow folks to
toggle options without updating sparsity paths. I'll add it.
> > ++
> > +Historically, `set` did not used to handle all the necessary config
> > +settings, which meant that both `init` and `set` had to be called.
> > +Invoking both meant the `init` step would first remove nearly all
> > +tracked files (and in cone mode, ignored files too), then the `set`
> > +step would add many of the tracked files (but not ignored files) back.
> > +In addition to the lost files, the performance and UI of this
> > +combination was poor.
> > ++
> > +Also, historically, `init` would not actually initialize the
> > +sparse-checkout file if it already existed. This meant it was
> > +possible to return to a sparse-checkout without remembering which
> > +paths to pass to a subsequent 'set' or 'add' command. However,
> > +`--cone` and `--sparse-index` options would not be remembered across
> > +the disable command, so the easy restore of calling a plain `init`
> > +decreased in utility.
> >
> > SPARSE CHECKOUT
> > ---------------
> > @@ -117,10 +125,8 @@ 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 init` to
> > -initialize a simple sparse-checkout file and enable the `core.sparseCheckout`
> > -config setting. Then, run `git sparse-checkout set` to modify the patterns in
> > -the sparse-checkout file.
> > +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.
> >
>
