On 3/9/2021 4:03 PM, Elijah Newren wrote: > On Tue, Mar 9, 2021 at 12:52 PM Derrick Stolee <stolee@xxxxxxxxx> wrote: >> >> On 2/24/2021 2:11 PM, Martin Ågren wrote: >>> There are several "layers" here, for lack of a better term. "Enabling foo >>> enables bar which may cause baz. If you fail due to baz, try dropping >>> bar by dropping foo." If I remove any mention of the config variable from >>> your text, I get the following. >>> >>> Enabling sparse index might cause other tools to stop working with your >>> repository. If you have trouble with this compatibility, then run `git >>> sparse-checkout sparse-index disable` to rewrite your index to not be >>> sparse. >>> >>> I'm tempted to suggest such a rewrite to relieve readers of knowing of >>> the middle step, which you could say is more of an implementation >>> detail. But if we think that the symptoms / error messages might involve >>> "extensions.sparseIndex" or, as would be the case with an older Git >>> installation, >>> >>> fatal: unknown repository extensions found: >>> sparseindex >>> >>> maybe there is some value in mentioning the config item by name. Just >>> thinking out loud, really, and I don't have any strong opinion. I only >>> came here to point out the typo in the docs. >> >> I agree that the layers are confusing. We could rearrange and have >> a similar flow to what you recommend by mentioning the extension at >> the end: >> >> **WARNING:** Using a sparse index requires modifying the index in a way >> that is not completely understood by other tools. If you have trouble with >> this compatibility, then run `git sparse-checkout sparse-index disable` to >> rewrite your index to not be sparse. Older versions of Git will not >> understand the `sparseIndex` repository extension and may fail to interact >> with your repository until it is disabled. >> >> Thanks, >> -Stolee > > This looks pretty good to me, but could we change the first sentence > to read "...modifying the index in a way that may not yet be > understood by external tools." ? I'm worried "other tools" might make > people worry about different builtin commands (e.g. fast-export, log). > I also prefer "may" and "yet" because I suspect most external tools > (e.g. git filter-repo just to name a personal example) won't need to > read an index format and will thus be unaffected, and any tools that > do read the index format will probably eventually learn how to work > with the new format. I can make the change, but I do want to point out that the current use of a repository extension _does_ mean that tools that (correctly) interact with a Git repository should fail even if they don't try to access the index file. This is only something to make this work until we introduce a new index file format version and then can drop the extension. "git filter-repo" _should_ be safe because it's really just shelling to Git, right? I'm more concerned about tools like libgit2. Thanks, -Stolee
