{"thread":{"id":"57519","subject":"[PATCH 0/9] sparse-checkout: make cone mode the default","startedAt":"2022-03-08T07:39:53Z","lastAt":"2022-04-25T14:38:55Z","messageCount":54,"participants":["Elijah Newren via GitGitGadget","Derrick Stolee","Elijah Newren","Victoria Dye","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":9},"messages":[{"id":"450703","messageId":"pull.1148.git.1646725188.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":null,"subject":"[PATCH 0/9] sparse-checkout: make cone mode the default","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-08T07:39:39Z","receivedAt":"2022-03-08T07:39:53Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"== Maintainer Note ==\n\nDepends on a merge of en/present-despite-skipped into master.\n\n== Overview ==\n\nThis patch changes the default mode for sparse-checkout from non-cone mode\nto cone-mode, and marks non-cone mode as deprecated. There is no plan to\nremove non-cone mode, we are merely recommending against its use.\n\nThe code change is pretty small, and most of this series is about\ndocumentation updates -- to focus on directories rather than patterns, to\nexplain the new default, to explain why we are deprecating non-cone mode\n(the final patch), and to make other related cleanups to simplify the\nmanual.\n\nPatch 1: Update tests to not assume cone-mode is the default Patch 2: Make\ncone-mode the default Patches 3-9: Various updates to\ngit-sparse-checkout.txt, divided up for ease of review\n\n== Alternative ==\n\nThere is one primary alternative to this series: make sparse-checkout error\nwhen neither --cone nor --no-cone are specified (so that there is no\ndefault), and wait until a future date to make --cone the default. That'd be\nreasonable, but I had three reason to avoid going this route (note that item\n2 means there's little practical difference between cone-mode-as-default and\nno-mode-is-default):\n\n 1. git-sparse-checkout.txt has the following huge warning early in the\n manual:\n\n\"\"\" THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR, AND THE BEHAVIOR OF OTHER\nCOMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN THE\nFUTURE. \"\"\"\n\n 2. If users are unaware of the default change and attempt to provide\n patterns instead of directories, then they will get error messages added\n from en/sparse-checkout-fixes. They can learn at that time to get around\n the error messages by providing --no-cone.\n\n 3. If users are unaware of the default change and provide directories, then\n that's where non-cone mode and cone mode overlap and things happen to\n work. (There is a slight difference in that cone mode will include files\n from parent directories of any specified directory, but that means the\n user gets a few more files in their sparse-checkout with cone mode than\n they would with non-cone mode.)\n\n== CCs ==\n\nElijah Newren (9):\n tests: stop assuming --no-cone is the default mode for sparse-checkout\n sparse-checkout: make --cone the default\n git-sparse-checkout.txt: wording updates for the cone mode default\n git-sparse-checkout.txt: update docs for deprecation of 'init'\n git-sparse-checkout.txt: shuffle some sections and mark as internal\n git-sparse-checkout.txt: add a new EXAMPLES section\n git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a\n bit\n git-sparse-checkout.txt: mark non-cone mode as deprecated\n Documentation: some sparsity wording clarifications\n\n Documentation/git-read-tree.txt | 9 +-\n Documentation/git-sparse-checkout.txt | 248 +++++++++++++++++++-------\n builtin/sparse-checkout.c | 2 +-\n t/t1091-sparse-checkout-builtin.sh | 15 +-\n t/t3602-rm-sparse-checkout.sh | 6 +-\n t/t3705-add-sparse-checkout.sh | 4 +-\n t/t6428-merge-conflicts-sparse.sh | 4 +-\n t/t7002-mv-sparse-checkout.sh | 2 +-\n t/t7012-skip-worktree-writing.sh | 2 +-\n 9 files changed, 206 insertions(+), 86 deletions(-)\n\n\nbase-commit: af002ccf9fe2ce6cce9111323423f1d4739bcf0d\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1148%2Fnewren%2Fsparse-checkout-default-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1148/newren/sparse-checkout-default-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1148\n-- \ngitgitgadget\n"},{"id":"450704","messageId":"f98b3fac78a707849951b317f50ee56754d0ff9d.1646725188.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.git.1646725188.gitgitgadget@gmail.com","subject":"[PATCH 3/9] git-sparse-checkout.txt: wording updates for the cone mode default","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-08T07:39:42Z","receivedAt":"2022-03-08T07:39:57Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nNow that cone mode is the default, we'd like to focus on the arguments\nto set/add being directories rather than patterns, and it probably makes\nsense to provide an earlier heads up that files from leading directories\nget included as well.\n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-sparse-checkout.txt | 31 +++++++++++++--------------\n 1 file changed, 15 insertions(+), 16 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 4ef03120797..42a984306bb 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -44,9 +44,9 @@ COMMANDS\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-\tand write a set of patterns to the sparse-checkout file from the\n-\tlist of arguments following the 'set' subcommand. Update the\n-\tworking directory to match the new patterns.\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@@ -60,15 +60,15 @@ 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-When `--cone` is passed or `core.sparseCheckoutCone` is not false, the\n-input list is considered a list of directories. This allows for\n-better performance with a limited set of patterns (see 'CONE PATTERN\n-SET' below). The input format matches the output of `git ls-tree\n---name-only`. This includes interpreting pathnames that begin with a\n-double quote (\") as C-style quoted strings. Note that the set command\n-will write patterns to the sparse-checkout file to include all files\n-contained in those directories (recursively) as well as files that are\n-siblings of ancestor directories.\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 or `core.sparseCheckoutCone` is false,\n the input list is considered a list of patterns. This mode is harder\n@@ -208,10 +208,9 @@ the following patterns:\n This says \"include everything in root, but nothing two levels below root.\"\n \n When in cone mode, the `git sparse-checkout set` subcommand takes a list of\n-directories instead of a list of sparse-checkout patterns. In this mode,\n-the command `git sparse-checkout set A/B/C` sets the directory `A/B/C` as\n-a recursive pattern, the directories `A` and `A/B` are added as parent\n-patterns. The resulting sparse-checkout file is now\n+directories. In this mode, the command `git sparse-checkout set A/B/C` sets\n+the directory `A/B/C` as a recursive pattern, the directories `A` and `A/B`\n+are added as parent patterns. The resulting sparse-checkout file is now\n \n ----------------\n /*\n-- \ngitgitgadget\n\n"},{"id":"450705","messageId":"b174b42ed82a45f57959a2a493dcfb32bf26c12d.1646725188.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.git.1646725188.gitgitgadget@gmail.com","subject":"[PATCH 2/9] sparse-checkout: make --cone the default","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-08T07:39:41Z","receivedAt":"2022-03-08T07:39:59Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nMake cone mode the default, and update the documentation accordingly.\n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-sparse-checkout.txt | 20 ++++++++++----------\n builtin/sparse-checkout.c | 2 +-\n 2 files changed, 11 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 88e55f432f3..4ef03120797 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -22,8 +22,8 @@ present, or undo and go back to having all tracked files present in the\n working copy.\n \n The subset of files is chosen by providing a list of directories in\n-cone mode (which is recommended), or by providing a list of patterns\n-in non-cone mode.\n+cone mode (the default), or by providing a list of patterns in\n+non-cone mode.\n \n When in a sparse-checkout, other Git commands behave a bit differently.\n For example, switching branches will not update paths outside the\n@@ -60,7 +60,7 @@ 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-When `--cone` is passed or `core.sparseCheckoutCone` is enabled, the\n+When `--cone` is passed or `core.sparseCheckoutCone` is not false, the\n input list is considered a list of directories. This allows for\n better performance with a limited set of patterns (see 'CONE PATTERN\n SET' below). The input format matches the output of `git ls-tree\n@@ -68,10 +68,9 @@ SET' below). The input format matches the output of `git ls-tree\n double quote (\") as C-style quoted strings. Note that the set command\n will write patterns to the sparse-checkout file to include all files\n contained in those directories (recursively) as well as files that are\n-siblings of ancestor directories. This may become the default in the\n-future; --no-cone can be passed to request non-cone mode.\n+siblings of ancestor directories.\n +\n-When `--no-cone` is passed or `core.sparseCheckoutCone` is not enabled,\n+When `--no-cone` is passed or `core.sparseCheckoutCone` is false,\n the input list is considered a list of patterns. This mode is harder\n to use and less performant, and is thus not recommended. See the\n \"Sparse Checkout\" section of linkgit:git-read-tree[1] and the \"Pattern\n@@ -227,10 +226,11 @@ patterns. The resulting sparse-checkout file is now\n Here, order matters, so the negative patterns are overridden by the positive\n patterns that appear lower in the file.\n \n-If `core.sparseCheckoutCone=true`, then Git will parse the sparse-checkout file\n-expecting patterns of these types. Git will warn if the patterns do not match.\n-If the patterns do match the expected format, then Git will use faster hash-\n-based algorithms to compute inclusion in the sparse-checkout.\n+If `core.sparseCheckoutCone=true` (set by default or with an explicit\n+`--cone`), then Git will parse the sparse-checkout file expecting\n+patterns of these types. Git will warn if the patterns do not match. If\n+the patterns do match the expected format, then Git will use faster\n+hash-based algorithms to compute inclusion in the sparse-checkout.\n \n In the cone mode case, the `git sparse-checkout list` subcommand will list the\n directories that define the recursive patterns. For the example sparse-checkout\ndiff --git a/builtin/sparse-checkout.c b/builtin/sparse-checkout.c\nindex 5518ed47f6c..61b7a7519bb 100644\n--- a/builtin/sparse-checkout.c\n+++ b/builtin/sparse-checkout.c\n@@ -397,7 +397,7 @@ static int update_modes(int *cone_mode, int *sparse_index)\n \n \t/* Set cone/non-cone mode appropriately */\n \tcore_apply_sparse_checkout = 1;\n-\tif (*cone_mode == 1) {\n+\tif (*cone_mode == 1 || *cone_mode == -1) {\n \t\tmode = MODE_CONE_PATTERNS;\n \t\tcore_sparse_checkout_cone = 1;\n \t} else {\n-- \ngitgitgadget\n\n"},{"id":"450706","messageId":"8c3e730e86ba3d453d8fad45ebed6be80190bde8.1646725188.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.git.1646725188.gitgitgadget@gmail.com","subject":"[PATCH 1/9] tests: stop assuming --no-cone is the default mode for sparse-checkout","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-08T07:39:40Z","receivedAt":"2022-03-08T07:40:01Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nAdd an explicit --no-cone to several sparse-checkout invocations in\npreparation for changing the default to cone mode.\n\nSigned-off-by: Elijah Newren \n---\n t/t1091-sparse-checkout-builtin.sh | 15 ++++++++-------\n t/t3602-rm-sparse-checkout.sh | 6 +++---\n t/t3705-add-sparse-checkout.sh | 4 ++--\n t/t6428-merge-conflicts-sparse.sh | 4 ++--\n t/t7002-mv-sparse-checkout.sh | 2 +-\n t/t7012-skip-worktree-writing.sh | 2 +-\n 6 files changed, 17 insertions(+), 16 deletions(-)\n\ndiff --git a/t/t1091-sparse-checkout-builtin.sh b/t/t1091-sparse-checkout-builtin.sh\nindex 9a900310186..de1ec89007d 100755\n--- a/t/t1091-sparse-checkout-builtin.sh\n+++ b/t/t1091-sparse-checkout-builtin.sh\n@@ -72,7 +72,7 @@ test_expect_success 'git sparse-checkout list (populated)' '\n '\n \n test_expect_success 'git sparse-checkout init' '\n-\tgit -C repo sparse-checkout init &&\n+\tgit -C repo sparse-checkout init --no-cone &&\n \tcat >expect <<-\\EOF &&\n \t/*\n \t!/*/\n@@ -111,6 +111,7 @@ test_expect_success 'init with existing sparse-checkout' '\n \n test_expect_success 'clone --sparse' '\n \tgit clone --sparse \"file://$(pwd)/repo\" clone &&\n+\tgit -C clone sparse-checkout reapply --no-cone &&\n \tgit -C clone sparse-checkout list >actual &&\n \tcat >expect <<-\\EOF &&\n \t/*\n@@ -124,7 +125,7 @@ test_expect_success 'switching to cone mode with non-cone mode patterns' '\n \tgit init bad-patterns &&\n \t(\n \t\tcd bad-patterns &&\n-\t\tgit sparse-checkout init &&\n+\t\tgit sparse-checkout init --no-cone &&\n \t\tgit sparse-checkout add dir &&\n \t\tgit config --worktree core.sparseCheckoutCone true &&\n \t\ttest_must_fail git sparse-checkout add dir 2>err &&\n@@ -402,7 +403,7 @@ test_expect_success 'revert to old sparse-checkout on empty update' '\n \t\tgit sparse-checkout set nothing 2>err &&\n \t\ttest_i18ngrep ! \"Sparse checkout leaves no entry on working directory\" err &&\n \t\ttest_i18ngrep ! \".git/index.lock\" err &&\n-\t\tgit sparse-checkout set file\n+\t\tgit sparse-checkout set --no-cone file\n \t)\n '\n \n@@ -424,7 +425,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with dirty status'\n \tgit clone repo dirty &&\n \techo dirty >dirty/folder1/a &&\n \n-\tgit -C dirty sparse-checkout init 2>err &&\n+\tgit -C dirty sparse-checkout init --no-cone 2>err &&\n \ttest_i18ngrep \"warning.*The following paths are not up to date\" err &&\n \n \tgit -C dirty sparse-checkout set /folder2/* /deep/deeper1/* 2>err &&\n@@ -435,7 +436,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with dirty status'\n \ttest_must_be_empty err &&\n \n \tgit -C dirty reset --hard &&\n-\tgit -C dirty sparse-checkout init &&\n+\tgit -C dirty sparse-checkout init --no-cone &&\n \tgit -C dirty sparse-checkout set /folder2/* /deep/deeper1/* &&\n \ttest_path_is_missing dirty/folder1/a &&\n \tgit -C dirty sparse-checkout disable &&\n@@ -451,7 +452,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with unmerged stat\n \tEOF\n \tgit -C unmerged update-index --index-info err &&\n+\tgit -C unmerged sparse-checkout init --no-cone 2>err &&\n \ttest_i18ngrep \"warning.*The following paths are unmerged\" err &&\n \n \tgit -C unmerged sparse-checkout set /folder2/* /deep/deeper1/* 2>err &&\n@@ -462,7 +463,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with unmerged stat\n \ttest_i18ngrep \"warning.*The following paths are unmerged\" err &&\n \n \tgit -C unmerged reset --hard &&\n-\tgit -C unmerged sparse-checkout init &&\n+\tgit -C unmerged sparse-checkout init --no-cone &&\n \tgit -C unmerged sparse-checkout set /folder2/* /deep/deeper1/* &&\n \tgit -C unmerged sparse-checkout disable\n '\ndiff --git a/t/t3602-rm-sparse-checkout.sh b/t/t3602-rm-sparse-checkout.sh\nindex 034ec010910..08580fd3dcc 100755\n--- a/t/t3602-rm-sparse-checkout.sh\n+++ b/t/t3602-rm-sparse-checkout.sh\n@@ -30,7 +30,7 @@ test_expect_success 'setup' \"\n for opt in \"\" -f --dry-run\n do\n \ttest_expect_success \"rm${opt:+ $opt} does not remove sparse entries\" '\n-\t\tgit sparse-checkout set a &&\n+\t\tgit sparse-checkout set --no-cone a &&\n \t\ttest_must_fail git rm $opt b 2>stderr &&\n \t\ttest_cmp b_error_and_hint stderr &&\n \t\tgit ls-files --error-unmatch b\n@@ -118,7 +118,7 @@ test_expect_success 'can remove files from non-sparse dir' '\n \ttest_commit w/f &&\n \ttest_commit x/y/f &&\n \n-\tgit sparse-checkout set w !/x y/ &&\n+\tgit sparse-checkout set --no-cone w !/x y/ &&\n \tgit rm w/f.t x/y/f.t 2>stderr &&\n \ttest_must_be_empty stderr\n '\n@@ -128,7 +128,7 @@ test_expect_success 'refuse to remove non-skip-worktree file from sparse dir' '\n \tgit sparse-checkout disable &&\n \tmkdir -p x/y/z &&\n \ttest_commit x/y/z/f &&\n-\tgit sparse-checkout set !/x y/ !x/y/z &&\n+\tgit sparse-checkout set --no-cone !/x y/ !x/y/z &&\n \n \tgit update-index --no-skip-worktree x/y/z/f.t &&\n \ttest_must_fail git rm x/y/z/f.t 2>stderr &&\ndiff --git a/t/t3705-add-sparse-checkout.sh b/t/t3705-add-sparse-checkout.sh\nindex 95609046c61..2bade9e804f 100755\n--- a/t/t3705-add-sparse-checkout.sh\n+++ b/t/t3705-add-sparse-checkout.sh\n@@ -166,7 +166,7 @@ test_expect_success 'do not warn when pathspec matches dense entries' '\n test_expect_success 'git add fails outside of sparse-checkout definition' '\n \ttest_when_finished git sparse-checkout disable &&\n \ttest_commit a &&\n-\tgit sparse-checkout init &&\n+\tgit sparse-checkout init --no-cone &&\n \tgit sparse-checkout set a &&\n \techo >>sparse_entry &&\n \n@@ -208,7 +208,7 @@ test_expect_success 'add obeys advice.updateSparsePath' '\n '\n \n test_expect_success 'add allows sparse entries with --sparse' '\n-\tgit sparse-checkout set a &&\n+\tgit sparse-checkout set --no-cone a &&\n \techo modified >sparse_entry &&\n \ttest_must_fail git add sparse_entry &&\n \ttest_sparse_entry_unchanged &&\ndiff --git a/t/t6428-merge-conflicts-sparse.sh b/t/t6428-merge-conflicts-sparse.sh\nindex 142c9aaabc5..064be1b629e 100755\n--- a/t/t6428-merge-conflicts-sparse.sh\n+++ b/t/t6428-merge-conflicts-sparse.sh\n@@ -87,7 +87,7 @@ test_expect_success 'conflicting entries written to worktree even if sparse' '\n \t\ttest_path_is_file numerals &&\n \n \t\tgit sparse-checkout init &&\n-\t\tgit sparse-checkout set README &&\n+\t\tgit sparse-checkout set --no-cone README &&\n \n \t\ttest_path_is_file README &&\n \t\ttest_path_is_missing numerals &&\n@@ -123,7 +123,7 @@ test_expect_success 'present-despite-SKIP_WORKTREE handled reasonably' '\n \t\ttest_path_is_file numerals &&\n \n \t\tgit sparse-checkout init &&\n-\t\tgit sparse-checkout set README &&\n+\t\tgit sparse-checkout set --no-cone README &&\n \n \t\ttest_path_is_file README &&\n \t\ttest_path_is_missing numerals &&\ndiff --git a/t/t7002-mv-sparse-checkout.sh b/t/t7002-mv-sparse-checkout.sh\nindex 1d3d2aca21c..f0f7cbfcdb7 100755\n--- a/t/t7002-mv-sparse-checkout.sh\n+++ b/t/t7002-mv-sparse-checkout.sh\n@@ -27,7 +27,7 @@ test_expect_success 'setup' \"\n test_expect_success 'mv refuses to move sparse-to-sparse' '\n \ttest_when_finished rm -f e &&\n \tgit reset --hard &&\n-\tgit sparse-checkout set a &&\n+\tgit sparse-checkout set --no-cone a &&\n \ttouch b &&\n \ttest_must_fail git mv b e 2>stderr &&\n \tcat sparse_error_header >expect &&\ndiff --git a/t/t7012-skip-worktree-writing.sh b/t/t7012-skip-worktree-writing.sh\nindex cb9f1a6981e..cd5c20fe51b 100755\n--- a/t/t7012-skip-worktree-writing.sh\n+++ b/t/t7012-skip-worktree-writing.sh\n@@ -151,7 +151,7 @@ test_expect_success 'stash restore in sparse checkout' '\n \n \t\tgit stash push &&\n \n-\t\tgit sparse-checkout set subdir &&\n+\t\tgit sparse-checkout set --no-cone subdir &&\n \n \t\t# Ensure after sparse-checkout we only have expected files\n \t\tcat >expect <<-EOF &&\n-- \ngitgitgadget\n\n"},{"id":"450707","messageId":"cd871966c064a8fada67e4c33c5f7e0c2542efc1.1646725188.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.git.1646725188.gitgitgadget@gmail.com","subject":"[PATCH 4/9] git-sparse-checkout.txt: update docs for deprecation of 'init'","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-08T07:39:43Z","receivedAt":"2022-03-08T07:40:03Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nThe 'init' subcommand of sparse-checkout was deprecated in ba2f3f58ac\n(\"git-sparse-checkout.txt: update to document init/set/reapply changes\",\n2021-12-14), but a couple places in the manual still assumed it was the\nprimary way to use sparse-checkout. Correct them.\n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-sparse-checkout.txt | 16 ++++++++--------\n 1 file changed, 8 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 42a984306bb..b9e44e3dd4c 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -70,11 +70,11 @@ 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 or `core.sparseCheckoutCone` is false,\n-the input list is considered a list of patterns. This mode is harder\n-to use and less performant, and is thus not recommended. See the\n-\"Sparse Checkout\" section of linkgit:git-read-tree[1] and the \"Pattern\n-Set\" sections below for more details.\n+When `--no-cone` is passed, the input list is considered a list of\n+patterns. This mode is harder to use and less performant, and is thus\n+not recommended. See the \"Sparse Checkout\" section of\n+linkgit:git-read-tree[1] and the \"Pattern Set\" sections below for more\n+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@@ -196,9 +196,9 @@ In addition to the above two patterns, we also expect that all files in the\n root directory are included. If a recursive pattern is added, then all\n leading directories are added as parent patterns.\n \n-By default, when running `git sparse-checkout init`, the root directory is\n-added as a parent pattern. At this point, the sparse-checkout file contains\n-the following patterns:\n+By default, when running `git sparse-checkout set` with no directories\n+specified, the root directory is added as a parent pattern. At this\n+point, the sparse-checkout file contains the following patterns:\n \n ----------------\n /*\n-- \ngitgitgadget\n\n"},{"id":"450708","messageId":"fe37a966699e073543d75e450197e535d021d622.1646725188.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.git.1646725188.gitgitgadget@gmail.com","subject":"[PATCH 5/9] git-sparse-checkout.txt: shuffle some sections and mark as internal","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-08T07:39:44Z","receivedAt":"2022-03-08T07:40:04Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nWith cone mode as the default, it makes sense to discuss it before\nnon-cone mode. Also, the new default means we can just use directories\nin most cases and users do not need to understand patterns or their\nmeanings. Let's take advantage of this to mark several sections as\n\"INTERNALS\", notifying the user that they do not need to know all those\ndetails in order to make use of the sparse-checkout command.\n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-sparse-checkout.txt | 44 +++++++++++++--------------\n 1 file changed, 22 insertions(+), 22 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex b9e44e3dd4c..883b7f4c44f 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -136,8 +136,8 @@ 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-SPARSE CHECKOUT\n----------------\n+INTERNALS -- SPARSE CHECKOUT\n+----------------------------\n \n \"Sparse checkout\" allows populating the working directory sparsely. It\n uses the skip-worktree bit (see linkgit:git-update-index[1]) to tell Git\n@@ -161,24 +161,8 @@ To repopulate the working directory with all files, use the\n `git sparse-checkout disable` command.\n \n \n-FULL PATTERN SET\n-----------------\n-\n-By default, the sparse-checkout file uses the same syntax as `.gitignore`\n-files.\n-\n-While `$GIT_DIR/info/sparse-checkout` is usually used to specify what\n-files are included, you can also specify what files are _not_ included,\n-using negative patterns. For example, to remove the file `unwanted`:\n-\n-----------------\n-/*\n-!unwanted\n-----------------\n-\n-\n-CONE PATTERN SET\n-----------------\n+INTERNALS -- CONE PATTERN SET\n+-----------------------------\n \n The full pattern set allows for arbitrary pattern matches and complicated\n inclusion/exclusion rules. These can result in O(N*M) pattern matches when\n@@ -256,8 +240,24 @@ use `git add` and `git commit` to store them, then remove any remaining files\n manually to ensure Git can behave optimally.\n \n \n-SUBMODULES\n-----------\n+INTERNALS -- FULL PATTERN SET\n+-----------------------------\n+\n+By default, the sparse-checkout file uses the same syntax as `.gitignore`\n+files.\n+\n+While `$GIT_DIR/info/sparse-checkout` is usually used to specify what\n+files are included, you can also specify what files are _not_ included,\n+using negative patterns. For example, to remove the file `unwanted`:\n+\n+----------------\n+/*\n+!unwanted\n+----------------\n+\n+\n+INTERNALS -- SUBMODULES\n+-----------------------\n \n If your repository contains one or more submodules, then submodules\n are populated based on interactions with the `git submodule` command.\n-- \ngitgitgadget\n\n"},{"id":"450709","messageId":"3265f41bcab7202991da5a7a160a85820fbff0c4.1646725188.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.git.1646725188.gitgitgadget@gmail.com","subject":"[PATCH 6/9] git-sparse-checkout.txt: add a new EXAMPLES section","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-08T07:39:45Z","receivedAt":"2022-03-08T07:40:06Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nSince many users like to learn from examples, provide a section in the\nmanual with example commands that would be used and a brief explanation\nof what each does.\n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-sparse-checkout.txt | 42 +++++++++++++++++++++++----\n 1 file changed, 36 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 883b7f4c44f..2cfb1d8f599 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -136,6 +136,42 @@ 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+EXAMPLES\n+--------\n+`git sparse-checkout set MY/DIR1 SUB/DIR2`::\n+\n+\tChange to a sparse checkout with all files (at any depth) under\n+\tMY/DIR1/ and SUB/DIR2/ present in the working copy (plus all\n+\tfiles immediately under MY/ and SUB/ and the toplevel\n+\tdirectory). If already in a sparse checkout, change which files\n+\tare present in the working copy to this new selection. Note\n+\tthat this command will also delete all ignored files in any\n+\tdirectory that no longer has either tracked or\n+\tnon-ignored-untracked files present.\n+\n+`git sparse-checkout disable`::\n+\n+\tRepopulate the working directory with all files, disabling sparse\n+\tcheckouts.\n+\n+`git sparse-checkout add SOME/DIR/ECTORY`::\n+\n+\tAdd all files under SOME/DIR/ECTORY/ (at any depth) to the\n+\tsparse checkout, as well as all files immediately under\n+\tSOME/DIR/ and immediately under SOME/. Must already be in a\n+\tsparse checkout before using this command.\n+\n+`git sparse-checkout reapply`::\n+\n+\tIt is possible for commands to update the working tree in a way\n+\tthat does not respect the selected sparsity directories, either\n+\tbecause of special cases (such as hitting conflicts when\n+\tmerging/rebasing), or because some commands didn't fully support\n+\tsparse checkouts (e.g. the old `recursive` merge backend had\n+\tonly limited support). This command reapplies the existing\n+\tsparse directory specifications to make the working directory\n+\tmatch.\n+\n INTERNALS -- SPARSE CHECKOUT\n ----------------------------\n \n@@ -154,12 +190,6 @@ directory, it updates the skip-worktree bits in the index based\n on this file. The files matching the patterns in the file will\n appear in the working directory, and the rest will not.\n \n-To enable the sparse-checkout feature, run `git sparse-checkout set` to\n-set the patterns you want to use.\n-\n-To repopulate the working directory with all files, use the\n-`git sparse-checkout disable` command.\n-\n \n INTERNALS -- CONE PATTERN SET\n -----------------------------\n-- \ngitgitgadget\n\n"},{"id":"450710","messageId":"bdbf61ee6a0c3cff1a570f4ef166f38afd9a4242.1646725188.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.git.1646725188.gitgitgadget@gmail.com","subject":"[PATCH 7/9] git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a bit","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-08T07:39:46Z","receivedAt":"2022-03-08T07:40:07Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-sparse-checkout.txt | 23 +++++++++++++++++------\n 1 file changed, 17 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 2cfb1d8f599..35e4e2d809e 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -273,12 +273,23 @@ manually to ensure Git can behave optimally.\n INTERNALS -- FULL PATTERN SET\n -----------------------------\n \n-By default, the sparse-checkout file uses the same syntax as `.gitignore`\n-files.\n-\n-While `$GIT_DIR/info/sparse-checkout` is usually used to specify what\n-files are included, you can also specify what files are _not_ included,\n-using negative patterns. For example, to remove the file `unwanted`:\n+As noted above, the sparse-checkout file uses the same syntax as\n+`.gitignore` files; see linkgit:gitignore[5] for details. Here,\n+though, the patterns are usually being used to select which files to\n+include rather than which files to exclude. (However, it can get a\n+bit confusing since gitignore-style patterns have negations defined by\n+patterns which begin with a '!', so you can also select files to _not_\n+include.)\n+\n+For example, to select everything, and then to remove the file\n+`unwanted` (so that every file will appear in your working tree except\n+the file named `unwanted`):\n+\n+ git sparse-checkout set --no-cone '/*' '!unwanted'\n+\n+These patterns are just placed into the\n+`$GIT_DIR/info/sparse-checkout` as-is, so the contents of that file\n+at this point would be\n \n ----------------\n /*\n-- \ngitgitgadget\n\n"},{"id":"450711","messageId":"3e35d62c5eefe5ef272cf0b3cbd10d94e6bbabd2.1646725188.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.git.1646725188.gitgitgadget@gmail.com","subject":"[PATCH 8/9] git-sparse-checkout.txt: mark non-cone mode as deprecated","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-08T07:39:47Z","receivedAt":"2022-03-08T07:40:09Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nWhile we have no current plans to actually remove --no-cone mode, we\nthink users would be better off not using it. Update the documentation\naccordingly, including explaining why we think non-cone mode is\nproblematic for users.\n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-sparse-checkout.txt | 86 +++++++++++++++++++++++++--\n 1 file changed, 82 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 35e4e2d809e..11792187224 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -71,10 +71,13 @@ 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 less performant, and is thus\n-not recommended. See the \"Sparse Checkout\" section of\n-linkgit:git-read-tree[1] and the \"Pattern Set\" sections below for more\n-details.\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@@ -190,6 +193,81 @@ directory, it updates the skip-worktree bits in the index based\n on this file. The files matching the patterns in the file will\n appear in the working directory, and the rest will not.\n \n+INTERNALS -- NON-CONE PROBLEMS\n+------------------------------\n+\n+The `$GIT_DIR/info/sparse-checkout` file populated by the `set` and\n+`add` subcommands is defined to be a bunch of patterns (one per line)\n+using the same syntax as `.gitignore` files. In cone mode, these\n+patterns are restricted to matching directories (and users only ever\n+need supply or see directory names), while in non-cone mode any\n+gitignore-style pattern is permitted. Using the full gitignore-style\n+patterns in non-cone mode has a number of shortcomings:\n+\n+ * Fundamentally, it makes various worktree-updating processes (pull,\n+ merge, rebase, switch, reset, checkout, etc.) require O(N*M) pattern\n+ matches, where N is the number of patterns and M is the number of\n+ paths in the index. This scales poorly.\n+\n+ * Avoiding the scaling issue has to be done via limiting the number\n+ of patterns via specifying leading directory name or glob.\n+\n+ * Passing globs on the command line is error-prone as users may\n+ forget to quote the glob, causing the shell to expand it into all\n+ matching files and pass them all individually along to\n+ sparse-checkout set/add. This both exacerbates the scaling\n+ problem, and hardcodes the list of selected files to those which\n+ were present at the time the initial set/add subcommand was run\n+ (and thus ignoring other files matching the same glob which come\n+ into the working tree after switching branches or pulling down\n+ updates).\n+\n+ * It uses \"ignore\"/\"exclude\" syntax for selecting what to \"include\",\n+ which periodically causes confusion.\n+\n+ * It introduces inconsistencies in the Git command line, since other\n+ commands use pathspecs, but sparse-checkout (in non-cone mode) uses\n+ gitignore patterns.\n+\n+ * It has edge cases where the \"right\" behavior is unclear. Two examples:\n+\n+ First, two users are in a subdirectory, and the first runs\n+ git sparse-checkout set '/toplevel-dir/*.c'\n+ while the second runs\n+ git sparse-checkout set relative-dir\n+ Should those arguments be transliterated into\n+ current/subdirectory/toplevel-dir/*.c\n+ and\n+ current/subdirectory/relative-dir\n+ before inserting into the sparse-checkout file? The user who typed\n+ the first command is probably aware that arguments to set/add are\n+ supposed to be patterns in non-cone mode, and probably would not be\n+ happy with such a transliteration. However, many gitignore-style\n+ patterns are just paths, which might be what the user who typed the\n+ second command was thinking, and they'd be upset if their argument\n+ wasn't transliterated.\n+\n+ Second, what should bash-completion complete on for set/add commands\n+ for non-cone users? If it suggests paths, is it exacerbating the\n+ problem above? Also, if it suggests paths, what if the user has a\n+ file or directory that begins with either a '!' or '#' or has a '*',\n+ '\\', '?', '[', or ']' in its name? And if it suggests paths, will\n+ it complete \"/pro\" to \"/proc\" (in the root filesytem) rather than to\n+ \"/progress.txt\" in the current directory? (Note that users are\n+ likely to want to start paths with a leading '/' in non-cone mode,\n+ for the same reason that .gitignore files often have one.)\n+ Completing on files or directories might give nasty surprises in\n+ all these cases.\n+\n+ * The excessive flexibility made other extensions essentially\n+ impractical. `--sparse-index` may not have been feasible in\n+ non-cone mode, but even if it was, it would have been far more work\n+ to implement and may have been too slow in practice. Some ideas for\n+ adding coupling between partial clones and sparse checkouts are only\n+ practical with a more restricted set of paths.\n+\n+For all these reasons, non-cone mode is deprecated. Please switch to\n+using cone mode.\n \n INTERNALS -- CONE PATTERN SET\n -----------------------------\n-- \ngitgitgadget\n\n"},{"id":"450712","messageId":"e7d3ff70914e1ba4622c2cb6cd30453089e5a53f.1646725188.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.git.1646725188.gitgitgadget@gmail.com","subject":"[PATCH 9/9] Documentation: some sparsity wording clarifications","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-08T07:39:48Z","receivedAt":"2022-03-08T07:40:13Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nImprove the wording for a couple paragraphs in two different manuals\nrelating to sparse behavior.\n\nReported-by: Ævar Arnfjörð Bjarmason \nSigned-off-by: Elijah Newren \n---\n Documentation/git-read-tree.txt | 9 +++++----\n Documentation/git-sparse-checkout.txt | 10 +++++-----\n 2 files changed, 10 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\nindex 99bb387134d..cbafb1aed49 100644\n--- a/Documentation/git-read-tree.txt\n+++ b/Documentation/git-read-tree.txt\n@@ -375,10 +375,11 @@ have finished your work-in-progress), attempt the merge again.\n SPARSE CHECKOUT\n ---------------\n \n-Note: The `update-index` and `read-tree` primitives for supporting the\n-skip-worktree bit predated the introduction of\n-linkgit:git-sparse-checkout[1]. Users are encouraged to use\n-`sparse-checkout` in preference to these low-level primitives.\n+Note: The skip-worktree capabilities in linkgit:git-update-index[1]\n+and `read-tree` predated the introduction of\n+linkgit:git-sparse-checkout[1]. Users are encouraged to use the\n+`sparse-checkout` command in preference to these plumbing commands for\n+sparse-checkout/skip-worktree related needs.\n \n \"Sparse checkout\" allows populating the working directory sparsely.\n It uses the skip-worktree bit (see linkgit:git-update-index[1]) to\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 11792187224..06f23660f63 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -15,11 +15,11 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-This command is used to create sparse checkouts, which means that it\n-changes the working tree from having all tracked files present, to only\n-have a subset of them. It can also switch which subset of files are\n-present, or undo and go back to having all tracked files present in the\n-working copy.\n+This command is used to create sparse checkouts, which change the\n+working tree from having all tracked files present to only having a\n+subset of those files. It can also switch which subset of files are\n+present, or undo and go back to having all tracked files present in\n+the working copy.\n \n The subset of files is chosen by providing a list of directories in\n cone mode (the default), or by providing a list of patterns in\n-- \ngitgitgadget\n"},{"id":"450734","messageId":"cbbf31e0-14fb-07fa-db12-aecbbeb1e592@github.com","threadId":"57519","inReplyTo":"b174b42ed82a45f57959a2a493dcfb32bf26c12d.1646725188.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 2/9] sparse-checkout: make --cone the default","fromName":"Derrick Stolee","fromEmail":"derrickstolee@github.com","sentAt":"2022-03-08T14:26:47Z","receivedAt":"2022-03-08T14:26:51Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"On 3/8/2022 2:39 AM, Elijah Newren via GitGitGadget wrote:\n> From: Elijah Newren \n> \n> Make cone mode the default, and update the documentation accordingly.\n\nDoc changes look good.\n\n> --- a/builtin/sparse-checkout.c\n> +++ b/builtin/sparse-checkout.c\n> @@ -397,7 +397,7 @@ static int update_modes(int *cone_mode, int *sparse_index)\n> \n> \t/* Set cone/non-cone mode appropriately */\n> \tcore_apply_sparse_checkout = 1;\n> -\tif (*cone_mode == 1) {\n> +\tif (*cone_mode == 1 || *cone_mode == -1) {\n\nPart of me likes the fact that you're pointing out \"if it is\nenabled directly or not set at all\", but maybe it would be\nbest to do\n\n\tif (*cone_mode) {\n\nWhat do you think?\n\nThanks,\n-Stolee\n"},{"id":"450735","messageId":"5c59964a-a3ce-3723-8044-16727d9d3170@github.com","threadId":"57519","inReplyTo":"3265f41bcab7202991da5a7a160a85820fbff0c4.1646725188.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 6/9] git-sparse-checkout.txt: add a new EXAMPLES section","fromName":"Derrick Stolee","fromEmail":"derrickstolee@github.com","sentAt":"2022-03-08T14:30:39Z","receivedAt":"2022-03-08T14:30:44Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"On 3/8/2022 2:39 AM, Elijah Newren via GitGitGadget wrote:\n> From: Elijah Newren \n> \n> Since many users like to learn from examples, provide a section in the\n> manual with example commands that would be used and a brief explanation\n> of what each does.\n\nExamples are great!\n \n> +`git sparse-checkout reapply`::\n> +\n> +\tIt is possible for commands to update the working tree in a way\n> +\tthat does not respect the selected sparsity directories, either\n> +\tbecause of special cases (such as hitting conflicts when\n> +\tmerging/rebasing), or because some commands didn't fully support\n> +\tsparse checkouts (e.g. the old `recursive` merge backend had\n> +\tonly limited support). This command reapplies the existing\n> +\tsparse directory specifications to make the working directory\n> +\tmatch.\n\nThis focuses on how a Git command might cause extra data, but it\ndoesn't mention how other tools might create ignored files outside\nof the sparse-checkout and this will clean them up. Do you want to\nadd that, or do you prefer focusing on just Git reasons?\n\nThanks,\n-Stolee\n"},{"id":"450736","messageId":"be0752cb-1802-04ad-7a71-ffea4f74d5f0@github.com","threadId":"57519","inReplyTo":"pull.1148.git.1646725188.gitgitgadget@gmail.com","subject":"Re: [PATCH 0/9] sparse-checkout: make cone mode the default","fromName":"Derrick Stolee","fromEmail":"derrickstolee@github.com","sentAt":"2022-03-08T14:34:43Z","receivedAt":"2022-03-08T14:34:49Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"On 3/8/2022 2:39 AM, Elijah Newren via GitGitGadget wrote:\n> == Maintainer Note ==\n> \n> Depends on a merge of en/present-despite-skipped into master.\n> \n> == Overview ==\n> \n> This patch changes the default mode for sparse-checkout from non-cone mode\n> to cone-mode, and marks non-cone mode as deprecated. There is no plan to\n> remove non-cone mode, we are merely recommending against its use.\n> \n> The code change is pretty small, and most of this series is about\n> documentation updates -- to focus on directories rather than patterns, to\n> explain the new default, to explain why we are deprecating non-cone mode\n> (the final patch), and to make other related cleanups to simplify the\n> manual.\n\nI made a couple comments with potential ways to improve the series, but\nin general this series is high quality without any changes. I'm happy\nwith it as-is.\n\nI'm particularly happy with the additional examples of how to use the\nsparse-checkout builtin. That should really improve discoverability.\n\n> == Alternative ==\n> \n> There is one primary alternative to this series: make sparse-checkout error\n> when neither --cone nor --no-cone are specified (so that there is no\n> default), and wait until a future date to make --cone the default.\n\nI appreciate considering this alternative, and I'd be open to it, if\nneeded. My gut feeling is that we don't need it.\n\nThanks,\n-Stolee\n\n"},{"id":"451195","messageId":"CABPp-BGfke=t99wY2OQuG3SnbFhRd1zpPFW8JqEBN-wANgVM1A@mail.gmail.com","threadId":"57519","inReplyTo":"5c59964a-a3ce-3723-8044-16727d9d3170@github.com","subject":"Re: [PATCH 6/9] git-sparse-checkout.txt: add a new EXAMPLES section","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2022-03-12T01:58:50Z","receivedAt":"2022-03-12T01:59:06Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"On Tue, Mar 8, 2022 at 6:30 AM Derrick Stolee wrote:\n>\n> On 3/8/2022 2:39 AM, Elijah Newren via GitGitGadget wrote:\n> > From: Elijah Newren \n> >\n> > Since many users like to learn from examples, provide a section in the\n> > manual with example commands that would be used and a brief explanation\n> > of what each does.\n>\n> Examples are great!\n>\n> > +`git sparse-checkout reapply`::\n> > +\n> > + It is possible for commands to update the working tree in a way\n> > + that does not respect the selected sparsity directories, either\n> > + because of special cases (such as hitting conflicts when\n> > + merging/rebasing), or because some commands didn't fully support\n> > + sparse checkouts (e.g. the old `recursive` merge backend had\n> > + only limited support). This command reapplies the existing\n> > + sparse directory specifications to make the working directory\n> > + match.\n>\n> This focuses on how a Git command might cause extra data, but it\n> doesn't mention how other tools might create ignored files outside\n> of the sparse-checkout and this will clean them up. Do you want to\n> add that, or do you prefer focusing on just Git reasons?\n\nDoes that happen in a significant number of cases? Prior to\nen/present-despite-skipped, it was essentially a null set of cases.\nAfter it, we'd need:\n * the file to be tracked (reapply doesn't touch untracked or ignored files)\n * the file to have been SKIP_WORKTREE prior to the other tool modifying it\n * the file has to have its contents match what is staged in the index\nand then reapply would clean the file out.\n\nI guess there is kind of a converse case of someone manually removing\nthe SKIP_WORKTREE bit via direct manipulation using `git update-index\n--no-skip-worktree $PATH` and removing the file locally, and then\nusing `reapply` to get it back, but that seems like a really unlikely\nusecase.\n\n\n Maybe if I just made a simple tweak to the wording:\n\n...selected sparsity directories. This can come from tools external to\nGit writing files, or even affect Git commands because of either\nspecial cases...\n\ndoes that sound good? I'll submit a re-roll with that but I'm open to\nalternative wordings.\n"},{"id":"451196","messageId":"CABPp-BHeYA1jErw7rm2fk6CE9W-meskX2xkTiAei-kCazyjLdQ@mail.gmail.com","threadId":"57519","inReplyTo":"cbbf31e0-14fb-07fa-db12-aecbbeb1e592@github.com","subject":"Re: [PATCH 2/9] sparse-checkout: make --cone the default","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2022-03-12T02:01:37Z","receivedAt":"2022-03-12T02:01:52Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"On Tue, Mar 8, 2022 at 6:26 AM Derrick Stolee wrote:\n>\n> On 3/8/2022 2:39 AM, Elijah Newren via GitGitGadget wrote:\n> > From: Elijah Newren \n> >\n> > Make cone mode the default, and update the documentation accordingly.\n>\n> Doc changes look good.\n>\n> > --- a/builtin/sparse-checkout.c\n> > +++ b/builtin/sparse-checkout.c\n> > @@ -397,7 +397,7 @@ static int update_modes(int *cone_mode, int *sparse_index)\n> >\n> > /* Set cone/non-cone mode appropriately */\n> > core_apply_sparse_checkout = 1;\n> > - if (*cone_mode == 1) {\n> > + if (*cone_mode == 1 || *cone_mode == -1) {\n>\n> Part of me likes the fact that you're pointing out \"if it is\n> enabled directly or not set at all\", but maybe it would be\n> best to do\n>\n> if (*cone_mode) {\n>\n> What do you think?\n\nHow about if I switch it, but add a comment since the special \"unset\"\nvalue of -1 may not be clear:\n\n if (*cone_mode) { /* also handles \"not specified\" (value of -1) */\n"},{"id":"451197","messageId":"pull.1148.v2.git.1647054681.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.git.1646725188.gitgitgadget@gmail.com","subject":"[PATCH v2 0/9] sparse-checkout: make cone mode the default","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-12T03:11:12Z","receivedAt":"2022-03-12T03:11:29Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"== Updates Log ==\n\nChanges since v1:\n\n * rebased on master, to remove dependence on en/present-despite-skipped\n (which has since merged to master). Earlier version of series wasn't\n picked up anyway, so rebasing should be safe.\n * Wording and code style tweaks suggested by Stolee in his review\n\n== Overview ==\n\nThis patch changes the default mode for sparse-checkout from non-cone mode\nto cone-mode, and marks non-cone mode as deprecated. There is no plan to\nremove non-cone mode, we are merely recommending against its use.\n\nThe code change is pretty small, and most of this series is about\ndocumentation updates -- to focus on directories rather than patterns, to\nexplain the new default, to explain why we are deprecating non-cone mode\n(the final patch), and to make other related cleanups to simplify the\nmanual.\n\nPatch 1: Update tests to not assume cone-mode is the default Patch 2: Make\ncone-mode the default Patches 3-9: Various updates to\ngit-sparse-checkout.txt, divided up for ease of review\n\n== Alternative ==\n\nThere is one primary alternative to this series: make sparse-checkout error\nwhen neither --cone nor --no-cone are specified (so that there is no\ndefault), and wait until a future date to make --cone the default. That'd be\nreasonable, but I had three reason to avoid going this route (note that item\n2 means there's little practical difference between cone-mode-as-default and\nno-mode-is-default):\n\n 1. git-sparse-checkout.txt has the following huge warning early in the\n manual:\n\n\"\"\" THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR, AND THE BEHAVIOR OF OTHER\nCOMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN THE\nFUTURE. \"\"\"\n\n 2. If users are unaware of the default change and attempt to provide\n patterns instead of directories, then they will get error messages added\n from en/sparse-checkout-fixes. They can learn at that time to get around\n the error messages by providing --no-cone.\n\n 3. If users are unaware of the default change and provide directories, then\n that's where non-cone mode and cone mode overlap and things happen to\n work. (There is a slight difference in that cone mode will include files\n from parent directories of any specified directory, but that means the\n user gets a few more files in their sparse-checkout with cone mode than\n they would with non-cone mode.)\n\n== CCs ==\n\nElijah Newren (9):\n tests: stop assuming --no-cone is the default mode for sparse-checkout\n sparse-checkout: make --cone the default\n git-sparse-checkout.txt: wording updates for the cone mode default\n git-sparse-checkout.txt: update docs for deprecation of 'init'\n git-sparse-checkout.txt: shuffle some sections and mark as internal\n git-sparse-checkout.txt: add a new EXAMPLES section\n git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a\n bit\n git-sparse-checkout.txt: mark non-cone mode as deprecated\n Documentation: some sparsity wording clarifications\n\n Documentation/git-read-tree.txt | 9 +-\n Documentation/git-sparse-checkout.txt | 249 +++++++++++++++++++-------\n builtin/sparse-checkout.c | 2 +-\n t/t1091-sparse-checkout-builtin.sh | 15 +-\n t/t3602-rm-sparse-checkout.sh | 6 +-\n t/t3705-add-sparse-checkout.sh | 4 +-\n t/t6428-merge-conflicts-sparse.sh | 4 +-\n t/t7002-mv-sparse-checkout.sh | 2 +-\n t/t7012-skip-worktree-writing.sh | 2 +-\n 9 files changed, 207 insertions(+), 86 deletions(-)\n\n\nbase-commit: 1a4874565fa3b6668042216189551b98b4dc0b1b\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1148%2Fnewren%2Fsparse-checkout-default-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1148/newren/sparse-checkout-default-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/1148\n\nRange-diff vs v1:\n\n 1: 8c3e730e86b = 1: 05dba7069c5 tests: stop assuming --no-cone is the default mode for sparse-checkout\n 2: b174b42ed82 ! 2: a53179764bc sparse-checkout: make --cone the default\n @@ builtin/sparse-checkout.c: static int update_modes(int *cone_mode, int *sparse_i\n \t/* Set cone/non-cone mode appropriately */\n \tcore_apply_sparse_checkout = 1;\n -\tif (*cone_mode == 1) {\n -+\tif (*cone_mode == 1 || *cone_mode == -1) {\n ++\tif (*cone_mode) { /* also handles \"not specified\" (value of -1) */\n \t\tmode = MODE_CONE_PATTERNS;\n \t\tcore_sparse_checkout_cone = 1;\n \t} else {\n 3: f98b3fac78a = 3: 8eab21996c7 git-sparse-checkout.txt: wording updates for the cone mode default\n 4: cd871966c06 = 4: eb3b318b39e git-sparse-checkout.txt: update docs for deprecation of 'init'\n 5: fe37a966699 = 5: 7333198b778 git-sparse-checkout.txt: shuffle some sections and mark as internal\n 6: 3265f41bcab ! 6: a814ea9e8d2 git-sparse-checkout.txt: add a new EXAMPLES section\n @@ Documentation/git-sparse-checkout.txt: paths to pass to a subsequent 'set' or 'a\n +\n +`git sparse-checkout reapply`::\n +\n -+\tIt is possible for commands to update the working tree in a way\n -+\tthat does not respect the selected sparsity directories, either\n -+\tbecause of special cases (such as hitting conflicts when\n -+\tmerging/rebasing), or because some commands didn't fully support\n -+\tsparse checkouts (e.g. the old `recursive` merge backend had\n -+\tonly limited support). This command reapplies the existing\n -+\tsparse directory specifications to make the working directory\n -+\tmatch.\n ++\tIt is possible for commands to update the working tree in a\n ++\tway that does not respect the selected sparsity directories.\n ++\tThis can come from tools external to Git writing files, or\n ++\teven affect Git commands because of either special cases (such\n ++\tas hitting conflicts when merging/rebasing), or because some\n ++\tcommands didn't fully support sparse checkouts (e.g. the old\n ++\t`recursive` merge backend had only limited support). This\n ++\tcommand reapplies the existing sparse directory specifications\n ++\tto make the working directory match.\n +\n INTERNALS -- SPARSE CHECKOUT\n ----------------------------\n 7: bdbf61ee6a0 = 7: 78028ecaa58 git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a bit\n 8: 3e35d62c5ee = 8: 2d2b81986a5 git-sparse-checkout.txt: mark non-cone mode as deprecated\n 9: e7d3ff70914 = 9: 4b89a3392b0 Documentation: some sparsity wording clarifications\n\n-- \ngitgitgadget\n"},{"id":"451198","messageId":"a53179764bc5d411726a095a587ea728aa9a20d3.1647054681.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.v2.git.1647054681.gitgitgadget@gmail.com","subject":"[PATCH v2 2/9] sparse-checkout: make --cone the default","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-12T03:11:14Z","receivedAt":"2022-03-12T03:11:33Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nMake cone mode the default, and update the documentation accordingly.\n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-sparse-checkout.txt | 20 ++++++++++----------\n builtin/sparse-checkout.c | 2 +-\n 2 files changed, 11 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 88e55f432f3..4ef03120797 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -22,8 +22,8 @@ present, or undo and go back to having all tracked files present in the\n working copy.\n \n The subset of files is chosen by providing a list of directories in\n-cone mode (which is recommended), or by providing a list of patterns\n-in non-cone mode.\n+cone mode (the default), or by providing a list of patterns in\n+non-cone mode.\n \n When in a sparse-checkout, other Git commands behave a bit differently.\n For example, switching branches will not update paths outside the\n@@ -60,7 +60,7 @@ 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-When `--cone` is passed or `core.sparseCheckoutCone` is enabled, the\n+When `--cone` is passed or `core.sparseCheckoutCone` is not false, the\n input list is considered a list of directories. This allows for\n better performance with a limited set of patterns (see 'CONE PATTERN\n SET' below). The input format matches the output of `git ls-tree\n@@ -68,10 +68,9 @@ SET' below). The input format matches the output of `git ls-tree\n double quote (\") as C-style quoted strings. Note that the set command\n will write patterns to the sparse-checkout file to include all files\n contained in those directories (recursively) as well as files that are\n-siblings of ancestor directories. This may become the default in the\n-future; --no-cone can be passed to request non-cone mode.\n+siblings of ancestor directories.\n +\n-When `--no-cone` is passed or `core.sparseCheckoutCone` is not enabled,\n+When `--no-cone` is passed or `core.sparseCheckoutCone` is false,\n the input list is considered a list of patterns. This mode is harder\n to use and less performant, and is thus not recommended. See the\n \"Sparse Checkout\" section of linkgit:git-read-tree[1] and the \"Pattern\n@@ -227,10 +226,11 @@ patterns. The resulting sparse-checkout file is now\n Here, order matters, so the negative patterns are overridden by the positive\n patterns that appear lower in the file.\n \n-If `core.sparseCheckoutCone=true`, then Git will parse the sparse-checkout file\n-expecting patterns of these types. Git will warn if the patterns do not match.\n-If the patterns do match the expected format, then Git will use faster hash-\n-based algorithms to compute inclusion in the sparse-checkout.\n+If `core.sparseCheckoutCone=true` (set by default or with an explicit\n+`--cone`), then Git will parse the sparse-checkout file expecting\n+patterns of these types. Git will warn if the patterns do not match. If\n+the patterns do match the expected format, then Git will use faster\n+hash-based algorithms to compute inclusion in the sparse-checkout.\n \n In the cone mode case, the `git sparse-checkout list` subcommand will list the\n directories that define the recursive patterns. For the example sparse-checkout\ndiff --git a/builtin/sparse-checkout.c b/builtin/sparse-checkout.c\nindex 5518ed47f6c..6603a0cc029 100644\n--- a/builtin/sparse-checkout.c\n+++ b/builtin/sparse-checkout.c\n@@ -397,7 +397,7 @@ static int update_modes(int *cone_mode, int *sparse_index)\n \n \t/* Set cone/non-cone mode appropriately */\n \tcore_apply_sparse_checkout = 1;\n-\tif (*cone_mode == 1) {\n+\tif (*cone_mode) { /* also handles \"not specified\" (value of -1) */\n \t\tmode = MODE_CONE_PATTERNS;\n \t\tcore_sparse_checkout_cone = 1;\n \t} else {\n-- \ngitgitgadget\n\n"},{"id":"451199","messageId":"05dba7069c5e0c1aec1a7206f9cbea593d8d68cb.1647054681.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.v2.git.1647054681.gitgitgadget@gmail.com","subject":"[PATCH v2 1/9] tests: stop assuming --no-cone is the default mode for sparse-checkout","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-12T03:11:13Z","receivedAt":"2022-03-12T03:11:33Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nAdd an explicit --no-cone to several sparse-checkout invocations in\npreparation for changing the default to cone mode.\n\nSigned-off-by: Elijah Newren \n---\n t/t1091-sparse-checkout-builtin.sh | 15 ++++++++-------\n t/t3602-rm-sparse-checkout.sh | 6 +++---\n t/t3705-add-sparse-checkout.sh | 4 ++--\n t/t6428-merge-conflicts-sparse.sh | 4 ++--\n t/t7002-mv-sparse-checkout.sh | 2 +-\n t/t7012-skip-worktree-writing.sh | 2 +-\n 6 files changed, 17 insertions(+), 16 deletions(-)\n\ndiff --git a/t/t1091-sparse-checkout-builtin.sh b/t/t1091-sparse-checkout-builtin.sh\nindex 9a900310186..de1ec89007d 100755\n--- a/t/t1091-sparse-checkout-builtin.sh\n+++ b/t/t1091-sparse-checkout-builtin.sh\n@@ -72,7 +72,7 @@ test_expect_success 'git sparse-checkout list (populated)' '\n '\n \n test_expect_success 'git sparse-checkout init' '\n-\tgit -C repo sparse-checkout init &&\n+\tgit -C repo sparse-checkout init --no-cone &&\n \tcat >expect <<-\\EOF &&\n \t/*\n \t!/*/\n@@ -111,6 +111,7 @@ test_expect_success 'init with existing sparse-checkout' '\n \n test_expect_success 'clone --sparse' '\n \tgit clone --sparse \"file://$(pwd)/repo\" clone &&\n+\tgit -C clone sparse-checkout reapply --no-cone &&\n \tgit -C clone sparse-checkout list >actual &&\n \tcat >expect <<-\\EOF &&\n \t/*\n@@ -124,7 +125,7 @@ test_expect_success 'switching to cone mode with non-cone mode patterns' '\n \tgit init bad-patterns &&\n \t(\n \t\tcd bad-patterns &&\n-\t\tgit sparse-checkout init &&\n+\t\tgit sparse-checkout init --no-cone &&\n \t\tgit sparse-checkout add dir &&\n \t\tgit config --worktree core.sparseCheckoutCone true &&\n \t\ttest_must_fail git sparse-checkout add dir 2>err &&\n@@ -402,7 +403,7 @@ test_expect_success 'revert to old sparse-checkout on empty update' '\n \t\tgit sparse-checkout set nothing 2>err &&\n \t\ttest_i18ngrep ! \"Sparse checkout leaves no entry on working directory\" err &&\n \t\ttest_i18ngrep ! \".git/index.lock\" err &&\n-\t\tgit sparse-checkout set file\n+\t\tgit sparse-checkout set --no-cone file\n \t)\n '\n \n@@ -424,7 +425,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with dirty status'\n \tgit clone repo dirty &&\n \techo dirty >dirty/folder1/a &&\n \n-\tgit -C dirty sparse-checkout init 2>err &&\n+\tgit -C dirty sparse-checkout init --no-cone 2>err &&\n \ttest_i18ngrep \"warning.*The following paths are not up to date\" err &&\n \n \tgit -C dirty sparse-checkout set /folder2/* /deep/deeper1/* 2>err &&\n@@ -435,7 +436,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with dirty status'\n \ttest_must_be_empty err &&\n \n \tgit -C dirty reset --hard &&\n-\tgit -C dirty sparse-checkout init &&\n+\tgit -C dirty sparse-checkout init --no-cone &&\n \tgit -C dirty sparse-checkout set /folder2/* /deep/deeper1/* &&\n \ttest_path_is_missing dirty/folder1/a &&\n \tgit -C dirty sparse-checkout disable &&\n@@ -451,7 +452,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with unmerged stat\n \tEOF\n \tgit -C unmerged update-index --index-info err &&\n+\tgit -C unmerged sparse-checkout init --no-cone 2>err &&\n \ttest_i18ngrep \"warning.*The following paths are unmerged\" err &&\n \n \tgit -C unmerged sparse-checkout set /folder2/* /deep/deeper1/* 2>err &&\n@@ -462,7 +463,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with unmerged stat\n \ttest_i18ngrep \"warning.*The following paths are unmerged\" err &&\n \n \tgit -C unmerged reset --hard &&\n-\tgit -C unmerged sparse-checkout init &&\n+\tgit -C unmerged sparse-checkout init --no-cone &&\n \tgit -C unmerged sparse-checkout set /folder2/* /deep/deeper1/* &&\n \tgit -C unmerged sparse-checkout disable\n '\ndiff --git a/t/t3602-rm-sparse-checkout.sh b/t/t3602-rm-sparse-checkout.sh\nindex 034ec010910..08580fd3dcc 100755\n--- a/t/t3602-rm-sparse-checkout.sh\n+++ b/t/t3602-rm-sparse-checkout.sh\n@@ -30,7 +30,7 @@ test_expect_success 'setup' \"\n for opt in \"\" -f --dry-run\n do\n \ttest_expect_success \"rm${opt:+ $opt} does not remove sparse entries\" '\n-\t\tgit sparse-checkout set a &&\n+\t\tgit sparse-checkout set --no-cone a &&\n \t\ttest_must_fail git rm $opt b 2>stderr &&\n \t\ttest_cmp b_error_and_hint stderr &&\n \t\tgit ls-files --error-unmatch b\n@@ -118,7 +118,7 @@ test_expect_success 'can remove files from non-sparse dir' '\n \ttest_commit w/f &&\n \ttest_commit x/y/f &&\n \n-\tgit sparse-checkout set w !/x y/ &&\n+\tgit sparse-checkout set --no-cone w !/x y/ &&\n \tgit rm w/f.t x/y/f.t 2>stderr &&\n \ttest_must_be_empty stderr\n '\n@@ -128,7 +128,7 @@ test_expect_success 'refuse to remove non-skip-worktree file from sparse dir' '\n \tgit sparse-checkout disable &&\n \tmkdir -p x/y/z &&\n \ttest_commit x/y/z/f &&\n-\tgit sparse-checkout set !/x y/ !x/y/z &&\n+\tgit sparse-checkout set --no-cone !/x y/ !x/y/z &&\n \n \tgit update-index --no-skip-worktree x/y/z/f.t &&\n \ttest_must_fail git rm x/y/z/f.t 2>stderr &&\ndiff --git a/t/t3705-add-sparse-checkout.sh b/t/t3705-add-sparse-checkout.sh\nindex 95609046c61..2bade9e804f 100755\n--- a/t/t3705-add-sparse-checkout.sh\n+++ b/t/t3705-add-sparse-checkout.sh\n@@ -166,7 +166,7 @@ test_expect_success 'do not warn when pathspec matches dense entries' '\n test_expect_success 'git add fails outside of sparse-checkout definition' '\n \ttest_when_finished git sparse-checkout disable &&\n \ttest_commit a &&\n-\tgit sparse-checkout init &&\n+\tgit sparse-checkout init --no-cone &&\n \tgit sparse-checkout set a &&\n \techo >>sparse_entry &&\n \n@@ -208,7 +208,7 @@ test_expect_success 'add obeys advice.updateSparsePath' '\n '\n \n test_expect_success 'add allows sparse entries with --sparse' '\n-\tgit sparse-checkout set a &&\n+\tgit sparse-checkout set --no-cone a &&\n \techo modified >sparse_entry &&\n \ttest_must_fail git add sparse_entry &&\n \ttest_sparse_entry_unchanged &&\ndiff --git a/t/t6428-merge-conflicts-sparse.sh b/t/t6428-merge-conflicts-sparse.sh\nindex 142c9aaabc5..064be1b629e 100755\n--- a/t/t6428-merge-conflicts-sparse.sh\n+++ b/t/t6428-merge-conflicts-sparse.sh\n@@ -87,7 +87,7 @@ test_expect_success 'conflicting entries written to worktree even if sparse' '\n \t\ttest_path_is_file numerals &&\n \n \t\tgit sparse-checkout init &&\n-\t\tgit sparse-checkout set README &&\n+\t\tgit sparse-checkout set --no-cone README &&\n \n \t\ttest_path_is_file README &&\n \t\ttest_path_is_missing numerals &&\n@@ -123,7 +123,7 @@ test_expect_success 'present-despite-SKIP_WORKTREE handled reasonably' '\n \t\ttest_path_is_file numerals &&\n \n \t\tgit sparse-checkout init &&\n-\t\tgit sparse-checkout set README &&\n+\t\tgit sparse-checkout set --no-cone README &&\n \n \t\ttest_path_is_file README &&\n \t\ttest_path_is_missing numerals &&\ndiff --git a/t/t7002-mv-sparse-checkout.sh b/t/t7002-mv-sparse-checkout.sh\nindex 1d3d2aca21c..f0f7cbfcdb7 100755\n--- a/t/t7002-mv-sparse-checkout.sh\n+++ b/t/t7002-mv-sparse-checkout.sh\n@@ -27,7 +27,7 @@ test_expect_success 'setup' \"\n test_expect_success 'mv refuses to move sparse-to-sparse' '\n \ttest_when_finished rm -f e &&\n \tgit reset --hard &&\n-\tgit sparse-checkout set a &&\n+\tgit sparse-checkout set --no-cone a &&\n \ttouch b &&\n \ttest_must_fail git mv b e 2>stderr &&\n \tcat sparse_error_header >expect &&\ndiff --git a/t/t7012-skip-worktree-writing.sh b/t/t7012-skip-worktree-writing.sh\nindex cb9f1a6981e..cd5c20fe51b 100755\n--- a/t/t7012-skip-worktree-writing.sh\n+++ b/t/t7012-skip-worktree-writing.sh\n@@ -151,7 +151,7 @@ test_expect_success 'stash restore in sparse checkout' '\n \n \t\tgit stash push &&\n \n-\t\tgit sparse-checkout set subdir &&\n+\t\tgit sparse-checkout set --no-cone subdir &&\n \n \t\t# Ensure after sparse-checkout we only have expected files\n \t\tcat >expect <<-EOF &&\n-- \ngitgitgadget\n\n"},{"id":"451200","messageId":"8eab21996c7984a31cb954dd787ee54ce77dfa69.1647054681.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.v2.git.1647054681.gitgitgadget@gmail.com","subject":"[PATCH v2 3/9] git-sparse-checkout.txt: wording updates for the cone mode default","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-12T03:11:15Z","receivedAt":"2022-03-12T03:11:37Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nNow that cone mode is the default, we'd like to focus on the arguments\nto set/add being directories rather than patterns, and it probably makes\nsense to provide an earlier heads up that files from leading directories\nget included as well.\n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-sparse-checkout.txt | 31 +++++++++++++--------------\n 1 file changed, 15 insertions(+), 16 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 4ef03120797..42a984306bb 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -44,9 +44,9 @@ COMMANDS\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-\tand write a set of patterns to the sparse-checkout file from the\n-\tlist of arguments following the 'set' subcommand. Update the\n-\tworking directory to match the new patterns.\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@@ -60,15 +60,15 @@ 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-When `--cone` is passed or `core.sparseCheckoutCone` is not false, the\n-input list is considered a list of directories. This allows for\n-better performance with a limited set of patterns (see 'CONE PATTERN\n-SET' below). The input format matches the output of `git ls-tree\n---name-only`. This includes interpreting pathnames that begin with a\n-double quote (\") as C-style quoted strings. Note that the set command\n-will write patterns to the sparse-checkout file to include all files\n-contained in those directories (recursively) as well as files that are\n-siblings of ancestor directories.\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 or `core.sparseCheckoutCone` is false,\n the input list is considered a list of patterns. This mode is harder\n@@ -208,10 +208,9 @@ the following patterns:\n This says \"include everything in root, but nothing two levels below root.\"\n \n When in cone mode, the `git sparse-checkout set` subcommand takes a list of\n-directories instead of a list of sparse-checkout patterns. In this mode,\n-the command `git sparse-checkout set A/B/C` sets the directory `A/B/C` as\n-a recursive pattern, the directories `A` and `A/B` are added as parent\n-patterns. The resulting sparse-checkout file is now\n+directories. In this mode, the command `git sparse-checkout set A/B/C` sets\n+the directory `A/B/C` as a recursive pattern, the directories `A` and `A/B`\n+are added as parent patterns. The resulting sparse-checkout file is now\n \n ----------------\n /*\n-- \ngitgitgadget\n\n"},{"id":"451201","messageId":"eb3b318b39ec3eed754eab7d2c9d20198117545b.1647054681.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.v2.git.1647054681.gitgitgadget@gmail.com","subject":"[PATCH v2 4/9] git-sparse-checkout.txt: update docs for deprecation of 'init'","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-12T03:11:16Z","receivedAt":"2022-03-12T03:11:47Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nThe 'init' subcommand of sparse-checkout was deprecated in ba2f3f58ac\n(\"git-sparse-checkout.txt: update to document init/set/reapply changes\",\n2021-12-14), but a couple places in the manual still assumed it was the\nprimary way to use sparse-checkout. Correct them.\n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-sparse-checkout.txt | 16 ++++++++--------\n 1 file changed, 8 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 42a984306bb..b9e44e3dd4c 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -70,11 +70,11 @@ 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 or `core.sparseCheckoutCone` is false,\n-the input list is considered a list of patterns. This mode is harder\n-to use and less performant, and is thus not recommended. See the\n-\"Sparse Checkout\" section of linkgit:git-read-tree[1] and the \"Pattern\n-Set\" sections below for more details.\n+When `--no-cone` is passed, the input list is considered a list of\n+patterns. This mode is harder to use and less performant, and is thus\n+not recommended. See the \"Sparse Checkout\" section of\n+linkgit:git-read-tree[1] and the \"Pattern Set\" sections below for more\n+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@@ -196,9 +196,9 @@ In addition to the above two patterns, we also expect that all files in the\n root directory are included. If a recursive pattern is added, then all\n leading directories are added as parent patterns.\n \n-By default, when running `git sparse-checkout init`, the root directory is\n-added as a parent pattern. At this point, the sparse-checkout file contains\n-the following patterns:\n+By default, when running `git sparse-checkout set` with no directories\n+specified, the root directory is added as a parent pattern. At this\n+point, the sparse-checkout file contains the following patterns:\n \n ----------------\n /*\n-- \ngitgitgadget\n\n"},{"id":"451202","messageId":"a814ea9e8d29a5eb702570bc3c11379479bd7b4e.1647054681.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.v2.git.1647054681.gitgitgadget@gmail.com","subject":"[PATCH v2 6/9] git-sparse-checkout.txt: add a new EXAMPLES section","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-12T03:11:18Z","receivedAt":"2022-03-12T03:11:50Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nSince many users like to learn from examples, provide a section in the\nmanual with example commands that would be used and a brief explanation\nof what each does.\n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-sparse-checkout.txt | 43 +++++++++++++++++++++++----\n 1 file changed, 37 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 883b7f4c44f..dddf5ac6942 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -136,6 +136,43 @@ 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+EXAMPLES\n+--------\n+`git sparse-checkout set MY/DIR1 SUB/DIR2`::\n+\n+\tChange to a sparse checkout with all files (at any depth) under\n+\tMY/DIR1/ and SUB/DIR2/ present in the working copy (plus all\n+\tfiles immediately under MY/ and SUB/ and the toplevel\n+\tdirectory). If already in a sparse checkout, change which files\n+\tare present in the working copy to this new selection. Note\n+\tthat this command will also delete all ignored files in any\n+\tdirectory that no longer has either tracked or\n+\tnon-ignored-untracked files present.\n+\n+`git sparse-checkout disable`::\n+\n+\tRepopulate the working directory with all files, disabling sparse\n+\tcheckouts.\n+\n+`git sparse-checkout add SOME/DIR/ECTORY`::\n+\n+\tAdd all files under SOME/DIR/ECTORY/ (at any depth) to the\n+\tsparse checkout, as well as all files immediately under\n+\tSOME/DIR/ and immediately under SOME/. Must already be in a\n+\tsparse checkout before using this command.\n+\n+`git sparse-checkout reapply`::\n+\n+\tIt is possible for commands to update the working tree in a\n+\tway that does not respect the selected sparsity directories.\n+\tThis can come from tools external to Git writing files, or\n+\teven affect Git commands because of either special cases (such\n+\tas hitting conflicts when merging/rebasing), or because some\n+\tcommands didn't fully support sparse checkouts (e.g. the old\n+\t`recursive` merge backend had only limited support). This\n+\tcommand reapplies the existing sparse directory specifications\n+\tto make the working directory match.\n+\n INTERNALS -- SPARSE CHECKOUT\n ----------------------------\n \n@@ -154,12 +191,6 @@ directory, it updates the skip-worktree bits in the index based\n on this file. The files matching the patterns in the file will\n appear in the working directory, and the rest will not.\n \n-To enable the sparse-checkout feature, run `git sparse-checkout set` to\n-set the patterns you want to use.\n-\n-To repopulate the working directory with all files, use the\n-`git sparse-checkout disable` command.\n-\n \n INTERNALS -- CONE PATTERN SET\n -----------------------------\n-- \ngitgitgadget\n\n"},{"id":"451203","messageId":"7333198b7785ff4ab6d424b3384c9e4d264e96b2.1647054681.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.v2.git.1647054681.gitgitgadget@gmail.com","subject":"[PATCH v2 5/9] git-sparse-checkout.txt: shuffle some sections and mark as internal","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-12T03:11:17Z","receivedAt":"2022-03-12T03:11:51Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nWith cone mode as the default, it makes sense to discuss it before\nnon-cone mode. Also, the new default means we can just use directories\nin most cases and users do not need to understand patterns or their\nmeanings. Let's take advantage of this to mark several sections as\n\"INTERNALS\", notifying the user that they do not need to know all those\ndetails in order to make use of the sparse-checkout command.\n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-sparse-checkout.txt | 44 +++++++++++++--------------\n 1 file changed, 22 insertions(+), 22 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex b9e44e3dd4c..883b7f4c44f 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -136,8 +136,8 @@ 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-SPARSE CHECKOUT\n----------------\n+INTERNALS -- SPARSE CHECKOUT\n+----------------------------\n \n \"Sparse checkout\" allows populating the working directory sparsely. It\n uses the skip-worktree bit (see linkgit:git-update-index[1]) to tell Git\n@@ -161,24 +161,8 @@ To repopulate the working directory with all files, use the\n `git sparse-checkout disable` command.\n \n \n-FULL PATTERN SET\n-----------------\n-\n-By default, the sparse-checkout file uses the same syntax as `.gitignore`\n-files.\n-\n-While `$GIT_DIR/info/sparse-checkout` is usually used to specify what\n-files are included, you can also specify what files are _not_ included,\n-using negative patterns. For example, to remove the file `unwanted`:\n-\n-----------------\n-/*\n-!unwanted\n-----------------\n-\n-\n-CONE PATTERN SET\n-----------------\n+INTERNALS -- CONE PATTERN SET\n+-----------------------------\n \n The full pattern set allows for arbitrary pattern matches and complicated\n inclusion/exclusion rules. These can result in O(N*M) pattern matches when\n@@ -256,8 +240,24 @@ use `git add` and `git commit` to store them, then remove any remaining files\n manually to ensure Git can behave optimally.\n \n \n-SUBMODULES\n-----------\n+INTERNALS -- FULL PATTERN SET\n+-----------------------------\n+\n+By default, the sparse-checkout file uses the same syntax as `.gitignore`\n+files.\n+\n+While `$GIT_DIR/info/sparse-checkout` is usually used to specify what\n+files are included, you can also specify what files are _not_ included,\n+using negative patterns. For example, to remove the file `unwanted`:\n+\n+----------------\n+/*\n+!unwanted\n+----------------\n+\n+\n+INTERNALS -- SUBMODULES\n+-----------------------\n \n If your repository contains one or more submodules, then submodules\n are populated based on interactions with the `git submodule` command.\n-- \ngitgitgadget\n\n"},{"id":"451204","messageId":"78028ecaa58f2c0b395b417cfa2543e73ab51fae.1647054681.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.v2.git.1647054681.gitgitgadget@gmail.com","subject":"[PATCH v2 7/9] git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a bit","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-12T03:11:19Z","receivedAt":"2022-03-12T03:11:53Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-sparse-checkout.txt | 23 +++++++++++++++++------\n 1 file changed, 17 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex dddf5ac6942..ae6ea8b48b0 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -274,12 +274,23 @@ manually to ensure Git can behave optimally.\n INTERNALS -- FULL PATTERN SET\n -----------------------------\n \n-By default, the sparse-checkout file uses the same syntax as `.gitignore`\n-files.\n-\n-While `$GIT_DIR/info/sparse-checkout` is usually used to specify what\n-files are included, you can also specify what files are _not_ included,\n-using negative patterns. For example, to remove the file `unwanted`:\n+As noted above, the sparse-checkout file uses the same syntax as\n+`.gitignore` files; see linkgit:gitignore[5] for details. Here,\n+though, the patterns are usually being used to select which files to\n+include rather than which files to exclude. (However, it can get a\n+bit confusing since gitignore-style patterns have negations defined by\n+patterns which begin with a '!', so you can also select files to _not_\n+include.)\n+\n+For example, to select everything, and then to remove the file\n+`unwanted` (so that every file will appear in your working tree except\n+the file named `unwanted`):\n+\n+ git sparse-checkout set --no-cone '/*' '!unwanted'\n+\n+These patterns are just placed into the\n+`$GIT_DIR/info/sparse-checkout` as-is, so the contents of that file\n+at this point would be\n \n ----------------\n /*\n-- \ngitgitgadget\n\n"},{"id":"451205","messageId":"2d2b81986a55f0692d5536dec88079c58853f205.1647054681.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.v2.git.1647054681.gitgitgadget@gmail.com","subject":"[PATCH v2 8/9] git-sparse-checkout.txt: mark non-cone mode as deprecated","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-12T03:11:20Z","receivedAt":"2022-03-12T03:11:55Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nWhile we have no current plans to actually remove --no-cone mode, we\nthink users would be better off not using it. Update the documentation\naccordingly, including explaining why we think non-cone mode is\nproblematic for users.\n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-sparse-checkout.txt | 86 +++++++++++++++++++++++++--\n 1 file changed, 82 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex ae6ea8b48b0..aaf3ae63853 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -71,10 +71,13 @@ 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 less performant, and is thus\n-not recommended. See the \"Sparse Checkout\" section of\n-linkgit:git-read-tree[1] and the \"Pattern Set\" sections below for more\n-details.\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@@ -191,6 +194,81 @@ directory, it updates the skip-worktree bits in the index based\n on this file. The files matching the patterns in the file will\n appear in the working directory, and the rest will not.\n \n+INTERNALS -- NON-CONE PROBLEMS\n+------------------------------\n+\n+The `$GIT_DIR/info/sparse-checkout` file populated by the `set` and\n+`add` subcommands is defined to be a bunch of patterns (one per line)\n+using the same syntax as `.gitignore` files. In cone mode, these\n+patterns are restricted to matching directories (and users only ever\n+need supply or see directory names), while in non-cone mode any\n+gitignore-style pattern is permitted. Using the full gitignore-style\n+patterns in non-cone mode has a number of shortcomings:\n+\n+ * Fundamentally, it makes various worktree-updating processes (pull,\n+ merge, rebase, switch, reset, checkout, etc.) require O(N*M) pattern\n+ matches, where N is the number of patterns and M is the number of\n+ paths in the index. This scales poorly.\n+\n+ * Avoiding the scaling issue has to be done via limiting the number\n+ of patterns via specifying leading directory name or glob.\n+\n+ * Passing globs on the command line is error-prone as users may\n+ forget to quote the glob, causing the shell to expand it into all\n+ matching files and pass them all individually along to\n+ sparse-checkout set/add. This both exacerbates the scaling\n+ problem, and hardcodes the list of selected files to those which\n+ were present at the time the initial set/add subcommand was run\n+ (and thus ignoring other files matching the same glob which come\n+ into the working tree after switching branches or pulling down\n+ updates).\n+\n+ * It uses \"ignore\"/\"exclude\" syntax for selecting what to \"include\",\n+ which periodically causes confusion.\n+\n+ * It introduces inconsistencies in the Git command line, since other\n+ commands use pathspecs, but sparse-checkout (in non-cone mode) uses\n+ gitignore patterns.\n+\n+ * It has edge cases where the \"right\" behavior is unclear. Two examples:\n+\n+ First, two users are in a subdirectory, and the first runs\n+ git sparse-checkout set '/toplevel-dir/*.c'\n+ while the second runs\n+ git sparse-checkout set relative-dir\n+ Should those arguments be transliterated into\n+ current/subdirectory/toplevel-dir/*.c\n+ and\n+ current/subdirectory/relative-dir\n+ before inserting into the sparse-checkout file? The user who typed\n+ the first command is probably aware that arguments to set/add are\n+ supposed to be patterns in non-cone mode, and probably would not be\n+ happy with such a transliteration. However, many gitignore-style\n+ patterns are just paths, which might be what the user who typed the\n+ second command was thinking, and they'd be upset if their argument\n+ wasn't transliterated.\n+\n+ Second, what should bash-completion complete on for set/add commands\n+ for non-cone users? If it suggests paths, is it exacerbating the\n+ problem above? Also, if it suggests paths, what if the user has a\n+ file or directory that begins with either a '!' or '#' or has a '*',\n+ '\\', '?', '[', or ']' in its name? And if it suggests paths, will\n+ it complete \"/pro\" to \"/proc\" (in the root filesytem) rather than to\n+ \"/progress.txt\" in the current directory? (Note that users are\n+ likely to want to start paths with a leading '/' in non-cone mode,\n+ for the same reason that .gitignore files often have one.)\n+ Completing on files or directories might give nasty surprises in\n+ all these cases.\n+\n+ * The excessive flexibility made other extensions essentially\n+ impractical. `--sparse-index` may not have been feasible in\n+ non-cone mode, but even if it was, it would have been far more work\n+ to implement and may have been too slow in practice. Some ideas for\n+ adding coupling between partial clones and sparse checkouts are only\n+ practical with a more restricted set of paths.\n+\n+For all these reasons, non-cone mode is deprecated. Please switch to\n+using cone mode.\n \n INTERNALS -- CONE PATTERN SET\n -----------------------------\n-- \ngitgitgadget\n\n"},{"id":"451206","messageId":"4b89a3392b04acccf28f09f90e26715140461373.1647054681.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.v2.git.1647054681.gitgitgadget@gmail.com","subject":"[PATCH v2 9/9] Documentation: some sparsity wording clarifications","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-12T03:11:21Z","receivedAt":"2022-03-12T03:11:56Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nImprove the wording for a couple paragraphs in two different manuals\nrelating to sparse behavior.\n\nReported-by: Ævar Arnfjörð Bjarmason \nSigned-off-by: Elijah Newren \n---\n Documentation/git-read-tree.txt | 9 +++++----\n Documentation/git-sparse-checkout.txt | 10 +++++-----\n 2 files changed, 10 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\nindex 99bb387134d..cbafb1aed49 100644\n--- a/Documentation/git-read-tree.txt\n+++ b/Documentation/git-read-tree.txt\n@@ -375,10 +375,11 @@ have finished your work-in-progress), attempt the merge again.\n SPARSE CHECKOUT\n ---------------\n \n-Note: The `update-index` and `read-tree` primitives for supporting the\n-skip-worktree bit predated the introduction of\n-linkgit:git-sparse-checkout[1]. Users are encouraged to use\n-`sparse-checkout` in preference to these low-level primitives.\n+Note: The skip-worktree capabilities in linkgit:git-update-index[1]\n+and `read-tree` predated the introduction of\n+linkgit:git-sparse-checkout[1]. Users are encouraged to use the\n+`sparse-checkout` command in preference to these plumbing commands for\n+sparse-checkout/skip-worktree related needs.\n \n \"Sparse checkout\" allows populating the working directory sparsely.\n It uses the skip-worktree bit (see linkgit:git-update-index[1]) to\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex aaf3ae63853..e4a29a2baa9 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -15,11 +15,11 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-This command is used to create sparse checkouts, which means that it\n-changes the working tree from having all tracked files present, to only\n-have a subset of them. It can also switch which subset of files are\n-present, or undo and go back to having all tracked files present in the\n-working copy.\n+This command is used to create sparse checkouts, which change the\n+working tree from having all tracked files present to only having a\n+subset of those files. It can also switch which subset of files are\n+present, or undo and go back to having all tracked files present in\n+the working copy.\n \n The subset of files is chosen by providing a list of directories in\n cone mode (the default), or by providing a list of patterns in\n-- \ngitgitgadget\n"},{"id":"451317","messageId":"af00cce6-262b-aebc-422d-4924df26f85a@github.com","threadId":"57519","inReplyTo":"pull.1148.v2.git.1647054681.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 0/9] sparse-checkout: make cone mode the default","fromName":"Derrick Stolee","fromEmail":"derrickstolee@github.com","sentAt":"2022-03-14T15:25:23Z","receivedAt":"2022-03-14T15:25:29Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"On 3/11/2022 10:11 PM, Elijah Newren via GitGitGadget wrote:\n> == Updates Log ==\n> \n> Changes since v1:\n> \n> * rebased on master, to remove dependence on en/present-despite-skipped\n> (which has since merged to master). Earlier version of series wasn't\n> picked up anyway, so rebasing should be safe.\n> * Wording and code style tweaks suggested by Stolee in his review\n\nThanks for these updates. This version looks good to me.\n\nThanks,\n-Stolee\n"},{"id":"451333","messageId":"0f8b57d9-0ce2-da94-ecb8-4fa7f51d9fdb@github.com","threadId":"57519","inReplyTo":"pull.1148.v2.git.1647054681.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 0/9] sparse-checkout: make cone mode the default","fromName":"Victoria Dye","fromEmail":"vdye@github.com","sentAt":"2022-03-14T19:04:52Z","receivedAt":"2022-03-14T19:04:58Z","isPatch":true,"sender":{"key":"vdye@github.com","avatar":"https://avatars.githubusercontent.com/u/3619353?v=4"},"body":"Elijah Newren via GitGitGadget wrote:\n> == Updates Log ==\n> \n> Changes since v1:\n> \n> * rebased on master, to remove dependence on en/present-despite-skipped\n> (which has since merged to master). Earlier version of series wasn't\n> picked up anyway, so rebasing should be safe.\n> * Wording and code style tweaks suggested by Stolee in his review\n> \n> == Overview ==\n> \n> This patch changes the default mode for sparse-checkout from non-cone mode\n> to cone-mode, and marks non-cone mode as deprecated. There is no plan to\n> remove non-cone mode, we are merely recommending against its use.\n> \n> The code change is pretty small, and most of this series is about\n> documentation updates -- to focus on directories rather than patterns, to\n> explain the new default, to explain why we are deprecating non-cone mode\n> (the final patch), and to make other related cleanups to simplify the\n> manual.\n> \n> Patch 1: Update tests to not assume cone-mode is the default Patch 2: Make\n> cone-mode the default Patches 3-9: Various updates to\n> git-sparse-checkout.txt, divided up for ease of review\n> \n\nAfter looking over the patches (and Stolee's prior feedback), I don't have\nany additional comments - it all looks great! \n\nI also ran through some scenarios going from \"non-cone\" to \"cone mode\" that\nhave been buggy in the past (e.g., non-cone directory patterns missing a\nleading '/', then 'git sparse-checkout init --cone'), but it looks like the\nchecks added back in a3eca58445 (sparse-checkout: refuse to add to bad\npatterns, 2021-12-16) prevent any unexplained behavior for a user that might\nnot be aware of the new default. In other words, changing the default looks\nto be safe and overall pushes users towards a better experience using\nsparse-checkout.\n\n> == Alternative ==\n> \n> There is one primary alternative to this series: make sparse-checkout error\n> when neither --cone nor --no-cone are specified (so that there is no\n> default), and wait until a future date to make --cone the default. That'd be\n> reasonable, but I had three reason to avoid going this route (note that item\n> 2 means there's little practical difference between cone-mode-as-default and\n> no-mode-is-default):\n> \n> 1. git-sparse-checkout.txt has the following huge warning early in the\n> manual:\n> \n> \"\"\" THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR, AND THE BEHAVIOR OF OTHER\n> COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN THE\n> FUTURE. \"\"\"\n> \n> 2. If users are unaware of the default change and attempt to provide\n> patterns instead of directories, then they will get error messages added\n> from en/sparse-checkout-fixes. They can learn at that time to get around\n> the error messages by providing --no-cone.\n> \n> 3. If users are unaware of the default change and provide directories, then\n> that's where non-cone mode and cone mode overlap and things happen to\n> work. (There is a slight difference in that cone mode will include files\n> from parent directories of any specified directory, but that means the\n> user gets a few more files in their sparse-checkout with cone mode than\n> they would with non-cone mode.)\n> \n\nAgreed with your comments here and Stolee's earlier that changing the\ndefault is a better approach.\n\n> == CCs ==\n> \n> Elijah Newren (9):\n> tests: stop assuming --no-cone is the default mode for sparse-checkout\n> sparse-checkout: make --cone the default\n> git-sparse-checkout.txt: wording updates for the cone mode default\n> git-sparse-checkout.txt: update docs for deprecation of 'init'\n> git-sparse-checkout.txt: shuffle some sections and mark as internal\n> git-sparse-checkout.txt: add a new EXAMPLES section\n> git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a\n> bit\n> git-sparse-checkout.txt: mark non-cone mode as deprecated\n> Documentation: some sparsity wording clarifications\n> \n> Documentation/git-read-tree.txt | 9 +-\n> Documentation/git-sparse-checkout.txt | 249 +++++++++++++++++++-------\n> builtin/sparse-checkout.c | 2 +-\n> t/t1091-sparse-checkout-builtin.sh | 15 +-\n> t/t3602-rm-sparse-checkout.sh | 6 +-\n> t/t3705-add-sparse-checkout.sh | 4 +-\n> t/t6428-merge-conflicts-sparse.sh | 4 +-\n> t/t7002-mv-sparse-checkout.sh | 2 +-\n> t/t7012-skip-worktree-writing.sh | 2 +-\n> 9 files changed, 207 insertions(+), 86 deletions(-)\n> \n> \n> base-commit: 1a4874565fa3b6668042216189551b98b4dc0b1b\n> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1148%2Fnewren%2Fsparse-checkout-default-v2\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1148/newren/sparse-checkout-default-v2\n> Pull-Request: https://github.com/gitgitgadget/git/pull/1148\n> \n> Range-diff vs v1:\n> \n> 1: 8c3e730e86b = 1: 05dba7069c5 tests: stop assuming --no-cone is the default mode for sparse-checkout\n> 2: b174b42ed82 ! 2: a53179764bc sparse-checkout: make --cone the default\n> @@ builtin/sparse-checkout.c: static int update_modes(int *cone_mode, int *sparse_i\n> \t/* Set cone/non-cone mode appropriately */\n> \tcore_apply_sparse_checkout = 1;\n> -\tif (*cone_mode == 1) {\n> -+\tif (*cone_mode == 1 || *cone_mode == -1) {\n> ++\tif (*cone_mode) { /* also handles \"not specified\" (value of -1) */\n> \t\tmode = MODE_CONE_PATTERNS;\n> \t\tcore_sparse_checkout_cone = 1;\n> \t} else {\n> 3: f98b3fac78a = 3: 8eab21996c7 git-sparse-checkout.txt: wording updates for the cone mode default\n> 4: cd871966c06 = 4: eb3b318b39e git-sparse-checkout.txt: update docs for deprecation of 'init'\n> 5: fe37a966699 = 5: 7333198b778 git-sparse-checkout.txt: shuffle some sections and mark as internal\n> 6: 3265f41bcab ! 6: a814ea9e8d2 git-sparse-checkout.txt: add a new EXAMPLES section\n> @@ Documentation/git-sparse-checkout.txt: paths to pass to a subsequent 'set' or 'a\n> +\n> +`git sparse-checkout reapply`::\n> +\n> -+\tIt is possible for commands to update the working tree in a way\n> -+\tthat does not respect the selected sparsity directories, either\n> -+\tbecause of special cases (such as hitting conflicts when\n> -+\tmerging/rebasing), or because some commands didn't fully support\n> -+\tsparse checkouts (e.g. the old `recursive` merge backend had\n> -+\tonly limited support). This command reapplies the existing\n> -+\tsparse directory specifications to make the working directory\n> -+\tmatch.\n> ++\tIt is possible for commands to update the working tree in a\n> ++\tway that does not respect the selected sparsity directories.\n> ++\tThis can come from tools external to Git writing files, or\n> ++\teven affect Git commands because of either special cases (such\n> ++\tas hitting conflicts when merging/rebasing), or because some\n> ++\tcommands didn't fully support sparse checkouts (e.g. the old\n> ++\t`recursive` merge backend had only limited support). This\n> ++\tcommand reapplies the existing sparse directory specifications\n> ++\tto make the working directory match.\n> +\n> INTERNALS -- SPARSE CHECKOUT\n> ----------------------------\n> 7: bdbf61ee6a0 = 7: 78028ecaa58 git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a bit\n> 8: 3e35d62c5ee = 8: 2d2b81986a5 git-sparse-checkout.txt: mark non-cone mode as deprecated\n> 9: e7d3ff70914 = 9: 4b89a3392b0 Documentation: some sparsity wording clarifications\n> \n\n"},{"id":"451338","messageId":"xmqqlexcqon9.fsf@gitster.g","threadId":"57519","inReplyTo":"pull.1148.v2.git.1647054681.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 0/9] sparse-checkout: make cone mode the default","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-03-14T20:12:42Z","receivedAt":"2022-03-14T20:12:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Elijah Newren via GitGitGadget\" writes:\n\n> == Updates Log ==\n>\n> Changes since v1:\n>\n> * rebased on master, to remove dependence on en/present-despite-skipped\n> (which has since merged to master). Earlier version of series wasn't\n> picked up anyway, so rebasing should be safe.\n> * Wording and code style tweaks suggested by Stolee in his review\n>\n> == Overview ==\n>\n> This patch changes the default mode for sparse-checkout from non-cone mode\n> to cone-mode, and marks non-cone mode as deprecated. There is no plan to\n> remove non-cone mode, we are merely recommending against its use.\n\nHopefully there are some convincing explanation to help users\nunderstand why the cone mode is recommended in the documentation in\nthese patches. Was there a discussion on list to give our unanimous\nsupport for this plan, or is this only preference by a developer or\ntwo who have worked on the sparse-checkout code recently?\n\n"},{"id":"451339","messageId":"xmqqfsnkqodp.fsf@gitster.g","threadId":"57519","inReplyTo":"05dba7069c5e0c1aec1a7206f9cbea593d8d68cb.1647054681.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 1/9] tests: stop assuming --no-cone is the default mode for sparse-checkout","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-03-14T20:18:26Z","receivedAt":"2022-03-14T20:18:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Elijah Newren via GitGitGadget\" writes:\n\n> From: Elijah Newren \n>\n> Add an explicit --no-cone to several sparse-checkout invocations in\n> preparation for changing the default to cone mode.\n\n\"several\"?\n\nAfter this step, wouldn't it be a bug if in t/ there still are\n\"sparse-checkout init\" or \"sparse-checkout set\" invocations for a\ngiven test repository for the first time that do not mention\n\"--cone\" or \"--no-cone\"?\n\nI am mostly asking for the criteria for reviewers to decide if they\nspotted a bug or if it is expected omission when they spot, say,\n\"sparse-checkout init\" without either.\n\n> Signed-off-by: Elijah Newren \n> ---\n> t/t1091-sparse-checkout-builtin.sh | 15 ++++++++-------\n> t/t3602-rm-sparse-checkout.sh | 6 +++---\n> t/t3705-add-sparse-checkout.sh | 4 ++--\n> t/t6428-merge-conflicts-sparse.sh | 4 ++--\n> t/t7002-mv-sparse-checkout.sh | 2 +-\n> t/t7012-skip-worktree-writing.sh | 2 +-\n> 6 files changed, 17 insertions(+), 16 deletions(-)\n>\n> diff --git a/t/t1091-sparse-checkout-builtin.sh b/t/t1091-sparse-checkout-builtin.sh\n> index 9a900310186..de1ec89007d 100755\n> --- a/t/t1091-sparse-checkout-builtin.sh\n> +++ b/t/t1091-sparse-checkout-builtin.sh\n> @@ -72,7 +72,7 @@ test_expect_success 'git sparse-checkout list (populated)' '\n> '\n> \n> test_expect_success 'git sparse-checkout init' '\n> -\tgit -C repo sparse-checkout init &&\n> +\tgit -C repo sparse-checkout init --no-cone &&\n> \tcat >expect <<-\\EOF &&\n> \t/*\n> \t!/*/\n> @@ -111,6 +111,7 @@ test_expect_success 'init with existing sparse-checkout' '\n> \n> test_expect_success 'clone --sparse' '\n> \tgit clone --sparse \"file://$(pwd)/repo\" clone &&\n> +\tgit -C clone sparse-checkout reapply --no-cone &&\n> \tgit -C clone sparse-checkout list >actual &&\n> \tcat >expect <<-\\EOF &&\n> \t/*\n> @@ -124,7 +125,7 @@ test_expect_success 'switching to cone mode with non-cone mode patterns' '\n> \tgit init bad-patterns &&\n> \t(\n> \t\tcd bad-patterns &&\n> -\t\tgit sparse-checkout init &&\n> +\t\tgit sparse-checkout init --no-cone &&\n> \t\tgit sparse-checkout add dir &&\n> \t\tgit config --worktree core.sparseCheckoutCone true &&\n> \t\ttest_must_fail git sparse-checkout add dir 2>err &&\n> @@ -402,7 +403,7 @@ test_expect_success 'revert to old sparse-checkout on empty update' '\n> \t\tgit sparse-checkout set nothing 2>err &&\n> \t\ttest_i18ngrep ! \"Sparse checkout leaves no entry on working directory\" err &&\n> \t\ttest_i18ngrep ! \".git/index.lock\" err &&\n> -\t\tgit sparse-checkout set file\n> +\t\tgit sparse-checkout set --no-cone file\n> \t)\n> '\n> \n> @@ -424,7 +425,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with dirty status'\n> \tgit clone repo dirty &&\n> \techo dirty >dirty/folder1/a &&\n> \n> -\tgit -C dirty sparse-checkout init 2>err &&\n> +\tgit -C dirty sparse-checkout init --no-cone 2>err &&\n> \ttest_i18ngrep \"warning.*The following paths are not up to date\" err &&\n> \n> \tgit -C dirty sparse-checkout set /folder2/* /deep/deeper1/* 2>err &&\n> @@ -435,7 +436,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with dirty status'\n> \ttest_must_be_empty err &&\n> \n> \tgit -C dirty reset --hard &&\n> -\tgit -C dirty sparse-checkout init &&\n> +\tgit -C dirty sparse-checkout init --no-cone &&\n> \tgit -C dirty sparse-checkout set /folder2/* /deep/deeper1/* &&\n> \ttest_path_is_missing dirty/folder1/a &&\n> \tgit -C dirty sparse-checkout disable &&\n> @@ -451,7 +452,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with unmerged stat\n> \tEOF\n> \tgit -C unmerged update-index --index-info \n> -\tgit -C unmerged sparse-checkout init 2>err &&\n> +\tgit -C unmerged sparse-checkout init --no-cone 2>err &&\n> \ttest_i18ngrep \"warning.*The following paths are unmerged\" err &&\n> \n> \tgit -C unmerged sparse-checkout set /folder2/* /deep/deeper1/* 2>err &&\n> @@ -462,7 +463,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with unmerged stat\n> \ttest_i18ngrep \"warning.*The following paths are unmerged\" err &&\n> \n> \tgit -C unmerged reset --hard &&\n> -\tgit -C unmerged sparse-checkout init &&\n> +\tgit -C unmerged sparse-checkout init --no-cone &&\n> \tgit -C unmerged sparse-checkout set /folder2/* /deep/deeper1/* &&\n> \tgit -C unmerged sparse-checkout disable\n> '\n> diff --git a/t/t3602-rm-sparse-checkout.sh b/t/t3602-rm-sparse-checkout.sh\n> index 034ec010910..08580fd3dcc 100755\n> --- a/t/t3602-rm-sparse-checkout.sh\n> +++ b/t/t3602-rm-sparse-checkout.sh\n> @@ -30,7 +30,7 @@ test_expect_success 'setup' \"\n> for opt in \"\" -f --dry-run\n> do\n> \ttest_expect_success \"rm${opt:+ $opt} does not remove sparse entries\" '\n> -\t\tgit sparse-checkout set a &&\n> +\t\tgit sparse-checkout set --no-cone a &&\n> \t\ttest_must_fail git rm $opt b 2>stderr &&\n> \t\ttest_cmp b_error_and_hint stderr &&\n> \t\tgit ls-files --error-unmatch b\n> @@ -118,7 +118,7 @@ test_expect_success 'can remove files from non-sparse dir' '\n> \ttest_commit w/f &&\n> \ttest_commit x/y/f &&\n> \n> -\tgit sparse-checkout set w !/x y/ &&\n> +\tgit sparse-checkout set --no-cone w !/x y/ &&\n> \tgit rm w/f.t x/y/f.t 2>stderr &&\n> \ttest_must_be_empty stderr\n> '\n> @@ -128,7 +128,7 @@ test_expect_success 'refuse to remove non-skip-worktree file from sparse dir' '\n> \tgit sparse-checkout disable &&\n> \tmkdir -p x/y/z &&\n> \ttest_commit x/y/z/f &&\n> -\tgit sparse-checkout set !/x y/ !x/y/z &&\n> +\tgit sparse-checkout set --no-cone !/x y/ !x/y/z &&\n> \n> \tgit update-index --no-skip-worktree x/y/z/f.t &&\n> \ttest_must_fail git rm x/y/z/f.t 2>stderr &&\n> diff --git a/t/t3705-add-sparse-checkout.sh b/t/t3705-add-sparse-checkout.sh\n> index 95609046c61..2bade9e804f 100755\n> --- a/t/t3705-add-sparse-checkout.sh\n> +++ b/t/t3705-add-sparse-checkout.sh\n> @@ -166,7 +166,7 @@ test_expect_success 'do not warn when pathspec matches dense entries' '\n> test_expect_success 'git add fails outside of sparse-checkout definition' '\n> \ttest_when_finished git sparse-checkout disable &&\n> \ttest_commit a &&\n> -\tgit sparse-checkout init &&\n> +\tgit sparse-checkout init --no-cone &&\n> \tgit sparse-checkout set a &&\n> \techo >>sparse_entry &&\n> \n> @@ -208,7 +208,7 @@ test_expect_success 'add obeys advice.updateSparsePath' '\n> '\n> \n> test_expect_success 'add allows sparse entries with --sparse' '\n> -\tgit sparse-checkout set a &&\n> +\tgit sparse-checkout set --no-cone a &&\n> \techo modified >sparse_entry &&\n> \ttest_must_fail git add sparse_entry &&\n> \ttest_sparse_entry_unchanged &&\n> diff --git a/t/t6428-merge-conflicts-sparse.sh b/t/t6428-merge-conflicts-sparse.sh\n> index 142c9aaabc5..064be1b629e 100755\n> --- a/t/t6428-merge-conflicts-sparse.sh\n> +++ b/t/t6428-merge-conflicts-sparse.sh\n> @@ -87,7 +87,7 @@ test_expect_success 'conflicting entries written to worktree even if sparse' '\n> \t\ttest_path_is_file numerals &&\n> \n> \t\tgit sparse-checkout init &&\n> -\t\tgit sparse-checkout set README &&\n> +\t\tgit sparse-checkout set --no-cone README &&\n> \n> \t\ttest_path_is_file README &&\n> \t\ttest_path_is_missing numerals &&\n> @@ -123,7 +123,7 @@ test_expect_success 'present-despite-SKIP_WORKTREE handled reasonably' '\n> \t\ttest_path_is_file numerals &&\n> \n> \t\tgit sparse-checkout init &&\n> -\t\tgit sparse-checkout set README &&\n> +\t\tgit sparse-checkout set --no-cone README &&\n> \n> \t\ttest_path_is_file README &&\n> \t\ttest_path_is_missing numerals &&\n> diff --git a/t/t7002-mv-sparse-checkout.sh b/t/t7002-mv-sparse-checkout.sh\n> index 1d3d2aca21c..f0f7cbfcdb7 100755\n> --- a/t/t7002-mv-sparse-checkout.sh\n> +++ b/t/t7002-mv-sparse-checkout.sh\n> @@ -27,7 +27,7 @@ test_expect_success 'setup' \"\n> test_expect_success 'mv refuses to move sparse-to-sparse' '\n> \ttest_when_finished rm -f e &&\n> \tgit reset --hard &&\n> -\tgit sparse-checkout set a &&\n> +\tgit sparse-checkout set --no-cone a &&\n> \ttouch b &&\n> \ttest_must_fail git mv b e 2>stderr &&\n> \tcat sparse_error_header >expect &&\n> diff --git a/t/t7012-skip-worktree-writing.sh b/t/t7012-skip-worktree-writing.sh\n> index cb9f1a6981e..cd5c20fe51b 100755\n> --- a/t/t7012-skip-worktree-writing.sh\n> +++ b/t/t7012-skip-worktree-writing.sh\n> @@ -151,7 +151,7 @@ test_expect_success 'stash restore in sparse checkout' '\n> \n> \t\tgit stash push &&\n> \n> -\t\tgit sparse-checkout set subdir &&\n> +\t\tgit sparse-checkout set --no-cone subdir &&\n> \n> \t\t# Ensure after sparse-checkout we only have expected files\n> \t\tcat >expect <<-EOF &&\n"},{"id":"451340","messageId":"xmqq8rtcqnnn.fsf@gitster.g","threadId":"57519","inReplyTo":"a53179764bc5d411726a095a587ea728aa9a20d3.1647054681.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 2/9] sparse-checkout: make --cone the default","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-03-14T20:34:04Z","receivedAt":"2022-03-14T20:34:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Elijah Newren via GitGitGadget\" writes:\n\n> The subset of files is chosen by providing a list of directories in\n> -cone mode (which is recommended), or by providing a list of patterns\n> -in non-cone mode.\n> +cone mode (the default), or by providing a list of patterns in\n> +non-cone mode.\n\nOK.\n\n> @@ -60,7 +60,7 @@ 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> -When `--cone` is passed or `core.sparseCheckoutCone` is enabled, the\n> +When `--cone` is passed or `core.sparseCheckoutCone` is not false, the\n> input list is considered a list of directories. This allows for\n\n\nI expected a change to Documentation/config/core.txt in this step,\nbecause the default value for core.sparseCheckoutCone becomes true\nif unspecified with this step, and the normal expectation by the\nreaders is what is not explicitly set to true is either 'false' or\n'unspecified' (when 'unspecified' has its own meaning, like in\ngitattributes).\n\nSomething like this?\n\ndiff --git i/Documentation/config/core.txt w/Documentation/config/core.txt\nindex c04f62a54a..03cf075821 100644\n--- i/Documentation/config/core.txt\n+++ w/Documentation/config/core.txt\n@@ -615,8 +615,10 @@ core.sparseCheckout::\n \n core.sparseCheckoutCone::\n \tEnables the \"cone mode\" of the sparse checkout feature. When the\n-\tsparse-checkout file contains a limited set of patterns, then this\n-\tmode provides significant performance advantages. See\n+\tsparse-checkout file contains a limited set of patterns, this\n+\tmode provides significant performance advantages. The \"non\n+\tcone mode\" can be requested to allow specifying a more flexible\n+\tpatterns by setting this variable to 'false'. See\n \tlinkgit:git-sparse-checkout[1] for more information.\n \n core.abbrev::\n\n> -When `--no-cone` is passed or `core.sparseCheckoutCone` is not enabled,\n> +When `--no-cone` is passed or `core.sparseCheckoutCone` is false,\n\n\"is set to 'false'\" would make it clearer.\n\n> +If `core.sparseCheckoutCone=true` (set by default or with an explicit\n> +`--cone`), then Git will parse the sparse-checkout file expecting\n\n\"Unless `core.sparseCheckoutCone` is explicitly set to `false`\"\nmight be clearer, but I am not sure. It is just that I found the\nphrase \"set by default\" confusing.\n\n> \t/* Set cone/non-cone mode appropriately */\n> \tcore_apply_sparse_checkout = 1;\n> -\tif (*cone_mode == 1) {\n> +\tif (*cone_mode) { /* also handles \"not specified\" (value of -1) */\n\nThe comment is correct, but if we can make the code not to require\nsuch a comment, that would be even better. Are there very small\nnumber of choke points where we always pass, after parsing\nconfiguration variables and options, that we ought to know which\nmode to use before the control comes here, and commit the choice\nwith \"if (cone_mode < 0) cone_mode = 1\"?\n\nWe see beyond precontext of this hunk an assignment to *cone_mode to\ntell the choice we made to our caller. Shouldn't we be doing the\nsame in this if/else that still assumes we can get \"undecided\"?\n\n> \t\tmode = MODE_CONE_PATTERNS;\n> \t\tcore_sparse_checkout_cone = 1;\n> \t} else {\n"},{"id":"451341","messageId":"xmqq4k40qneu.fsf@gitster.g","threadId":"57519","inReplyTo":"8eab21996c7984a31cb954dd787ee54ce77dfa69.1647054681.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 3/9] git-sparse-checkout.txt: wording updates for the cone mode default","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-03-14T20:39:21Z","receivedAt":"2022-03-14T20:39:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Elijah Newren via GitGitGadget\" writes:\n\n> From: Elijah Newren \n>\n> Now that cone mode is the default, we'd like to focus on the arguments\n> to set/add being directories rather than patterns, and it probably makes\n> sense to provide an earlier heads up that files from leading directories\n> get included as well.\n\nLooking good.\n"},{"id":"451342","messageId":"xmqqwngwp87k.fsf@gitster.g","threadId":"57519","inReplyTo":"eb3b318b39ec3eed754eab7d2c9d20198117545b.1647054681.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 4/9] git-sparse-checkout.txt: update docs for deprecation of 'init'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-03-14T20:53:03Z","receivedAt":"2022-03-14T20:53:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Elijah Newren via GitGitGadget\" writes:\n\n> -When `--no-cone` is passed or `core.sparseCheckoutCone` is false,\n> -the input list is considered a list of patterns. This mode is harder\n> -to use and less performant, and is thus not recommended. See the\n> -\"Sparse Checkout\" section of linkgit:git-read-tree[1] and the \"Pattern\n> -Set\" sections below for more details.\n> +When `--no-cone` is passed, the input list is considered a list of\n> +patterns. This mode is harder to use and less performant, and is thus\n\n\"less perfromant\" can be quantified, but \"harder to use\" is probably\nharder to defend. Those on a project with need for more flexible\nway to specify than \"these are the directories I care about\" would\nnot find it convincing.\n\n> +not recommended. See the \"Sparse Checkout\" section of\n> +linkgit:git-read-tree[1]\n\nThe referenced section (I am reading \"git read-tree --help\" from\nseen with these patches) may need updating. It shows an example\nof including everything except for unwanted, without mentioning\nif that is for cone or non-cone.\n\n> and the \"Pattern Set\" sections below for more\n> +details.\n\nAre we referring to \"Internals - cone/full pattern set\" sections?\n\nThis may be a topic of another step in this series, but the \"core\"\nsection starts by mentioning what characteristics the full pattern\nset has and uses it to steer readers away from it, which I find it\nless than ideal. As we present \"core\" first (because it is the\ndefault), we should present \"core\" by itself, without requiring to\nknow what the other thing is. Perhaps replace the entire first\nparagraph so that the section begins more like so:\n\n\tThe \"cone mode\", which is the default, lets you specify only\n\twhat directories to include and what directories to exclude.\n\n\tThe accepted patterns in the cone pattern set are:...\n\nEspecially, the last sentence in the paragraph to be struck still\nlives in the old world in which you needed to opt into the cone\nmode.\n\nThanks.\n"},{"id":"451343","messageId":"xmqqsfrkp83y.fsf@gitster.g","threadId":"57519","inReplyTo":"7333198b7785ff4ab6d424b3384c9e4d264e96b2.1647054681.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 5/9] git-sparse-checkout.txt: shuffle some sections and mark as internal","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-03-14T20:55:13Z","receivedAt":"2022-03-14T20:55:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Elijah Newren via GitGitGadget\" writes:\n\n> -CONE PATTERN SET\n> -----------------\n> +INTERNALS -- CONE PATTERN SET\n> +-----------------------------\n\nAh, this is why I was confused during my review of an earlier step,\nwhere it refered to this (and the other) sections as \"sections on\n'pattern set'\", because I was reading the end-result of applying the\nwhole series.\n\nWith this change, shouldn't the reference be updated?\n\n"},{"id":"451344","messageId":"xmqqo828p7zt.fsf@gitster.g","threadId":"57519","inReplyTo":"78028ecaa58f2c0b395b417cfa2543e73ab51fae.1647054681.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 7/9] git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a bit","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-03-14T20:57:42Z","receivedAt":"2022-03-14T20:57:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Elijah Newren via GitGitGadget\" writes:\n\n> INTERNALS -- FULL PATTERN SET\n> -----------------------------\n> \n> -By default, the sparse-checkout file uses the same syntax as `.gitignore`\n> -files.\n> -\n> -While `$GIT_DIR/info/sparse-checkout` is usually used to specify what\n> -files are included, you can also specify what files are _not_ included,\n> -using negative patterns. For example, to remove the file `unwanted`:\n> +As noted above, the sparse-checkout file uses the same syntax as\n> +`.gitignore` files; see linkgit:gitignore[5] for details. Here,\n\nHere, following the suggestion to fix the early part of \"Cone mode\npatterns\" section, move the \"it is more flexible but requires more\ncycles to process\" you had there to replace the \"As noted above\".\n"},{"id":"451345","messageId":"xmqqa6dsp78q.fsf@gitster.g","threadId":"57519","inReplyTo":"2d2b81986a55f0692d5536dec88079c58853f205.1647054681.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 8/9] git-sparse-checkout.txt: mark non-cone mode as deprecated","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-03-14T21:13:57Z","receivedAt":"2022-03-14T21:14:05Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Elijah Newren via GitGitGadget\" writes:\n\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.\n\nIf we explicitly say we have no intention to remove, while saying\nthat \"non-cone\" mode is a second class citizen, the users would be\nconfused. Does this mixed attitude only apply to non-cone mode, or\nis it true for any other fringe features that we do not care about\nin Git?\n\nThis does not build confidence with the Git software suite. If we\nare removing, then this attitude is OK, but if we are keeping it,\nthen we should promise that we never add features only to \"cone\".\n\n> +INTERNALS -- NON-CONE PROBLEMS\n> +------------------------------\n> +\n> +The `$GIT_DIR/info/sparse-checkout` file populated by the `set` and\n> +`add` subcommands is defined to be a bunch of patterns (one per line)\n> +using the same syntax as `.gitignore` files. In cone mode, these\n> +patterns are restricted to matching directories (and users only ever\n> +need supply or see directory names), while in non-cone mode any\n> +gitignore-style pattern is permitted. Using the full gitignore-style\n> +patterns in non-cone mode has a number of shortcomings:\n> +\n> + * Fundamentally, it makes various worktree-updating processes (pull,\n> + merge, rebase, switch, reset, checkout, etc.) require O(N*M) pattern\n> + matches, where N is the number of patterns and M is the number of\n> + paths in the index. This scales poorly.\n> +\n> + * Avoiding the scaling issue has to be done via limiting the number\n> + of patterns via specifying leading directory name or glob.\n\nThese are valid.\n\n> + * Passing globs on the command line is error-prone as users may\n> + forget to quote the glob, causing the shell to expand it into all\n> + matching files and pass them all individually along to\n> + sparse-checkout set/add. This both exacerbates the scaling\n> + problem, and hardcodes the list of selected files to those which\n> + were present at the time the initial set/add subcommand was run\n> + (and thus ignoring other files matching the same glob which come\n> + into the working tree after switching branches or pulling down\n> + updates).\n\nThat's end-user mistakes that is common to other things like\npathspecs, i.e. \"git grep -- \\*.c\" vs \"git grep -- *.c\". It hardly\ndeserves to spend more than 5 lines shouting.\n\n> + * It uses \"ignore\"/\"exclude\" syntax for selecting what to \"include\",\n> + which periodically causes confusion.\n\nWell, .gitignore uses the syntax to select the paths to include or\nexclude from a set, and then the set specifies what is left out of\nthe index. I am not sure if that is the source of confusion.\n\n> + * It introduces inconsistencies in the Git command line, since other\n> + commands use pathspecs, but sparse-checkout (in non-cone mode) uses\n> + gitignore patterns.\n\nBut \"cone\" mode does not take pathspec, does it? \":(icase)/A/B/C\"\nfor example? I do not see this as a credible argument against it.\n\n> + * It has edge cases where the \"right\" behavior is unclear. Two examples:\n> +\n> + First, two users are in a subdirectory, and the first runs\n> + git sparse-checkout set '/toplevel-dir/*.c'\n> + while the second runs\n> + git sparse-checkout set relative-dir\n\nAre we aware which mode of sparse-checkout they are in? Do we give\na mechanism for users to ask \"we have 'non-cone' sparse checkout in\nthe sparse-checkout file. we want to use the more efficient and\nrecommended 'cone' mode. Please convert it\", or even if there is\nnot an automated conversion mechansim, can the user manually do so\n(which I suspect is not fundamentally possible---the cone mode is\ninherently less expressive)?\n\nIf not, then we should expect these two users to _know_ (or at least\ncheck before they run \"set\" subcommand) which mode is in use.\n\nSo, with that expectation,\n\n> + Should those arguments be transliterated into\n> + current/subdirectory/toplevel-dir/*.c\n> + and\n> + current/subdirectory/relative-dir\n\nIf we are using non-cone mode, then both would be recorded as-is.\n\nIf we are using cone mode, we may reject the one that ends with \"*.c\"\nbased on the two traits it has, i.e. (1) there is no such directory\nin the working tree nor the index nor the HEAD, and (2) it has an\nunusual character (i.e. glob) '*' to be in a real path.\n"},{"id":"451358","messageId":"xmqqh780jf5h.fsf@gitster.g","threadId":"57519","inReplyTo":"xmqqlexcqon9.fsf@gitster.g","subject":"Re: [PATCH v2 0/9] sparse-checkout: make cone mode the default","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-03-14T23:19:38Z","receivedAt":"2022-03-14T23:19:43Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> \"Elijah Newren via GitGitGadget\" writes:\n>\n>> == Updates Log ==\n>>\n>> Changes since v1:\n>>\n>> * rebased on master, to remove dependence on en/present-despite-skipped\n>> (which has since merged to master). Earlier version of series wasn't\n>> picked up anyway, so rebasing should be safe.\n>> * Wording and code style tweaks suggested by Stolee in his review\n>>\n>> == Overview ==\n>>\n>> This patch changes the default mode for sparse-checkout from non-cone mode\n>> to cone-mode, and marks non-cone mode as deprecated. There is no plan to\n>> remove non-cone mode, we are merely recommending against its use.\n>\n> Hopefully there are some convincing explanation to help users\n> understand why the cone mode is recommended in the documentation in\n> these patches. Was there a discussion on list to give our unanimous\n> support for this plan, or is this only preference by a developer or\n> two who have worked on the sparse-checkout code recently?\n\nOK. There are a few things that I found questionable, but they were\nmostly documentation issues (and lack of updates to two places, one\nin read-tree and the other in config/core.txt).\n\nThanks.\n"},{"id":"451402","messageId":"d6631b7e-3237-5f7b-a97c-1b152ffd242d@github.com","threadId":"57519","inReplyTo":"xmqqfsnkqodp.fsf@gitster.g","subject":"Re: [PATCH v2 1/9] tests: stop assuming --no-cone is the default mode for sparse-checkout","fromName":"Derrick Stolee","fromEmail":"derrickstolee@github.com","sentAt":"2022-03-15T17:15:55Z","receivedAt":"2022-03-15T17:16:00Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"On 3/14/2022 4:18 PM, Junio C Hamano wrote:\n> \"Elijah Newren via GitGitGadget\" writes:\n> \n>> From: Elijah Newren \n>>\n>> Add an explicit --no-cone to several sparse-checkout invocations in\n>> preparation for changing the default to cone mode.\n> \n> \"several\"?\n> \n> After this step, wouldn't it be a bug if in t/ there still are\n> \"sparse-checkout init\" or \"sparse-checkout set\" invocations for a\n> given test repository for the first time that do not mention\n> \"--cone\" or \"--no-cone\"?\n> \n> I am mostly asking for the criteria for reviewers to decide if they\n> spotted a bug or if it is expected omission when they spot, say,\n> \"sparse-checkout init\" without either.\n\nThere are some \"git sparse-checkout init\" runs without the\n--no-cone, but since they are followed by a \"set --no-cone\",\nthe difference is not important. Perhaps, as a later cleanup,\nwe could go in and delete those \"init\" calls.\n\nThanks,\n-Stolee\n"},{"id":"454206","messageId":"CABPp-BGmmg7YxaZwerivWGAQ6J5cpc9pRrJkHwMUXArvRXZ+rg@mail.gmail.com","threadId":"57519","inReplyTo":"xmqq8rtcqnnn.fsf@gitster.g","subject":"Re: [PATCH v2 2/9] sparse-checkout: make --cone the default","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2022-04-22T02:29:42Z","receivedAt":"2022-04-22T02:30:02Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"Sorry for the long delay...\n\nOn Mon, Mar 14, 2022 at 1:34 PM Junio C Hamano wrote:\n>\n> \"Elijah Newren via GitGitGadget\" writes:\n>\n> > The subset of files is chosen by providing a list of directories in\n> > -cone mode (which is recommended), or by providing a list of patterns\n> > -in non-cone mode.\n> > +cone mode (the default), or by providing a list of patterns in\n> > +non-cone mode.\n>\n> OK.\n>\n> > @@ -60,7 +60,7 @@ 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> > -When `--cone` is passed or `core.sparseCheckoutCone` is enabled, the\n> > +When `--cone` is passed or `core.sparseCheckoutCone` is not false, the\n> > input list is considered a list of directories. This allows for\n>\n>\n> I expected a change to Documentation/config/core.txt in this step,\n> because the default value for core.sparseCheckoutCone becomes true\n> if unspecified with this step, and the normal expectation by the\n> readers is what is not explicitly set to true is either 'false' or\n> 'unspecified' (when 'unspecified' has its own meaning, like in\n> gitattributes).\n>\n> Something like this?\n>\n> diff --git i/Documentation/config/core.txt w/Documentation/config/core.txt\n> index c04f62a54a..03cf075821 100644\n> --- i/Documentation/config/core.txt\n> +++ w/Documentation/config/core.txt\n> @@ -615,8 +615,10 @@ core.sparseCheckout::\n>\n> core.sparseCheckoutCone::\n> Enables the \"cone mode\" of the sparse checkout feature. When the\n> - sparse-checkout file contains a limited set of patterns, then this\n> - mode provides significant performance advantages. See\n> + sparse-checkout file contains a limited set of patterns, this\n> + mode provides significant performance advantages. The \"non\n> + cone mode\" can be requested to allow specifying a more flexible\n> + patterns by setting this variable to 'false'. See\n> linkgit:git-sparse-checkout[1] for more information.\n>\n> core.abbrev::\n>\n> > -When `--no-cone` is passed or `core.sparseCheckoutCone` is not enabled,\n> > +When `--no-cone` is passed or `core.sparseCheckoutCone` is false,\n>\n> \"is set to 'false'\" would make it clearer.\n>\n> > +If `core.sparseCheckoutCone=true` (set by default or with an explicit\n> > +`--cone`), then Git will parse the sparse-checkout file expecting\n>\n> \"Unless `core.sparseCheckoutCone` is explicitly set to `false`\"\n> might be clearer, but I am not sure. It is just that I found the\n> phrase \"set by default\" confusing.\n\nThanks; I applied all three suggestions.\n\n> > /* Set cone/non-cone mode appropriately */\n> > core_apply_sparse_checkout = 1;\n> > - if (*cone_mode == 1) {\n> > + if (*cone_mode) { /* also handles \"not specified\" (value of -1) */\n>\n> The comment is correct, but if we can make the code not to require\n> such a comment, that would be even better.\n\nI had that in v1; I'll revert back to it.\n"},{"id":"454207","messageId":"CABPp-BEt0CzP7B_EvYXOhQoKqk+h=9OwXDmUDCYfB3fnHxv-uA@mail.gmail.com","threadId":"57519","inReplyTo":"xmqqwngwp87k.fsf@gitster.g","subject":"Re: [PATCH v2 4/9] git-sparse-checkout.txt: update docs for deprecation of 'init'","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2022-04-22T02:29:57Z","receivedAt":"2022-04-22T02:30:14Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"On Mon, Mar 14, 2022 at 1:53 PM Junio C Hamano wrote:\n>\n> \"Elijah Newren via GitGitGadget\" writes:\n>\n> > -When `--no-cone` is passed or `core.sparseCheckoutCone` is false,\n> > -the input list is considered a list of patterns. This mode is harder\n> > -to use and less performant, and is thus not recommended. See the\n> > -\"Sparse Checkout\" section of linkgit:git-read-tree[1] and the \"Pattern\n> > -Set\" sections below for more details.\n> > +When `--no-cone` is passed, the input list is considered a list of\n> > +patterns. This mode is harder to use and less performant, and is thus\n>\n> \"less perfromant\" can be quantified, but \"harder to use\" is probably\n> harder to defend. Those on a project with need for more flexible\n> way to specify than \"these are the directories I care about\" would\n> not find it convincing.\n\nThat text wasn't added by this patch (or even by any patch in this\nseries); it was in the pre-image. I can still change it, of course,\nbut I don't think it belongs in this particular patch. How about I\nreplace this text in 8/9 with a link to the new section that was added\n(the one that explains the problems we see with non-cone mode).\n\n> > +not recommended. See the \"Sparse Checkout\" section of\n> > +linkgit:git-read-tree[1]\n>\n> The referenced section (I am reading \"git read-tree --help\" from\n> seen with these patches) may need updating. It shows an example\n> of including everything except for unwanted, without mentioning\n> if that is for cone or non-cone.\n\nI wouldn't really say that the example is for either mode (the point\nof the sparse-checkout command is so users don't need to directly edit\nthe $GIT_DIR/info/sparse-checkout file), but the examples might be\nuseful for people trying to understand the patterns used in non-cone\nmode. Perhaps this change would be helpful?:\n\ndiff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\nindex 99bb387134..0eae9e01fd 100644\n--- a/Documentation/git-read-tree.txt\n+++ b/Documentation/git-read-tree.txt\n@@ -378,7 +378,9 @@ SPARSE CHECKOUT\n Note: The `update-index` and `read-tree` primitives for supporting the\n skip-worktree bit predated the introduction of\n linkgit:git-sparse-checkout[1]. Users are encouraged to use\n-`sparse-checkout` in preference to these low-level primitives.\n+`sparse-checkout` in preference to these low-level primitives. However,\n+the information below might be useful to users trying to understand the\n+pattern style used in non-cone mode of the `sparse-checkout` command.\n\nHowever, I don't think that belongs in this patch (since you were\ncommenting on text that only appeared in the diff due to reflowing\nparagraphs), but I can add it to 9/9.\n\n> > and the \"Pattern Set\" sections below for more\n> > +details.\n>\n> Are we referring to \"Internals - cone/full pattern set\" sections?\n\nYeah, as you noted in a later patch, you got confused by looking at\nthe end result rather than the state of the tree as of this patch.\nThe \"Internals -\" prefix was added in a later patch.\n\n> This may be a topic of another step in this series, but the \"core\"\n> section starts by mentioning what characteristics the full pattern\n> set has and uses it to steer readers away from it, which I find it\n> less than ideal. As we present \"core\" first (because it is the\n> default), we should present \"core\" by itself, without requiring to\n> know what the other thing is.\n\nBy '\"core\" section' do you mean the \"cone pattern set\" section?\nThat's my best guess after several comparisons. I agree that it's\nless than ideal, though I thought that perhaps adding the \"Internals\"\nprefix would allow folks to just ignore it. But you may be right that\nI should also overhaul it a bit, maybe splitting it into two sections,\none about some implementation details about the mode, and another\nlater section about how the patterns in cone mode are a strictly\ncontrolled subset of the possible full pattern set. However, I think\nthat'd go better in patch 7 rather than here.\n\n> Perhaps replace the entire first\n> paragraph so that the section begins more like so:\n>\n> The \"cone mode\", which is the default, lets you specify only\n> what directories to include and what directories to exclude.\n\nThere's no provision to specify individual directories to exclude,\nonly which to include. Everything not listed is excluded.\n\n> The accepted patterns in the cone pattern set are:...\n>\n> Especially, the last sentence in the paragraph to be struck still\n> lives in the old world in which you needed to opt into the cone\n> mode.\n\nThis patch didn't strike any paragraph, so I'm not sure which sentence\nyou're referring to. I tried looking around, and didn't readily find\nit either. Perhaps my big reshufflings in my new patch 7 addressed\nwhat you're talking about, though?\n"},{"id":"454208","messageId":"CABPp-BGaVvUBadGWn5rCgjO8tP9OVmjD0WvYw2dR36Brf=Rbmw@mail.gmail.com","threadId":"57519","inReplyTo":"xmqqsfrkp83y.fsf@gitster.g","subject":"Re: [PATCH v2 5/9] git-sparse-checkout.txt: shuffle some sections and mark as internal","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2022-04-22T02:30:02Z","receivedAt":"2022-04-22T02:30:21Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"On Mon, Mar 14, 2022 at 1:55 PM Junio C Hamano wrote:\n>\n> \"Elijah Newren via GitGitGadget\" writes:\n>\n> > -CONE PATTERN SET\n> > -----------------\n> > +INTERNALS -- CONE PATTERN SET\n> > +-----------------------------\n>\n> Ah, this is why I was confused during my review of an earlier step,\n> where it refered to this (and the other) sections as \"sections on\n> 'pattern set'\", because I was reading the end-result of applying the\n> whole series.\n>\n> With this change, shouldn't the reference be updated?\n\nMakes sense; will do.\n"},{"id":"454209","messageId":"CABPp-BE6bFsdSs1j4_M7T1EisT6vQOOoTPeRU8GJKprRqqeedw@mail.gmail.com","threadId":"57519","inReplyTo":"xmqqo828p7zt.fsf@gitster.g","subject":"Re: [PATCH v2 7/9] git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a bit","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2022-04-22T02:30:08Z","receivedAt":"2022-04-22T02:30:29Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"On Mon, Mar 14, 2022 at 1:57 PM Junio C Hamano wrote:\n>\n> \"Elijah Newren via GitGitGadget\" writes:\n>\n> > INTERNALS -- FULL PATTERN SET\n> > -----------------------------\n> >\n> > -By default, the sparse-checkout file uses the same syntax as `.gitignore`\n> > -files.\n> > -\n> > -While `$GIT_DIR/info/sparse-checkout` is usually used to specify what\n> > -files are included, you can also specify what files are _not_ included,\n> > -using negative patterns. For example, to remove the file `unwanted`:\n> > +As noted above, the sparse-checkout file uses the same syntax as\n> > +`.gitignore` files; see linkgit:gitignore[5] for details. Here,\n>\n> Here, following the suggestion to fix the early part of \"Cone mode\n> patterns\" section, move the \"it is more flexible but requires more\n> cycles to process\" you had there to replace the \"As noted above\".\n\nMakes sense; I'll restructure it with this and some of the other\nmodifications you mentioned earlier to simplify the cone mode\ndiscussion.\n"},{"id":"454210","messageId":"CABPp-BH_GuWdW55FAF=keidVWv+Zy3OJG6pN-VpcpOdCZuKqGw@mail.gmail.com","threadId":"57519","inReplyTo":"xmqqa6dsp78q.fsf@gitster.g","subject":"Re: [PATCH v2 8/9] git-sparse-checkout.txt: mark non-cone mode as deprecated","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2022-04-22T02:31:06Z","receivedAt":"2022-04-22T02:31:23Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"On Mon, Mar 14, 2022 at 2:14 PM Junio C Hamano wrote:\n>\n> \"Elijah Newren via GitGitGadget\" writes:\n>\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.\n>\n> If we explicitly say we have no intention to remove, while saying\n> that \"non-cone\" mode is a second class citizen, the users would be\n> confused.\n\nI don't see why they'd be confused. It seems common to me in software\ndevelopment to state that a less preferred option will continue to be\nsupported with its existing feature set, while some other option is\nboth recommended and will gain new features.\n\n> Does this mixed attitude only apply to non-cone mode, or\n> is it true for any other fringe features that we do not care about\n> in Git?\n>\n> This does not build confidence with the Git software suite. If we\n> are removing, then this attitude is OK, but if we are keeping it,\n> then we should promise that we never add features only to \"cone\".\n\nThe sparse-index feature only works with \"cone\" mode and adding\nsupport for non-cone mode would be infeasible. So we've already\ncrossed that line.\n\nI'd also like to make partial clones and sparse-checkouts work better\ntogether (something you also suggested in the past), and improve\nsupport for disconnected development. In particular, having a partial\nclone that starts with the history of files within the sparse-cone\ninstead of an empty set of blobs seems like a reasonable way to do\nthat. However, having a partial clone that starts with the history of\nfiles matching a non-cone mode set of paths seems intractable to me; I\ndon't see how that could reasonably be implemented server side and\nwould expect it to be rejected even if implemented. So there's at\nleast one example in my mind where we would want to cross that line\nagain.\n\nAlthough, if you really are saying these are the only two acceptable\noptions to you, then I'll start pushing to remove non-cone mode;\nthat'd be much preferable to removing the sparse-index feature and\nhamstringing future development.\n\n> > +INTERNALS -- NON-CONE PROBLEMS\n> > +------------------------------\n> > +\n> > +The `$GIT_DIR/info/sparse-checkout` file populated by the `set` and\n> > +`add` subcommands is defined to be a bunch of patterns (one per line)\n> > +using the same syntax as `.gitignore` files. In cone mode, these\n> > +patterns are restricted to matching directories (and users only ever\n> > +need supply or see directory names), while in non-cone mode any\n> > +gitignore-style pattern is permitted. Using the full gitignore-style\n> > +patterns in non-cone mode has a number of shortcomings:\n> > +\n> > + * Fundamentally, it makes various worktree-updating processes (pull,\n> > + merge, rebase, switch, reset, checkout, etc.) require O(N*M) pattern\n> > + matches, where N is the number of patterns and M is the number of\n> > + paths in the index. This scales poorly.\n> > +\n> > + * Avoiding the scaling issue has to be done via limiting the number\n> > + of patterns via specifying leading directory name or glob.\n>\n> These are valid.\n>\n> > + * Passing globs on the command line is error-prone as users may\n> > + forget to quote the glob, causing the shell to expand it into all\n> > + matching files and pass them all individually along to\n> > + sparse-checkout set/add. This both exacerbates the scaling\n> > + problem, and hardcodes the list of selected files to those which\n> > + were present at the time the initial set/add subcommand was run\n> > + (and thus ignoring other files matching the same glob which come\n> > + into the working tree after switching branches or pulling down\n> > + updates).\n>\n> That's end-user mistakes that is common to other things like\n> pathspecs, i.e. \"git grep -- \\*.c\" vs \"git grep -- *.c\". It hardly\n> deserves to spend more than 5 lines shouting.\n\nFair point.\n\nI do think there's still a small qualitative difference, though, in\nregards to timing and the ability of the user to discover their\nmistake. With sparse-checkout, the mistake gets recorded and affects\nlater commands. In particular, it's possible that at the time the\ncommand is run, the shell completion of the glob catches all currently\nexisting relevant files, so the user doesn't notice the mistake. Once\nthe user switches branches or rebases or merges or whatever, then the\npast expansion of the glob finally bites the user. In contrast, if\nthe grep/log/status command is wrong, it's noticeable from the\nimmediate output the user gets and they can simply re-run with the\ncorrected command.\n\n> > + * It uses \"ignore\"/\"exclude\" syntax for selecting what to \"include\",\n> > + which periodically causes confusion.\n>\n> Well, .gitignore uses the syntax to select the paths to include or\n> exclude from a set, and then the set specifies what is left out of\n> the index. I am not sure if that is the source of confusion.\n\nPerhaps I should reword this point:\n\n * .gitignore files use the gitignore pattern syntax to specify\npatterns that are *excluded* (unless the pattern is negated) from the\nindex.\n * non-cone mode sparse-checkout uses the same syntax to specify\npatterns with the opposite meaning -- they are *included* in the tree\n(unless the pattern is negated).\n\nIf there were two copies of the pattern specification, or if the\ndocumentation carefully pointed out matching/non-matching instead of\nexclude/include everywhere, then this perhaps wouldn't be a problem.\nHowever, the documentation for these patterns is almost completely\n.gitignore-specific and written talking about exclusion (with\ninclusion exceptions).\n\n> > + * It introduces inconsistencies in the Git command line, since other\n> > + commands use pathspecs, but sparse-checkout (in non-cone mode) uses\n> > + gitignore patterns.\n>\n> But \"cone\" mode does not take pathspec, does it? \":(icase)/A/B/C\"\n> for example? I do not see this as a credible argument against it.\n\nMy objection is that it's weird having two different forms of \"special\npath pattern matching\" in the git command line. Every git subcommand\nthat has such a thing uses pathspecs, except for non-cone mode\nsparse-checkout.\n\nI don't see why any subcommand necessarily needs to have \"special path\npattern matching\", I'm just saying that *if* some subcommand does have\nsuch a thing, it'd be nice to use the same kind of special path\npattern matching that all other git commands do.\n\n> > + * It has edge cases where the \"right\" behavior is unclear. Two examples:\n> > +\n> > + First, two users are in a subdirectory, and the first runs\n> > + git sparse-checkout set '/toplevel-dir/*.c'\n> > + while the second runs\n> > + git sparse-checkout set relative-dir\n>\n> Are we aware which mode of sparse-checkout they are in? Do we give\n> a mechanism for users to ask \"we have 'non-cone' sparse checkout in\n> the sparse-checkout file. we want to use the more efficient and\n> recommended 'cone' mode. Please convert it\", or even if there is\n> not an automated conversion mechansim, can the user manually do so\n> (which I suspect is not fundamentally possible---the cone mode is\n> inherently less expressive)?\n>\n> If not, then we should expect these two users to _know_ (or at least\n> check before they run \"set\" subcommand) which mode is in use.\n>\n> So, with that expectation,\n>\n> > + Should those arguments be transliterated into\n> > + current/subdirectory/toplevel-dir/*.c\n> > + and\n> > + current/subdirectory/relative-dir\n>\n> If we are using non-cone mode, then both would be recorded as-is.\n\nRecording '/toplevel-dir/*.c' and 'relative-dir' as-is sounds great to\nme, but doesn't it run contrary to what you previously pushed for\ntab-completion? Previously, you said that in non-cone mode, tab\ncompletion should complete on files and directories (with no \"relative\nto the toplevel directory\" qualification that I could see), which does\nnot seem to work well with what you've specified here.\n"},{"id":"454211","messageId":"05dba7069c5e0c1aec1a7206f9cbea593d8d68cb.1650594746.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.v3.git.1650594746.gitgitgadget@gmail.com","subject":"[PATCH v3 1/9] tests: stop assuming --no-cone is the default mode for sparse-checkout","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-04-22T02:32:18Z","receivedAt":"2022-04-22T02:32:34Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nAdd an explicit --no-cone to several sparse-checkout invocations in\npreparation for changing the default to cone mode.\n\nSigned-off-by: Elijah Newren \n---\n t/t1091-sparse-checkout-builtin.sh | 15 ++++++++-------\n t/t3602-rm-sparse-checkout.sh | 6 +++---\n t/t3705-add-sparse-checkout.sh | 4 ++--\n t/t6428-merge-conflicts-sparse.sh | 4 ++--\n t/t7002-mv-sparse-checkout.sh | 2 +-\n t/t7012-skip-worktree-writing.sh | 2 +-\n 6 files changed, 17 insertions(+), 16 deletions(-)\n\ndiff --git a/t/t1091-sparse-checkout-builtin.sh b/t/t1091-sparse-checkout-builtin.sh\nindex 9a900310186..de1ec89007d 100755\n--- a/t/t1091-sparse-checkout-builtin.sh\n+++ b/t/t1091-sparse-checkout-builtin.sh\n@@ -72,7 +72,7 @@ test_expect_success 'git sparse-checkout list (populated)' '\n '\n \n test_expect_success 'git sparse-checkout init' '\n-\tgit -C repo sparse-checkout init &&\n+\tgit -C repo sparse-checkout init --no-cone &&\n \tcat >expect <<-\\EOF &&\n \t/*\n \t!/*/\n@@ -111,6 +111,7 @@ test_expect_success 'init with existing sparse-checkout' '\n \n test_expect_success 'clone --sparse' '\n \tgit clone --sparse \"file://$(pwd)/repo\" clone &&\n+\tgit -C clone sparse-checkout reapply --no-cone &&\n \tgit -C clone sparse-checkout list >actual &&\n \tcat >expect <<-\\EOF &&\n \t/*\n@@ -124,7 +125,7 @@ test_expect_success 'switching to cone mode with non-cone mode patterns' '\n \tgit init bad-patterns &&\n \t(\n \t\tcd bad-patterns &&\n-\t\tgit sparse-checkout init &&\n+\t\tgit sparse-checkout init --no-cone &&\n \t\tgit sparse-checkout add dir &&\n \t\tgit config --worktree core.sparseCheckoutCone true &&\n \t\ttest_must_fail git sparse-checkout add dir 2>err &&\n@@ -402,7 +403,7 @@ test_expect_success 'revert to old sparse-checkout on empty update' '\n \t\tgit sparse-checkout set nothing 2>err &&\n \t\ttest_i18ngrep ! \"Sparse checkout leaves no entry on working directory\" err &&\n \t\ttest_i18ngrep ! \".git/index.lock\" err &&\n-\t\tgit sparse-checkout set file\n+\t\tgit sparse-checkout set --no-cone file\n \t)\n '\n \n@@ -424,7 +425,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with dirty status'\n \tgit clone repo dirty &&\n \techo dirty >dirty/folder1/a &&\n \n-\tgit -C dirty sparse-checkout init 2>err &&\n+\tgit -C dirty sparse-checkout init --no-cone 2>err &&\n \ttest_i18ngrep \"warning.*The following paths are not up to date\" err &&\n \n \tgit -C dirty sparse-checkout set /folder2/* /deep/deeper1/* 2>err &&\n@@ -435,7 +436,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with dirty status'\n \ttest_must_be_empty err &&\n \n \tgit -C dirty reset --hard &&\n-\tgit -C dirty sparse-checkout init &&\n+\tgit -C dirty sparse-checkout init --no-cone &&\n \tgit -C dirty sparse-checkout set /folder2/* /deep/deeper1/* &&\n \ttest_path_is_missing dirty/folder1/a &&\n \tgit -C dirty sparse-checkout disable &&\n@@ -451,7 +452,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with unmerged stat\n \tEOF\n \tgit -C unmerged update-index --index-info err &&\n+\tgit -C unmerged sparse-checkout init --no-cone 2>err &&\n \ttest_i18ngrep \"warning.*The following paths are unmerged\" err &&\n \n \tgit -C unmerged sparse-checkout set /folder2/* /deep/deeper1/* 2>err &&\n@@ -462,7 +463,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with unmerged stat\n \ttest_i18ngrep \"warning.*The following paths are unmerged\" err &&\n \n \tgit -C unmerged reset --hard &&\n-\tgit -C unmerged sparse-checkout init &&\n+\tgit -C unmerged sparse-checkout init --no-cone &&\n \tgit -C unmerged sparse-checkout set /folder2/* /deep/deeper1/* &&\n \tgit -C unmerged sparse-checkout disable\n '\ndiff --git a/t/t3602-rm-sparse-checkout.sh b/t/t3602-rm-sparse-checkout.sh\nindex 034ec010910..08580fd3dcc 100755\n--- a/t/t3602-rm-sparse-checkout.sh\n+++ b/t/t3602-rm-sparse-checkout.sh\n@@ -30,7 +30,7 @@ test_expect_success 'setup' \"\n for opt in \"\" -f --dry-run\n do\n \ttest_expect_success \"rm${opt:+ $opt} does not remove sparse entries\" '\n-\t\tgit sparse-checkout set a &&\n+\t\tgit sparse-checkout set --no-cone a &&\n \t\ttest_must_fail git rm $opt b 2>stderr &&\n \t\ttest_cmp b_error_and_hint stderr &&\n \t\tgit ls-files --error-unmatch b\n@@ -118,7 +118,7 @@ test_expect_success 'can remove files from non-sparse dir' '\n \ttest_commit w/f &&\n \ttest_commit x/y/f &&\n \n-\tgit sparse-checkout set w !/x y/ &&\n+\tgit sparse-checkout set --no-cone w !/x y/ &&\n \tgit rm w/f.t x/y/f.t 2>stderr &&\n \ttest_must_be_empty stderr\n '\n@@ -128,7 +128,7 @@ test_expect_success 'refuse to remove non-skip-worktree file from sparse dir' '\n \tgit sparse-checkout disable &&\n \tmkdir -p x/y/z &&\n \ttest_commit x/y/z/f &&\n-\tgit sparse-checkout set !/x y/ !x/y/z &&\n+\tgit sparse-checkout set --no-cone !/x y/ !x/y/z &&\n \n \tgit update-index --no-skip-worktree x/y/z/f.t &&\n \ttest_must_fail git rm x/y/z/f.t 2>stderr &&\ndiff --git a/t/t3705-add-sparse-checkout.sh b/t/t3705-add-sparse-checkout.sh\nindex 95609046c61..2bade9e804f 100755\n--- a/t/t3705-add-sparse-checkout.sh\n+++ b/t/t3705-add-sparse-checkout.sh\n@@ -166,7 +166,7 @@ test_expect_success 'do not warn when pathspec matches dense entries' '\n test_expect_success 'git add fails outside of sparse-checkout definition' '\n \ttest_when_finished git sparse-checkout disable &&\n \ttest_commit a &&\n-\tgit sparse-checkout init &&\n+\tgit sparse-checkout init --no-cone &&\n \tgit sparse-checkout set a &&\n \techo >>sparse_entry &&\n \n@@ -208,7 +208,7 @@ test_expect_success 'add obeys advice.updateSparsePath' '\n '\n \n test_expect_success 'add allows sparse entries with --sparse' '\n-\tgit sparse-checkout set a &&\n+\tgit sparse-checkout set --no-cone a &&\n \techo modified >sparse_entry &&\n \ttest_must_fail git add sparse_entry &&\n \ttest_sparse_entry_unchanged &&\ndiff --git a/t/t6428-merge-conflicts-sparse.sh b/t/t6428-merge-conflicts-sparse.sh\nindex 142c9aaabc5..064be1b629e 100755\n--- a/t/t6428-merge-conflicts-sparse.sh\n+++ b/t/t6428-merge-conflicts-sparse.sh\n@@ -87,7 +87,7 @@ test_expect_success 'conflicting entries written to worktree even if sparse' '\n \t\ttest_path_is_file numerals &&\n \n \t\tgit sparse-checkout init &&\n-\t\tgit sparse-checkout set README &&\n+\t\tgit sparse-checkout set --no-cone README &&\n \n \t\ttest_path_is_file README &&\n \t\ttest_path_is_missing numerals &&\n@@ -123,7 +123,7 @@ test_expect_success 'present-despite-SKIP_WORKTREE handled reasonably' '\n \t\ttest_path_is_file numerals &&\n \n \t\tgit sparse-checkout init &&\n-\t\tgit sparse-checkout set README &&\n+\t\tgit sparse-checkout set --no-cone README &&\n \n \t\ttest_path_is_file README &&\n \t\ttest_path_is_missing numerals &&\ndiff --git a/t/t7002-mv-sparse-checkout.sh b/t/t7002-mv-sparse-checkout.sh\nindex 1d3d2aca21c..f0f7cbfcdb7 100755\n--- a/t/t7002-mv-sparse-checkout.sh\n+++ b/t/t7002-mv-sparse-checkout.sh\n@@ -27,7 +27,7 @@ test_expect_success 'setup' \"\n test_expect_success 'mv refuses to move sparse-to-sparse' '\n \ttest_when_finished rm -f e &&\n \tgit reset --hard &&\n-\tgit sparse-checkout set a &&\n+\tgit sparse-checkout set --no-cone a &&\n \ttouch b &&\n \ttest_must_fail git mv b e 2>stderr &&\n \tcat sparse_error_header >expect &&\ndiff --git a/t/t7012-skip-worktree-writing.sh b/t/t7012-skip-worktree-writing.sh\nindex cb9f1a6981e..cd5c20fe51b 100755\n--- a/t/t7012-skip-worktree-writing.sh\n+++ b/t/t7012-skip-worktree-writing.sh\n@@ -151,7 +151,7 @@ test_expect_success 'stash restore in sparse checkout' '\n \n \t\tgit stash push &&\n \n-\t\tgit sparse-checkout set subdir &&\n+\t\tgit sparse-checkout set --no-cone subdir &&\n \n \t\t# Ensure after sparse-checkout we only have expected files\n \t\tcat >expect <<-EOF &&\n-- \ngitgitgadget\n\n"},{"id":"454212","messageId":"d86c9179435a6f44446de525089c0fcb3df0b117.1650594746.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.v3.git.1650594746.gitgitgadget@gmail.com","subject":"[PATCH v3 2/9] sparse-checkout: make --cone the default","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-04-22T02:32:19Z","receivedAt":"2022-04-22T02:32:36Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nMake cone mode the default, and update the documentation accordingly.\n\nSigned-off-by: Elijah Newren \n---\n Documentation/config/core.txt | 6 ++++--\n Documentation/git-sparse-checkout.txt | 20 ++++++++++----------\n builtin/sparse-checkout.c | 2 +-\n 3 files changed, 15 insertions(+), 13 deletions(-)\n\ndiff --git a/Documentation/config/core.txt b/Documentation/config/core.txt\nindex c04f62a54a1..03cf075821b 100644\n--- a/Documentation/config/core.txt\n+++ b/Documentation/config/core.txt\n@@ -615,8 +615,10 @@ core.sparseCheckout::\n \n core.sparseCheckoutCone::\n \tEnables the \"cone mode\" of the sparse checkout feature. When the\n-\tsparse-checkout file contains a limited set of patterns, then this\n-\tmode provides significant performance advantages. See\n+\tsparse-checkout file contains a limited set of patterns, this\n+\tmode provides significant performance advantages. The \"non\n+\tcone mode\" can be requested to allow specifying a more flexible\n+\tpatterns by setting this variable to 'false'. See\n \tlinkgit:git-sparse-checkout[1] for more information.\n \n core.abbrev::\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 88e55f432f3..7308e744c57 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -22,8 +22,8 @@ present, or undo and go back to having all tracked files present in the\n working copy.\n \n The subset of files is chosen by providing a list of directories in\n-cone mode (which is recommended), or by providing a list of patterns\n-in non-cone mode.\n+cone mode (the default), or by providing a list of patterns in\n+non-cone mode.\n \n When in a sparse-checkout, other Git commands behave a bit differently.\n For example, switching branches will not update paths outside the\n@@ -60,7 +60,7 @@ 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-When `--cone` is passed or `core.sparseCheckoutCone` is enabled, the\n+When `--cone` is passed or `core.sparseCheckoutCone` is not false, the\n input list is considered a list of directories. This allows for\n better performance with a limited set of patterns (see 'CONE PATTERN\n SET' below). The input format matches the output of `git ls-tree\n@@ -68,10 +68,9 @@ SET' below). The input format matches the output of `git ls-tree\n double quote (\") as C-style quoted strings. Note that the set command\n will write patterns to the sparse-checkout file to include all files\n contained in those directories (recursively) as well as files that are\n-siblings of ancestor directories. This may become the default in the\n-future; --no-cone can be passed to request non-cone mode.\n+siblings of ancestor directories.\n +\n-When `--no-cone` is passed or `core.sparseCheckoutCone` is not enabled,\n+When `--no-cone` is passed or `core.sparseCheckoutCone` is set to false,\n the input list is considered a list of patterns. This mode is harder\n to use and less performant, and is thus not recommended. See the\n \"Sparse Checkout\" section of linkgit:git-read-tree[1] and the \"Pattern\n@@ -227,10 +226,11 @@ patterns. The resulting sparse-checkout file is now\n Here, order matters, so the negative patterns are overridden by the positive\n patterns that appear lower in the file.\n \n-If `core.sparseCheckoutCone=true`, then Git will parse the sparse-checkout file\n-expecting patterns of these types. Git will warn if the patterns do not match.\n-If the patterns do match the expected format, then Git will use faster hash-\n-based algorithms to compute inclusion in the sparse-checkout.\n+Unless `core.sparseCheckoutCone` is explicitly set to `false`, Git will\n+parse the sparse-checkout file expecting patterns of these types. Git will\n+warn if the patterns do not match. If the patterns do match the expected\n+format, then Git will use faster hash-based algorithms to compute inclusion\n+in the sparse-checkout.\n \n In the cone mode case, the `git sparse-checkout list` subcommand will list the\n directories that define the recursive patterns. For the example sparse-checkout\ndiff --git a/builtin/sparse-checkout.c b/builtin/sparse-checkout.c\nindex 5518ed47f6c..61b7a7519bb 100644\n--- a/builtin/sparse-checkout.c\n+++ b/builtin/sparse-checkout.c\n@@ -397,7 +397,7 @@ static int update_modes(int *cone_mode, int *sparse_index)\n \n \t/* Set cone/non-cone mode appropriately */\n \tcore_apply_sparse_checkout = 1;\n-\tif (*cone_mode == 1) {\n+\tif (*cone_mode == 1 || *cone_mode == -1) {\n \t\tmode = MODE_CONE_PATTERNS;\n \t\tcore_sparse_checkout_cone = 1;\n \t} else {\n-- \ngitgitgadget\n\n"},{"id":"454213","messageId":"pull.1148.v3.git.1650594746.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.v2.git.1647054681.gitgitgadget@gmail.com","subject":"[PATCH v3 0/9] sparse-checkout: make cone mode the default","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-04-22T02:32:17Z","receivedAt":"2022-04-22T02:32:37Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"Sorry for the long delay since v1. On the plus side, perhaps there will be a\nlonger feedback period for this series since it's now really early in the\n2.37 series?\n\n== Updates Log ==\n\nChanges since v2:\n\n * Code style tweak suggested by Junio in one area, reverting back to v1.\n * Several documentation updates to address Junio's review. Patches 6 & 7\n had significant changes and would most benefit from a further review.\n\nChanges since v1:\n\n * rebased on master, to remove dependence on en/present-despite-skipped\n (which has since merged to master). Earlier version of series wasn't\n picked up anyway, so rebasing should be safe.\n * Wording and code style tweaks suggested by Stolee in his review\n\n== Overview ==\n\nThis patch changes the default mode for sparse-checkout from non-cone mode\nto cone-mode, and marks non-cone mode as deprecated. There is no plan to\nremove non-cone mode, we are merely recommending against its use.\n\nThe code change is pretty small, and most of this series is about\ndocumentation updates -- to focus on directories rather than patterns, to\nexplain the new default, to explain why we are deprecating non-cone mode\n(the final patch), and to make other related cleanups to simplify the\nmanual.\n\nPatch 1: Update tests to not assume cone-mode is the default Patch 2: Make\ncone-mode the default Patches 3-9: Various updates to\ngit-sparse-checkout.txt, divided up for ease of review\n\n== Alternative ==\n\nThere is one primary alternative to this series: make sparse-checkout error\nwhen neither --cone nor --no-cone are specified (so that there is no\ndefault), and wait until a future date to make --cone the default. That'd be\nreasonable, but I had three reason to avoid going this route (note that item\n2 means there's little practical difference between cone-mode-as-default and\nno-mode-is-default):\n\n 1. git-sparse-checkout.txt has the following huge warning early in the\n manual:\n\n\"\"\" THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR, AND THE BEHAVIOR OF OTHER\nCOMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN THE\nFUTURE. \"\"\"\n\n 2. If users are unaware of the default change and attempt to provide\n patterns instead of directories, then they will get error messages added\n from en/sparse-checkout-fixes. They can learn at that time to get around\n the error messages by providing --no-cone.\n\n 3. If users are unaware of the default change and provide directories, then\n that's where non-cone mode and cone mode overlap and things happen to\n work. (There is a slight difference in that cone mode will include files\n from parent directories of any specified directory, but that means the\n user gets a few more files in their sparse-checkout with cone mode than\n they would with non-cone mode.)\n\n== CCs ==\n\nElijah Newren (9):\n tests: stop assuming --no-cone is the default mode for sparse-checkout\n sparse-checkout: make --cone the default\n git-sparse-checkout.txt: wording updates for the cone mode default\n git-sparse-checkout.txt: update docs for deprecation of 'init'\n git-sparse-checkout.txt: shuffle some sections and mark as internal\n git-sparse-checkout.txt: add a new EXAMPLES section\n git-sparse-checkout.txt: flesh out pattern set sections a bit\n git-sparse-checkout.txt: mark non-cone mode as deprecated\n Documentation: some sparsity wording clarifications\n\n Documentation/config/core.txt | 6 +-\n Documentation/git-read-tree.txt | 11 +-\n Documentation/git-sparse-checkout.txt | 317 +++++++++++++++++++-------\n builtin/sparse-checkout.c | 2 +-\n t/t1091-sparse-checkout-builtin.sh | 15 +-\n t/t3602-rm-sparse-checkout.sh | 6 +-\n t/t3705-add-sparse-checkout.sh | 4 +-\n t/t6428-merge-conflicts-sparse.sh | 4 +-\n t/t7002-mv-sparse-checkout.sh | 2 +-\n t/t7012-skip-worktree-writing.sh | 2 +-\n 10 files changed, 268 insertions(+), 101 deletions(-)\n\n\nbase-commit: 1a4874565fa3b6668042216189551b98b4dc0b1b\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1148%2Fnewren%2Fsparse-checkout-default-v3\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1148/newren/sparse-checkout-default-v3\nPull-Request: https://github.com/gitgitgadget/git/pull/1148\n\nRange-diff vs v2:\n\n 1: 05dba7069c5 = 1: 05dba7069c5 tests: stop assuming --no-cone is the default mode for sparse-checkout\n 2: a53179764bc ! 2: d86c9179435 sparse-checkout: make --cone the default\n @@ Commit message\n \n Signed-off-by: Elijah Newren \n \n + ## Documentation/config/core.txt ##\n +@@ Documentation/config/core.txt: core.sparseCheckout::\n + \n + core.sparseCheckoutCone::\n + \tEnables the \"cone mode\" of the sparse checkout feature. When the\n +-\tsparse-checkout file contains a limited set of patterns, then this\n +-\tmode provides significant performance advantages. See\n ++\tsparse-checkout file contains a limited set of patterns, this\n ++\tmode provides significant performance advantages. The \"non\n ++\tcone mode\" can be requested to allow specifying a more flexible\n ++\tpatterns by setting this variable to 'false'. See\n + \tlinkgit:git-sparse-checkout[1] for more information.\n + \n + core.abbrev::\n +\n ## Documentation/git-sparse-checkout.txt ##\n @@ Documentation/git-sparse-checkout.txt: present, or undo and go back to having all tracked files present in the\n working copy.\n @@ Documentation/git-sparse-checkout.txt: SET' below). The input format matches th\n +siblings of ancestor directories.\n +\n -When `--no-cone` is passed or `core.sparseCheckoutCone` is not enabled,\n -+When `--no-cone` is passed or `core.sparseCheckoutCone` is false,\n ++When `--no-cone` is passed or `core.sparseCheckoutCone` is set to false,\n the input list is considered a list of patterns. This mode is harder\n to use and less performant, and is thus not recommended. See the\n \"Sparse Checkout\" section of linkgit:git-read-tree[1] and the \"Pattern\n @@ Documentation/git-sparse-checkout.txt: patterns. The resulting sparse-checkout f\n -expecting patterns of these types. Git will warn if the patterns do not match.\n -If the patterns do match the expected format, then Git will use faster hash-\n -based algorithms to compute inclusion in the sparse-checkout.\n -+If `core.sparseCheckoutCone=true` (set by default or with an explicit\n -+`--cone`), then Git will parse the sparse-checkout file expecting\n -+patterns of these types. Git will warn if the patterns do not match. If\n -+the patterns do match the expected format, then Git will use faster\n -+hash-based algorithms to compute inclusion in the sparse-checkout.\n ++Unless `core.sparseCheckoutCone` is explicitly set to `false`, Git will\n ++parse the sparse-checkout file expecting patterns of these types. Git will\n ++warn if the patterns do not match. If the patterns do match the expected\n ++format, then Git will use faster hash-based algorithms to compute inclusion\n ++in the sparse-checkout.\n \n In the cone mode case, the `git sparse-checkout list` subcommand will list the\n directories that define the recursive patterns. For the example sparse-checkout\n @@ builtin/sparse-checkout.c: static int update_modes(int *cone_mode, int *sparse_i\n \t/* Set cone/non-cone mode appropriately */\n \tcore_apply_sparse_checkout = 1;\n -\tif (*cone_mode == 1) {\n -+\tif (*cone_mode) { /* also handles \"not specified\" (value of -1) */\n ++\tif (*cone_mode == 1 || *cone_mode == -1) {\n \t\tmode = MODE_CONE_PATTERNS;\n \t\tcore_sparse_checkout_cone = 1;\n \t} else {\n 3: 8eab21996c7 ! 3: b1e2c95a278 git-sparse-checkout.txt: wording updates for the cone mode default\n @@ Documentation/git-sparse-checkout.txt: When the `--stdin` option is provided, th\n +and `--cone` needed to be specified or `core.sparseCheckoutCone` needed\n +to be enabled.\n +\n - When `--no-cone` is passed or `core.sparseCheckoutCone` is false,\n + When `--no-cone` is passed or `core.sparseCheckoutCone` is set to false,\n the input list is considered a list of patterns. This mode is harder\n @@ Documentation/git-sparse-checkout.txt: the following patterns:\n This says \"include everything in root, but nothing two levels below root.\"\n 4: eb3b318b39e ! 4: b0b57cd37e7 git-sparse-checkout.txt: update docs for deprecation of 'init'\n @@ Documentation/git-sparse-checkout.txt: SET' below for more details). In the pas\n and `--cone` needed to be specified or `core.sparseCheckoutCone` needed\n to be enabled.\n +\n --When `--no-cone` is passed or `core.sparseCheckoutCone` is false,\n +-When `--no-cone` is passed or `core.sparseCheckoutCone` is set to false,\n -the input list is considered a list of patterns. This mode is harder\n -to use and less performant, and is thus not recommended. See the\n -\"Sparse Checkout\" section of linkgit:git-read-tree[1] and the \"Pattern\n 5: 7333198b778 ! 5: eda0f41395b git-sparse-checkout.txt: shuffle some sections and mark as internal\n @@ Commit message\n Signed-off-by: Elijah Newren \n \n ## Documentation/git-sparse-checkout.txt ##\n +@@ Documentation/git-sparse-checkout.txt: to be enabled.\n + When `--no-cone` is passed, the input list is considered a list of\n + patterns. This mode is harder to use and less performant, and is thus\n + not recommended. See the \"Sparse Checkout\" section of\n +-linkgit:git-read-tree[1] and the \"Pattern Set\" sections below for more\n +-details.\n ++linkgit:git-read-tree[1] and the \"Internals...Pattern Set\" sections\n ++below 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 @@ Documentation/git-sparse-checkout.txt: 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 6: a814ea9e8d2 = 6: 7908c8f83d8 git-sparse-checkout.txt: add a new EXAMPLES section\n 7: 78028ecaa58 ! 7: 546ae3d6732 git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a bit\n @@ Metadata\n Author: Elijah Newren \n \n ## Commit message ##\n - git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a bit\n + git-sparse-checkout.txt: flesh out pattern set sections a bit\n +\n + The \"Internals -- Cone Pattern Set\" section starts off discussing\n + patterns, despite the fact that cone mode is about avoiding the\n + patterns. This made sense back when non-cone mode was the default and\n + we started by discussing the full pattern set, but now that we are\n + changing the default, it makes more sense to discuss cone-mode first and\n + avoid the full discussion of patterns. Split this section into two, the\n + first with details about how cone mode operates, and the second\n + following the full pattern set section and discussing how the cone mode\n + patterns used under the hood relate to the full pattern set.\n +\n + While at it, flesh out the \"Internals -- Full Pattern Set\" section a bit\n + to include more examples as well.\n \n Signed-off-by: Elijah Newren \n \n ## Documentation/git-sparse-checkout.txt ##\n -@@ Documentation/git-sparse-checkout.txt: manually to ensure Git can behave optimally.\n - INTERNALS -- FULL PATTERN SET\n +@@ Documentation/git-sparse-checkout.txt: on this file. The files matching the patterns in the file will\n + appear in the working directory, and the rest will not.\n + \n + \n +-INTERNALS -- CONE PATTERN SET\n ++INTERNALS -- CONE MODE HANDLING\n ++-------------------------------\n ++\n ++The \"cone mode\", which is the default, lets you specify only what\n ++directories to include. For any directory specified, all paths below\n ++that directory will be included, and any paths immediately under\n ++leading directories (including the toplevel directory) will also be\n ++included. Thus, if you specified the directory\n ++ Documentation/technical/\n ++then your sparse checkout would contain:\n ++\n ++ * all files in the toplevel-directory\n ++ * all files immediately under Documentation/\n ++ * all files at any depth under Documentation/technical/\n ++\n ++Also, in cone mode, even if no directories are specified, then the\n ++files in the toplevel directory will be included.\n ++\n ++When changing the sparse-checkout patterns in cone mode, Git will inspect each\n ++tracked directory that is not within the sparse-checkout cone to see if it\n ++contains any untracked files. If all of those files are ignored due to the\n ++`.gitignore` patterns, then the directory will be deleted. If any of the\n ++untracked files within that directory is not ignored, then no deletions will\n ++occur within that directory and a warning message will appear. If these files\n ++are important, then reset your sparse-checkout definition so they are included,\n ++use `git add` and `git commit` to store them, then remove any remaining files\n ++manually to ensure Git can behave optimally.\n ++\n ++See also the \"Internals -- Cone Pattern Set\" section to learn how the\n ++directories are transformed under the hood into a subset of the\n ++Full Pattern Set of sparse-checkout.\n ++\n ++\n ++INTERNALS -- FULL PATTERN SET\n -----------------------------\n \n --By default, the sparse-checkout file uses the same syntax as `.gitignore`\n --files.\n --\n --While `$GIT_DIR/info/sparse-checkout` is usually used to specify what\n --files are included, you can also specify what files are _not_ included,\n --using negative patterns. For example, to remove the file `unwanted`:\n -+As noted above, the sparse-checkout file uses the same syntax as\n -+`.gitignore` files; see linkgit:gitignore[5] for details. Here,\n -+though, the patterns are usually being used to select which files to\n -+include rather than which files to exclude. (However, it can get a\n -+bit confusing since gitignore-style patterns have negations defined by\n -+patterns which begin with a '!', so you can also select files to _not_\n -+include.)\n + The full pattern set allows for arbitrary pattern matches and complicated\n +@@ Documentation/git-sparse-checkout.txt: updating the index, where N is the number of patterns and M is the number\n + of paths in the index. To combat this performance issue, a more restricted\n + pattern set is allowed when `core.sparseCheckoutCone` is enabled.\n + \n +-The accepted patterns in the cone pattern set are:\n ++The sparse-checkout file uses the same syntax as `.gitignore` files;\n ++see linkgit:gitignore[5] for details. Here, though, the patterns are\n ++usually being used to select which files to include rather than which\n ++files to exclude. (However, it can get a bit confusing since\n ++gitignore-style patterns have negations defined by patterns which\n ++begin with a '!', so you can also select files to _not_ include.)\n +\n +For example, to select everything, and then to remove the file\n +`unwanted` (so that every file will appear in your working tree except\n @@ Documentation/git-sparse-checkout.txt: manually to ensure Git can behave optimal\n +These patterns are just placed into the\n +`$GIT_DIR/info/sparse-checkout` as-is, so the contents of that file\n +at this point would be\n ++\n ++----------------\n ++/*\n ++!unwanted\n ++----------------\n ++\n ++See also the \"Sparse Checkout\" section of linkgit:git-read-tree[1] to\n ++learn more about the gitignore-style patterns used in sparse\n ++checkouts.\n ++\n ++\n ++INTERNALS -- CONE PATTERN SET\n ++-----------------------------\n ++\n ++In cone mode, only directories are accepted, but they are translated into\n ++the same gitignore-style patterns used in the full pattern set. We refer\n ++to the particular patterns used in those mode as being of one of two types:\n + \n + 1. *Recursive:* All paths inside a directory are included.\n + \n + 2. *Parent:* All files immediately inside a directory are included.\n + \n +-In addition to the above two patterns, we also expect that all files in the\n +-root directory are included. If a recursive pattern is added, then all\n +-leading directories are added as parent patterns.\n +-\n +-By default, when running `git sparse-checkout set` with no directories\n +-specified, the root directory is added as a parent pattern. At this\n +-point, the sparse-checkout file contains the following patterns:\n ++Since cone mode always includes files at the toplevel, when running\n ++`git sparse-checkout set` with no directories specified, the toplevel\n ++directory is added as a parent pattern. At this point, the\n ++sparse-checkout file contains the following patterns:\n + \n + ----------------\n + /*\n + !/*/\n + ----------------\n + \n +-This says \"include everything in root, but nothing two levels below root.\"\n ++This says \"include everything immediately under the toplevel\n ++directory, but nothing at any level below that.\"\n + \n +-When in cone mode, the `git sparse-checkout set` subcommand takes a list of\n +-directories. In this mode, the command `git sparse-checkout set A/B/C` sets\n +-the directory `A/B/C` as a recursive pattern, the directories `A` and `A/B`\n +-are added as parent patterns. The resulting sparse-checkout file is now\n ++When in cone mode, the `git sparse-checkout set` subcommand takes a\n ++list of directories. The command `git sparse-checkout set A/B/C` sets\n ++the directory `A/B/C` as a recursive pattern, the directories `A` and\n ++`A/B` are added as parent patterns. The resulting sparse-checkout file\n ++is now\n \n ----------------\n /*\n +@@ Documentation/git-sparse-checkout.txt: Unless `core.sparseCheckoutCone` is explicitly set to `false`, Git will\n + parse the sparse-checkout file expecting patterns of these types. Git will\n + warn if the patterns do not match. If the patterns do match the expected\n + format, then Git will use faster hash-based algorithms to compute inclusion\n +-in the sparse-checkout.\n ++in the sparse-checkout. If they do not match, git will behave as though\n ++`core.sparseCheckoutCone` was false, regardless of its setting.\n + \n +-In the cone mode case, the `git sparse-checkout list` subcommand will list the\n +-directories that define the recursive patterns. For the example sparse-checkout\n +-file above, the output is as follows:\n ++In the cone mode case, despite the fact that full patterns are written\n ++to the $GIT_DIR/info/sparse-checkout file, the `git sparse-checkout\n ++list` subcommand will list the directories that define the recursive\n ++patterns. For the example sparse-checkout file above, the output is as\n ++follows:\n + \n + --------------------------\n + $ git sparse-checkout list\n +@@ Documentation/git-sparse-checkout.txt: case-insensitive check. This corrects for case mismatched filenames in the\n + 'git sparse-checkout set' command to reflect the expected cone in the working\n + directory.\n + \n +-When changing the sparse-checkout patterns in cone mode, Git will inspect each\n +-tracked directory that is not within the sparse-checkout cone to see if it\n +-contains any untracked files. If all of those files are ignored due to the\n +-`.gitignore` patterns, then the directory will be deleted. If any of the\n +-untracked files within that directory is not ignored, then no deletions will\n +-occur within that directory and a warning message will appear. If these files\n +-are important, then reset your sparse-checkout definition so they are included,\n +-use `git add` and `git commit` to store them, then remove any remaining files\n +-manually to ensure Git can behave optimally.\n +-\n +-\n +-INTERNALS -- FULL PATTERN SET\n +------------------------------\n +-\n +-By default, the sparse-checkout file uses the same syntax as `.gitignore`\n +-files.\n +-\n +-While `$GIT_DIR/info/sparse-checkout` is usually used to specify what\n +-files are included, you can also specify what files are _not_ included,\n +-using negative patterns. For example, to remove the file `unwanted`:\n +-\n +-----------------\n +-/*\n +-!unwanted\n +-----------------\n +-\n + \n + INTERNALS -- SUBMODULES\n + -----------------------\n 8: 2d2b81986a5 ! 8: a1b68fd6126 git-sparse-checkout.txt: mark non-cone mode as deprecated\n @@ Documentation/git-sparse-checkout.txt: and `--cone` needed to be specified or `c\n When `--no-cone` is passed, the input list is considered a list of\n -patterns. This mode is harder to use and less performant, and is thus\n -not recommended. See the \"Sparse Checkout\" section of\n --linkgit:git-read-tree[1] and the \"Pattern Set\" sections below for more\n --details.\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 +-linkgit:git-read-tree[1] and the \"Internals...Pattern Set\" sections\n +-below for more details.\n ++patterns. This mode has a number of drawbacks, including not working\n ++with some options like `--sparse-index`. As explained in the\n ++\"Non-cone Problems\" section below, we do not recommend using it.\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 @@ Documentation/git-sparse-checkout.txt: directory, it updates the skip-worktree b\n + * Passing globs on the command line is error-prone as users may\n + forget to quote the glob, causing the shell to expand it into all\n + matching files and pass them all individually along to\n -+ sparse-checkout set/add. This both exacerbates the scaling\n -+ problem, and hardcodes the list of selected files to those which\n -+ were present at the time the initial set/add subcommand was run\n -+ (and thus ignoring other files matching the same glob which come\n -+ into the working tree after switching branches or pulling down\n -+ updates).\n ++ sparse-checkout set/add. While this could also be a problem with\n ++ e.g. \"git grep -- *.c\", mistakes with grep/log/status appear in\n ++ the immediate output. With sparse-checkout, the mistake gets\n ++ recorded at the time the sparse-checkout command is run and might\n ++ not be problematic until the user later switches branches or rebases\n ++ or merges, thus putting a delay between the user's error and when\n ++ they have a chance to catch/notice it.\n +\n -+ * It uses \"ignore\"/\"exclude\" syntax for selecting what to \"include\",\n -+ which periodically causes confusion.\n ++ * Related to the previous item, sparse-checkout has an 'add'\n ++ subcommand but no 'remove' subcommand. Even if a 'remove'\n ++ subcommand were added, undoing an accidental unquoted glob runs\n ++ the risk of \"removing too much\", as it may remove entries that had\n ++ been included before the accidental add.\n +\n -+ * It introduces inconsistencies in the Git command line, since other\n -+ commands use pathspecs, but sparse-checkout (in non-cone mode) uses\n -+ gitignore patterns.\n ++ * Non-cone mode uses gitignore-style patterns to select what to\n ++ *include* (with the exception of negated patterns), while\n ++ .gitignore files use gitignore-style patterns to select what to\n ++ *exclude* (with the exception of negated patterns). The\n ++ documentation on gitignore-style patterns usually does not talk in\n ++ terms of matching or non-matching, but on what the user wants to\n ++ \"exclude\". This can cause confusion for users trying to learn how\n ++ to specify sparse-checkout patterns to get their desired behavior.\n ++\n ++ * Every other git subcommand that wants to provide \"special path\n ++ pattern matching\" of some sort uses pathspecs, but non-cone mode\n ++ for sparse-checkout uses gitignore patterns, which feels\n ++ inconsistent.\n +\n + * It has edge cases where the \"right\" behavior is unclear. Two examples:\n +\n @@ Documentation/git-sparse-checkout.txt: directory, it updates the skip-worktree b\n + all these cases.\n +\n + * The excessive flexibility made other extensions essentially\n -+ impractical. `--sparse-index` may not have been feasible in\n -+ non-cone mode, but even if it was, it would have been far more work\n -+ to implement and may have been too slow in practice. Some ideas for\n -+ adding coupling between partial clones and sparse checkouts are only\n -+ practical with a more restricted set of paths.\n ++ impractical. `--sparse-index` is likely impossible in non-cone\n ++ mode; even if it is somehow feasible, it would have been far more\n ++ work to implement and may have been too slow in practice. Some\n ++ ideas for adding coupling between partial clones and sparse\n ++ checkouts are only practical with a more restricted set of paths\n ++ as well.\n +\n +For all these reasons, non-cone mode is deprecated. Please switch to\n +using cone mode.\n ++\n \n - INTERNALS -- CONE PATTERN SET\n - -----------------------------\n + INTERNALS -- CONE MODE HANDLING\n + -------------------------------\n 9: 4b89a3392b0 ! 9: 5f0e80777de Documentation: some sparsity wording clarifications\n @@ Documentation/git-read-tree.txt: have finished your work-in-progress), attempt t\n +and `read-tree` predated the introduction of\n +linkgit:git-sparse-checkout[1]. Users are encouraged to use the\n +`sparse-checkout` command in preference to these plumbing commands for\n -+sparse-checkout/skip-worktree related needs.\n ++sparse-checkout/skip-worktree related needs. However, the information\n ++below might be useful to users trying to understand the pattern style\n ++used in non-cone mode of the `sparse-checkout` command.\n \n \"Sparse checkout\" allows populating the working directory sparsely.\n It uses the skip-worktree bit (see linkgit:git-update-index[1]) to\n\n-- \ngitgitgadget\n"},{"id":"454214","messageId":"b1e2c95a2780ee7afb81cdc8d9262da3ca12a59a.1650594746.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.v3.git.1650594746.gitgitgadget@gmail.com","subject":"[PATCH v3 3/9] git-sparse-checkout.txt: wording updates for the cone mode default","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-04-22T02:32:20Z","receivedAt":"2022-04-22T02:32:48Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nNow that cone mode is the default, we'd like to focus on the arguments\nto set/add being directories rather than patterns, and it probably makes\nsense to provide an earlier heads up that files from leading directories\nget included as well.\n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-sparse-checkout.txt | 31 +++++++++++++--------------\n 1 file changed, 15 insertions(+), 16 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 7308e744c57..b5db812f09e 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -44,9 +44,9 @@ COMMANDS\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-\tand write a set of patterns to the sparse-checkout file from the\n-\tlist of arguments following the 'set' subcommand. Update the\n-\tworking directory to match the new patterns.\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@@ -60,15 +60,15 @@ 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-When `--cone` is passed or `core.sparseCheckoutCone` is not false, the\n-input list is considered a list of directories. This allows for\n-better performance with a limited set of patterns (see 'CONE PATTERN\n-SET' below). The input format matches the output of `git ls-tree\n---name-only`. This includes interpreting pathnames that begin with a\n-double quote (\") as C-style quoted strings. Note that the set command\n-will write patterns to the sparse-checkout file to include all files\n-contained in those directories (recursively) as well as files that are\n-siblings of ancestor directories.\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 or `core.sparseCheckoutCone` is set to false,\n the input list is considered a list of patterns. This mode is harder\n@@ -208,10 +208,9 @@ the following patterns:\n This says \"include everything in root, but nothing two levels below root.\"\n \n When in cone mode, the `git sparse-checkout set` subcommand takes a list of\n-directories instead of a list of sparse-checkout patterns. In this mode,\n-the command `git sparse-checkout set A/B/C` sets the directory `A/B/C` as\n-a recursive pattern, the directories `A` and `A/B` are added as parent\n-patterns. The resulting sparse-checkout file is now\n+directories. In this mode, the command `git sparse-checkout set A/B/C` sets\n+the directory `A/B/C` as a recursive pattern, the directories `A` and `A/B`\n+are added as parent patterns. The resulting sparse-checkout file is now\n \n ----------------\n /*\n-- \ngitgitgadget\n\n"},{"id":"454215","messageId":"b0b57cd37e7c2044ff64d8432e821a4350a174ad.1650594746.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.v3.git.1650594746.gitgitgadget@gmail.com","subject":"[PATCH v3 4/9] git-sparse-checkout.txt: update docs for deprecation of 'init'","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-04-22T02:32:21Z","receivedAt":"2022-04-22T02:32:53Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nThe 'init' subcommand of sparse-checkout was deprecated in ba2f3f58ac\n(\"git-sparse-checkout.txt: update to document init/set/reapply changes\",\n2021-12-14), but a couple places in the manual still assumed it was the\nprimary way to use sparse-checkout. Correct them.\n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-sparse-checkout.txt | 16 ++++++++--------\n 1 file changed, 8 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex b5db812f09e..8e80d1c7332 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -70,11 +70,11 @@ 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 or `core.sparseCheckoutCone` is set to false,\n-the input list is considered a list of patterns. This mode is harder\n-to use and less performant, and is thus not recommended. See the\n-\"Sparse Checkout\" section of linkgit:git-read-tree[1] and the \"Pattern\n-Set\" sections below for more details.\n+When `--no-cone` is passed, the input list is considered a list of\n+patterns. This mode is harder to use and less performant, and is thus\n+not recommended. See the \"Sparse Checkout\" section of\n+linkgit:git-read-tree[1] and the \"Pattern Set\" sections below for more\n+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@@ -196,9 +196,9 @@ In addition to the above two patterns, we also expect that all files in the\n root directory are included. If a recursive pattern is added, then all\n leading directories are added as parent patterns.\n \n-By default, when running `git sparse-checkout init`, the root directory is\n-added as a parent pattern. At this point, the sparse-checkout file contains\n-the following patterns:\n+By default, when running `git sparse-checkout set` with no directories\n+specified, the root directory is added as a parent pattern. At this\n+point, the sparse-checkout file contains the following patterns:\n \n ----------------\n /*\n-- \ngitgitgadget\n\n"},{"id":"454216","messageId":"eda0f41395b28b309ea15fa2927ac6ad867f97ed.1650594746.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.v3.git.1650594746.gitgitgadget@gmail.com","subject":"[PATCH v3 5/9] git-sparse-checkout.txt: shuffle some sections and mark as internal","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-04-22T02:32:22Z","receivedAt":"2022-04-22T02:32:55Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nWith cone mode as the default, it makes sense to discuss it before\nnon-cone mode. Also, the new default means we can just use directories\nin most cases and users do not need to understand patterns or their\nmeanings. Let's take advantage of this to mark several sections as\n\"INTERNALS\", notifying the user that they do not need to know all those\ndetails in order to make use of the sparse-checkout command.\n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-sparse-checkout.txt | 48 +++++++++++++--------------\n 1 file changed, 24 insertions(+), 24 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 8e80d1c7332..2083e6df356 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -73,8 +73,8 @@ to be enabled.\n When `--no-cone` is passed, the input list is considered a list of\n patterns. This mode is harder to use and less performant, and is thus\n not recommended. See the \"Sparse Checkout\" section of\n-linkgit:git-read-tree[1] and the \"Pattern Set\" sections below for more\n-details.\n+linkgit:git-read-tree[1] and the \"Internals...Pattern Set\" sections\n+below 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@@ -136,8 +136,8 @@ 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-SPARSE CHECKOUT\n----------------\n+INTERNALS -- SPARSE CHECKOUT\n+----------------------------\n \n \"Sparse checkout\" allows populating the working directory sparsely. It\n uses the skip-worktree bit (see linkgit:git-update-index[1]) to tell Git\n@@ -161,24 +161,8 @@ To repopulate the working directory with all files, use the\n `git sparse-checkout disable` command.\n \n \n-FULL PATTERN SET\n-----------------\n-\n-By default, the sparse-checkout file uses the same syntax as `.gitignore`\n-files.\n-\n-While `$GIT_DIR/info/sparse-checkout` is usually used to specify what\n-files are included, you can also specify what files are _not_ included,\n-using negative patterns. For example, to remove the file `unwanted`:\n-\n-----------------\n-/*\n-!unwanted\n-----------------\n-\n-\n-CONE PATTERN SET\n-----------------\n+INTERNALS -- CONE PATTERN SET\n+-----------------------------\n \n The full pattern set allows for arbitrary pattern matches and complicated\n inclusion/exclusion rules. These can result in O(N*M) pattern matches when\n@@ -256,8 +240,24 @@ use `git add` and `git commit` to store them, then remove any remaining files\n manually to ensure Git can behave optimally.\n \n \n-SUBMODULES\n-----------\n+INTERNALS -- FULL PATTERN SET\n+-----------------------------\n+\n+By default, the sparse-checkout file uses the same syntax as `.gitignore`\n+files.\n+\n+While `$GIT_DIR/info/sparse-checkout` is usually used to specify what\n+files are included, you can also specify what files are _not_ included,\n+using negative patterns. For example, to remove the file `unwanted`:\n+\n+----------------\n+/*\n+!unwanted\n+----------------\n+\n+\n+INTERNALS -- SUBMODULES\n+-----------------------\n \n If your repository contains one or more submodules, then submodules\n are populated based on interactions with the `git submodule` command.\n-- \ngitgitgadget\n\n"},{"id":"454217","messageId":"5f0e80777de6d4dcb245f3f0281cd31cac497cbc.1650594746.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.v3.git.1650594746.gitgitgadget@gmail.com","subject":"[PATCH v3 9/9] Documentation: some sparsity wording clarifications","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-04-22T02:32:26Z","receivedAt":"2022-04-22T02:32:57Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nImprove the wording for a couple paragraphs in two different manuals\nrelating to sparse behavior.\n\nReported-by: Ævar Arnfjörð Bjarmason \nSigned-off-by: Elijah Newren \n---\n Documentation/git-read-tree.txt | 11 +++++++----\n Documentation/git-sparse-checkout.txt | 10 +++++-----\n 2 files changed, 12 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\nindex 99bb387134d..d255807798c 100644\n--- a/Documentation/git-read-tree.txt\n+++ b/Documentation/git-read-tree.txt\n@@ -375,10 +375,13 @@ have finished your work-in-progress), attempt the merge again.\n SPARSE CHECKOUT\n ---------------\n \n-Note: The `update-index` and `read-tree` primitives for supporting the\n-skip-worktree bit predated the introduction of\n-linkgit:git-sparse-checkout[1]. Users are encouraged to use\n-`sparse-checkout` in preference to these low-level primitives.\n+Note: The skip-worktree capabilities in linkgit:git-update-index[1]\n+and `read-tree` predated the introduction of\n+linkgit:git-sparse-checkout[1]. Users are encouraged to use the\n+`sparse-checkout` command in preference to these plumbing commands for\n+sparse-checkout/skip-worktree related needs. However, the information\n+below might be useful to users trying to understand the pattern style\n+used in non-cone mode of the `sparse-checkout` command.\n \n \"Sparse checkout\" allows populating the working directory sparsely.\n It uses the skip-worktree bit (see linkgit:git-update-index[1]) to\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex c65d0ce96bb..3776705bf53 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -15,11 +15,11 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-This command is used to create sparse checkouts, which means that it\n-changes the working tree from having all tracked files present, to only\n-have a subset of them. It can also switch which subset of files are\n-present, or undo and go back to having all tracked files present in the\n-working copy.\n+This command is used to create sparse checkouts, which change the\n+working tree from having all tracked files present to only having a\n+subset of those files. It can also switch which subset of files are\n+present, or undo and go back to having all tracked files present in\n+the working copy.\n \n The subset of files is chosen by providing a list of directories in\n cone mode (the default), or by providing a list of patterns in\n-- \ngitgitgadget\n"},{"id":"454218","messageId":"a1b68fd6126eb341ef3637bb93fedad4309b36d0.1650594746.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.v3.git.1650594746.gitgitgadget@gmail.com","subject":"[PATCH v3 8/9] git-sparse-checkout.txt: mark non-cone mode as deprecated","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-04-22T02:32:25Z","receivedAt":"2022-04-22T02:32:58Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nWhile we have no current plans to actually remove --no-cone mode, we\nthink users would be better off not using it. Update the documentation\naccordingly, including explaining why we think non-cone mode is\nproblematic for users.\n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-sparse-checkout.txt | 98 +++++++++++++++++++++++++--\n 1 file changed, 94 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 6e32034511d..c65d0ce96bb 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -71,10 +71,9 @@ 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 less performant, and is thus\n-not recommended. See the \"Sparse Checkout\" section of\n-linkgit:git-read-tree[1] and the \"Internals...Pattern Set\" sections\n-below for more details.\n+patterns. This mode has a number of drawbacks, including not working\n+with some options like `--sparse-index`. As explained in the\n+\"Non-cone Problems\" section below, we do not recommend using it.\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@@ -191,6 +190,97 @@ directory, it updates the skip-worktree bits in the index based\n on this file. The files matching the patterns in the file will\n appear in the working directory, and the rest will not.\n \n+INTERNALS -- NON-CONE PROBLEMS\n+------------------------------\n+\n+The `$GIT_DIR/info/sparse-checkout` file populated by the `set` and\n+`add` subcommands is defined to be a bunch of patterns (one per line)\n+using the same syntax as `.gitignore` files. In cone mode, these\n+patterns are restricted to matching directories (and users only ever\n+need supply or see directory names), while in non-cone mode any\n+gitignore-style pattern is permitted. Using the full gitignore-style\n+patterns in non-cone mode has a number of shortcomings:\n+\n+ * Fundamentally, it makes various worktree-updating processes (pull,\n+ merge, rebase, switch, reset, checkout, etc.) require O(N*M) pattern\n+ matches, where N is the number of patterns and M is the number of\n+ paths in the index. This scales poorly.\n+\n+ * Avoiding the scaling issue has to be done via limiting the number\n+ of patterns via specifying leading directory name or glob.\n+\n+ * Passing globs on the command line is error-prone as users may\n+ forget to quote the glob, causing the shell to expand it into all\n+ matching files and pass them all individually along to\n+ sparse-checkout set/add. While this could also be a problem with\n+ e.g. \"git grep -- *.c\", mistakes with grep/log/status appear in\n+ the immediate output. With sparse-checkout, the mistake gets\n+ recorded at the time the sparse-checkout command is run and might\n+ not be problematic until the user later switches branches or rebases\n+ or merges, thus putting a delay between the user's error and when\n+ they have a chance to catch/notice it.\n+\n+ * Related to the previous item, sparse-checkout has an 'add'\n+ subcommand but no 'remove' subcommand. Even if a 'remove'\n+ subcommand were added, undoing an accidental unquoted glob runs\n+ the risk of \"removing too much\", as it may remove entries that had\n+ been included before the accidental add.\n+\n+ * Non-cone mode uses gitignore-style patterns to select what to\n+ *include* (with the exception of negated patterns), while\n+ .gitignore files use gitignore-style patterns to select what to\n+ *exclude* (with the exception of negated patterns). The\n+ documentation on gitignore-style patterns usually does not talk in\n+ terms of matching or non-matching, but on what the user wants to\n+ \"exclude\". This can cause confusion for users trying to learn how\n+ to specify sparse-checkout patterns to get their desired behavior.\n+\n+ * Every other git subcommand that wants to provide \"special path\n+ pattern matching\" of some sort uses pathspecs, but non-cone mode\n+ for sparse-checkout uses gitignore patterns, which feels\n+ inconsistent.\n+\n+ * It has edge cases where the \"right\" behavior is unclear. Two examples:\n+\n+ First, two users are in a subdirectory, and the first runs\n+ git sparse-checkout set '/toplevel-dir/*.c'\n+ while the second runs\n+ git sparse-checkout set relative-dir\n+ Should those arguments be transliterated into\n+ current/subdirectory/toplevel-dir/*.c\n+ and\n+ current/subdirectory/relative-dir\n+ before inserting into the sparse-checkout file? The user who typed\n+ the first command is probably aware that arguments to set/add are\n+ supposed to be patterns in non-cone mode, and probably would not be\n+ happy with such a transliteration. However, many gitignore-style\n+ patterns are just paths, which might be what the user who typed the\n+ second command was thinking, and they'd be upset if their argument\n+ wasn't transliterated.\n+\n+ Second, what should bash-completion complete on for set/add commands\n+ for non-cone users? If it suggests paths, is it exacerbating the\n+ problem above? Also, if it suggests paths, what if the user has a\n+ file or directory that begins with either a '!' or '#' or has a '*',\n+ '\\', '?', '[', or ']' in its name? And if it suggests paths, will\n+ it complete \"/pro\" to \"/proc\" (in the root filesytem) rather than to\n+ \"/progress.txt\" in the current directory? (Note that users are\n+ likely to want to start paths with a leading '/' in non-cone mode,\n+ for the same reason that .gitignore files often have one.)\n+ Completing on files or directories might give nasty surprises in\n+ all these cases.\n+\n+ * The excessive flexibility made other extensions essentially\n+ impractical. `--sparse-index` is likely impossible in non-cone\n+ mode; even if it is somehow feasible, it would have been far more\n+ work to implement and may have been too slow in practice. Some\n+ ideas for adding coupling between partial clones and sparse\n+ checkouts are only practical with a more restricted set of paths\n+ as well.\n+\n+For all these reasons, non-cone mode is deprecated. Please switch to\n+using cone mode.\n+\n \n INTERNALS -- CONE MODE HANDLING\n -------------------------------\n-- \ngitgitgadget\n\n"},{"id":"454219","messageId":"546ae3d67326435c2b4a689f9217639bce660d88.1650594746.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.v3.git.1650594746.gitgitgadget@gmail.com","subject":"[PATCH v3 7/9] git-sparse-checkout.txt: flesh out pattern set sections a bit","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-04-22T02:32:24Z","receivedAt":"2022-04-22T02:33:00Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nThe \"Internals -- Cone Pattern Set\" section starts off discussing\npatterns, despite the fact that cone mode is about avoiding the\npatterns. This made sense back when non-cone mode was the default and\nwe started by discussing the full pattern set, but now that we are\nchanging the default, it makes more sense to discuss cone-mode first and\navoid the full discussion of patterns. Split this section into two, the\nfirst with details about how cone mode operates, and the second\nfollowing the full pattern set section and discussing how the cone mode\npatterns used under the hood relate to the full pattern set.\n\nWhile at it, flesh out the \"Internals -- Full Pattern Set\" section a bit\nto include more examples as well.\n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-sparse-checkout.txt | 129 +++++++++++++++++---------\n 1 file changed, 85 insertions(+), 44 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex c54437428bb..6e32034511d 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -192,7 +192,40 @@ on this file. The files matching the patterns in the file will\n appear in the working directory, and the rest will not.\n \n \n-INTERNALS -- CONE PATTERN SET\n+INTERNALS -- CONE MODE HANDLING\n+-------------------------------\n+\n+The \"cone mode\", which is the default, lets you specify only what\n+directories to include. For any directory specified, all paths below\n+that directory will be included, and any paths immediately under\n+leading directories (including the toplevel directory) will also be\n+included. Thus, if you specified the directory\n+ Documentation/technical/\n+then your sparse checkout would contain:\n+\n+ * all files in the toplevel-directory\n+ * all files immediately under Documentation/\n+ * all files at any depth under Documentation/technical/\n+\n+Also, in cone mode, even if no directories are specified, then the\n+files in the toplevel directory will be included.\n+\n+When changing the sparse-checkout patterns in cone mode, Git will inspect each\n+tracked directory that is not within the sparse-checkout cone to see if it\n+contains any untracked files. If all of those files are ignored due to the\n+`.gitignore` patterns, then the directory will be deleted. If any of the\n+untracked files within that directory is not ignored, then no deletions will\n+occur within that directory and a warning message will appear. If these files\n+are important, then reset your sparse-checkout definition so they are included,\n+use `git add` and `git commit` to store them, then remove any remaining files\n+manually to ensure Git can behave optimally.\n+\n+See also the \"Internals -- Cone Pattern Set\" section to learn how the\n+directories are transformed under the hood into a subset of the\n+Full Pattern Set of sparse-checkout.\n+\n+\n+INTERNALS -- FULL PATTERN SET\n -----------------------------\n \n The full pattern set allows for arbitrary pattern matches and complicated\n@@ -201,31 +234,62 @@ updating the index, where N is the number of patterns and M is the number\n of paths in the index. To combat this performance issue, a more restricted\n pattern set is allowed when `core.sparseCheckoutCone` is enabled.\n \n-The accepted patterns in the cone pattern set are:\n+The sparse-checkout file uses the same syntax as `.gitignore` files;\n+see linkgit:gitignore[5] for details. Here, though, the patterns are\n+usually being used to select which files to include rather than which\n+files to exclude. (However, it can get a bit confusing since\n+gitignore-style patterns have negations defined by patterns which\n+begin with a '!', so you can also select files to _not_ include.)\n+\n+For example, to select everything, and then to remove the file\n+`unwanted` (so that every file will appear in your working tree except\n+the file named `unwanted`):\n+\n+ git sparse-checkout set --no-cone '/*' '!unwanted'\n+\n+These patterns are just placed into the\n+`$GIT_DIR/info/sparse-checkout` as-is, so the contents of that file\n+at this point would be\n+\n+----------------\n+/*\n+!unwanted\n+----------------\n+\n+See also the \"Sparse Checkout\" section of linkgit:git-read-tree[1] to\n+learn more about the gitignore-style patterns used in sparse\n+checkouts.\n+\n+\n+INTERNALS -- CONE PATTERN SET\n+-----------------------------\n+\n+In cone mode, only directories are accepted, but they are translated into\n+the same gitignore-style patterns used in the full pattern set. We refer\n+to the particular patterns used in those mode as being of one of two types:\n \n 1. *Recursive:* All paths inside a directory are included.\n \n 2. *Parent:* All files immediately inside a directory are included.\n \n-In addition to the above two patterns, we also expect that all files in the\n-root directory are included. If a recursive pattern is added, then all\n-leading directories are added as parent patterns.\n-\n-By default, when running `git sparse-checkout set` with no directories\n-specified, the root directory is added as a parent pattern. At this\n-point, the sparse-checkout file contains the following patterns:\n+Since cone mode always includes files at the toplevel, when running\n+`git sparse-checkout set` with no directories specified, the toplevel\n+directory is added as a parent pattern. At this point, the\n+sparse-checkout file contains the following patterns:\n \n ----------------\n /*\n !/*/\n ----------------\n \n-This says \"include everything in root, but nothing two levels below root.\"\n+This says \"include everything immediately under the toplevel\n+directory, but nothing at any level below that.\"\n \n-When in cone mode, the `git sparse-checkout set` subcommand takes a list of\n-directories. In this mode, the command `git sparse-checkout set A/B/C` sets\n-the directory `A/B/C` as a recursive pattern, the directories `A` and `A/B`\n-are added as parent patterns. The resulting sparse-checkout file is now\n+When in cone mode, the `git sparse-checkout set` subcommand takes a\n+list of directories. The command `git sparse-checkout set A/B/C` sets\n+the directory `A/B/C` as a recursive pattern, the directories `A` and\n+`A/B` are added as parent patterns. The resulting sparse-checkout file\n+is now\n \n ----------------\n /*\n@@ -244,11 +308,14 @@ Unless `core.sparseCheckoutCone` is explicitly set to `false`, Git will\n parse the sparse-checkout file expecting patterns of these types. Git will\n warn if the patterns do not match. If the patterns do match the expected\n format, then Git will use faster hash-based algorithms to compute inclusion\n-in the sparse-checkout.\n+in the sparse-checkout. If they do not match, git will behave as though\n+`core.sparseCheckoutCone` was false, regardless of its setting.\n \n-In the cone mode case, the `git sparse-checkout list` subcommand will list the\n-directories that define the recursive patterns. For the example sparse-checkout\n-file above, the output is as follows:\n+In the cone mode case, despite the fact that full patterns are written\n+to the $GIT_DIR/info/sparse-checkout file, the `git sparse-checkout\n+list` subcommand will list the directories that define the recursive\n+patterns. For the example sparse-checkout file above, the output is as\n+follows:\n \n --------------------------\n $ git sparse-checkout list\n@@ -260,32 +327,6 @@ case-insensitive check. This corrects for case mismatched filenames in the\n 'git sparse-checkout set' command to reflect the expected cone in the working\n directory.\n \n-When changing the sparse-checkout patterns in cone mode, Git will inspect each\n-tracked directory that is not within the sparse-checkout cone to see if it\n-contains any untracked files. If all of those files are ignored due to the\n-`.gitignore` patterns, then the directory will be deleted. If any of the\n-untracked files within that directory is not ignored, then no deletions will\n-occur within that directory and a warning message will appear. If these files\n-are important, then reset your sparse-checkout definition so they are included,\n-use `git add` and `git commit` to store them, then remove any remaining files\n-manually to ensure Git can behave optimally.\n-\n-\n-INTERNALS -- FULL PATTERN SET\n------------------------------\n-\n-By default, the sparse-checkout file uses the same syntax as `.gitignore`\n-files.\n-\n-While `$GIT_DIR/info/sparse-checkout` is usually used to specify what\n-files are included, you can also specify what files are _not_ included,\n-using negative patterns. For example, to remove the file `unwanted`:\n-\n-----------------\n-/*\n-!unwanted\n-----------------\n-\n \n INTERNALS -- SUBMODULES\n -----------------------\n-- \ngitgitgadget\n\n"},{"id":"454220","messageId":"7908c8f83d85c5e0bfea8476f0d9577d41ccd82b.1650594746.git.gitgitgadget@gmail.com","threadId":"57519","inReplyTo":"pull.1148.v3.git.1650594746.gitgitgadget@gmail.com","subject":"[PATCH v3 6/9] git-sparse-checkout.txt: add a new EXAMPLES section","fromName":"Elijah Newren via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-04-22T02:32:23Z","receivedAt":"2022-04-22T02:33:01Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"From: Elijah Newren \n\nSince many users like to learn from examples, provide a section in the\nmanual with example commands that would be used and a brief explanation\nof what each does.\n\nSigned-off-by: Elijah Newren \n---\n Documentation/git-sparse-checkout.txt | 43 +++++++++++++++++++++++----\n 1 file changed, 37 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 2083e6df356..c54437428bb 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -136,6 +136,43 @@ 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+EXAMPLES\n+--------\n+`git sparse-checkout set MY/DIR1 SUB/DIR2`::\n+\n+\tChange to a sparse checkout with all files (at any depth) under\n+\tMY/DIR1/ and SUB/DIR2/ present in the working copy (plus all\n+\tfiles immediately under MY/ and SUB/ and the toplevel\n+\tdirectory). If already in a sparse checkout, change which files\n+\tare present in the working copy to this new selection. Note\n+\tthat this command will also delete all ignored files in any\n+\tdirectory that no longer has either tracked or\n+\tnon-ignored-untracked files present.\n+\n+`git sparse-checkout disable`::\n+\n+\tRepopulate the working directory with all files, disabling sparse\n+\tcheckouts.\n+\n+`git sparse-checkout add SOME/DIR/ECTORY`::\n+\n+\tAdd all files under SOME/DIR/ECTORY/ (at any depth) to the\n+\tsparse checkout, as well as all files immediately under\n+\tSOME/DIR/ and immediately under SOME/. Must already be in a\n+\tsparse checkout before using this command.\n+\n+`git sparse-checkout reapply`::\n+\n+\tIt is possible for commands to update the working tree in a\n+\tway that does not respect the selected sparsity directories.\n+\tThis can come from tools external to Git writing files, or\n+\teven affect Git commands because of either special cases (such\n+\tas hitting conflicts when merging/rebasing), or because some\n+\tcommands didn't fully support sparse checkouts (e.g. the old\n+\t`recursive` merge backend had only limited support). This\n+\tcommand reapplies the existing sparse directory specifications\n+\tto make the working directory match.\n+\n INTERNALS -- SPARSE CHECKOUT\n ----------------------------\n \n@@ -154,12 +191,6 @@ directory, it updates the skip-worktree bits in the index based\n on this file. The files matching the patterns in the file will\n appear in the working directory, and the rest will not.\n \n-To enable the sparse-checkout feature, run `git sparse-checkout set` to\n-set the patterns you want to use.\n-\n-To repopulate the working directory with all files, use the\n-`git sparse-checkout disable` command.\n-\n \n INTERNALS -- CONE PATTERN SET\n -----------------------------\n-- \ngitgitgadget\n\n"},{"id":"454223","messageId":"xmqqh76ld4za.fsf@gitster.g","threadId":"57519","inReplyTo":"CABPp-BEt0CzP7B_EvYXOhQoKqk+h=9OwXDmUDCYfB3fnHxv-uA@mail.gmail.com","subject":"Re: [PATCH v2 4/9] git-sparse-checkout.txt: update docs for deprecation of 'init'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-04-22T06:09:13Z","receivedAt":"2022-04-22T06:09:25Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Elijah Newren writes:\n\n>> less than ideal. As we present \"core\" first (because it is the\n>> default), we should present \"core\" by itself, without requiring to\n>> know what the other thing is.\n>\n> By '\"core\" section' do you mean the \"cone pattern set\" section?\n\ns/core/cone mode/g, I guess (because it is so long ago I do not\noffhand recall what I had in mind exactly back when I wrote it).\n"},{"id":"454386","messageId":"c64eb904-1524-c44d-4d1c-6289becebf63@github.com","threadId":"57519","inReplyTo":"pull.1148.v3.git.1650594746.gitgitgadget@gmail.com","subject":"Re: [PATCH v3 0/9] sparse-checkout: make cone mode the default","fromName":"Derrick Stolee","fromEmail":"derrickstolee@github.com","sentAt":"2022-04-25T14:38:45Z","receivedAt":"2022-04-25T14:38:55Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"On 4/21/2022 10:32 PM, Elijah Newren via GitGitGadget wrote:\n> Sorry for the long delay since v1. On the plus side, perhaps there will be a\n> longer feedback period for this series since it's now really early in the\n> 2.37 series?\n\nYes, a merge early in the cycle would be good for feedback, if any.\n\n> == Updates Log ==\n> \n> Changes since v2:\n> \n> * Code style tweak suggested by Junio in one area, reverting back to v1.\n> * Several documentation updates to address Junio's review. Patches 6 & 7\n> had significant changes and would most benefit from a further review.\n\nI took a quick scan of the range-diff, and read patches 6 and 7\non their own. This version looks good to me.\n\nThanks,\n-Stolee\n"}]}