[PATCH 0/9] sparse-checkout: make cone mode the default

[PATCH 0/9] sparse-checkout: make cone mode the default

[Elijah Newren via GitGitGadget]

== Maintainer Note ==

Depends on a merge of en/present-despite-skipped into master.

== Overview ==

This patch changes the default mode for sparse-checkout from non-cone mode
to cone-mode, and marks non-cone mode as deprecated. There is no plan to
remove non-cone mode, we are merely recommending against its use.

The code change is pretty small, and most of this series is about
documentation updates -- to focus on directories rather than patterns, to
explain the new default, to explain why we are deprecating non-cone mode
(the final patch), and to make other related cleanups to simplify the
manual.

Patch 1: Update tests to not assume cone-mode is the default Patch 2: Make
cone-mode the default Patches 3-9: Various updates to
git-sparse-checkout.txt, divided up for ease of review

== Alternative ==

There is one primary alternative to this series: make sparse-checkout error
when neither --cone nor --no-cone are specified (so that there is no
default), and wait until a future date to make --cone the default. That'd be
reasonable, but I had three reason to avoid going this route (note that item
2 means there's little practical difference between cone-mode-as-default and
no-mode-is-default):

 1. git-sparse-checkout.txt has the following huge warning early in the
    manual:

""" THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR, AND THE BEHAVIOR OF OTHER
COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN THE
FUTURE. """

 2. If users are unaware of the default change and attempt to provide
    patterns instead of directories, then they will get error messages added
    from en/sparse-checkout-fixes. They can learn at that time to get around
    the error messages by providing --no-cone.

 3. If users are unaware of the default change and provide directories, then
    that's where non-cone mode and cone mode overlap and things happen to
    work. (There is a slight difference in that cone mode will include files
    from parent directories of any specified directory, but that means the
    user gets a few more files in their sparse-checkout with cone mode than
    they would with non-cone mode.)

== CCs ==

Elijah Newren (9):
  tests: stop assuming --no-cone is the default mode for sparse-checkout
  sparse-checkout: make --cone the default
  git-sparse-checkout.txt: wording updates for the cone mode default
  git-sparse-checkout.txt: update docs for deprecation of 'init'
  git-sparse-checkout.txt: shuffle some sections and mark as internal
  git-sparse-checkout.txt: add a new EXAMPLES section
  git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a
    bit
  git-sparse-checkout.txt: mark non-cone mode as deprecated
  Documentation: some sparsity wording clarifications

 Documentation/git-read-tree.txt       |   9 +-
 Documentation/git-sparse-checkout.txt | 248 +++++++++++++++++++-------
 builtin/sparse-checkout.c             |   2 +-
 t/t1091-sparse-checkout-builtin.sh    |  15 +-
 t/t3602-rm-sparse-checkout.sh         |   6 +-
 t/t3705-add-sparse-checkout.sh        |   4 +-
 t/t6428-merge-conflicts-sparse.sh     |   4 +-
 t/t7002-mv-sparse-checkout.sh         |   2 +-
 t/t7012-skip-worktree-writing.sh      |   2 +-
 9 files changed, 206 insertions(+), 86 deletions(-)


base-commit: af002ccf9fe2ce6cce9111323423f1d4739bcf0d
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1148%2Fnewren%2Fsparse-checkout-default-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1148/newren/sparse-checkout-default-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1148
-- 
gitgitgadget

[PATCH 1/9] tests: stop assuming --no-cone is the default mode for sparse-checkout

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

Add an explicit --no-cone to several sparse-checkout invocations in
preparation for changing the default to cone mode.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
 t/t1091-sparse-checkout-builtin.sh | 15 ++++++++-------
 t/t3602-rm-sparse-checkout.sh      |  6 +++---
 t/t3705-add-sparse-checkout.sh     |  4 ++--
 t/t6428-merge-conflicts-sparse.sh  |  4 ++--
 t/t7002-mv-sparse-checkout.sh      |  2 +-
 t/t7012-skip-worktree-writing.sh   |  2 +-
 6 files changed, 17 insertions(+), 16 deletions(-)

diff --git a/t/t1091-sparse-checkout-builtin.sh b/t/t1091-sparse-checkout-builtin.sh
index 9a900310186..de1ec89007d 100755
--- a/t/t1091-sparse-checkout-builtin.sh
+++ b/t/t1091-sparse-checkout-builtin.sh
@@ -72,7 +72,7 @@ test_expect_success 'git sparse-checkout list (populated)' '
 '
 
 test_expect_success 'git sparse-checkout init' '
-	git -C repo sparse-checkout init &&
+	git -C repo sparse-checkout init --no-cone &&
 	cat >expect <<-\EOF &&
 	/*
 	!/*/
@@ -111,6 +111,7 @@ test_expect_success 'init with existing sparse-checkout' '
 
 test_expect_success 'clone --sparse' '
 	git clone --sparse "file://$(pwd)/repo" clone &&
+	git -C clone sparse-checkout reapply --no-cone &&
 	git -C clone sparse-checkout list >actual &&
 	cat >expect <<-\EOF &&
 	/*
@@ -124,7 +125,7 @@ test_expect_success 'switching to cone mode with non-cone mode patterns' '
 	git init bad-patterns &&
 	(
 		cd bad-patterns &&
-		git sparse-checkout init &&
+		git sparse-checkout init --no-cone &&
 		git sparse-checkout add dir &&
 		git config --worktree core.sparseCheckoutCone true &&
 		test_must_fail git sparse-checkout add dir 2>err &&
@@ -402,7 +403,7 @@ test_expect_success 'revert to old sparse-checkout on empty update' '
 		git sparse-checkout set nothing 2>err &&
 		test_i18ngrep ! "Sparse checkout leaves no entry on working directory" err &&
 		test_i18ngrep ! ".git/index.lock" err &&
-		git sparse-checkout set file
+		git sparse-checkout set --no-cone file
 	)
 '
 
@@ -424,7 +425,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with dirty status'
 	git clone repo dirty &&
 	echo dirty >dirty/folder1/a &&
 
-	git -C dirty sparse-checkout init 2>err &&
+	git -C dirty sparse-checkout init --no-cone 2>err &&
 	test_i18ngrep "warning.*The following paths are not up to date" err &&
 
 	git -C dirty sparse-checkout set /folder2/* /deep/deeper1/* 2>err &&
@@ -435,7 +436,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with dirty status'
 	test_must_be_empty err &&
 
 	git -C dirty reset --hard &&
-	git -C dirty sparse-checkout init &&
+	git -C dirty sparse-checkout init --no-cone &&
 	git -C dirty sparse-checkout set /folder2/* /deep/deeper1/* &&
 	test_path_is_missing dirty/folder1/a &&
 	git -C dirty sparse-checkout disable &&
@@ -451,7 +452,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with unmerged stat
 	EOF
 	git -C unmerged update-index --index-info <input &&
 
-	git -C unmerged sparse-checkout init 2>err &&
+	git -C unmerged sparse-checkout init --no-cone 2>err &&
 	test_i18ngrep "warning.*The following paths are unmerged" err &&
 
 	git -C unmerged sparse-checkout set /folder2/* /deep/deeper1/* 2>err &&
@@ -462,7 +463,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with unmerged stat
 	test_i18ngrep "warning.*The following paths are unmerged" err &&
 
 	git -C unmerged reset --hard &&
-	git -C unmerged sparse-checkout init &&
+	git -C unmerged sparse-checkout init --no-cone &&
 	git -C unmerged sparse-checkout set /folder2/* /deep/deeper1/* &&
 	git -C unmerged sparse-checkout disable
 '
diff --git a/t/t3602-rm-sparse-checkout.sh b/t/t3602-rm-sparse-checkout.sh
index 034ec010910..08580fd3dcc 100755
--- a/t/t3602-rm-sparse-checkout.sh
+++ b/t/t3602-rm-sparse-checkout.sh
@@ -30,7 +30,7 @@ test_expect_success 'setup' "
 for opt in "" -f --dry-run
 do
 	test_expect_success "rm${opt:+ $opt} does not remove sparse entries" '
-		git sparse-checkout set a &&
+		git sparse-checkout set --no-cone a &&
 		test_must_fail git rm $opt b 2>stderr &&
 		test_cmp b_error_and_hint stderr &&
 		git ls-files --error-unmatch b
@@ -118,7 +118,7 @@ test_expect_success 'can remove files from non-sparse dir' '
 	test_commit w/f &&
 	test_commit x/y/f &&
 
-	git sparse-checkout set w !/x y/ &&
+	git sparse-checkout set --no-cone w !/x y/ &&
 	git rm w/f.t x/y/f.t 2>stderr &&
 	test_must_be_empty stderr
 '
@@ -128,7 +128,7 @@ test_expect_success 'refuse to remove non-skip-worktree file from sparse dir' '
 	git sparse-checkout disable &&
 	mkdir -p x/y/z &&
 	test_commit x/y/z/f &&
-	git sparse-checkout set !/x y/ !x/y/z &&
+	git sparse-checkout set --no-cone !/x y/ !x/y/z &&
 
 	git update-index --no-skip-worktree x/y/z/f.t &&
 	test_must_fail git rm x/y/z/f.t 2>stderr &&
diff --git a/t/t3705-add-sparse-checkout.sh b/t/t3705-add-sparse-checkout.sh
index 95609046c61..2bade9e804f 100755
--- a/t/t3705-add-sparse-checkout.sh
+++ b/t/t3705-add-sparse-checkout.sh
@@ -166,7 +166,7 @@ test_expect_success 'do not warn when pathspec matches dense entries' '
 test_expect_success 'git add fails outside of sparse-checkout definition' '
 	test_when_finished git sparse-checkout disable &&
 	test_commit a &&
-	git sparse-checkout init &&
+	git sparse-checkout init --no-cone &&
 	git sparse-checkout set a &&
 	echo >>sparse_entry &&
 
@@ -208,7 +208,7 @@ test_expect_success 'add obeys advice.updateSparsePath' '
 '
 
 test_expect_success 'add allows sparse entries with --sparse' '
-	git sparse-checkout set a &&
+	git sparse-checkout set --no-cone a &&
 	echo modified >sparse_entry &&
 	test_must_fail git add sparse_entry &&
 	test_sparse_entry_unchanged &&
diff --git a/t/t6428-merge-conflicts-sparse.sh b/t/t6428-merge-conflicts-sparse.sh
index 142c9aaabc5..064be1b629e 100755
--- a/t/t6428-merge-conflicts-sparse.sh
+++ b/t/t6428-merge-conflicts-sparse.sh
@@ -87,7 +87,7 @@ test_expect_success 'conflicting entries written to worktree even if sparse' '
 		test_path_is_file numerals &&
 
 		git sparse-checkout init &&
-		git sparse-checkout set README &&
+		git sparse-checkout set --no-cone README &&
 
 		test_path_is_file README &&
 		test_path_is_missing numerals &&
@@ -123,7 +123,7 @@ test_expect_success 'present-despite-SKIP_WORKTREE handled reasonably' '
 		test_path_is_file numerals &&
 
 		git sparse-checkout init &&
-		git sparse-checkout set README &&
+		git sparse-checkout set --no-cone README &&
 
 		test_path_is_file README &&
 		test_path_is_missing numerals &&
diff --git a/t/t7002-mv-sparse-checkout.sh b/t/t7002-mv-sparse-checkout.sh
index 1d3d2aca21c..f0f7cbfcdb7 100755
--- a/t/t7002-mv-sparse-checkout.sh
+++ b/t/t7002-mv-sparse-checkout.sh
@@ -27,7 +27,7 @@ test_expect_success 'setup' "
 test_expect_success 'mv refuses to move sparse-to-sparse' '
 	test_when_finished rm -f e &&
 	git reset --hard &&
-	git sparse-checkout set a &&
+	git sparse-checkout set --no-cone a &&
 	touch b &&
 	test_must_fail git mv b e 2>stderr &&
 	cat sparse_error_header >expect &&
diff --git a/t/t7012-skip-worktree-writing.sh b/t/t7012-skip-worktree-writing.sh
index cb9f1a6981e..cd5c20fe51b 100755
--- a/t/t7012-skip-worktree-writing.sh
+++ b/t/t7012-skip-worktree-writing.sh
@@ -151,7 +151,7 @@ test_expect_success 'stash restore in sparse checkout' '
 
 		git stash push &&
 
-		git sparse-checkout set subdir &&
+		git sparse-checkout set --no-cone subdir &&
 
 		# Ensure after sparse-checkout we only have expected files
 		cat >expect <<-EOF &&
-- 
gitgitgadget

[PATCH 2/9] sparse-checkout: make --cone the default

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

Make cone mode the default, and update the documentation accordingly.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 20 ++++++++++----------
 builtin/sparse-checkout.c             |  2 +-
 2 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 88e55f432f3..4ef03120797 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -22,8 +22,8 @@ present, or undo and go back to having all tracked files present in the
 working copy.
 
 The subset of files is chosen by providing a list of directories in
-cone mode (which is recommended), or by providing a list of patterns
-in non-cone mode.
+cone mode (the default), or by providing a list of patterns in
+non-cone mode.
 
 When in a sparse-checkout, other Git commands behave a bit differently.
 For example, switching branches will not update paths outside the
@@ -60,7 +60,7 @@ When the `--stdin` option is provided, the directories or patterns are
 read from standard in as a newline-delimited list instead of from the
 arguments.
 +
-When `--cone` is passed or `core.sparseCheckoutCone` is enabled, the
+When `--cone` is passed or `core.sparseCheckoutCone` is not false, the
 input list is considered a list of directories.  This allows for
 better performance with a limited set of patterns (see 'CONE PATTERN
 SET' below).  The input format matches the output of `git ls-tree
@@ -68,10 +68,9 @@ SET' below).  The input format matches the output of `git ls-tree
 double quote (") as C-style quoted strings.  Note that the set command
 will write patterns to the sparse-checkout file to include all files
 contained in those directories (recursively) as well as files that are
-siblings of ancestor directories. This may become the default in the
-future; --no-cone can be passed to request non-cone mode.
+siblings of ancestor directories.
 +
-When `--no-cone` is passed or `core.sparseCheckoutCone` is not enabled,
+When `--no-cone` is passed or `core.sparseCheckoutCone` is false,
 the input list is considered a list of patterns.  This mode is harder
 to use and less performant, and is thus not recommended.  See the
 "Sparse Checkout" section of linkgit:git-read-tree[1] and the "Pattern
@@ -227,10 +226,11 @@ patterns. The resulting sparse-checkout file is now
 Here, order matters, so the negative patterns are overridden by the positive
 patterns that appear lower in the file.
 
-If `core.sparseCheckoutCone=true`, then Git will parse the sparse-checkout file
-expecting patterns of these types. Git will warn if the patterns do not match.
-If the patterns do match the expected format, then Git will use faster hash-
-based algorithms to compute inclusion in the sparse-checkout.
+If `core.sparseCheckoutCone=true` (set by default or with an explicit
+`--cone`), then Git will parse the sparse-checkout file expecting
+patterns of these types. Git will warn if the patterns do not match.  If
+the patterns do match the expected format, then Git will use faster
+hash-based algorithms to compute inclusion in the sparse-checkout.
 
 In the cone mode case, the `git sparse-checkout list` subcommand will list the
 directories that define the recursive patterns. For the example sparse-checkout
diff --git a/builtin/sparse-checkout.c b/builtin/sparse-checkout.c
index 5518ed47f6c..61b7a7519bb 100644
--- a/builtin/sparse-checkout.c
+++ b/builtin/sparse-checkout.c
@@ -397,7 +397,7 @@ static int update_modes(int *cone_mode, int *sparse_index)
 
 	/* Set cone/non-cone mode appropriately */
 	core_apply_sparse_checkout = 1;
-	if (*cone_mode == 1) {
+	if (*cone_mode == 1 || *cone_mode == -1) {
 		mode = MODE_CONE_PATTERNS;
 		core_sparse_checkout_cone = 1;
 	} else {
-- 
gitgitgadget

[PATCH 3/9] git-sparse-checkout.txt: wording updates for the cone mode default

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

Now that cone mode is the default, we'd like to focus on the arguments
to set/add being directories rather than patterns, and it probably makes
sense to provide an earlier heads up that files from leading directories
get included as well.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 31 +++++++++++++--------------
 1 file changed, 15 insertions(+), 16 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 4ef03120797..42a984306bb 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -44,9 +44,9 @@ COMMANDS
 	Enable the necessary sparse-checkout config settings
 	(`core.sparseCheckout`, `core.sparseCheckoutCone`, and
 	`index.sparse`) if they are not already set to the desired values,
-	and write a set of patterns to the sparse-checkout file from the
-	list of arguments following the 'set' subcommand. Update the
-	working directory to match the new patterns.
+	populate the sparse-checkout file from the list of arguments
+	following the 'set' subcommand, and update the working directory to
+	match.
 +
 To ensure that adjusting the sparse-checkout settings within a worktree
 does not alter the sparse-checkout settings in other worktrees, the 'set'
@@ -60,15 +60,15 @@ When the `--stdin` option is provided, the directories or patterns are
 read from standard in as a newline-delimited list instead of from the
 arguments.
 +
-When `--cone` is passed or `core.sparseCheckoutCone` is not false, the
-input list is considered a list of directories.  This allows for
-better performance with a limited set of patterns (see 'CONE PATTERN
-SET' below).  The input format matches the output of `git ls-tree
---name-only`.  This includes interpreting pathnames that begin with a
-double quote (") as C-style quoted strings.  Note that the set command
-will write patterns to the sparse-checkout file to include all files
-contained in those directories (recursively) as well as files that are
-siblings of ancestor directories.
+By default, the input list is considered a list of directories, matching
+the output of `git ls-tree -d --name-only`.  This includes interpreting
+pathnames that begin with a double quote (") as C-style quoted strings.
+Note that all files under the specified directories (at any depth) will
+be included in the sparse checkout, as well as files that are siblings
+of either the given directory or any of its ancestors (see 'CONE PATTERN
+SET' below for more details).  In the past, this was not the default,
+and `--cone` needed to be specified or `core.sparseCheckoutCone` needed
+to be enabled.
 +
 When `--no-cone` is passed or `core.sparseCheckoutCone` is false,
 the input list is considered a list of patterns.  This mode is harder
@@ -208,10 +208,9 @@ the following patterns:
 This says "include everything in root, but nothing two levels below root."
 
 When in cone mode, the `git sparse-checkout set` subcommand takes a list of
-directories instead of a list of sparse-checkout patterns. In this mode,
-the command `git sparse-checkout set A/B/C` sets the directory `A/B/C` as
-a recursive pattern, the directories `A` and `A/B` are added as parent
-patterns. The resulting sparse-checkout file is now
+directories. In this mode, the command `git sparse-checkout set A/B/C` sets
+the directory `A/B/C` as a recursive pattern, the directories `A` and `A/B`
+are added as parent patterns. The resulting sparse-checkout file is now
 
 ----------------
 /*
-- 
gitgitgadget

[PATCH 4/9] git-sparse-checkout.txt: update docs for deprecation of 'init'

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

The 'init' subcommand of sparse-checkout was deprecated in ba2f3f58ac
("git-sparse-checkout.txt: update to document init/set/reapply changes",
2021-12-14), but a couple places in the manual still assumed it was the
primary way to use sparse-checkout.  Correct them.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 42a984306bb..b9e44e3dd4c 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -70,11 +70,11 @@ SET' below for more details).  In the past, this was not the default,
 and `--cone` needed to be specified or `core.sparseCheckoutCone` needed
 to be enabled.
 +
-When `--no-cone` is passed or `core.sparseCheckoutCone` is false,
-the input list is considered a list of patterns.  This mode is harder
-to use and less performant, and is thus not recommended.  See the
-"Sparse Checkout" section of linkgit:git-read-tree[1] and the "Pattern
-Set" sections below for more details.
+When `--no-cone` is passed, the input list is considered a list of
+patterns.  This mode is harder to use and less performant, and is thus
+not recommended.  See the "Sparse Checkout" section of
+linkgit:git-read-tree[1] and the "Pattern Set" sections below for more
+details.
 +
 Use the `--[no-]sparse-index` option to use a sparse index (the
 default is to not use it).  A sparse index reduces the size of the
@@ -196,9 +196,9 @@ In addition to the above two patterns, we also expect that all files in the
 root directory are included. If a recursive pattern is added, then all
 leading directories are added as parent patterns.
 
-By default, when running `git sparse-checkout init`, the root directory is
-added as a parent pattern. At this point, the sparse-checkout file contains
-the following patterns:
+By default, when running `git sparse-checkout set` with no directories
+specified, the root directory is added as a parent pattern. At this
+point, the sparse-checkout file contains the following patterns:
 
 ----------------
 /*
-- 
gitgitgadget

[PATCH 5/9] git-sparse-checkout.txt: shuffle some sections and mark as internal

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

With cone mode as the default, it makes sense to discuss it before
non-cone mode.  Also, the new default means we can just use directories
in most cases and users do not need to understand patterns or their
meanings.  Let's take advantage of this to mark several sections as
"INTERNALS", notifying the user that they do not need to know all those
details in order to make use of the sparse-checkout command.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 44 +++++++++++++--------------
 1 file changed, 22 insertions(+), 22 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index b9e44e3dd4c..883b7f4c44f 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -136,8 +136,8 @@ paths to pass to a subsequent 'set' or 'add' command.  However,
 the disable command, so the easy restore of calling a plain `init`
 decreased in utility.
 
-SPARSE CHECKOUT
----------------
+INTERNALS -- SPARSE CHECKOUT
+----------------------------
 
 "Sparse checkout" allows populating the working directory sparsely.  It
 uses the skip-worktree bit (see linkgit:git-update-index[1]) to tell Git
@@ -161,24 +161,8 @@ To repopulate the working directory with all files, use the
 `git sparse-checkout disable` command.
 
 
-FULL PATTERN SET
-----------------
-
-By default, the sparse-checkout file uses the same syntax as `.gitignore`
-files.
-
-While `$GIT_DIR/info/sparse-checkout` is usually used to specify what
-files are included, you can also specify what files are _not_ included,
-using negative patterns. For example, to remove the file `unwanted`:
-
-----------------
-/*
-!unwanted
-----------------
-
-
-CONE PATTERN SET
-----------------
+INTERNALS -- CONE PATTERN SET
+-----------------------------
 
 The full pattern set allows for arbitrary pattern matches and complicated
 inclusion/exclusion rules. These can result in O(N*M) pattern matches when
@@ -256,8 +240,24 @@ use `git add` and `git commit` to store them, then remove any remaining files
 manually to ensure Git can behave optimally.
 
 
-SUBMODULES
-----------
+INTERNALS -- FULL PATTERN SET
+-----------------------------
+
+By default, the sparse-checkout file uses the same syntax as `.gitignore`
+files.
+
+While `$GIT_DIR/info/sparse-checkout` is usually used to specify what
+files are included, you can also specify what files are _not_ included,
+using negative patterns. For example, to remove the file `unwanted`:
+
+----------------
+/*
+!unwanted
+----------------
+
+
+INTERNALS -- SUBMODULES
+-----------------------
 
 If your repository contains one or more submodules, then submodules
 are populated based on interactions with the `git submodule` command.
-- 
gitgitgadget

[PATCH 6/9] git-sparse-checkout.txt: add a new EXAMPLES section

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

Since many users like to learn from examples, provide a section in the
manual with example commands that would be used and a brief explanation
of what each does.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 42 +++++++++++++++++++++++----
 1 file changed, 36 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 883b7f4c44f..2cfb1d8f599 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -136,6 +136,42 @@ paths to pass to a subsequent 'set' or 'add' command.  However,
 the disable command, so the easy restore of calling a plain `init`
 decreased in utility.
 
+EXAMPLES
+--------
+`git sparse-checkout set MY/DIR1 SUB/DIR2`::
+
+	Change to a sparse checkout with all files (at any depth) under
+	MY/DIR1/ and SUB/DIR2/ present in the working copy (plus all
+	files immediately under MY/ and SUB/ and the toplevel
+	directory).  If already in a sparse checkout, change which files
+	are present in the working copy to this new selection.  Note
+	that this command will also delete all ignored files in any
+	directory that no longer has either tracked or
+	non-ignored-untracked files present.
+
+`git sparse-checkout disable`::
+
+	Repopulate the working directory with all files, disabling sparse
+	checkouts.
+
+`git sparse-checkout add SOME/DIR/ECTORY`::
+
+	Add all files under SOME/DIR/ECTORY/ (at any depth) to the
+	sparse checkout, as well as all files immediately under
+	SOME/DIR/ and immediately under SOME/.  Must already be in a
+	sparse checkout before using this command.
+
+`git sparse-checkout reapply`::
+
+	It is possible for commands to update the working tree in a way
+	that does not respect the selected sparsity directories, either
+	because of special cases (such as hitting conflicts when
+	merging/rebasing), or because some commands didn't fully support
+	sparse checkouts (e.g. the old `recursive` merge backend had
+	only limited support).  This command reapplies the existing
+	sparse directory specifications to make the working directory
+	match.
+
 INTERNALS -- SPARSE CHECKOUT
 ----------------------------
 
@@ -154,12 +190,6 @@ directory, it updates the skip-worktree bits in the index based
 on this file. The files matching the patterns in the file will
 appear in the working directory, and the rest will not.
 
-To enable the sparse-checkout feature, run `git sparse-checkout set` to
-set the patterns you want to use.
-
-To repopulate the working directory with all files, use the
-`git sparse-checkout disable` command.
-
 
 INTERNALS -- CONE PATTERN SET
 -----------------------------
-- 
gitgitgadget

[PATCH 7/9] git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a bit

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

Signed-off-by: Elijah Newren <newren@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 2cfb1d8f599..35e4e2d809e 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -273,12 +273,23 @@ manually to ensure Git can behave optimally.
 INTERNALS -- FULL PATTERN SET
 -----------------------------
 
-By default, the sparse-checkout file uses the same syntax as `.gitignore`
-files.
-
-While `$GIT_DIR/info/sparse-checkout` is usually used to specify what
-files are included, you can also specify what files are _not_ included,
-using negative patterns. For example, to remove the file `unwanted`:
+As noted above, the sparse-checkout file uses the same syntax as
+`.gitignore` files; see linkgit:gitignore[5] for details.  Here,
+though, the patterns are usually being used to select which files to
+include rather than which files to exclude.  (However, it can get a
+bit confusing since gitignore-style patterns have negations defined by
+patterns which begin with a '!', so you can also select files to _not_
+include.)
+
+For example, to select everything, and then to remove the file
+`unwanted` (so that every file will appear in your working tree except
+the file named `unwanted`):
+
+    git sparse-checkout set --no-cone '/*' '!unwanted'
+
+These patterns are just placed into the
+`$GIT_DIR/info/sparse-checkout` as-is, so the contents of that file
+at this point would be
 
 ----------------
 /*
-- 
gitgitgadget

[PATCH 8/9] git-sparse-checkout.txt: mark non-cone mode as deprecated

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

While we have no current plans to actually remove --no-cone mode, we
think users would be better off not using it.  Update the documentation
accordingly, including explaining why we think non-cone mode is
problematic for users.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 86 +++++++++++++++++++++++++--
 1 file changed, 82 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 35e4e2d809e..11792187224 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -71,10 +71,13 @@ and `--cone` needed to be specified or `core.sparseCheckoutCone` needed
 to be enabled.
 +
 When `--no-cone` is passed, the input list is considered a list of
-patterns.  This mode is harder to use and less performant, and is thus
-not recommended.  See the "Sparse Checkout" section of
-linkgit:git-read-tree[1] and the "Pattern Set" sections below for more
-details.
+patterns.  This mode is harder to use, and unless you can keep the
+number of patterns small, its design also scales poorly.  It used to be
+the default mode, but we do not recommend using it.  It does not work
+with the `--sparse-index` option, and will likely be incompatible with
+other new features as they are added.  See the "Non-cone Problems"
+section below and the "Sparse Checkout" section of
+linkgit:git-read-tree[1] for more details.
 +
 Use the `--[no-]sparse-index` option to use a sparse index (the
 default is to not use it).  A sparse index reduces the size of the
@@ -190,6 +193,81 @@ directory, it updates the skip-worktree bits in the index based
 on this file. The files matching the patterns in the file will
 appear in the working directory, and the rest will not.
 
+INTERNALS -- NON-CONE PROBLEMS
+------------------------------
+
+The `$GIT_DIR/info/sparse-checkout` file populated by the `set` and
+`add` subcommands is defined to be a bunch of patterns (one per line)
+using the same syntax as `.gitignore` files.  In cone mode, these
+patterns are restricted to matching directories (and users only ever
+need supply or see directory names), while in non-cone mode any
+gitignore-style pattern is permitted.  Using the full gitignore-style
+patterns in non-cone mode has a number of shortcomings:
+
+  * Fundamentally, it makes various worktree-updating processes (pull,
+    merge, rebase, switch, reset, checkout, etc.) require O(N*M) pattern
+    matches, where N is the number of patterns and M is the number of
+    paths in the index.  This scales poorly.
+
+  * Avoiding the scaling issue has to be done via limiting the number
+    of patterns via specifying leading directory name or glob.
+
+  * Passing globs on the command line is error-prone as users may
+    forget to quote the glob, causing the shell to expand it into all
+    matching files and pass them all individually along to
+    sparse-checkout set/add.  This both exacerbates the scaling
+    problem, and hardcodes the list of selected files to those which
+    were present at the time the initial set/add subcommand was run
+    (and thus ignoring other files matching the same glob which come
+    into the working tree after switching branches or pulling down
+    updates).
+
+  * It uses "ignore"/"exclude" syntax for selecting what to "include",
+    which periodically causes confusion.
+
+  * It introduces inconsistencies in the Git command line, since other
+    commands use pathspecs, but sparse-checkout (in non-cone mode) uses
+    gitignore patterns.
+
+  * It has edge cases where the "right" behavior is unclear.  Two examples:
+
+    First, two users are in a subdirectory, and the first runs
+       git sparse-checkout set '/toplevel-dir/*.c'
+    while the second runs
+       git sparse-checkout set relative-dir
+    Should those arguments be transliterated into
+       current/subdirectory/toplevel-dir/*.c
+    and
+       current/subdirectory/relative-dir
+    before inserting into the sparse-checkout file?  The user who typed
+    the first command is probably aware that arguments to set/add are
+    supposed to be patterns in non-cone mode, and probably would not be
+    happy with such a transliteration.  However, many gitignore-style
+    patterns are just paths, which might be what the user who typed the
+    second command was thinking, and they'd be upset if their argument
+    wasn't transliterated.
+
+    Second, what should bash-completion complete on for set/add commands
+    for non-cone users?  If it suggests paths, is it exacerbating the
+    problem above?  Also, if it suggests paths, what if the user has a
+    file or directory that begins with either a '!' or '#' or has a '*',
+    '\', '?', '[', or ']' in its name?  And if it suggests paths, will
+    it complete "/pro" to "/proc" (in the root filesytem) rather than to
+    "/progress.txt" in the current directory?  (Note that users are
+    likely to want to start paths with a leading '/' in non-cone mode,
+    for the same reason that .gitignore files often have one.)
+    Completing on files or directories might give nasty surprises in
+    all these cases.
+
+  * The excessive flexibility made other extensions essentially
+    impractical.  `--sparse-index` may not have been feasible in
+    non-cone mode, but even if it was, it would have been far more work
+    to implement and may have been too slow in practice.  Some ideas for
+    adding coupling between partial clones and sparse checkouts are only
+    practical with a more restricted set of paths.
+
+For all these reasons, non-cone mode is deprecated.  Please switch to
+using cone mode.
 
 INTERNALS -- CONE PATTERN SET
 -----------------------------
-- 
gitgitgadget

[PATCH 9/9] Documentation: some sparsity wording clarifications

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

Improve the wording for a couple paragraphs in two different manuals
relating to sparse behavior.

Reported-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Elijah Newren <newren@gmail.com>
---
 Documentation/git-read-tree.txt       |  9 +++++----
 Documentation/git-sparse-checkout.txt | 10 +++++-----
 2 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index 99bb387134d..cbafb1aed49 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -375,10 +375,11 @@ have finished your work-in-progress), attempt the merge again.
 SPARSE CHECKOUT
 ---------------
 
-Note: The `update-index` and `read-tree` primitives for supporting the
-skip-worktree bit predated the introduction of
-linkgit:git-sparse-checkout[1].  Users are encouraged to use
-`sparse-checkout` in preference to these low-level primitives.
+Note: The skip-worktree capabilities in linkgit:git-update-index[1]
+and `read-tree` predated the introduction of
+linkgit:git-sparse-checkout[1].  Users are encouraged to use the
+`sparse-checkout` command in preference to these plumbing commands for
+sparse-checkout/skip-worktree related needs.
 
 "Sparse checkout" allows populating the working directory sparsely.
 It uses the skip-worktree bit (see linkgit:git-update-index[1]) to
diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 11792187224..06f23660f63 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -15,11 +15,11 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-This command is used to create sparse checkouts, which means that it
-changes the working tree from having all tracked files present, to only
-have a subset of them.  It can also switch which subset of files are
-present, or undo and go back to having all tracked files present in the
-working copy.
+This command is used to create sparse checkouts, which change the
+working tree from having all tracked files present to only having a
+subset of those files.  It can also switch which subset of files are
+present, or undo and go back to having all tracked files present in
+the working copy.
 
 The subset of files is chosen by providing a list of directories in
 cone mode (the default), or by providing a list of patterns in
-- 
gitgitgadget

Re: [PATCH 2/9] sparse-checkout: make --cone the default

[Derrick Stolee]

On 3/8/2022 2:39 AM, Elijah Newren via GitGitGadget wrote:
> From: Elijah Newren <newren@gmail.com>
> 
> Make cone mode the default, and update the documentation accordingly.

Doc changes look good.

> --- a/builtin/sparse-checkout.c
> +++ b/builtin/sparse-checkout.c
> @@ -397,7 +397,7 @@ static int update_modes(int *cone_mode, int *sparse_index)
>  
>  	/* Set cone/non-cone mode appropriately */
>  	core_apply_sparse_checkout = 1;
> -	if (*cone_mode == 1) {
> +	if (*cone_mode == 1 || *cone_mode == -1) {

Part of me likes the fact that you're pointing out "if it is
enabled directly or not set at all", but maybe it would be
best to do

	if (*cone_mode) {

What do you think?

Thanks,
-Stolee

Re: [PATCH 6/9] git-sparse-checkout.txt: add a new EXAMPLES section

[Derrick Stolee]

On 3/8/2022 2:39 AM, Elijah Newren via GitGitGadget wrote:
> From: Elijah Newren <newren@gmail.com>
> 
> Since many users like to learn from examples, provide a section in the
> manual with example commands that would be used and a brief explanation
> of what each does.

Examples are great!
 
> +`git sparse-checkout reapply`::
> +
> +	It is possible for commands to update the working tree in a way
> +	that does not respect the selected sparsity directories, either
> +	because of special cases (such as hitting conflicts when
> +	merging/rebasing), or because some commands didn't fully support
> +	sparse checkouts (e.g. the old `recursive` merge backend had
> +	only limited support).  This command reapplies the existing
> +	sparse directory specifications to make the working directory
> +	match.

This focuses on how a Git command might cause extra data, but it
doesn't mention how other tools might create ignored files outside
of the sparse-checkout and this will clean them up. Do you want to
add that, or do you prefer focusing on just Git reasons?

Thanks,
-Stolee

Re: [PATCH 0/9] sparse-checkout: make cone mode the default

[Derrick Stolee]

On 3/8/2022 2:39 AM, Elijah Newren via GitGitGadget wrote:
> == Maintainer Note ==
> 
> Depends on a merge of en/present-despite-skipped into master.
> 
> == Overview ==
> 
> This patch changes the default mode for sparse-checkout from non-cone mode
> to cone-mode, and marks non-cone mode as deprecated. There is no plan to
> remove non-cone mode, we are merely recommending against its use.
> 
> The code change is pretty small, and most of this series is about
> documentation updates -- to focus on directories rather than patterns, to
> explain the new default, to explain why we are deprecating non-cone mode
> (the final patch), and to make other related cleanups to simplify the
> manual.

I made a couple comments with potential ways to improve the series, but
in general this series is high quality without any changes. I'm happy
with it as-is.

I'm particularly happy with the additional examples of how to use the
sparse-checkout builtin. That should really improve discoverability.

> == Alternative ==
> 
> There is one primary alternative to this series: make sparse-checkout error
> when neither --cone nor --no-cone are specified (so that there is no
> default), and wait until a future date to make --cone the default.

I appreciate considering this alternative, and I'd be open to it, if
needed. My gut feeling is that we don't need it.

Thanks,
-Stolee

Re: [PATCH 6/9] git-sparse-checkout.txt: add a new EXAMPLES section

[Elijah Newren]

On Tue, Mar 8, 2022 at 6:30 AM Derrick Stolee <derrickstolee@github.com> wrote:
>
> On 3/8/2022 2:39 AM, Elijah Newren via GitGitGadget wrote:
> > From: Elijah Newren <newren@gmail.com>
> >
> > Since many users like to learn from examples, provide a section in the
> > manual with example commands that would be used and a brief explanation
> > of what each does.
>
> Examples are great!
>
> > +`git sparse-checkout reapply`::
> > +
> > +     It is possible for commands to update the working tree in a way
> > +     that does not respect the selected sparsity directories, either
> > +     because of special cases (such as hitting conflicts when
> > +     merging/rebasing), or because some commands didn't fully support
> > +     sparse checkouts (e.g. the old `recursive` merge backend had
> > +     only limited support).  This command reapplies the existing
> > +     sparse directory specifications to make the working directory
> > +     match.
>
> This focuses on how a Git command might cause extra data, but it
> doesn't mention how other tools might create ignored files outside
> of the sparse-checkout and this will clean them up. Do you want to
> add that, or do you prefer focusing on just Git reasons?

Does that happen in a significant number of cases?  Prior to
en/present-despite-skipped, it was essentially a null set of cases.
After it, we'd need:
   * the file to be tracked (reapply doesn't touch untracked or ignored files)
   * the file to have been SKIP_WORKTREE prior to the other tool modifying it
   * the file has to have its contents match what is staged in the index
and then reapply would clean the file out.

I guess there is kind of a converse case of someone manually removing
the SKIP_WORKTREE bit via direct manipulation using `git update-index
--no-skip-worktree $PATH` and removing the file locally, and then
using `reapply` to get it back, but that seems like a really unlikely
usecase.


 Maybe if I just made a simple tweak to the wording:

...selected sparsity directories. This can come from tools external to
Git writing files, or even affect Git commands because of either
special cases...

does that sound good?  I'll submit a re-roll with that but I'm open to
alternative wordings.

Re: [PATCH 2/9] sparse-checkout: make --cone the default

[Elijah Newren]

On Tue, Mar 8, 2022 at 6:26 AM Derrick Stolee <derrickstolee@github.com> wrote:
>
> On 3/8/2022 2:39 AM, Elijah Newren via GitGitGadget wrote:
> > From: Elijah Newren <newren@gmail.com>
> >
> > Make cone mode the default, and update the documentation accordingly.
>
> Doc changes look good.
>
> > --- a/builtin/sparse-checkout.c
> > +++ b/builtin/sparse-checkout.c
> > @@ -397,7 +397,7 @@ static int update_modes(int *cone_mode, int *sparse_index)
> >
> >       /* Set cone/non-cone mode appropriately */
> >       core_apply_sparse_checkout = 1;
> > -     if (*cone_mode == 1) {
> > +     if (*cone_mode == 1 || *cone_mode == -1) {
>
> Part of me likes the fact that you're pointing out "if it is
> enabled directly or not set at all", but maybe it would be
> best to do
>
>         if (*cone_mode) {
>
> What do you think?

How about if I switch it, but add a comment since the special "unset"
value of -1 may not be clear:

    if (*cone_mode) { /* also handles "not specified" (value of -1) */

[PATCH v2 0/9] sparse-checkout: make cone mode the default

[Elijah Newren via GitGitGadget]

== Updates Log ==

Changes since v1:

 * rebased on master, to remove dependence on en/present-despite-skipped
   (which has since merged to master). Earlier version of series wasn't
   picked up anyway, so rebasing should be safe.
 * Wording and code style tweaks suggested by Stolee in his review

== Overview ==

This patch changes the default mode for sparse-checkout from non-cone mode
to cone-mode, and marks non-cone mode as deprecated. There is no plan to
remove non-cone mode, we are merely recommending against its use.

The code change is pretty small, and most of this series is about
documentation updates -- to focus on directories rather than patterns, to
explain the new default, to explain why we are deprecating non-cone mode
(the final patch), and to make other related cleanups to simplify the
manual.

Patch 1: Update tests to not assume cone-mode is the default Patch 2: Make
cone-mode the default Patches 3-9: Various updates to
git-sparse-checkout.txt, divided up for ease of review

== Alternative ==

There is one primary alternative to this series: make sparse-checkout error
when neither --cone nor --no-cone are specified (so that there is no
default), and wait until a future date to make --cone the default. That'd be
reasonable, but I had three reason to avoid going this route (note that item
2 means there's little practical difference between cone-mode-as-default and
no-mode-is-default):

 1. git-sparse-checkout.txt has the following huge warning early in the
    manual:

""" THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR, AND THE BEHAVIOR OF OTHER
COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN THE
FUTURE. """

 2. If users are unaware of the default change and attempt to provide
    patterns instead of directories, then they will get error messages added
    from en/sparse-checkout-fixes. They can learn at that time to get around
    the error messages by providing --no-cone.

 3. If users are unaware of the default change and provide directories, then
    that's where non-cone mode and cone mode overlap and things happen to
    work. (There is a slight difference in that cone mode will include files
    from parent directories of any specified directory, but that means the
    user gets a few more files in their sparse-checkout with cone mode than
    they would with non-cone mode.)

== CCs ==

Elijah Newren (9):
  tests: stop assuming --no-cone is the default mode for sparse-checkout
  sparse-checkout: make --cone the default
  git-sparse-checkout.txt: wording updates for the cone mode default
  git-sparse-checkout.txt: update docs for deprecation of 'init'
  git-sparse-checkout.txt: shuffle some sections and mark as internal
  git-sparse-checkout.txt: add a new EXAMPLES section
  git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a
    bit
  git-sparse-checkout.txt: mark non-cone mode as deprecated
  Documentation: some sparsity wording clarifications

 Documentation/git-read-tree.txt       |   9 +-
 Documentation/git-sparse-checkout.txt | 249 +++++++++++++++++++-------
 builtin/sparse-checkout.c             |   2 +-
 t/t1091-sparse-checkout-builtin.sh    |  15 +-
 t/t3602-rm-sparse-checkout.sh         |   6 +-
 t/t3705-add-sparse-checkout.sh        |   4 +-
 t/t6428-merge-conflicts-sparse.sh     |   4 +-
 t/t7002-mv-sparse-checkout.sh         |   2 +-
 t/t7012-skip-worktree-writing.sh      |   2 +-
 9 files changed, 207 insertions(+), 86 deletions(-)


base-commit: 1a4874565fa3b6668042216189551b98b4dc0b1b
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1148%2Fnewren%2Fsparse-checkout-default-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1148/newren/sparse-checkout-default-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1148

Range-diff vs v1:

  1:  8c3e730e86b =  1:  05dba7069c5 tests: stop assuming --no-cone is the default mode for sparse-checkout
  2:  b174b42ed82 !  2:  a53179764bc sparse-checkout: make --cone the default
     @@ builtin/sparse-checkout.c: static int update_modes(int *cone_mode, int *sparse_i
       	/* Set cone/non-cone mode appropriately */
       	core_apply_sparse_checkout = 1;
      -	if (*cone_mode == 1) {
     -+	if (*cone_mode == 1 || *cone_mode == -1) {
     ++	if (*cone_mode) { /* also handles "not specified" (value of -1) */
       		mode = MODE_CONE_PATTERNS;
       		core_sparse_checkout_cone = 1;
       	} else {
  3:  f98b3fac78a =  3:  8eab21996c7 git-sparse-checkout.txt: wording updates for the cone mode default
  4:  cd871966c06 =  4:  eb3b318b39e git-sparse-checkout.txt: update docs for deprecation of 'init'
  5:  fe37a966699 =  5:  7333198b778 git-sparse-checkout.txt: shuffle some sections and mark as internal
  6:  3265f41bcab !  6:  a814ea9e8d2 git-sparse-checkout.txt: add a new EXAMPLES section
     @@ Documentation/git-sparse-checkout.txt: paths to pass to a subsequent 'set' or 'a
      +
      +`git sparse-checkout reapply`::
      +
     -+	It is possible for commands to update the working tree in a way
     -+	that does not respect the selected sparsity directories, either
     -+	because of special cases (such as hitting conflicts when
     -+	merging/rebasing), or because some commands didn't fully support
     -+	sparse checkouts (e.g. the old `recursive` merge backend had
     -+	only limited support).  This command reapplies the existing
     -+	sparse directory specifications to make the working directory
     -+	match.
     ++	It is possible for commands to update the working tree in a
     ++	way that does not respect the selected sparsity directories.
     ++	This can come from tools external to Git writing files, or
     ++	even affect Git commands because of either special cases (such
     ++	as hitting conflicts when merging/rebasing), or because some
     ++	commands didn't fully support sparse checkouts (e.g. the old
     ++	`recursive` merge backend had only limited support).  This
     ++	command reapplies the existing sparse directory specifications
     ++	to make the working directory match.
      +
       INTERNALS -- SPARSE CHECKOUT
       ----------------------------
  7:  bdbf61ee6a0 =  7:  78028ecaa58 git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a bit
  8:  3e35d62c5ee =  8:  2d2b81986a5 git-sparse-checkout.txt: mark non-cone mode as deprecated
  9:  e7d3ff70914 =  9:  4b89a3392b0 Documentation: some sparsity wording clarifications

-- 
gitgitgadget

[PATCH v2 1/9] tests: stop assuming --no-cone is the default mode for sparse-checkout

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

Add an explicit --no-cone to several sparse-checkout invocations in
preparation for changing the default to cone mode.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
 t/t1091-sparse-checkout-builtin.sh | 15 ++++++++-------
 t/t3602-rm-sparse-checkout.sh      |  6 +++---
 t/t3705-add-sparse-checkout.sh     |  4 ++--
 t/t6428-merge-conflicts-sparse.sh  |  4 ++--
 t/t7002-mv-sparse-checkout.sh      |  2 +-
 t/t7012-skip-worktree-writing.sh   |  2 +-
 6 files changed, 17 insertions(+), 16 deletions(-)

diff --git a/t/t1091-sparse-checkout-builtin.sh b/t/t1091-sparse-checkout-builtin.sh
index 9a900310186..de1ec89007d 100755
--- a/t/t1091-sparse-checkout-builtin.sh
+++ b/t/t1091-sparse-checkout-builtin.sh
@@ -72,7 +72,7 @@ test_expect_success 'git sparse-checkout list (populated)' '
 '
 
 test_expect_success 'git sparse-checkout init' '
-	git -C repo sparse-checkout init &&
+	git -C repo sparse-checkout init --no-cone &&
 	cat >expect <<-\EOF &&
 	/*
 	!/*/
@@ -111,6 +111,7 @@ test_expect_success 'init with existing sparse-checkout' '
 
 test_expect_success 'clone --sparse' '
 	git clone --sparse "file://$(pwd)/repo" clone &&
+	git -C clone sparse-checkout reapply --no-cone &&
 	git -C clone sparse-checkout list >actual &&
 	cat >expect <<-\EOF &&
 	/*
@@ -124,7 +125,7 @@ test_expect_success 'switching to cone mode with non-cone mode patterns' '
 	git init bad-patterns &&
 	(
 		cd bad-patterns &&
-		git sparse-checkout init &&
+		git sparse-checkout init --no-cone &&
 		git sparse-checkout add dir &&
 		git config --worktree core.sparseCheckoutCone true &&
 		test_must_fail git sparse-checkout add dir 2>err &&
@@ -402,7 +403,7 @@ test_expect_success 'revert to old sparse-checkout on empty update' '
 		git sparse-checkout set nothing 2>err &&
 		test_i18ngrep ! "Sparse checkout leaves no entry on working directory" err &&
 		test_i18ngrep ! ".git/index.lock" err &&
-		git sparse-checkout set file
+		git sparse-checkout set --no-cone file
 	)
 '
 
@@ -424,7 +425,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with dirty status'
 	git clone repo dirty &&
 	echo dirty >dirty/folder1/a &&
 
-	git -C dirty sparse-checkout init 2>err &&
+	git -C dirty sparse-checkout init --no-cone 2>err &&
 	test_i18ngrep "warning.*The following paths are not up to date" err &&
 
 	git -C dirty sparse-checkout set /folder2/* /deep/deeper1/* 2>err &&
@@ -435,7 +436,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with dirty status'
 	test_must_be_empty err &&
 
 	git -C dirty reset --hard &&
-	git -C dirty sparse-checkout init &&
+	git -C dirty sparse-checkout init --no-cone &&
 	git -C dirty sparse-checkout set /folder2/* /deep/deeper1/* &&
 	test_path_is_missing dirty/folder1/a &&
 	git -C dirty sparse-checkout disable &&
@@ -451,7 +452,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with unmerged stat
 	EOF
 	git -C unmerged update-index --index-info <input &&
 
-	git -C unmerged sparse-checkout init 2>err &&
+	git -C unmerged sparse-checkout init --no-cone 2>err &&
 	test_i18ngrep "warning.*The following paths are unmerged" err &&
 
 	git -C unmerged sparse-checkout set /folder2/* /deep/deeper1/* 2>err &&
@@ -462,7 +463,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with unmerged stat
 	test_i18ngrep "warning.*The following paths are unmerged" err &&
 
 	git -C unmerged reset --hard &&
-	git -C unmerged sparse-checkout init &&
+	git -C unmerged sparse-checkout init --no-cone &&
 	git -C unmerged sparse-checkout set /folder2/* /deep/deeper1/* &&
 	git -C unmerged sparse-checkout disable
 '
diff --git a/t/t3602-rm-sparse-checkout.sh b/t/t3602-rm-sparse-checkout.sh
index 034ec010910..08580fd3dcc 100755
--- a/t/t3602-rm-sparse-checkout.sh
+++ b/t/t3602-rm-sparse-checkout.sh
@@ -30,7 +30,7 @@ test_expect_success 'setup' "
 for opt in "" -f --dry-run
 do
 	test_expect_success "rm${opt:+ $opt} does not remove sparse entries" '
-		git sparse-checkout set a &&
+		git sparse-checkout set --no-cone a &&
 		test_must_fail git rm $opt b 2>stderr &&
 		test_cmp b_error_and_hint stderr &&
 		git ls-files --error-unmatch b
@@ -118,7 +118,7 @@ test_expect_success 'can remove files from non-sparse dir' '
 	test_commit w/f &&
 	test_commit x/y/f &&
 
-	git sparse-checkout set w !/x y/ &&
+	git sparse-checkout set --no-cone w !/x y/ &&
 	git rm w/f.t x/y/f.t 2>stderr &&
 	test_must_be_empty stderr
 '
@@ -128,7 +128,7 @@ test_expect_success 'refuse to remove non-skip-worktree file from sparse dir' '
 	git sparse-checkout disable &&
 	mkdir -p x/y/z &&
 	test_commit x/y/z/f &&
-	git sparse-checkout set !/x y/ !x/y/z &&
+	git sparse-checkout set --no-cone !/x y/ !x/y/z &&
 
 	git update-index --no-skip-worktree x/y/z/f.t &&
 	test_must_fail git rm x/y/z/f.t 2>stderr &&
diff --git a/t/t3705-add-sparse-checkout.sh b/t/t3705-add-sparse-checkout.sh
index 95609046c61..2bade9e804f 100755
--- a/t/t3705-add-sparse-checkout.sh
+++ b/t/t3705-add-sparse-checkout.sh
@@ -166,7 +166,7 @@ test_expect_success 'do not warn when pathspec matches dense entries' '
 test_expect_success 'git add fails outside of sparse-checkout definition' '
 	test_when_finished git sparse-checkout disable &&
 	test_commit a &&
-	git sparse-checkout init &&
+	git sparse-checkout init --no-cone &&
 	git sparse-checkout set a &&
 	echo >>sparse_entry &&
 
@@ -208,7 +208,7 @@ test_expect_success 'add obeys advice.updateSparsePath' '
 '
 
 test_expect_success 'add allows sparse entries with --sparse' '
-	git sparse-checkout set a &&
+	git sparse-checkout set --no-cone a &&
 	echo modified >sparse_entry &&
 	test_must_fail git add sparse_entry &&
 	test_sparse_entry_unchanged &&
diff --git a/t/t6428-merge-conflicts-sparse.sh b/t/t6428-merge-conflicts-sparse.sh
index 142c9aaabc5..064be1b629e 100755
--- a/t/t6428-merge-conflicts-sparse.sh
+++ b/t/t6428-merge-conflicts-sparse.sh
@@ -87,7 +87,7 @@ test_expect_success 'conflicting entries written to worktree even if sparse' '
 		test_path_is_file numerals &&
 
 		git sparse-checkout init &&
-		git sparse-checkout set README &&
+		git sparse-checkout set --no-cone README &&
 
 		test_path_is_file README &&
 		test_path_is_missing numerals &&
@@ -123,7 +123,7 @@ test_expect_success 'present-despite-SKIP_WORKTREE handled reasonably' '
 		test_path_is_file numerals &&
 
 		git sparse-checkout init &&
-		git sparse-checkout set README &&
+		git sparse-checkout set --no-cone README &&
 
 		test_path_is_file README &&
 		test_path_is_missing numerals &&
diff --git a/t/t7002-mv-sparse-checkout.sh b/t/t7002-mv-sparse-checkout.sh
index 1d3d2aca21c..f0f7cbfcdb7 100755
--- a/t/t7002-mv-sparse-checkout.sh
+++ b/t/t7002-mv-sparse-checkout.sh
@@ -27,7 +27,7 @@ test_expect_success 'setup' "
 test_expect_success 'mv refuses to move sparse-to-sparse' '
 	test_when_finished rm -f e &&
 	git reset --hard &&
-	git sparse-checkout set a &&
+	git sparse-checkout set --no-cone a &&
 	touch b &&
 	test_must_fail git mv b e 2>stderr &&
 	cat sparse_error_header >expect &&
diff --git a/t/t7012-skip-worktree-writing.sh b/t/t7012-skip-worktree-writing.sh
index cb9f1a6981e..cd5c20fe51b 100755
--- a/t/t7012-skip-worktree-writing.sh
+++ b/t/t7012-skip-worktree-writing.sh
@@ -151,7 +151,7 @@ test_expect_success 'stash restore in sparse checkout' '
 
 		git stash push &&
 
-		git sparse-checkout set subdir &&
+		git sparse-checkout set --no-cone subdir &&
 
 		# Ensure after sparse-checkout we only have expected files
 		cat >expect <<-EOF &&
-- 
gitgitgadget

[PATCH v2 2/9] sparse-checkout: make --cone the default

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

Make cone mode the default, and update the documentation accordingly.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 20 ++++++++++----------
 builtin/sparse-checkout.c             |  2 +-
 2 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 88e55f432f3..4ef03120797 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -22,8 +22,8 @@ present, or undo and go back to having all tracked files present in the
 working copy.
 
 The subset of files is chosen by providing a list of directories in
-cone mode (which is recommended), or by providing a list of patterns
-in non-cone mode.
+cone mode (the default), or by providing a list of patterns in
+non-cone mode.
 
 When in a sparse-checkout, other Git commands behave a bit differently.
 For example, switching branches will not update paths outside the
@@ -60,7 +60,7 @@ When the `--stdin` option is provided, the directories or patterns are
 read from standard in as a newline-delimited list instead of from the
 arguments.
 +
-When `--cone` is passed or `core.sparseCheckoutCone` is enabled, the
+When `--cone` is passed or `core.sparseCheckoutCone` is not false, the
 input list is considered a list of directories.  This allows for
 better performance with a limited set of patterns (see 'CONE PATTERN
 SET' below).  The input format matches the output of `git ls-tree
@@ -68,10 +68,9 @@ SET' below).  The input format matches the output of `git ls-tree
 double quote (") as C-style quoted strings.  Note that the set command
 will write patterns to the sparse-checkout file to include all files
 contained in those directories (recursively) as well as files that are
-siblings of ancestor directories. This may become the default in the
-future; --no-cone can be passed to request non-cone mode.
+siblings of ancestor directories.
 +
-When `--no-cone` is passed or `core.sparseCheckoutCone` is not enabled,
+When `--no-cone` is passed or `core.sparseCheckoutCone` is false,
 the input list is considered a list of patterns.  This mode is harder
 to use and less performant, and is thus not recommended.  See the
 "Sparse Checkout" section of linkgit:git-read-tree[1] and the "Pattern
@@ -227,10 +226,11 @@ patterns. The resulting sparse-checkout file is now
 Here, order matters, so the negative patterns are overridden by the positive
 patterns that appear lower in the file.
 
-If `core.sparseCheckoutCone=true`, then Git will parse the sparse-checkout file
-expecting patterns of these types. Git will warn if the patterns do not match.
-If the patterns do match the expected format, then Git will use faster hash-
-based algorithms to compute inclusion in the sparse-checkout.
+If `core.sparseCheckoutCone=true` (set by default or with an explicit
+`--cone`), then Git will parse the sparse-checkout file expecting
+patterns of these types. Git will warn if the patterns do not match.  If
+the patterns do match the expected format, then Git will use faster
+hash-based algorithms to compute inclusion in the sparse-checkout.
 
 In the cone mode case, the `git sparse-checkout list` subcommand will list the
 directories that define the recursive patterns. For the example sparse-checkout
diff --git a/builtin/sparse-checkout.c b/builtin/sparse-checkout.c
index 5518ed47f6c..6603a0cc029 100644
--- a/builtin/sparse-checkout.c
+++ b/builtin/sparse-checkout.c
@@ -397,7 +397,7 @@ static int update_modes(int *cone_mode, int *sparse_index)
 
 	/* Set cone/non-cone mode appropriately */
 	core_apply_sparse_checkout = 1;
-	if (*cone_mode == 1) {
+	if (*cone_mode) { /* also handles "not specified" (value of -1) */
 		mode = MODE_CONE_PATTERNS;
 		core_sparse_checkout_cone = 1;
 	} else {
-- 
gitgitgadget

[PATCH v2 3/9] git-sparse-checkout.txt: wording updates for the cone mode default

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

Now that cone mode is the default, we'd like to focus on the arguments
to set/add being directories rather than patterns, and it probably makes
sense to provide an earlier heads up that files from leading directories
get included as well.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 31 +++++++++++++--------------
 1 file changed, 15 insertions(+), 16 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 4ef03120797..42a984306bb 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -44,9 +44,9 @@ COMMANDS
 	Enable the necessary sparse-checkout config settings
 	(`core.sparseCheckout`, `core.sparseCheckoutCone`, and
 	`index.sparse`) if they are not already set to the desired values,
-	and write a set of patterns to the sparse-checkout file from the
-	list of arguments following the 'set' subcommand. Update the
-	working directory to match the new patterns.
+	populate the sparse-checkout file from the list of arguments
+	following the 'set' subcommand, and update the working directory to
+	match.
 +
 To ensure that adjusting the sparse-checkout settings within a worktree
 does not alter the sparse-checkout settings in other worktrees, the 'set'
@@ -60,15 +60,15 @@ When the `--stdin` option is provided, the directories or patterns are
 read from standard in as a newline-delimited list instead of from the
 arguments.
 +
-When `--cone` is passed or `core.sparseCheckoutCone` is not false, the
-input list is considered a list of directories.  This allows for
-better performance with a limited set of patterns (see 'CONE PATTERN
-SET' below).  The input format matches the output of `git ls-tree
---name-only`.  This includes interpreting pathnames that begin with a
-double quote (") as C-style quoted strings.  Note that the set command
-will write patterns to the sparse-checkout file to include all files
-contained in those directories (recursively) as well as files that are
-siblings of ancestor directories.
+By default, the input list is considered a list of directories, matching
+the output of `git ls-tree -d --name-only`.  This includes interpreting
+pathnames that begin with a double quote (") as C-style quoted strings.
+Note that all files under the specified directories (at any depth) will
+be included in the sparse checkout, as well as files that are siblings
+of either the given directory or any of its ancestors (see 'CONE PATTERN
+SET' below for more details).  In the past, this was not the default,
+and `--cone` needed to be specified or `core.sparseCheckoutCone` needed
+to be enabled.
 +
 When `--no-cone` is passed or `core.sparseCheckoutCone` is false,
 the input list is considered a list of patterns.  This mode is harder
@@ -208,10 +208,9 @@ the following patterns:
 This says "include everything in root, but nothing two levels below root."
 
 When in cone mode, the `git sparse-checkout set` subcommand takes a list of
-directories instead of a list of sparse-checkout patterns. In this mode,
-the command `git sparse-checkout set A/B/C` sets the directory `A/B/C` as
-a recursive pattern, the directories `A` and `A/B` are added as parent
-patterns. The resulting sparse-checkout file is now
+directories. In this mode, the command `git sparse-checkout set A/B/C` sets
+the directory `A/B/C` as a recursive pattern, the directories `A` and `A/B`
+are added as parent patterns. The resulting sparse-checkout file is now
 
 ----------------
 /*
-- 
gitgitgadget

[PATCH v2 4/9] git-sparse-checkout.txt: update docs for deprecation of 'init'

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

The 'init' subcommand of sparse-checkout was deprecated in ba2f3f58ac
("git-sparse-checkout.txt: update to document init/set/reapply changes",
2021-12-14), but a couple places in the manual still assumed it was the
primary way to use sparse-checkout.  Correct them.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 42a984306bb..b9e44e3dd4c 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -70,11 +70,11 @@ SET' below for more details).  In the past, this was not the default,
 and `--cone` needed to be specified or `core.sparseCheckoutCone` needed
 to be enabled.
 +
-When `--no-cone` is passed or `core.sparseCheckoutCone` is false,
-the input list is considered a list of patterns.  This mode is harder
-to use and less performant, and is thus not recommended.  See the
-"Sparse Checkout" section of linkgit:git-read-tree[1] and the "Pattern
-Set" sections below for more details.
+When `--no-cone` is passed, the input list is considered a list of
+patterns.  This mode is harder to use and less performant, and is thus
+not recommended.  See the "Sparse Checkout" section of
+linkgit:git-read-tree[1] and the "Pattern Set" sections below for more
+details.
 +
 Use the `--[no-]sparse-index` option to use a sparse index (the
 default is to not use it).  A sparse index reduces the size of the
@@ -196,9 +196,9 @@ In addition to the above two patterns, we also expect that all files in the
 root directory are included. If a recursive pattern is added, then all
 leading directories are added as parent patterns.
 
-By default, when running `git sparse-checkout init`, the root directory is
-added as a parent pattern. At this point, the sparse-checkout file contains
-the following patterns:
+By default, when running `git sparse-checkout set` with no directories
+specified, the root directory is added as a parent pattern. At this
+point, the sparse-checkout file contains the following patterns:
 
 ----------------
 /*
-- 
gitgitgadget

[PATCH v2 5/9] git-sparse-checkout.txt: shuffle some sections and mark as internal

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

With cone mode as the default, it makes sense to discuss it before
non-cone mode.  Also, the new default means we can just use directories
in most cases and users do not need to understand patterns or their
meanings.  Let's take advantage of this to mark several sections as
"INTERNALS", notifying the user that they do not need to know all those
details in order to make use of the sparse-checkout command.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 44 +++++++++++++--------------
 1 file changed, 22 insertions(+), 22 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index b9e44e3dd4c..883b7f4c44f 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -136,8 +136,8 @@ paths to pass to a subsequent 'set' or 'add' command.  However,
 the disable command, so the easy restore of calling a plain `init`
 decreased in utility.
 
-SPARSE CHECKOUT
----------------
+INTERNALS -- SPARSE CHECKOUT
+----------------------------
 
 "Sparse checkout" allows populating the working directory sparsely.  It
 uses the skip-worktree bit (see linkgit:git-update-index[1]) to tell Git
@@ -161,24 +161,8 @@ To repopulate the working directory with all files, use the
 `git sparse-checkout disable` command.
 
 
-FULL PATTERN SET
-----------------
-
-By default, the sparse-checkout file uses the same syntax as `.gitignore`
-files.
-
-While `$GIT_DIR/info/sparse-checkout` is usually used to specify what
-files are included, you can also specify what files are _not_ included,
-using negative patterns. For example, to remove the file `unwanted`:
-
-----------------
-/*
-!unwanted
-----------------
-
-
-CONE PATTERN SET
-----------------
+INTERNALS -- CONE PATTERN SET
+-----------------------------
 
 The full pattern set allows for arbitrary pattern matches and complicated
 inclusion/exclusion rules. These can result in O(N*M) pattern matches when
@@ -256,8 +240,24 @@ use `git add` and `git commit` to store them, then remove any remaining files
 manually to ensure Git can behave optimally.
 
 
-SUBMODULES
-----------
+INTERNALS -- FULL PATTERN SET
+-----------------------------
+
+By default, the sparse-checkout file uses the same syntax as `.gitignore`
+files.
+
+While `$GIT_DIR/info/sparse-checkout` is usually used to specify what
+files are included, you can also specify what files are _not_ included,
+using negative patterns. For example, to remove the file `unwanted`:
+
+----------------
+/*
+!unwanted
+----------------
+
+
+INTERNALS -- SUBMODULES
+-----------------------
 
 If your repository contains one or more submodules, then submodules
 are populated based on interactions with the `git submodule` command.
-- 
gitgitgadget

[PATCH v2 6/9] git-sparse-checkout.txt: add a new EXAMPLES section

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

Since many users like to learn from examples, provide a section in the
manual with example commands that would be used and a brief explanation
of what each does.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 43 +++++++++++++++++++++++----
 1 file changed, 37 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 883b7f4c44f..dddf5ac6942 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -136,6 +136,43 @@ paths to pass to a subsequent 'set' or 'add' command.  However,
 the disable command, so the easy restore of calling a plain `init`
 decreased in utility.
 
+EXAMPLES
+--------
+`git sparse-checkout set MY/DIR1 SUB/DIR2`::
+
+	Change to a sparse checkout with all files (at any depth) under
+	MY/DIR1/ and SUB/DIR2/ present in the working copy (plus all
+	files immediately under MY/ and SUB/ and the toplevel
+	directory).  If already in a sparse checkout, change which files
+	are present in the working copy to this new selection.  Note
+	that this command will also delete all ignored files in any
+	directory that no longer has either tracked or
+	non-ignored-untracked files present.
+
+`git sparse-checkout disable`::
+
+	Repopulate the working directory with all files, disabling sparse
+	checkouts.
+
+`git sparse-checkout add SOME/DIR/ECTORY`::
+
+	Add all files under SOME/DIR/ECTORY/ (at any depth) to the
+	sparse checkout, as well as all files immediately under
+	SOME/DIR/ and immediately under SOME/.  Must already be in a
+	sparse checkout before using this command.
+
+`git sparse-checkout reapply`::
+
+	It is possible for commands to update the working tree in a
+	way that does not respect the selected sparsity directories.
+	This can come from tools external to Git writing files, or
+	even affect Git commands because of either special cases (such
+	as hitting conflicts when merging/rebasing), or because some
+	commands didn't fully support sparse checkouts (e.g. the old
+	`recursive` merge backend had only limited support).  This
+	command reapplies the existing sparse directory specifications
+	to make the working directory match.
+
 INTERNALS -- SPARSE CHECKOUT
 ----------------------------
 
@@ -154,12 +191,6 @@ directory, it updates the skip-worktree bits in the index based
 on this file. The files matching the patterns in the file will
 appear in the working directory, and the rest will not.
 
-To enable the sparse-checkout feature, run `git sparse-checkout set` to
-set the patterns you want to use.
-
-To repopulate the working directory with all files, use the
-`git sparse-checkout disable` command.
-
 
 INTERNALS -- CONE PATTERN SET
 -----------------------------
-- 
gitgitgadget

[PATCH v2 7/9] git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a bit

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

Signed-off-by: Elijah Newren <newren@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index dddf5ac6942..ae6ea8b48b0 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -274,12 +274,23 @@ manually to ensure Git can behave optimally.
 INTERNALS -- FULL PATTERN SET
 -----------------------------
 
-By default, the sparse-checkout file uses the same syntax as `.gitignore`
-files.
-
-While `$GIT_DIR/info/sparse-checkout` is usually used to specify what
-files are included, you can also specify what files are _not_ included,
-using negative patterns. For example, to remove the file `unwanted`:
+As noted above, the sparse-checkout file uses the same syntax as
+`.gitignore` files; see linkgit:gitignore[5] for details.  Here,
+though, the patterns are usually being used to select which files to
+include rather than which files to exclude.  (However, it can get a
+bit confusing since gitignore-style patterns have negations defined by
+patterns which begin with a '!', so you can also select files to _not_
+include.)
+
+For example, to select everything, and then to remove the file
+`unwanted` (so that every file will appear in your working tree except
+the file named `unwanted`):
+
+    git sparse-checkout set --no-cone '/*' '!unwanted'
+
+These patterns are just placed into the
+`$GIT_DIR/info/sparse-checkout` as-is, so the contents of that file
+at this point would be
 
 ----------------
 /*
-- 
gitgitgadget

[PATCH v2 8/9] git-sparse-checkout.txt: mark non-cone mode as deprecated

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

While we have no current plans to actually remove --no-cone mode, we
think users would be better off not using it.  Update the documentation
accordingly, including explaining why we think non-cone mode is
problematic for users.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 86 +++++++++++++++++++++++++--
 1 file changed, 82 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index ae6ea8b48b0..aaf3ae63853 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -71,10 +71,13 @@ and `--cone` needed to be specified or `core.sparseCheckoutCone` needed
 to be enabled.
 +
 When `--no-cone` is passed, the input list is considered a list of
-patterns.  This mode is harder to use and less performant, and is thus
-not recommended.  See the "Sparse Checkout" section of
-linkgit:git-read-tree[1] and the "Pattern Set" sections below for more
-details.
+patterns.  This mode is harder to use, and unless you can keep the
+number of patterns small, its design also scales poorly.  It used to be
+the default mode, but we do not recommend using it.  It does not work
+with the `--sparse-index` option, and will likely be incompatible with
+other new features as they are added.  See the "Non-cone Problems"
+section below and the "Sparse Checkout" section of
+linkgit:git-read-tree[1] for more details.
 +
 Use the `--[no-]sparse-index` option to use a sparse index (the
 default is to not use it).  A sparse index reduces the size of the
@@ -191,6 +194,81 @@ directory, it updates the skip-worktree bits in the index based
 on this file. The files matching the patterns in the file will
 appear in the working directory, and the rest will not.
 
+INTERNALS -- NON-CONE PROBLEMS
+------------------------------
+
+The `$GIT_DIR/info/sparse-checkout` file populated by the `set` and
+`add` subcommands is defined to be a bunch of patterns (one per line)
+using the same syntax as `.gitignore` files.  In cone mode, these
+patterns are restricted to matching directories (and users only ever
+need supply or see directory names), while in non-cone mode any
+gitignore-style pattern is permitted.  Using the full gitignore-style
+patterns in non-cone mode has a number of shortcomings:
+
+  * Fundamentally, it makes various worktree-updating processes (pull,
+    merge, rebase, switch, reset, checkout, etc.) require O(N*M) pattern
+    matches, where N is the number of patterns and M is the number of
+    paths in the index.  This scales poorly.
+
+  * Avoiding the scaling issue has to be done via limiting the number
+    of patterns via specifying leading directory name or glob.
+
+  * Passing globs on the command line is error-prone as users may
+    forget to quote the glob, causing the shell to expand it into all
+    matching files and pass them all individually along to
+    sparse-checkout set/add.  This both exacerbates the scaling
+    problem, and hardcodes the list of selected files to those which
+    were present at the time the initial set/add subcommand was run
+    (and thus ignoring other files matching the same glob which come
+    into the working tree after switching branches or pulling down
+    updates).
+
+  * It uses "ignore"/"exclude" syntax for selecting what to "include",
+    which periodically causes confusion.
+
+  * It introduces inconsistencies in the Git command line, since other
+    commands use pathspecs, but sparse-checkout (in non-cone mode) uses
+    gitignore patterns.
+
+  * It has edge cases where the "right" behavior is unclear.  Two examples:
+
+    First, two users are in a subdirectory, and the first runs
+       git sparse-checkout set '/toplevel-dir/*.c'
+    while the second runs
+       git sparse-checkout set relative-dir
+    Should those arguments be transliterated into
+       current/subdirectory/toplevel-dir/*.c
+    and
+       current/subdirectory/relative-dir
+    before inserting into the sparse-checkout file?  The user who typed
+    the first command is probably aware that arguments to set/add are
+    supposed to be patterns in non-cone mode, and probably would not be
+    happy with such a transliteration.  However, many gitignore-style
+    patterns are just paths, which might be what the user who typed the
+    second command was thinking, and they'd be upset if their argument
+    wasn't transliterated.
+
+    Second, what should bash-completion complete on for set/add commands
+    for non-cone users?  If it suggests paths, is it exacerbating the
+    problem above?  Also, if it suggests paths, what if the user has a
+    file or directory that begins with either a '!' or '#' or has a '*',
+    '\', '?', '[', or ']' in its name?  And if it suggests paths, will
+    it complete "/pro" to "/proc" (in the root filesytem) rather than to
+    "/progress.txt" in the current directory?  (Note that users are
+    likely to want to start paths with a leading '/' in non-cone mode,
+    for the same reason that .gitignore files often have one.)
+    Completing on files or directories might give nasty surprises in
+    all these cases.
+
+  * The excessive flexibility made other extensions essentially
+    impractical.  `--sparse-index` may not have been feasible in
+    non-cone mode, but even if it was, it would have been far more work
+    to implement and may have been too slow in practice.  Some ideas for
+    adding coupling between partial clones and sparse checkouts are only
+    practical with a more restricted set of paths.
+
+For all these reasons, non-cone mode is deprecated.  Please switch to
+using cone mode.
 
 INTERNALS -- CONE PATTERN SET
 -----------------------------
-- 
gitgitgadget

[PATCH v2 9/9] Documentation: some sparsity wording clarifications

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

Improve the wording for a couple paragraphs in two different manuals
relating to sparse behavior.

Reported-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Elijah Newren <newren@gmail.com>
---
 Documentation/git-read-tree.txt       |  9 +++++----
 Documentation/git-sparse-checkout.txt | 10 +++++-----
 2 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index 99bb387134d..cbafb1aed49 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -375,10 +375,11 @@ have finished your work-in-progress), attempt the merge again.
 SPARSE CHECKOUT
 ---------------
 
-Note: The `update-index` and `read-tree` primitives for supporting the
-skip-worktree bit predated the introduction of
-linkgit:git-sparse-checkout[1].  Users are encouraged to use
-`sparse-checkout` in preference to these low-level primitives.
+Note: The skip-worktree capabilities in linkgit:git-update-index[1]
+and `read-tree` predated the introduction of
+linkgit:git-sparse-checkout[1].  Users are encouraged to use the
+`sparse-checkout` command in preference to these plumbing commands for
+sparse-checkout/skip-worktree related needs.
 
 "Sparse checkout" allows populating the working directory sparsely.
 It uses the skip-worktree bit (see linkgit:git-update-index[1]) to
diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index aaf3ae63853..e4a29a2baa9 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -15,11 +15,11 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-This command is used to create sparse checkouts, which means that it
-changes the working tree from having all tracked files present, to only
-have a subset of them.  It can also switch which subset of files are
-present, or undo and go back to having all tracked files present in the
-working copy.
+This command is used to create sparse checkouts, which change the
+working tree from having all tracked files present to only having a
+subset of those files.  It can also switch which subset of files are
+present, or undo and go back to having all tracked files present in
+the working copy.
 
 The subset of files is chosen by providing a list of directories in
 cone mode (the default), or by providing a list of patterns in
-- 
gitgitgadget

Re: [PATCH v2 0/9] sparse-checkout: make cone mode the default

[Derrick Stolee]

On 3/11/2022 10:11 PM, Elijah Newren via GitGitGadget wrote:
> == Updates Log ==
> 
> Changes since v1:
> 
>  * rebased on master, to remove dependence on en/present-despite-skipped
>    (which has since merged to master). Earlier version of series wasn't
>    picked up anyway, so rebasing should be safe.
>  * Wording and code style tweaks suggested by Stolee in his review

Thanks for these updates. This version looks good to me.

Thanks,
-Stolee

Re: [PATCH v2 0/9] sparse-checkout: make cone mode the default

[Victoria Dye]

Elijah Newren via GitGitGadget wrote:
> == Updates Log ==
> 
> Changes since v1:
> 
>  * rebased on master, to remove dependence on en/present-despite-skipped
>    (which has since merged to master). Earlier version of series wasn't
>    picked up anyway, so rebasing should be safe.
>  * Wording and code style tweaks suggested by Stolee in his review
> 
> == Overview ==
> 
> This patch changes the default mode for sparse-checkout from non-cone mode
> to cone-mode, and marks non-cone mode as deprecated. There is no plan to
> remove non-cone mode, we are merely recommending against its use.
> 
> The code change is pretty small, and most of this series is about
> documentation updates -- to focus on directories rather than patterns, to
> explain the new default, to explain why we are deprecating non-cone mode
> (the final patch), and to make other related cleanups to simplify the
> manual.
> 
> Patch 1: Update tests to not assume cone-mode is the default Patch 2: Make
> cone-mode the default Patches 3-9: Various updates to
> git-sparse-checkout.txt, divided up for ease of review
> 

After looking over the patches (and Stolee's prior feedback), I don't have
any additional comments - it all looks great! 

I also ran through some scenarios going from "non-cone" to "cone mode" that
have been buggy in the past (e.g., non-cone directory patterns missing a
leading '/', then 'git sparse-checkout init --cone'), but it looks like the
checks added back in a3eca58445 (sparse-checkout: refuse to add to bad
patterns, 2021-12-16) prevent any unexplained behavior for a user that might
not be aware of the new default. In other words, changing the default looks
to be safe and overall pushes users towards a better experience using
sparse-checkout.

> == Alternative ==
> 
> There is one primary alternative to this series: make sparse-checkout error
> when neither --cone nor --no-cone are specified (so that there is no
> default), and wait until a future date to make --cone the default. That'd be
> reasonable, but I had three reason to avoid going this route (note that item
> 2 means there's little practical difference between cone-mode-as-default and
> no-mode-is-default):
> 
>  1. git-sparse-checkout.txt has the following huge warning early in the
>     manual:
> 
> """ THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR, AND THE BEHAVIOR OF OTHER
> COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN THE
> FUTURE. """
> 
>  2. If users are unaware of the default change and attempt to provide
>     patterns instead of directories, then they will get error messages added
>     from en/sparse-checkout-fixes. They can learn at that time to get around
>     the error messages by providing --no-cone.
> 
>  3. If users are unaware of the default change and provide directories, then
>     that's where non-cone mode and cone mode overlap and things happen to
>     work. (There is a slight difference in that cone mode will include files
>     from parent directories of any specified directory, but that means the
>     user gets a few more files in their sparse-checkout with cone mode than
>     they would with non-cone mode.)
> 

Agreed with your comments here and Stolee's earlier that changing the
default is a better approach.

> == CCs ==
> 
> Elijah Newren (9):
>   tests: stop assuming --no-cone is the default mode for sparse-checkout
>   sparse-checkout: make --cone the default
>   git-sparse-checkout.txt: wording updates for the cone mode default
>   git-sparse-checkout.txt: update docs for deprecation of 'init'
>   git-sparse-checkout.txt: shuffle some sections and mark as internal
>   git-sparse-checkout.txt: add a new EXAMPLES section
>   git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a
>     bit
>   git-sparse-checkout.txt: mark non-cone mode as deprecated
>   Documentation: some sparsity wording clarifications
> 
>  Documentation/git-read-tree.txt       |   9 +-
>  Documentation/git-sparse-checkout.txt | 249 +++++++++++++++++++-------
>  builtin/sparse-checkout.c             |   2 +-
>  t/t1091-sparse-checkout-builtin.sh    |  15 +-
>  t/t3602-rm-sparse-checkout.sh         |   6 +-
>  t/t3705-add-sparse-checkout.sh        |   4 +-
>  t/t6428-merge-conflicts-sparse.sh     |   4 +-
>  t/t7002-mv-sparse-checkout.sh         |   2 +-
>  t/t7012-skip-worktree-writing.sh      |   2 +-
>  9 files changed, 207 insertions(+), 86 deletions(-)
> 
> 
> base-commit: 1a4874565fa3b6668042216189551b98b4dc0b1b
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1148%2Fnewren%2Fsparse-checkout-default-v2
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1148/newren/sparse-checkout-default-v2
> Pull-Request: https://github.com/gitgitgadget/git/pull/1148
> 
> Range-diff vs v1:
> 
>   1:  8c3e730e86b =  1:  05dba7069c5 tests: stop assuming --no-cone is the default mode for sparse-checkout
>   2:  b174b42ed82 !  2:  a53179764bc sparse-checkout: make --cone the default
>      @@ builtin/sparse-checkout.c: static int update_modes(int *cone_mode, int *sparse_i
>        	/* Set cone/non-cone mode appropriately */
>        	core_apply_sparse_checkout = 1;
>       -	if (*cone_mode == 1) {
>      -+	if (*cone_mode == 1 || *cone_mode == -1) {
>      ++	if (*cone_mode) { /* also handles "not specified" (value of -1) */
>        		mode = MODE_CONE_PATTERNS;
>        		core_sparse_checkout_cone = 1;
>        	} else {
>   3:  f98b3fac78a =  3:  8eab21996c7 git-sparse-checkout.txt: wording updates for the cone mode default
>   4:  cd871966c06 =  4:  eb3b318b39e git-sparse-checkout.txt: update docs for deprecation of 'init'
>   5:  fe37a966699 =  5:  7333198b778 git-sparse-checkout.txt: shuffle some sections and mark as internal
>   6:  3265f41bcab !  6:  a814ea9e8d2 git-sparse-checkout.txt: add a new EXAMPLES section
>      @@ Documentation/git-sparse-checkout.txt: paths to pass to a subsequent 'set' or 'a
>       +
>       +`git sparse-checkout reapply`::
>       +
>      -+	It is possible for commands to update the working tree in a way
>      -+	that does not respect the selected sparsity directories, either
>      -+	because of special cases (such as hitting conflicts when
>      -+	merging/rebasing), or because some commands didn't fully support
>      -+	sparse checkouts (e.g. the old `recursive` merge backend had
>      -+	only limited support).  This command reapplies the existing
>      -+	sparse directory specifications to make the working directory
>      -+	match.
>      ++	It is possible for commands to update the working tree in a
>      ++	way that does not respect the selected sparsity directories.
>      ++	This can come from tools external to Git writing files, or
>      ++	even affect Git commands because of either special cases (such
>      ++	as hitting conflicts when merging/rebasing), or because some
>      ++	commands didn't fully support sparse checkouts (e.g. the old
>      ++	`recursive` merge backend had only limited support).  This
>      ++	command reapplies the existing sparse directory specifications
>      ++	to make the working directory match.
>       +
>        INTERNALS -- SPARSE CHECKOUT
>        ----------------------------
>   7:  bdbf61ee6a0 =  7:  78028ecaa58 git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a bit
>   8:  3e35d62c5ee =  8:  2d2b81986a5 git-sparse-checkout.txt: mark non-cone mode as deprecated
>   9:  e7d3ff70914 =  9:  4b89a3392b0 Documentation: some sparsity wording clarifications
> 

Re: [PATCH v2 0/9] sparse-checkout: make cone mode the default

[Junio C Hamano]

"Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:

> == Updates Log ==
>
> Changes since v1:
>
>  * rebased on master, to remove dependence on en/present-despite-skipped
>    (which has since merged to master). Earlier version of series wasn't
>    picked up anyway, so rebasing should be safe.
>  * Wording and code style tweaks suggested by Stolee in his review
>
> == Overview ==
>
> This patch changes the default mode for sparse-checkout from non-cone mode
> to cone-mode, and marks non-cone mode as deprecated. There is no plan to
> remove non-cone mode, we are merely recommending against its use.

Hopefully there are some convincing explanation to help users
understand why the cone mode is recommended in the documentation in
these patches.  Was there a discussion on list to give our unanimous
support for this plan, or is this only preference by a developer or
two who have worked on the sparse-checkout code recently?

Re: [PATCH v2 1/9] tests: stop assuming --no-cone is the default mode for sparse-checkout

[Junio C Hamano]

"Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Elijah Newren <newren@gmail.com>
>
> Add an explicit --no-cone to several sparse-checkout invocations in
> preparation for changing the default to cone mode.

"several"?

After this step, wouldn't it be a bug if in t/ there still are
"sparse-checkout init" or "sparse-checkout set" invocations for a
given test repository for the first time that do not mention
"--cone" or "--no-cone"?

I am mostly asking for the criteria for reviewers to decide if they
spotted a bug or if it is expected omission when they spot, say,
"sparse-checkout init" without either.

> Signed-off-by: Elijah Newren <newren@gmail.com>
> ---
>  t/t1091-sparse-checkout-builtin.sh | 15 ++++++++-------
>  t/t3602-rm-sparse-checkout.sh      |  6 +++---
>  t/t3705-add-sparse-checkout.sh     |  4 ++--
>  t/t6428-merge-conflicts-sparse.sh  |  4 ++--
>  t/t7002-mv-sparse-checkout.sh      |  2 +-
>  t/t7012-skip-worktree-writing.sh   |  2 +-
>  6 files changed, 17 insertions(+), 16 deletions(-)
>
> diff --git a/t/t1091-sparse-checkout-builtin.sh b/t/t1091-sparse-checkout-builtin.sh
> index 9a900310186..de1ec89007d 100755
> --- a/t/t1091-sparse-checkout-builtin.sh
> +++ b/t/t1091-sparse-checkout-builtin.sh
> @@ -72,7 +72,7 @@ test_expect_success 'git sparse-checkout list (populated)' '
>  '
>  
>  test_expect_success 'git sparse-checkout init' '
> -	git -C repo sparse-checkout init &&
> +	git -C repo sparse-checkout init --no-cone &&
>  	cat >expect <<-\EOF &&
>  	/*
>  	!/*/
> @@ -111,6 +111,7 @@ test_expect_success 'init with existing sparse-checkout' '
>  
>  test_expect_success 'clone --sparse' '
>  	git clone --sparse "file://$(pwd)/repo" clone &&
> +	git -C clone sparse-checkout reapply --no-cone &&
>  	git -C clone sparse-checkout list >actual &&
>  	cat >expect <<-\EOF &&
>  	/*
> @@ -124,7 +125,7 @@ test_expect_success 'switching to cone mode with non-cone mode patterns' '
>  	git init bad-patterns &&
>  	(
>  		cd bad-patterns &&
> -		git sparse-checkout init &&
> +		git sparse-checkout init --no-cone &&
>  		git sparse-checkout add dir &&
>  		git config --worktree core.sparseCheckoutCone true &&
>  		test_must_fail git sparse-checkout add dir 2>err &&
> @@ -402,7 +403,7 @@ test_expect_success 'revert to old sparse-checkout on empty update' '
>  		git sparse-checkout set nothing 2>err &&
>  		test_i18ngrep ! "Sparse checkout leaves no entry on working directory" err &&
>  		test_i18ngrep ! ".git/index.lock" err &&
> -		git sparse-checkout set file
> +		git sparse-checkout set --no-cone file
>  	)
>  '
>  
> @@ -424,7 +425,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with dirty status'
>  	git clone repo dirty &&
>  	echo dirty >dirty/folder1/a &&
>  
> -	git -C dirty sparse-checkout init 2>err &&
> +	git -C dirty sparse-checkout init --no-cone 2>err &&
>  	test_i18ngrep "warning.*The following paths are not up to date" err &&
>  
>  	git -C dirty sparse-checkout set /folder2/* /deep/deeper1/* 2>err &&
> @@ -435,7 +436,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with dirty status'
>  	test_must_be_empty err &&
>  
>  	git -C dirty reset --hard &&
> -	git -C dirty sparse-checkout init &&
> +	git -C dirty sparse-checkout init --no-cone &&
>  	git -C dirty sparse-checkout set /folder2/* /deep/deeper1/* &&
>  	test_path_is_missing dirty/folder1/a &&
>  	git -C dirty sparse-checkout disable &&
> @@ -451,7 +452,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with unmerged stat
>  	EOF
>  	git -C unmerged update-index --index-info <input &&
>  
> -	git -C unmerged sparse-checkout init 2>err &&
> +	git -C unmerged sparse-checkout init --no-cone 2>err &&
>  	test_i18ngrep "warning.*The following paths are unmerged" err &&
>  
>  	git -C unmerged sparse-checkout set /folder2/* /deep/deeper1/* 2>err &&
> @@ -462,7 +463,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with unmerged stat
>  	test_i18ngrep "warning.*The following paths are unmerged" err &&
>  
>  	git -C unmerged reset --hard &&
> -	git -C unmerged sparse-checkout init &&
> +	git -C unmerged sparse-checkout init --no-cone &&
>  	git -C unmerged sparse-checkout set /folder2/* /deep/deeper1/* &&
>  	git -C unmerged sparse-checkout disable
>  '
> diff --git a/t/t3602-rm-sparse-checkout.sh b/t/t3602-rm-sparse-checkout.sh
> index 034ec010910..08580fd3dcc 100755
> --- a/t/t3602-rm-sparse-checkout.sh
> +++ b/t/t3602-rm-sparse-checkout.sh
> @@ -30,7 +30,7 @@ test_expect_success 'setup' "
>  for opt in "" -f --dry-run
>  do
>  	test_expect_success "rm${opt:+ $opt} does not remove sparse entries" '
> -		git sparse-checkout set a &&
> +		git sparse-checkout set --no-cone a &&
>  		test_must_fail git rm $opt b 2>stderr &&
>  		test_cmp b_error_and_hint stderr &&
>  		git ls-files --error-unmatch b
> @@ -118,7 +118,7 @@ test_expect_success 'can remove files from non-sparse dir' '
>  	test_commit w/f &&
>  	test_commit x/y/f &&
>  
> -	git sparse-checkout set w !/x y/ &&
> +	git sparse-checkout set --no-cone w !/x y/ &&
>  	git rm w/f.t x/y/f.t 2>stderr &&
>  	test_must_be_empty stderr
>  '
> @@ -128,7 +128,7 @@ test_expect_success 'refuse to remove non-skip-worktree file from sparse dir' '
>  	git sparse-checkout disable &&
>  	mkdir -p x/y/z &&
>  	test_commit x/y/z/f &&
> -	git sparse-checkout set !/x y/ !x/y/z &&
> +	git sparse-checkout set --no-cone !/x y/ !x/y/z &&
>  
>  	git update-index --no-skip-worktree x/y/z/f.t &&
>  	test_must_fail git rm x/y/z/f.t 2>stderr &&
> diff --git a/t/t3705-add-sparse-checkout.sh b/t/t3705-add-sparse-checkout.sh
> index 95609046c61..2bade9e804f 100755
> --- a/t/t3705-add-sparse-checkout.sh
> +++ b/t/t3705-add-sparse-checkout.sh
> @@ -166,7 +166,7 @@ test_expect_success 'do not warn when pathspec matches dense entries' '
>  test_expect_success 'git add fails outside of sparse-checkout definition' '
>  	test_when_finished git sparse-checkout disable &&
>  	test_commit a &&
> -	git sparse-checkout init &&
> +	git sparse-checkout init --no-cone &&
>  	git sparse-checkout set a &&
>  	echo >>sparse_entry &&
>  
> @@ -208,7 +208,7 @@ test_expect_success 'add obeys advice.updateSparsePath' '
>  '
>  
>  test_expect_success 'add allows sparse entries with --sparse' '
> -	git sparse-checkout set a &&
> +	git sparse-checkout set --no-cone a &&
>  	echo modified >sparse_entry &&
>  	test_must_fail git add sparse_entry &&
>  	test_sparse_entry_unchanged &&
> diff --git a/t/t6428-merge-conflicts-sparse.sh b/t/t6428-merge-conflicts-sparse.sh
> index 142c9aaabc5..064be1b629e 100755
> --- a/t/t6428-merge-conflicts-sparse.sh
> +++ b/t/t6428-merge-conflicts-sparse.sh
> @@ -87,7 +87,7 @@ test_expect_success 'conflicting entries written to worktree even if sparse' '
>  		test_path_is_file numerals &&
>  
>  		git sparse-checkout init &&
> -		git sparse-checkout set README &&
> +		git sparse-checkout set --no-cone README &&
>  
>  		test_path_is_file README &&
>  		test_path_is_missing numerals &&
> @@ -123,7 +123,7 @@ test_expect_success 'present-despite-SKIP_WORKTREE handled reasonably' '
>  		test_path_is_file numerals &&
>  
>  		git sparse-checkout init &&
> -		git sparse-checkout set README &&
> +		git sparse-checkout set --no-cone README &&
>  
>  		test_path_is_file README &&
>  		test_path_is_missing numerals &&
> diff --git a/t/t7002-mv-sparse-checkout.sh b/t/t7002-mv-sparse-checkout.sh
> index 1d3d2aca21c..f0f7cbfcdb7 100755
> --- a/t/t7002-mv-sparse-checkout.sh
> +++ b/t/t7002-mv-sparse-checkout.sh
> @@ -27,7 +27,7 @@ test_expect_success 'setup' "
>  test_expect_success 'mv refuses to move sparse-to-sparse' '
>  	test_when_finished rm -f e &&
>  	git reset --hard &&
> -	git sparse-checkout set a &&
> +	git sparse-checkout set --no-cone a &&
>  	touch b &&
>  	test_must_fail git mv b e 2>stderr &&
>  	cat sparse_error_header >expect &&
> diff --git a/t/t7012-skip-worktree-writing.sh b/t/t7012-skip-worktree-writing.sh
> index cb9f1a6981e..cd5c20fe51b 100755
> --- a/t/t7012-skip-worktree-writing.sh
> +++ b/t/t7012-skip-worktree-writing.sh
> @@ -151,7 +151,7 @@ test_expect_success 'stash restore in sparse checkout' '
>  
>  		git stash push &&
>  
> -		git sparse-checkout set subdir &&
> +		git sparse-checkout set --no-cone subdir &&
>  
>  		# Ensure after sparse-checkout we only have expected files
>  		cat >expect <<-EOF &&

Re: [PATCH v2 2/9] sparse-checkout: make --cone the default

[Junio C Hamano]

"Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:

>  The subset of files is chosen by providing a list of directories in
> -cone mode (which is recommended), or by providing a list of patterns
> -in non-cone mode.
> +cone mode (the default), or by providing a list of patterns in
> +non-cone mode.

OK.

> @@ -60,7 +60,7 @@ When the `--stdin` option is provided, the directories or patterns are
>  read from standard in as a newline-delimited list instead of from the
>  arguments.
>  +
> -When `--cone` is passed or `core.sparseCheckoutCone` is enabled, the
> +When `--cone` is passed or `core.sparseCheckoutCone` is not false, the
>  input list is considered a list of directories.  This allows for


I expected a change to Documentation/config/core.txt in this step,
because the default value for core.sparseCheckoutCone becomes true
if unspecified with this step, and the normal expectation by the
readers is what is not explicitly set to true is either 'false' or
'unspecified' (when 'unspecified' has its own meaning, like in
gitattributes).

Something like this?

diff --git i/Documentation/config/core.txt w/Documentation/config/core.txt
index c04f62a54a..03cf075821 100644
--- i/Documentation/config/core.txt
+++ w/Documentation/config/core.txt
@@ -615,8 +615,10 @@ core.sparseCheckout::
 
 core.sparseCheckoutCone::
 	Enables the "cone mode" of the sparse checkout feature. When the
-	sparse-checkout file contains a limited set of patterns, then this
-	mode provides significant performance advantages. See
+	sparse-checkout file contains a limited set of patterns, this
+	mode provides significant performance advantages. The "non
+	cone mode" can be requested to allow specifying a more flexible
+	patterns by setting this variable to 'false'. See
 	linkgit:git-sparse-checkout[1] for more information.
 
 core.abbrev::

> -When `--no-cone` is passed or `core.sparseCheckoutCone` is not enabled,
> +When `--no-cone` is passed or `core.sparseCheckoutCone` is false,

"is set to 'false'" would make it clearer.

> +If `core.sparseCheckoutCone=true` (set by default or with an explicit
> +`--cone`), then Git will parse the sparse-checkout file expecting

"Unless `core.sparseCheckoutCone` is explicitly set to `false`"
might be clearer, but I am not sure.  It is just that I found the
phrase "set by default" confusing.

>  	/* Set cone/non-cone mode appropriately */
>  	core_apply_sparse_checkout = 1;
> -	if (*cone_mode == 1) {
> +	if (*cone_mode) { /* also handles "not specified" (value of -1) */

The comment is correct, but if we can make the code not to require
such a comment, that would be even better.  Are there very small
number of choke points where we always pass, after parsing
configuration variables and options, that we ought to know which
mode to use before the control comes here, and commit the choice
with "if (cone_mode < 0) cone_mode = 1"?

We see beyond precontext of this hunk an assignment to *cone_mode to
tell the choice we made to our caller.  Shouldn't we be doing the
same in this if/else that still assumes we can get "undecided"?

>  		mode = MODE_CONE_PATTERNS;
>  		core_sparse_checkout_cone = 1;
>  	} else {

Re: [PATCH v2 3/9] git-sparse-checkout.txt: wording updates for the cone mode default

[Junio C Hamano]

"Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Elijah Newren <newren@gmail.com>
>
> Now that cone mode is the default, we'd like to focus on the arguments
> to set/add being directories rather than patterns, and it probably makes
> sense to provide an earlier heads up that files from leading directories
> get included as well.

Looking good.

Re: [PATCH v2 4/9] git-sparse-checkout.txt: update docs for deprecation of 'init'

[Junio C Hamano]

"Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:

> -When `--no-cone` is passed or `core.sparseCheckoutCone` is false,
> -the input list is considered a list of patterns.  This mode is harder
> -to use and less performant, and is thus not recommended.  See the
> -"Sparse Checkout" section of linkgit:git-read-tree[1] and the "Pattern
> -Set" sections below for more details.
> +When `--no-cone` is passed, the input list is considered a list of
> +patterns.  This mode is harder to use and less performant, and is thus

"less perfromant" can be quantified, but "harder to use" is probably
harder to defend.  Those on a project with need for more flexible
way to specify than "these are the directories I care about" would
not find it convincing.

> +not recommended.  See the "Sparse Checkout" section of
> +linkgit:git-read-tree[1]

The referenced section (I am reading "git read-tree --help" from
seen with these patches) may need updating.  It shows an example
of including everything except for unwanted, without mentioning
if that is for cone or non-cone.

> and the "Pattern Set" sections below for more
> +details.

Are we referring to "Internals - cone/full pattern set" sections?

This may be a topic of another step in this series, but the "core"
section starts by mentioning what characteristics the full pattern
set has and uses it to steer readers away from it, which I find it
less than ideal.  As we present "core" first (because it is the
default), we should present "core" by itself, without requiring to
know what the other thing is.  Perhaps replace the entire first
paragraph so that the section begins more like so:

	The "cone mode", which is the default, lets you specify only
	what directories to include and what directories to exclude.

	The accepted patterns in the cone pattern set are:...

Especially, the last sentence in the paragraph to be struck still
lives in the old world in which you needed to opt into the cone
mode.

Thanks.

Re: [PATCH v2 5/9] git-sparse-checkout.txt: shuffle some sections and mark as internal

[Junio C Hamano]

"Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:

> -CONE PATTERN SET
> -----------------
> +INTERNALS -- CONE PATTERN SET
> +-----------------------------

Ah, this is why I was confused during my review of an earlier step,
where it refered to this (and the other) sections as "sections on
'pattern set'", because I was reading the end-result of applying the
whole series.

With this change, shouldn't the reference be updated?

Re: [PATCH v2 7/9] git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a bit

[Junio C Hamano]

"Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:

>  INTERNALS -- FULL PATTERN SET
>  -----------------------------
>  
> -By default, the sparse-checkout file uses the same syntax as `.gitignore`
> -files.
> -
> -While `$GIT_DIR/info/sparse-checkout` is usually used to specify what
> -files are included, you can also specify what files are _not_ included,
> -using negative patterns. For example, to remove the file `unwanted`:
> +As noted above, the sparse-checkout file uses the same syntax as
> +`.gitignore` files; see linkgit:gitignore[5] for details.  Here,

Here, following the suggestion to fix the early part of "Cone mode
patterns" section, move the "it is more flexible but requires more
cycles to process" you had there to replace the "As noted above".

Re: [PATCH v2 8/9] git-sparse-checkout.txt: mark non-cone mode as deprecated

[Junio C Hamano]

"Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:

> +the default mode, but we do not recommend using it.  It does not work
> +with the `--sparse-index` option, and will likely be incompatible with
> +other new features as they are added.

If we explicitly say we have no intention to remove, while saying
that "non-cone" mode is a second class citizen, the users would be
confused. Does this mixed attitude only apply to non-cone mode, or
is it true for any other fringe features that we do not care about
in Git?

This does not build confidence with the Git software suite.  If we
are removing, then this attitude is OK, but if we are keeping it,
then we should promise that we never add features only to "cone".

> +INTERNALS -- NON-CONE PROBLEMS
> +------------------------------
> +
> +The `$GIT_DIR/info/sparse-checkout` file populated by the `set` and
> +`add` subcommands is defined to be a bunch of patterns (one per line)
> +using the same syntax as `.gitignore` files.  In cone mode, these
> +patterns are restricted to matching directories (and users only ever
> +need supply or see directory names), while in non-cone mode any
> +gitignore-style pattern is permitted.  Using the full gitignore-style
> +patterns in non-cone mode has a number of shortcomings:
> +
> +  * Fundamentally, it makes various worktree-updating processes (pull,
> +    merge, rebase, switch, reset, checkout, etc.) require O(N*M) pattern
> +    matches, where N is the number of patterns and M is the number of
> +    paths in the index.  This scales poorly.
> +
> +  * Avoiding the scaling issue has to be done via limiting the number
> +    of patterns via specifying leading directory name or glob.

These are valid.

> +  * Passing globs on the command line is error-prone as users may
> +    forget to quote the glob, causing the shell to expand it into all
> +    matching files and pass them all individually along to
> +    sparse-checkout set/add.  This both exacerbates the scaling
> +    problem, and hardcodes the list of selected files to those which
> +    were present at the time the initial set/add subcommand was run
> +    (and thus ignoring other files matching the same glob which come
> +    into the working tree after switching branches or pulling down
> +    updates).

That's end-user mistakes that is common to other things like
pathspecs, i.e. "git grep -- \*.c" vs "git grep -- *.c".  It hardly
deserves to spend more than 5 lines shouting.

> +  * It uses "ignore"/"exclude" syntax for selecting what to "include",
> +    which periodically causes confusion.

Well, .gitignore uses the syntax to select the paths to include or
exclude from a set, and then the set specifies what is left out of
the index.  I am not sure if that is the source of confusion.

> +  * It introduces inconsistencies in the Git command line, since other
> +    commands use pathspecs, but sparse-checkout (in non-cone mode) uses
> +    gitignore patterns.

But "cone" mode does not take pathspec, does it?  ":(icase)/A/B/C"
for example?  I do not see this as a credible argument against it.

> +  * It has edge cases where the "right" behavior is unclear.  Two examples:
> +
> +    First, two users are in a subdirectory, and the first runs
> +       git sparse-checkout set '/toplevel-dir/*.c'
> +    while the second runs
> +       git sparse-checkout set relative-dir

Are we aware which mode of sparse-checkout they are in?  Do we give
a mechanism for users to ask "we have 'non-cone' sparse checkout in
the sparse-checkout file.  we want to use the more efficient and
recommended 'cone' mode.  Please convert it", or even if there is
not an automated conversion mechansim, can the user manually do so
(which I suspect is not fundamentally possible---the cone mode is
inherently less expressive)?

If not, then we should expect these two users to _know_ (or at least
check before they run "set" subcommand) which mode is in use.

So, with that expectation,

> +    Should those arguments be transliterated into
> +       current/subdirectory/toplevel-dir/*.c
> +    and
> +       current/subdirectory/relative-dir

If we are using non-cone mode, then both would be recorded as-is.

If we are using cone mode, we may reject the one that ends with "*.c"
based on the two traits it has, i.e. (1) there is no such directory
in the working tree nor the index nor the HEAD, and (2) it has an
unusual character (i.e. glob) '*' to be in a real path.

Re: [PATCH v2 0/9] sparse-checkout: make cone mode the default

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> "Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> == Updates Log ==
>>
>> Changes since v1:
>>
>>  * rebased on master, to remove dependence on en/present-despite-skipped
>>    (which has since merged to master). Earlier version of series wasn't
>>    picked up anyway, so rebasing should be safe.
>>  * Wording and code style tweaks suggested by Stolee in his review
>>
>> == Overview ==
>>
>> This patch changes the default mode for sparse-checkout from non-cone mode
>> to cone-mode, and marks non-cone mode as deprecated. There is no plan to
>> remove non-cone mode, we are merely recommending against its use.
>
> Hopefully there are some convincing explanation to help users
> understand why the cone mode is recommended in the documentation in
> these patches.  Was there a discussion on list to give our unanimous
> support for this plan, or is this only preference by a developer or
> two who have worked on the sparse-checkout code recently?

OK.  There are a few things that I found questionable, but they were
mostly documentation issues (and lack of updates to two places, one
in read-tree and the other in config/core.txt).

Thanks.

Re: [PATCH v2 1/9] tests: stop assuming --no-cone is the default mode for sparse-checkout

[Derrick Stolee]

On 3/14/2022 4:18 PM, Junio C Hamano wrote:
> "Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
>> From: Elijah Newren <newren@gmail.com>
>>
>> Add an explicit --no-cone to several sparse-checkout invocations in
>> preparation for changing the default to cone mode.
> 
> "several"?
> 
> After this step, wouldn't it be a bug if in t/ there still are
> "sparse-checkout init" or "sparse-checkout set" invocations for a
> given test repository for the first time that do not mention
> "--cone" or "--no-cone"?
> 
> I am mostly asking for the criteria for reviewers to decide if they
> spotted a bug or if it is expected omission when they spot, say,
> "sparse-checkout init" without either.

There are some "git sparse-checkout init" runs without the
--no-cone, but since they are followed by a "set --no-cone",
the difference is not important. Perhaps, as a later cleanup,
we could go in and delete those "init" calls.

Thanks,
-Stolee

Re: [PATCH v2 2/9] sparse-checkout: make --cone the default

[Elijah Newren]

Sorry for the long delay...

On Mon, Mar 14, 2022 at 1:34 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> "Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> >  The subset of files is chosen by providing a list of directories in
> > -cone mode (which is recommended), or by providing a list of patterns
> > -in non-cone mode.
> > +cone mode (the default), or by providing a list of patterns in
> > +non-cone mode.
>
> OK.
>
> > @@ -60,7 +60,7 @@ When the `--stdin` option is provided, the directories or patterns are
> >  read from standard in as a newline-delimited list instead of from the
> >  arguments.
> >  +
> > -When `--cone` is passed or `core.sparseCheckoutCone` is enabled, the
> > +When `--cone` is passed or `core.sparseCheckoutCone` is not false, the
> >  input list is considered a list of directories.  This allows for
>
>
> I expected a change to Documentation/config/core.txt in this step,
> because the default value for core.sparseCheckoutCone becomes true
> if unspecified with this step, and the normal expectation by the
> readers is what is not explicitly set to true is either 'false' or
> 'unspecified' (when 'unspecified' has its own meaning, like in
> gitattributes).
>
> Something like this?
>
> diff --git i/Documentation/config/core.txt w/Documentation/config/core.txt
> index c04f62a54a..03cf075821 100644
> --- i/Documentation/config/core.txt
> +++ w/Documentation/config/core.txt
> @@ -615,8 +615,10 @@ core.sparseCheckout::
>
>  core.sparseCheckoutCone::
>         Enables the "cone mode" of the sparse checkout feature. When the
> -       sparse-checkout file contains a limited set of patterns, then this
> -       mode provides significant performance advantages. See
> +       sparse-checkout file contains a limited set of patterns, this
> +       mode provides significant performance advantages. The "non
> +       cone mode" can be requested to allow specifying a more flexible
> +       patterns by setting this variable to 'false'. See
>         linkgit:git-sparse-checkout[1] for more information.
>
>  core.abbrev::
>
> > -When `--no-cone` is passed or `core.sparseCheckoutCone` is not enabled,
> > +When `--no-cone` is passed or `core.sparseCheckoutCone` is false,
>
> "is set to 'false'" would make it clearer.
>
> > +If `core.sparseCheckoutCone=true` (set by default or with an explicit
> > +`--cone`), then Git will parse the sparse-checkout file expecting
>
> "Unless `core.sparseCheckoutCone` is explicitly set to `false`"
> might be clearer, but I am not sure.  It is just that I found the
> phrase "set by default" confusing.

Thanks; I applied all three suggestions.

> >       /* Set cone/non-cone mode appropriately */
> >       core_apply_sparse_checkout = 1;
> > -     if (*cone_mode == 1) {
> > +     if (*cone_mode) { /* also handles "not specified" (value of -1) */
>
> The comment is correct, but if we can make the code not to require
> such a comment, that would be even better.

I had that in v1; I'll revert back to it.

Re: [PATCH v2 4/9] git-sparse-checkout.txt: update docs for deprecation of 'init'

[Elijah Newren]

On Mon, Mar 14, 2022 at 1:53 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> "Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > -When `--no-cone` is passed or `core.sparseCheckoutCone` is false,
> > -the input list is considered a list of patterns.  This mode is harder
> > -to use and less performant, and is thus not recommended.  See the
> > -"Sparse Checkout" section of linkgit:git-read-tree[1] and the "Pattern
> > -Set" sections below for more details.
> > +When `--no-cone` is passed, the input list is considered a list of
> > +patterns.  This mode is harder to use and less performant, and is thus
>
> "less perfromant" can be quantified, but "harder to use" is probably
> harder to defend.  Those on a project with need for more flexible
> way to specify than "these are the directories I care about" would
> not find it convincing.

That text wasn't added by this patch (or even by any patch in this
series); it was in the pre-image.  I can still change it, of course,
but I don't think it belongs in this particular patch.  How about I
replace this text in 8/9 with a link to the new section that was added
(the one that explains the problems we see with non-cone mode).

> > +not recommended.  See the "Sparse Checkout" section of
> > +linkgit:git-read-tree[1]
>
> The referenced section (I am reading "git read-tree --help" from
> seen with these patches) may need updating.  It shows an example
> of including everything except for unwanted, without mentioning
> if that is for cone or non-cone.

I wouldn't really say that the example is for either mode (the point
of the sparse-checkout command is so users don't need to directly edit
the $GIT_DIR/info/sparse-checkout file), but the examples might be
useful for people trying to understand the patterns used in non-cone
mode.  Perhaps this change would be helpful?:

diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index 99bb387134..0eae9e01fd 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -378,7 +378,9 @@ SPARSE CHECKOUT
 Note: The `update-index` and `read-tree` primitives for supporting the
 skip-worktree bit predated the introduction of
 linkgit:git-sparse-checkout[1].  Users are encouraged to use
-`sparse-checkout` in preference to these low-level primitives.
+`sparse-checkout` in preference to these low-level primitives.  However,
+the information below might be useful to users trying to understand the
+pattern style used in non-cone mode of the `sparse-checkout` command.

However, I don't think that belongs in this patch (since you were
commenting on text that only appeared in the diff due to reflowing
paragraphs), but I can add it to 9/9.

> > and the "Pattern Set" sections below for more
> > +details.
>
> Are we referring to "Internals - cone/full pattern set" sections?

Yeah, as you noted in a later patch, you got confused by looking at
the end result rather than the state of the tree as of this patch.
The "Internals -" prefix was added in a later patch.

> This may be a topic of another step in this series, but the "core"
> section starts by mentioning what characteristics the full pattern
> set has and uses it to steer readers away from it, which I find it
> less than ideal.  As we present "core" first (because it is the
> default), we should present "core" by itself, without requiring to
> know what the other thing is.

By '"core" section' do you mean the "cone pattern set" section?
That's my best guess after several comparisons.  I agree that it's
less than ideal, though I thought that perhaps adding the "Internals"
prefix would allow folks to just ignore it.  But you may be right that
I should also overhaul it a bit, maybe splitting it into two sections,
one about some implementation details about the mode, and another
later section about how the patterns in cone mode are a strictly
controlled subset of the possible full pattern set.  However, I think
that'd go better in patch 7 rather than here.

>  Perhaps replace the entire first
> paragraph so that the section begins more like so:
>
>         The "cone mode", which is the default, lets you specify only
>         what directories to include and what directories to exclude.

There's no provision to specify individual directories to exclude,
only which to include.  Everything not listed is excluded.

>         The accepted patterns in the cone pattern set are:...
>
> Especially, the last sentence in the paragraph to be struck still
> lives in the old world in which you needed to opt into the cone
> mode.

This patch didn't strike any paragraph, so I'm not sure which sentence
you're referring to.  I tried looking around, and didn't readily find
it either.  Perhaps my big reshufflings in my new patch 7 addressed
what you're talking about, though?

Re: [PATCH v2 5/9] git-sparse-checkout.txt: shuffle some sections and mark as internal

[Elijah Newren]

On Mon, Mar 14, 2022 at 1:55 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> "Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > -CONE PATTERN SET
> > -----------------
> > +INTERNALS -- CONE PATTERN SET
> > +-----------------------------
>
> Ah, this is why I was confused during my review of an earlier step,
> where it refered to this (and the other) sections as "sections on
> 'pattern set'", because I was reading the end-result of applying the
> whole series.
>
> With this change, shouldn't the reference be updated?

Makes sense; will do.

Re: [PATCH v2 7/9] git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a bit

[Elijah Newren]

On Mon, Mar 14, 2022 at 1:57 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> "Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> >  INTERNALS -- FULL PATTERN SET
> >  -----------------------------
> >
> > -By default, the sparse-checkout file uses the same syntax as `.gitignore`
> > -files.
> > -
> > -While `$GIT_DIR/info/sparse-checkout` is usually used to specify what
> > -files are included, you can also specify what files are _not_ included,
> > -using negative patterns. For example, to remove the file `unwanted`:
> > +As noted above, the sparse-checkout file uses the same syntax as
> > +`.gitignore` files; see linkgit:gitignore[5] for details.  Here,
>
> Here, following the suggestion to fix the early part of "Cone mode
> patterns" section, move the "it is more flexible but requires more
> cycles to process" you had there to replace the "As noted above".

Makes sense; I'll restructure it with this and some of the other
modifications you mentioned earlier to simplify the cone mode
discussion.

Re: [PATCH v2 8/9] git-sparse-checkout.txt: mark non-cone mode as deprecated

[Elijah Newren]

On Mon, Mar 14, 2022 at 2:14 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> "Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > +the default mode, but we do not recommend using it.  It does not work
> > +with the `--sparse-index` option, and will likely be incompatible with
> > +other new features as they are added.
>
> If we explicitly say we have no intention to remove, while saying
> that "non-cone" mode is a second class citizen, the users would be
> confused.

I don't see why they'd be confused.  It seems common to me in software
development to state that a less preferred option will continue to be
supported with its existing feature set, while some other option is
both recommended and will gain new features.

> Does this mixed attitude only apply to non-cone mode, or
> is it true for any other fringe features that we do not care about
> in Git?
>
> This does not build confidence with the Git software suite.  If we
> are removing, then this attitude is OK, but if we are keeping it,
> then we should promise that we never add features only to "cone".

The sparse-index feature only works with "cone" mode and adding
support for non-cone mode would be infeasible.  So we've already
crossed that line.

I'd also like to make partial clones and sparse-checkouts work better
together (something you also suggested in the past), and improve
support for disconnected development.  In particular, having a partial
clone that starts with the history of files within the sparse-cone
instead of an empty set of blobs seems like a reasonable way to do
that.  However, having a partial clone that starts with the history of
files matching a non-cone mode set of paths seems intractable to me; I
don't see how that could reasonably be implemented server side and
would expect it to be rejected even if implemented.  So there's at
least one example in my mind where we would want to cross that line
again.

Although, if you really are saying these are the only two acceptable
options to you, then I'll start pushing to remove non-cone mode;
that'd be much preferable to removing the sparse-index feature and
hamstringing future development.

> > +INTERNALS -- NON-CONE PROBLEMS
> > +------------------------------
> > +
> > +The `$GIT_DIR/info/sparse-checkout` file populated by the `set` and
> > +`add` subcommands is defined to be a bunch of patterns (one per line)
> > +using the same syntax as `.gitignore` files.  In cone mode, these
> > +patterns are restricted to matching directories (and users only ever
> > +need supply or see directory names), while in non-cone mode any
> > +gitignore-style pattern is permitted.  Using the full gitignore-style
> > +patterns in non-cone mode has a number of shortcomings:
> > +
> > +  * Fundamentally, it makes various worktree-updating processes (pull,
> > +    merge, rebase, switch, reset, checkout, etc.) require O(N*M) pattern
> > +    matches, where N is the number of patterns and M is the number of
> > +    paths in the index.  This scales poorly.
> > +
> > +  * Avoiding the scaling issue has to be done via limiting the number
> > +    of patterns via specifying leading directory name or glob.
>
> These are valid.
>
> > +  * Passing globs on the command line is error-prone as users may
> > +    forget to quote the glob, causing the shell to expand it into all
> > +    matching files and pass them all individually along to
> > +    sparse-checkout set/add.  This both exacerbates the scaling
> > +    problem, and hardcodes the list of selected files to those which
> > +    were present at the time the initial set/add subcommand was run
> > +    (and thus ignoring other files matching the same glob which come
> > +    into the working tree after switching branches or pulling down
> > +    updates).
>
> That's end-user mistakes that is common to other things like
> pathspecs, i.e. "git grep -- \*.c" vs "git grep -- *.c".  It hardly
> deserves to spend more than 5 lines shouting.

Fair point.

I do think there's still a small qualitative difference, though, in
regards to timing and the ability of the user to discover their
mistake.  With sparse-checkout, the mistake gets recorded and affects
later commands.  In particular, it's possible that at the time the
command is run, the shell completion of the glob catches all currently
existing relevant files, so the user doesn't notice the mistake.  Once
the user switches branches or rebases or merges or whatever, then the
past expansion of the glob finally bites the user.  In contrast, if
the grep/log/status command is wrong, it's noticeable from the
immediate output the user gets and they can simply re-run with the
corrected command.

> > +  * It uses "ignore"/"exclude" syntax for selecting what to "include",
> > +    which periodically causes confusion.
>
> Well, .gitignore uses the syntax to select the paths to include or
> exclude from a set, and then the set specifies what is left out of
> the index.  I am not sure if that is the source of confusion.

Perhaps I should reword this point:

  * .gitignore files use the gitignore pattern syntax to specify
patterns that are *excluded* (unless the pattern is negated) from the
index.
  * non-cone mode sparse-checkout uses the same syntax to specify
patterns with the opposite meaning -- they are *included* in the tree
(unless the pattern is negated).

If there were two copies of the pattern specification, or if the
documentation carefully pointed out matching/non-matching instead of
exclude/include everywhere, then this perhaps wouldn't be a problem.
However, the documentation for these patterns is almost completely
.gitignore-specific and written talking about exclusion (with
inclusion exceptions).

> > +  * It introduces inconsistencies in the Git command line, since other
> > +    commands use pathspecs, but sparse-checkout (in non-cone mode) uses
> > +    gitignore patterns.
>
> But "cone" mode does not take pathspec, does it?  ":(icase)/A/B/C"
> for example?  I do not see this as a credible argument against it.

My objection is that it's weird having two different forms of "special
path pattern matching" in the git command line.  Every git subcommand
that has such a thing uses pathspecs, except for non-cone mode
sparse-checkout.

I don't see why any subcommand necessarily needs to have "special path
pattern matching", I'm just saying that *if* some subcommand does have
such a thing, it'd be nice to use the same kind of special path
pattern matching that all other git commands do.

> > +  * It has edge cases where the "right" behavior is unclear.  Two examples:
> > +
> > +    First, two users are in a subdirectory, and the first runs
> > +       git sparse-checkout set '/toplevel-dir/*.c'
> > +    while the second runs
> > +       git sparse-checkout set relative-dir
>
> Are we aware which mode of sparse-checkout they are in?  Do we give
> a mechanism for users to ask "we have 'non-cone' sparse checkout in
> the sparse-checkout file.  we want to use the more efficient and
> recommended 'cone' mode.  Please convert it", or even if there is
> not an automated conversion mechansim, can the user manually do so
> (which I suspect is not fundamentally possible---the cone mode is
> inherently less expressive)?
>
> If not, then we should expect these two users to _know_ (or at least
> check before they run "set" subcommand) which mode is in use.
>
> So, with that expectation,
>
> > +    Should those arguments be transliterated into
> > +       current/subdirectory/toplevel-dir/*.c
> > +    and
> > +       current/subdirectory/relative-dir
>
> If we are using non-cone mode, then both would be recorded as-is.

Recording '/toplevel-dir/*.c' and 'relative-dir' as-is sounds great to
me, but doesn't it run contrary to what you previously pushed for
tab-completion?  Previously, you said that in non-cone mode, tab
completion should complete on files and directories (with no "relative
to the toplevel directory" qualification that I could see), which does
not seem to work well with what you've specified here.

[PATCH v3 0/9] sparse-checkout: make cone mode the default

[Elijah Newren via GitGitGadget]

Sorry for the long delay since v1. On the plus side, perhaps there will be a
longer feedback period for this series since it's now really early in the
2.37 series?

== Updates Log ==

Changes since v2:

 * Code style tweak suggested by Junio in one area, reverting back to v1.
 * Several documentation updates to address Junio's review. Patches 6 & 7
   had significant changes and would most benefit from a further review.

Changes since v1:

 * rebased on master, to remove dependence on en/present-despite-skipped
   (which has since merged to master). Earlier version of series wasn't
   picked up anyway, so rebasing should be safe.
 * Wording and code style tweaks suggested by Stolee in his review

== Overview ==

This patch changes the default mode for sparse-checkout from non-cone mode
to cone-mode, and marks non-cone mode as deprecated. There is no plan to
remove non-cone mode, we are merely recommending against its use.

The code change is pretty small, and most of this series is about
documentation updates -- to focus on directories rather than patterns, to
explain the new default, to explain why we are deprecating non-cone mode
(the final patch), and to make other related cleanups to simplify the
manual.

Patch 1: Update tests to not assume cone-mode is the default Patch 2: Make
cone-mode the default Patches 3-9: Various updates to
git-sparse-checkout.txt, divided up for ease of review

== Alternative ==

There is one primary alternative to this series: make sparse-checkout error
when neither --cone nor --no-cone are specified (so that there is no
default), and wait until a future date to make --cone the default. That'd be
reasonable, but I had three reason to avoid going this route (note that item
2 means there's little practical difference between cone-mode-as-default and
no-mode-is-default):

 1. git-sparse-checkout.txt has the following huge warning early in the
    manual:

""" THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR, AND THE BEHAVIOR OF OTHER
COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN THE
FUTURE. """

 2. If users are unaware of the default change and attempt to provide
    patterns instead of directories, then they will get error messages added
    from en/sparse-checkout-fixes. They can learn at that time to get around
    the error messages by providing --no-cone.

 3. If users are unaware of the default change and provide directories, then
    that's where non-cone mode and cone mode overlap and things happen to
    work. (There is a slight difference in that cone mode will include files
    from parent directories of any specified directory, but that means the
    user gets a few more files in their sparse-checkout with cone mode than
    they would with non-cone mode.)

== CCs ==

Elijah Newren (9):
  tests: stop assuming --no-cone is the default mode for sparse-checkout
  sparse-checkout: make --cone the default
  git-sparse-checkout.txt: wording updates for the cone mode default
  git-sparse-checkout.txt: update docs for deprecation of 'init'
  git-sparse-checkout.txt: shuffle some sections and mark as internal
  git-sparse-checkout.txt: add a new EXAMPLES section
  git-sparse-checkout.txt: flesh out pattern set sections a bit
  git-sparse-checkout.txt: mark non-cone mode as deprecated
  Documentation: some sparsity wording clarifications

 Documentation/config/core.txt         |   6 +-
 Documentation/git-read-tree.txt       |  11 +-
 Documentation/git-sparse-checkout.txt | 317 +++++++++++++++++++-------
 builtin/sparse-checkout.c             |   2 +-
 t/t1091-sparse-checkout-builtin.sh    |  15 +-
 t/t3602-rm-sparse-checkout.sh         |   6 +-
 t/t3705-add-sparse-checkout.sh        |   4 +-
 t/t6428-merge-conflicts-sparse.sh     |   4 +-
 t/t7002-mv-sparse-checkout.sh         |   2 +-
 t/t7012-skip-worktree-writing.sh      |   2 +-
 10 files changed, 268 insertions(+), 101 deletions(-)


base-commit: 1a4874565fa3b6668042216189551b98b4dc0b1b
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1148%2Fnewren%2Fsparse-checkout-default-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1148/newren/sparse-checkout-default-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/1148

Range-diff vs v2:

  1:  05dba7069c5 =  1:  05dba7069c5 tests: stop assuming --no-cone is the default mode for sparse-checkout
  2:  a53179764bc !  2:  d86c9179435 sparse-checkout: make --cone the default
     @@ Commit message
      
          Signed-off-by: Elijah Newren <newren@gmail.com>
      
     + ## Documentation/config/core.txt ##
     +@@ Documentation/config/core.txt: core.sparseCheckout::
     + 
     + core.sparseCheckoutCone::
     + 	Enables the "cone mode" of the sparse checkout feature. When the
     +-	sparse-checkout file contains a limited set of patterns, then this
     +-	mode provides significant performance advantages. See
     ++	sparse-checkout file contains a limited set of patterns, this
     ++	mode provides significant performance advantages. The "non
     ++	cone mode" can be requested to allow specifying a more flexible
     ++	patterns by setting this variable to 'false'. See
     + 	linkgit:git-sparse-checkout[1] for more information.
     + 
     + core.abbrev::
     +
       ## Documentation/git-sparse-checkout.txt ##
      @@ Documentation/git-sparse-checkout.txt: present, or undo and go back to having all tracked files present in the
       working copy.
     @@ Documentation/git-sparse-checkout.txt: SET' below).  The input format matches th
      +siblings of ancestor directories.
       +
      -When `--no-cone` is passed or `core.sparseCheckoutCone` is not enabled,
     -+When `--no-cone` is passed or `core.sparseCheckoutCone` is false,
     ++When `--no-cone` is passed or `core.sparseCheckoutCone` is set to false,
       the input list is considered a list of patterns.  This mode is harder
       to use and less performant, and is thus not recommended.  See the
       "Sparse Checkout" section of linkgit:git-read-tree[1] and the "Pattern
     @@ Documentation/git-sparse-checkout.txt: patterns. The resulting sparse-checkout f
      -expecting patterns of these types. Git will warn if the patterns do not match.
      -If the patterns do match the expected format, then Git will use faster hash-
      -based algorithms to compute inclusion in the sparse-checkout.
     -+If `core.sparseCheckoutCone=true` (set by default or with an explicit
     -+`--cone`), then Git will parse the sparse-checkout file expecting
     -+patterns of these types. Git will warn if the patterns do not match.  If
     -+the patterns do match the expected format, then Git will use faster
     -+hash-based algorithms to compute inclusion in the sparse-checkout.
     ++Unless `core.sparseCheckoutCone` is explicitly set to `false`, Git will
     ++parse the sparse-checkout file expecting patterns of these types. Git will
     ++warn if the patterns do not match.  If the patterns do match the expected
     ++format, then Git will use faster hash-based algorithms to compute inclusion
     ++in the sparse-checkout.
       
       In the cone mode case, the `git sparse-checkout list` subcommand will list the
       directories that define the recursive patterns. For the example sparse-checkout
     @@ builtin/sparse-checkout.c: static int update_modes(int *cone_mode, int *sparse_i
       	/* Set cone/non-cone mode appropriately */
       	core_apply_sparse_checkout = 1;
      -	if (*cone_mode == 1) {
     -+	if (*cone_mode) { /* also handles "not specified" (value of -1) */
     ++	if (*cone_mode == 1 || *cone_mode == -1) {
       		mode = MODE_CONE_PATTERNS;
       		core_sparse_checkout_cone = 1;
       	} else {
  3:  8eab21996c7 !  3:  b1e2c95a278 git-sparse-checkout.txt: wording updates for the cone mode default
     @@ Documentation/git-sparse-checkout.txt: When the `--stdin` option is provided, th
      +and `--cone` needed to be specified or `core.sparseCheckoutCone` needed
      +to be enabled.
       +
     - When `--no-cone` is passed or `core.sparseCheckoutCone` is false,
     + When `--no-cone` is passed or `core.sparseCheckoutCone` is set to false,
       the input list is considered a list of patterns.  This mode is harder
      @@ Documentation/git-sparse-checkout.txt: the following patterns:
       This says "include everything in root, but nothing two levels below root."
  4:  eb3b318b39e !  4:  b0b57cd37e7 git-sparse-checkout.txt: update docs for deprecation of 'init'
     @@ Documentation/git-sparse-checkout.txt: SET' below for more details).  In the pas
       and `--cone` needed to be specified or `core.sparseCheckoutCone` needed
       to be enabled.
       +
     --When `--no-cone` is passed or `core.sparseCheckoutCone` is false,
     +-When `--no-cone` is passed or `core.sparseCheckoutCone` is set to false,
      -the input list is considered a list of patterns.  This mode is harder
      -to use and less performant, and is thus not recommended.  See the
      -"Sparse Checkout" section of linkgit:git-read-tree[1] and the "Pattern
  5:  7333198b778 !  5:  eda0f41395b git-sparse-checkout.txt: shuffle some sections and mark as internal
     @@ Commit message
          Signed-off-by: Elijah Newren <newren@gmail.com>
      
       ## Documentation/git-sparse-checkout.txt ##
     +@@ Documentation/git-sparse-checkout.txt: to be enabled.
     + When `--no-cone` is passed, the input list is considered a list of
     + patterns.  This mode is harder to use and less performant, and is thus
     + not recommended.  See the "Sparse Checkout" section of
     +-linkgit:git-read-tree[1] and the "Pattern Set" sections below for more
     +-details.
     ++linkgit:git-read-tree[1] and the "Internals...Pattern Set" sections
     ++below for more details.
     + +
     + Use the `--[no-]sparse-index` option to use a sparse index (the
     + default is to not use it).  A sparse index reduces the size of the
      @@ Documentation/git-sparse-checkout.txt: paths to pass to a subsequent 'set' or 'add' command.  However,
       the disable command, so the easy restore of calling a plain `init`
       decreased in utility.
  6:  a814ea9e8d2 =  6:  7908c8f83d8 git-sparse-checkout.txt: add a new EXAMPLES section
  7:  78028ecaa58 !  7:  546ae3d6732 git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a bit
     @@ Metadata
      Author: Elijah Newren <newren@gmail.com>
      
       ## Commit message ##
     -    git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a bit
     +    git-sparse-checkout.txt: flesh out pattern set sections a bit
     +
     +    The "Internals -- Cone Pattern Set" section starts off discussing
     +    patterns, despite the fact that cone mode is about avoiding the
     +    patterns.  This made sense back when non-cone mode was the default and
     +    we started by discussing the full pattern set, but now that we are
     +    changing the default, it makes more sense to discuss cone-mode first and
     +    avoid the full discussion of patterns.  Split this section into two, the
     +    first with details about how cone mode operates, and the second
     +    following the full pattern set section and discussing how the cone mode
     +    patterns used under the hood relate to the full pattern set.
     +
     +    While at it, flesh out the "Internals -- Full Pattern Set" section a bit
     +    to include more examples as well.
      
          Signed-off-by: Elijah Newren <newren@gmail.com>
      
       ## Documentation/git-sparse-checkout.txt ##
     -@@ Documentation/git-sparse-checkout.txt: manually to ensure Git can behave optimally.
     - INTERNALS -- FULL PATTERN SET
     +@@ Documentation/git-sparse-checkout.txt: on this file. The files matching the patterns in the file will
     + appear in the working directory, and the rest will not.
     + 
     + 
     +-INTERNALS -- CONE PATTERN SET
     ++INTERNALS -- CONE MODE HANDLING
     ++-------------------------------
     ++
     ++The "cone mode", which is the default, lets you specify only what
     ++directories to include.  For any directory specified, all paths below
     ++that directory will be included, and any paths immediately under
     ++leading directories (including the toplevel directory) will also be
     ++included.  Thus, if you specified the directory
     ++    Documentation/technical/
     ++then your sparse checkout would contain:
     ++
     ++  * all files in the toplevel-directory
     ++  * all files immediately under Documentation/
     ++  * all files at any depth under Documentation/technical/
     ++
     ++Also, in cone mode, even if no directories are specified, then the
     ++files in the toplevel directory will be included.
     ++
     ++When changing the sparse-checkout patterns in cone mode, Git will inspect each
     ++tracked directory that is not within the sparse-checkout cone to see if it
     ++contains any untracked files. If all of those files are ignored due to the
     ++`.gitignore` patterns, then the directory will be deleted. If any of the
     ++untracked files within that directory is not ignored, then no deletions will
     ++occur within that directory and a warning message will appear. If these files
     ++are important, then reset your sparse-checkout definition so they are included,
     ++use `git add` and `git commit` to store them, then remove any remaining files
     ++manually to ensure Git can behave optimally.
     ++
     ++See also the "Internals -- Cone Pattern Set" section to learn how the
     ++directories are transformed under the hood into a subset of the
     ++Full Pattern Set of sparse-checkout.
     ++
     ++
     ++INTERNALS -- FULL PATTERN SET
       -----------------------------
       
     --By default, the sparse-checkout file uses the same syntax as `.gitignore`
     --files.
     --
     --While `$GIT_DIR/info/sparse-checkout` is usually used to specify what
     --files are included, you can also specify what files are _not_ included,
     --using negative patterns. For example, to remove the file `unwanted`:
     -+As noted above, the sparse-checkout file uses the same syntax as
     -+`.gitignore` files; see linkgit:gitignore[5] for details.  Here,
     -+though, the patterns are usually being used to select which files to
     -+include rather than which files to exclude.  (However, it can get a
     -+bit confusing since gitignore-style patterns have negations defined by
     -+patterns which begin with a '!', so you can also select files to _not_
     -+include.)
     + The full pattern set allows for arbitrary pattern matches and complicated
     +@@ Documentation/git-sparse-checkout.txt: updating the index, where N is the number of patterns and M is the number
     + of paths in the index. To combat this performance issue, a more restricted
     + pattern set is allowed when `core.sparseCheckoutCone` is enabled.
     + 
     +-The accepted patterns in the cone pattern set are:
     ++The sparse-checkout file uses the same syntax as `.gitignore` files;
     ++see linkgit:gitignore[5] for details.  Here, though, the patterns are
     ++usually being used to select which files to include rather than which
     ++files to exclude.  (However, it can get a bit confusing since
     ++gitignore-style patterns have negations defined by patterns which
     ++begin with a '!', so you can also select files to _not_ include.)
      +
      +For example, to select everything, and then to remove the file
      +`unwanted` (so that every file will appear in your working tree except
     @@ Documentation/git-sparse-checkout.txt: manually to ensure Git can behave optimal
      +These patterns are just placed into the
      +`$GIT_DIR/info/sparse-checkout` as-is, so the contents of that file
      +at this point would be
     ++
     ++----------------
     ++/*
     ++!unwanted
     ++----------------
     ++
     ++See also the "Sparse Checkout" section of linkgit:git-read-tree[1] to
     ++learn more about the gitignore-style patterns used in sparse
     ++checkouts.
     ++
     ++
     ++INTERNALS -- CONE PATTERN SET
     ++-----------------------------
     ++
     ++In cone mode, only directories are accepted, but they are translated into
     ++the same gitignore-style patterns used in the full pattern set.  We refer
     ++to the particular patterns used in those mode as being of one of two types:
     + 
     + 1. *Recursive:* All paths inside a directory are included.
     + 
     + 2. *Parent:* All files immediately inside a directory are included.
     + 
     +-In addition to the above two patterns, we also expect that all files in the
     +-root directory are included. If a recursive pattern is added, then all
     +-leading directories are added as parent patterns.
     +-
     +-By default, when running `git sparse-checkout set` with no directories
     +-specified, the root directory is added as a parent pattern. At this
     +-point, the sparse-checkout file contains the following patterns:
     ++Since cone mode always includes files at the toplevel, when running
     ++`git sparse-checkout set` with no directories specified, the toplevel
     ++directory is added as a parent pattern.  At this point, the
     ++sparse-checkout file contains the following patterns:
     + 
     + ----------------
     + /*
     + !/*/
     + ----------------
     + 
     +-This says "include everything in root, but nothing two levels below root."
     ++This says "include everything immediately under the toplevel
     ++directory, but nothing at any level below that."
     + 
     +-When in cone mode, the `git sparse-checkout set` subcommand takes a list of
     +-directories. In this mode, the command `git sparse-checkout set A/B/C` sets
     +-the directory `A/B/C` as a recursive pattern, the directories `A` and `A/B`
     +-are added as parent patterns. The resulting sparse-checkout file is now
     ++When in cone mode, the `git sparse-checkout set` subcommand takes a
     ++list of directories.  The command `git sparse-checkout set A/B/C` sets
     ++the directory `A/B/C` as a recursive pattern, the directories `A` and
     ++`A/B` are added as parent patterns. The resulting sparse-checkout file
     ++is now
       
       ----------------
       /*
     +@@ Documentation/git-sparse-checkout.txt: Unless `core.sparseCheckoutCone` is explicitly set to `false`, Git will
     + parse the sparse-checkout file expecting patterns of these types. Git will
     + warn if the patterns do not match.  If the patterns do match the expected
     + format, then Git will use faster hash-based algorithms to compute inclusion
     +-in the sparse-checkout.
     ++in the sparse-checkout.  If they do not match, git will behave as though
     ++`core.sparseCheckoutCone` was false, regardless of its setting.
     + 
     +-In the cone mode case, the `git sparse-checkout list` subcommand will list the
     +-directories that define the recursive patterns. For the example sparse-checkout
     +-file above, the output is as follows:
     ++In the cone mode case, despite the fact that full patterns are written
     ++to the $GIT_DIR/info/sparse-checkout file, the `git sparse-checkout
     ++list` subcommand will list the directories that define the recursive
     ++patterns. For the example sparse-checkout file above, the output is as
     ++follows:
     + 
     + --------------------------
     + $ git sparse-checkout list
     +@@ Documentation/git-sparse-checkout.txt: case-insensitive check. This corrects for case mismatched filenames in the
     + 'git sparse-checkout set' command to reflect the expected cone in the working
     + directory.
     + 
     +-When changing the sparse-checkout patterns in cone mode, Git will inspect each
     +-tracked directory that is not within the sparse-checkout cone to see if it
     +-contains any untracked files. If all of those files are ignored due to the
     +-`.gitignore` patterns, then the directory will be deleted. If any of the
     +-untracked files within that directory is not ignored, then no deletions will
     +-occur within that directory and a warning message will appear. If these files
     +-are important, then reset your sparse-checkout definition so they are included,
     +-use `git add` and `git commit` to store them, then remove any remaining files
     +-manually to ensure Git can behave optimally.
     +-
     +-
     +-INTERNALS -- FULL PATTERN SET
     +------------------------------
     +-
     +-By default, the sparse-checkout file uses the same syntax as `.gitignore`
     +-files.
     +-
     +-While `$GIT_DIR/info/sparse-checkout` is usually used to specify what
     +-files are included, you can also specify what files are _not_ included,
     +-using negative patterns. For example, to remove the file `unwanted`:
     +-
     +-----------------
     +-/*
     +-!unwanted
     +-----------------
     +-
     + 
     + INTERNALS -- SUBMODULES
     + -----------------------
  8:  2d2b81986a5 !  8:  a1b68fd6126 git-sparse-checkout.txt: mark non-cone mode as deprecated
     @@ Documentation/git-sparse-checkout.txt: and `--cone` needed to be specified or `c
       When `--no-cone` is passed, the input list is considered a list of
      -patterns.  This mode is harder to use and less performant, and is thus
      -not recommended.  See the "Sparse Checkout" section of
     --linkgit:git-read-tree[1] and the "Pattern Set" sections below for more
     --details.
     -+patterns.  This mode is harder to use, and unless you can keep the
     -+number of patterns small, its design also scales poorly.  It used to be
     -+the default mode, but we do not recommend using it.  It does not work
     -+with the `--sparse-index` option, and will likely be incompatible with
     -+other new features as they are added.  See the "Non-cone Problems"
     -+section below and the "Sparse Checkout" section of
     -+linkgit:git-read-tree[1] for more details.
     +-linkgit:git-read-tree[1] and the "Internals...Pattern Set" sections
     +-below for more details.
     ++patterns.  This mode has a number of drawbacks, including not working
     ++with some options like `--sparse-index`.  As explained in the
     ++"Non-cone Problems" section below, we do not recommend using it.
       +
       Use the `--[no-]sparse-index` option to use a sparse index (the
       default is to not use it).  A sparse index reduces the size of the
     @@ Documentation/git-sparse-checkout.txt: directory, it updates the skip-worktree b
      +  * Passing globs on the command line is error-prone as users may
      +    forget to quote the glob, causing the shell to expand it into all
      +    matching files and pass them all individually along to
     -+    sparse-checkout set/add.  This both exacerbates the scaling
     -+    problem, and hardcodes the list of selected files to those which
     -+    were present at the time the initial set/add subcommand was run
     -+    (and thus ignoring other files matching the same glob which come
     -+    into the working tree after switching branches or pulling down
     -+    updates).
     ++    sparse-checkout set/add.  While this could also be a problem with
     ++    e.g. "git grep -- *.c", mistakes with grep/log/status appear in
     ++    the immediate output.  With sparse-checkout, the mistake gets
     ++    recorded at the time the sparse-checkout command is run and might
     ++    not be problematic until the user later switches branches or rebases
     ++    or merges, thus putting a delay between the user's error and when
     ++    they have a chance to catch/notice it.
      +
     -+  * It uses "ignore"/"exclude" syntax for selecting what to "include",
     -+    which periodically causes confusion.
     ++  * Related to the previous item, sparse-checkout has an 'add'
     ++    subcommand but no 'remove' subcommand.  Even if a 'remove'
     ++    subcommand were added, undoing an accidental unquoted glob runs
     ++    the risk of "removing too much", as it may remove entries that had
     ++    been included before the accidental add.
      +
     -+  * It introduces inconsistencies in the Git command line, since other
     -+    commands use pathspecs, but sparse-checkout (in non-cone mode) uses
     -+    gitignore patterns.
     ++  * Non-cone mode uses gitignore-style patterns to select what to
     ++    *include* (with the exception of negated patterns), while
     ++    .gitignore files use gitignore-style patterns to select what to
     ++    *exclude* (with the exception of negated patterns).  The
     ++    documentation on gitignore-style patterns usually does not talk in
     ++    terms of matching or non-matching, but on what the user wants to
     ++    "exclude".  This can cause confusion for users trying to learn how
     ++    to specify sparse-checkout patterns to get their desired behavior.
     ++
     ++  * Every other git subcommand that wants to provide "special path
     ++    pattern matching" of some sort uses pathspecs, but non-cone mode
     ++    for sparse-checkout uses gitignore patterns, which feels
     ++    inconsistent.
      +
      +  * It has edge cases where the "right" behavior is unclear.  Two examples:
      +
     @@ Documentation/git-sparse-checkout.txt: directory, it updates the skip-worktree b
      +    all these cases.
      +
      +  * The excessive flexibility made other extensions essentially
     -+    impractical.  `--sparse-index` may not have been feasible in
     -+    non-cone mode, but even if it was, it would have been far more work
     -+    to implement and may have been too slow in practice.  Some ideas for
     -+    adding coupling between partial clones and sparse checkouts are only
     -+    practical with a more restricted set of paths.
     ++    impractical.  `--sparse-index` is likely impossible in non-cone
     ++    mode; even if it is somehow feasible, it would have been far more
     ++    work to implement and may have been too slow in practice.  Some
     ++    ideas for adding coupling between partial clones and sparse
     ++    checkouts are only practical with a more restricted set of paths
     ++    as well.
      +
      +For all these reasons, non-cone mode is deprecated.  Please switch to
      +using cone mode.
     ++
       
     - INTERNALS -- CONE PATTERN SET
     - -----------------------------
     + INTERNALS -- CONE MODE HANDLING
     + -------------------------------
  9:  4b89a3392b0 !  9:  5f0e80777de Documentation: some sparsity wording clarifications
     @@ Documentation/git-read-tree.txt: have finished your work-in-progress), attempt t
      +and `read-tree` predated the introduction of
      +linkgit:git-sparse-checkout[1].  Users are encouraged to use the
      +`sparse-checkout` command in preference to these plumbing commands for
     -+sparse-checkout/skip-worktree related needs.
     ++sparse-checkout/skip-worktree related needs.  However, the information
     ++below might be useful to users trying to understand the pattern style
     ++used in non-cone mode of the `sparse-checkout` command.
       
       "Sparse checkout" allows populating the working directory sparsely.
       It uses the skip-worktree bit (see linkgit:git-update-index[1]) to

-- 
gitgitgadget

[PATCH v3 1/9] tests: stop assuming --no-cone is the default mode for sparse-checkout

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

Add an explicit --no-cone to several sparse-checkout invocations in
preparation for changing the default to cone mode.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
 t/t1091-sparse-checkout-builtin.sh | 15 ++++++++-------
 t/t3602-rm-sparse-checkout.sh      |  6 +++---
 t/t3705-add-sparse-checkout.sh     |  4 ++--
 t/t6428-merge-conflicts-sparse.sh  |  4 ++--
 t/t7002-mv-sparse-checkout.sh      |  2 +-
 t/t7012-skip-worktree-writing.sh   |  2 +-
 6 files changed, 17 insertions(+), 16 deletions(-)

diff --git a/t/t1091-sparse-checkout-builtin.sh b/t/t1091-sparse-checkout-builtin.sh
index 9a900310186..de1ec89007d 100755
--- a/t/t1091-sparse-checkout-builtin.sh
+++ b/t/t1091-sparse-checkout-builtin.sh
@@ -72,7 +72,7 @@ test_expect_success 'git sparse-checkout list (populated)' '
 '
 
 test_expect_success 'git sparse-checkout init' '
-	git -C repo sparse-checkout init &&
+	git -C repo sparse-checkout init --no-cone &&
 	cat >expect <<-\EOF &&
 	/*
 	!/*/
@@ -111,6 +111,7 @@ test_expect_success 'init with existing sparse-checkout' '
 
 test_expect_success 'clone --sparse' '
 	git clone --sparse "file://$(pwd)/repo" clone &&
+	git -C clone sparse-checkout reapply --no-cone &&
 	git -C clone sparse-checkout list >actual &&
 	cat >expect <<-\EOF &&
 	/*
@@ -124,7 +125,7 @@ test_expect_success 'switching to cone mode with non-cone mode patterns' '
 	git init bad-patterns &&
 	(
 		cd bad-patterns &&
-		git sparse-checkout init &&
+		git sparse-checkout init --no-cone &&
 		git sparse-checkout add dir &&
 		git config --worktree core.sparseCheckoutCone true &&
 		test_must_fail git sparse-checkout add dir 2>err &&
@@ -402,7 +403,7 @@ test_expect_success 'revert to old sparse-checkout on empty update' '
 		git sparse-checkout set nothing 2>err &&
 		test_i18ngrep ! "Sparse checkout leaves no entry on working directory" err &&
 		test_i18ngrep ! ".git/index.lock" err &&
-		git sparse-checkout set file
+		git sparse-checkout set --no-cone file
 	)
 '
 
@@ -424,7 +425,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with dirty status'
 	git clone repo dirty &&
 	echo dirty >dirty/folder1/a &&
 
-	git -C dirty sparse-checkout init 2>err &&
+	git -C dirty sparse-checkout init --no-cone 2>err &&
 	test_i18ngrep "warning.*The following paths are not up to date" err &&
 
 	git -C dirty sparse-checkout set /folder2/* /deep/deeper1/* 2>err &&
@@ -435,7 +436,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with dirty status'
 	test_must_be_empty err &&
 
 	git -C dirty reset --hard &&
-	git -C dirty sparse-checkout init &&
+	git -C dirty sparse-checkout init --no-cone &&
 	git -C dirty sparse-checkout set /folder2/* /deep/deeper1/* &&
 	test_path_is_missing dirty/folder1/a &&
 	git -C dirty sparse-checkout disable &&
@@ -451,7 +452,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with unmerged stat
 	EOF
 	git -C unmerged update-index --index-info <input &&
 
-	git -C unmerged sparse-checkout init 2>err &&
+	git -C unmerged sparse-checkout init --no-cone 2>err &&
 	test_i18ngrep "warning.*The following paths are unmerged" err &&
 
 	git -C unmerged sparse-checkout set /folder2/* /deep/deeper1/* 2>err &&
@@ -462,7 +463,7 @@ test_expect_success 'sparse-checkout (init|set|disable) warns with unmerged stat
 	test_i18ngrep "warning.*The following paths are unmerged" err &&
 
 	git -C unmerged reset --hard &&
-	git -C unmerged sparse-checkout init &&
+	git -C unmerged sparse-checkout init --no-cone &&
 	git -C unmerged sparse-checkout set /folder2/* /deep/deeper1/* &&
 	git -C unmerged sparse-checkout disable
 '
diff --git a/t/t3602-rm-sparse-checkout.sh b/t/t3602-rm-sparse-checkout.sh
index 034ec010910..08580fd3dcc 100755
--- a/t/t3602-rm-sparse-checkout.sh
+++ b/t/t3602-rm-sparse-checkout.sh
@@ -30,7 +30,7 @@ test_expect_success 'setup' "
 for opt in "" -f --dry-run
 do
 	test_expect_success "rm${opt:+ $opt} does not remove sparse entries" '
-		git sparse-checkout set a &&
+		git sparse-checkout set --no-cone a &&
 		test_must_fail git rm $opt b 2>stderr &&
 		test_cmp b_error_and_hint stderr &&
 		git ls-files --error-unmatch b
@@ -118,7 +118,7 @@ test_expect_success 'can remove files from non-sparse dir' '
 	test_commit w/f &&
 	test_commit x/y/f &&
 
-	git sparse-checkout set w !/x y/ &&
+	git sparse-checkout set --no-cone w !/x y/ &&
 	git rm w/f.t x/y/f.t 2>stderr &&
 	test_must_be_empty stderr
 '
@@ -128,7 +128,7 @@ test_expect_success 'refuse to remove non-skip-worktree file from sparse dir' '
 	git sparse-checkout disable &&
 	mkdir -p x/y/z &&
 	test_commit x/y/z/f &&
-	git sparse-checkout set !/x y/ !x/y/z &&
+	git sparse-checkout set --no-cone !/x y/ !x/y/z &&
 
 	git update-index --no-skip-worktree x/y/z/f.t &&
 	test_must_fail git rm x/y/z/f.t 2>stderr &&
diff --git a/t/t3705-add-sparse-checkout.sh b/t/t3705-add-sparse-checkout.sh
index 95609046c61..2bade9e804f 100755
--- a/t/t3705-add-sparse-checkout.sh
+++ b/t/t3705-add-sparse-checkout.sh
@@ -166,7 +166,7 @@ test_expect_success 'do not warn when pathspec matches dense entries' '
 test_expect_success 'git add fails outside of sparse-checkout definition' '
 	test_when_finished git sparse-checkout disable &&
 	test_commit a &&
-	git sparse-checkout init &&
+	git sparse-checkout init --no-cone &&
 	git sparse-checkout set a &&
 	echo >>sparse_entry &&
 
@@ -208,7 +208,7 @@ test_expect_success 'add obeys advice.updateSparsePath' '
 '
 
 test_expect_success 'add allows sparse entries with --sparse' '
-	git sparse-checkout set a &&
+	git sparse-checkout set --no-cone a &&
 	echo modified >sparse_entry &&
 	test_must_fail git add sparse_entry &&
 	test_sparse_entry_unchanged &&
diff --git a/t/t6428-merge-conflicts-sparse.sh b/t/t6428-merge-conflicts-sparse.sh
index 142c9aaabc5..064be1b629e 100755
--- a/t/t6428-merge-conflicts-sparse.sh
+++ b/t/t6428-merge-conflicts-sparse.sh
@@ -87,7 +87,7 @@ test_expect_success 'conflicting entries written to worktree even if sparse' '
 		test_path_is_file numerals &&
 
 		git sparse-checkout init &&
-		git sparse-checkout set README &&
+		git sparse-checkout set --no-cone README &&
 
 		test_path_is_file README &&
 		test_path_is_missing numerals &&
@@ -123,7 +123,7 @@ test_expect_success 'present-despite-SKIP_WORKTREE handled reasonably' '
 		test_path_is_file numerals &&
 
 		git sparse-checkout init &&
-		git sparse-checkout set README &&
+		git sparse-checkout set --no-cone README &&
 
 		test_path_is_file README &&
 		test_path_is_missing numerals &&
diff --git a/t/t7002-mv-sparse-checkout.sh b/t/t7002-mv-sparse-checkout.sh
index 1d3d2aca21c..f0f7cbfcdb7 100755
--- a/t/t7002-mv-sparse-checkout.sh
+++ b/t/t7002-mv-sparse-checkout.sh
@@ -27,7 +27,7 @@ test_expect_success 'setup' "
 test_expect_success 'mv refuses to move sparse-to-sparse' '
 	test_when_finished rm -f e &&
 	git reset --hard &&
-	git sparse-checkout set a &&
+	git sparse-checkout set --no-cone a &&
 	touch b &&
 	test_must_fail git mv b e 2>stderr &&
 	cat sparse_error_header >expect &&
diff --git a/t/t7012-skip-worktree-writing.sh b/t/t7012-skip-worktree-writing.sh
index cb9f1a6981e..cd5c20fe51b 100755
--- a/t/t7012-skip-worktree-writing.sh
+++ b/t/t7012-skip-worktree-writing.sh
@@ -151,7 +151,7 @@ test_expect_success 'stash restore in sparse checkout' '
 
 		git stash push &&
 
-		git sparse-checkout set subdir &&
+		git sparse-checkout set --no-cone subdir &&
 
 		# Ensure after sparse-checkout we only have expected files
 		cat >expect <<-EOF &&
-- 
gitgitgadget

[PATCH v3 2/9] sparse-checkout: make --cone the default

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

Make cone mode the default, and update the documentation accordingly.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
 Documentation/config/core.txt         |  6 ++++--
 Documentation/git-sparse-checkout.txt | 20 ++++++++++----------
 builtin/sparse-checkout.c             |  2 +-
 3 files changed, 15 insertions(+), 13 deletions(-)

diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt
index c04f62a54a1..03cf075821b 100644
--- a/Documentation/config/core.txt
+++ b/Documentation/config/core.txt
@@ -615,8 +615,10 @@ core.sparseCheckout::
 
 core.sparseCheckoutCone::
 	Enables the "cone mode" of the sparse checkout feature. When the
-	sparse-checkout file contains a limited set of patterns, then this
-	mode provides significant performance advantages. See
+	sparse-checkout file contains a limited set of patterns, this
+	mode provides significant performance advantages. The "non
+	cone mode" can be requested to allow specifying a more flexible
+	patterns by setting this variable to 'false'. See
 	linkgit:git-sparse-checkout[1] for more information.
 
 core.abbrev::
diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 88e55f432f3..7308e744c57 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -22,8 +22,8 @@ present, or undo and go back to having all tracked files present in the
 working copy.
 
 The subset of files is chosen by providing a list of directories in
-cone mode (which is recommended), or by providing a list of patterns
-in non-cone mode.
+cone mode (the default), or by providing a list of patterns in
+non-cone mode.
 
 When in a sparse-checkout, other Git commands behave a bit differently.
 For example, switching branches will not update paths outside the
@@ -60,7 +60,7 @@ When the `--stdin` option is provided, the directories or patterns are
 read from standard in as a newline-delimited list instead of from the
 arguments.
 +
-When `--cone` is passed or `core.sparseCheckoutCone` is enabled, the
+When `--cone` is passed or `core.sparseCheckoutCone` is not false, the
 input list is considered a list of directories.  This allows for
 better performance with a limited set of patterns (see 'CONE PATTERN
 SET' below).  The input format matches the output of `git ls-tree
@@ -68,10 +68,9 @@ SET' below).  The input format matches the output of `git ls-tree
 double quote (") as C-style quoted strings.  Note that the set command
 will write patterns to the sparse-checkout file to include all files
 contained in those directories (recursively) as well as files that are
-siblings of ancestor directories. This may become the default in the
-future; --no-cone can be passed to request non-cone mode.
+siblings of ancestor directories.
 +
-When `--no-cone` is passed or `core.sparseCheckoutCone` is not enabled,
+When `--no-cone` is passed or `core.sparseCheckoutCone` is set to false,
 the input list is considered a list of patterns.  This mode is harder
 to use and less performant, and is thus not recommended.  See the
 "Sparse Checkout" section of linkgit:git-read-tree[1] and the "Pattern
@@ -227,10 +226,11 @@ patterns. The resulting sparse-checkout file is now
 Here, order matters, so the negative patterns are overridden by the positive
 patterns that appear lower in the file.
 
-If `core.sparseCheckoutCone=true`, then Git will parse the sparse-checkout file
-expecting patterns of these types. Git will warn if the patterns do not match.
-If the patterns do match the expected format, then Git will use faster hash-
-based algorithms to compute inclusion in the sparse-checkout.
+Unless `core.sparseCheckoutCone` is explicitly set to `false`, Git will
+parse the sparse-checkout file expecting patterns of these types. Git will
+warn if the patterns do not match.  If the patterns do match the expected
+format, then Git will use faster hash-based algorithms to compute inclusion
+in the sparse-checkout.
 
 In the cone mode case, the `git sparse-checkout list` subcommand will list the
 directories that define the recursive patterns. For the example sparse-checkout
diff --git a/builtin/sparse-checkout.c b/builtin/sparse-checkout.c
index 5518ed47f6c..61b7a7519bb 100644
--- a/builtin/sparse-checkout.c
+++ b/builtin/sparse-checkout.c
@@ -397,7 +397,7 @@ static int update_modes(int *cone_mode, int *sparse_index)
 
 	/* Set cone/non-cone mode appropriately */
 	core_apply_sparse_checkout = 1;
-	if (*cone_mode == 1) {
+	if (*cone_mode == 1 || *cone_mode == -1) {
 		mode = MODE_CONE_PATTERNS;
 		core_sparse_checkout_cone = 1;
 	} else {
-- 
gitgitgadget

[PATCH v3 3/9] git-sparse-checkout.txt: wording updates for the cone mode default

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

Now that cone mode is the default, we'd like to focus on the arguments
to set/add being directories rather than patterns, and it probably makes
sense to provide an earlier heads up that files from leading directories
get included as well.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 31 +++++++++++++--------------
 1 file changed, 15 insertions(+), 16 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 7308e744c57..b5db812f09e 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -44,9 +44,9 @@ COMMANDS
 	Enable the necessary sparse-checkout config settings
 	(`core.sparseCheckout`, `core.sparseCheckoutCone`, and
 	`index.sparse`) if they are not already set to the desired values,
-	and write a set of patterns to the sparse-checkout file from the
-	list of arguments following the 'set' subcommand. Update the
-	working directory to match the new patterns.
+	populate the sparse-checkout file from the list of arguments
+	following the 'set' subcommand, and update the working directory to
+	match.
 +
 To ensure that adjusting the sparse-checkout settings within a worktree
 does not alter the sparse-checkout settings in other worktrees, the 'set'
@@ -60,15 +60,15 @@ When the `--stdin` option is provided, the directories or patterns are
 read from standard in as a newline-delimited list instead of from the
 arguments.
 +
-When `--cone` is passed or `core.sparseCheckoutCone` is not false, the
-input list is considered a list of directories.  This allows for
-better performance with a limited set of patterns (see 'CONE PATTERN
-SET' below).  The input format matches the output of `git ls-tree
---name-only`.  This includes interpreting pathnames that begin with a
-double quote (") as C-style quoted strings.  Note that the set command
-will write patterns to the sparse-checkout file to include all files
-contained in those directories (recursively) as well as files that are
-siblings of ancestor directories.
+By default, the input list is considered a list of directories, matching
+the output of `git ls-tree -d --name-only`.  This includes interpreting
+pathnames that begin with a double quote (") as C-style quoted strings.
+Note that all files under the specified directories (at any depth) will
+be included in the sparse checkout, as well as files that are siblings
+of either the given directory or any of its ancestors (see 'CONE PATTERN
+SET' below for more details).  In the past, this was not the default,
+and `--cone` needed to be specified or `core.sparseCheckoutCone` needed
+to be enabled.
 +
 When `--no-cone` is passed or `core.sparseCheckoutCone` is set to false,
 the input list is considered a list of patterns.  This mode is harder
@@ -208,10 +208,9 @@ the following patterns:
 This says "include everything in root, but nothing two levels below root."
 
 When in cone mode, the `git sparse-checkout set` subcommand takes a list of
-directories instead of a list of sparse-checkout patterns. In this mode,
-the command `git sparse-checkout set A/B/C` sets the directory `A/B/C` as
-a recursive pattern, the directories `A` and `A/B` are added as parent
-patterns. The resulting sparse-checkout file is now
+directories. In this mode, the command `git sparse-checkout set A/B/C` sets
+the directory `A/B/C` as a recursive pattern, the directories `A` and `A/B`
+are added as parent patterns. The resulting sparse-checkout file is now
 
 ----------------
 /*
-- 
gitgitgadget

[PATCH v3 4/9] git-sparse-checkout.txt: update docs for deprecation of 'init'

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

The 'init' subcommand of sparse-checkout was deprecated in ba2f3f58ac
("git-sparse-checkout.txt: update to document init/set/reapply changes",
2021-12-14), but a couple places in the manual still assumed it was the
primary way to use sparse-checkout.  Correct them.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index b5db812f09e..8e80d1c7332 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -70,11 +70,11 @@ SET' below for more details).  In the past, this was not the default,
 and `--cone` needed to be specified or `core.sparseCheckoutCone` needed
 to be enabled.
 +
-When `--no-cone` is passed or `core.sparseCheckoutCone` is set to false,
-the input list is considered a list of patterns.  This mode is harder
-to use and less performant, and is thus not recommended.  See the
-"Sparse Checkout" section of linkgit:git-read-tree[1] and the "Pattern
-Set" sections below for more details.
+When `--no-cone` is passed, the input list is considered a list of
+patterns.  This mode is harder to use and less performant, and is thus
+not recommended.  See the "Sparse Checkout" section of
+linkgit:git-read-tree[1] and the "Pattern Set" sections below for more
+details.
 +
 Use the `--[no-]sparse-index` option to use a sparse index (the
 default is to not use it).  A sparse index reduces the size of the
@@ -196,9 +196,9 @@ In addition to the above two patterns, we also expect that all files in the
 root directory are included. If a recursive pattern is added, then all
 leading directories are added as parent patterns.
 
-By default, when running `git sparse-checkout init`, the root directory is
-added as a parent pattern. At this point, the sparse-checkout file contains
-the following patterns:
+By default, when running `git sparse-checkout set` with no directories
+specified, the root directory is added as a parent pattern. At this
+point, the sparse-checkout file contains the following patterns:
 
 ----------------
 /*
-- 
gitgitgadget

[PATCH v3 5/9] git-sparse-checkout.txt: shuffle some sections and mark as internal

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

With cone mode as the default, it makes sense to discuss it before
non-cone mode.  Also, the new default means we can just use directories
in most cases and users do not need to understand patterns or their
meanings.  Let's take advantage of this to mark several sections as
"INTERNALS", notifying the user that they do not need to know all those
details in order to make use of the sparse-checkout command.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 48 +++++++++++++--------------
 1 file changed, 24 insertions(+), 24 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 8e80d1c7332..2083e6df356 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -73,8 +73,8 @@ to be enabled.
 When `--no-cone` is passed, the input list is considered a list of
 patterns.  This mode is harder to use and less performant, and is thus
 not recommended.  See the "Sparse Checkout" section of
-linkgit:git-read-tree[1] and the "Pattern Set" sections below for more
-details.
+linkgit:git-read-tree[1] and the "Internals...Pattern Set" sections
+below for more details.
 +
 Use the `--[no-]sparse-index` option to use a sparse index (the
 default is to not use it).  A sparse index reduces the size of the
@@ -136,8 +136,8 @@ paths to pass to a subsequent 'set' or 'add' command.  However,
 the disable command, so the easy restore of calling a plain `init`
 decreased in utility.
 
-SPARSE CHECKOUT
----------------
+INTERNALS -- SPARSE CHECKOUT
+----------------------------
 
 "Sparse checkout" allows populating the working directory sparsely.  It
 uses the skip-worktree bit (see linkgit:git-update-index[1]) to tell Git
@@ -161,24 +161,8 @@ To repopulate the working directory with all files, use the
 `git sparse-checkout disable` command.
 
 
-FULL PATTERN SET
-----------------
-
-By default, the sparse-checkout file uses the same syntax as `.gitignore`
-files.
-
-While `$GIT_DIR/info/sparse-checkout` is usually used to specify what
-files are included, you can also specify what files are _not_ included,
-using negative patterns. For example, to remove the file `unwanted`:
-
-----------------
-/*
-!unwanted
-----------------
-
-
-CONE PATTERN SET
-----------------
+INTERNALS -- CONE PATTERN SET
+-----------------------------
 
 The full pattern set allows for arbitrary pattern matches and complicated
 inclusion/exclusion rules. These can result in O(N*M) pattern matches when
@@ -256,8 +240,24 @@ use `git add` and `git commit` to store them, then remove any remaining files
 manually to ensure Git can behave optimally.
 
 
-SUBMODULES
-----------
+INTERNALS -- FULL PATTERN SET
+-----------------------------
+
+By default, the sparse-checkout file uses the same syntax as `.gitignore`
+files.
+
+While `$GIT_DIR/info/sparse-checkout` is usually used to specify what
+files are included, you can also specify what files are _not_ included,
+using negative patterns. For example, to remove the file `unwanted`:
+
+----------------
+/*
+!unwanted
+----------------
+
+
+INTERNALS -- SUBMODULES
+-----------------------
 
 If your repository contains one or more submodules, then submodules
 are populated based on interactions with the `git submodule` command.
-- 
gitgitgadget

[PATCH v3 6/9] git-sparse-checkout.txt: add a new EXAMPLES section

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

Since many users like to learn from examples, provide a section in the
manual with example commands that would be used and a brief explanation
of what each does.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 43 +++++++++++++++++++++++----
 1 file changed, 37 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 2083e6df356..c54437428bb 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -136,6 +136,43 @@ paths to pass to a subsequent 'set' or 'add' command.  However,
 the disable command, so the easy restore of calling a plain `init`
 decreased in utility.
 
+EXAMPLES
+--------
+`git sparse-checkout set MY/DIR1 SUB/DIR2`::
+
+	Change to a sparse checkout with all files (at any depth) under
+	MY/DIR1/ and SUB/DIR2/ present in the working copy (plus all
+	files immediately under MY/ and SUB/ and the toplevel
+	directory).  If already in a sparse checkout, change which files
+	are present in the working copy to this new selection.  Note
+	that this command will also delete all ignored files in any
+	directory that no longer has either tracked or
+	non-ignored-untracked files present.
+
+`git sparse-checkout disable`::
+
+	Repopulate the working directory with all files, disabling sparse
+	checkouts.
+
+`git sparse-checkout add SOME/DIR/ECTORY`::
+
+	Add all files under SOME/DIR/ECTORY/ (at any depth) to the
+	sparse checkout, as well as all files immediately under
+	SOME/DIR/ and immediately under SOME/.  Must already be in a
+	sparse checkout before using this command.
+
+`git sparse-checkout reapply`::
+
+	It is possible for commands to update the working tree in a
+	way that does not respect the selected sparsity directories.
+	This can come from tools external to Git writing files, or
+	even affect Git commands because of either special cases (such
+	as hitting conflicts when merging/rebasing), or because some
+	commands didn't fully support sparse checkouts (e.g. the old
+	`recursive` merge backend had only limited support).  This
+	command reapplies the existing sparse directory specifications
+	to make the working directory match.
+
 INTERNALS -- SPARSE CHECKOUT
 ----------------------------
 
@@ -154,12 +191,6 @@ directory, it updates the skip-worktree bits in the index based
 on this file. The files matching the patterns in the file will
 appear in the working directory, and the rest will not.
 
-To enable the sparse-checkout feature, run `git sparse-checkout set` to
-set the patterns you want to use.
-
-To repopulate the working directory with all files, use the
-`git sparse-checkout disable` command.
-
 
 INTERNALS -- CONE PATTERN SET
 -----------------------------
-- 
gitgitgadget

[PATCH v3 7/9] git-sparse-checkout.txt: flesh out pattern set sections a bit

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

The "Internals -- Cone Pattern Set" section starts off discussing
patterns, despite the fact that cone mode is about avoiding the
patterns.  This made sense back when non-cone mode was the default and
we started by discussing the full pattern set, but now that we are
changing the default, it makes more sense to discuss cone-mode first and
avoid the full discussion of patterns.  Split this section into two, the
first with details about how cone mode operates, and the second
following the full pattern set section and discussing how the cone mode
patterns used under the hood relate to the full pattern set.

While at it, flesh out the "Internals -- Full Pattern Set" section a bit
to include more examples as well.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 129 +++++++++++++++++---------
 1 file changed, 85 insertions(+), 44 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index c54437428bb..6e32034511d 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -192,7 +192,40 @@ on this file. The files matching the patterns in the file will
 appear in the working directory, and the rest will not.
 
 
-INTERNALS -- CONE PATTERN SET
+INTERNALS -- CONE MODE HANDLING
+-------------------------------
+
+The "cone mode", which is the default, lets you specify only what
+directories to include.  For any directory specified, all paths below
+that directory will be included, and any paths immediately under
+leading directories (including the toplevel directory) will also be
+included.  Thus, if you specified the directory
+    Documentation/technical/
+then your sparse checkout would contain:
+
+  * all files in the toplevel-directory
+  * all files immediately under Documentation/
+  * all files at any depth under Documentation/technical/
+
+Also, in cone mode, even if no directories are specified, then the
+files in the toplevel directory will be included.
+
+When changing the sparse-checkout patterns in cone mode, Git will inspect each
+tracked directory that is not within the sparse-checkout cone to see if it
+contains any untracked files. If all of those files are ignored due to the
+`.gitignore` patterns, then the directory will be deleted. If any of the
+untracked files within that directory is not ignored, then no deletions will
+occur within that directory and a warning message will appear. If these files
+are important, then reset your sparse-checkout definition so they are included,
+use `git add` and `git commit` to store them, then remove any remaining files
+manually to ensure Git can behave optimally.
+
+See also the "Internals -- Cone Pattern Set" section to learn how the
+directories are transformed under the hood into a subset of the
+Full Pattern Set of sparse-checkout.
+
+
+INTERNALS -- FULL PATTERN SET
 -----------------------------
 
 The full pattern set allows for arbitrary pattern matches and complicated
@@ -201,31 +234,62 @@ updating the index, where N is the number of patterns and M is the number
 of paths in the index. To combat this performance issue, a more restricted
 pattern set is allowed when `core.sparseCheckoutCone` is enabled.
 
-The accepted patterns in the cone pattern set are:
+The sparse-checkout file uses the same syntax as `.gitignore` files;
+see linkgit:gitignore[5] for details.  Here, though, the patterns are
+usually being used to select which files to include rather than which
+files to exclude.  (However, it can get a bit confusing since
+gitignore-style patterns have negations defined by patterns which
+begin with a '!', so you can also select files to _not_ include.)
+
+For example, to select everything, and then to remove the file
+`unwanted` (so that every file will appear in your working tree except
+the file named `unwanted`):
+
+    git sparse-checkout set --no-cone '/*' '!unwanted'
+
+These patterns are just placed into the
+`$GIT_DIR/info/sparse-checkout` as-is, so the contents of that file
+at this point would be
+
+----------------
+/*
+!unwanted
+----------------
+
+See also the "Sparse Checkout" section of linkgit:git-read-tree[1] to
+learn more about the gitignore-style patterns used in sparse
+checkouts.
+
+
+INTERNALS -- CONE PATTERN SET
+-----------------------------
+
+In cone mode, only directories are accepted, but they are translated into
+the same gitignore-style patterns used in the full pattern set.  We refer
+to the particular patterns used in those mode as being of one of two types:
 
 1. *Recursive:* All paths inside a directory are included.
 
 2. *Parent:* All files immediately inside a directory are included.
 
-In addition to the above two patterns, we also expect that all files in the
-root directory are included. If a recursive pattern is added, then all
-leading directories are added as parent patterns.
-
-By default, when running `git sparse-checkout set` with no directories
-specified, the root directory is added as a parent pattern. At this
-point, the sparse-checkout file contains the following patterns:
+Since cone mode always includes files at the toplevel, when running
+`git sparse-checkout set` with no directories specified, the toplevel
+directory is added as a parent pattern.  At this point, the
+sparse-checkout file contains the following patterns:
 
 ----------------
 /*
 !/*/
 ----------------
 
-This says "include everything in root, but nothing two levels below root."
+This says "include everything immediately under the toplevel
+directory, but nothing at any level below that."
 
-When in cone mode, the `git sparse-checkout set` subcommand takes a list of
-directories. In this mode, the command `git sparse-checkout set A/B/C` sets
-the directory `A/B/C` as a recursive pattern, the directories `A` and `A/B`
-are added as parent patterns. The resulting sparse-checkout file is now
+When in cone mode, the `git sparse-checkout set` subcommand takes a
+list of directories.  The command `git sparse-checkout set A/B/C` sets
+the directory `A/B/C` as a recursive pattern, the directories `A` and
+`A/B` are added as parent patterns. The resulting sparse-checkout file
+is now
 
 ----------------
 /*
@@ -244,11 +308,14 @@ Unless `core.sparseCheckoutCone` is explicitly set to `false`, Git will
 parse the sparse-checkout file expecting patterns of these types. Git will
 warn if the patterns do not match.  If the patterns do match the expected
 format, then Git will use faster hash-based algorithms to compute inclusion
-in the sparse-checkout.
+in the sparse-checkout.  If they do not match, git will behave as though
+`core.sparseCheckoutCone` was false, regardless of its setting.
 
-In the cone mode case, the `git sparse-checkout list` subcommand will list the
-directories that define the recursive patterns. For the example sparse-checkout
-file above, the output is as follows:
+In the cone mode case, despite the fact that full patterns are written
+to the $GIT_DIR/info/sparse-checkout file, the `git sparse-checkout
+list` subcommand will list the directories that define the recursive
+patterns. For the example sparse-checkout file above, the output is as
+follows:
 
 --------------------------
 $ git sparse-checkout list
@@ -260,32 +327,6 @@ case-insensitive check. This corrects for case mismatched filenames in the
 'git sparse-checkout set' command to reflect the expected cone in the working
 directory.
 
-When changing the sparse-checkout patterns in cone mode, Git will inspect each
-tracked directory that is not within the sparse-checkout cone to see if it
-contains any untracked files. If all of those files are ignored due to the
-`.gitignore` patterns, then the directory will be deleted. If any of the
-untracked files within that directory is not ignored, then no deletions will
-occur within that directory and a warning message will appear. If these files
-are important, then reset your sparse-checkout definition so they are included,
-use `git add` and `git commit` to store them, then remove any remaining files
-manually to ensure Git can behave optimally.
-
-
-INTERNALS -- FULL PATTERN SET
------------------------------
-
-By default, the sparse-checkout file uses the same syntax as `.gitignore`
-files.
-
-While `$GIT_DIR/info/sparse-checkout` is usually used to specify what
-files are included, you can also specify what files are _not_ included,
-using negative patterns. For example, to remove the file `unwanted`:
-
-----------------
-/*
-!unwanted
-----------------
-
 
 INTERNALS -- SUBMODULES
 -----------------------
-- 
gitgitgadget

[PATCH v3 8/9] git-sparse-checkout.txt: mark non-cone mode as deprecated

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

While we have no current plans to actually remove --no-cone mode, we
think users would be better off not using it.  Update the documentation
accordingly, including explaining why we think non-cone mode is
problematic for users.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
 Documentation/git-sparse-checkout.txt | 98 +++++++++++++++++++++++++--
 1 file changed, 94 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 6e32034511d..c65d0ce96bb 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -71,10 +71,9 @@ and `--cone` needed to be specified or `core.sparseCheckoutCone` needed
 to be enabled.
 +
 When `--no-cone` is passed, the input list is considered a list of
-patterns.  This mode is harder to use and less performant, and is thus
-not recommended.  See the "Sparse Checkout" section of
-linkgit:git-read-tree[1] and the "Internals...Pattern Set" sections
-below for more details.
+patterns.  This mode has a number of drawbacks, including not working
+with some options like `--sparse-index`.  As explained in the
+"Non-cone Problems" section below, we do not recommend using it.
 +
 Use the `--[no-]sparse-index` option to use a sparse index (the
 default is to not use it).  A sparse index reduces the size of the
@@ -191,6 +190,97 @@ directory, it updates the skip-worktree bits in the index based
 on this file. The files matching the patterns in the file will
 appear in the working directory, and the rest will not.
 
+INTERNALS -- NON-CONE PROBLEMS
+------------------------------
+
+The `$GIT_DIR/info/sparse-checkout` file populated by the `set` and
+`add` subcommands is defined to be a bunch of patterns (one per line)
+using the same syntax as `.gitignore` files.  In cone mode, these
+patterns are restricted to matching directories (and users only ever
+need supply or see directory names), while in non-cone mode any
+gitignore-style pattern is permitted.  Using the full gitignore-style
+patterns in non-cone mode has a number of shortcomings:
+
+  * Fundamentally, it makes various worktree-updating processes (pull,
+    merge, rebase, switch, reset, checkout, etc.) require O(N*M) pattern
+    matches, where N is the number of patterns and M is the number of
+    paths in the index.  This scales poorly.
+
+  * Avoiding the scaling issue has to be done via limiting the number
+    of patterns via specifying leading directory name or glob.
+
+  * Passing globs on the command line is error-prone as users may
+    forget to quote the glob, causing the shell to expand it into all
+    matching files and pass them all individually along to
+    sparse-checkout set/add.  While this could also be a problem with
+    e.g. "git grep -- *.c", mistakes with grep/log/status appear in
+    the immediate output.  With sparse-checkout, the mistake gets
+    recorded at the time the sparse-checkout command is run and might
+    not be problematic until the user later switches branches or rebases
+    or merges, thus putting a delay between the user's error and when
+    they have a chance to catch/notice it.
+
+  * Related to the previous item, sparse-checkout has an 'add'
+    subcommand but no 'remove' subcommand.  Even if a 'remove'
+    subcommand were added, undoing an accidental unquoted glob runs
+    the risk of "removing too much", as it may remove entries that had
+    been included before the accidental add.
+
+  * Non-cone mode uses gitignore-style patterns to select what to
+    *include* (with the exception of negated patterns), while
+    .gitignore files use gitignore-style patterns to select what to
+    *exclude* (with the exception of negated patterns).  The
+    documentation on gitignore-style patterns usually does not talk in
+    terms of matching or non-matching, but on what the user wants to
+    "exclude".  This can cause confusion for users trying to learn how
+    to specify sparse-checkout patterns to get their desired behavior.
+
+  * Every other git subcommand that wants to provide "special path
+    pattern matching" of some sort uses pathspecs, but non-cone mode
+    for sparse-checkout uses gitignore patterns, which feels
+    inconsistent.
+
+  * It has edge cases where the "right" behavior is unclear.  Two examples:
+
+    First, two users are in a subdirectory, and the first runs
+       git sparse-checkout set '/toplevel-dir/*.c'
+    while the second runs
+       git sparse-checkout set relative-dir
+    Should those arguments be transliterated into
+       current/subdirectory/toplevel-dir/*.c
+    and
+       current/subdirectory/relative-dir
+    before inserting into the sparse-checkout file?  The user who typed
+    the first command is probably aware that arguments to set/add are
+    supposed to be patterns in non-cone mode, and probably would not be
+    happy with such a transliteration.  However, many gitignore-style
+    patterns are just paths, which might be what the user who typed the
+    second command was thinking, and they'd be upset if their argument
+    wasn't transliterated.
+
+    Second, what should bash-completion complete on for set/add commands
+    for non-cone users?  If it suggests paths, is it exacerbating the
+    problem above?  Also, if it suggests paths, what if the user has a
+    file or directory that begins with either a '!' or '#' or has a '*',
+    '\', '?', '[', or ']' in its name?  And if it suggests paths, will
+    it complete "/pro" to "/proc" (in the root filesytem) rather than to
+    "/progress.txt" in the current directory?  (Note that users are
+    likely to want to start paths with a leading '/' in non-cone mode,
+    for the same reason that .gitignore files often have one.)
+    Completing on files or directories might give nasty surprises in
+    all these cases.
+
+  * The excessive flexibility made other extensions essentially
+    impractical.  `--sparse-index` is likely impossible in non-cone
+    mode; even if it is somehow feasible, it would have been far more
+    work to implement and may have been too slow in practice.  Some
+    ideas for adding coupling between partial clones and sparse
+    checkouts are only practical with a more restricted set of paths
+    as well.
+
+For all these reasons, non-cone mode is deprecated.  Please switch to
+using cone mode.
+
 
 INTERNALS -- CONE MODE HANDLING
 -------------------------------
-- 
gitgitgadget

[PATCH v3 9/9] Documentation: some sparsity wording clarifications

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

Improve the wording for a couple paragraphs in two different manuals
relating to sparse behavior.

Reported-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Elijah Newren <newren@gmail.com>
---
 Documentation/git-read-tree.txt       | 11 +++++++----
 Documentation/git-sparse-checkout.txt | 10 +++++-----
 2 files changed, 12 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index 99bb387134d..d255807798c 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -375,10 +375,13 @@ have finished your work-in-progress), attempt the merge again.
 SPARSE CHECKOUT
 ---------------
 
-Note: The `update-index` and `read-tree` primitives for supporting the
-skip-worktree bit predated the introduction of
-linkgit:git-sparse-checkout[1].  Users are encouraged to use
-`sparse-checkout` in preference to these low-level primitives.
+Note: The skip-worktree capabilities in linkgit:git-update-index[1]
+and `read-tree` predated the introduction of
+linkgit:git-sparse-checkout[1].  Users are encouraged to use the
+`sparse-checkout` command in preference to these plumbing commands for
+sparse-checkout/skip-worktree related needs.  However, the information
+below might be useful to users trying to understand the pattern style
+used in non-cone mode of the `sparse-checkout` command.
 
 "Sparse checkout" allows populating the working directory sparsely.
 It uses the skip-worktree bit (see linkgit:git-update-index[1]) to
diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index c65d0ce96bb..3776705bf53 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -15,11 +15,11 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-This command is used to create sparse checkouts, which means that it
-changes the working tree from having all tracked files present, to only
-have a subset of them.  It can also switch which subset of files are
-present, or undo and go back to having all tracked files present in the
-working copy.
+This command is used to create sparse checkouts, which change the
+working tree from having all tracked files present to only having a
+subset of those files.  It can also switch which subset of files are
+present, or undo and go back to having all tracked files present in
+the working copy.
 
 The subset of files is chosen by providing a list of directories in
 cone mode (the default), or by providing a list of patterns in
-- 
gitgitgadget

Re: [PATCH v2 4/9] git-sparse-checkout.txt: update docs for deprecation of 'init'

[Junio C Hamano]

Elijah Newren <newren@gmail.com> writes:

>> less than ideal.  As we present "core" first (because it is the
>> default), we should present "core" by itself, without requiring to
>> know what the other thing is.
>
> By '"core" section' do you mean the "cone pattern set" section?

s/core/cone mode/g, I guess (because it is so long ago I do not
offhand recall what I had in mind exactly back when I wrote it).

Re: [PATCH v3 0/9] sparse-checkout: make cone mode the default

[Derrick Stolee]

On 4/21/2022 10:32 PM, Elijah Newren via GitGitGadget wrote:
> Sorry for the long delay since v1. On the plus side, perhaps there will be a
> longer feedback period for this series since it's now really early in the
> 2.37 series?

Yes, a merge early in the cycle would be good for feedback, if any.

> == Updates Log ==
> 
> Changes since v2:
> 
>  * Code style tweak suggested by Junio in one area, reverting back to v1.
>  * Several documentation updates to address Junio's review. Patches 6 & 7
>    had significant changes and would most benefit from a further review.

I took a quick scan of the range-diff, and read patches 6 and 7
on their own. This version looks good to me.

Thanks,
-Stolee