From: Elijah Newren <newren@xxxxxxxxx> 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@xxxxxxxxx> --- 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
