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