Add an OPTIONS section to the manual and move the descriptions about
these options from COMMANDS to the section.
Helped-by: Derrick Stolee <derrickstolee@xxxxxxxxxx>
Signed-off-by: Shaoxuan Yuan <shaoxuan.yuan02@xxxxxxxxx>
---
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
