[RFC PATCH 0/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section

[RFC PATCH 0/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section

[Shaoxuan Yuan]

Add an OPTIONS section to the manual and move the descriptions/explanations for 
these options from below COMMANDS to OPTIONS. 

This patch is based on Elijah's series [1].

[1] https://lore.kernel.org/git/pull.1148.git.1646725188.gitgitgadget@gmail.com/

Shaoxuan Yuan (1):
  Documentation/git-sparse-checkout.txt: add an OPTIONS section

 Documentation/git-sparse-checkout.txt | 63 +++++++++++++++++----------
 1 file changed, 39 insertions(+), 24 deletions(-)


base-commit: b5b154774abc80247a09c488c5125d328153c1cb
-- 
2.35.1

[RFC PATCH 1/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section

[Shaoxuan Yuan]

Add an OPTIONS section to the manual and move the descriptions about
these options from COMMANDS to the section.

Signed-off-by: Shaoxuan Yuan <shaoxuan.yuan02@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 63 +++++++++++++++++----------
 1 file changed, 39 insertions(+), 24 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 06f23660f6..0bc742cb3a 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -35,30 +35,11 @@ COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN
 THE FUTURE.
 
 
-COMMANDS
---------
-'list'::
-	Describe the directories or patterns in the sparse-checkout file.
-
-'set'::
-	Enable the necessary sparse-checkout config settings
-	(`core.sparseCheckout`, `core.sparseCheckoutCone`, and
-	`index.sparse`) if they are not already set to the desired values,
-	populate the sparse-checkout file from the list of arguments
-	following the 'set' subcommand, and update the working directory to
-	match.
-+
-To ensure that adjusting the sparse-checkout settings within a worktree
-does not alter the sparse-checkout settings in other worktrees, the 'set'
-subcommand will upgrade your repository config to use worktree-specific
-config if not already present. The sparsity defined by the arguments to
-the 'set' subcommand are stored in the worktree-specific sparse-checkout
-file. See linkgit:git-worktree[1] and the documentation of
-`extensions.worktreeConfig` in linkgit:git-config[1] for more details.
-+
-When the `--stdin` option is provided, the directories or patterns are
-read from standard in as a newline-delimited list instead of from the
-arguments.
+OPTIONS
+-------
+'--[no-]cone'::
+	Use with ['set'|'reapply'].
+	Specify using cone mode or not. The default is to use cone mode.
 +
 By default, the input list is considered a list of directories, matching
 the output of `git ls-tree -d --name-only`.  This includes interpreting
@@ -78,6 +59,11 @@ with the `--sparse-index` option, and will likely be incompatible with
 other new features as they are added.  See the "Non-cone Problems"
 section below and the "Sparse Checkout" section of
 linkgit:git-read-tree[1] for more details.
+
+'--[no-]sparse-index'::
+	Use with ['set'|'reapply'].
+	Specify using a sparse index or not. The default is to not use a 
+	sparse index.
 +
 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
@@ -94,6 +80,35 @@ 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.
 
+'--stdin'::
+	Use with ['set'|'add'].
++
+When the `--stdin` option is provided, the directories or patterns are
+read from standard in as a newline-delimited list instead of from the
+arguments.
+
+
+COMMANDS
+--------
+'list'::
+	Describe the directories or patterns in the sparse-checkout file.
+
+'set'::
+	Enable the necessary sparse-checkout config settings
+	(`core.sparseCheckout`, `core.sparseCheckoutCone`, and
+	`index.sparse`) if they are not already set to the desired values,
+	populate the sparse-checkout file from the list of arguments
+	following the 'set' subcommand, and update the working directory to
+	match.
++
+To ensure that adjusting the sparse-checkout settings within a worktree
+does not alter the sparse-checkout settings in other worktrees, the 'set'
+subcommand will upgrade your repository config to use worktree-specific
+config if not already present. The sparsity defined by the arguments to
+the 'set' subcommand are stored in the worktree-specific sparse-checkout
+file. See linkgit:git-worktree[1] and the documentation of
+`extensions.worktreeConfig` in linkgit:git-config[1] for more details.
+
 'add'::
 	Update the sparse-checkout file to include additional directories
 	(in cone mode) or patterns (in non-cone mode).  By default, these
-- 
2.35.1

Re: [RFC PATCH 1/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section

[Derrick Stolee]

On 3/11/2022 8:21 AM, Shaoxuan Yuan wrote:
> Add an OPTIONS section to the manual and move the descriptions about
> these options from COMMANDS to the section.

This is a good goal.

> +OPTIONS
> +-------

However, there are a few issues with the current approach. First, I
believe it would be better to start with COMMANDS, then OPTIONS.

To be fair, we are not consistent here. These commands use OPTIONS
and then COMMANDS:

* git-commit-graph.txt
* git-remote.txt
* git-revert.txt

These use [SUB]COMMANDS and then OPTIONS:

* git-maintenance.txt
* git-notes.txt
* git-p4.txt
* git-stash.txt
* git-submodule.txt
* git-worktree.txt

My preference would be OPTIONS second (and we can clean up the
other docs as #leftoverbits). In particular, I noticed that
the SYNOPSIS for git-maintenance.txt is out of date.	

> +'--[no-]cone'::
> +	Use with ['set'|'reapply'].
> +	Specify using cone mode or not. The default is to use cone mode.
>  +
>  By default, the input list is considered a list of directories, matching
>  the output of `git ls-tree -d --name-only`.  This includes interpreting

The other issue is that this context is detailing information about
the 'set' command and the input it takes. You'll want to make sure
the information is properly grouped.

> @@ -78,6 +59,11 @@ with the `--sparse-index` option, and will likely be incompatible with
>  other new features as they are added.  See the "Non-cone Problems"
>  section below and the "Sparse Checkout" section of
>  linkgit:git-read-tree[1] for more details.
> +
> +'--[no-]sparse-index'::
> +	Use with ['set'|'reapply'].

I do like these clear indicators of which commands allow this
option. I wonder if it should instead be

	Use with the `set` and `reapply` commands.

Thanks,
-Stolee

[PATCH v2 0/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section

[Shaoxuan Yuan]

== Updates Log ==

Changes since v1:

 * rebase on Elijah's v2 [1]
 * move OPTIONS to after COMMANDS
 * add two sub-sections under option '--[no-]cone', one for command 'set' and
one for command 'reapply'
 * change the command indicators from this style:

  Use with ['set'|'reapply'].

  to this style:

  Use with the `set` and `reapply` commands.

== Overview ==

Add an OPTIONS section to the manual and move the descriptions/explanations for 
these options from below COMMANDS to OPTIONS. 

[1] https://lore.kernel.org/git/pull.1148.v2.git.1647054681.gitgitgadget@gmail.com/#r

Shaoxuan Yuan (1):
  Documentation/git-sparse-checkout.txt: add an OPTIONS section

 Documentation/git-sparse-checkout.txt | 106 +++++++++++++++-----------
 1 file changed, 63 insertions(+), 43 deletions(-)


base-commit: 4b89a3392b04acccf28f09f90e26715140461373
-- 
2.35.1

[PATCH v2 1/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section

[Shaoxuan Yuan]

Add an OPTIONS section to the manual and move the descriptions about
these options from COMMANDS to the section.

Helped-by: Derick Stolee <derrickstolee@github.com>
Signed-off-by: Shaoxuan Yuan <shaoxuan.yuan02@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 106 +++++++++++++++-----------
 1 file changed, 63 insertions(+), 43 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index e4a29a2baa..b8f3b89b74 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -55,44 +55,6 @@ config if not already present. The sparsity defined by the arguments to
 the 'set' subcommand are stored in the worktree-specific sparse-checkout
 file. See linkgit:git-worktree[1] and the documentation of
 `extensions.worktreeConfig` in linkgit:git-config[1] for more details.
-+
-When the `--stdin` option is provided, the directories or patterns are
-read from standard in as a newline-delimited list instead of from the
-arguments.
-+
-By default, the input list is considered a list of directories, matching
-the output of `git ls-tree -d --name-only`.  This includes interpreting
-pathnames that begin with a double quote (") as C-style quoted strings.
-Note that all files under the specified directories (at any depth) will
-be included in the sparse checkout, as well as files that are siblings
-of either the given directory or any of its ancestors (see 'CONE PATTERN
-SET' below for more details).  In the past, this was not the default,
-and `--cone` needed to be specified or `core.sparseCheckoutCone` needed
-to be enabled.
-+
-When `--no-cone` is passed, the input list is considered a list of
-patterns.  This mode is harder to use, and unless you can keep the
-number of patterns small, its design also scales poorly.  It used to be
-the default mode, but we do not recommend using it.  It does not work
-with the `--sparse-index` option, and will likely be incompatible with
-other new features as they are added.  See the "Non-cone Problems"
-section below and the "Sparse Checkout" section of
-linkgit:git-read-tree[1] for more details.
-+
-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
-with this compatibility, then run `git sparse-checkout init --no-sparse-index`
-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.
 
 'add'::
 	Update the sparse-checkout file to include additional directories
@@ -109,11 +71,6 @@ interact with your repository until it is disabled.
 	cases, it can make sense to run `git sparse-checkout reapply` later
 	after cleaning up affected paths (e.g. resolving conflicts, undoing
 	or committing changes, etc.).
-+
-The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`
-flags, with the same meaning as the flags from the `set` command, in order
-to change which sparsity mode you are using without needing to also respecify
-all sparsity paths.
 
 'disable'::
 	Disable the `core.sparseCheckout` config setting, and restore the
@@ -139,6 +96,69 @@ 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.
 
+
+OPTIONS
+-------
+'--[no-]cone'::
+	Use with the `set` and `reapply` commands.
+	Specify using cone mode or not. The default is to use cone mode.
++
+For `set` command:
++
+By default, the input list is considered a list of directories, matching
+the output of `git ls-tree -d --name-only`.  This includes interpreting
+pathnames that begin with a double quote (") as C-style quoted strings.
+Note that all files under the specified directories (at any depth) will
+be included in the sparse checkout, as well as files that are siblings
+of either the given directory or any of its ancestors (see 'CONE PATTERN
+SET' below for more details).  In the past, this was not the default,
+and `--cone` needed to be specified or `core.sparseCheckoutCone` needed
+to be enabled.
++
+When `--no-cone` is passed, the input list is considered a list of
+patterns.  This mode is harder to use, and unless you can keep the
+number of patterns small, its design also scales poorly.  It used to be
+the default mode, but we do not recommend using it.  It does not work
+with the `--sparse-index` option, and will likely be incompatible with
+other new features as they are added.  See the "Non-cone Problems"
+section below and the "Sparse Checkout" section of
+linkgit:git-read-tree[1] for more details.
++
+For `reapply` command:
++
+The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`
+flags, with the same meaning as the flags from the `set` command, in order
+to change which sparsity mode you are using without needing to also respecify
+all sparsity paths.
+
+'--[no-]sparse-index'::
+	Use with the `set` and `reapply` commands.
+	Specify using a sparse index or not. The default is to not use a
+	sparse index.
++
+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
+with this compatibility, then run `git sparse-checkout init --no-sparse-index`
+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.
+
+'--stdin'::
+	Use with the `set` and `add` commands.
++
+When the `--stdin` option is provided, the directories or patterns are
+read from standard in as a newline-delimited list instead of from the
+arguments.
+
+
 EXAMPLES
 --------
 `git sparse-checkout set MY/DIR1 SUB/DIR2`::
-- 
2.35.1

[PATCH v3 0/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section

[Shaoxuan Yuan]

== Updates Log ==

Changes since v2:

 * correct Derrick's name in the single-patch (I really missed it XD)
 * rebase on Elijah's v2 [1]
 * move OPTIONS to after COMMANDS
 * add two sub-sections under option '--[no-]cone', one for command 'set' and
one for command 'reapply'
 * change the command indicators from this style:

  Use with ['set'|'reapply'].

  to this style:

  Use with the `set` and `reapply` commands.

== Overview ==

Add an OPTIONS section to the manual and move the descriptions/explanations for 
these options from below COMMANDS to OPTIONS. 

[1] https://lore.kernel.org/git/pull.1148.v2.git.1647054681.gitgitgadget@gmail.com/#r

Shaoxuan Yuan (1):
  Documentation/git-sparse-checkout.txt: add an OPTIONS section

 Documentation/git-sparse-checkout.txt | 106 +++++++++++++++-----------
 1 file changed, 63 insertions(+), 43 deletions(-)


base-commit: 4b89a3392b04acccf28f09f90e26715140461373
-- 
2.35.1

[PATCH v3 1/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section

[Shaoxuan Yuan]

Add an OPTIONS section to the manual and move the descriptions about
these options from COMMANDS to the section.

Helped-by: Derrick Stolee <derrickstolee@github.com>
Signed-off-by: Shaoxuan Yuan <shaoxuan.yuan02@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 106 +++++++++++++++-----------
 1 file changed, 63 insertions(+), 43 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index e4a29a2baa..b8f3b89b74 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -55,44 +55,6 @@ config if not already present. The sparsity defined by the arguments to
 the 'set' subcommand are stored in the worktree-specific sparse-checkout
 file. See linkgit:git-worktree[1] and the documentation of
 `extensions.worktreeConfig` in linkgit:git-config[1] for more details.
-+
-When the `--stdin` option is provided, the directories or patterns are
-read from standard in as a newline-delimited list instead of from the
-arguments.
-+
-By default, the input list is considered a list of directories, matching
-the output of `git ls-tree -d --name-only`.  This includes interpreting
-pathnames that begin with a double quote (") as C-style quoted strings.
-Note that all files under the specified directories (at any depth) will
-be included in the sparse checkout, as well as files that are siblings
-of either the given directory or any of its ancestors (see 'CONE PATTERN
-SET' below for more details).  In the past, this was not the default,
-and `--cone` needed to be specified or `core.sparseCheckoutCone` needed
-to be enabled.
-+
-When `--no-cone` is passed, the input list is considered a list of
-patterns.  This mode is harder to use, and unless you can keep the
-number of patterns small, its design also scales poorly.  It used to be
-the default mode, but we do not recommend using it.  It does not work
-with the `--sparse-index` option, and will likely be incompatible with
-other new features as they are added.  See the "Non-cone Problems"
-section below and the "Sparse Checkout" section of
-linkgit:git-read-tree[1] for more details.
-+
-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
-with this compatibility, then run `git sparse-checkout init --no-sparse-index`
-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.
 
 'add'::
 	Update the sparse-checkout file to include additional directories
@@ -109,11 +71,6 @@ interact with your repository until it is disabled.
 	cases, it can make sense to run `git sparse-checkout reapply` later
 	after cleaning up affected paths (e.g. resolving conflicts, undoing
 	or committing changes, etc.).
-+
-The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`
-flags, with the same meaning as the flags from the `set` command, in order
-to change which sparsity mode you are using without needing to also respecify
-all sparsity paths.
 
 'disable'::
 	Disable the `core.sparseCheckout` config setting, and restore the
@@ -139,6 +96,69 @@ 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.
 
+
+OPTIONS
+-------
+'--[no-]cone'::
+	Use with the `set` and `reapply` commands.
+	Specify using cone mode or not. The default is to use cone mode.
++
+For `set` command:
++
+By default, the input list is considered a list of directories, matching
+the output of `git ls-tree -d --name-only`.  This includes interpreting
+pathnames that begin with a double quote (") as C-style quoted strings.
+Note that all files under the specified directories (at any depth) will
+be included in the sparse checkout, as well as files that are siblings
+of either the given directory or any of its ancestors (see 'CONE PATTERN
+SET' below for more details).  In the past, this was not the default,
+and `--cone` needed to be specified or `core.sparseCheckoutCone` needed
+to be enabled.
++
+When `--no-cone` is passed, the input list is considered a list of
+patterns.  This mode is harder to use, and unless you can keep the
+number of patterns small, its design also scales poorly.  It used to be
+the default mode, but we do not recommend using it.  It does not work
+with the `--sparse-index` option, and will likely be incompatible with
+other new features as they are added.  See the "Non-cone Problems"
+section below and the "Sparse Checkout" section of
+linkgit:git-read-tree[1] for more details.
++
+For `reapply` command:
++
+The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`
+flags, with the same meaning as the flags from the `set` command, in order
+to change which sparsity mode you are using without needing to also respecify
+all sparsity paths.
+
+'--[no-]sparse-index'::
+	Use with the `set` and `reapply` commands.
+	Specify using a sparse index or not. The default is to not use a
+	sparse index.
++
+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
+with this compatibility, then run `git sparse-checkout init --no-sparse-index`
+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.
+
+'--stdin'::
+	Use with the `set` and `add` commands.
++
+When the `--stdin` option is provided, the directories or patterns are
+read from standard in as a newline-delimited list instead of from the
+arguments.
+
+
 EXAMPLES
 --------
 `git sparse-checkout set MY/DIR1 SUB/DIR2`::
-- 
2.35.1

Re: [PATCH v3 1/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section

[Derrick Stolee]

On 3/14/2022 2:56 AM, Shaoxuan Yuan wrote:
> Add an OPTIONS section to the manual and move the descriptions about
> these options from COMMANDS to the section.
> 
> Helped-by: Derrick Stolee <derrickstolee@github.com>
> Signed-off-by: Shaoxuan Yuan <shaoxuan.yuan02@gmail.com>

Thank you for reorganizing the COMMANDS and OPTIONS. I still think
there is some improvement to be made here.

>  the 'set' subcommand are stored in the worktree-specific sparse-checkout
>  file. See linkgit:git-worktree[1] and the documentation of
>  `extensions.worktreeConfig` in linkgit:git-config[1] for more details.

Just to provide some extra context to the review, here is the content
of the 'set' command up to this point:

'set'::
	Enable the necessary sparse-checkout config settings
	(`core.sparseCheckout`, `core.sparseCheckoutCone`, and
	`index.sparse`) if they are not already set to the desired values,
	populate the sparse-checkout file from the list of arguments
	following the 'set' subcommand, and update the working directory to
	match.
+
To ensure that adjusting the sparse-checkout settings within a worktree
does not alter the sparse-checkout settings in other worktrees, the 'set'
subcommand will upgrade your repository config to use worktree-specific
config if not already present. The sparsity defined by the arguments to
the 'set' subcommand are stored in the worktree-specific sparse-checkout
file. See linkgit:git-worktree[1] and the documentation of
`extensions.worktreeConfig` in linkgit:git-config[1] for more details.


So this mentions that we will "write a set of patterns to the
sparse-checkout file from the list of arguments" but with the
deletions below we lose understanding of how the arguments match with
the patterns.

I think it would be good to insert a paragraph between the two above
paragraphs that briefly touches on the input. Something like:

  By default, the arguments to the `set` command are interpreted as a
  list of directories. The sparse-checkout patterns are set to match
  all files within those directories, recursively, as well as any file
  directly contained in a parent of those directories. See INTERNALS
  -- CONE PATTERN SET below for full details. If --no-cone is specified,
  then the arguments are interpreted as sparse-checkout patterns. See
  INTERNALS -- FULL PATTERN SET below for more information.

We might need to refer to the `set` command input when talking about
the `add` command.

>  'add'::
>  	Update the sparse-checkout file to include additional directories
> @@ -109,11 +71,6 @@ interact with your repository until it is disabled.
>  	cases, it can make sense to run `git sparse-checkout reapply` later
>  	after cleaning up affected paths (e.g. resolving conflicts, undoing
>  	or committing changes, etc.).
> -+
> -The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`
> -flags, with the same meaning as the flags from the `set` command, in order
> -to change which sparsity mode you are using without needing to also respecify
> -all sparsity paths.
>  
>  'disable'::
>  	Disable the `core.sparseCheckout` config setting, and restore the
> @@ -139,6 +96,69 @@ 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.
>  
> +
> +OPTIONS
> +-------
> +'--[no-]cone'::
> +	Use with the `set` and `reapply` commands.
> +	Specify using cone mode or not. The default is to use cone mode.
> ++
> +For `set` command:
> ++
> +By default, the input list is considered a list of directories, matching
> +the output of `git ls-tree -d --name-only`.  This includes interpreting
> +pathnames that begin with a double quote (") as C-style quoted strings.
> +Note that all files under the specified directories (at any depth) will
> +be included in the sparse checkout, as well as files that are siblings
> +of either the given directory or any of its ancestors (see 'CONE PATTERN
> +SET' below for more details).  In the past, this was not the default,
> +and `--cone` needed to be specified or `core.sparseCheckoutCone` needed
> +to be enabled.
> ++
> +When `--no-cone` is passed, the input list is considered a list of
> +patterns.  This mode is harder to use, and unless you can keep the
> +number of patterns small, its design also scales poorly.  It used to be
> +the default mode, but we do not recommend using it.  It does not work
> +with the `--sparse-index` option, and will likely be incompatible with
> +other new features as they are added.  See the "Non-cone Problems"
> +section below and the "Sparse Checkout" section of
> +linkgit:git-read-tree[1] for more details.
> ++

With the recommended change above, this pair of paragraphs can be
condensed. Something like...

  For the `set` command, the option to use cone mode or not changes
  the interpretation of the remaining arguments to either be a list
  of directories or a list of patterns.

> +For `reapply` command:
> ++
> +The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`
> +flags, with the same meaning as the flags from the `set` command, in order
> +to change which sparsity mode you are using without needing to also respecify
> +all sparsity paths.

I'm not sure that this mention of `reapply` is necessary, as those
options document themselves further down.

> +
> +'--[no-]sparse-index'::
> +	Use with the `set` and `reapply` commands.
> +	Specify using a sparse index or not. The default is to not use a
> +	sparse index.
> ++
> +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
> +with this compatibility, then run `git sparse-checkout init --no-sparse-index`
> +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.
> +
> +'--stdin'::
> +	Use with the `set` and `add` commands.
> ++
> +When the `--stdin` option is provided, the directories or patterns are
> +read from standard in as a newline-delimited list instead of from the
> +arguments.

These options are excellent.

Thanks,
-Stolee

[PATCH v4 0/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section

[Shaoxuan Yuan]

== Updates Log ==

Changes since v3 (based on v3's single patch):

 * changes according to Derrick [1]

== Overview ==

Add an OPTIONS section to the manual and move the descriptions/explanations for 
these options from below COMMANDS to OPTIONS. 

[1] https://lore.kernel.org/git/307ac60d-b0a1-ea90-8118-a4e02b809102@github.com/


Shaoxuan Yuan (1):
  Documentation/git-sparse-checkout.txt: add an OPTIONS section

 Documentation/git-sparse-checkout.txt | 44 +++++++++------------------
 1 file changed, 15 insertions(+), 29 deletions(-)

base-commit: eb129e532a7c58ea34afeec70b0e2e029c0d5fee
-- 
2.35.1

[PATCH v4 1/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section

[Shaoxuan Yuan]

Add an OPTIONS section to the manual and move the descriptions about
these options from COMMANDS to the section.

Helped-by: Derrick Stolee <derrickstolee@github.com>
Signed-off-by: Shaoxuan Yuan <shaoxuan.yuan02@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 44 +++++++++------------------
 1 file changed, 15 insertions(+), 29 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index b8f3b89b74..0178d63f56 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -48,6 +48,14 @@ COMMANDS
 	following the 'set' subcommand, and update the working directory to
 	match.
 +
+By default, the arguments to the `set` command are interpreted as a
+list of directories. The sparse-checkout patterns are set to match
+all files within those directories, recursively, as well as any file
+directly contained in a parent of those directories. See INTERNALS
+-- CONE PATTERN SET below for full details. If --no-cone is specified,
+then the arguments are interpreted as sparse-checkout patterns. See
+INTERNALS -- FULL PATTERN SET below for more information.
++
 To ensure that adjusting the sparse-checkout settings within a worktree
 does not alter the sparse-checkout settings in other worktrees, the 'set'
 subcommand will upgrade your repository config to use worktree-specific
@@ -59,8 +67,10 @@ file. See linkgit:git-worktree[1] and the documentation of
 'add'::
 	Update the sparse-checkout file to include additional directories
 	(in cone mode) or patterns (in non-cone mode).  By default, these
-	directories or patterns are read from the command-line arguments,
-	but they can be read from stdin using the `--stdin` option.
+	directories or patterns are read from the command-line arguments.
+  These directories or patterns are interpreted the same way as stated
+  above in `set` command, and they can be read from stdin using the
+  `--stdin` option.
 
 'reapply'::
 	Reapply the sparsity pattern rules to paths in the working tree.
@@ -103,33 +113,9 @@ OPTIONS
 	Use with the `set` and `reapply` commands.
 	Specify using cone mode or not. The default is to use cone mode.
 +
-For `set` command:
-+
-By default, the input list is considered a list of directories, matching
-the output of `git ls-tree -d --name-only`.  This includes interpreting
-pathnames that begin with a double quote (") as C-style quoted strings.
-Note that all files under the specified directories (at any depth) will
-be included in the sparse checkout, as well as files that are siblings
-of either the given directory or any of its ancestors (see 'CONE PATTERN
-SET' below for more details).  In the past, this was not the default,
-and `--cone` needed to be specified or `core.sparseCheckoutCone` needed
-to be enabled.
-+
-When `--no-cone` is passed, the input list is considered a list of
-patterns.  This mode is harder to use, and unless you can keep the
-number of patterns small, its design also scales poorly.  It used to be
-the default mode, but we do not recommend using it.  It does not work
-with the `--sparse-index` option, and will likely be incompatible with
-other new features as they are added.  See the "Non-cone Problems"
-section below and the "Sparse Checkout" section of
-linkgit:git-read-tree[1] for more details.
-+
-For `reapply` command:
-+
-The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`
-flags, with the same meaning as the flags from the `set` command, in order
-to change which sparsity mode you are using without needing to also respecify
-all sparsity paths.
+For the `set` command, the option to use cone mode or not changes
+the interpretation of the remaining arguments to either be a list
+of directories or a list of patterns.
 
 '--[no-]sparse-index'::
 	Use with the `set` and `reapply` commands.
-- 
2.35.1

Re: [PATCH v4 1/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section

[Junio C Hamano]

Shaoxuan Yuan <shaoxuan.yuan02@gmail.com> writes:

> Add an OPTIONS section to the manual and move the descriptions about
> these options from COMMANDS to the section.

The above description does not seem to match what the patch does at
all, though.  Sent a wrong patch, possibly just the tip of a series,
when you needed to send more than one patches?  For example, the
header for the hunk -103,33 tells us that the file already has OPTIONS
section before this patch gets applied.

> @@ -48,6 +48,14 @@ COMMANDS
>  	following the 'set' subcommand, and update the working directory to
>  	match.
>  +
> +By default, the arguments to the `set` command are interpreted as a
> +list of directories. The sparse-checkout patterns are set to match
> +all files within those directories, recursively, as well as any file
> +directly contained in a parent of those directories. See INTERNALS
> +-- CONE PATTERN SET below for full details. If --no-cone is specified,
> +then the arguments are interpreted as sparse-checkout patterns. See
> +INTERNALS -- FULL PATTERN SET below for more information.
> ++
>  To ensure that adjusting the sparse-checkout settings within a worktree

That reads well.

> @@ -59,8 +67,10 @@ file. See linkgit:git-worktree[1] and the documentation of
>  'add'::
>  	Update the sparse-checkout file to include additional directories
>  	(in cone mode) or patterns (in non-cone mode).  By default, these
> -	directories or patterns are read from the command-line arguments,
> -	but they can be read from stdin using the `--stdin` option.
> +	directories or patterns are read from the command-line arguments.
> +  These directories or patterns are interpreted the same way as stated
> +  above in `set` command, and they can be read from stdin using the
> +  `--stdin` option.

The original removed by the patch said "directories or patterns",
and I understand that this change is an attempt to say that the
command chooses between directories and patterns using the same
criteria as the "set" command, but the added "are interpreted the
same way as ..." in the middle interrupts the flow of thought the
sentence conveys.  To me, it looks like the first sentence gives
clear enough explanation of that already.

Broken indentation aside, I do not see why this change is needed.

> @@ -103,33 +113,9 @@ OPTIONS
>  	Use with the `set` and `reapply` commands.
>  	Specify using cone mode or not. The default is to use cone mode.
>  +
> -For `set` command:
> ...
> -flags, with the same meaning as the flags from the `set` command, in order
> -to change which sparsity mode you are using without needing to also respecify
> -all sparsity paths.
> +For the `set` command, the option to use cone mode or not changes
> +the interpretation of the remaining arguments to either be a list
> +of directories or a list of patterns.

These three lines are not technically incorrect, but is not written
in a way that helps readers.

Read these three lines a few times, pretending that you have never
used the sparse-checkout, and try to answer this question: "I am
giving a few arguments to the command using the cone mode.  Are they
taken as directories, or patterns?"

It is hard for me to guess what is being improved upon because I do
not have the preimage of this hunk, but the new text is much less
clear than "directories (in cone mode) or patterns (in non-cone
mode)" we saw earlier in the description for the 'add' command,
which would help us answer the question (answer: they are taken as
directories).

Thanks.

Re: [PATCH v4 0/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section

[Junio C Hamano]

Shaoxuan Yuan <shaoxuan.yuan02@gmail.com> writes:

> == Updates Log ==
>
> Changes since v3 (based on v3's single patch):
>
>  * changes according to Derrick [1]
>
> == Overview ==
>
> Add an OPTIONS section to the manual and move the descriptions/explanations for 
> these options from below COMMANDS to OPTIONS. 
>
> [1] https://lore.kernel.org/git/307ac60d-b0a1-ea90-8118-a4e02b809102@github.com/
>
>
> Shaoxuan Yuan (1):
>   Documentation/git-sparse-checkout.txt: add an OPTIONS section
>
>  Documentation/git-sparse-checkout.txt | 44 +++++++++------------------
>  1 file changed, 15 insertions(+), 29 deletions(-)
>
> base-commit: eb129e532a7c58ea34afeec70b0e2e029c0d5fee

It is not very helpful to give the name of an object that is not
publicly available.  Basing a patch on some topics in flight is
fine, but please clearly state what it is based on in a cover letter
(if the topic is a multi-patch series) or below the three-dash line
(if it is a single patch).

[PATCH v5 0/4] Documentation/git-sparse-checkout.txt: add an OPTIONS section

[Shaoxuan Yuan]

== Updates Log ==

Changes since v4

 * ship a multi-patch series to reflect the history
 * base on Elijah's series [1]
 * changes according to Junio [2]

[1] https://lore.kernel.org/git/pull.1148.v2.git.1647054681.gitgitgadget@gmail.com/
[2] https://lore.kernel.org/git/xmqqfsnfb42c.fsf@gitster.g/

== Overview ==

Add an OPTIONS section to the manual. Also provide corresponding text changes
for better understanding the topic.

Shaoxuan Yuan (4):
  Documentation/git-sparse-checkout.txt: add an OPTIONS section
  Documentation/git-sparse-checkout.txt: move OPTIONS after COMMANDS
  Documentation/git-sparse-checkout.txt: some reword and modifications
  Documentation/git-sparse-checkout.txt: some reword and modifications

 Documentation/git-sparse-checkout.txt | 88 +++++++++++++--------------
 1 file changed, 44 insertions(+), 44 deletions(-)


base-commit: 4b89a3392b04acccf28f09f90e26715140461373
-- 
2.35.1

[PATCH v5 1/4] Documentation/git-sparse-checkout.txt: add an OPTIONS section

[Shaoxuan Yuan]

Add an OPTIONS section to the manual and move the descriptions about
these options from COMMANDS to the section.

Signed-off-by: Shaoxuan Yuan <shaoxuan.yuan02@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 63 +++++++++++++++++----------
 1 file changed, 39 insertions(+), 24 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index e4a29a2baa..5db5c0ab47 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -35,30 +35,11 @@ COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN
 THE FUTURE.
 
 
-COMMANDS
---------
-'list'::
-	Describe the directories or patterns in the sparse-checkout file.
-
-'set'::
-	Enable the necessary sparse-checkout config settings
-	(`core.sparseCheckout`, `core.sparseCheckoutCone`, and
-	`index.sparse`) if they are not already set to the desired values,
-	populate the sparse-checkout file from the list of arguments
-	following the 'set' subcommand, and update the working directory to
-	match.
-+
-To ensure that adjusting the sparse-checkout settings within a worktree
-does not alter the sparse-checkout settings in other worktrees, the 'set'
-subcommand will upgrade your repository config to use worktree-specific
-config if not already present. The sparsity defined by the arguments to
-the 'set' subcommand are stored in the worktree-specific sparse-checkout
-file. See linkgit:git-worktree[1] and the documentation of
-`extensions.worktreeConfig` in linkgit:git-config[1] for more details.
-+
-When the `--stdin` option is provided, the directories or patterns are
-read from standard in as a newline-delimited list instead of from the
-arguments.
+OPTIONS
+-------
+'--[no-]cone'::
+	Use with ['set'|'reapply'].
+	Specify using cone mode or not. The default is to use cone mode.
 +
 By default, the input list is considered a list of directories, matching
 the output of `git ls-tree -d --name-only`.  This includes interpreting
@@ -78,6 +59,11 @@ with the `--sparse-index` option, and will likely be incompatible with
 other new features as they are added.  See the "Non-cone Problems"
 section below and the "Sparse Checkout" section of
 linkgit:git-read-tree[1] for more details.
+
+'--[no-]sparse-index'::
+	Use with ['set'|'reapply'].
+	Specify using a sparse index or not. The default is to not use a
+	sparse index.
 +
 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
@@ -94,6 +80,35 @@ 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.
 
+'--stdin'::
+	Use with ['set'|'add'].
++
+When the `--stdin` option is provided, the directories or patterns are
+read from standard in as a newline-delimited list instead of from the
+arguments.
+
+
+COMMANDS
+--------
+'list'::
+	Describe the directories or patterns in the sparse-checkout file.
+
+'set'::
+	Enable the necessary sparse-checkout config settings
+	(`core.sparseCheckout`, `core.sparseCheckoutCone`, and
+	`index.sparse`) if they are not already set to the desired values,
+	populate the sparse-checkout file from the list of arguments
+	following the 'set' subcommand, and update the working directory to
+	match.
++
+To ensure that adjusting the sparse-checkout settings within a worktree
+does not alter the sparse-checkout settings in other worktrees, the 'set'
+subcommand will upgrade your repository config to use worktree-specific
+config if not already present. The sparsity defined by the arguments to
+the 'set' subcommand are stored in the worktree-specific sparse-checkout
+file. See linkgit:git-worktree[1] and the documentation of
+`extensions.worktreeConfig` in linkgit:git-config[1] for more details.
+
 'add'::
 	Update the sparse-checkout file to include additional directories
 	(in cone mode) or patterns (in non-cone mode).  By default, these
-- 
2.35.1

[PATCH v5 2/4] Documentation/git-sparse-checkout.txt: move OPTIONS after COMMANDS

[Shaoxuan Yuan]

* move OPTIONS after COMMANDS
* add two sub-sections under option '--[no-]cone', one for command 'set' and
one for command 'reapply'
* change the command indicators from this style:

	Use with ['set'|'reapply'].

to this style:

	Use with the `set` and `reapply` commands.

Helped-by: Derrick Stolee <derrickstolee@github.com>
Signed-off-by: Shaoxuan Yuan <shaoxuan.yuan02@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 121 ++++++++++++++------------
 1 file changed, 63 insertions(+), 58 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 5db5c0ab47..b8f3b89b74 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -35,59 +35,6 @@ COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN
 THE FUTURE.
 
 
-OPTIONS
--------
-'--[no-]cone'::
-	Use with ['set'|'reapply'].
-	Specify using cone mode or not. The default is to use cone mode.
-+
-By default, the input list is considered a list of directories, matching
-the output of `git ls-tree -d --name-only`.  This includes interpreting
-pathnames that begin with a double quote (") as C-style quoted strings.
-Note that all files under the specified directories (at any depth) will
-be included in the sparse checkout, as well as files that are siblings
-of either the given directory or any of its ancestors (see 'CONE PATTERN
-SET' below for more details).  In the past, this was not the default,
-and `--cone` needed to be specified or `core.sparseCheckoutCone` needed
-to be enabled.
-+
-When `--no-cone` is passed, the input list is considered a list of
-patterns.  This mode is harder to use, and unless you can keep the
-number of patterns small, its design also scales poorly.  It used to be
-the default mode, but we do not recommend using it.  It does not work
-with the `--sparse-index` option, and will likely be incompatible with
-other new features as they are added.  See the "Non-cone Problems"
-section below and the "Sparse Checkout" section of
-linkgit:git-read-tree[1] for more details.
-
-'--[no-]sparse-index'::
-	Use with ['set'|'reapply'].
-	Specify using a sparse index or not. The default is to not use a
-	sparse index.
-+
-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
-with this compatibility, then run `git sparse-checkout init --no-sparse-index`
-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.
-
-'--stdin'::
-	Use with ['set'|'add'].
-+
-When the `--stdin` option is provided, the directories or patterns are
-read from standard in as a newline-delimited list instead of from the
-arguments.
-
-
 COMMANDS
 --------
 'list'::
@@ -124,11 +71,6 @@ file. See linkgit:git-worktree[1] and the documentation of
 	cases, it can make sense to run `git sparse-checkout reapply` later
 	after cleaning up affected paths (e.g. resolving conflicts, undoing
 	or committing changes, etc.).
-+
-The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`
-flags, with the same meaning as the flags from the `set` command, in order
-to change which sparsity mode you are using without needing to also respecify
-all sparsity paths.
 
 'disable'::
 	Disable the `core.sparseCheckout` config setting, and restore the
@@ -154,6 +96,69 @@ 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.
 
+
+OPTIONS
+-------
+'--[no-]cone'::
+	Use with the `set` and `reapply` commands.
+	Specify using cone mode or not. The default is to use cone mode.
++
+For `set` command:
++
+By default, the input list is considered a list of directories, matching
+the output of `git ls-tree -d --name-only`.  This includes interpreting
+pathnames that begin with a double quote (") as C-style quoted strings.
+Note that all files under the specified directories (at any depth) will
+be included in the sparse checkout, as well as files that are siblings
+of either the given directory or any of its ancestors (see 'CONE PATTERN
+SET' below for more details).  In the past, this was not the default,
+and `--cone` needed to be specified or `core.sparseCheckoutCone` needed
+to be enabled.
++
+When `--no-cone` is passed, the input list is considered a list of
+patterns.  This mode is harder to use, and unless you can keep the
+number of patterns small, its design also scales poorly.  It used to be
+the default mode, but we do not recommend using it.  It does not work
+with the `--sparse-index` option, and will likely be incompatible with
+other new features as they are added.  See the "Non-cone Problems"
+section below and the "Sparse Checkout" section of
+linkgit:git-read-tree[1] for more details.
++
+For `reapply` command:
++
+The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`
+flags, with the same meaning as the flags from the `set` command, in order
+to change which sparsity mode you are using without needing to also respecify
+all sparsity paths.
+
+'--[no-]sparse-index'::
+	Use with the `set` and `reapply` commands.
+	Specify using a sparse index or not. The default is to not use a
+	sparse index.
++
+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
+with this compatibility, then run `git sparse-checkout init --no-sparse-index`
+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.
+
+'--stdin'::
+	Use with the `set` and `add` commands.
++
+When the `--stdin` option is provided, the directories or patterns are
+read from standard in as a newline-delimited list instead of from the
+arguments.
+
+
 EXAMPLES
 --------
 `git sparse-checkout set MY/DIR1 SUB/DIR2`::
-- 
2.35.1

[PATCH v5 3/4] Documentation/git-sparse-checkout.txt: some reword and modifications

[Shaoxuan Yuan]

Some changes according to Derrick [1]

* added a paragraph that breifly touches on the input of 'set' command
* refer to the 'set' command when talking about 'add' command
* condense the '--[no-]cone' section
* remove 'For `reapply` command' section under '--[no-]cone' section

[1] https://lore.kernel.org/git/307ac60d-b0a1-ea90-8118-a4e02b809102@github.com/

Helped-by: Derrick Stolee <derrickstolee@github.com>
Signed-off-by: Shaoxuan Yuan <shaoxuan.yuan02@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 44 +++++++++------------------
 1 file changed, 15 insertions(+), 29 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index b8f3b89b74..0178d63f56 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -48,6 +48,14 @@ COMMANDS
 	following the 'set' subcommand, and update the working directory to
 	match.
 +
+By default, the arguments to the `set` command are interpreted as a
+list of directories. The sparse-checkout patterns are set to match
+all files within those directories, recursively, as well as any file
+directly contained in a parent of those directories. See INTERNALS
+-- CONE PATTERN SET below for full details. If --no-cone is specified,
+then the arguments are interpreted as sparse-checkout patterns. See
+INTERNALS -- FULL PATTERN SET below for more information.
++
 To ensure that adjusting the sparse-checkout settings within a worktree
 does not alter the sparse-checkout settings in other worktrees, the 'set'
 subcommand will upgrade your repository config to use worktree-specific
@@ -59,8 +67,10 @@ file. See linkgit:git-worktree[1] and the documentation of
 'add'::
 	Update the sparse-checkout file to include additional directories
 	(in cone mode) or patterns (in non-cone mode).  By default, these
-	directories or patterns are read from the command-line arguments,
-	but they can be read from stdin using the `--stdin` option.
+	directories or patterns are read from the command-line arguments.
+  These directories or patterns are interpreted the same way as stated
+  above in `set` command, and they can be read from stdin using the
+  `--stdin` option.
 
 'reapply'::
 	Reapply the sparsity pattern rules to paths in the working tree.
@@ -103,33 +113,9 @@ OPTIONS
 	Use with the `set` and `reapply` commands.
 	Specify using cone mode or not. The default is to use cone mode.
 +
-For `set` command:
-+
-By default, the input list is considered a list of directories, matching
-the output of `git ls-tree -d --name-only`.  This includes interpreting
-pathnames that begin with a double quote (") as C-style quoted strings.
-Note that all files under the specified directories (at any depth) will
-be included in the sparse checkout, as well as files that are siblings
-of either the given directory or any of its ancestors (see 'CONE PATTERN
-SET' below for more details).  In the past, this was not the default,
-and `--cone` needed to be specified or `core.sparseCheckoutCone` needed
-to be enabled.
-+
-When `--no-cone` is passed, the input list is considered a list of
-patterns.  This mode is harder to use, and unless you can keep the
-number of patterns small, its design also scales poorly.  It used to be
-the default mode, but we do not recommend using it.  It does not work
-with the `--sparse-index` option, and will likely be incompatible with
-other new features as they are added.  See the "Non-cone Problems"
-section below and the "Sparse Checkout" section of
-linkgit:git-read-tree[1] for more details.
-+
-For `reapply` command:
-+
-The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`
-flags, with the same meaning as the flags from the `set` command, in order
-to change which sparsity mode you are using without needing to also respecify
-all sparsity paths.
+For the `set` command, the option to use cone mode or not changes
+the interpretation of the remaining arguments to either be a list
+of directories or a list of patterns.
 
 '--[no-]sparse-index'::
 	Use with the `set` and `reapply` commands.
-- 
2.35.1

[PATCH v5 4/4] Documentation/git-sparse-checkout.txt: some reword and modifications

[Shaoxuan Yuan]

Modifications suggested by Junio [1]

* remove redundant part under 'add' command
* fix broken indentation
* remove redundant part under '--[no-]cone' option

[1] https://lore.kernel.org/git/xmqqfsnfb42c.fsf@gitster.g/

Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Shaoxuan Yuan <shaoxuan.yuan02@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 12 +++---------
 1 file changed, 3 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 0178d63f56..482ecfe28c 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -66,11 +66,9 @@ file. See linkgit:git-worktree[1] and the documentation of
 
 'add'::
 	Update the sparse-checkout file to include additional directories
-	(in cone mode) or patterns (in non-cone mode).  By default, these
-	directories or patterns are read from the command-line arguments.
-  These directories or patterns are interpreted the same way as stated
-  above in `set` command, and they can be read from stdin using the
-  `--stdin` option.
+	(in cone mode) or patterns (in non-cone mode). By default, these
+	directories or patterns are read from the command-line arguments,
+	but they can be read from stdin using the `--stdin` option.
 
 'reapply'::
 	Reapply the sparsity pattern rules to paths in the working tree.
@@ -112,10 +110,6 @@ OPTIONS
 '--[no-]cone'::
 	Use with the `set` and `reapply` commands.
 	Specify using cone mode or not. The default is to use cone mode.
-+
-For the `set` command, the option to use cone mode or not changes
-the interpretation of the remaining arguments to either be a list
-of directories or a list of patterns.
 
 '--[no-]sparse-index'::
 	Use with the `set` and `reapply` commands.
-- 
2.35.1

Re: [PATCH v5 0/4] Documentation/git-sparse-checkout.txt: add an OPTIONS section

[Derrick Stolee]

On 3/19/22 2:19 AM, Shaoxuan Yuan wrote:
> == Updates Log ==
> 
> Changes since v4
> 
>  * ship a multi-patch series to reflect the history
>  * base on Elijah's series [1]
>  * changes according to Junio [2]
> 
> [1] https://lore.kernel.org/git/pull.1148.v2.git.1647054681.gitgitgadget@gmail.com/
> [2] https://lore.kernel.org/git/xmqqfsnfb42c.fsf@gitster.g/
> 
> == Overview ==
> 
> Add an OPTIONS section to the manual. Also provide corresponding text changes
> for better understanding the topic.
> Shaoxuan Yuan (4):
>   Documentation/git-sparse-checkout.txt: add an OPTIONS section
>   Documentation/git-sparse-checkout.txt: move OPTIONS after COMMANDS
>   Documentation/git-sparse-checkout.txt: some reword and modifications
>   Documentation/git-sparse-checkout.txt: some reword and modifications

Hi Shaoxuan,

This commit organization seems to be one that you created naturally from
responding to feedback. Unfortunately, we expect that each patch is
expected to be created with the intent of presenting changes in an
efficient way. This helps both with review and future history
investigations. See Documentation/SubmittingPatches for more information.

In particular, patches 2-4 are of the mode "Modify the changes from patch
1 based on feedback". Instead, we expect that you update that single patch
unless there is a clear reason why two separate changes are valuable.

When submitting new versions to a series, adding a range-diff to your
cover letter helps reviewers see what changed between versions, so we
still see how you responded to our feedback in a more isolated way.

I took your changes and applied them to en/sparse-cone-becomes-default and
got the diff below end-to-end. This is much easier to read. It also makes
some things clear (like an unnecessary whitespace change).

I think that this diff would be better served as a single patch. I'll
review this diff inline below:


> diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
> index e4a29a2baa9..482ecfe28c5 100644
> --- a/Documentation/git-sparse-checkout.txt
> +++ b/Documentation/git-sparse-checkout.txt
> @@ -48,6 +48,14 @@ COMMANDS
>  	following the 'set' subcommand, and update the working directory to
>  	match.
>  +
> +By default, the arguments to the `set` command are interpreted as a
> +list of directories. The sparse-checkout patterns are set to match
> +all files within those directories, recursively, as well as any file
> +directly contained in a parent of those directories. See INTERNALS
> +-- CONE PATTERN SET below for full details. If --no-cone is specified,
> +then the arguments are interpreted as sparse-checkout patterns. See
> +INTERNALS -- FULL PATTERN SET below for more information.
> ++
>  To ensure that adjusting the sparse-checkout settings within a worktree
>  does not alter the sparse-checkout settings in other worktrees, the 'set'
>  subcommand will upgrade your repository config to use worktree-specific
> @@ -55,48 +63,10 @@ config if not already present. The sparsity defined by the arguments to
>  the 'set' subcommand are stored in the worktree-specific sparse-checkout
>  file. See linkgit:git-worktree[1] and the documentation of
>  `extensions.worktreeConfig` in linkgit:git-config[1] for more details.
> -+
> -When the `--stdin` option is provided, the directories or patterns are
> -read from standard in as a newline-delimited list instead of from the
> -arguments.
> -+
> -By default, the input list is considered a list of directories, matching
> -the output of `git ls-tree -d --name-only`.  This includes interpreting
> -pathnames that begin with a double quote (") as C-style quoted strings.
> -Note that all files under the specified directories (at any depth) will
> -be included in the sparse checkout, as well as files that are siblings
> -of either the given directory or any of its ancestors (see 'CONE PATTERN
> -SET' below for more details).  In the past, this was not the default,
> -and `--cone` needed to be specified or `core.sparseCheckoutCone` needed
> -to be enabled.
> -+
> -When `--no-cone` is passed, the input list is considered a list of
> -patterns.  This mode is harder to use, and unless you can keep the
> -number of patterns small, its design also scales poorly.  It used to be
> -the default mode, but we do not recommend using it.  It does not work
> -with the `--sparse-index` option, and will likely be incompatible with
> -other new features as they are added.  See the "Non-cone Problems"
> -section below and the "Sparse Checkout" section of
> -linkgit:git-read-tree[1] for more details.
> -+
> -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
> -with this compatibility, then run `git sparse-checkout init --no-sparse-index`
> -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.
>  
>  'add'::
>  	Update the sparse-checkout file to include additional directories
> -	(in cone mode) or patterns (in non-cone mode).  By default, these
> +	(in cone mode) or patterns (in non-cone mode). By default, these

This whitespace change doesn't need to be here. I do think a single space
is more common in our docs, but it has no effect on the rendered docs, so
this is unnecessary noise for the diff.

>  	directories or patterns are read from the command-line arguments,
>  	but they can be read from stdin using the `--stdin` option.
>  
> @@ -109,11 +79,6 @@ interact with your repository until it is disabled.
>  	cases, it can make sense to run `git sparse-checkout reapply` later
>  	after cleaning up affected paths (e.g. resolving conflicts, undoing
>  	or committing changes, etc.).
> -+
> -The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`
> -flags, with the same meaning as the flags from the `set` command, in order
> -to change which sparsity mode you are using without needing to also respecify
> -all sparsity paths.
>  
>  'disable'::
>  	Disable the `core.sparseCheckout` config setting, and restore the
> @@ -139,6 +104,41 @@ 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.
>  
> +
> +OPTIONS
> +-------
> +'--[no-]cone'::
> +	Use with the `set` and `reapply` commands.
> +	Specify using cone mode or not. The default is to use cone mode.
> +
> +'--[no-]sparse-index'::
> +	Use with the `set` and `reapply` commands.
> +	Specify using a sparse index or not. The default is to not use a
> +	sparse index.
> ++
> +Use the `--[no-]sparse-index` option to use a sparse index (the

I find this a bit confusing. Maybe just "`--sparse-index`" would make
it clear that leaving out the [no-] is for enabling it.

> +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
> +with this compatibility, then run `git sparse-checkout init --no-sparse-index`
> +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.
> +
> +'--stdin'::
> +	Use with the `set` and `add` commands.
> ++
> +When the `--stdin` option is provided, the directories or patterns are
> +read from standard in as a newline-delimited list instead of from the
> +arguments.
> +
> +

I find it a lot easier to see these options being moved and updated at the
same time.

Thanks,
-Stolee