Re: [PATCH v2 4/9] git-sparse-checkout.txt: update docs for deprecation of 'init'

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 14, 2022, 20:53 UTC
Message-ID: <xmqqwngwp87k.fsf@gitster.g>
In-Reply-To: <eb3b318b39ec3eed754eab7d2c9d20198117545b.1647054681.git.gitgitgadget@gmail.com>

"Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 7 quoted lines

> -When `--no-cone` is passed or `core.sparseCheckoutCone` is false,
> -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 "Pattern
> -Set" sections below for more details.
> +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

"less perfromant" can be quantified, but "harder to use" is probably harder to defend. Those on a project with need for more flexible way to specify than "these are the directories I care about" would not find it convincing.

> +not recommended.  See the "Sparse Checkout" section of
> +linkgit:git-read-tree[1]

The referenced section (I am reading "git read-tree --help" from seen with these patches) may need updating. It shows an example of including everything except for unwanted, without mentioning if that is for cone or non-cone.

> and the "Pattern Set" sections below for more
> +details.

Are we referring to "Internals - cone/full pattern set" sections?

This may be a topic of another step in this series, but the "core" section starts by mentioning what characteristics the full pattern set has and uses it to steer readers away from it, which I find it less than ideal. As we present "core" first (because it is the default), we should present "core" by itself, without requiring to know what the other thing is. Perhaps replace the entire first paragraph so that the section begins more like so:

	The "cone mode", which is the default, lets you specify only
	what directories to include and what directories to exclude.

	The accepted patterns in the cone pattern set are:...

Especially, the last sentence in the paragraph to be struck still lives in the old world in which you needed to opt into the cone mode.

Thanks.