`git worktree` support for VFSForGit by tyrielv · Pull Request #1911 · microsoft/VFSForGit

tyrielv · 2026-03-12T15:34:24Z

`git worktree` support for VFSForGit

Motivation

VS Code Copilot Chat background agents use git worktree to create isolated working directories for code editing. On VFSForGit enlistments, git worktree is blocked by BLOCK_ON_VFS_ENABLED because the VFS layer had no support for multiple working trees. This PR enables worktree support by running an independent GVFS mount (ProjFS instance) per worktree.

Companion PR

microsoft/git: tyrielv/gvfs-worktree (1 commit, 4 files, +82 lines)

Adds GVFS_SUPPORTS_WORKTREES (1<<8) to the core.gvfs bitmask
Conditionally allows git worktree when the bit is set
Forces --no-checkout when VFS is active (GVFS handles checkout after mount)
Adds skip-clean-check marker for pre-unmount cleanliness verification
Tests in t0402-block-command-on-gvfs.sh

Design

Each worktree gets its own:

ProjFS virtualization instance rooted at the worktree directory
Named pipe (GVFS_<ROOT>_WT_<NAME>) for IPC with hooks
Index projection reading the worktree's own index file
Metadata at .git/worktrees/<name>/.gvfs/
Service registration by worktree path (independent of primary)

Worktrees share:

Object cache — same shared cache, no re-download
Hook executables — shared via core.hookspath (absolute path)
Git config — shared .git/config via git's commondir mechanism

How it works

User runs git worktree add <path> → git creates the worktree structure with --no-checkout (forced by the git-side change)
Post-command hook detects worktree add → runs git checkout -f to create the index → runs gvfs mount <path>
GVFS detects the worktree (.git file → gitdir: → .git/worktrees/<name>/) → creates worktree-specific GVFSEnlistment → starts ProjFS → files appear
All 5 hooks (read-object, post-index-changed, virtual-filesystem, pre-command, post-command) connect to the worktree's mount via the _WT_<NAME> pipe suffix
git worktree remove → pre-command hook unmounts ProjFS → git deletes the directory

Commits (review in order)

#	Commit	What to review
1	common: add worktree detection and enlistment support	`TryGetWorktreeInfo()` detection logic, `CreateForWorktree()` path mappings
2	hooks: make pipe name resolution worktree-aware	Native C++ `.git` file detection in `GetGVFSPipeName()`, pipe suffix derivation
3	mount: teach gvfs mount/unmount to handle worktrees	`MountVerb`/`UnmountVerb` worktree detection, service registration by worktree path, `InProcessMount` metadata bootstrap, index path fixes
4	hooks: auto-mount/unmount worktrees via git hooks	Pre/post-command orchestration for add/remove/move/prune, `skip-clean-check` flow, remount-on-failure recovery, `WorktreeCommandParser` arg extraction
5	tests: add worktree unit and functional tests	3 unit test classes (451 lines), functional tests (163 lines)
	The remaining commits were added to address PR feedback
6-8	Block nesting worktrees, Block worktree remove without --force if not mounted
9	hooks: fix index copy race and vfs-hook script cleanup	Atomic index copy via temp+rename, try/finally for .vfs-empty-hook cleanup
10	mount: wrap RepoMetadata init/shutdown in try/finally	Guarantee singleton cleanup during worktree metadata bootstrap
11	hooks: fix MAX_PATH overflow and simplify unmount wait	Dynamic buffers in native worktree detection, replace pipe polling with simple sleep
12	common: store enlistment root in worktree gitdir, remove path assumptions	Explicit marker file replaces GetDirectoryName chains; use WorkingDirectoryRootName constant
13	misc: restore unmount log path, API compat overload, narrow catch	Fix null gvfsEnlistmentRoot, add WaitUntilMounted backward-compat overload, specific exception types in TryGetWorktreeInfo
14	tests: fix worktree cleanup to use gvfs unmount	Replace broken Process.StartInfo matching with gvfs unmount for stuck mount cleanup
15	tests: concurrent worktree creation, commit, and removal	Parallel add/remove of two worktrees, cross-worktree commit visibility, shared object cache verification
16	Merge upstream/master	Resolve conflicts with mount lock and GitIndexPath changes
17	Address PR feedback from mjcheetham and KeithIsSleeping	Walk-up in TryGetWorktreeInfo, constants, error propagation, robust arg parsing, unmount exit code checks, whitespace revert

Testing done

✅ git worktree add — auto-mounts, files visible via ProjFS
✅ git worktree list — shows primary + worktrees
✅ git worktree move — unmounts old, mounts new
✅ git worktree remove — unmounts, cleans up
✅ git worktree prune — cleans stale entries
✅ Concurrent worktrees — two simultaneous worktrees, independent mounts
✅ Edit/commit in worktree — commit visible from primary
✅ gvfs service --unmount-all / --mount-all — worktrees survive the cycle
✅ Large repo (500k+ trees) — add/move/remove works
✅ All 616 unit tests pass
✅ Git tests (t0402) — 18/18 pass

Known limitations

If worktree remove partially succeeds (ProjFS unmounted but directory deletion fails due to locked file), the worktree is left in a degraded state. The post-command hook attempts remount only if both the directory and .git file still exist.
The added VFSForGit functional tests will not pass in the PR validation build until the corresponding git.exe changes have been released.

Add TryGetWorktreeInfo() to detect git worktrees by checking for a .git file (not directory) and reading its gitdir pointer. WorktreeInfo carries the worktree name, paths, and derived pipe suffix. Add GVFSEnlistment.CreateForWorktree() factory that constructs an enlistment with worktree-specific paths: WorkingDirectoryRoot points to the worktree, DotGitRoot uses the shared .git directory, and NamedPipeName includes a worktree-specific suffix. Add WorktreeCommandParser to extract subcommands and positional args from git worktree hook arguments. Add GVFS_SUPPORTS_WORKTREES to GitCoreGVFSFlags enum. Assisted-by: Claude Opus 4.6 Signed-off-by: Tyrie Vella <tyrielv@gmail.com>

Update GetGVFSPipeName() in common.windows.cpp to detect when running inside a git worktree. If the current directory contains a .git file (not directory), read the gitdir pointer, extract the worktree name, and append a _WT_<NAME> suffix to the pipe name. This single change makes all native hooks (read-object, post-index-changed, virtual-filesystem) connect to the correct worktree-specific GVFS mount process. Assisted-by: Claude Opus 4.6 Signed-off-by: Tyrie Vella <tyrielv@gmail.com>

MountVerb: detect worktree paths via TryGetWorktreeInfo(), create worktree-specific GVFSEnlistment, check worktree-specific pipe for already-mounted state, register worktrees by their own path (not the primary enlistment root). UnmountVerb: resolve worktree pipe name for unmount, unregister by worktree path so the primary enlistment registration is not affected. InProcessMount: bootstrap worktree metadata (.gvfs/ inside worktree gitdir), set absolute paths for core.hookspath and core.virtualfilesystem, skip hook installation for worktree mounts (hooks are shared via hookspath), set GVFS_SUPPORTS_WORKTREES bit. GitIndexProjection/FileSystemCallbacks: use worktree-specific index path instead of assuming primary .git/index. Assisted-by: Claude Opus 4.6 Signed-off-by: Tyrie Vella <tyrielv@gmail.com>

In the managed pre/post-command hooks, intercept git worktree subcommands to transparently manage GVFS mounts: add: Post-command runs 'git checkout -f' to create the index, then 'gvfs mount' to start ProjFS projection. remove: Pre-command checks for uncommitted changes while ProjFS is alive, writes skip-clean-check marker, unmounts. Post-command remounts if removal failed (dir + .git exist). move: Pre-command unmounts old path, post-command mounts new. prune: Post-command cleans stale worktree metadata. Add WorktreeCommandParser reference to GVFS.Hooks.csproj. Assisted-by: Claude Opus 4.6 Signed-off-by: Tyrie Vella <tyrielv@gmail.com>

Unit tests: WorktreeInfoTests — TryGetWorktreeInfo detection, pipe suffix WorktreeEnlistmentTests — CreateForWorktree path mappings WorktreeCommandParserTests — subcommand and arg extraction Functional tests: WorktreeTests — end-to-end add/list/remove with live GVFS mount GitBlockCommandsTests — update existing test for conditional block Assisted-by: Claude Opus 4.6 Signed-off-by: Tyrie Vella <tyrielv@gmail.com>

ProjFS cannot handle nested virtualization roots. Add a pre-command check that blocks 'git worktree add' when the target path is inside the primary enlistment's working directory. Add IsPathInsideDirectory() utility to GVFSEnlistment.Shared.cs with unit tests for path matching (case-insensitive, sibling paths allowed). Assisted-by: Claude Opus 4.6 Signed-off-by: Tyrie Vella <tyrielv@gmail.com>

Before removing a worktree, probe the named pipe to verify the GVFS mount is running. If not mounted: - Without --force: error with guidance to mount or use --force - With --force: skip unmount and let git proceed Refactor UnmountWorktree to accept a pre-resolved WorktreeInfo to avoid redundant TryGetWorktreeInfo calls. Assisted-by: Claude Opus 4.6 Signed-off-by: Tyrie Vella <tyrielv@gmail.com>

GVFS/GVFS.Common/GVFSEnlistment.Shared.cs

Normalize paths in IsPathInsideDirectory using Path.GetFullPath to prevent traversal attacks with segments like '/../'. Add GetKnownWorktreePaths to enumerate existing worktrees from the .git/worktrees directory, and block creating a worktree inside any existing worktree — not just the primary VFS working directory. Assisted-by: Claude Opus 4.6 Signed-off-by: Tyrie Vella <tyrielv@gmail.com>

KeithIsSleeping

Risk Analysis Review

Reviewed from an OS developer perspective, focusing on GVFS + worktree integration risks, ProjFS concerns, test coverage, and deployment safety.

Assumption: GVFS is only used in the OS repo, so OS-specific layout assumptions (e.g., src/ subdirectory) are acceptable.

Summary: 3 critical issues, 4 high-risk issues, several medium concerns and test gaps. See inline comments for details.

GVFS/GVFS.Hooks/Program.Worktree.cs

GVFS/GVFS.Mount/InProcessMount.cs

GVFS/GVFS.NativeHooks.Common/common.windows.cpp

GVFS/GVFS.Hooks/Program.Worktree.cs

GVFS/GVFS.Common/GVFSEnlistment.cs

GVFS/GVFS.FunctionalTests/Tests/EnlistmentPerFixture/WorktreeTests.cs

GVFS/GVFS.Common/WorktreeCommandParser.cs

GVFS/GVFS.Common/GVFSEnlistment.cs

GVFS/GVFS.Common/GVFSEnlistment.Shared.cs

Copy the primary index to a temp file first, then rename atomically into the worktree's index path. A direct File.Copy on a live index risks a torn read on large indexes. Clean up the temp file on failure. Wrap the .vfs-empty-hook script creation and deletion in try/finally so the file is always cleaned up even if git checkout crashes. Assisted-by: Claude Opus 4.6 Signed-off-by: Tyrie Vella <tyrielv@gmail.com>

Guarantee RepoMetadata.Shutdown() is called even if an unexpected exception occurs between TryInitialize and Shutdown. Without this, the process-global singleton could be left pointing at the wrong metadata directory. Assisted-by: Claude Opus 4.6 Signed-off-by: Tyrie Vella <tyrielv@gmail.com>

Replace MAX_PATH fixed buffers in GetWorktreePipeSuffix() with std::wstring/std::string to handle long worktree paths safely. Use dynamic MultiByteToWideChar sizing instead of fixed buffer. Replace the 10-iteration pipe polling loop after gvfs unmount with a simple sleep. The unmount command already blocks until the mount process exits; the sleep allows remaining ProjFS handles to close. Assisted-by: Claude Opus 4.6 Signed-off-by: Tyrie Vella <tyrielv@gmail.com>

…ions Write the primary enlistment root to a marker file in the worktree gitdir during creation (gvfs-enlistment-root). WorktreeInfo.GetEnlistmentRoot() reads this marker, falling back to the GetDirectoryName chain for worktrees created before this change. Replace all GetDirectoryName(GetDirectoryName(SharedGitDir)) chains in MountVerb, UnmountVerb, GVFSMountProcess, and GVFSEnlistment with the new GetEnlistmentRoot() method. Replace hardcoded "src" with GVFSConstants.WorkingDirectoryRootName in the nested worktree path check. Assisted-by: Claude Opus 4.6 Signed-off-by: Tyrie Vella <tyrielv@gmail.com>

Restore enlistmentRoot parameter in UnmountVerb.AcquireLock so the "Run gvfs log" message appears on lock acquisition failure. Add backward-compatible WaitUntilMounted(tracer, enlistmentRoot, unattended, out error) overload for out-of-tree callers. Narrow bare catch in TryGetWorktreeInfo to IOException and UnauthorizedAccessException to avoid swallowing unexpected errors. Assisted-by: Claude Opus 4.6 Signed-off-by: Tyrie Vella <tyrielv@gmail.com>

Process.StartInfo.Arguments is empty for externally-launched processes, so the old code that matched GVFS.Mount by arguments would never find or kill stuck mounts. Replace with gvfs unmount which uses the named pipe to cleanly shut down the mount process. Assisted-by: Claude Opus 4.6 Signed-off-by: Tyrie Vella <tyrielv@gmail.com>

Replace the single-worktree functional test with a concurrent test that creates two worktrees in parallel, verifies both have projected files and clean status, commits in both, verifies cross-visibility of commits (shared objects), and removes both in parallel. Assisted-by: Claude Opus 4.6 Signed-off-by: Tyrie Vella <tyrielv@gmail.com>

KeithIsSleeping

Approved -- see below

KeithIsSleeping

All review items have been addressed in commits 6-15:

Review Item	Status	Commit
CRITICAL: Index copy race	✅ Fixed — atomic temp+rename	`e1ec486`
CRITICAL: RepoMetadata singleton	✅ Fixed — try/finally	`0b19c7a`
CRITICAL: core.gvfs unconditional	✅ Acknowledged — bit-check is safe	noted in thread
HIGH: MAX_PATH native hooks	✅ Fixed — dynamic buffers	`137571b`
HIGH: Hardcoded "src" path	✅ Fixed — uses WorkingDirectoryRootName	`8351b71`
HIGH: Fragile enlistment root derivation	✅ Fixed — explicit marker file	`8351b71`
HIGH: Unmount timeout	✅ Fixed — simplified wait	`137571b`
MEDIUM: Service registration orphaning	Open — see thread	—
MEDIUM: No worktree limit	✅ Acknowledged	noted in thread
MEDIUM: null gvfsEnlistmentRoot	✅ Fixed	`b58d060`
MEDIUM: Shell script cleanup	✅ Fixed — try/finally	`e1ec486`
MEDIUM: WaitUntilMounted API break	✅ Fixed — compat overload	`b58d060`
MINOR: Bare catch	✅ Fixed — specific exceptions	`b58d060`
MINOR: --orphan flag	✅ N/A — my comment was incorrect, `--orphan` is a boolean flag
TEST GAP: Broken cleanup	✅ Fixed — uses gvfs unmount	`6b4e6b2`
TEST GAP: Concurrent tests	✅ Added	`321b5a4`

LGTM — all critical and high items resolved. Only the service registration orphaning item remains open as a future consideration.

…tree-2 # Conflicts: # GVFS/GVFS.Common/GVFSEnlistment.cs # GVFS/GVFS.Mount/InProcessMount.cs Assisted-by: Claude Opus 4.6 Signed-off-by: Tyrie Vella <tyrielv@gmail.com>

mjcheetham

Since this is a pretty big PR I'll be reviewing in waves to save losing unposted review comments. Follow up review rounds incoming after this one.

GVFS/GVFS.Common/GVFSEnlistment.Shared.cs

GVFS/GVFS.Common/GVFSEnlistment.cs

GVFS/GVFS.Common/GVFSEnlistment.Shared.cs

mjcheetham

Here's the rest of my review!

GVFS/GVFS.Common/WorktreeCommandParser.cs

GVFS/GVFS.Hooks/Program.Worktree.cs

mjcheetham · 2026-03-27T10:32:04Z

GVFS/GVFS.Hooks/Program.Worktree.cs

+            ProcessHelper.Run("gvfs", $"unmount \"{fullPath}\"", redirectOutput: false);
+
+            // After gvfs unmount exits, ProjFS handles may still be closing.
+            // Wait briefly to allow the OS to release all handles before git
+            // attempts to delete the worktree directory.
+            System.Threading.Thread.Sleep(200);


If unmount fails then we may wish to stop Git from continuing to try and delete the still-mounted directory?

GVFS/GVFS.Hooks/Program.Worktree.cs

GVFS/GVFS.Mount/InProcessMount.cs

GVFS/GVFS.Mount/InProcessMountVerb.cs

GVFS/GVFS/CommandLine/MountVerb.cs

Add GVFS_SUPPORTS_WORKTREES flag (1<<8) to core.gvfs bitmask. When set, allow git worktree commands to run on VFS-enabled repos instead of blocking them with BLOCK_ON_VFS_ENABLED. Force --no-checkout during worktree add when VFS is active so ProjFS can be mounted before files are projected. Support skip-clean-check marker file in worktree gitdir: if .git/worktrees/<name>/skip-clean-check exists, skip the cleanliness check during worktree remove. This allows VFSForGit's pre-command hook to unmount ProjFS after its own status check, then let git proceed without re-checking (which would fail without the virtual filesystem). The corresponding change in VFSForGit is microsoft/VFSForGit#1911 * [x] This change only applies to the virtualization hook and VFS for Git.

TryGetWorktreeInfo: - Walk up from subdirectories to find worktree root - Canonicalize directory to absolute path - Require commondir file for valid worktree (return null if missing) - Add out string error overload; callers fail or warn on IO errors - Add GitDirPrefix, CommonDirName, SkipCleanCheckName constants WorktreeCommandParser: - Handle combined short flags (e.g., -fd, -fb branch, -bfd) - Separate long/short option handling - Handle --git-pid/--exit_code as separate-value options - Document assumptions and note Mono.Options as future improvement Hooks: - Write empty marker file instead of "1" for skip-clean-check - Check unmount exit code; block git on failure unless --force - Reference PhysicalFileSystem.TryCopyToTempFileAndRename in comment Other: - Revert whitespace-only changes in InProcessMountVerb.cs - New unit tests for subdirectory detection, combined flags, baked-in values Assisted-by: Claude Opus 4.6 Signed-off-by: Tyrie Vella <tyrielv@gmail.com>

tyrielv force-pushed the tyrielv/gvfs-worktree-2 branch 2 times, most recently from 2ff5914 to ab088d8 Compare March 12, 2026 15:51

Tyrie Vella added 3 commits March 12, 2026 08:56

tyrielv force-pushed the tyrielv/gvfs-worktree-2 branch 3 times, most recently from 153f071 to 07dbad0 Compare March 12, 2026 16:12

tyrielv mentioned this pull request Mar 12, 2026

worktree: conditionally allow worktree on VFS-enabled repos microsoft/git#868

Merged

1 task

tyrielv marked this pull request as ready for review March 12, 2026 16:20

Tyrie Vella added 2 commits March 12, 2026 11:09

tyrielv force-pushed the tyrielv/gvfs-worktree-2 branch from 07dbad0 to e4314b3 Compare March 12, 2026 18:09

Tyrie Vella added 2 commits March 12, 2026 13:41

winstliu reviewed Mar 13, 2026

View reviewed changes

GVFS/GVFS.Common/GVFSEnlistment.Shared.cs Show resolved Hide resolved

KeithIsSleeping reviewed Mar 16, 2026

View reviewed changes

Tyrie Vella added 7 commits March 17, 2026 09:14

KeithIsSleeping approved these changes Mar 17, 2026

View reviewed changes

KeithIsSleeping mentioned this pull request Mar 21, 2026

Add mount lock to prevent concurrent mount race condition #1915

Merged

Merge remote-tracking branch 'upstream/master' into tyrielv/gvfs-work…

998a230

…tree-2 # Conflicts: # GVFS/GVFS.Common/GVFSEnlistment.cs # GVFS/GVFS.Mount/InProcessMount.cs Assisted-by: Claude Opus 4.6 Signed-off-by: Tyrie Vella <tyrielv@gmail.com>

mjcheetham reviewed Mar 26, 2026

View reviewed changes

mjcheetham reviewed Mar 27, 2026

View reviewed changes

tyrielv force-pushed the tyrielv/gvfs-worktree-2 branch from f42cf3d to d933fae Compare March 31, 2026 17:49

mjcheetham enabled auto-merge April 2, 2026 10:54

Conversation

tyrielv commented Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

git worktree support for VFSForGit

Motivation

Companion PR

Design

How it works

Commits (review in order)

Testing done

Known limitations

Uh oh!

Uh oh!

KeithIsSleeping left a comment

Choose a reason for hiding this comment

Risk Analysis Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

KeithIsSleeping left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

KeithIsSleeping left a comment

Choose a reason for hiding this comment

Uh oh!

mjcheetham left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mjcheetham left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mjcheetham Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

tyrielv commented Mar 12, 2026 •

edited

Loading

`git worktree` support for VFSForGit

KeithIsSleeping left a comment •

edited

Loading