[0/9] sparse-checkout: make cone mode the default

Message

Derrick Stolee via GitGitGadget March 8, 2022, 7:39 a.m. UTC

== Maintainer Note ==

Depends on a merge of en/present-despite-skipped into master.

== Overview ==

This patch changes the default mode for sparse-checkout from non-cone mode
to cone-mode, and marks non-cone mode as deprecated. There is no plan to
remove non-cone mode, we are merely recommending against its use.

The code change is pretty small, and most of this series is about
documentation updates -- to focus on directories rather than patterns, to
explain the new default, to explain why we are deprecating non-cone mode
(the final patch), and to make other related cleanups to simplify the
manual.

Patch 1: Update tests to not assume cone-mode is the default Patch 2: Make
cone-mode the default Patches 3-9: Various updates to
git-sparse-checkout.txt, divided up for ease of review

== Alternative ==

There is one primary alternative to this series: make sparse-checkout error
when neither --cone nor --no-cone are specified (so that there is no
default), and wait until a future date to make --cone the default. That'd be
reasonable, but I had three reason to avoid going this route (note that item
2 means there's little practical difference between cone-mode-as-default and
no-mode-is-default):

 1. git-sparse-checkout.txt has the following huge warning early in the
    manual:

""" THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR, AND THE BEHAVIOR OF OTHER
COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN THE
FUTURE. """

 2. If users are unaware of the default change and attempt to provide
    patterns instead of directories, then they will get error messages added
    from en/sparse-checkout-fixes. They can learn at that time to get around
    the error messages by providing --no-cone.

 3. If users are unaware of the default change and provide directories, then
    that's where non-cone mode and cone mode overlap and things happen to
    work. (There is a slight difference in that cone mode will include files
    from parent directories of any specified directory, but that means the
    user gets a few more files in their sparse-checkout with cone mode than
    they would with non-cone mode.)

== CCs ==

Elijah Newren (9):
  tests: stop assuming --no-cone is the default mode for sparse-checkout
  sparse-checkout: make --cone the default
  git-sparse-checkout.txt: wording updates for the cone mode default
  git-sparse-checkout.txt: update docs for deprecation of 'init'
  git-sparse-checkout.txt: shuffle some sections and mark as internal
  git-sparse-checkout.txt: add a new EXAMPLES section
  git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a
    bit
  git-sparse-checkout.txt: mark non-cone mode as deprecated
  Documentation: some sparsity wording clarifications

 Documentation/git-read-tree.txt       |   9 +-
 Documentation/git-sparse-checkout.txt | 248 +++++++++++++++++++-------
 builtin/sparse-checkout.c             |   2 +-
 t/t1091-sparse-checkout-builtin.sh    |  15 +-
 t/t3602-rm-sparse-checkout.sh         |   6 +-
 t/t3705-add-sparse-checkout.sh        |   4 +-
 t/t6428-merge-conflicts-sparse.sh     |   4 +-
 t/t7002-mv-sparse-checkout.sh         |   2 +-
 t/t7012-skip-worktree-writing.sh      |   2 +-
 9 files changed, 206 insertions(+), 86 deletions(-)


base-commit: af002ccf9fe2ce6cce9111323423f1d4739bcf0d
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1148%2Fnewren%2Fsparse-checkout-default-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1148/newren/sparse-checkout-default-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1148

Comments

Derrick Stolee March 8, 2022, 2:34 p.m. UTC | #1

On 3/8/2022 2:39 AM, Elijah Newren via GitGitGadget wrote:
> == Maintainer Note ==
> 
> Depends on a merge of en/present-despite-skipped into master.
> 
> == Overview ==
> 
> This patch changes the default mode for sparse-checkout from non-cone mode
> to cone-mode, and marks non-cone mode as deprecated. There is no plan to
> remove non-cone mode, we are merely recommending against its use.
> 
> The code change is pretty small, and most of this series is about
> documentation updates -- to focus on directories rather than patterns, to
> explain the new default, to explain why we are deprecating non-cone mode
> (the final patch), and to make other related cleanups to simplify the
> manual.

I made a couple comments with potential ways to improve the series, but
in general this series is high quality without any changes. I'm happy
with it as-is.

I'm particularly happy with the additional examples of how to use the
sparse-checkout builtin. That should really improve discoverability.

> == Alternative ==
> 
> There is one primary alternative to this series: make sparse-checkout error
> when neither --cone nor --no-cone are specified (so that there is no
> default), and wait until a future date to make --cone the default.

I appreciate considering this alternative, and I'd be open to it, if
needed. My gut feeling is that we don't need it.

Thanks,
-Stolee