[Tyrie Vella (tyrielv)]

Problem and Context

A repository with core.virtualFilesystem cannot use a sparse index today. There are three causes:

• path_in_sparse_checkout() reports every path as inside the sparse-checkout under a virtual file system. So convert_to_sparse() never collapses an out-of-cone directory into a sparse-directory entry.
• apply_virtualfilesystem() runs on every index read. When it looks up a reported path inside a sparse directory, index_name_pos() expands the whole index. On a repository with about 2.2 million index entries, this full expansion costs many seconds on every command.
• After expand_index(), the name-hash cannot find the cache entries that the expansion reuses. With core.ignoreCase, lookups then miss tracked in-cone files. Under a virtual file system, git sparse-checkout add or reapply then deletes in-cone files from the working tree. Without a virtual file system, git status can report a tracked in-cone directory as untracked (see the first commit).

The changes to the virtual file system behavior apply only when core.virtualFilesystem is set. The cone patterns are used only when the repository also uses cone-mode sparse-checkout and sets index.sparse to true in its configuration. The default value of index.sparse (true) does not count, so that a virtual file system that cannot read a sparse index never gets one. A virtual file system repository without these settings behaves as before.

A virtual file system that uses a sparse index must keep modified files inside the cone. Git does not check the working tree for a path inside a sparse-directory entry, even when the hook reports the path.

Changes

The first commit fixes a sparse-index bug that does not depend on a virtual file system. In a plain cone-mode repository with index.sparse, core.ignoreCase, and sparse.expectFilesOutsideOfPatterns, git status reports a tracked in-cone directory as untracked when an untracked file sits in an out-of-cone directory that the walk visits first. The commit can move to a separate pull request if reviewers prefer.

• sparse-index.c: expand_index() clears CE_HASHED on each reused cache entry, so that the next lazy_init_name_hash() adds it to the new name-hash. It also discards the old name-hash with free_name_hash(), which frees the dir_hash entries that hashmap_clear() leaked. The new git status test exposes that leak. This change is not limited to a virtual file system.
• t/helper/test-read-cache.c: add a --expand-and-find=<path> option. It looks up a path in the name-hash, expands the index, and looks up the path again.
• Add t1092 tests that use this option, and that run git status with core.ignoreCase after an expansion.
• virtualfilesystem.c: clear_ce_flags_virtualfilesystem_1() uses index_name_pos_sparse() instead of index_name_pos(). A reported path inside a sparse directory is not found, so the sparse-directory entry keeps its skip-worktree bit. With a full index the two functions are the same. The directory-wildcard loop skips nested sparse-directory entries.
• Add t1095. The tests use trace2 regions and expansion-reason data to check that the index does not expand. They check the skip-worktree bits for paths inside sparse directories, for directory wildcards, and for case-insensitive matches.
• virtualfilesystem.c: add vfs_sparse_index_configured() and vfs_uses_cone_patterns(). The first returns true when the configuration sets cone mode and sets index.sparse to true explicitly. The second also checks the cone-mode pattern file. They run for each path, so they do not read the environment or write the configuration, unlike is_sparse_index_allowed(istate, 0).
• dir.c: under a virtual file system, path_in_sparse_checkout_1() uses the cone patterns when vfs_uses_cone_patterns() returns true. path_matches_pattern_list() gets a pattern list that is already in cone mode, so it checks only vfs_sparse_index_configured(). This keeps it from loading patterns into the temporary index of expand_index(). For a cone-mode pattern list, path_matches_pattern_list() skips its virtual file system block. That block returns 1 for a directory that the hook does not report, and for the cone list 1 means "in the cone". This also fixes git sparse-checkout reapply on a collapsed index, which died with is_excluded_from_virtualfilesystem passed unhandled dtype.
• read-cache.c: under a virtual file system, do_read_index() does not collapse a full index. The skip-worktree bits are not correct until apply_virtualfilesystem() sets them, after the read. The index collapses when it is written.
• Data-loss prevention in builtin/sparse-checkout.c: clean_tracked_sparse_directories() returns early under a virtual file system. After git sparse-checkout set, add, or reapply, this function deletes each out-of-cone directory that has no untracked files. A virtual file system shows these directories in the working tree and owns them. Without this guard, a collapsed index under a virtual file system makes Git delete the projected out-of-cone files.
• Documentation/config/core.adoc: describe how core.virtualFilesystem works with cone mode and an explicit index.sparse=true.
• Add t1096. In these tests the out-of-cone files are on disk, as a virtual file system shows them. The tests check that nothing collapses with index.sparse false or with its default value, and that the out-of-cone directory collapses with index.sparse true. They check that git status does not expand the index, and that git sparse-checkout add and reapply keep all files on disk. They also check that a directory with a reported path does not collapse, and that the behavior without a virtual file system or without cone mode does not change.

Known gaps and deliberate decisions

• The working-tree walk can still expand the index. git status with untracked-file scanning can still expand the index when the walk enters an out-of-cone directory. The tests in this change use --untracked-files=no. A separate change handles the lookups in the working-tree walk.
• A reported path inside a collapsed directory is ignored. Git does not check the working tree for it, and no trace2 value names it. Keeping modified paths inside the cone is the responsibility of the virtual file system.
• Per-path cost. vfs_uses_cone_patterns() runs for each path under a virtual file system. It reads only the cached configuration and the loaded patterns. Its cost on a very large repository was not measured separately.
• Path-walk under a virtual file system. The path-walk API (for example git backfill --sparse) uses a cone-mode pattern list. With the cone patterns in use, it now matches only the patterns, as it does without a virtual file system.