git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: "Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com>
To: git@vger.kernel.org
Cc: Victoria Dye <vdye@github.com>,
	Lessley Dennington <lessleydennington@gmail.com>,
	Derrick Stolee <derrickstolee@github.com>,
	Elijah Newren <newren@gmail.com>,
	Elijah Newren <newren@gmail.com>,
	Elijah Newren <newren@gmail.com>
Subject: [PATCH v3 8/9] git-sparse-checkout.txt: mark non-cone mode as deprecated
Date: Fri, 22 Apr 2022 02:32:25 +0000	[thread overview]
Message-ID: <a1b68fd6126eb341ef3637bb93fedad4309b36d0.1650594746.git.gitgitgadget@gmail.com> (raw)
In-Reply-To: <pull.1148.v3.git.1650594746.gitgitgadget@gmail.com>

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


  parent reply	other threads:[~2022-04-22  2:32 UTC|newest]

Thread overview: 54+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-03-08  7:39 [PATCH 0/9] sparse-checkout: make cone mode the default Elijah Newren via GitGitGadget
2022-03-08  7:39 ` [PATCH 1/9] tests: stop assuming --no-cone is the default mode for sparse-checkout Elijah Newren via GitGitGadget
2022-03-08  7:39 ` [PATCH 2/9] sparse-checkout: make --cone the default Elijah Newren via GitGitGadget
2022-03-08 14:26   ` Derrick Stolee
2022-03-12  2:01     ` Elijah Newren
2022-03-08  7:39 ` [PATCH 3/9] git-sparse-checkout.txt: wording updates for the cone mode default Elijah Newren via GitGitGadget
2022-03-08  7:39 ` [PATCH 4/9] git-sparse-checkout.txt: update docs for deprecation of 'init' Elijah Newren via GitGitGadget
2022-03-08  7:39 ` [PATCH 5/9] git-sparse-checkout.txt: shuffle some sections and mark as internal Elijah Newren via GitGitGadget
2022-03-08  7:39 ` [PATCH 6/9] git-sparse-checkout.txt: add a new EXAMPLES section Elijah Newren via GitGitGadget
2022-03-08 14:30   ` Derrick Stolee
2022-03-12  1:58     ` Elijah Newren
2022-03-08  7:39 ` [PATCH 7/9] git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a bit Elijah Newren via GitGitGadget
2022-03-08  7:39 ` [PATCH 8/9] git-sparse-checkout.txt: mark non-cone mode as deprecated Elijah Newren via GitGitGadget
2022-03-08  7:39 ` [PATCH 9/9] Documentation: some sparsity wording clarifications Elijah Newren via GitGitGadget
2022-03-08 14:34 ` [PATCH 0/9] sparse-checkout: make cone mode the default Derrick Stolee
2022-03-12  3:11 ` [PATCH v2 " Elijah Newren via GitGitGadget
2022-03-12  3:11   ` [PATCH v2 1/9] tests: stop assuming --no-cone is the default mode for sparse-checkout Elijah Newren via GitGitGadget
2022-03-14 20:18     ` Junio C Hamano
2022-03-15 17:15       ` Derrick Stolee
2022-03-12  3:11   ` [PATCH v2 2/9] sparse-checkout: make --cone the default Elijah Newren via GitGitGadget
2022-03-14 20:34     ` Junio C Hamano
2022-04-22  2:29       ` Elijah Newren
2022-03-12  3:11   ` [PATCH v2 3/9] git-sparse-checkout.txt: wording updates for the cone mode default Elijah Newren via GitGitGadget
2022-03-14 20:39     ` Junio C Hamano
2022-03-12  3:11   ` [PATCH v2 4/9] git-sparse-checkout.txt: update docs for deprecation of 'init' Elijah Newren via GitGitGadget
2022-03-14 20:53     ` Junio C Hamano
2022-04-22  2:29       ` Elijah Newren
2022-04-22  6:09         ` Junio C Hamano
2022-03-12  3:11   ` [PATCH v2 5/9] git-sparse-checkout.txt: shuffle some sections and mark as internal Elijah Newren via GitGitGadget
2022-03-14 20:55     ` Junio C Hamano
2022-04-22  2:30       ` Elijah Newren
2022-03-12  3:11   ` [PATCH v2 6/9] git-sparse-checkout.txt: add a new EXAMPLES section Elijah Newren via GitGitGadget
2022-03-12  3:11   ` [PATCH v2 7/9] git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a bit Elijah Newren via GitGitGadget
2022-03-14 20:57     ` Junio C Hamano
2022-04-22  2:30       ` Elijah Newren
2022-03-12  3:11   ` [PATCH v2 8/9] git-sparse-checkout.txt: mark non-cone mode as deprecated Elijah Newren via GitGitGadget
2022-03-14 21:13     ` Junio C Hamano
2022-04-22  2:31       ` Elijah Newren
2022-03-12  3:11   ` [PATCH v2 9/9] Documentation: some sparsity wording clarifications Elijah Newren via GitGitGadget
2022-03-14 15:25   ` [PATCH v2 0/9] sparse-checkout: make cone mode the default Derrick Stolee
2022-03-14 19:04   ` Victoria Dye
2022-03-14 20:12   ` Junio C Hamano
2022-03-14 23:19     ` Junio C Hamano
2022-04-22  2:32   ` [PATCH v3 " Elijah Newren via GitGitGadget
2022-04-22  2:32     ` [PATCH v3 1/9] tests: stop assuming --no-cone is the default mode for sparse-checkout Elijah Newren via GitGitGadget
2022-04-22  2:32     ` [PATCH v3 2/9] sparse-checkout: make --cone the default Elijah Newren via GitGitGadget
2022-04-22  2:32     ` [PATCH v3 3/9] git-sparse-checkout.txt: wording updates for the cone mode default Elijah Newren via GitGitGadget
2022-04-22  2:32     ` [PATCH v3 4/9] git-sparse-checkout.txt: update docs for deprecation of 'init' Elijah Newren via GitGitGadget
2022-04-22  2:32     ` [PATCH v3 5/9] git-sparse-checkout.txt: shuffle some sections and mark as internal Elijah Newren via GitGitGadget
2022-04-22  2:32     ` [PATCH v3 6/9] git-sparse-checkout.txt: add a new EXAMPLES section Elijah Newren via GitGitGadget
2022-04-22  2:32     ` [PATCH v3 7/9] git-sparse-checkout.txt: flesh out pattern set sections a bit Elijah Newren via GitGitGadget
2022-04-22  2:32     ` Elijah Newren via GitGitGadget [this message]
2022-04-22  2:32     ` [PATCH v3 9/9] Documentation: some sparsity wording clarifications Elijah Newren via GitGitGadget
2022-04-25 14:38     ` [PATCH v3 0/9] sparse-checkout: make cone mode the default Derrick Stolee

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=a1b68fd6126eb341ef3637bb93fedad4309b36d0.1650594746.git.gitgitgadget@gmail.com \
    --to=gitgitgadget@gmail.com \
    --cc=derrickstolee@github.com \
    --cc=git@vger.kernel.org \
    --cc=lessleydennington@gmail.com \
    --cc=newren@gmail.com \
    --cc=vdye@github.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).