[4/6] git-sparse-checkout.txt: update to document that set handles init

Commit Message

Elijah Newren Dec. 4, 2021, 8 p.m. UTC

From: Elijah Newren <[e-mail]>

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 <[e-mail]>
---
 Documentation/git-sparse-checkout.txt | 92 ++++++++++++++-------------
 1 file changed, 49 insertions(+), 43 deletions(-)

Comments

Victoria Dye Dec. 4, 2021, 9:48 p.m. UTC | #1

Elijah Newren via GitGitGadget wrote:
> From: Elijah Newren <[e-mail]>
> 
> 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 <[e-mail]>
> ---
>  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.
>

Derrick Stolee Dec. 7, 2021, 4:45 p.m. UTC | #2

On 12/4/2021 4:48 PM, Victoria Dye wrote:
> Elijah Newren via GitGitGadget wrote:

>> +'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 'reapply' as a good place for that functionality. Hopefully it
won't be long before the sparse index is on by default, but it will
still be good to have a user-facing way to toggle it, when necessary.

Thanks,
-Stolee

Elijah Newren Dec. 7, 2021, 5:06 p.m. UTC | #3

On Sat, Dec 4, 2021 at 1:48 PM Victoria Dye <[e-mail]> wrote:
>
> Elijah Newren via GitGitGadget wrote:
> > From: Elijah Newren <[e-mail]>
> >
> > 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 <[e-mail]>
> > ---
> >  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.
> >
>

Lessley Dennington Dec. 7, 2021, 8:42 p.m. UTC | #4

On 12/4/21 12:00 PM, Elijah Newren via GitGitGadget wrote:
> From: Elijah Newren <[e-mail]>
> 
> 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 <[e-mail]>
> ---
>   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.
> ++
> +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.
> ++
Super nit: Perhaps update '`set` did not used to handle' to '`set` did not
handle'.
> +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.
>

Elijah Newren Dec. 7, 2021, 9:13 p.m. UTC | #5

On Tue, Dec 7, 2021 at 12:42 PM Lessley Dennington
<[e-mail]> wrote:
>
> On 12/4/21 12:00 PM, Elijah Newren via GitGitGadget wrote:
> > From: Elijah Newren <[e-mail]>
> >
...
> > ++
> > +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.
> > ++
> Super nit: Perhaps update '`set` did not used to handle' to '`set` did not
> handle'.

Yeah, that sounds better.  I'll wait a bit longer for other comments,
then send a fix for this along with any other needed fixes (even if
just included Acks & Reviewed-bys I get).  Thanks!

Lessley Dennington Dec. 7, 2021, 10:36 p.m. UTC | #6

On 12/7/21 1:13 PM, Elijah Newren wrote:
> On Tue, Dec 7, 2021 at 12:42 PM Lessley Dennington
> <[e-mail]> wrote:
>>
>> On 12/4/21 12:00 PM, Elijah Newren via GitGitGadget wrote:
>>> From: Elijah Newren <[e-mail]>
>>>
> ...
>>> ++
>>> +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.
>>> ++
>> Super nit: Perhaps update '`set` did not used to handle' to '`set` did not
>> handle'.
> 
> Yeah, that sounds better.  I'll wait a bit longer for other comments,
> then send a fix for this along with any other needed fixes (even if
> just included Acks & Reviewed-bys I get).  Thanks!
> 
Sounds good. Also apologies that I didn't add this to v2 - my Thunderbird
client hadn't loaded those messages at the time I sent my feedback.

Patch

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