VFSForGit: Instructions file for Codex

Agent instructions for VFS for Git

This file is for AI coding assistants (GitHub Copilot, Claude Code, Cursor, OpenAI Codex, Gemini CLI, Aider, etc.). It captures project-specific knowledge that isn't obvious from a fresh git clone and which routinely trips up agents. See CONTRIBUTING.md for coding standards (StyleCop rules, error handling, exception logging) — do not duplicate those here.

Repository layout

The build scripts (scripts\Build.bat and friends) put build outputs one level up from the git working tree. The Readme documents the recommended clone-into-src\ convention, which matches the layout that gvfs clone creates for end users:

# Recommended (matches Readme.md and CI):
git clone https://github.com/microsoft/VFSForGit C:\Repos\VFSForGit\src

C:\Repos\VFSForGit\
├── src\                    ← git working tree (.git, GVFS.sln, all source)
├── out\                    ← build output (gitignored — it's outside the working tree)
└── packages\               ← NuGet cache

Cloning without the src\ suffix also works — outputs just land one level above wherever you cloned. The rest of this document and the project's own scripts (CI, Readme) use the src\ form, so commands assume it. The parent directory must be writable (cloning to C:\ itself won't work because the build can't create C:\out).

All commands below run from the enlistment root (the parent of src\):

cd C:\Repos\VFSForGit         # NOT C:\Repos\VFSForGit\src

This keeps src\... and out\... paths symmetric and matches what Build.bat does internally.

Build paths

scripts\Build.bat does a full installer build with NativeAOT publish plus Inno Setup. That's ~5 minutes minimum, and AOT has no incremental support — ilc relinks every executable on every dotnet publish. Do not use Build.bat for dev-loop iteration. Pick the right path for what you're doing.