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 filesystem) 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
-------------------------------

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
inclusion/exclusion rules. These can result