From dde1358970ab9ddafb9f664baadeddde1e9e7842 Mon Sep 17 00:00:00 2001 From: Elijah Newren Date: Fri, 22 Apr 2022 02:32:18 +0000 Subject: [PATCH 1/9] tests: stop assuming --no-cone is the default mode for sparse-checkout Add an explicit --no-cone to several sparse-checkout invocations in preparation for changing the default to cone mode. Signed-off-by: Elijah Newren Signed-off-by: Junio C Hamano --- 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 9a90031018..de1ec89007 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 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 034ec01091..08580fd3dc 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 95609046c6..2bade9e804 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 142c9aaabc..064be1b629 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 1d3d2aca21..f0f7cbfcdb 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 cb9f1a6981..cd5c20fe51 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 && From 2d95707a02ffd68933f8af0fa76090bea908d376 Mon Sep 17 00:00:00 2001 From: Elijah Newren Date: Fri, 22 Apr 2022 02:32:19 +0000 Subject: [PATCH 2/9] sparse-checkout: make --cone the default Make cone mode the default, and update the documentation accordingly. Signed-off-by: Elijah Newren Signed-off-by: Junio C Hamano --- 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 c04f62a54a..03cf075821 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 88e55f432f..7308e744c5 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 5518ed47f6..61b7a7519b 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 { From f69dfef355aec867693deb68376a08e97303d61c Mon Sep 17 00:00:00 2001 From: Elijah Newren Date: Fri, 22 Apr 2022 02:32:20 +0000 Subject: [PATCH 3/9] git-sparse-checkout.txt: wording updates for the cone mode default 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 Signed-off-by: Junio C Hamano --- 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 7308e744c5..b5db812f09 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 ---------------- /* From 71ceb816b3d22953c63f3d71b6c8e5d016ece958 Mon Sep 17 00:00:00 2001 From: Elijah Newren Date: Fri, 22 Apr 2022 02:32:21 +0000 Subject: [PATCH 4/9] git-sparse-checkout.txt: update docs for deprecation of 'init' 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 Signed-off-by: Junio C Hamano --- 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 b5db812f09..8e80d1c733 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: ---------------- /* From 0d86f59a3c7ce06bebb44a691cf8743e8eda1fbe Mon Sep 17 00:00:00 2001 From: Elijah Newren Date: Fri, 22 Apr 2022 02:32:22 +0000 Subject: [PATCH 5/9] git-sparse-checkout.txt: shuffle some sections and mark as internal 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 Signed-off-by: Junio C Hamano --- 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 8e80d1c733..2083e6df35 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. From 5d295dc39606990688766916a2bcf93dc0efb61b Mon Sep 17 00:00:00 2001 From: Elijah Newren Date: Fri, 22 Apr 2022 02:32:23 +0000 Subject: [PATCH 6/9] git-sparse-checkout.txt: add a new EXAMPLES section 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 Signed-off-by: Junio C Hamano --- 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 2083e6df35..c54437428b 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 ----------------------------- From 72fa58ef50e8f7fcc1b992168785219726fb162e Mon Sep 17 00:00:00 2001 From: Elijah Newren Date: Fri, 22 Apr 2022 02:32:24 +0000 Subject: [PATCH 7/9] 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 Signed-off-by: Junio C Hamano --- 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 c54437428b..6e32034511 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 ----------------------- From a8defed07cb4c287306d228b2e9f03d1195f5395 Mon Sep 17 00:00:00 2001 From: Elijah Newren Date: Fri, 22 Apr 2022 02:32:25 +0000 Subject: [PATCH 8/9] git-sparse-checkout.txt: mark non-cone mode as deprecated 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 Signed-off-by: Junio C Hamano --- 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 6e32034511..c65d0ce96b 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 ------------------------------- From 5d4b2933407286ac2b76a1a66a04967a35d973f0 Mon Sep 17 00:00:00 2001 From: Elijah Newren Date: Fri, 22 Apr 2022 02:32:26 +0000 Subject: [PATCH 9/9] Documentation: some sparsity wording clarifications MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Improve the wording for a couple paragraphs in two different manuals relating to sparse behavior. Reported-by: Ævar Arnfjörð Bjarmason Signed-off-by: Elijah Newren Signed-off-by: Junio C Hamano --- 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 99bb387134..d255807798 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 c65d0ce96b..3776705bf5 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