Add virtual file system settings and hook proc

benpeart · dscho · commit d991bc6dc8b4 · 2025-08-08T18:54:56.000+02:00
On index load, clear/set the skip worktree bits based on the virtual
file system data. Use virtual file system data to update skip-worktree
bit in unpack-trees. Use virtual file system data to exclude files and
folders not explicitly requested.

Update 2022-04-05: disable the "present-despite-SKIP_WORKTREE" file removal
behavior when 'core.virtualfilesystem' is enabled.

Signed-off-by: Ben Peart &lt;benpeart@microsoft.com&gt;
diff --git a/Documentation/config/core.adoc b/Documentation/config/core.adoc
@@ -111,6 +111,14 @@ Version 2 uses an opaque string so that the monitor can return
 something that can be used to determine what files have changed
 without race conditions.
 
+core.virtualFilesystem::
+	If set, the value of this variable is used as a command which
+	will identify all files and directories that are present in
+	the working directory.  Git will only track and update files
+	listed in the virtual file system.  Using the virtual file system
+	will supersede the sparse-checkout settings which will be ignored.
+	See the "virtual file system" section of linkgit:githooks[5].
+
 core.trustctime::
 	If false, the ctime differences between the index and the
 	working tree are ignored; useful when the inode change time
diff --git a/Documentation/githooks.adoc b/Documentation/githooks.adoc
@@ -758,6 +758,26 @@ and "0" meaning they were not.
 Only one parameter should be set to "1" when the hook runs.  The hook
 running passing "1", "1" should not be possible.
 
+virtualFilesystem
+~~~~~~~~~~~~~~~~~~
+
+"Virtual File System" allows populating the working directory sparsely.
+The projection data is typically automatically generated by an external
+process.  Git will limit what files it checks for changes as well as which
+directories are checked for untracked files based on the path names given.
+Git will also only update those files listed in the projection.
+
+The hook is invoked when the configuration option core.virtualFilesystem
+is set.  It takes one argument, a version (currently 1).
+
+The hook should output to stdout the list of all files in the working
+directory that git should track.  The paths are relative to the root
+of the working directory and are separated by a single NUL.  Full paths
+('dir1/a.txt') as well as directories are supported (ie 'dir1/').
+
+The exit status determines whether git will use the data from the
+hook.  On error, git will abort the command with an error message.
+
 SEE ALSO
 --------
 linkgit:git-hook[1]
diff --git a/Makefile b/Makefile
@@ -1206,6 +1206,7 @@ LIB_OBJS += utf8.o
 LIB_OBJS += varint.o
 LIB_OBJS += version.o
 LIB_OBJS += versioncmp.o
+LIB_OBJS += virtualfilesystem.o
 LIB_OBJS += walker.o
 LIB_OBJS += wildmatch.o
 LIB_OBJS += worktree.o
diff --git a/config.c b/config.c
@@ -2186,6 +2186,32 @@ int repo_config_get_max_percent_split_change(struct repository *r)
 	return -1; /* default value */
 }
 
+int repo_config_get_virtualfilesystem(struct repository *r)
+{
+	/* Run only once. */
+	static int virtual_filesystem_result = -1;
+	extern char *core_virtualfilesystem;
+	extern int core_apply_sparse_checkout;
+	if (virtual_filesystem_result >= 0)
+		return virtual_filesystem_result;
+
+	if (repo_config_get_pathname(r, "core.virtualfilesystem", &core_virtualfilesystem))
+		core_virtualfilesystem = xstrdup_or_null(getenv("GIT_VIRTUALFILESYSTEM_TEST"));
+
+	if (core_virtualfilesystem && !*core_virtualfilesystem)
+		FREE_AND_NULL(core_virtualfilesystem);
+
+	/* virtual file system relies on the sparse checkout logic so force it on */
+	if (core_virtualfilesystem) {
+		core_apply_sparse_checkout = 1;
+		virtual_filesystem_result = 1;
+		return 1;
+	}
+
+	virtual_filesystem_result = 0;
+	return 0;
+}
+
 int repo_config_get_index_threads(struct repository *r, int *dest)
 {
 	int is_bool, val;
diff --git a/config.h b/config.h
@@ -686,6 +686,8 @@ int repo_config_get_index_threads(struct repository *r, int *dest);
 int repo_config_get_split_index(struct repository *r);
 int repo_config_get_max_percent_split_change(struct repository *r);
 
+int repo_config_get_virtualfilesystem(struct repository *r);
+
 /* This dies if the configured or default date is in the future */
 int repo_config_get_expiry(struct repository *r, const char *key, char **output);
 
diff --git a/dir.c b/dir.c
@@ -11,6 +11,7 @@
 
 #include "git-compat-util.h"
 #include "abspath.h"
+#include "virtualfilesystem.h"
 #include "config.h"
 #include "convert.h"
 #include "dir.h"
@@ -1498,6 +1499,19 @@ enum pattern_match_result path_matches_pattern_list(
 	int result = NOT_MATCHED;
 	size_t slash_pos;
 
+	if (core_virtualfilesystem) {
+		/*
+		* The virtual file system data is used to prevent git from traversing
+		* any part of the tree that is not in the virtual file system.  Return
+		* 1 to exclude the entry if it is not found in the virtual file system,
+		* else fall through to the regular excludes logic as it may further exclude.
+		*/
+		if (*dtype == DT_UNKNOWN)
+			*dtype = resolve_dtype(DT_UNKNOWN, istate, pathname, pathlen);
+		if (is_excluded_from_virtualfilesystem(pathname, pathlen, *dtype) > 0)
+			return 1;
+	}
+
 	if (!pl->use_cone_patterns) {
 		pattern = last_matching_pattern_from_list(pathname, pathlen, basename,
 							dtype, pl, istate);
@@ -1842,8 +1856,22 @@ struct path_pattern *last_matching_pattern(struct dir_struct *dir,
 int is_excluded(struct dir_struct *dir, struct index_state *istate,
 		const char *pathname, int *dtype_p)
 {
-	struct path_pattern *pattern =
-		last_matching_pattern(dir, istate, pathname, dtype_p);
+	struct path_pattern *pattern;
+
+	if (core_virtualfilesystem) {
+		/*
+		* The virtual file system data is used to prevent git from traversing
+		* any part of the tree that is not in the virtual file system.  Return
+		* 1 to exclude the entry if it is not found in the virtual file system,
+		* else fall through to the regular excludes logic as it may further exclude.
+		*/
+		if (*dtype_p == DT_UNKNOWN)
+			*dtype_p = resolve_dtype(DT_UNKNOWN, istate, pathname, strlen(pathname));
+		if (is_excluded_from_virtualfilesystem(pathname, strlen(pathname), *dtype_p) > 0)
+			return 1;
+	}
+
+	pattern = last_matching_pattern(dir, istate, pathname, dtype_p);
 	if (pattern)
 		return pattern->flags & PATTERN_FLAG_NEGATIVE ? 0 : 1;
 	return 0;
@@ -2461,6 +2489,8 @@ static enum path_treatment treat_path(struct dir_struct *dir,
 						ignore_case);
 	if (dtype != DT_DIR && has_path_in_index)
 		return path_none;
+	if (is_excluded_from_virtualfilesystem(path->buf, path->len, dtype) > 0)
+		return path_excluded;
 
 	/*
 	 * When we are looking at a directory P in the working tree,
@@ -2665,6 +2695,8 @@ static void add_path_to_appropriate_result_list(struct dir_struct *dir,
 	/* add the path to the appropriate result list */
 	switch (state) {
 	case path_excluded:
+		if (is_excluded_from_virtualfilesystem(path->buf, path->len, DT_DIR) > 0)
+			break;
 		if (dir->flags & DIR_SHOW_IGNORED)
 			dir_add_name(dir, istate, path->buf, path->len);
 		else if ((dir->flags & DIR_SHOW_IGNORED_TOO) ||
diff --git a/environment.c b/environment.c
@@ -78,6 +78,7 @@ int grafts_keep_true_parents;
 int core_apply_sparse_checkout;
 int core_sparse_checkout_cone;
 int sparse_expect_files_outside_of_patterns;
+char *core_virtualfilesystem;
 int merge_log_config = -1;
 int precomposed_unicode = -1; /* see probe_utf8_pathname_composition() */
 unsigned long pack_size_limit_cfg;
@@ -545,7 +546,11 @@ int git_default_core_config(const char *var, const char *value,
 	}
 
 	if (!strcmp(var, "core.sparsecheckout")) {
-		core_apply_sparse_checkout = git_config_bool(var, value);
+		/* virtual file system relies on the sparse checkout logic so force it on */
+		if (core_virtualfilesystem)
+			core_apply_sparse_checkout = 1;
+		else
+			core_apply_sparse_checkout = git_config_bool(var, value);
 		return 0;
 	}
 
diff --git a/environment.h b/environment.h
@@ -160,6 +160,7 @@ extern int pack_compression_level;
 extern unsigned long pack_size_limit_cfg;
 extern int max_allowed_tree_depth;
 
+extern char *core_virtualfilesystem;
 extern int precomposed_unicode;
 extern int protect_hfs;
 extern int protect_ntfs;
diff --git a/meson.build b/meson.build
@@ -526,6 +526,7 @@ libgit_sources = [
   'varint.c',
   'version.c',
   'versioncmp.c',
+  'virtualfilesystem.c',
   'walker.c',
   'wildmatch.c',
   'worktree.c',
diff --git a/read-cache.c b/read-cache.c
@@ -9,6 +9,7 @@
 
 #include "git-compat-util.h"
 #include "bulk-checkin.h"
+#include "virtualfilesystem.h"
 #include "config.h"
 #include "date.h"
 #include "diff.h"
@@ -1953,6 +1954,7 @@ static void post_read_index_from(struct index_state *istate)
 	tweak_untracked_cache(istate);
 	tweak_split_index(istate);
 	tweak_fsmonitor(istate);
+	apply_virtualfilesystem(istate);
 }
 
 static size_t estimate_cache_size_from_compressed(unsigned int entries)
diff --git a/sparse-index.c b/sparse-index.c
@@ -270,7 +270,7 @@ static int add_path_to_index(const struct object_id *oid,
 	size_t len = base->len;
 
 	if (S_ISDIR(mode)) {
-		int dtype;
+		int dtype = DT_DIR;
 		size_t baselen = base->len;
 		if (!ctx->pl)
 			return READ_TREE_RECURSIVE;
@@ -394,7 +394,7 @@ void expand_index(struct index_state *istate, struct pattern_list *pl)
 		struct cache_entry *ce = istate->cache[i];
 		struct tree *tree;
 		struct pathspec ps;
-		int dtype;
+		int dtype = DT_UNKNOWN;
 
 		if (!S_ISSPARSEDIR(ce->ce_mode)) {
 			set_index_entry(full, full->cache_nr++, ce);
@@ -670,6 +670,7 @@ static void clear_skip_worktree_from_present_files_full(struct index_state *ista
 void clear_skip_worktree_from_present_files(struct index_state *istate)
 {
 	if (!core_apply_sparse_checkout ||
+	    core_virtualfilesystem ||
 	    sparse_expect_files_outside_of_patterns)
 		return;
 
diff --git a/t/meson.build b/t/meson.build
@@ -176,6 +176,7 @@ integration_tests = [
   't1090-sparse-checkout-scope.sh',
   't1091-sparse-checkout-builtin.sh',
   't1092-sparse-checkout-compatibility.sh',
+  't1093-virtualfilesystem.sh',
   't1100-commit-tree-options.sh',
   't1300-config.sh',
   't1301-shared-repo.sh',
diff --git a/t/t1090-sparse-checkout-scope.sh b/t/t1090-sparse-checkout-scope.sh
@@ -107,9 +107,9 @@ test_expect_success 'in partial clone, sparse checkout only fetches needed blobs
 '
 
 test_expect_success 'checkout does not delete items outside the sparse checkout file' '
-	# The "sparse.expectfilesoutsideofpatterns" config will prevent the
+	# The "core.virtualfilesystem" config will prevent the
 	# SKIP_WORKTREE flag from being dropped on files present on-disk.
-	test_config sparse.expectfilesoutsideofpatterns true &&
+	test_config core.virtualfilesystem true &&
 
 	test_config core.gvfs 8 &&
 	git checkout -b outside &&
diff --git a/t/t1093-virtualfilesystem.sh b/t/t1093-virtualfilesystem.sh
diff --git a/unpack-trees.c b/unpack-trees.c
diff --git a/virtualfilesystem.c b/virtualfilesystem.c
diff --git a/virtualfilesystem.h b/virtualfilesystem.h
diff --git a/wt-status.c b/wt-status.c
