git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
Elijah Newren <newren@gmail.com>
Date
Apr 22, 2022, 02:31 UTC
Message-ID
<CABPp-BH_GuWdW55FAF=keidVWv+Zy3OJG6pN-VpcpOdCZuKqGw@mail.gmail.com>
In-Reply-To
<xmqqa6dsp78q.fsf@gitster.g>
On Mon, Mar 14, 2022 at 2:14 PM Junio C Hamano <gitster@pobox.com> wrote:
Show 10 quoted lines
>
> "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.

Show 7 quoted lines
> 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.

Show 34 quoted lines
> > +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.

Show 6 quoted lines
> > +  * 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).

Show 6 quoted lines
> > +  * 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.

Show 26 quoted lines
> > +  * 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.

Previous: Junio C HamanoNext: Elijah Newren via GitGitGadget
Message 38 of 54 in “sparse-checkout: make cone mode the default”
  1. 0/9 sparse-checkout: make cone mode the defaultElijah Newren via GitGitGadget, Mar 8, 2022
  2. 3/9 git-sparse-checkout.txt: wording updates for the cone mode defaultElijah Newren via GitGitGadget, Mar 8, 2022
  3. 2/9 sparse-checkout: make --cone the defaultElijah Newren via GitGitGadget, Mar 8, 2022
  4. Derrick StoleeMar 8, 2022
  5. Elijah NewrenMar 12, 2022
  6. 1/9 tests: stop assuming --no-cone is the default mode for sparse-checkoutElijah Newren via GitGitGadget, Mar 8, 2022
  7. 4/9 git-sparse-checkout.txt: update docs for deprecation of 'init'Elijah Newren via GitGitGadget, Mar 8, 2022
  8. 5/9 git-sparse-checkout.txt: shuffle some sections and mark as internalElijah Newren via GitGitGadget, Mar 8, 2022
  9. 6/9 git-sparse-checkout.txt: add a new EXAMPLES sectionElijah Newren via GitGitGadget, Mar 8, 2022
  10. Derrick StoleeMar 8, 2022
  11. Elijah NewrenMar 12, 2022
  12. 7/9 git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a bitElijah Newren via GitGitGadget, Mar 8, 2022
  13. 8/9 git-sparse-checkout.txt: mark non-cone mode as deprecatedElijah Newren via GitGitGadget, Mar 8, 2022
  14. 9/9 Documentation: some sparsity wording clarificationsElijah Newren via GitGitGadget, Mar 8, 2022
  15. Derrick StoleeMar 8, 2022
  16. 0/9 sparse-checkout: make cone mode the defaultElijah Newren via GitGitGadget, Mar 12, 2022
  17. 2/9 sparse-checkout: make --cone the defaultElijah Newren via GitGitGadget, Mar 12, 2022
  18. Junio C HamanoMar 14, 2022
  19. Elijah NewrenApr 22, 2022
  20. 1/9 tests: stop assuming --no-cone is the default mode for sparse-checkoutElijah Newren via GitGitGadget, Mar 12, 2022
  21. Junio C HamanoMar 14, 2022
  22. Derrick StoleeMar 15, 2022
  23. 3/9 git-sparse-checkout.txt: wording updates for the cone mode defaultElijah Newren via GitGitGadget, Mar 12, 2022
  24. Junio C HamanoMar 14, 2022
  25. 4/9 git-sparse-checkout.txt: update docs for deprecation of 'init'Elijah Newren via GitGitGadget, Mar 12, 2022
  26. Junio C HamanoMar 14, 2022
  27. Elijah NewrenApr 22, 2022
  28. Junio C HamanoApr 22, 2022
  29. 6/9 git-sparse-checkout.txt: add a new EXAMPLES sectionElijah Newren via GitGitGadget, Mar 12, 2022
  30. 5/9 git-sparse-checkout.txt: shuffle some sections and mark as internalElijah Newren via GitGitGadget, Mar 12, 2022
  31. Junio C HamanoMar 14, 2022
  32. Elijah NewrenApr 22, 2022
  33. 7/9 git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a bitElijah Newren via GitGitGadget, Mar 12, 2022
  34. Junio C HamanoMar 14, 2022
  35. Elijah NewrenApr 22, 2022
  36. 8/9 git-sparse-checkout.txt: mark non-cone mode as deprecatedElijah Newren via GitGitGadget, Mar 12, 2022
  37. Junio C HamanoMar 14, 2022
  38. Elijah NewrenApr 22, 2022
  39. 9/9 Documentation: some sparsity wording clarificationsElijah Newren via GitGitGadget, Mar 12, 2022
  40. Derrick StoleeMar 14, 2022
  41. Victoria DyeMar 14, 2022
  42. Junio C HamanoMar 14, 2022
  43. Junio C HamanoMar 14, 2022
  44. 0/9 sparse-checkout: make cone mode the defaultElijah Newren via GitGitGadget, Apr 22, 2022
  45. 1/9 tests: stop assuming --no-cone is the default mode for sparse-checkoutElijah Newren via GitGitGadget, Apr 22, 2022
  46. 2/9 sparse-checkout: make --cone the defaultElijah Newren via GitGitGadget, Apr 22, 2022
  47. 3/9 git-sparse-checkout.txt: wording updates for the cone mode defaultElijah Newren via GitGitGadget, Apr 22, 2022
  48. 4/9 git-sparse-checkout.txt: update docs for deprecation of 'init'Elijah Newren via GitGitGadget, Apr 22, 2022
  49. 5/9 git-sparse-checkout.txt: shuffle some sections and mark as internalElijah Newren via GitGitGadget, Apr 22, 2022
  50. 9/9 Documentation: some sparsity wording clarificationsElijah Newren via GitGitGadget, Apr 22, 2022
  51. 8/9 git-sparse-checkout.txt: mark non-cone mode as deprecatedElijah Newren via GitGitGadget, Apr 22, 2022
  52. 7/9 git-sparse-checkout.txt: flesh out pattern set sections a bitElijah Newren via GitGitGadget, Apr 22, 2022
  53. 6/9 git-sparse-checkout.txt: add a new EXAMPLES sectionElijah Newren via GitGitGadget, Apr 22, 2022
  54. Derrick StoleeApr 25, 2022

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.