{"thread":{"id":"57539","subject":"[RFC PATCH 0/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section","startedAt":"2022-03-11T13:22:26Z","lastAt":"2022-03-22T15:05:18Z","messageCount":18,"participants":["Shaoxuan Yuan","Derrick Stolee","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":1},"messages":[{"id":"451125","messageId":"20220311132141.1817-1-shaoxuan.yuan02@gmail.com","threadId":"57539","inReplyTo":null,"subject":"[RFC PATCH 0/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section","fromName":"Shaoxuan Yuan","fromEmail":"shaoxuan.yuan02@gmail.com","sentAt":"2022-03-11T13:21:40Z","receivedAt":"2022-03-11T13:22:26Z","isPatch":true,"sender":{"key":"shaoxuan.yuan02@gmail.com","avatar":"https://avatars.githubusercontent.com/u/46557895?v=4"},"body":"Add an OPTIONS section to the manual and move the descriptions/explanations for \nthese options from below COMMANDS to OPTIONS. \n\nThis patch is based on Elijah's series [1].\n\n[1] https://lore.kernel.org/git/pull.1148.git.1646725188.gitgitgadget@gmail.com/\n\nShaoxuan Yuan (1):\n  Documentation/git-sparse-checkout.txt: add an OPTIONS section\n\n Documentation/git-sparse-checkout.txt | 63 +++++++++++++++++----------\n 1 file changed, 39 insertions(+), 24 deletions(-)\n\n\nbase-commit: b5b154774abc80247a09c488c5125d328153c1cb\n-- \n2.35.1\n"},{"id":"451126","messageId":"20220311132141.1817-2-shaoxuan.yuan02@gmail.com","threadId":"57539","inReplyTo":"20220311132141.1817-1-shaoxuan.yuan02@gmail.com","subject":"[RFC PATCH 1/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section","fromName":"Shaoxuan Yuan","fromEmail":"shaoxuan.yuan02@gmail.com","sentAt":"2022-03-11T13:21:41Z","receivedAt":"2022-03-11T13:22:28Z","isPatch":true,"sender":{"key":"shaoxuan.yuan02@gmail.com","avatar":"https://avatars.githubusercontent.com/u/46557895?v=4"},"body":"Add an OPTIONS section to the manual and move the descriptions about\nthese options from COMMANDS to the section.\n\nSigned-off-by: Shaoxuan Yuan <shaoxuan.yuan02@gmail.com>\n---\n Documentation/git-sparse-checkout.txt | 63 +++++++++++++++++----------\n 1 file changed, 39 insertions(+), 24 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 06f23660f6..0bc742cb3a 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -35,30 +35,11 @@ COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN\n THE FUTURE.\n \n \n-COMMANDS\n---------\n-'list'::\n-\tDescribe the directories or patterns in the sparse-checkout file.\n-\n-'set'::\n-\tEnable the necessary sparse-checkout config settings\n-\t(`core.sparseCheckout`, `core.sparseCheckoutCone`, and\n-\t`index.sparse`) if they are not already set to the desired values,\n-\tpopulate the sparse-checkout file from the list of arguments\n-\tfollowing the 'set' subcommand, and update the working directory to\n-\tmatch.\n-+\n-To ensure that adjusting the sparse-checkout settings within a worktree\n-does not alter the sparse-checkout settings in other worktrees, the 'set'\n-subcommand will upgrade your repository config to use worktree-specific\n-config if not already present. The sparsity defined by the arguments to\n-the 'set' subcommand are stored in the worktree-specific sparse-checkout\n-file. See linkgit:git-worktree[1] and the documentation of\n-`extensions.worktreeConfig` in linkgit:git-config[1] for more details.\n-+\n-When the `--stdin` option is provided, the directories or patterns are\n-read from standard in as a newline-delimited list instead of from the\n-arguments.\n+OPTIONS\n+-------\n+'--[no-]cone'::\n+\tUse with ['set'|'reapply'].\n+\tSpecify using cone mode or not. The default is to use cone mode.\n +\n By default, the input list is considered a list of directories, matching\n the output of `git ls-tree -d --name-only`.  This includes interpreting\n@@ -78,6 +59,11 @@ with the `--sparse-index` option, and will likely be incompatible with\n other new features as they are added.  See the \"Non-cone Problems\"\n section below and the \"Sparse Checkout\" section of\n linkgit:git-read-tree[1] for more details.\n+\n+'--[no-]sparse-index'::\n+\tUse with ['set'|'reapply'].\n+\tSpecify using a sparse index or not. The default is to not use a \n+\tsparse index.\n +\n Use the `--[no-]sparse-index` option to use a sparse index (the\n default is to not use it).  A sparse index reduces the size of the\n@@ -94,6 +80,35 @@ to rewrite your index to not be sparse. Older versions of Git will not\n understand the sparse directory entries index extension and may fail to\n interact with your repository until it is disabled.\n \n+'--stdin'::\n+\tUse with ['set'|'add'].\n++\n+When the `--stdin` option is provided, the directories or patterns are\n+read from standard in as a newline-delimited list instead of from the\n+arguments.\n+\n+\n+COMMANDS\n+--------\n+'list'::\n+\tDescribe the directories or patterns in the sparse-checkout file.\n+\n+'set'::\n+\tEnable the necessary sparse-checkout config settings\n+\t(`core.sparseCheckout`, `core.sparseCheckoutCone`, and\n+\t`index.sparse`) if they are not already set to the desired values,\n+\tpopulate the sparse-checkout file from the list of arguments\n+\tfollowing the 'set' subcommand, and update the working directory to\n+\tmatch.\n++\n+To ensure that adjusting the sparse-checkout settings within a worktree\n+does not alter the sparse-checkout settings in other worktrees, the 'set'\n+subcommand will upgrade your repository config to use worktree-specific\n+config if not already present. The sparsity defined by the arguments to\n+the 'set' subcommand are stored in the worktree-specific sparse-checkout\n+file. See linkgit:git-worktree[1] and the documentation of\n+`extensions.worktreeConfig` in linkgit:git-config[1] for more details.\n+\n 'add'::\n \tUpdate the sparse-checkout file to include additional directories\n \t(in cone mode) or patterns (in non-cone mode).  By default, these\n-- \n2.35.1\n\n"},{"id":"451162","messageId":"dd9413da-1b8c-2adf-c471-e5fd4230375c@github.com","threadId":"57539","inReplyTo":"20220311132141.1817-2-shaoxuan.yuan02@gmail.com","subject":"Re: [RFC PATCH 1/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section","fromName":"Derrick Stolee","fromEmail":"derrickstolee@github.com","sentAt":"2022-03-11T20:56:41Z","receivedAt":"2022-03-11T20:57:23Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"On 3/11/2022 8:21 AM, Shaoxuan Yuan wrote:\n> Add an OPTIONS section to the manual and move the descriptions about\n> these options from COMMANDS to the section.\n\nThis is a good goal.\n\n> +OPTIONS\n> +-------\n\nHowever, there are a few issues with the current approach. First, I\nbelieve it would be better to start with COMMANDS, then OPTIONS.\n\nTo be fair, we are not consistent here. These commands use OPTIONS\nand then COMMANDS:\n\n* git-commit-graph.txt\n* git-remote.txt\n* git-revert.txt\n\nThese use [SUB]COMMANDS and then OPTIONS:\n\n* git-maintenance.txt\n* git-notes.txt\n* git-p4.txt\n* git-stash.txt\n* git-submodule.txt\n* git-worktree.txt\n\nMy preference would be OPTIONS second (and we can clean up the\nother docs as #leftoverbits). In particular, I noticed that\nthe SYNOPSIS for git-maintenance.txt is out of date.\t\n\n> +'--[no-]cone'::\n> +\tUse with ['set'|'reapply'].\n> +\tSpecify using cone mode or not. The default is to use cone mode.\n>  +\n>  By default, the input list is considered a list of directories, matching\n>  the output of `git ls-tree -d --name-only`.  This includes interpreting\n\nThe other issue is that this context is detailing information about\nthe 'set' command and the input it takes. You'll want to make sure\nthe information is properly grouped.\n\n> @@ -78,6 +59,11 @@ with the `--sparse-index` option, and will likely be incompatible with\n>  other new features as they are added.  See the \"Non-cone Problems\"\n>  section below and the \"Sparse Checkout\" section of\n>  linkgit:git-read-tree[1] for more details.\n> +\n> +'--[no-]sparse-index'::\n> +\tUse with ['set'|'reapply'].\n\nI do like these clear indicators of which commands allow this\noption. I wonder if it should instead be\n\n\tUse with the `set` and `reapply` commands.\n\nThanks,\n-Stolee\n"},{"id":"451285","messageId":"20220314063434.81895-1-shaoxuan.yuan02@gmail.com","threadId":"57539","inReplyTo":"20220311132141.1817-1-shaoxuan.yuan02@gmail.com","subject":"[PATCH v2 0/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section","fromName":"Shaoxuan Yuan","fromEmail":"shaoxuan.yuan02@gmail.com","sentAt":"2022-03-14T06:34:33Z","receivedAt":"2022-03-14T06:34:44Z","isPatch":true,"sender":{"key":"shaoxuan.yuan02@gmail.com","avatar":"https://avatars.githubusercontent.com/u/46557895?v=4"},"body":"== Updates Log ==\n\nChanges since v1:\n\n * rebase on Elijah's v2 [1]\n * move OPTIONS to after COMMANDS\n * add two sub-sections under option '--[no-]cone', one for command 'set' and\none for command 'reapply'\n * change the command indicators from this style:\n\n  Use with ['set'|'reapply'].\n\n  to this style:\n\n  Use with the `set` and `reapply` commands.\n\n== Overview ==\n\nAdd an OPTIONS section to the manual and move the descriptions/explanations for \nthese options from below COMMANDS to OPTIONS. \n\n[1] https://lore.kernel.org/git/pull.1148.v2.git.1647054681.gitgitgadget@gmail.com/#r\n\nShaoxuan Yuan (1):\n  Documentation/git-sparse-checkout.txt: add an OPTIONS section\n\n Documentation/git-sparse-checkout.txt | 106 +++++++++++++++-----------\n 1 file changed, 63 insertions(+), 43 deletions(-)\n\n\nbase-commit: 4b89a3392b04acccf28f09f90e26715140461373\n-- \n2.35.1\n\n"},{"id":"451286","messageId":"20220314063434.81895-2-shaoxuan.yuan02@gmail.com","threadId":"57539","inReplyTo":"20220314063434.81895-1-shaoxuan.yuan02@gmail.com","subject":"[PATCH v2 1/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section","fromName":"Shaoxuan Yuan","fromEmail":"shaoxuan.yuan02@gmail.com","sentAt":"2022-03-14T06:34:34Z","receivedAt":"2022-03-14T06:34:46Z","isPatch":true,"sender":{"key":"shaoxuan.yuan02@gmail.com","avatar":"https://avatars.githubusercontent.com/u/46557895?v=4"},"body":"Add an OPTIONS section to the manual and move the descriptions about\nthese options from COMMANDS to the section.\n\nHelped-by: Derick Stolee <derrickstolee@github.com>\nSigned-off-by: Shaoxuan Yuan <shaoxuan.yuan02@gmail.com>\n---\n Documentation/git-sparse-checkout.txt | 106 +++++++++++++++-----------\n 1 file changed, 63 insertions(+), 43 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex e4a29a2baa..b8f3b89b74 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -55,44 +55,6 @@ config if not already present. The sparsity defined by the arguments to\n the 'set' subcommand are stored in the worktree-specific sparse-checkout\n file. See linkgit:git-worktree[1] and the documentation of\n `extensions.worktreeConfig` in linkgit:git-config[1] for more details.\n-+\n-When the `--stdin` option is provided, the directories or patterns are\n-read from standard in as a newline-delimited list instead of from the\n-arguments.\n-+\n-By default, the input list is considered a list of directories, matching\n-the output of `git ls-tree -d --name-only`.  This includes interpreting\n-pathnames that begin with a double quote (\") as C-style quoted strings.\n-Note that all files under the specified directories (at any depth) will\n-be included in the sparse checkout, as well as files that are siblings\n-of either the given directory or any of its ancestors (see 'CONE PATTERN\n-SET' below for more details).  In the past, this was not the default,\n-and `--cone` needed to be specified or `core.sparseCheckoutCone` needed\n-to be enabled.\n-+\n-When `--no-cone` is passed, the input list is considered a list of\n-patterns.  This mode is harder to use, and unless you can keep the\n-number of patterns small, its design also scales poorly.  It used to be\n-the default mode, but we do not recommend using it.  It does not work\n-with the `--sparse-index` option, and will likely be incompatible with\n-other new features as they are added.  See the \"Non-cone Problems\"\n-section below and the \"Sparse Checkout\" section of\n-linkgit:git-read-tree[1] for more details.\n-+\n-Use the `--[no-]sparse-index` option to use a sparse index (the\n-default is to not use it).  A sparse index reduces the size of the\n-index to be more closely aligned with your sparse-checkout\n-definition. This can have significant performance advantages for\n-commands such as `git status` or `git add`.  This feature is still\n-experimental. Some commands might be slower with a sparse index until\n-they are properly integrated with the feature.\n-+\n-**WARNING:** Using a sparse index requires modifying the index in a way\n-that is not completely understood by external tools. If you have trouble\n-with this compatibility, then run `git sparse-checkout init --no-sparse-index`\n-to rewrite your index to not be sparse. Older versions of Git will not\n-understand the sparse directory entries index extension and may fail to\n-interact with your repository until it is disabled.\n \n 'add'::\n \tUpdate the sparse-checkout file to include additional directories\n@@ -109,11 +71,6 @@ interact with your repository until it is disabled.\n \tcases, it can make sense to run `git sparse-checkout reapply` later\n \tafter cleaning up affected paths (e.g. resolving conflicts, undoing\n \tor committing changes, etc.).\n-+\n-The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`\n-flags, with the same meaning as the flags from the `set` command, in order\n-to change which sparsity mode you are using without needing to also respecify\n-all sparsity paths.\n \n 'disable'::\n \tDisable the `core.sparseCheckout` config setting, and restore the\n@@ -139,6 +96,69 @@ paths to pass to a subsequent 'set' or 'add' command.  However,\n the disable command, so the easy restore of calling a plain `init`\n decreased in utility.\n \n+\n+OPTIONS\n+-------\n+'--[no-]cone'::\n+\tUse with the `set` and `reapply` commands.\n+\tSpecify using cone mode or not. The default is to use cone mode.\n++\n+For `set` command:\n++\n+By default, the input list is considered a list of directories, matching\n+the output of `git ls-tree -d --name-only`.  This includes interpreting\n+pathnames that begin with a double quote (\") as C-style quoted strings.\n+Note that all files under the specified directories (at any depth) will\n+be included in the sparse checkout, as well as files that are siblings\n+of either the given directory or any of its ancestors (see 'CONE PATTERN\n+SET' below for more details).  In the past, this was not the default,\n+and `--cone` needed to be specified or `core.sparseCheckoutCone` needed\n+to be enabled.\n++\n+When `--no-cone` is passed, the input list is considered a list of\n+patterns.  This mode is harder to use, and unless you can keep the\n+number of patterns small, its design also scales poorly.  It used to be\n+the default mode, but we do not recommend using it.  It does not work\n+with the `--sparse-index` option, and will likely be incompatible with\n+other new features as they are added.  See the \"Non-cone Problems\"\n+section below and the \"Sparse Checkout\" section of\n+linkgit:git-read-tree[1] for more details.\n++\n+For `reapply` command:\n++\n+The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`\n+flags, with the same meaning as the flags from the `set` command, in order\n+to change which sparsity mode you are using without needing to also respecify\n+all sparsity paths.\n+\n+'--[no-]sparse-index'::\n+\tUse with the `set` and `reapply` commands.\n+\tSpecify using a sparse index or not. The default is to not use a\n+\tsparse index.\n++\n+Use the `--[no-]sparse-index` option to use a sparse index (the\n+default is to not use it).  A sparse index reduces the size of the\n+index to be more closely aligned with your sparse-checkout\n+definition. This can have significant performance advantages for\n+commands such as `git status` or `git add`.  This feature is still\n+experimental. Some commands might be slower with a sparse index until\n+they are properly integrated with the feature.\n++\n+**WARNING:** Using a sparse index requires modifying the index in a way\n+that is not completely understood by external tools. If you have trouble\n+with this compatibility, then run `git sparse-checkout init --no-sparse-index`\n+to rewrite your index to not be sparse. Older versions of Git will not\n+understand the sparse directory entries index extension and may fail to\n+interact with your repository until it is disabled.\n+\n+'--stdin'::\n+\tUse with the `set` and `add` commands.\n++\n+When the `--stdin` option is provided, the directories or patterns are\n+read from standard in as a newline-delimited list instead of from the\n+arguments.\n+\n+\n EXAMPLES\n --------\n `git sparse-checkout set MY/DIR1 SUB/DIR2`::\n-- \n2.35.1\n\n"},{"id":"451287","messageId":"20220314065659.82029-1-shaoxuan.yuan02@gmail.com","threadId":"57539","inReplyTo":"20220311132141.1817-1-shaoxuan.yuan02@gmail.com","subject":"[PATCH v3 0/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section","fromName":"Shaoxuan Yuan","fromEmail":"shaoxuan.yuan02@gmail.com","sentAt":"2022-03-14T06:56:58Z","receivedAt":"2022-03-14T06:57:14Z","isPatch":true,"sender":{"key":"shaoxuan.yuan02@gmail.com","avatar":"https://avatars.githubusercontent.com/u/46557895?v=4"},"body":"== Updates Log ==\n\nChanges since v2:\n\n * correct Derrick's name in the single-patch (I really missed it XD)\n * rebase on Elijah's v2 [1]\n * move OPTIONS to after COMMANDS\n * add two sub-sections under option '--[no-]cone', one for command 'set' and\none for command 'reapply'\n * change the command indicators from this style:\n\n  Use with ['set'|'reapply'].\n\n  to this style:\n\n  Use with the `set` and `reapply` commands.\n\n== Overview ==\n\nAdd an OPTIONS section to the manual and move the descriptions/explanations for \nthese options from below COMMANDS to OPTIONS. \n\n[1] https://lore.kernel.org/git/pull.1148.v2.git.1647054681.gitgitgadget@gmail.com/#r\n\nShaoxuan Yuan (1):\n  Documentation/git-sparse-checkout.txt: add an OPTIONS section\n\n Documentation/git-sparse-checkout.txt | 106 +++++++++++++++-----------\n 1 file changed, 63 insertions(+), 43 deletions(-)\n\n\nbase-commit: 4b89a3392b04acccf28f09f90e26715140461373\n-- \n2.35.1\n\n"},{"id":"451288","messageId":"20220314065659.82029-2-shaoxuan.yuan02@gmail.com","threadId":"57539","inReplyTo":"20220314065659.82029-1-shaoxuan.yuan02@gmail.com","subject":"[PATCH v3 1/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section","fromName":"Shaoxuan Yuan","fromEmail":"shaoxuan.yuan02@gmail.com","sentAt":"2022-03-14T06:56:59Z","receivedAt":"2022-03-14T06:57:16Z","isPatch":true,"sender":{"key":"shaoxuan.yuan02@gmail.com","avatar":"https://avatars.githubusercontent.com/u/46557895?v=4"},"body":"Add an OPTIONS section to the manual and move the descriptions about\nthese options from COMMANDS to the section.\n\nHelped-by: Derrick Stolee <derrickstolee@github.com>\nSigned-off-by: Shaoxuan Yuan <shaoxuan.yuan02@gmail.com>\n---\n Documentation/git-sparse-checkout.txt | 106 +++++++++++++++-----------\n 1 file changed, 63 insertions(+), 43 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex e4a29a2baa..b8f3b89b74 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -55,44 +55,6 @@ config if not already present. The sparsity defined by the arguments to\n the 'set' subcommand are stored in the worktree-specific sparse-checkout\n file. See linkgit:git-worktree[1] and the documentation of\n `extensions.worktreeConfig` in linkgit:git-config[1] for more details.\n-+\n-When the `--stdin` option is provided, the directories or patterns are\n-read from standard in as a newline-delimited list instead of from the\n-arguments.\n-+\n-By default, the input list is considered a list of directories, matching\n-the output of `git ls-tree -d --name-only`.  This includes interpreting\n-pathnames that begin with a double quote (\") as C-style quoted strings.\n-Note that all files under the specified directories (at any depth) will\n-be included in the sparse checkout, as well as files that are siblings\n-of either the given directory or any of its ancestors (see 'CONE PATTERN\n-SET' below for more details).  In the past, this was not the default,\n-and `--cone` needed to be specified or `core.sparseCheckoutCone` needed\n-to be enabled.\n-+\n-When `--no-cone` is passed, the input list is considered a list of\n-patterns.  This mode is harder to use, and unless you can keep the\n-number of patterns small, its design also scales poorly.  It used to be\n-the default mode, but we do not recommend using it.  It does not work\n-with the `--sparse-index` option, and will likely be incompatible with\n-other new features as they are added.  See the \"Non-cone Problems\"\n-section below and the \"Sparse Checkout\" section of\n-linkgit:git-read-tree[1] for more details.\n-+\n-Use the `--[no-]sparse-index` option to use a sparse index (the\n-default is to not use it).  A sparse index reduces the size of the\n-index to be more closely aligned with your sparse-checkout\n-definition. This can have significant performance advantages for\n-commands such as `git status` or `git add`.  This feature is still\n-experimental. Some commands might be slower with a sparse index until\n-they are properly integrated with the feature.\n-+\n-**WARNING:** Using a sparse index requires modifying the index in a way\n-that is not completely understood by external tools. If you have trouble\n-with this compatibility, then run `git sparse-checkout init --no-sparse-index`\n-to rewrite your index to not be sparse. Older versions of Git will not\n-understand the sparse directory entries index extension and may fail to\n-interact with your repository until it is disabled.\n \n 'add'::\n \tUpdate the sparse-checkout file to include additional directories\n@@ -109,11 +71,6 @@ interact with your repository until it is disabled.\n \tcases, it can make sense to run `git sparse-checkout reapply` later\n \tafter cleaning up affected paths (e.g. resolving conflicts, undoing\n \tor committing changes, etc.).\n-+\n-The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`\n-flags, with the same meaning as the flags from the `set` command, in order\n-to change which sparsity mode you are using without needing to also respecify\n-all sparsity paths.\n \n 'disable'::\n \tDisable the `core.sparseCheckout` config setting, and restore the\n@@ -139,6 +96,69 @@ paths to pass to a subsequent 'set' or 'add' command.  However,\n the disable command, so the easy restore of calling a plain `init`\n decreased in utility.\n \n+\n+OPTIONS\n+-------\n+'--[no-]cone'::\n+\tUse with the `set` and `reapply` commands.\n+\tSpecify using cone mode or not. The default is to use cone mode.\n++\n+For `set` command:\n++\n+By default, the input list is considered a list of directories, matching\n+the output of `git ls-tree -d --name-only`.  This includes interpreting\n+pathnames that begin with a double quote (\") as C-style quoted strings.\n+Note that all files under the specified directories (at any depth) will\n+be included in the sparse checkout, as well as files that are siblings\n+of either the given directory or any of its ancestors (see 'CONE PATTERN\n+SET' below for more details).  In the past, this was not the default,\n+and `--cone` needed to be specified or `core.sparseCheckoutCone` needed\n+to be enabled.\n++\n+When `--no-cone` is passed, the input list is considered a list of\n+patterns.  This mode is harder to use, and unless you can keep the\n+number of patterns small, its design also scales poorly.  It used to be\n+the default mode, but we do not recommend using it.  It does not work\n+with the `--sparse-index` option, and will likely be incompatible with\n+other new features as they are added.  See the \"Non-cone Problems\"\n+section below and the \"Sparse Checkout\" section of\n+linkgit:git-read-tree[1] for more details.\n++\n+For `reapply` command:\n++\n+The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`\n+flags, with the same meaning as the flags from the `set` command, in order\n+to change which sparsity mode you are using without needing to also respecify\n+all sparsity paths.\n+\n+'--[no-]sparse-index'::\n+\tUse with the `set` and `reapply` commands.\n+\tSpecify using a sparse index or not. The default is to not use a\n+\tsparse index.\n++\n+Use the `--[no-]sparse-index` option to use a sparse index (the\n+default is to not use it).  A sparse index reduces the size of the\n+index to be more closely aligned with your sparse-checkout\n+definition. This can have significant performance advantages for\n+commands such as `git status` or `git add`.  This feature is still\n+experimental. Some commands might be slower with a sparse index until\n+they are properly integrated with the feature.\n++\n+**WARNING:** Using a sparse index requires modifying the index in a way\n+that is not completely understood by external tools. If you have trouble\n+with this compatibility, then run `git sparse-checkout init --no-sparse-index`\n+to rewrite your index to not be sparse. Older versions of Git will not\n+understand the sparse directory entries index extension and may fail to\n+interact with your repository until it is disabled.\n+\n+'--stdin'::\n+\tUse with the `set` and `add` commands.\n++\n+When the `--stdin` option is provided, the directories or patterns are\n+read from standard in as a newline-delimited list instead of from the\n+arguments.\n+\n+\n EXAMPLES\n --------\n `git sparse-checkout set MY/DIR1 SUB/DIR2`::\n-- \n2.35.1\n\n"},{"id":"451327","messageId":"307ac60d-b0a1-ea90-8118-a4e02b809102@github.com","threadId":"57539","inReplyTo":"20220314065659.82029-2-shaoxuan.yuan02@gmail.com","subject":"Re: [PATCH v3 1/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section","fromName":"Derrick Stolee","fromEmail":"derrickstolee@github.com","sentAt":"2022-03-14T16:13:11Z","receivedAt":"2022-03-14T16:13:31Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"On 3/14/2022 2:56 AM, Shaoxuan Yuan wrote:\n> Add an OPTIONS section to the manual and move the descriptions about\n> these options from COMMANDS to the section.\n> \n> Helped-by: Derrick Stolee <derrickstolee@github.com>\n> Signed-off-by: Shaoxuan Yuan <shaoxuan.yuan02@gmail.com>\n\nThank you for reorganizing the COMMANDS and OPTIONS. I still think\nthere is some improvement to be made here.\n\n>  the 'set' subcommand are stored in the worktree-specific sparse-checkout\n>  file. See linkgit:git-worktree[1] and the documentation of\n>  `extensions.worktreeConfig` in linkgit:git-config[1] for more details.\n\nJust to provide some extra context to the review, here is the content\nof the 'set' command up to this point:\n\n'set'::\n\tEnable the necessary sparse-checkout config settings\n\t(`core.sparseCheckout`, `core.sparseCheckoutCone`, and\n\t`index.sparse`) if they are not already set to the desired values,\n\tpopulate the sparse-checkout file from the list of arguments\n\tfollowing the 'set' subcommand, and update the working directory to\n\tmatch.\n+\nTo ensure that adjusting the sparse-checkout settings within a worktree\ndoes not alter the sparse-checkout settings in other worktrees, the 'set'\nsubcommand will upgrade your repository config to use worktree-specific\nconfig if not already present. The sparsity defined by the arguments to\nthe 'set' subcommand are stored in the worktree-specific sparse-checkout\nfile. See linkgit:git-worktree[1] and the documentation of\n`extensions.worktreeConfig` in linkgit:git-config[1] for more details.\n\n\nSo this mentions that we will \"write a set of patterns to the\nsparse-checkout file from the list of arguments\" but with the\ndeletions below we lose understanding of how the arguments match with\nthe patterns.\n\nI think it would be good to insert a paragraph between the two above\nparagraphs that briefly touches on the input. Something like:\n\n  By default, the arguments to the `set` command are interpreted as a\n  list of directories. The sparse-checkout patterns are set to match\n  all files within those directories, recursively, as well as any file\n  directly contained in a parent of those directories. See INTERNALS\n  -- CONE PATTERN SET below for full details. If --no-cone is specified,\n  then the arguments are interpreted as sparse-checkout patterns. See\n  INTERNALS -- FULL PATTERN SET below for more information.\n\nWe might need to refer to the `set` command input when talking about\nthe `add` command.\n\n>  'add'::\n>  \tUpdate the sparse-checkout file to include additional directories\n> @@ -109,11 +71,6 @@ interact with your repository until it is disabled.\n>  \tcases, it can make sense to run `git sparse-checkout reapply` later\n>  \tafter cleaning up affected paths (e.g. resolving conflicts, undoing\n>  \tor committing changes, etc.).\n> -+\n> -The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`\n> -flags, with the same meaning as the flags from the `set` command, in order\n> -to change which sparsity mode you are using without needing to also respecify\n> -all sparsity paths.\n>  \n>  'disable'::\n>  \tDisable the `core.sparseCheckout` config setting, and restore the\n> @@ -139,6 +96,69 @@ paths to pass to a subsequent 'set' or 'add' command.  However,\n>  the disable command, so the easy restore of calling a plain `init`\n>  decreased in utility.\n>  \n> +\n> +OPTIONS\n> +-------\n> +'--[no-]cone'::\n> +\tUse with the `set` and `reapply` commands.\n> +\tSpecify using cone mode or not. The default is to use cone mode.\n> ++\n> +For `set` command:\n> ++\n> +By default, the input list is considered a list of directories, matching\n> +the output of `git ls-tree -d --name-only`.  This includes interpreting\n> +pathnames that begin with a double quote (\") as C-style quoted strings.\n> +Note that all files under the specified directories (at any depth) will\n> +be included in the sparse checkout, as well as files that are siblings\n> +of either the given directory or any of its ancestors (see 'CONE PATTERN\n> +SET' below for more details).  In the past, this was not the default,\n> +and `--cone` needed to be specified or `core.sparseCheckoutCone` needed\n> +to be enabled.\n> ++\n> +When `--no-cone` is passed, the input list is considered a list of\n> +patterns.  This mode is harder to use, and unless you can keep the\n> +number of patterns small, its design also scales poorly.  It used to be\n> +the default mode, but we do not recommend using it.  It does not work\n> +with the `--sparse-index` option, and will likely be incompatible with\n> +other new features as they are added.  See the \"Non-cone Problems\"\n> +section below and the \"Sparse Checkout\" section of\n> +linkgit:git-read-tree[1] for more details.\n> ++\n\nWith the recommended change above, this pair of paragraphs can be\ncondensed. Something like...\n\n  For the `set` command, the option to use cone mode or not changes\n  the interpretation of the remaining arguments to either be a list\n  of directories or a list of patterns.\n\n> +For `reapply` command:\n> ++\n> +The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`\n> +flags, with the same meaning as the flags from the `set` command, in order\n> +to change which sparsity mode you are using without needing to also respecify\n> +all sparsity paths.\n\nI'm not sure that this mention of `reapply` is necessary, as those\noptions document themselves further down.\n\n> +\n> +'--[no-]sparse-index'::\n> +\tUse with the `set` and `reapply` commands.\n> +\tSpecify using a sparse index or not. The default is to not use a\n> +\tsparse index.\n> ++\n> +Use the `--[no-]sparse-index` option to use a sparse index (the\n> +default is to not use it).  A sparse index reduces the size of the\n> +index to be more closely aligned with your sparse-checkout\n> +definition. This can have significant performance advantages for\n> +commands such as `git status` or `git add`.  This feature is still\n> +experimental. Some commands might be slower with a sparse index until\n> +they are properly integrated with the feature.\n> ++\n> +**WARNING:** Using a sparse index requires modifying the index in a way\n> +that is not completely understood by external tools. If you have trouble\n> +with this compatibility, then run `git sparse-checkout init --no-sparse-index`\n> +to rewrite your index to not be sparse. Older versions of Git will not\n> +understand the sparse directory entries index extension and may fail to\n> +interact with your repository until it is disabled.\n> +\n> +'--stdin'::\n> +\tUse with the `set` and `add` commands.\n> ++\n> +When the `--stdin` option is provided, the directories or patterns are\n> +read from standard in as a newline-delimited list instead of from the\n> +arguments.\n\nThese options are excellent.\n\nThanks,\n-Stolee\n\n"},{"id":"451555","messageId":"20220317123718.480093-1-shaoxuan.yuan02@gmail.com","threadId":"57539","inReplyTo":"20220311132141.1817-1-shaoxuan.yuan02@gmail.com","subject":"[PATCH v4 0/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section","fromName":"Shaoxuan Yuan","fromEmail":"shaoxuan.yuan02@gmail.com","sentAt":"2022-03-17T12:37:17Z","receivedAt":"2022-03-17T12:37:28Z","isPatch":true,"sender":{"key":"shaoxuan.yuan02@gmail.com","avatar":"https://avatars.githubusercontent.com/u/46557895?v=4"},"body":"== Updates Log ==\n\nChanges since v3 (based on v3's single patch):\n\n * changes according to Derrick [1]\n\n== Overview ==\n\nAdd an OPTIONS section to the manual and move the descriptions/explanations for \nthese options from below COMMANDS to OPTIONS. \n\n[1] https://lore.kernel.org/git/307ac60d-b0a1-ea90-8118-a4e02b809102@github.com/\n\n\nShaoxuan Yuan (1):\n  Documentation/git-sparse-checkout.txt: add an OPTIONS section\n\n Documentation/git-sparse-checkout.txt | 44 +++++++++------------------\n 1 file changed, 15 insertions(+), 29 deletions(-)\n\nbase-commit: eb129e532a7c58ea34afeec70b0e2e029c0d5fee\n-- \n2.35.1\n"},{"id":"451556","messageId":"20220317123718.480093-2-shaoxuan.yuan02@gmail.com","threadId":"57539","inReplyTo":"20220317123718.480093-1-shaoxuan.yuan02@gmail.com","subject":"[PATCH v4 1/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section","fromName":"Shaoxuan Yuan","fromEmail":"shaoxuan.yuan02@gmail.com","sentAt":"2022-03-17T12:37:18Z","receivedAt":"2022-03-17T12:37:30Z","isPatch":true,"sender":{"key":"shaoxuan.yuan02@gmail.com","avatar":"https://avatars.githubusercontent.com/u/46557895?v=4"},"body":"Add an OPTIONS section to the manual and move the descriptions about\nthese options from COMMANDS to the section.\n\nHelped-by: Derrick Stolee <derrickstolee@github.com>\nSigned-off-by: Shaoxuan Yuan <shaoxuan.yuan02@gmail.com>\n---\n Documentation/git-sparse-checkout.txt | 44 +++++++++------------------\n 1 file changed, 15 insertions(+), 29 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex b8f3b89b74..0178d63f56 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -48,6 +48,14 @@ COMMANDS\n \tfollowing the 'set' subcommand, and update the working directory to\n \tmatch.\n +\n+By default, the arguments to the `set` command are interpreted as a\n+list of directories. The sparse-checkout patterns are set to match\n+all files within those directories, recursively, as well as any file\n+directly contained in a parent of those directories. See INTERNALS\n+-- CONE PATTERN SET below for full details. If --no-cone is specified,\n+then the arguments are interpreted as sparse-checkout patterns. See\n+INTERNALS -- FULL PATTERN SET below for more information.\n++\n To ensure that adjusting the sparse-checkout settings within a worktree\n does not alter the sparse-checkout settings in other worktrees, the 'set'\n subcommand will upgrade your repository config to use worktree-specific\n@@ -59,8 +67,10 @@ file. See linkgit:git-worktree[1] and the documentation of\n 'add'::\n \tUpdate the sparse-checkout file to include additional directories\n \t(in cone mode) or patterns (in non-cone mode).  By default, these\n-\tdirectories or patterns are read from the command-line arguments,\n-\tbut they can be read from stdin using the `--stdin` option.\n+\tdirectories or patterns are read from the command-line arguments.\n+  These directories or patterns are interpreted the same way as stated\n+  above in `set` command, and they can be read from stdin using the\n+  `--stdin` option.\n \n 'reapply'::\n \tReapply the sparsity pattern rules to paths in the working tree.\n@@ -103,33 +113,9 @@ OPTIONS\n \tUse with the `set` and `reapply` commands.\n \tSpecify using cone mode or not. The default is to use cone mode.\n +\n-For `set` command:\n-+\n-By default, the input list is considered a list of directories, matching\n-the output of `git ls-tree -d --name-only`.  This includes interpreting\n-pathnames that begin with a double quote (\") as C-style quoted strings.\n-Note that all files under the specified directories (at any depth) will\n-be included in the sparse checkout, as well as files that are siblings\n-of either the given directory or any of its ancestors (see 'CONE PATTERN\n-SET' below for more details).  In the past, this was not the default,\n-and `--cone` needed to be specified or `core.sparseCheckoutCone` needed\n-to be enabled.\n-+\n-When `--no-cone` is passed, the input list is considered a list of\n-patterns.  This mode is harder to use, and unless you can keep the\n-number of patterns small, its design also scales poorly.  It used to be\n-the default mode, but we do not recommend using it.  It does not work\n-with the `--sparse-index` option, and will likely be incompatible with\n-other new features as they are added.  See the \"Non-cone Problems\"\n-section below and the \"Sparse Checkout\" section of\n-linkgit:git-read-tree[1] for more details.\n-+\n-For `reapply` command:\n-+\n-The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`\n-flags, with the same meaning as the flags from the `set` command, in order\n-to change which sparsity mode you are using without needing to also respecify\n-all sparsity paths.\n+For the `set` command, the option to use cone mode or not changes\n+the interpretation of the remaining arguments to either be a list\n+of directories or a list of patterns.\n \n '--[no-]sparse-index'::\n \tUse with the `set` and `reapply` commands.\n-- \n2.35.1\n\n"},{"id":"451631","messageId":"xmqqmthnb4uq.fsf@gitster.g","threadId":"57539","inReplyTo":"20220317123718.480093-1-shaoxuan.yuan02@gmail.com","subject":"Re: [PATCH v4 0/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-03-18T16:30:37Z","receivedAt":"2022-03-18T16:31:03Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Shaoxuan Yuan <shaoxuan.yuan02@gmail.com> writes:\n\n> == Updates Log ==\n>\n> Changes since v3 (based on v3's single patch):\n>\n>  * changes according to Derrick [1]\n>\n> == Overview ==\n>\n> Add an OPTIONS section to the manual and move the descriptions/explanations for \n> these options from below COMMANDS to OPTIONS. \n>\n> [1] https://lore.kernel.org/git/307ac60d-b0a1-ea90-8118-a4e02b809102@github.com/\n>\n>\n> Shaoxuan Yuan (1):\n>   Documentation/git-sparse-checkout.txt: add an OPTIONS section\n>\n>  Documentation/git-sparse-checkout.txt | 44 +++++++++------------------\n>  1 file changed, 15 insertions(+), 29 deletions(-)\n>\n> base-commit: eb129e532a7c58ea34afeec70b0e2e029c0d5fee\n\nIt is not very helpful to give the name of an object that is not\npublicly available.  Basing a patch on some topics in flight is\nfine, but please clearly state what it is based on in a cover letter\n(if the topic is a multi-patch series) or below the three-dash line\n(if it is a single patch).\n\n"},{"id":"451632","messageId":"xmqqfsnfb42c.fsf@gitster.g","threadId":"57539","inReplyTo":"20220317123718.480093-2-shaoxuan.yuan02@gmail.com","subject":"Re: [PATCH v4 1/1] Documentation/git-sparse-checkout.txt: add an OPTIONS section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-03-18T16:47:39Z","receivedAt":"2022-03-18T16:47:44Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Shaoxuan Yuan <shaoxuan.yuan02@gmail.com> writes:\n\n> Add an OPTIONS section to the manual and move the descriptions about\n> these options from COMMANDS to the section.\n\nThe above description does not seem to match what the patch does at\nall, though.  Sent a wrong patch, possibly just the tip of a series,\nwhen you needed to send more than one patches?  For example, the\nheader for the hunk -103,33 tells us that the file already has OPTIONS\nsection before this patch gets applied.\n\n> @@ -48,6 +48,14 @@ COMMANDS\n>  \tfollowing the 'set' subcommand, and update the working directory to\n>  \tmatch.\n>  +\n> +By default, the arguments to the `set` command are interpreted as a\n> +list of directories. The sparse-checkout patterns are set to match\n> +all files within those directories, recursively, as well as any file\n> +directly contained in a parent of those directories. See INTERNALS\n> +-- CONE PATTERN SET below for full details. If --no-cone is specified,\n> +then the arguments are interpreted as sparse-checkout patterns. See\n> +INTERNALS -- FULL PATTERN SET below for more information.\n> ++\n>  To ensure that adjusting the sparse-checkout settings within a worktree\n\nThat reads well.\n\n> @@ -59,8 +67,10 @@ file. See linkgit:git-worktree[1] and the documentation of\n>  'add'::\n>  \tUpdate the sparse-checkout file to include additional directories\n>  \t(in cone mode) or patterns (in non-cone mode).  By default, these\n> -\tdirectories or patterns are read from the command-line arguments,\n> -\tbut they can be read from stdin using the `--stdin` option.\n> +\tdirectories or patterns are read from the command-line arguments.\n> +  These directories or patterns are interpreted the same way as stated\n> +  above in `set` command, and they can be read from stdin using the\n> +  `--stdin` option.\n\nThe original removed by the patch said \"directories or patterns\",\nand I understand that this change is an attempt to say that the\ncommand chooses between directories and patterns using the same\ncriteria as the \"set\" command, but the added \"are interpreted the\nsame way as ...\" in the middle interrupts the flow of thought the\nsentence conveys.  To me, it looks like the first sentence gives\nclear enough explanation of that already.\n\nBroken indentation aside, I do not see why this change is needed.\n\n> @@ -103,33 +113,9 @@ OPTIONS\n>  \tUse with the `set` and `reapply` commands.\n>  \tSpecify using cone mode or not. The default is to use cone mode.\n>  +\n> -For `set` command:\n> ...\n> -flags, with the same meaning as the flags from the `set` command, in order\n> -to change which sparsity mode you are using without needing to also respecify\n> -all sparsity paths.\n> +For the `set` command, the option to use cone mode or not changes\n> +the interpretation of the remaining arguments to either be a list\n> +of directories or a list of patterns.\n\nThese three lines are not technically incorrect, but is not written\nin a way that helps readers.\n\nRead these three lines a few times, pretending that you have never\nused the sparse-checkout, and try to answer this question: \"I am\ngiving a few arguments to the command using the cone mode.  Are they\ntaken as directories, or patterns?\"\n\nIt is hard for me to guess what is being improved upon because I do\nnot have the preimage of this hunk, but the new text is much less\nclear than \"directories (in cone mode) or patterns (in non-cone\nmode)\" we saw earlier in the description for the 'add' command,\nwhich would help us answer the question (answer: they are taken as\ndirectories).\n\nThanks.\n"},{"id":"451661","messageId":"20220319061910.786850-2-shaoxuan.yuan02@gmail.com","threadId":"57539","inReplyTo":"20220319061910.786850-1-shaoxuan.yuan02@gmail.com","subject":"[PATCH v5 1/4] Documentation/git-sparse-checkout.txt: add an OPTIONS section","fromName":"Shaoxuan Yuan","fromEmail":"shaoxuan.yuan02@gmail.com","sentAt":"2022-03-19T06:19:07Z","receivedAt":"2022-03-19T06:19:34Z","isPatch":true,"sender":{"key":"shaoxuan.yuan02@gmail.com","avatar":"https://avatars.githubusercontent.com/u/46557895?v=4"},"body":"Add an OPTIONS section to the manual and move the descriptions about\nthese options from COMMANDS to the section.\n\nSigned-off-by: Shaoxuan Yuan <shaoxuan.yuan02@gmail.com>\n---\n Documentation/git-sparse-checkout.txt | 63 +++++++++++++++++----------\n 1 file changed, 39 insertions(+), 24 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex e4a29a2baa..5db5c0ab47 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -35,30 +35,11 @@ COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN\n THE FUTURE.\n \n \n-COMMANDS\n---------\n-'list'::\n-\tDescribe the directories or patterns in the sparse-checkout file.\n-\n-'set'::\n-\tEnable the necessary sparse-checkout config settings\n-\t(`core.sparseCheckout`, `core.sparseCheckoutCone`, and\n-\t`index.sparse`) if they are not already set to the desired values,\n-\tpopulate the sparse-checkout file from the list of arguments\n-\tfollowing the 'set' subcommand, and update the working directory to\n-\tmatch.\n-+\n-To ensure that adjusting the sparse-checkout settings within a worktree\n-does not alter the sparse-checkout settings in other worktrees, the 'set'\n-subcommand will upgrade your repository config to use worktree-specific\n-config if not already present. The sparsity defined by the arguments to\n-the 'set' subcommand are stored in the worktree-specific sparse-checkout\n-file. See linkgit:git-worktree[1] and the documentation of\n-`extensions.worktreeConfig` in linkgit:git-config[1] for more details.\n-+\n-When the `--stdin` option is provided, the directories or patterns are\n-read from standard in as a newline-delimited list instead of from the\n-arguments.\n+OPTIONS\n+-------\n+'--[no-]cone'::\n+\tUse with ['set'|'reapply'].\n+\tSpecify using cone mode or not. The default is to use cone mode.\n +\n By default, the input list is considered a list of directories, matching\n the output of `git ls-tree -d --name-only`.  This includes interpreting\n@@ -78,6 +59,11 @@ with the `--sparse-index` option, and will likely be incompatible with\n other new features as they are added.  See the \"Non-cone Problems\"\n section below and the \"Sparse Checkout\" section of\n linkgit:git-read-tree[1] for more details.\n+\n+'--[no-]sparse-index'::\n+\tUse with ['set'|'reapply'].\n+\tSpecify using a sparse index or not. The default is to not use a\n+\tsparse index.\n +\n Use the `--[no-]sparse-index` option to use a sparse index (the\n default is to not use it).  A sparse index reduces the size of the\n@@ -94,6 +80,35 @@ to rewrite your index to not be sparse. Older versions of Git will not\n understand the sparse directory entries index extension and may fail to\n interact with your repository until it is disabled.\n \n+'--stdin'::\n+\tUse with ['set'|'add'].\n++\n+When the `--stdin` option is provided, the directories or patterns are\n+read from standard in as a newline-delimited list instead of from the\n+arguments.\n+\n+\n+COMMANDS\n+--------\n+'list'::\n+\tDescribe the directories or patterns in the sparse-checkout file.\n+\n+'set'::\n+\tEnable the necessary sparse-checkout config settings\n+\t(`core.sparseCheckout`, `core.sparseCheckoutCone`, and\n+\t`index.sparse`) if they are not already set to the desired values,\n+\tpopulate the sparse-checkout file from the list of arguments\n+\tfollowing the 'set' subcommand, and update the working directory to\n+\tmatch.\n++\n+To ensure that adjusting the sparse-checkout settings within a worktree\n+does not alter the sparse-checkout settings in other worktrees, the 'set'\n+subcommand will upgrade your repository config to use worktree-specific\n+config if not already present. The sparsity defined by the arguments to\n+the 'set' subcommand are stored in the worktree-specific sparse-checkout\n+file. See linkgit:git-worktree[1] and the documentation of\n+`extensions.worktreeConfig` in linkgit:git-config[1] for more details.\n+\n 'add'::\n \tUpdate the sparse-checkout file to include additional directories\n \t(in cone mode) or patterns (in non-cone mode).  By default, these\n-- \n2.35.1\n\n"},{"id":"451660","messageId":"20220319061910.786850-1-shaoxuan.yuan02@gmail.com","threadId":"57539","inReplyTo":"20220311132141.1817-1-shaoxuan.yuan02@gmail.com","subject":"[PATCH v5 0/4] Documentation/git-sparse-checkout.txt: add an OPTIONS section","fromName":"Shaoxuan Yuan","fromEmail":"shaoxuan.yuan02@gmail.com","sentAt":"2022-03-19T06:19:06Z","receivedAt":"2022-03-19T06:19:35Z","isPatch":true,"sender":{"key":"shaoxuan.yuan02@gmail.com","avatar":"https://avatars.githubusercontent.com/u/46557895?v=4"},"body":"== Updates Log ==\n\nChanges since v4\n\n * ship a multi-patch series to reflect the history\n * base on Elijah's series [1]\n * changes according to Junio [2]\n\n[1] https://lore.kernel.org/git/pull.1148.v2.git.1647054681.gitgitgadget@gmail.com/\n[2] https://lore.kernel.org/git/xmqqfsnfb42c.fsf@gitster.g/\n\n== Overview ==\n\nAdd an OPTIONS section to the manual. Also provide corresponding text changes\nfor better understanding the topic.\n\nShaoxuan Yuan (4):\n  Documentation/git-sparse-checkout.txt: add an OPTIONS section\n  Documentation/git-sparse-checkout.txt: move OPTIONS after COMMANDS\n  Documentation/git-sparse-checkout.txt: some reword and modifications\n  Documentation/git-sparse-checkout.txt: some reword and modifications\n\n Documentation/git-sparse-checkout.txt | 88 +++++++++++++--------------\n 1 file changed, 44 insertions(+), 44 deletions(-)\n\n\nbase-commit: 4b89a3392b04acccf28f09f90e26715140461373\n-- \n2.35.1\n\n"},{"id":"451662","messageId":"20220319061910.786850-4-shaoxuan.yuan02@gmail.com","threadId":"57539","inReplyTo":"20220319061910.786850-1-shaoxuan.yuan02@gmail.com","subject":"[PATCH v5 3/4] Documentation/git-sparse-checkout.txt: some reword and modifications","fromName":"Shaoxuan Yuan","fromEmail":"shaoxuan.yuan02@gmail.com","sentAt":"2022-03-19T06:19:09Z","receivedAt":"2022-03-19T06:19:49Z","isPatch":true,"sender":{"key":"shaoxuan.yuan02@gmail.com","avatar":"https://avatars.githubusercontent.com/u/46557895?v=4"},"body":"Some changes according to Derrick [1]\n\n* added a paragraph that breifly touches on the input of 'set' command\n* refer to the 'set' command when talking about 'add' command\n* condense the '--[no-]cone' section\n* remove 'For `reapply` command' section under '--[no-]cone' section\n\n[1] https://lore.kernel.org/git/307ac60d-b0a1-ea90-8118-a4e02b809102@github.com/\n\nHelped-by: Derrick Stolee <derrickstolee@github.com>\nSigned-off-by: Shaoxuan Yuan <shaoxuan.yuan02@gmail.com>\n---\n Documentation/git-sparse-checkout.txt | 44 +++++++++------------------\n 1 file changed, 15 insertions(+), 29 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex b8f3b89b74..0178d63f56 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -48,6 +48,14 @@ COMMANDS\n \tfollowing the 'set' subcommand, and update the working directory to\n \tmatch.\n +\n+By default, the arguments to the `set` command are interpreted as a\n+list of directories. The sparse-checkout patterns are set to match\n+all files within those directories, recursively, as well as any file\n+directly contained in a parent of those directories. See INTERNALS\n+-- CONE PATTERN SET below for full details. If --no-cone is specified,\n+then the arguments are interpreted as sparse-checkout patterns. See\n+INTERNALS -- FULL PATTERN SET below for more information.\n++\n To ensure that adjusting the sparse-checkout settings within a worktree\n does not alter the sparse-checkout settings in other worktrees, the 'set'\n subcommand will upgrade your repository config to use worktree-specific\n@@ -59,8 +67,10 @@ file. See linkgit:git-worktree[1] and the documentation of\n 'add'::\n \tUpdate the sparse-checkout file to include additional directories\n \t(in cone mode) or patterns (in non-cone mode).  By default, these\n-\tdirectories or patterns are read from the command-line arguments,\n-\tbut they can be read from stdin using the `--stdin` option.\n+\tdirectories or patterns are read from the command-line arguments.\n+  These directories or patterns are interpreted the same way as stated\n+  above in `set` command, and they can be read from stdin using the\n+  `--stdin` option.\n \n 'reapply'::\n \tReapply the sparsity pattern rules to paths in the working tree.\n@@ -103,33 +113,9 @@ OPTIONS\n \tUse with the `set` and `reapply` commands.\n \tSpecify using cone mode or not. The default is to use cone mode.\n +\n-For `set` command:\n-+\n-By default, the input list is considered a list of directories, matching\n-the output of `git ls-tree -d --name-only`.  This includes interpreting\n-pathnames that begin with a double quote (\") as C-style quoted strings.\n-Note that all files under the specified directories (at any depth) will\n-be included in the sparse checkout, as well as files that are siblings\n-of either the given directory or any of its ancestors (see 'CONE PATTERN\n-SET' below for more details).  In the past, this was not the default,\n-and `--cone` needed to be specified or `core.sparseCheckoutCone` needed\n-to be enabled.\n-+\n-When `--no-cone` is passed, the input list is considered a list of\n-patterns.  This mode is harder to use, and unless you can keep the\n-number of patterns small, its design also scales poorly.  It used to be\n-the default mode, but we do not recommend using it.  It does not work\n-with the `--sparse-index` option, and will likely be incompatible with\n-other new features as they are added.  See the \"Non-cone Problems\"\n-section below and the \"Sparse Checkout\" section of\n-linkgit:git-read-tree[1] for more details.\n-+\n-For `reapply` command:\n-+\n-The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`\n-flags, with the same meaning as the flags from the `set` command, in order\n-to change which sparsity mode you are using without needing to also respecify\n-all sparsity paths.\n+For the `set` command, the option to use cone mode or not changes\n+the interpretation of the remaining arguments to either be a list\n+of directories or a list of patterns.\n \n '--[no-]sparse-index'::\n \tUse with the `set` and `reapply` commands.\n-- \n2.35.1\n\n"},{"id":"451663","messageId":"20220319061910.786850-5-shaoxuan.yuan02@gmail.com","threadId":"57539","inReplyTo":"20220319061910.786850-1-shaoxuan.yuan02@gmail.com","subject":"[PATCH v5 4/4] Documentation/git-sparse-checkout.txt: some reword and modifications","fromName":"Shaoxuan Yuan","fromEmail":"shaoxuan.yuan02@gmail.com","sentAt":"2022-03-19T06:19:10Z","receivedAt":"2022-03-19T06:19:49Z","isPatch":true,"sender":{"key":"shaoxuan.yuan02@gmail.com","avatar":"https://avatars.githubusercontent.com/u/46557895?v=4"},"body":"Modifications suggested by Junio [1]\n\n* remove redundant part under 'add' command\n* fix broken indentation\n* remove redundant part under '--[no-]cone' option\n\n[1] https://lore.kernel.org/git/xmqqfsnfb42c.fsf@gitster.g/\n\nHelped-by: Junio C Hamano <gitster@pobox.com>\nSigned-off-by: Shaoxuan Yuan <shaoxuan.yuan02@gmail.com>\n---\n Documentation/git-sparse-checkout.txt | 12 +++---------\n 1 file changed, 3 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 0178d63f56..482ecfe28c 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -66,11 +66,9 @@ file. See linkgit:git-worktree[1] and the documentation of\n \n 'add'::\n \tUpdate the sparse-checkout file to include additional directories\n-\t(in cone mode) or patterns (in non-cone mode).  By default, these\n-\tdirectories or patterns are read from the command-line arguments.\n-  These directories or patterns are interpreted the same way as stated\n-  above in `set` command, and they can be read from stdin using the\n-  `--stdin` option.\n+\t(in cone mode) or patterns (in non-cone mode). By default, these\n+\tdirectories or patterns are read from the command-line arguments,\n+\tbut they can be read from stdin using the `--stdin` option.\n \n 'reapply'::\n \tReapply the sparsity pattern rules to paths in the working tree.\n@@ -112,10 +110,6 @@ OPTIONS\n '--[no-]cone'::\n \tUse with the `set` and `reapply` commands.\n \tSpecify using cone mode or not. The default is to use cone mode.\n-+\n-For the `set` command, the option to use cone mode or not changes\n-the interpretation of the remaining arguments to either be a list\n-of directories or a list of patterns.\n \n '--[no-]sparse-index'::\n \tUse with the `set` and `reapply` commands.\n-- \n2.35.1\n\n"},{"id":"451664","messageId":"20220319061910.786850-3-shaoxuan.yuan02@gmail.com","threadId":"57539","inReplyTo":"20220319061910.786850-1-shaoxuan.yuan02@gmail.com","subject":"[PATCH v5 2/4] Documentation/git-sparse-checkout.txt: move OPTIONS after COMMANDS","fromName":"Shaoxuan Yuan","fromEmail":"shaoxuan.yuan02@gmail.com","sentAt":"2022-03-19T06:19:08Z","receivedAt":"2022-03-19T06:19:49Z","isPatch":true,"sender":{"key":"shaoxuan.yuan02@gmail.com","avatar":"https://avatars.githubusercontent.com/u/46557895?v=4"},"body":"* move OPTIONS after COMMANDS\n* add two sub-sections under option '--[no-]cone', one for command 'set' and\none for command 'reapply'\n* change the command indicators from this style:\n\n\tUse with ['set'|'reapply'].\n\nto this style:\n\n\tUse with the `set` and `reapply` commands.\n\nHelped-by: Derrick Stolee <derrickstolee@github.com>\nSigned-off-by: Shaoxuan Yuan <shaoxuan.yuan02@gmail.com>\n---\n Documentation/git-sparse-checkout.txt | 121 ++++++++++++++------------\n 1 file changed, 63 insertions(+), 58 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 5db5c0ab47..b8f3b89b74 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -35,59 +35,6 @@ COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN\n THE FUTURE.\n \n \n-OPTIONS\n--------\n-'--[no-]cone'::\n-\tUse with ['set'|'reapply'].\n-\tSpecify using cone mode or not. The default is to use cone mode.\n-+\n-By default, the input list is considered a list of directories, matching\n-the output of `git ls-tree -d --name-only`.  This includes interpreting\n-pathnames that begin with a double quote (\") as C-style quoted strings.\n-Note that all files under the specified directories (at any depth) will\n-be included in the sparse checkout, as well as files that are siblings\n-of either the given directory or any of its ancestors (see 'CONE PATTERN\n-SET' below for more details).  In the past, this was not the default,\n-and `--cone` needed to be specified or `core.sparseCheckoutCone` needed\n-to be enabled.\n-+\n-When `--no-cone` is passed, the input list is considered a list of\n-patterns.  This mode is harder to use, and unless you can keep the\n-number of patterns small, its design also scales poorly.  It used to be\n-the default mode, but we do not recommend using it.  It does not work\n-with the `--sparse-index` option, and will likely be incompatible with\n-other new features as they are added.  See the \"Non-cone Problems\"\n-section below and the \"Sparse Checkout\" section of\n-linkgit:git-read-tree[1] for more details.\n-\n-'--[no-]sparse-index'::\n-\tUse with ['set'|'reapply'].\n-\tSpecify using a sparse index or not. The default is to not use a\n-\tsparse index.\n-+\n-Use the `--[no-]sparse-index` option to use a sparse index (the\n-default is to not use it).  A sparse index reduces the size of the\n-index to be more closely aligned with your sparse-checkout\n-definition. This can have significant performance advantages for\n-commands such as `git status` or `git add`.  This feature is still\n-experimental. Some commands might be slower with a sparse index until\n-they are properly integrated with the feature.\n-+\n-**WARNING:** Using a sparse index requires modifying the index in a way\n-that is not completely understood by external tools. If you have trouble\n-with this compatibility, then run `git sparse-checkout init --no-sparse-index`\n-to rewrite your index to not be sparse. Older versions of Git will not\n-understand the sparse directory entries index extension and may fail to\n-interact with your repository until it is disabled.\n-\n-'--stdin'::\n-\tUse with ['set'|'add'].\n-+\n-When the `--stdin` option is provided, the directories or patterns are\n-read from standard in as a newline-delimited list instead of from the\n-arguments.\n-\n-\n COMMANDS\n --------\n 'list'::\n@@ -124,11 +71,6 @@ file. See linkgit:git-worktree[1] and the documentation of\n \tcases, it can make sense to run `git sparse-checkout reapply` later\n \tafter cleaning up affected paths (e.g. resolving conflicts, undoing\n \tor committing changes, etc.).\n-+\n-The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`\n-flags, with the same meaning as the flags from the `set` command, in order\n-to change which sparsity mode you are using without needing to also respecify\n-all sparsity paths.\n \n 'disable'::\n \tDisable the `core.sparseCheckout` config setting, and restore the\n@@ -154,6 +96,69 @@ paths to pass to a subsequent 'set' or 'add' command.  However,\n the disable command, so the easy restore of calling a plain `init`\n decreased in utility.\n \n+\n+OPTIONS\n+-------\n+'--[no-]cone'::\n+\tUse with the `set` and `reapply` commands.\n+\tSpecify using cone mode or not. The default is to use cone mode.\n++\n+For `set` command:\n++\n+By default, the input list is considered a list of directories, matching\n+the output of `git ls-tree -d --name-only`.  This includes interpreting\n+pathnames that begin with a double quote (\") as C-style quoted strings.\n+Note that all files under the specified directories (at any depth) will\n+be included in the sparse checkout, as well as files that are siblings\n+of either the given directory or any of its ancestors (see 'CONE PATTERN\n+SET' below for more details).  In the past, this was not the default,\n+and `--cone` needed to be specified or `core.sparseCheckoutCone` needed\n+to be enabled.\n++\n+When `--no-cone` is passed, the input list is considered a list of\n+patterns.  This mode is harder to use, and unless you can keep the\n+number of patterns small, its design also scales poorly.  It used to be\n+the default mode, but we do not recommend using it.  It does not work\n+with the `--sparse-index` option, and will likely be incompatible with\n+other new features as they are added.  See the \"Non-cone Problems\"\n+section below and the \"Sparse Checkout\" section of\n+linkgit:git-read-tree[1] for more details.\n++\n+For `reapply` command:\n++\n+The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`\n+flags, with the same meaning as the flags from the `set` command, in order\n+to change which sparsity mode you are using without needing to also respecify\n+all sparsity paths.\n+\n+'--[no-]sparse-index'::\n+\tUse with the `set` and `reapply` commands.\n+\tSpecify using a sparse index or not. The default is to not use a\n+\tsparse index.\n++\n+Use the `--[no-]sparse-index` option to use a sparse index (the\n+default is to not use it).  A sparse index reduces the size of the\n+index to be more closely aligned with your sparse-checkout\n+definition. This can have significant performance advantages for\n+commands such as `git status` or `git add`.  This feature is still\n+experimental. Some commands might be slower with a sparse index until\n+they are properly integrated with the feature.\n++\n+**WARNING:** Using a sparse index requires modifying the index in a way\n+that is not completely understood by external tools. If you have trouble\n+with this compatibility, then run `git sparse-checkout init --no-sparse-index`\n+to rewrite your index to not be sparse. Older versions of Git will not\n+understand the sparse directory entries index extension and may fail to\n+interact with your repository until it is disabled.\n+\n+'--stdin'::\n+\tUse with the `set` and `add` commands.\n++\n+When the `--stdin` option is provided, the directories or patterns are\n+read from standard in as a newline-delimited list instead of from the\n+arguments.\n+\n+\n EXAMPLES\n --------\n `git sparse-checkout set MY/DIR1 SUB/DIR2`::\n-- \n2.35.1\n\n"},{"id":"451848","messageId":"acb2c221-8bf0-9cf8-8fee-8c6a807836cd@github.com","threadId":"57539","inReplyTo":"20220319061910.786850-1-shaoxuan.yuan02@gmail.com","subject":"Re: [PATCH v5 0/4] Documentation/git-sparse-checkout.txt: add an OPTIONS section","fromName":"Derrick Stolee","fromEmail":"derrickstolee@github.com","sentAt":"2022-03-22T15:05:12Z","receivedAt":"2022-03-22T15:05:18Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"On 3/19/22 2:19 AM, Shaoxuan Yuan wrote:\n> == Updates Log ==\n> \n> Changes since v4\n> \n>  * ship a multi-patch series to reflect the history\n>  * base on Elijah's series [1]\n>  * changes according to Junio [2]\n> \n> [1] https://lore.kernel.org/git/pull.1148.v2.git.1647054681.gitgitgadget@gmail.com/\n> [2] https://lore.kernel.org/git/xmqqfsnfb42c.fsf@gitster.g/\n> \n> == Overview ==\n> \n> Add an OPTIONS section to the manual. Also provide corresponding text changes\n> for better understanding the topic.\n> Shaoxuan Yuan (4):\n>   Documentation/git-sparse-checkout.txt: add an OPTIONS section\n>   Documentation/git-sparse-checkout.txt: move OPTIONS after COMMANDS\n>   Documentation/git-sparse-checkout.txt: some reword and modifications\n>   Documentation/git-sparse-checkout.txt: some reword and modifications\n\nHi Shaoxuan,\n\nThis commit organization seems to be one that you created naturally from\nresponding to feedback. Unfortunately, we expect that each patch is\nexpected to be created with the intent of presenting changes in an\nefficient way. This helps both with review and future history\ninvestigations. See Documentation/SubmittingPatches for more information.\n\nIn particular, patches 2-4 are of the mode \"Modify the changes from patch\n1 based on feedback\". Instead, we expect that you update that single patch\nunless there is a clear reason why two separate changes are valuable.\n\nWhen submitting new versions to a series, adding a range-diff to your\ncover letter helps reviewers see what changed between versions, so we\nstill see how you responded to our feedback in a more isolated way.\n\nI took your changes and applied them to en/sparse-cone-becomes-default and\ngot the diff below end-to-end. This is much easier to read. It also makes\nsome things clear (like an unnecessary whitespace change).\n\nI think that this diff would be better served as a single patch. I'll\nreview this diff inline below:\n\n\n> diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\n> index e4a29a2baa9..482ecfe28c5 100644\n> --- a/Documentation/git-sparse-checkout.txt\n> +++ b/Documentation/git-sparse-checkout.txt\n> @@ -48,6 +48,14 @@ COMMANDS\n>  \tfollowing the 'set' subcommand, and update the working directory to\n>  \tmatch.\n>  +\n> +By default, the arguments to the `set` command are interpreted as a\n> +list of directories. The sparse-checkout patterns are set to match\n> +all files within those directories, recursively, as well as any file\n> +directly contained in a parent of those directories. See INTERNALS\n> +-- CONE PATTERN SET below for full details. If --no-cone is specified,\n> +then the arguments are interpreted as sparse-checkout patterns. See\n> +INTERNALS -- FULL PATTERN SET below for more information.\n> ++\n>  To ensure that adjusting the sparse-checkout settings within a worktree\n>  does not alter the sparse-checkout settings in other worktrees, the 'set'\n>  subcommand will upgrade your repository config to use worktree-specific\n> @@ -55,48 +63,10 @@ config if not already present. The sparsity defined by the arguments to\n>  the 'set' subcommand are stored in the worktree-specific sparse-checkout\n>  file. See linkgit:git-worktree[1] and the documentation of\n>  `extensions.worktreeConfig` in linkgit:git-config[1] for more details.\n> -+\n> -When the `--stdin` option is provided, the directories or patterns are\n> -read from standard in as a newline-delimited list instead of from the\n> -arguments.\n> -+\n> -By default, the input list is considered a list of directories, matching\n> -the output of `git ls-tree -d --name-only`.  This includes interpreting\n> -pathnames that begin with a double quote (\") as C-style quoted strings.\n> -Note that all files under the specified directories (at any depth) will\n> -be included in the sparse checkout, as well as files that are siblings\n> -of either the given directory or any of its ancestors (see 'CONE PATTERN\n> -SET' below for more details).  In the past, this was not the default,\n> -and `--cone` needed to be specified or `core.sparseCheckoutCone` needed\n> -to be enabled.\n> -+\n> -When `--no-cone` is passed, the input list is considered a list of\n> -patterns.  This mode is harder to use, and unless you can keep the\n> -number of patterns small, its design also scales poorly.  It used to be\n> -the default mode, but we do not recommend using it.  It does not work\n> -with the `--sparse-index` option, and will likely be incompatible with\n> -other new features as they are added.  See the \"Non-cone Problems\"\n> -section below and the \"Sparse Checkout\" section of\n> -linkgit:git-read-tree[1] for more details.\n> -+\n> -Use the `--[no-]sparse-index` option to use a sparse index (the\n> -default is to not use it).  A sparse index reduces the size of the\n> -index to be more closely aligned with your sparse-checkout\n> -definition. This can have significant performance advantages for\n> -commands such as `git status` or `git add`.  This feature is still\n> -experimental. Some commands might be slower with a sparse index until\n> -they are properly integrated with the feature.\n> -+\n> -**WARNING:** Using a sparse index requires modifying the index in a way\n> -that is not completely understood by external tools. If you have trouble\n> -with this compatibility, then run `git sparse-checkout init --no-sparse-index`\n> -to rewrite your index to not be sparse. Older versions of Git will not\n> -understand the sparse directory entries index extension and may fail to\n> -interact with your repository until it is disabled.\n>  \n>  'add'::\n>  \tUpdate the sparse-checkout file to include additional directories\n> -\t(in cone mode) or patterns (in non-cone mode).  By default, these\n> +\t(in cone mode) or patterns (in non-cone mode). By default, these\n\nThis whitespace change doesn't need to be here. I do think a single space\nis more common in our docs, but it has no effect on the rendered docs, so\nthis is unnecessary noise for the diff.\n\n>  \tdirectories or patterns are read from the command-line arguments,\n>  \tbut they can be read from stdin using the `--stdin` option.\n>  \n> @@ -109,11 +79,6 @@ interact with your repository until it is disabled.\n>  \tcases, it can make sense to run `git sparse-checkout reapply` later\n>  \tafter cleaning up affected paths (e.g. resolving conflicts, undoing\n>  \tor committing changes, etc.).\n> -+\n> -The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`\n> -flags, with the same meaning as the flags from the `set` command, in order\n> -to change which sparsity mode you are using without needing to also respecify\n> -all sparsity paths.\n>  \n>  'disable'::\n>  \tDisable the `core.sparseCheckout` config setting, and restore the\n> @@ -139,6 +104,41 @@ paths to pass to a subsequent 'set' or 'add' command.  However,\n>  the disable command, so the easy restore of calling a plain `init`\n>  decreased in utility.\n>  \n> +\n> +OPTIONS\n> +-------\n> +'--[no-]cone'::\n> +\tUse with the `set` and `reapply` commands.\n> +\tSpecify using cone mode or not. The default is to use cone mode.\n> +\n> +'--[no-]sparse-index'::\n> +\tUse with the `set` and `reapply` commands.\n> +\tSpecify using a sparse index or not. The default is to not use a\n> +\tsparse index.\n> ++\n> +Use the `--[no-]sparse-index` option to use a sparse index (the\n\nI find this a bit confusing. Maybe just \"`--sparse-index`\" would make\nit clear that leaving out the [no-] is for enabling it.\n\n> +default is to not use it).  A sparse index reduces the size of the\n> +index to be more closely aligned with your sparse-checkout\n> +definition. This can have significant performance advantages for\n> +commands such as `git status` or `git add`.  This feature is still\n> +experimental. Some commands might be slower with a sparse index until\n> +they are properly integrated with the feature.\n> ++\n> +**WARNING:** Using a sparse index requires modifying the index in a way\n> +that is not completely understood by external tools. If you have trouble\n> +with this compatibility, then run `git sparse-checkout init --no-sparse-index`\n> +to rewrite your index to not be sparse. Older versions of Git will not\n> +understand the sparse directory entries index extension and may fail to\n> +interact with your repository until it is disabled.\n> +\n> +'--stdin'::\n> +\tUse with the `set` and `add` commands.\n> ++\n> +When the `--stdin` option is provided, the directories or patterns are\n> +read from standard in as a newline-delimited list instead of from the\n> +arguments.\n> +\n> +\n\nI find it a lot easier to see these options being moved and updated at the\nsame time.\n\nThanks,\n-Stolee\n"}]}