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

[Junio C Hamano <gitster@pobox.com>]

"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.