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