test_pytest_plugin(test[xfail]): Add regression test for git_repo submodule file protocol

why: Document the issue where git_repo fixture lacks set_home dependency,
causing submodule operations to fail in isolated build environments
what:
- Add test_git_repo_fixture_submodule_file_protocol with xfail marker
- Test isolates HOME to prove child processes can't find gitconfig
- References GitHub issue #509

Author: tony

tests/test_pytest_plugin.py

@@ -16,6 +16,7 @@
     import pathlib
 
     from libvcs.pytest_plugin import CreateRepoPytestFixtureFn
+    from libvcs.sync.git import GitSync
 
 
 @pytest.mark.skipif(not shutil.which("git"), reason="git is not available")
@@ -258,3 +259,54 @@ def test_gitconfig_submodule_file_protocol(
     # Verify submodule was actually added
     gitmodules = main_repo / ".gitmodules"
     assert gitmodules.exists(), "Submodule should create .gitmodules file"
+
+
+@pytest.mark.skipif(not shutil.which("git"), reason="git is not available")
+@pytest.mark.xfail(reason="git_repo fixture missing set_home dependency")
+def test_git_repo_fixture_submodule_file_protocol(
+    git_repo: GitSync,
+    create_git_remote_repo: CreateRepoPytestFixtureFn,
+    git_commit_envvars: dict[str, str],
+    user_path: pathlib.Path,
+    tmp_path: pathlib.Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Test that git_repo fixture allows file:// protocol for submodule operations.
+
+    This validates that the git_repo fixture has proper HOME setup so child
+    processes (spawned by git submodule add) can find $HOME/.gitconfig with
+    protocol.file.allow=always.
+
+    Without set_home in git_repo, this test fails with:
+        fatal: transport 'file' not allowed
+
+    See: https://github.com/vcs-python/libvcs/issues/509
+    """
+    from libvcs.pytest_plugin import git_remote_repo_single_commit_post_init
+
+    # Isolate git config: set HOME to a clean path without protocol.file.allow
+    # This simulates what happens on a fresh build system like Arch Linux packaging
+    clean_home = tmp_path / "clean_home"
+    clean_home.mkdir()
+    monkeypatch.setenv("HOME", str(clean_home))
+    monkeypatch.setenv("GIT_CONFIG_SYSTEM", os.devnull)
+    monkeypatch.delenv("GIT_CONFIG_GLOBAL", raising=False)
+
+    # Create a repo to use as submodule source (with a commit so it can be cloned)
+    submodule_source = create_git_remote_repo()
+    git_remote_repo_single_commit_post_init(
+        remote_repo_path=submodule_source,
+        env=git_commit_envvars,
+    )
+
+    # Add submodule - this spawns child git clone that needs HOME set
+    # NOTE: We do NOT use the local config workaround here
+    result = git_repo.cmd.submodules.add(
+        repository=f"file://{submodule_source}",
+        path="vendor/lib",
+    )
+
+    assert "fatal" not in result.lower(), (
+        f"git submodule add failed: {result}\n"
+        "git_repo fixture needs set_home dependency for child processes"
+    )